Main Page Widgets Namespaces Book

# Miscellaneous Utility Functions

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

## Functions

std::string | get_prgname ()
| Gets the name of the program.
void | set_prgname (const std::string& prgname)
| Sets the name of the program.
std::string | getenv (const std::string& variable, bool& found)
| Returns an environment variable.
std::string | getenv (const std::string& variable)
| Returns an environment variable.
std::string | get_user_name ()
| Gets the user name of the current user.
std::string | get_real_name ()
| Gets the real name of the user.
std::string | get_home_dir ()
| Gets the current user's home directory.
std::string | get_tmp_dir ()
| Gets the directory to use for temporary files.
std::string | get_current_dir ()
| Gets the current directory.
bool | 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.
std::string | 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.
std::string | path_get_basename (const std::string& filename)
| Gets the name of the file without any leading directory components.
std::string | path_get_dirname (const std::string& filename)
| Gets the directory components of a file name.
std::string | build_filename (const Glib::ArrayHandle<std::string>& elements)
| Creates a filename from a series of elements using the correct separator for filenames.
std::string | build_filename (const std::string& elem1, const std::string& elem2)
| Creates a filename from two elements separator for filenames.
std::string | 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.
std::string | 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.

## Detailed Description

Miscellaneous Utility Functions -- a selection of portable utility functions.

## Function Documentation

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

Creates a filename from two elements 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.

std::string 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.

std::string 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.

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.

std::string 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 `""`.

std::string get_current_dir | ( |  | ) |

Gets the current directory.

Returns:
  The current directory.

std::string get_home_dir | ( |  | ) |

Gets the current user's home directory.

Returns:
  The current user's home directory.

std::string get_prgname | ( |  | ) |

Gets the name of the program.

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

Returns:
  The name of the program.

std::string get_real_name | ( |  | ) |

Gets the real name of the user.

This usually comes from the user's entry in the `passwd` file.

Returns:
  The user's real name.

std::string 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.

std::string get_user_name | ( |  | ) |

Gets the user name of the current user.

Returns:
  The name of the current user.

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

Returns an environment variable.

Parameters:

  variable | The environment variable to get.

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

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

Returns an environment variable.

Parameters:

  variable | The environment variable to get.
  found | Output argument, set to `true` if the environment variable has been found, otherwise to `false`.

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

std::string 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.

std::string 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.

bool 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.

std::string 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 `""`.

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

Sets the name of the program.

Parameters:

  prgname | The name of the program.