#ifndef _GLIBMM_STRINGUTILS_H #define _GLIBMM_STRINGUTILS_H /* 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, see . */ #include namespace Glib { /** @defgroup StringUtils String Utility Functions * * This section describes a number of utility functions for creating * and manipulating strings, as well as other string-related stuff. */ /** Looks whether the string @a str begins with @a prefix. * @ingroup StringUtils * @param str A string. * @param prefix The prefix to look for. * @return true if @a str begins with @a prefix, false otherwise. */ GLIBMM_API bool str_has_prefix(const std::string& str, const std::string& prefix); /** Looks whether the string @a str ends with @a suffix. * @ingroup StringUtils * @param str A string. * @param suffix The suffix to look for. * @return true if @a str ends with @a suffix, false otherwise. */ GLIBMM_API bool str_has_suffix(const std::string& str, const std::string& suffix); namespace Ascii { /** Converts a string to a double value. * @ingroup StringUtils * This function behaves like the standard %strtod() function does in * the C locale. It does this without actually changing the current * locale, since that would not be thread-safe. * * This function is typically used when reading configuration files or other * non-user input that should be locale independent. To handle input from the * user you should normally use locale-sensitive C++ streams. * * To convert from a string to double in a locale-insensitive way, use * Glib::Ascii::dtostr(). * * @param str The string to convert to a numeric value. * @return The double value. * @throw std::overflow_error Thrown if the correct value would cause overflow. * @throw std::underflow_error Thrown if the correct value would cause underflow. */ GLIBMM_API double strtod(const std::string& str); /** Converts a string to a double value. * @ingroup StringUtils * This function behaves like the standard %strtod() function does in * the C locale. It does this without actually changing the current * locale, since that would not be thread-safe. * * This function is typically used when reading configuration files or other * non-user input that should be locale independent. To handle input from the * user you should normally use locale-sensitive C++ streams. * * To convert from a string to double in a locale-insensitive way, use * Glib::Ascii::dtostr(). * * @param str The string to convert to a numeric value. * @param start_index The index of the first character that should be used in the conversion. * @param[out] end_index The index of the character after the last character used in the conversion. * @return The double value. * @throw std::out_of_range Thrown if @a start_index is out of range. * @throw std::overflow_error Thrown if the correct value would cause overflow. * @throw std::underflow_error Thrown if the correct value would cause underflow. */ GLIBMM_API double strtod(const std::string& str, std::string::size_type& end_index, std::string::size_type start_index = 0); /** Converts a double to a string, using the @c '.' as decimal point. * @ingroup StringUtils * This functions generates enough precision that converting the string back * using Glib::Ascii::strtod() gives the same machine-number (on machines with * IEEE compatible 64bit doubles). * * @param d The double value to convert. * @return The converted string. */ GLIBMM_API std::string dtostr(double d); } // namespace Ascii /** Escapes all special characters in the string. * @ingroup StringUtils * Escapes the special characters '\\b', '\\f', '\\n', * '\\r', '\\t', '\\' and '"' in the string * @a source by inserting a '\\' before them. Additionally all characters * in the range 0x01 - 0x1F (everything below SPACE) * and in the range 0x80 - 0xFF (all non-ASCII chars) * are replaced with a '\\' followed by their octal representation. * * Glib::strcompress() does the reverse conversion. * * @param source A string to escape. * @return A copy of @a source with certain characters escaped. See above. */ GLIBMM_API std::string strescape(const std::string& source); /** Escapes all special characters in the string. * @ingroup StringUtils * Escapes the special characters '\\b', '\\f', '\\n', * '\\r', '\\t', '\\' and '"' in the string * @a source by inserting a '\\' before them. Additionally all characters * in the range 0x01 - 0x1F (everything below SPACE) * and in the range 0x80 - 0xFF (all non-ASCII chars) * are replaced with a '\\' followed by their octal representation. * Characters supplied in @a exceptions are not escaped. * * Glib::strcompress() does the reverse conversion. * * @param source A string to escape. * @param exceptions A string of characters not to escape in @a source. * @return A copy of @a source with certain characters escaped. See above. */ GLIBMM_API std::string strescape(const std::string& source, const std::string& exceptions); /** Replaces all escaped characters with their one byte equivalent. * @ingroup StringUtils * This function does the reverse conversion of Glib::strescape(). * * @param source A string to compress. * @return A copy of @a source with all escaped characters compressed. */ GLIBMM_API std::string strcompress(const std::string& source); /** Returns a string corresponding to the given error code, e.g.\ "no such process". * @ingroup StringUtils * This function is included since not all platforms support the * %strerror() function. * * @param errnum The system error number. See the standard C errno documentation. * @return A string describing the error code. If the error code is unknown, * "unknown error (\)" is returned. */ GLIBMM_API Glib::ustring strerror(int errnum); /** Returns a string describing the given signal, e.g.\ "Segmentation fault". * @ingroup StringUtils * This function is included since not all platforms support the * %strsignal() function. * * @param signum The signal number. See the signal() documentation. * @return A string describing the signal. If the signal is unknown, * "unknown signal (\)" is returned. */ GLIBMM_API Glib::ustring strsignal(int signum); } // namespace Glib #endif /* _GLIBMM_STRINGUTILS_H */