glibmm 2.56.0

Functions
Miscellaneous Utility Functions

Miscellaneous Utility Functions – a selection of portable utility functions. More...

## Functions
Glib::ustring | Glib::get_application_name ()
| Gets a human-readable name for the application, as set by Glib::set_application_name(). More...
void | Glib::set_application_name (const Glib::ustring& application_name)
| Sets a human-readable name for the application. More...
std::string | Glib::get_prgname ()
| Gets the name of the program. More...
void | Glib::set_prgname (const std::string& prgname)
| Sets the name of the program. More...
std::string | Glib::getenv (const std::string& variable, bool& found)
| Returns the value of an environment variable. More...
std::string | Glib::getenv (const std::string& variable)
| Returns the value of an environment variable. More...
bool | Glib::setenv (const std::string& variable, const std::string& value, bool overwrite=true)
| Sets an environment variable. More...
void | Glib::unsetenv (const std::string& variable)
| Removes an environment variable from the environment. More...
Glib::ArrayHandle< std::string > | Glib::listenv ()
| Gets the names of all variables set in the environment. More...
std::string | Glib::get_user_name ()
| Gets the user name of the current user. More...
std::string | Glib::get_real_name ()
| Gets the real name of the current user. More...
std::string | Glib::get_home_dir ()
| Gets the current user's home directory. More...
std::string | Glib::get_tmp_dir ()
| Gets the directory to use for temporary files. More...
std::string | Glib::get_current_dir ()
| Gets the current directory. More...
std::string | Glib::get_user_special_dir (GUserDirectory directory)
| Returns the full path of a special directory using its logical id. More...
std::string | Glib::get_user_special_dir (UserDirectory directory)
| Returns the full path of a special directory using its logical id. More...
std::string | Glib::get_user_data_dir ()
| Returns a base directory in which to access application data such as icons that is customized for a particular user. More...
std::string | Glib::get_user_config_dir ()
| Returns a base directory in which to store user-specific application configuration information such as user preferences and settings. More...
std::vector< std::string > | Glib::get_system_data_dirs ()
| Returns an ordered list of base directories in which to access system-wide application data. More...
std::vector< std::string > | Glib::get_system_config_dirs ()
| Returns an ordered list of base directories in which to access system-wide configuration information. More...
std::string | Glib::get_user_cache_dir ()
| Returns a base directory in which to store non-essential, cached data specific to particular user. More...
bool | Glib::path_is_absolute (const std::string& filename)
| Returns `true` if the given filename is an absolute file name, i.e. it contains a full path from the root directory such as `"/usr/local"` on UNIX or `"C:\\windows"` on Windows systems. More...
std::string | Glib::path_skip_root (const std::string& filename)
| Returns the remaining part of filename after the root component, i.e. after the `"/"` on UNIX or `"C:\\"` on Windows. More...
std::string | Glib::path_get_basename (const std::string& filename)
| Gets the name of the file without any leading directory components. More...
std::string | Glib::path_get_dirname (const std::string& filename)
| Gets the directory components of a file name. More...
std::string | Glib::build_filename (const Glib::ArrayHandle< std::string >& elements)
| Creates a filename from a series of elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2)
| Creates a filename from two elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3)
| Creates a filename from three elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4)
| Creates a filename from four elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4, const std::string& elem5)
| Creates a filename from five elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4, const std::string& elem5, const std::string& elem6)
| Creates a filename from six elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4, const std::string& elem5, const std::string& elem6, const std::string& elem7)
| Creates a filename from seven elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4, const std::string& elem5, const std::string& elem6, const std::string& elem7, const std::string& elem8)
| Creates a filename from eight elements using the correct separator for filenames. More...
std::string | Glib::build_filename (const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4, const std::string& elem5, const std::string& elem6, const std::string& elem7, const std::string& elem8, const std::string& elem9)
| Creates a filename from nine elements using the correct separator for filenames. More...
std::string | Glib::build_path (const std::string& separator, const Glib::ArrayHandle< std::string >& elements)
| Creates a path from a series of elements using separator as the separator between elements. More...
std::string | Glib::find_program_in_path (const std::string& program)
| Locates the first executable named program in the user's path, in the same way that `execvp()` would locate it. More...
Glib::ustring | Glib::format_size (guint64 size, FormatSizeFlags flags=FORMAT_SIZE_DEFAULT)
| Formats a size (for example the size of a file) into a human readable string. More...

## Detailed Description

Miscellaneous Utility Functions – a selection of portable utility functions.

## Function Documentation

## ◆ build_filename() [1/9]

std::string Glib::build_filename | ( | const Glib::ArrayHandle< std::string >& | elements | ) |

Creates a filename from a series of elements using the correct separator for filenames.

This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S, elements). No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elements | A container holding the elements of the path to build. Any STL compatible container type is accepted.

Returns
  The resulting path.

## ◆ build_filename() [2/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2
| ) |  |

Creates a filename from two elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.

Returns
  The resulting path.

## ◆ build_filename() [3/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3
| ) |  |

Creates a filename from three elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_filename() [4/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4
| ) |  |

Creates a filename from four elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_filename() [5/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4,
|  | const std::string & | elem5
| ) |  |

Creates a filename from five elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.
  elem5 | Fifth path element.

Returns
  The resulting path.

## ◆ build_filename() [6/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4,
|  | const std::string & | elem5,
|  | const std::string & | elem6
| ) |  |

Creates a filename from six elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.
  elem5 | Fifth path element.
  elem6 | Sixth path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_filename() [7/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4,
|  | const std::string & | elem5,
|  | const std::string & | elem6,
|  | const std::string & | elem7
| ) |  |

Creates a filename from seven elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.
  elem5 | Fifth path element.
  elem6 | Sixth path element.
  elem7 | Seventh path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_filename() [8/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4,
|  | const std::string & | elem5,
|  | const std::string & | elem6,
|  | const std::string & | elem7,
|  | const std::string & | elem8
| ) |  |

Creates a filename from eight elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.
  elem5 | Fifth path element.
  elem6 | Sixth path element.
  elem7 | Seventh path element.
  elem8 | Eighth path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_filename() [9/9]

std::string Glib::build_filename | ( | const std::string & | elem1,
|  | const std::string & | elem2,
|  | const std::string & | elem3,
|  | const std::string & | elem4,
|  | const std::string & | elem5,
|  | const std::string & | elem6,
|  | const std::string & | elem7,
|  | const std::string & | elem8,
|  | const std::string & | elem9
| ) |  |

Creates a filename from nine elements using the correct separator for filenames.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

Parameters

  elem1 | First path element.
  elem2 | Second path element.
  elem3 | Third path element.
  elem4 | Fourth path element.
  elem5 | Fifth path element.
  elem6 | Sixth path element.
  elem7 | Seventh path element.
  elem8 | Eighth path element.
  elem9 | Ninth path element.

Returns
  The resulting path.

Since glibmm 2.28:

## ◆ build_path()

std::string Glib::build_path | ( | const std::string & | separator,
|  | const Glib::ArrayHandle< std::string >& | elements
| ) |  |

Creates a path from a series of elements using separator as the separator between elements.

At the boundary between two elements, any trailing occurrences of separator in the first element, or leading occurrences of separator in the second element are removed and exactly one copy of the separator is inserted.

Empty elements are ignored.

The number of leading copies of the separator on the result is the same as the number of leading copies of the separator on the first non-empty element.

The number of trailing copies of the separator on the result is the same as the number of trailing copies of the separator on the last non-empty element. (Determination of the number of trailing copies is done without stripping leading copies, so if the separator is `"ABA"`, `"ABABA"` has 1 trailing copy.)

However, if there is only a single non-empty element, and there are no characters in that element not part of the leading or trailing separators, then the result is exactly the original value of that element.

Other than for determination of the number of leading and trailing copies of the separator, elements consisting only of copies of the separator are ignored.

Parameters

  separator | A string used to separate the elements of the path.
  elements | A container holding the elements of the path to build. Any STL compatible container type is accepted.

Returns
  The resulting path.

## ◆ find_program_in_path()

std::string Glib::find_program_in_path | ( | const std::string & | program | ) |

Locates the first executable named program in the user's path, in the same way that `execvp()` would locate it.

Returns a string with the absolute path name, or `""` if the program is not found in the path. If program is already an absolute path, returns a copy of program if program exists and is executable, and `""` otherwise.

On Windows, if program does not have a file type suffix, tries to append the suffixes in the `PATHEXT` environment variable (if that doesn't exist, the suffixes .com, .exe, and .bat) in turn, and then look for the resulting file name in the same way as CreateProcess() would. This means first in the directory where the program was loaded from, then in the current directory, then in the Windows 32-bit system directory, then in the Windows directory, and finally in the directories in the `PATH` environment variable. If the program is found, the return value contains the full name including the type suffix.

Parameters

  program | A program name.

Returns
  An absolute path, or `""`.

## ◆ format_size()

Glib::ustring Glib::format_size | ( | guint64 | size,
|  | FormatSizeFlags | flags = `FORMAT_SIZE_DEFAULT`
| ) |  |

Formats a size (for example the size of a file) into a human readable string.

Sizes are rounded to the nearest size prefix (kB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the string "3.2 MB".

The prefix units base is 1000 (i.e. 1 kB is 1000 bytes), unless the Glib::FORMAT_SIZE_IEC_UNITS flag is set.

Parameters

  size | A size in bytes.
  flags | Flags to modify the output.

Returns
  A formatted string containing a human readable file size.

Since glibmm 2.46:

## ◆ get_application_name()

Glib::ustring Glib::get_application_name | ( |  | ) |

Gets a human-readable name for the application, as set by Glib::set_application_name().

This name should be localized if possible, and is intended for display to the user. Contrast with Glib::get_prgname(), which gets a non-localized name. If Glib::set_application_name() has not been called, returns the result of Glib::get_prgname() (which may be empty if Glib::set_prgname() has also not been called).

Returns
  Human-readable application name. May return `""`.

## ◆ get_current_dir()

std::string Glib::get_current_dir | ( |  | ) |

Gets the current directory.

Returns
  The current directory.

## ◆ get_home_dir()

std::string Glib::get_home_dir | ( |  | ) |

Gets the current user's home directory.

Returns
  The current user's home directory or an empty string if not defined.

## ◆ get_prgname()

std::string Glib::get_prgname | ( |  | ) |

Gets the name of the program.

This name should not be localized, in contrast to get_application_name().

If you are using GDK or GTK+ the program name is set in `gdk_init()`, which is called by `gtk_init()` and therefore by the constructors of Gtk::Main and Gtk::Application. The program name is found by taking the last component of `argv[0]`.

Returns
  The name of the program.

## ◆ get_real_name()

std::string Glib::get_real_name | ( |  | ) |

Gets the real name of the current user.

This usually comes from the user's entry in the `passwd` file. The encoding of the returned string is subject to the same variability as noted for get_user_name(). If the real user name cannot be determined, the string "Unknown" is returned.

Returns
  The current user's real name.

## ◆ get_system_config_dirs()

std::vector<std::string> Glib::get_system_config_dirs | ( |  | ) |

Returns an ordered list of base directories in which to access system-wide configuration information.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.

Since glibmm 2.18:

## ◆ get_system_data_dirs()

std::vector<std::string> Glib::get_system_data_dirs | ( |  | ) |

Returns an ordered list of base directories in which to access system-wide application data.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.

Since glibmm 2.18:

## ◆ get_tmp_dir()

std::string Glib::get_tmp_dir | ( |  | ) |

Gets the directory to use for temporary files.

This is found from inspecting the environment variables `TMPDIR`, `TMP`, and `TEMP` in that order. If none of those are defined `"/tmp"` is returned on UNIX and `"C:\\"` on Windows.

Returns
  The directory to use for temporary files.

## ◆ get_user_cache_dir()

std::string Glib::get_user_cache_dir | ( |  | ) |

Returns a base directory in which to store non-essential, cached data specific to particular user.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Since glibmm 2.14:

## ◆ get_user_config_dir()

std::string Glib::get_user_config_dir | ( |  | ) |

Returns a base directory in which to store user-specific application configuration information such as user preferences and settings.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Since glibmm 2.14:

## ◆ get_user_data_dir()

std::string Glib::get_user_data_dir | ( |  | ) |

Returns a base directory in which to access application data such as icons that is customized for a particular user.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Since glibmm 2.14:

## ◆ get_user_name()

std::string Glib::get_user_name | ( |  | ) |

Gets the user name of the current user.

The encoding of the returned string is system-defined. On UNIX, it might be the preferred file name encoding, or something else, and there is no guarantee that it is ever consistent on a machine. On Windows, it is always UTF-8.

Returns
  The name of the current user.

## ◆ get_user_special_dir() [1/2]

std::string Glib::get_user_special_dir | ( | GUserDirectory | directory | ) |

Returns the full path of a special directory using its logical id.

On Unix this is done using the XDG special user directories. For compatibility with existing practise, G_USER_DIRECTORY_DESKTOP falls back to `$HOME/Desktop` when XDG special user directories have not been set up.

Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded.

Parameters

  directory | The logical id of special directory.

Returns
  The path to the specified special directory, or an empty string if the logical id was not found.

Since glibmm 2.14:

Deprecated:
  Use get_user_special_dir(Glib::UserDirectory directory) instead.

## ◆ get_user_special_dir() [2/2]

std::string Glib::get_user_special_dir | ( | UserDirectory | directory | ) |

Returns the full path of a special directory using its logical id.

On Unix this is done using the XDG special user directories. For compatibility with existing practise, Glib::USER_DIRECTORY_DESKTOP falls back to `$HOME/Desktop` when XDG special user directories have not been set up.

Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded.

Parameters

  directory | The logical id of special directory.

Returns
  The path to the specified special directory, or an empty string if the logical id was not found.

Since glibmm 2.46:

## ◆ getenv() [1/2]

std::string Glib::getenv | ( | const std::string & | variable,
|  | bool & | found
| ) |  |

Returns the value of an environment variable.

The name and value are in the GLib file name encoding. On Unix, this means the actual bytes which might or might not be in some consistent character set and encoding. On Windows, it is in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded.

Parameters

  | variable | The environment variable to get.
  [out] | found | Whether the environment variable has been found.

Returns
  The value of the environment variable, or `""` if not found.

## ◆ getenv() [2/2]

std::string Glib::getenv | ( | const std::string & | variable | ) |

Returns the value of an environment variable.

The name and value are in the GLib file name encoding. On Unix, this means the actual bytes which might or might not be in some consistent character set and encoding. On Windows, it is in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded.

Parameters

  variable | The environment variable to get.

Returns
  The value of the environment variable, or `""` if not found.

## ◆ listenv()

Glib::ArrayHandle<std::string> Glib::listenv | ( |  | ) |

Gets the names of all variables set in the environment.

Programs that want to be portable to Windows should typically use this function and getenv() instead of using the environ array from the C library directly. On Windows, the strings in the environ array are in system codepage encoding, while in most of the typical use cases for environment variables in GLib-using programs you want the UTF-8 encoding that this function and getenv() provide.

Returns
  Array of environment names (The generic ArrayHandle will be implicitly converted to any STL compatible container type).

## ◆ path_get_basename()

std::string Glib::path_get_basename | ( | const std::string & | filename | ) |

Gets the name of the file without any leading directory components.

Parameters

  filename | The name of the file.

Returns
  The name of the file without any leading directory components.

## ◆ path_get_dirname()

std::string Glib::path_get_dirname | ( | const std::string & | filename | ) |

Gets the directory components of a file name.

If the file name has no directory components `"."` is returned.

Parameters

  filename | The name of the file.

Returns
  The directory components of the file.

## ◆ path_is_absolute()

bool Glib::path_is_absolute | ( | const std::string & | filename | ) |

Returns `true` if the given filename is an absolute file name, i.e. it contains a full path from the root directory such as `"/usr/local"` on UNIX or `"C:\\windows"` on Windows systems.

Parameters

  filename | A file name.

Returns
  Whether filename is an absolute path.

## ◆ path_skip_root()

std::string Glib::path_skip_root | ( | const std::string & | filename | ) |

Returns the remaining part of filename after the root component, i.e. after the `"/"` on UNIX or `"C:\\"` on Windows.

If filename is not an absolute path, `""` will be returned.

Parameters

  filename | A file name.

Returns
  The file name without the root component, or `""`.

## ◆ set_application_name()

void Glib::set_application_name | ( | const Glib::ustring& | application_name | ) |

Sets a human-readable name for the application.

This name should be localized if possible, and is intended for display to the user. Contrast with Glib::set_prgname(), which sets a non-localized name. Glib::set_prgname() will be called automatically by `gtk_init()`, but Glib::set_application_name() will not.

Note that for thread safety reasons, this function can only be called once.

The application name will be used in contexts such as error messages, or when displaying an application's name in the task list.

Parameters

  application_name | Localized name of the application.

## ◆ set_prgname()

void Glib::set_prgname | ( | const std::string & | prgname | ) |

Sets the name of the program.

Parameters

  prgname | The name of the program.

## ◆ setenv()

bool Glib::setenv | ( | const std::string & | variable,
|  | const std::string & | value,
|  | bool | overwrite = `true`
| ) |  |

Sets an environment variable.

Both the variable's name and value should be in the GLib file name encoding. On Unix, this means that they can be any sequence of bytes. On Windows, they should be in UTF-8.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed.

Parameters

  variable | The environment variable to set. It must not contain '='.
  value | The value to which the variable should be set.
  overwrite | Whether to change the variable if it already exists.

Returns
  false if the environment variable couldn't be set.

## ◆ unsetenv()

void Glib::unsetenv | ( | const std::string & | variable | ) |

Removes an environment variable from the environment.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. Furthermore, this function can't be guaranteed to operate in a threadsafe way.

Parameters

  variable | the environment variable to remove. It must not contain '='.