/* Copyright (C) 2002 The gtkmm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ _DEFS(glibmm,glib) #include #include namespace Glib { _WRAP_ENUM(UserDirectory, GUserDirectory, NO_GTYPE) _WRAP_ENUM(FormatSizeFlags, GFormatSizeFlags, NO_GTYPE) /** @defgroup MiscUtils Miscellaneous Utility Functions * Miscellaneous Utility Functions -- a selection of portable utility functions. * @{ */ /** 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). * * @return Human-readable application name. May return "". */ Glib::ustring get_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. * * @param application_name Localized name of the application. */ void set_application_name(const Glib::ustring& application_name); /** 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]. * @return The name of the program. */ std::string get_prgname(); /** Sets the name of the program. * @param prgname The name of the program. */ void set_prgname(const std::string& prgname); /** 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. * * @param variable The environment variable to get. * @param[out] found Whether the environment variable has been found. * @return The value of the environment variable, or "" if not found. */ std::string 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. * * @param variable The environment variable to get. * @return The value of the environment variable, or "" if not found. */ std::string getenv(const std::string& variable); /** 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. * * @param variable The environment variable to set. It must not contain '='. * @param value The value to which the variable should be set. * @param overwrite Whether to change the variable if it already exists. * @result false if the environment variable couldn't be set. */ bool setenv(const std::string& variable, const std::string& value, bool overwrite = true); /** 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. * * @param variable: the environment variable to remove. It must not contain '='. **/ void unsetenv(const std::string& variable); /** 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. * * @return Array of environment names (The generic ArrayHandle will be * implicitly converted to any STL compatible container type). */ Glib::ArrayHandle listenv(); /** Gets the user name of the current user. * @return The name of the current user. */ std::string get_user_name(); /** Gets the real name of the user. * This usually comes from the user's entry in the passwd file. * @return The user's real name. */ std::string get_real_name(); /** Gets the current user's home directory. * @return The current user's home directory or an empty string if not defined. */ std::string get_home_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. * @return The directory to use for temporary files. */ std::string get_tmp_dir(); /** Gets the current directory. * @return The current directory. */ std::string get_current_dir(); #ifndef GLIBMM_DISABLE_DEPRECATED /** 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. * * @param directory The logical id of special directory. * @return The path to the specified special directory, or an empty string * if the logical id was not found. * * @newin{2,14} * @deprecated Use get_user_special_dir(Glib::UserDirectory directory) instead. */ std::string get_user_special_dir(GUserDirectory directory); #endif // GLIBMM_DISABLE_DEPRECATED /** 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. * * @param directory The logical id of special directory. * @return The path to the specified special directory, or an empty string * if the logical id was not found. * * @newin{2,46} */ std::string get_user_special_dir(UserDirectory directory); /** 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 * * @newin{2,14} */ std::string get_user_data_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 * * @newin{2,14} */ std::string get_user_config_dir(); /** 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. * * @newin{2,18} */ std::vector get_system_data_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. * * @newin{2,18} */ std::vector get_system_config_dirs(); /** 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 * * @newin{2,14} */ std::string get_user_cache_dir(); /** Returns @c true if the given @a 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. * @param filename A file name. * @return Whether @a filename is an absolute path. */ bool path_is_absolute(const std::string& filename); /** Returns the remaining part of @a filename after the root component, * i.e.\ after the "/" on UNIX or "C:\\" on Windows. * If @a filename is not an absolute path, "" will be returned. * @param filename A file name. * @return The file name without the root component, or "". */ std::string path_skip_root(const std::string& filename); /** Gets the name of the file without any leading directory components. * @param filename The name of the file. * @return The name of the file without any leading directory components. */ std::string path_get_basename(const std::string& filename); /** Gets the directory components of a file name. * If the file name has no directory components "." is returned. * @param filename The name of the file. * @return The directory components of the file. */ std::string path_get_dirname(const std::string& filename); /** 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. * @param elements A container holding the elements of the path to build. * Any STL compatible container type is accepted. * @return The resulting path. */ std::string build_filename(const Glib::ArrayHandle& elements); /** 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. * @param elem1 First path element. * @param elem2 Second path element. * @return The resulting path. */ std::string build_filename(const std::string& elem1, const std::string& elem2); /** 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @return The resulting path. * * @newin{2,28} */ std::string build_filename(const std::string& elem1, const std::string& elem2, const std::string& elem3); /** 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @return The resulting path. * * @newin{2,28} */ std::string build_filename(const std::string& elem1, const std::string& elem2, const std::string& elem3, const std::string& elem4); /** 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @param elem5 Fifth path element. * @return The resulting path. */ std::string 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 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @param elem5 Fifth path element. * @param elem6 Sixth path element. * @return The resulting path. * * @newin{2,28} */ std::string 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 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @param elem5 Fifth path element. * @param elem6 Sixth path element. * @param elem7 Seventh path element. * @return The resulting path. * * @newin{2,28} */ std::string 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 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @param elem5 Fifth path element. * @param elem6 Sixth path element. * @param elem7 Seventh path element. * @param elem8 Eighth path element. * @return The resulting path. * * @newin{2,28} */ std::string 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 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. * @param elem1 First path element. * @param elem2 Second path element. * @param elem3 Third path element. * @param elem4 Fourth path element. * @param elem5 Fifth path element. * @param elem6 Sixth path element. * @param elem7 Seventh path element. * @param elem8 Eighth path element. * @param elem9 Ninth path element. * @return The resulting path. * * @newin{2,28} */ std::string 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 path from a series of elements using @a separator as the * separator between elements. * * At the boundary between two elements, any trailing occurrences of * @a separator in the first element, or leading occurrences of @a 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. * * @param separator A string used to separate the elements of the path. * @param elements A container holding the elements of the path to build. * Any STL compatible container type is accepted. * @return The resulting path. */ std::string build_path(const std::string& separator, const Glib::ArrayHandle& elements); /** Locates the first executable named @a 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 @a program is already an absolute path, * returns a copy of @a program if @a program exists and is executable, and * "" otherwise. * * On Windows, if @a 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. * * @param program A program name. * @return An absolute path, or "". */ std::string find_program_in_path(const std::string& program); /** 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. * * @param size A size in bytes. * @param flags Flags to modify the output. * @return A formatted string containing a human readable file size. * * @newin{2,46} */ Glib::ustring format_size(guint64 size, FormatSizeFlags flags = FORMAT_SIZE_DEFAULT); /** @} group MiscUtils */ } // namespace Glib