source: appstream-generator/build/girepo/glib/Util.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 35.7 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module glib.Util;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.Str;
26
27
28/** */
29public struct Util
30{
31        /**
32         * Behaves exactly like g_build_filename(), but takes the path elements
33         * as a string array, instead of varargs. This function is mainly
34         * meant for language bindings.
35         *
36         * Params:
37         *     args = strings containing the path elements.
38         *
39         * Return: a newly-allocated string that must be freed with g_free().
40         *
41         * Since: 2.8
42         */
43        public static string buildFilename(string[] firstElement ... )
44        {
45                return Str.toString(g_build_filenamev(Str.toStringzArray(firstElement)));
46        }
47       
48        /**
49         * Behaves exactly like g_build_path(), but takes the path elements
50         * as a string array, instead of varargs. This function is mainly
51         * meant for language bindings.
52         *
53         * Params:
54         *     separator = a string used to separator the elements of the path.
55         *     args = strings containing the path elements.
56         *
57         * Return: a newly-allocated string that must be freed with g_free().
58         *
59         * Since: 2.8
60         */
61        public static string buildPath(string separator, string[] firstElement ... )
62        {
63                return Str.toString(g_build_pathv(Str.toStringz(separator), Str.toStringzArray(firstElement)));
64        }
65
66        /**
67         */
68
69        /**
70         * Specifies a function to be called at normal program termination.
71         *
72         * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
73         * macro that maps to a call to the atexit() function in the C
74         * library. This means that in case the code that calls g_atexit(),
75         * i.e. atexit(), is in a DLL, the function will be called when the
76         * DLL is detached from the program. This typically makes more sense
77         * than that the function is called when the GLib DLL is detached,
78         * which happened earlier when g_atexit() was a function in the GLib
79         * DLL.
80         *
81         * The behaviour of atexit() in the context of dynamically loaded
82         * modules is not formally specified and varies wildly.
83         *
84         * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
85         * loaded module which is unloaded before the program terminates might
86         * well cause a crash at program exit.
87         *
88         * Some POSIX systems implement atexit() like Windows, and have each
89         * dynamically loaded module maintain an own atexit chain that is
90         * called when the module is unloaded.
91         *
92         * On other POSIX systems, before a dynamically loaded module is
93         * unloaded, the registered atexit functions (if any) residing in that
94         * module are called, regardless where the code that registered them
95         * resided. This is presumably the most robust approach.
96         *
97         * As can be seen from the above, for portability it's best to avoid
98         * calling g_atexit() (or atexit()) except in the main executable of a
99         * program.
100         *
101         * Deprecated: It is best to avoid g_atexit().
102         *
103         * Params:
104         *     func = the function to call on normal program termination.
105         */
106        public static void atexit(GVoidFunc func)
107        {
108                g_atexit(func);
109        }
110
111        /**
112         * Gets the name of the file without any leading directory
113         * components. It returns a pointer into the given file name
114         * string.
115         *
116         * Deprecated: Use g_path_get_basename() instead, but notice
117         * that g_path_get_basename() allocates new memory for the
118         * returned string, unlike this function which returns a pointer
119         * into the argument.
120         *
121         * Params:
122         *     fileName = the name of the file
123         *
124         * Returns: the name of the file without any leading
125         *     directory components
126         */
127        public static string basename(string fileName)
128        {
129                return Str.toString(g_basename(Str.toStringz(fileName)));
130        }
131
132        /**
133         * Find the position of the first bit set in @mask, searching
134         * from (but not including) @nth_bit upwards. Bits are numbered
135         * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
136         * usually). To start searching from the 0th bit, set @nth_bit to -1.
137         *
138         * Params:
139         *     mask = a #gulong containing flags
140         *     nthBit = the index of the bit to start the search from
141         *
142         * Returns: the index of the first bit set which is higher than @nth_bit, or -1
143         *     if no higher bits are set
144         */
145        public static int bitNthLsf(gulong mask, int nthBit)
146        {
147                return g_bit_nth_lsf(mask, nthBit);
148        }
149
150        /**
151         * Find the position of the first bit set in @mask, searching
152         * from (but not including) @nth_bit downwards. Bits are numbered
153         * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
154         * usually). To start searching from the last bit, set @nth_bit to
155         * -1 or GLIB_SIZEOF_LONG * 8.
156         *
157         * Params:
158         *     mask = a #gulong containing flags
159         *     nthBit = the index of the bit to start the search from
160         *
161         * Returns: the index of the first bit set which is lower than @nth_bit, or -1
162         *     if no lower bits are set
163         */
164        public static int bitNthMsf(gulong mask, int nthBit)
165        {
166                return g_bit_nth_msf(mask, nthBit);
167        }
168
169        /**
170         * Gets the number of bits used to hold @number,
171         * e.g. if @number is 4, 3 bits are needed.
172         *
173         * Params:
174         *     number = a #guint
175         *
176         * Returns: the number of bits used to hold @number
177         */
178        public static uint bitStorage(gulong number)
179        {
180                return g_bit_storage(number);
181        }
182
183        /**
184         * Returns the value of the environment variable @variable in the
185         * provided list @envp.
186         *
187         * Params:
188         *     envp = an environment
189         *         list (eg, as returned from g_get_environ()), or %NULL
190         *         for an empty environment list
191         *     variable = the environment variable to get
192         *
193         * Returns: the value of the environment variable, or %NULL if
194         *     the environment variable is not set in @envp. The returned
195         *     string is owned by @envp, and will be freed if @variable is
196         *     set or unset again.
197         *
198         * Since: 2.32
199         */
200        public static string environGetenv(string[] envp, string variable)
201        {
202                return Str.toString(g_environ_getenv(Str.toStringzArray(envp), Str.toStringz(variable)));
203        }
204
205        /**
206         * Sets the environment variable @variable in the provided list
207         * @envp to @value.
208         *
209         * Params:
210         *     envp = an
211         *         environment list that can be freed using g_strfreev() (e.g., as
212         *         returned from g_get_environ()), or %NULL for an empty
213         *         environment list
214         *     variable = the environment variable to set, must not contain '='
215         *     value = the value for to set the variable to
216         *     overwrite = whether to change the variable if it already exists
217         *
218         * Returns: the
219         *     updated environment list. Free it using g_strfreev().
220         *
221         * Since: 2.32
222         */
223        public static string[] environSetenv(string[] envp, string variable, string value, bool overwrite)
224        {
225                auto retStr = g_environ_setenv(Str.toStringzArray(envp), Str.toStringz(variable), Str.toStringz(value), overwrite);
226               
227                scope(exit) Str.freeStringArray(retStr);
228                return Str.toStringArray(retStr);
229        }
230
231        /**
232         * Removes the environment variable @variable from the provided
233         * environment @envp.
234         *
235         * Params:
236         *     envp = an environment
237         *         list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
238         *         or %NULL for an empty environment list
239         *     variable = the environment variable to remove, must not contain '='
240         *
241         * Returns: the
242         *     updated environment list. Free it using g_strfreev().
243         *
244         * Since: 2.32
245         */
246        public static string[] environUnsetenv(string[] envp, string variable)
247        {
248                auto retStr = g_environ_unsetenv(Str.toStringzArray(envp), Str.toStringz(variable));
249               
250                scope(exit) Str.freeStringArray(retStr);
251                return Str.toStringArray(retStr);
252        }
253
254        /**
255         * Locates the first executable named @program in the user's path, in the
256         * same way that execvp() would locate it. Returns an allocated string
257         * with the absolute path name, or %NULL if the program is not found in
258         * the path. If @program is already an absolute path, returns a copy of
259         * @program if @program exists and is executable, and %NULL otherwise.
260         *
261         * On Windows, if @program does not have a file type suffix, tries
262         * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
263         * the `PATHEXT` environment variable.
264         *
265         * On Windows, it looks for the file in the same way as CreateProcess()
266         * would. This means first in the directory where the executing
267         * program was loaded from, then in the current directory, then in the
268         * Windows 32-bit system directory, then in the Windows directory, and
269         * finally in the directories in the `PATH` environment variable. If
270         * the program is found, the return value contains the full name
271         * including the type suffix.
272         *
273         * Params:
274         *     program = a program name in the GLib file name encoding
275         *
276         * Returns: a newly-allocated string with the absolute path, or %NULL
277         */
278        public static string findProgramInPath(string program)
279        {
280                auto retStr = g_find_program_in_path(Str.toStringz(program));
281               
282                scope(exit) Str.freeString(retStr);
283                return Str.toString(retStr);
284        }
285
286        /**
287         * Formats a size (for example the size of a file) into a human readable
288         * string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
289         * and are displayed rounded to the nearest tenth. E.g. the file size
290         * 3292528 bytes will be converted into the string "3.2 MB".
291         *
292         * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
293         *
294         * This string should be freed with g_free() when not needed any longer.
295         *
296         * See g_format_size_full() for more options about how the size might be
297         * formatted.
298         *
299         * Params:
300         *     size = a size in bytes
301         *
302         * Returns: a newly-allocated formatted string containing a human readable
303         *     file size
304         *
305         * Since: 2.30
306         */
307        public static string formatSize(ulong size)
308        {
309                auto retStr = g_format_size(size);
310               
311                scope(exit) Str.freeString(retStr);
312                return Str.toString(retStr);
313        }
314
315        /**
316         * Formats a size (for example the size of a file) into a human
317         * readable string. Sizes are rounded to the nearest size prefix
318         * (KB, MB, GB) and are displayed rounded to the nearest tenth.
319         * E.g. the file size 3292528 bytes will be converted into the
320         * string "3.1 MB".
321         *
322         * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
323         *
324         * This string should be freed with g_free() when not needed any longer.
325         *
326         * Deprecated: This function is broken due to its use of SI
327         * suffixes to denote IEC units. Use g_format_size() instead.
328         *
329         * Params:
330         *     size = a size in bytes
331         *
332         * Returns: a newly-allocated formatted string containing a human
333         *     readable file size
334         *
335         * Since: 2.16
336         */
337        public static string formatSizeForDisplay(long size)
338        {
339                auto retStr = g_format_size_for_display(size);
340               
341                scope(exit) Str.freeString(retStr);
342                return Str.toString(retStr);
343        }
344
345        /**
346         * Formats a size.
347         *
348         * This function is similar to g_format_size() but allows for flags
349         * that modify the output. See #GFormatSizeFlags.
350         *
351         * Params:
352         *     size = a size in bytes
353         *     flags = #GFormatSizeFlags to modify the output
354         *
355         * Returns: a newly-allocated formatted string containing a human
356         *     readable file size
357         *
358         * Since: 2.30
359         */
360        public static string formatSizeFull(ulong size, GFormatSizeFlags flags)
361        {
362                auto retStr = g_format_size_full(size, flags);
363               
364                scope(exit) Str.freeString(retStr);
365                return Str.toString(retStr);
366        }
367
368        /**
369         * Gets a human-readable name for the application, as set by
370         * g_set_application_name(). This name should be localized if
371         * possible, and is intended for display to the user.  Contrast with
372         * g_get_prgname(), which gets a non-localized name. If
373         * g_set_application_name() has not been called, returns the result of
374         * g_get_prgname() (which may be %NULL if g_set_prgname() has also not
375         * been called).
376         *
377         * Returns: human-readable application name. may return %NULL
378         *
379         * Since: 2.2
380         */
381        public static string getApplicationName()
382        {
383                return Str.toString(g_get_application_name());
384        }
385
386        /**
387         * Gets the list of environment variables for the current process.
388         *
389         * The list is %NULL terminated and each item in the list is of the
390         * form 'NAME=VALUE'.
391         *
392         * This is equivalent to direct access to the 'environ' global variable,
393         * except portable.
394         *
395         * The return value is freshly allocated and it should be freed with
396         * g_strfreev() when it is no longer needed.
397         *
398         * Returns: the list of
399         *     environment variables
400         *
401         * Since: 2.28
402         */
403        public static string[] getEnviron()
404        {
405                auto retStr = g_get_environ();
406               
407                scope(exit) Str.freeStringArray(retStr);
408                return Str.toStringArray(retStr);
409        }
410
411        /**
412         * Gets the current directory.
413         *
414         * The returned string should be freed when no longer needed.
415         * The encoding of the returned string is system defined.
416         * On Windows, it is always UTF-8.
417         *
418         * Since GLib 2.40, this function will return the value of the "PWD"
419         * environment variable if it is set and it happens to be the same as
420         * the current directory.  This can make a difference in the case that
421         * the current directory is the target of a symbolic link.
422         *
423         * Returns: the current directory
424         */
425        public static string getCurrentDir()
426        {
427                auto retStr = g_get_current_dir();
428               
429                scope(exit) Str.freeString(retStr);
430                return Str.toString(retStr);
431        }
432
433        /**
434         * Gets the current user's home directory.
435         *
436         * As with most UNIX tools, this function will return the value of the
437         * `HOME` environment variable if it is set to an existing absolute path
438         * name, falling back to the `passwd` file in the case that it is unset.
439         *
440         * If the path given in `HOME` is non-absolute, does not exist, or is
441         * not a directory, the result is undefined.
442         *
443         * Before version 2.36 this function would ignore the `HOME` environment
444         * variable, taking the value from the `passwd` database instead. This was
445         * changed to increase the compatibility of GLib with other programs (and
446         * the XDG basedir specification) and to increase testability of programs
447         * based on GLib (by making it easier to run them from test frameworks).
448         *
449         * If your program has a strong requirement for either the new or the
450         * old behaviour (and if you don't wish to increase your GLib
451         * dependency to ensure that the new behaviour is in effect) then you
452         * should either directly check the `HOME` environment variable yourself
453         * or unset it before calling any functions in GLib.
454         *
455         * Returns: the current user's home directory
456         */
457        public static string getHomeDir()
458        {
459                return Str.toString(g_get_home_dir());
460        }
461
462        /**
463         * Return a name for the machine.
464         *
465         * The returned name is not necessarily a fully-qualified domain name,
466         * or even present in DNS or some other name service at all. It need
467         * not even be unique on your local network or site, but usually it
468         * is. Callers should not rely on the return value having any specific
469         * properties like uniqueness for security purposes. Even if the name
470         * of the machine is changed while an application is running, the
471         * return value from this function does not change. The returned
472         * string is owned by GLib and should not be modified or freed. If no
473         * name can be determined, a default fixed string "localhost" is
474         * returned.
475         *
476         * Returns: the host name of the machine.
477         *
478         * Since: 2.8
479         */
480        public static string getHostName()
481        {
482                return Str.toString(g_get_host_name());
483        }
484
485        /**
486         * Gets the name of the program. This name should not be localized,
487         * in contrast to g_get_application_name().
488         *
489         * If you are using GDK or GTK+ the program name is set in gdk_init(),
490         * which is called by gtk_init(). The program name is found by taking
491         * the last component of @argv[0].
492         *
493         * Returns: the name of the program. The returned string belongs
494         *     to GLib and must not be modified or freed.
495         */
496        public static string getPrgname()
497        {
498                return Str.toString(g_get_prgname());
499        }
500
501        /**
502         * Gets the real name of the user. This usually comes from the user's
503         * entry in the `passwd` file. The encoding of the returned string is
504         * system-defined. (On Windows, it is, however, always UTF-8.) If the
505         * real user name cannot be determined, the string "Unknown" is
506         * returned.
507         *
508         * Returns: the user's real name.
509         */
510        public static string getRealName()
511        {
512                return Str.toString(g_get_real_name());
513        }
514
515        /**
516         * Returns an ordered list of base directories in which to access
517         * system-wide configuration information.
518         *
519         * On UNIX platforms this is determined using the mechanisms described
520         * in the
521         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
522         * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
523         *
524         * On Windows is the directory that contains application data for all users.
525         * A typical path is C:\Documents and Settings\All Users\Application Data.
526         * This folder is used for application data that is not user specific.
527         * For example, an application can store a spell-check dictionary, a database
528         * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
529         * This information will not roam and is available to anyone using the computer.
530         *
531         * Returns: a %NULL-terminated array of strings owned by GLib that must
532         *     not be modified or freed.
533         *
534         * Since: 2.6
535         */
536        public static string[] getSystemConfigDirs()
537        {
538                return Str.toStringArray(g_get_system_config_dirs());
539        }
540
541        /**
542         * Returns an ordered list of base directories in which to access
543         * system-wide application data.
544         *
545         * On UNIX platforms this is determined using the mechanisms described
546         * in the
547         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
548         * In this case the list of directories retrieved will be XDG_DATA_DIRS.
549         *
550         * On Windows the first elements in the list are the Application Data
551         * and Documents folders for All Users. (These can be determined only
552         * on Windows 2000 or later and are not present in the list on other
553         * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
554         * CSIDL_COMMON_DOCUMENTS.
555         *
556         * Then follows the "share" subfolder in the installation folder for
557         * the package containing the DLL that calls this function, if it can
558         * be determined.
559         *
560         * Finally the list contains the "share" subfolder in the installation
561         * folder for GLib, and in the installation folder for the package the
562         * application's .exe file belongs to.
563         *
564         * The installation folders above are determined by looking up the
565         * folder where the module (DLL or EXE) in question is located. If the
566         * folder's name is "bin", its parent is used, otherwise the folder
567         * itself.
568         *
569         * Note that on Windows the returned list can vary depending on where
570         * this function is called.
571         *
572         * Returns: a %NULL-terminated array of strings owned by GLib that must
573         *     not be modified or freed.
574         *
575         * Since: 2.6
576         */
577        public static string[] getSystemDataDirs()
578        {
579                return Str.toStringArray(g_get_system_data_dirs());
580        }
581
582        /**
583         * Gets the directory to use for temporary files.
584         *
585         * On UNIX, this is taken from the `TMPDIR` environment variable.
586         * If the variable is not set, `P_tmpdir` is
587         * used, as defined by the system C library. Failing that, a
588         * hard-coded default of "/tmp" is returned.
589         *
590         * On Windows, the `TEMP` environment variable is used, with the
591         * root directory of the Windows installation (eg: "C:\") used
592         * as a default.
593         *
594         * The encoding of the returned string is system-defined. On Windows,
595         * it is always UTF-8. The return value is never %NULL or the empty
596         * string.
597         *
598         * Returns: the directory to use for temporary files.
599         */
600        public static string getTmpDir()
601        {
602                return Str.toString(g_get_tmp_dir());
603        }
604
605        /**
606         * Returns a base directory in which to store non-essential, cached
607         * data specific to particular user.
608         *
609         * On UNIX platforms this is determined using the mechanisms described
610         * in the
611         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
612         * In this case the directory retrieved will be XDG_CACHE_HOME.
613         *
614         * On Windows is the directory that serves as a common repository for
615         * temporary Internet files. A typical path is
616         * C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
617         * See documentation for CSIDL_INTERNET_CACHE.
618         *
619         * Returns: a string owned by GLib that must not be modified
620         *     or freed.
621         *
622         * Since: 2.6
623         */
624        public static string getUserCacheDir()
625        {
626                return Str.toString(g_get_user_cache_dir());
627        }
628
629        /**
630         * Returns a base directory in which to store user-specific application
631         * configuration information such as user preferences and settings.
632         *
633         * On UNIX platforms this is determined using the mechanisms described
634         * in the
635         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
636         * In this case the directory retrieved will be `XDG_CONFIG_HOME`.
637         *
638         * On Windows this is the folder to use for local (as opposed to
639         * roaming) application data. See documentation for
640         * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
641         * what g_get_user_data_dir() returns.
642         *
643         * Returns: a string owned by GLib that must not be modified
644         *     or freed.
645         *
646         * Since: 2.6
647         */
648        public static string getUserConfigDir()
649        {
650                return Str.toString(g_get_user_config_dir());
651        }
652
653        /**
654         * Returns a base directory in which to access application data such
655         * as icons that is customized for a particular user.
656         *
657         * On UNIX platforms this is determined using the mechanisms described
658         * in the
659         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
660         * In this case the directory retrieved will be `XDG_DATA_HOME`.
661         *
662         * On Windows this is the folder to use for local (as opposed to
663         * roaming) application data. See documentation for
664         * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
665         * what g_get_user_config_dir() returns.
666         *
667         * Returns: a string owned by GLib that must not be modified
668         *     or freed.
669         *
670         * Since: 2.6
671         */
672        public static string getUserDataDir()
673        {
674                return Str.toString(g_get_user_data_dir());
675        }
676
677        /**
678         * Gets the user name of the current user. The encoding of the returned
679         * string is system-defined. On UNIX, it might be the preferred file name
680         * encoding, or something else, and there is no guarantee that it is even
681         * consistent on a machine. On Windows, it is always UTF-8.
682         *
683         * Returns: the user name of the current user.
684         */
685        public static string getUserName()
686        {
687                return Str.toString(g_get_user_name());
688        }
689
690        /**
691         * Returns a directory that is unique to the current user on the local
692         * system.
693         *
694         * On UNIX platforms this is determined using the mechanisms described
695         * in the
696         * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
697         * This is the directory
698         * specified in the `XDG_RUNTIME_DIR` environment variable.
699         * In the case that this variable is not set, GLib will issue a warning
700         * message to stderr and return the value of g_get_user_cache_dir().
701         *
702         * On Windows this is the folder to use for local (as opposed to
703         * roaming) application data. See documentation for
704         * CSIDL_LOCAL_APPDATA.  Note that on Windows it thus is the same as
705         * what g_get_user_config_dir() returns.
706         *
707         * Returns: a string owned by GLib that must not be modified or freed.
708         *
709         * Since: 2.28
710         */
711        public static string getUserRuntimeDir()
712        {
713                return Str.toString(g_get_user_runtime_dir());
714        }
715
716        /**
717         * Returns the full path of a special directory using its logical id.
718         *
719         * On UNIX this is done using the XDG special user directories.
720         * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
721         * falls back to `$HOME/Desktop` when XDG special user directories have
722         * not been set up.
723         *
724         * Depending on the platform, the user might be able to change the path
725         * of the special directory without requiring the session to restart; GLib
726         * will not reflect any change once the special directories are loaded.
727         *
728         * Params:
729         *     directory = the logical id of special directory
730         *
731         * Returns: the path to the specified special directory, or %NULL
732         *     if the logical id was not found. The returned string is owned by
733         *     GLib and should not be modified or freed.
734         *
735         * Since: 2.14
736         */
737        public static string getUserSpecialDir(GUserDirectory directory)
738        {
739                return Str.toString(g_get_user_special_dir(directory));
740        }
741
742        /**
743         * Returns the value of an environment variable.
744         *
745         * On UNIX, the name and value are byte strings which might or might not
746         * be in some consistent character set and encoding. On Windows, they are
747         * in UTF-8.
748         * On Windows, in case the environment variable's value contains
749         * references to other environment variables, they are expanded.
750         *
751         * Params:
752         *     variable = the environment variable to get
753         *
754         * Returns: the value of the environment variable, or %NULL if
755         *     the environment variable is not found. The returned string
756         *     may be overwritten by the next call to g_getenv(), g_setenv()
757         *     or g_unsetenv().
758         */
759        public static string getenv(string variable)
760        {
761                return Str.toString(g_getenv(Str.toStringz(variable)));
762        }
763
764        /**
765         * Gets the names of all variables set in the environment.
766         *
767         * Programs that want to be portable to Windows should typically use
768         * this function and g_getenv() instead of using the environ array
769         * from the C library directly. On Windows, the strings in the environ
770         * array are in system codepage encoding, while in most of the typical
771         * use cases for environment variables in GLib-using programs you want
772         * the UTF-8 encoding that this function and g_getenv() provide.
773         *
774         * Returns: a %NULL-terminated
775         *     list of strings which must be freed with g_strfreev().
776         *
777         * Since: 2.8
778         */
779        public static string[] listenv()
780        {
781                auto retStr = g_listenv();
782               
783                scope(exit) Str.freeStringArray(retStr);
784                return Str.toStringArray(retStr);
785        }
786
787        /**
788         * Set the pointer at the specified location to %NULL.
789         *
790         * Params:
791         *     nullifyLocation = the memory address of the pointer.
792         */
793        public static void nullifyPointer(void** nullifyLocation)
794        {
795                g_nullify_pointer(nullifyLocation);
796        }
797
798        /**
799         * Parses a string containing debugging options
800         * into a %guint containing bit flags. This is used
801         * within GDK and GTK+ to parse the debug options passed on the
802         * command line or through environment variables.
803         *
804         * If @string is equal to "all", all flags are set. Any flags
805         * specified along with "all" in @string are inverted; thus,
806         * "all,foo,bar" or "foo,bar,all" sets all flags except those
807         * corresponding to "foo" and "bar".
808         *
809         * If @string is equal to "help", all the available keys in @keys
810         * are printed out to standard error.
811         *
812         * Params:
813         *     str = a list of debug options separated by colons, spaces, or
814         *         commas, or %NULL.
815         *     keys = pointer to an array of #GDebugKey which associate
816         *         strings with bit flags.
817         *     nkeys = the number of #GDebugKeys in the array.
818         *
819         * Returns: the combined set of bit flags.
820         */
821        public static uint parseDebugString(string str, GDebugKey[] keys)
822        {
823                return g_parse_debug_string(Str.toStringz(str), keys.ptr, cast(uint)keys.length);
824        }
825
826        /**
827         * Gets the last component of the filename.
828         *
829         * If @file_name ends with a directory separator it gets the component
830         * before the last slash. If @file_name consists only of directory
831         * separators (and on Windows, possibly a drive letter), a single
832         * separator is returned. If @file_name is empty, it gets ".".
833         *
834         * Params:
835         *     fileName = the name of the file
836         *
837         * Returns: a newly allocated string containing the last
838         *     component of the filename
839         */
840        public static string pathGetBasename(string fileName)
841        {
842                auto retStr = g_path_get_basename(Str.toStringz(fileName));
843               
844                scope(exit) Str.freeString(retStr);
845                return Str.toString(retStr);
846        }
847
848        /**
849         * Gets the directory components of a file name.
850         *
851         * If the file name has no directory components "." is returned.
852         * The returned string should be freed when no longer needed.
853         *
854         * Params:
855         *     fileName = the name of the file
856         *
857         * Returns: the directory components of the file
858         */
859        public static string pathGetDirname(string fileName)
860        {
861                auto retStr = g_path_get_dirname(Str.toStringz(fileName));
862               
863                scope(exit) Str.freeString(retStr);
864                return Str.toString(retStr);
865        }
866
867        /**
868         * Returns %TRUE if the given @file_name is an absolute file name.
869         * Note that this is a somewhat vague concept on Windows.
870         *
871         * On POSIX systems, an absolute file name is well-defined. It always
872         * starts from the single root directory. For example "/usr/local".
873         *
874         * On Windows, the concepts of current drive and drive-specific
875         * current directory introduce vagueness. This function interprets as
876         * an absolute file name one that either begins with a directory
877         * separator such as "\Users\tml" or begins with the root on a drive,
878         * for example "C:\Windows". The first case also includes UNC paths
879         * such as "\\myserver\docs\foo". In all cases, either slashes or
880         * backslashes are accepted.
881         *
882         * Note that a file name relative to the current drive root does not
883         * truly specify a file uniquely over time and across processes, as
884         * the current drive is a per-process value and can be changed.
885         *
886         * File names relative the current directory on some specific drive,
887         * such as "D:foo/bar", are not interpreted as absolute by this
888         * function, but they obviously are not relative to the normal current
889         * directory as returned by getcwd() or g_get_current_dir()
890         * either. Such paths should be avoided, or need to be handled using
891         * Windows-specific code.
892         *
893         * Params:
894         *     fileName = a file name
895         *
896         * Returns: %TRUE if @file_name is absolute
897         */
898        public static bool pathIsAbsolute(string fileName)
899        {
900                return g_path_is_absolute(Str.toStringz(fileName)) != 0;
901        }
902
903        /**
904         * Returns a pointer into @file_name after the root component,
905         * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
906         * is not an absolute path it returns %NULL.
907         *
908         * Params:
909         *     fileName = a file name
910         *
911         * Returns: a pointer into @file_name after the root component
912         */
913        public static string pathSkipRoot(string fileName)
914        {
915                return Str.toString(g_path_skip_root(Str.toStringz(fileName)));
916        }
917
918        /**
919         * This is just like the standard C qsort() function, but
920         * the comparison routine accepts a user data argument.
921         *
922         * This is guaranteed to be a stable sort since version 2.32.
923         *
924         * Params:
925         *     pbase = start of array to sort
926         *     totalElems = elements in the array
927         *     size = size of each element
928         *     compareFunc = function to compare elements
929         *     userData = data to pass to @compare_func
930         */
931        public static void qsortWithData(void* pbase, int totalElems, size_t size, GCompareDataFunc compareFunc, void* userData)
932        {
933                g_qsort_with_data(pbase, totalElems, size, compareFunc, userData);
934        }
935
936        /**
937         * Resets the cache used for g_get_user_special_dir(), so
938         * that the latest on-disk version is used. Call this only
939         * if you just changed the data on disk yourself.
940         *
941         * Due to threadsafety issues this may cause leaking of strings
942         * that were previously returned from g_get_user_special_dir()
943         * that can't be freed. We ensure to only leak the data for
944         * the directories that actually changed value though.
945         *
946         * Since: 2.22
947         */
948        public static void reloadUserSpecialDirsCache()
949        {
950                g_reload_user_special_dirs_cache();
951        }
952
953        /**
954         * Sets a human-readable name for the application. This name should be
955         * localized if possible, and is intended for display to the user.
956         * Contrast with g_set_prgname(), which sets a non-localized name.
957         * g_set_prgname() will be called automatically by gtk_init(),
958         * but g_set_application_name() will not.
959         *
960         * Note that for thread safety reasons, this function can only
961         * be called once.
962         *
963         * The application name will be used in contexts such as error messages,
964         * or when displaying an application's name in the task list.
965         *
966         * Params:
967         *     applicationName = localized name of the application
968         *
969         * Since: 2.2
970         */
971        public static void setApplicationName(string applicationName)
972        {
973                g_set_application_name(Str.toStringz(applicationName));
974        }
975
976        /**
977         * Sets the name of the program. This name should not be localized,
978         * in contrast to g_set_application_name().
979         *
980         * Note that for thread-safety reasons this function can only be called once.
981         *
982         * Params:
983         *     prgname = the name of the program.
984         */
985        public static void setPrgname(string prgname)
986        {
987                g_set_prgname(Str.toStringz(prgname));
988        }
989
990        /**
991         * Sets an environment variable. On UNIX, both the variable's name and
992         * value can be arbitrary byte strings, except that the variable's name
993         * cannot contain '='. On Windows, they should be in UTF-8.
994         *
995         * Note that on some systems, when variables are overwritten, the memory
996         * used for the previous variables and its value isn't reclaimed.
997         *
998         * You should be mindful of the fact that environment variable handling
999         * in UNIX is not thread-safe, and your program may crash if one thread
1000         * calls g_setenv() while another thread is calling getenv(). (And note
1001         * that many functions, such as gettext(), call getenv() internally.)
1002         * This function is only safe to use at the very start of your program,
1003         * before creating any other threads (or creating objects that create
1004         * worker threads of their own).
1005         *
1006         * If you need to set up the environment for a child process, you can
1007         * use g_get_environ() to get an environment array, modify that with
1008         * g_environ_setenv() and g_environ_unsetenv(), and then pass that
1009         * array directly to execvpe(), g_spawn_async(), or the like.
1010         *
1011         * Params:
1012         *     variable = the environment variable to set, must not contain '='.
1013         *     value = the value for to set the variable to.
1014         *     overwrite = whether to change the variable if it already exists.
1015         *
1016         * Returns: %FALSE if the environment variable couldn't be set.
1017         *
1018         * Since: 2.4
1019         */
1020        public static bool setenv(string variable, string value, bool overwrite)
1021        {
1022                return g_setenv(Str.toStringz(variable), Str.toStringz(value), overwrite) != 0;
1023        }
1024
1025        /**
1026         * Gets the smallest prime number from a built-in array of primes which
1027         * is larger than @num. This is used within GLib to calculate the optimum
1028         * size of a #GHashTable.
1029         *
1030         * The built-in array of primes ranges from 11 to 13845163 such that
1031         * each prime is approximately 1.5-2 times the previous prime.
1032         *
1033         * Params:
1034         *     num = a #guint
1035         *
1036         * Returns: the smallest prime number from a built-in array of primes
1037         *     which is larger than @num
1038         */
1039        public static uint spacedPrimesClosest(uint num)
1040        {
1041                return g_spaced_primes_closest(num);
1042        }
1043
1044        /**
1045         * Removes an environment variable from the environment.
1046         *
1047         * Note that on some systems, when variables are overwritten, the
1048         * memory used for the previous variables and its value isn't reclaimed.
1049         *
1050         * You should be mindful of the fact that environment variable handling
1051         * in UNIX is not thread-safe, and your program may crash if one thread
1052         * calls g_unsetenv() while another thread is calling getenv(). (And note
1053         * that many functions, such as gettext(), call getenv() internally.) This
1054         * function is only safe to use at the very start of your program, before
1055         * creating any other threads (or creating objects that create worker
1056         * threads of their own).
1057         *
1058         * If you need to set up the environment for a child process, you can
1059         * use g_get_environ() to get an environment array, modify that with
1060         * g_environ_setenv() and g_environ_unsetenv(), and then pass that
1061         * array directly to execvpe(), g_spawn_async(), or the like.
1062         *
1063         * Params:
1064         *     variable = the environment variable to remove, must not contain '='
1065         *
1066         * Since: 2.4
1067         */
1068        public static void unsetenv(string variable)
1069        {
1070                g_unsetenv(Str.toStringz(variable));
1071        }
1072}
Note: See TracBrowser for help on using the repository browser.