1 #ifndef _GLIBMM_STRINGUTILS_H 2 #define _GLIBMM_STRINGUTILS_H 3 4 /* Copyright (C) 2002 The gtkmm Development Team 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 18 */ 19 20 #include <glibmm/ustring.h> 21 22 namespace Glib 23 { 24 25 /** @defgroup StringUtils String Utility Functions 26 * 27 * This section describes a number of utility functions for creating 28 * and manipulating strings, as well as other string-related stuff. 29 */ 30 31 /** Looks whether the string @a str begins with @a prefix. 32 * @ingroup StringUtils 33 * @param str A string. 34 * @param prefix The prefix to look for. 35 * @return <tt>true</tt> if @a str begins with @a prefix, <tt>false</tt> otherwise. 36 */ 37 GLIBMM_API 38 bool str_has_prefix(const std::string& str, const std::string& prefix); 39 40 /** Looks whether the string @a str ends with @a suffix. 41 * @ingroup StringUtils 42 * @param str A string. 43 * @param suffix The suffix to look for. 44 * @return <tt>true</tt> if @a str ends with @a suffix, <tt>false</tt> otherwise. 45 */ 46 GLIBMM_API 47 bool str_has_suffix(const std::string& str, const std::string& suffix); 48 49 namespace Ascii 50 { 51 52 /** Converts a string to a <tt>double</tt> value. 53 * @ingroup StringUtils 54 * This function behaves like the standard <tt>%strtod()</tt> function does in 55 * the C locale. It does this without actually changing the current 56 * locale, since that would not be thread-safe. 57 * 58 * This function is typically used when reading configuration files or other 59 * non-user input that should be locale independent. To handle input from the 60 * user you should normally use locale-sensitive C++ streams. 61 * 62 * To convert from a string to <tt>double</tt> in a locale-insensitive way, use 63 * Glib::Ascii::dtostr(). 64 * 65 * @param str The string to convert to a numeric value. 66 * @return The <tt>double</tt> value. 67 * @throw std::overflow_error Thrown if the correct value would cause overflow. 68 * @throw std::underflow_error Thrown if the correct value would cause underflow. 69 */ 70 GLIBMM_API 71 double strtod(const std::string& str); 72 73 /** Converts a string to a <tt>double</tt> value. 74 * @ingroup StringUtils 75 * This function behaves like the standard <tt>%strtod()</tt> function does in 76 * the C locale. It does this without actually changing the current 77 * locale, since that would not be thread-safe. 78 * 79 * This function is typically used when reading configuration files or other 80 * non-user input that should be locale independent. To handle input from the 81 * user you should normally use locale-sensitive C++ streams. 82 * 83 * To convert from a string to <tt>double</tt> in a locale-insensitive way, use 84 * Glib::Ascii::dtostr(). 85 * 86 * @param str The string to convert to a numeric value. 87 * @param start_index The index of the first character that should be used in the conversion. 88 * @param[out] end_index The index of the character after the last character used in the conversion. 89 * @return The <tt>double</tt> value. 90 * @throw std::out_of_range Thrown if @a start_index is out of range. 91 * @throw std::overflow_error Thrown if the correct value would cause overflow. 92 * @throw std::underflow_error Thrown if the correct value would cause underflow. 93 */ 94 GLIBMM_API 95 double strtod(const std::string& str, std::string::size_type& end_index, 96 std::string::size_type start_index = 0); 97 98 /** Converts a <tt>double</tt> to a string, using the @c '.' as decimal point. 99 * @ingroup StringUtils 100 * This functions generates enough precision that converting the string back 101 * using Glib::Ascii::strtod() gives the same machine-number (on machines with 102 * IEEE compatible 64bit doubles). 103 * 104 * @param d The <tt>double</tt> value to convert. 105 * @return The converted string. 106 */ 107 GLIBMM_API 108 std::string dtostr(double d); 109 110 } // namespace Ascii 111 112 /** Escapes all special characters in the string. 113 * @ingroup StringUtils 114 * Escapes the special characters <tt>'\\b'</tt>, <tt>'\\f'</tt>, <tt>'\\n'</tt>, 115 * <tt>'\\r'</tt>, <tt>'\\t'</tt>, <tt>'\\'</tt> and <tt>'"'</tt> in the string 116 * @a source by inserting a <tt>'\\'</tt> before them. Additionally all characters 117 * in the range <tt>0x01</tt> - <tt>0x1F</tt> (everything below <tt>SPACE</tt>) 118 * and in the range <tt>0x80</tt> - <tt>0xFF</tt> (all non-ASCII chars) 119 * are replaced with a <tt>'\\'</tt> followed by their octal representation. 120 * 121 * Glib::strcompress() does the reverse conversion. 122 * 123 * @param source A string to escape. 124 * @return A copy of @a source with certain characters escaped. See above. 125 */ 126 GLIBMM_API 127 std::string strescape(const std::string& source); 128 129 /** Escapes all special characters in the string. 130 * @ingroup StringUtils 131 * Escapes the special characters <tt>'\\b'</tt>, <tt>'\\f'</tt>, <tt>'\\n'</tt>, 132 * <tt>'\\r'</tt>, <tt>'\\t'</tt>, <tt>'\\'</tt> and <tt>'"'</tt> in the string 133 * @a source by inserting a <tt>'\\'</tt> before them. Additionally all characters 134 * in the range <tt>0x01</tt> - <tt>0x1F</tt> (everything below <tt>SPACE</tt>) 135 * and in the range <tt>0x80</tt> - <tt>0xFF</tt> (all non-ASCII chars) 136 * are replaced with a <tt>'\\'</tt> followed by their octal representation. 137 * Characters supplied in @a exceptions are not escaped. 138 * 139 * Glib::strcompress() does the reverse conversion. 140 * 141 * @param source A string to escape. 142 * @param exceptions A string of characters not to escape in @a source. 143 * @return A copy of @a source with certain characters escaped. See above. 144 */ 145 GLIBMM_API 146 std::string strescape(const std::string& source, const std::string& exceptions); 147 148 /** Replaces all escaped characters with their one byte equivalent. 149 * @ingroup StringUtils 150 * This function does the reverse conversion of Glib::strescape(). 151 * 152 * @param source A string to compress. 153 * @return A copy of @a source with all escaped characters compressed. 154 */ 155 GLIBMM_API 156 std::string strcompress(const std::string& source); 157 158 /** Returns a string corresponding to the given error code, e.g.\ <tt>"no such process"</tt>. 159 * @ingroup StringUtils 160 * This function is included since not all platforms support the 161 * <tt>%strerror()</tt> function. 162 * 163 * @param errnum The system error number. See the standard C <tt>errno</tt> documentation. 164 * @return A string describing the error code. If the error code is unknown, 165 * <tt>"unknown error (<em>\<errnum\></em>)"</tt> is returned. 166 */ 167 GLIBMM_API 168 Glib::ustring strerror(int errnum); 169 170 /** Returns a string describing the given signal, e.g.\ <tt>"Segmentation fault"</tt>. 171 * @ingroup StringUtils 172 * This function is included since not all platforms support the 173 * <tt>%strsignal()</tt> function. 174 * 175 * @param signum The signal number. See the <tt>signal()</tt> documentation. 176 * @return A string describing the signal. If the signal is unknown, 177 * <tt>"unknown signal (<em>\<signum\></em>)"</tt> is returned. 178 */ 179 GLIBMM_API 180 Glib::ustring strsignal(int signum); 181 182 } // namespace Glib 183 184 #endif /* _GLIBMM_STRINGUTILS_H */ 185