1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY!
2 #ifndef _GLIBMM_MISCUTILS_H
3 #define _GLIBMM_MISCUTILS_H
4
5
6 /* Copyright (C) 2002 The gtkmm Development Team
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22
23 #include <glibmm/arrayhandle.h>
24 #include <glibmm/ustring.h>
25 #include <glibmm/utility.h>
26
27 namespace Glib
28 {
29 /** @addtogroup glibmmEnums glibmm Enums and Flags */
30
31 /**
32 * @var UserDirectory USER_DIRECTORY_DESKTOP
33 * The user's Desktop directory.
34 *
35 * @var UserDirectory USER_DIRECTORY_DOCUMENTS
36 * The user's Documents directory.
37 *
38 * @var UserDirectory USER_DIRECTORY_DOWNLOAD
39 * The user's Downloads directory.
40 *
41 * @var UserDirectory USER_DIRECTORY_MUSIC
42 * The user's Music directory.
43 *
44 * @var UserDirectory USER_DIRECTORY_PICTURES
45 * The user's Pictures directory.
46 *
47 * @var UserDirectory USER_DIRECTORY_PUBLIC_SHARE
48 * The user's shared directory.
49 *
50 * @var UserDirectory USER_DIRECTORY_TEMPLATES
51 * The user's Templates directory.
52 *
53 * @var UserDirectory USER_DIRECTORY_VIDEOS
54 * The user's Movies directory.
55 *
56 * @var UserDirectory USER_N_DIRECTORIES
57 * The number of enum values.
58 *
59 * @enum UserDirectory
60 *
61 * These are logical ids for special directories which are defined
62 * depending on the platform used. You should use g_get_user_special_dir()
63 * to retrieve the full path associated to the logical id.
64 *
65 * The UserDirectory enumeration can be extended at later date. Not
66 * every platform has a directory for every logical id in this
67 * enumeration.
68 *
69 * @newin{2,14}
70 *
71 * @ingroup glibmmEnums
72 */
73 enum UserDirectory
74 {
75 USER_DIRECTORY_DESKTOP,
76 USER_DIRECTORY_DOCUMENTS,
77 USER_DIRECTORY_DOWNLOAD,
78 USER_DIRECTORY_MUSIC,
79 USER_DIRECTORY_PICTURES,
80 USER_DIRECTORY_PUBLIC_SHARE,
81 USER_DIRECTORY_TEMPLATES,
82 USER_DIRECTORY_VIDEOS,
83 USER_N_DIRECTORIES
84 };
85
86
87 /**
88 * @var FormatSizeFlags FORMAT_SIZE_DEFAULT
89 * Behave the same as g_format_size().
90 *
91 * @var FormatSizeFlags FORMAT_SIZE_LONG_FORMAT
92 * Include the exact number of bytes as part
93 * of the returned string. For example, "45.6 kB (45,612 bytes)".
94 *
95 * @var FormatSizeFlags FORMAT_SIZE_IEC_UNITS
96 * Use IEC (base 1024) units with "KiB"-style
97 * suffixes. IEC units should only be used for reporting things with
98 * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
99 * Network and storage sizes should be reported in the normal SI units.
100 *
101 * @var FormatSizeFlags FORMAT_SIZE_BITS
102 * Set the size as a quantity in bits, rather than
103 * bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.
104 *
105 * @enum FormatSizeFlags
106 *
107 * Flags to modify the format of the string returned by g_format_size_full().
108 *
109 * @ingroup glibmmEnums
110 * @par Bitwise operators:
111 * <tt>%FormatSizeFlags operator|(FormatSizeFlags, FormatSizeFlags)</tt><br>
112 * <tt>%FormatSizeFlags operator&(FormatSizeFlags, FormatSizeFlags)</tt><br>
113 * <tt>%FormatSizeFlags operator^(FormatSizeFlags, FormatSizeFlags)</tt><br>
114 * <tt>%FormatSizeFlags operator~(FormatSizeFlags)</tt><br>
115 * <tt>%FormatSizeFlags& operator|=(FormatSizeFlags&, FormatSizeFlags)</tt><br>
116 * <tt>%FormatSizeFlags& operator&=(FormatSizeFlags&, FormatSizeFlags)</tt><br>
117 * <tt>%FormatSizeFlags& operator^=(FormatSizeFlags&, FormatSizeFlags)</tt><br>
118 */
119 enum FormatSizeFlags
120 {
121 FORMAT_SIZE_DEFAULT = 0x0,
122 FORMAT_SIZE_LONG_FORMAT = 1 << 0,
123 FORMAT_SIZE_IEC_UNITS = 1 << 1,
124 FORMAT_SIZE_BITS = 1 << 2
125 };
126
127 /** @ingroup glibmmEnums */
128 inline FormatSizeFlags operator|(FormatSizeFlags lhs, FormatSizeFlags rhs)
129 { return static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
130
131 /** @ingroup glibmmEnums */
132 inline FormatSizeFlags operator&(FormatSizeFlags lhs, FormatSizeFlags rhs)
133 { return static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
134
135 /** @ingroup glibmmEnums */
136 inline FormatSizeFlags operator^(FormatSizeFlags lhs, FormatSizeFlags rhs)
137 { return static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
138
139 /** @ingroup glibmmEnums */
140 inline FormatSizeFlags operator~(FormatSizeFlags flags)
141 { return static_cast<FormatSizeFlags>(~static_cast<unsigned>(flags)); }
142
143 /** @ingroup glibmmEnums */
144 inline FormatSizeFlags& operator|=(FormatSizeFlags& lhs, FormatSizeFlags rhs)
145 { return (lhs = static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
146
147 /** @ingroup glibmmEnums */
148 inline FormatSizeFlags& operator&=(FormatSizeFlags& lhs, FormatSizeFlags rhs)
149 { return (lhs = static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
150
151 /** @ingroup glibmmEnums */
152 inline FormatSizeFlags& operator^=(FormatSizeFlags& lhs, FormatSizeFlags rhs)
153 { return (lhs = static_cast<FormatSizeFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
154
155
156 /** @defgroup MiscUtils Miscellaneous Utility Functions
157 * Miscellaneous Utility Functions -- a selection of portable utility functions.
158 * @{
159 */
160
161 /** Gets a human-readable name for the application,
162 * as set by Glib::set_application_name().
163 *
164 * This name should be localized if possible, and is intended for display to
165 * the user. Contrast with Glib::get_prgname(), which gets a non-localized
166 * name. If Glib::set_application_name() has not been called, returns the
167 * result of Glib::get_prgname() (which may be empty if Glib::set_prgname()
168 * has also not been called).
169 *
170 * @return Human-readable application name. May return <tt>""</tt>.
171 */
172 GLIBMM_API
173 Glib::ustring get_application_name();
174
175 /** Sets a human-readable name for the application.
176 * This name should be localized if possible, and is intended for display to
177 * the user. Contrast with Glib::set_prgname(), which sets a non-localized
178 * name. Glib::set_prgname() will be called automatically by
179 * <tt>gtk_init()</tt>, but Glib::set_application_name() will not.
180 *
181 * Note that for thread safety reasons, this function can only be called once.
182 *
183 * The application name will be used in contexts such as error messages,
184 * or when displaying an application's name in the task list.
185 *
186 * @param application_name Localized name of the application.
187 */
188 GLIBMM_API
189 void set_application_name(const Glib::ustring& application_name);
190
191 /** Gets the name of the program.
192 *
193 * This name should not be localized, in contrast to get_application_name().
194 *
195 * If you are using GDK or GTK+ the program name is set in <tt>gdk_init()</tt>,
196 * which is called by <tt>gtk_init()</tt> and therefore by the constructors of
197 * Gtk::Main and Gtk::Application. The program name is found by taking the last
198 * component of <tt>argv[0]</tt>.
199 *
200 * @return The name of the program.
201 */
202 GLIBMM_API
203 std::string get_prgname();
204
205 /** Sets the name of the program.
206 * @param prgname The name of the program.
207 */
208 GLIBMM_API
209 void set_prgname(const std::string& prgname);
210
211 /** Returns the value of an environment variable. The name and value
212 * are in the GLib file name encoding. On Unix, this means the actual
213 * bytes which might or might not be in some consistent character set
214 * and encoding. On Windows, it is in UTF-8. On Windows, in case the
215 * environment variable's value contains references to other
216 * environment variables, they are expanded.
217 *
218 * @param variable The environment variable to get.
219 * @param[out] found Whether the environment variable has been found.
220 * @return The value of the environment variable, or <tt>""</tt> if not found.
221 */
222 GLIBMM_API
223 std::string getenv(const std::string& variable, bool& found);
224
225 /** Returns the value of an environment variable. The name and value
226 * are in the GLib file name encoding. On Unix, this means the actual
227 * bytes which might or might not be in some consistent character set
228 * and encoding. On Windows, it is in UTF-8. On Windows, in case the
229 * environment variable's value contains references to other
230 * environment variables, they are expanded.
231 *
232 * @param variable The environment variable to get.
233 * @return The value of the environment variable, or <tt>""</tt> if not found.
234 */
235 GLIBMM_API
236 std::string getenv(const std::string& variable);
237
238
239 /** Sets an environment variable. Both the variable's name and value
240 * should be in the GLib file name encoding. On Unix, this means that
241 * they can be any sequence of bytes. On Windows, they should be in
242 * UTF-8.
243 *
244 * Note that on some systems, when variables are overwritten, the memory
245 * used for the previous variables and its value isn't reclaimed.
246 *
247 * @param variable The environment variable to set. It must not contain '='.
248 * @param value The value to which the variable should be set.
249 * @param overwrite Whether to change the variable if it already exists.
250 * @result false if the environment variable couldn't be set.
251 */
252 GLIBMM_API
253 bool setenv(const std::string& variable, const std::string& value, bool overwrite = true);
254
255 /** Removes an environment variable from the environment.
256 *
257 * Note that on some systems, when variables are overwritten, the memory
258 * used for the previous variables and its value isn't reclaimed.
259 * Furthermore, this function can't be guaranteed to operate in a
260 * threadsafe way.
261 *
262 * @param variable: the environment variable to remove. It must not contain '='.
263 **/
264 GLIBMM_API
265 void unsetenv(const std::string& variable);
266
267 /** Gets the names of all variables set in the environment.
268 *
269 * Programs that want to be portable to Windows should typically use this
270 * function and getenv() instead of using the environ array from the C library
271 * directly. On Windows, the strings in the environ array are in system
272 * codepage encoding, while in most of the typical use cases for environment
273 * variables in GLib-using programs you want the UTF-8 encoding that this
274 * function and getenv() provide.
275 *
276 * @return Array of environment names (The generic ArrayHandle will be
277 * implicitly converted to any STL compatible container type).
278 */
279 GLIBMM_API
280 Glib::ArrayHandle<std::string> listenv();
281
282 /** Gets the user name of the current user.
283 *
284 * The encoding of the returned string is system-defined. On UNIX, it might be
285 * the preferred file name encoding, or something else, and there is no
286 * guarantee that it is ever consistent on a machine. On Windows, it is always
287 * UTF-8.
288 *
289 * @return The name of the current user.
290 */
291 GLIBMM_API
292 std::string get_user_name();
293
294 /** Gets the real name of the current user.
295 *
296 * This usually comes from the user's entry in the <tt>passwd</tt> file. The
297 * encoding of the returned string is subject to the same variability as noted
298 * for get_user_name(). If the real user name cannot be determined, the string
299 * "Unknown" is returned.
300 *
301 * @return The current user's real name.
302 */
303 GLIBMM_API
304 std::string get_real_name();
305
306 /** Return a name for the machine.
307 *
308 * The returned name is not necessarily a fully-qualified domain name,
309 * or even present in DNS or some other name service at all. It need
310 * not even be unique on your local network or site, but usually it
311 * is. Callers should not rely on the return value having any specific
312 * properties like uniqueness for security purposes. Even if the name
313 * of the machine is changed while an application is running, the
314 * return value from this function does not change. If no name can be
315 * determined, a default fixed string "localhost" is returned.
316 *
317 * @return The host name of the machine.
318 *
319 * @newin{2,64}
320 */
321 GLIBMM_API
322 Glib::ustring get_host_name();
323
324 /** Gets the current user's home directory.
325 * @return The current user's home directory or an empty string if not defined.
326 */
327 GLIBMM_API
328 std::string get_home_dir();
329
330 /** Gets the directory to use for temporary files.
331 * This is found from inspecting the environment variables <tt>TMPDIR</tt>,
332 * <tt>TMP</tt>, and <tt>TEMP</tt> in that order. If none of those are defined
333 * <tt>"/tmp"</tt> is returned on UNIX and <tt>"C:\\"</tt> on Windows.
334 * @return The directory to use for temporary files.
335 */
336 GLIBMM_API
337 std::string get_tmp_dir();
338
339 /** Gets the current directory.
340 * @return The current directory.
341 */
342 GLIBMM_API
343 std::string get_current_dir();
344
345 #ifndef GLIBMM_DISABLE_DEPRECATED
346 /** Returns the full path of a special directory using its logical id.
347 *
348 * On Unix this is done using the XDG special user directories.
349 * For compatibility with existing practise, G_USER_DIRECTORY_DESKTOP
350 * falls back to `$HOME/Desktop` when XDG special user directories have
351 * not been set up.
352 *
353 * Depending on the platform, the user might be able to change the path
354 * of the special directory without requiring the session to restart; GLib
355 * will not reflect any change once the special directories are loaded.
356 *
357 * @param directory The logical id of special directory.
358 * @return The path to the specified special directory, or an empty string
359 * if the logical id was not found.
360 *
361 * @newin{2,14}
362 * @deprecated Use get_user_special_dir(Glib::UserDirectory directory) instead.
363 */
364 GLIBMM_API
365 std::string get_user_special_dir(GUserDirectory directory);
366 #endif // GLIBMM_DISABLE_DEPRECATED
367
368 /** Returns the full path of a special directory using its logical id.
369 *
370 * On Unix this is done using the XDG special user directories.
371 * For compatibility with existing practise, Glib::USER_DIRECTORY_DESKTOP
372 * falls back to `$HOME/Desktop` when XDG special user directories have
373 * not been set up.
374 *
375 * Depending on the platform, the user might be able to change the path
376 * of the special directory without requiring the session to restart; GLib
377 * will not reflect any change once the special directories are loaded.
378 *
379 * @param directory The logical id of special directory.
380 * @return The path to the specified special directory, or an empty string
381 * if the logical id was not found.
382 *
383 * @newin{2,46}
384 */
385 GLIBMM_API
386 std::string get_user_special_dir(UserDirectory directory);
387
388 /** Returns a base directory in which to access application data such as icons
389 * that is customized for a particular user.
390 *
391 * On UNIX platforms this is determined using the mechanisms described in the
392 * XDG Base Directory Specification
393 *
394 * @newin{2,14}
395 */
396 GLIBMM_API
397 std::string get_user_data_dir();
398
399 /** Returns a base directory in which to store user-specific application
400 * configuration information such as user preferences and settings.
401 *
402 * On UNIX platforms this is determined using the mechanisms described in the
403 * XDG Base Directory Specification
404 *
405 * @newin{2,14}
406 */
407 GLIBMM_API
408 std::string get_user_config_dir();
409
410 /** Returns an ordered list of base directories in which to access system-wide application data.
411 * On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.
412 *
413 * @newin{2,18}
414 */
415 GLIBMM_API
416 std::vector<std::string> get_system_data_dirs();
417
418 /** Returns an ordered list of base directories in which to access system-wide configuration information.
419 * On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.
420 *
421 * @newin{2,18}
422 */
423 GLIBMM_API
424 std::vector<std::string> get_system_config_dirs();
425
426 /** Returns a base directory in which to store non-essential, cached data
427 * specific to particular user.
428 *
429 * On UNIX platforms this is determined using the mechanisms described in the
430 * XDG Base Directory Specification
431 *
432 * @newin{2,14}
433 */
434 GLIBMM_API
435 std::string get_user_cache_dir();
436
437 /** Returns a directory that is unique to the current user on the local system.
438 *
439 * This is the directory specified in the XDG_RUNTIME_DIR environment variable.
440 * In the case that this variable is not set, we return the value of
441 * Glib::get_user_cache_dir(), after verifying that it exists.
442 *
443 * @newin{2,64}
444 */
445 GLIBMM_API
446 std::string get_user_runtime_dir();
447
448 /** Returns @c true if the given @a filename is an absolute file name, i.e.\ it
449 * contains a full path from the root directory such as <tt>"/usr/local"</tt>
450 * on UNIX or <tt>"C:\\windows"</tt> on Windows systems.
451 * @param filename A file name.
452 * @return Whether @a filename is an absolute path.
453 */
454 GLIBMM_API
455 bool path_is_absolute(const std::string& filename);
456
457 /** Returns the remaining part of @a filename after the root component,
458 * i.e.\ after the <tt>"/"</tt> on UNIX or <tt>"C:\\"</tt> on Windows.
459 * If @a filename is not an absolute path, <tt>""</tt> will be returned.
460 * @param filename A file name.
461 * @return The file name without the root component, or <tt>""</tt>.
462 */
463 GLIBMM_API
464 std::string path_skip_root(const std::string& filename);
465
466 /** Gets the name of the file without any leading directory components.
467 * @param filename The name of the file.
468 * @return The name of the file without any leading directory components.
469 */
470 GLIBMM_API
471 std::string path_get_basename(const std::string& filename);
472
473 /** Gets the directory components of a file name.
474 * If the file name has no directory components <tt>"."</tt> is returned.
475 * @param filename The name of the file.
476 * @return The directory components of the file.
477 */
478 GLIBMM_API
479 std::string path_get_dirname(const std::string& filename);
480
481 /** Gets the canonical file name from @a filename.
482 *
483 * All triple slashes are turned into single slashes, and all `..` and `.`s
484 * resolved against @a relative_to.
485 *
486 * Symlinks are not followed, and the returned path is guaranteed to be absolute.
487 *
488 * If @a filename is an absolute path, @a relative_to is ignored. Otherwise,
489 * @a relative_to will be prepended to @a filename to make it absolute. @a relative_to
490 * must be an absolute path, or <tt>nullptr</tt>. If @a relative_to is <tt>nullptr</tt>,
491 * it'll fallback to get_current_dir().
492 *
493 * This function never fails, and will canonicalize file paths even if they don't exist.
494 *
495 * No file system I/O is done.
496 *
497 * @param filename The name of the file.
498 * @param relative_to The relative directory, or <tt>nullptr</tt> to use the
499 * current working directory.
500 * @return The canonical file path.
501 *
502 * @newin{2,64}
503 */
504 GLIBMM_API
505 std::string canonicalize_filename(StdStringView filename, StdStringView relative_to = nullptr);
506
507 /** Creates a filename from a series of elements using the correct
508 * separator for filenames.
509 * This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S,
510 * elements). No attempt is made to force the resulting filename to be an
511 * absolute path. If the first element is a relative path, the result will
512 * be a relative path.
513 * @param elements A container holding the elements of the path to build.
514 * Any STL compatible container type is accepted.
515 * @return The resulting path.
516 */
517 GLIBMM_API
518 std::string build_filename(const Glib::ArrayHandle<std::string>& elements);
519
520 /** Creates a filename from two or more elements using the correct separator for filenames.
521 * No attempt is made to force the resulting filename to be an absolute path.
522 * If the first element is a relative path, the result will be a relative path.
523 * @tparam String1 std::string or const char*.
524 * @tparam String2 std::string or const char*.
525 * @tparam Strings std::string or const char*.
526 * @param elem1 First path element.
527 * @param elem2 Second path element.
528 * @param strings The following path elements, if any.
529 * @return The resulting path.
530 *
531 * @newin{2,64}
532 */
533 template <typename String1, typename String2, typename... Strings>
build_filename(const String1 & elem1,const String2 & elem2,const Strings &...strings)534 std::string build_filename(const String1& elem1, const String2& elem2, const Strings&... strings)
535 {
536 return Glib::convert_return_gchar_ptr_to_stdstring(
537 g_build_filename(StdStringView(elem1).c_str(), StdStringView(elem2).c_str(),
538 StdStringView(strings).c_str()..., nullptr));
539 }
540
541 // When the templated build_filename() overload was added, the following
542 // build_filename() overloads became unnecessary.
543 //TODO: They can be removed when we can break ABI.
544
545 /** Creates a filename from two elements using the correct separator for filenames.
546 * No attempt is made to force the resulting filename to be an absolute path.
547 * If the first element is a relative path, the result will be a relative path.
548 * @param elem1 First path element.
549 * @param elem2 Second path element.
550 * @return The resulting path.
551 */
552 GLIBMM_API
553 std::string build_filename(const std::string& elem1, const std::string& elem2);
554
555 /** Creates a filename from three elements using the correct separator for filenames.
556 * No attempt is made to force the resulting filename to be an absolute path.
557 * If the first element is a relative path, the result will be a relative path.
558 * @param elem1 First path element.
559 * @param elem2 Second path element.
560 * @param elem3 Third path element.
561 * @return The resulting path.
562 *
563 * @newin{2,28}
564 */
565 GLIBMM_API
566 std::string build_filename(const std::string& elem1, const std::string& elem2,
567 const std::string& elem3);
568
569
570 /** Creates a filename from four elements using the correct separator for filenames.
571 * No attempt is made to force the resulting filename to be an absolute path.
572 * If the first element is a relative path, the result will be a relative path.
573 * @param elem1 First path element.
574 * @param elem2 Second path element.
575 * @param elem3 Third path element.
576 * @param elem4 Fourth path element.
577 * @return The resulting path.
578 *
579 * @newin{2,28}
580 */
581 GLIBMM_API
582 std::string build_filename(const std::string& elem1, const std::string& elem2,
583 const std::string& elem3, const std::string& elem4);
584
585 /** Creates a filename from five elements using the correct separator for filenames.
586 * No attempt is made to force the resulting filename to be an absolute path.
587 * If the first element is a relative path, the result will be a relative path.
588 * @param elem1 First path element.
589 * @param elem2 Second path element.
590 * @param elem3 Third path element.
591 * @param elem4 Fourth path element.
592 * @param elem5 Fifth path element.
593 * @return The resulting path.
594 */
595 GLIBMM_API
596 std::string build_filename(const std::string& elem1, const std::string& elem2,
597 const std::string& elem3, const std::string& elem4,
598 const std::string& elem5);
599
600 /** Creates a filename from six elements using the correct separator for filenames.
601 * No attempt is made to force the resulting filename to be an absolute path.
602 * If the first element is a relative path, the result will be a relative path.
603 * @param elem1 First path element.
604 * @param elem2 Second path element.
605 * @param elem3 Third path element.
606 * @param elem4 Fourth path element.
607 * @param elem5 Fifth path element.
608 * @param elem6 Sixth path element.
609 * @return The resulting path.
610 *
611 * @newin{2,28}
612 */
613 GLIBMM_API
614 std::string build_filename(const std::string& elem1, const std::string& elem2,
615 const std::string& elem3, const std::string& elem4,
616 const std::string& elem5, const std::string& elem6);
617
618 /** Creates a filename from seven elements using the correct separator for filenames.
619 * No attempt is made to force the resulting filename to be an absolute path.
620 * If the first element is a relative path, the result will be a relative path.
621 * @param elem1 First path element.
622 * @param elem2 Second path element.
623 * @param elem3 Third path element.
624 * @param elem4 Fourth path element.
625 * @param elem5 Fifth path element.
626 * @param elem6 Sixth path element.
627 * @param elem7 Seventh path element.
628 * @return The resulting path.
629 *
630 * @newin{2,28}
631 */
632 GLIBMM_API
633 std::string build_filename(const std::string& elem1, const std::string& elem2,
634 const std::string& elem3, const std::string& elem4,
635 const std::string& elem5, const std::string& elem6,
636 const std::string& elem7);
637
638 /** Creates a filename from eight elements using the correct separator for filenames.
639 * No attempt is made to force the resulting filename to be an absolute path.
640 * If the first element is a relative path, the result will be a relative path.
641 * @param elem1 First path element.
642 * @param elem2 Second path element.
643 * @param elem3 Third path element.
644 * @param elem4 Fourth path element.
645 * @param elem5 Fifth path element.
646 * @param elem6 Sixth path element.
647 * @param elem7 Seventh path element.
648 * @param elem8 Eighth path element.
649 * @return The resulting path.
650 *
651 * @newin{2,28}
652 */
653 GLIBMM_API
654 std::string build_filename(const std::string& elem1, const std::string& elem2,
655 const std::string& elem3, const std::string& elem4,
656 const std::string& elem5, const std::string& elem6,
657 const std::string& elem7, const std::string& elem8);
658
659 /** Creates a filename from nine elements using the correct separator for filenames.
660 * No attempt is made to force the resulting filename to be an absolute path.
661 * If the first element is a relative path, the result will be a relative path.
662 * @param elem1 First path element.
663 * @param elem2 Second path element.
664 * @param elem3 Third path element.
665 * @param elem4 Fourth path element.
666 * @param elem5 Fifth path element.
667 * @param elem6 Sixth path element.
668 * @param elem7 Seventh path element.
669 * @param elem8 Eighth path element.
670 * @param elem9 Ninth path element.
671 * @return The resulting path.
672 *
673 * @newin{2,28}
674 */
675 GLIBMM_API
676 std::string build_filename(const std::string& elem1, const std::string& elem2,
677 const std::string& elem3, const std::string& elem4,
678 const std::string& elem5, const std::string& elem6,
679 const std::string& elem7, const std::string& elem8,
680 const std::string& elem9);
681
682 /** Creates a path from a series of elements using @a separator as the
683 * separator between elements.
684 *
685 * At the boundary between two elements, any trailing occurrences of
686 * @a separator in the first element, or leading occurrences of @a separator
687 * in the second element are removed and exactly one copy of the separator is
688 * inserted.
689 *
690 * Empty elements are ignored.
691 *
692 * The number of leading copies of the separator on the result is
693 * the same as the number of leading copies of the separator on
694 * the first non-empty element.
695 *
696 * The number of trailing copies of the separator on the result is the same
697 * as the number of trailing copies of the separator on the last non-empty
698 * element. (Determination of the number of trailing copies is done without
699 * stripping leading copies, so if the separator is <tt>"ABA"</tt>,
700 * <tt>"ABABA"</tt> has 1 trailing copy.)
701 *
702 * However, if there is only a single non-empty element, and there
703 * are no characters in that element not part of the leading or
704 * trailing separators, then the result is exactly the original value
705 * of that element.
706 *
707 * Other than for determination of the number of leading and trailing
708 * copies of the separator, elements consisting only of copies
709 * of the separator are ignored.
710 *
711 * @param separator A string used to separate the elements of the path.
712 * @param elements A container holding the elements of the path to build.
713 * Any STL compatible container type is accepted.
714 * @return The resulting path.
715 */
716 GLIBMM_API
717 std::string build_path(const std::string& separator,
718 const Glib::ArrayHandle<std::string>& elements);
719
720 /** Locates the first executable named @a program in the user's path, in the
721 * same way that <tt>execvp()</tt> would locate it.
722 * Returns a string with the absolute path name, or <tt>""</tt> if the program
723 * is not found in the path. If @a program is already an absolute path,
724 * returns a copy of @a program if @a program exists and is executable, and
725 * <tt>""</tt> otherwise.
726 *
727 * On Windows, if @a program does not have a file type suffix, tries to append
728 * the suffixes in the <tt>PATHEXT</tt> environment variable (if that doesn't
729 * exist, the suffixes .com, .exe, and .bat) in turn, and then look for the
730 * resulting file name in the same way as CreateProcess() would. This means
731 * first in the directory where the program was loaded from, then in the
732 * current directory, then in the Windows 32-bit system directory, then in the
733 * Windows directory, and finally in the directories in the <tt>PATH</tt>
734 * environment variable. If the program is found, the return value contains
735 * the full name including the type suffix.
736 *
737 * @param program A program name.
738 * @return An absolute path, or <tt>""</tt>.
739 */
740 GLIBMM_API
741 std::string find_program_in_path(const std::string& program);
742
743 /** Formats a size (for example the size of a file) into a human readable string.
744 *
745 * Sizes are rounded to the nearest size prefix (kB, MB, GB)
746 * and are displayed rounded to the nearest tenth. E.g. the file size
747 * 3292528 bytes will be converted into the string "3.2 MB".
748 *
749 * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes), unless the
750 * Glib::FORMAT_SIZE_IEC_UNITS flag is set.
751 *
752 * @param size A size in bytes.
753 * @param flags Flags to modify the output.
754 * @return A formatted string containing a human readable file size.
755 *
756 * @newin{2,46}
757 */
758 GLIBMM_API
759 Glib::ustring format_size(guint64 size, FormatSizeFlags flags = FORMAT_SIZE_DEFAULT);
760
761 /** @} group MiscUtils */
762
763 } // namespace Glib
764
765
766 #endif /* _GLIBMM_MISCUTILS_H */
767
768