2 #ifndef _GLIBMM_STRINGUTILS_H
3 #define _GLIBMM_STRINGUTILS_H
7 /* Copyright (C) 2002 The gtkmm Development Team
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
19 * You should have received a copy of the GNU Library General Public
20 * License along with this library; if not, write to the Free
21 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 #include <glibmm/ustring.h>
30 /** @defgroup StringUtils String Utility Functions
32 * This section describes a number of utility functions for creating
33 * and manipulating strings, as well as other string-related stuff.
36 /** Looks whether the string @a str begins with @a prefix.
37 * @ingroup StringUtils
38 * @param str A string.
39 * @param prefix The prefix to look for.
40 * @return <tt>true</tt> if @a str begins with @a prefix, <tt>false</tt> otherwise.
42 bool str_has_prefix(const std::string& str, const std::string& prefix);
44 /** Looks whether the string @a str ends with @a suffix.
45 * @ingroup StringUtils
46 * @param str A string.
47 * @param suffix The suffix to look for.
48 * @return <tt>true</tt> if @a str ends with @a suffix, <tt>false</tt> otherwise.
50 bool str_has_suffix(const std::string& str, const std::string& suffix);
56 /** Converts a string to a <tt>double</tt> value.
57 * @ingroup StringUtils
58 * This function behaves like the standard <tt>%strtod()</tt> function does in
59 * the C locale. It does this without actually changing the current
60 * locale, since that would not be thread-safe.
62 * This function is typically used when reading configuration files or other
63 * non-user input that should be locale independent. To handle input from the
64 * user you should normally use locale-sensitive C++ streams.
66 * To convert from a string to <tt>double</tt> in a locale-insensitive way, use
67 * Glib::Ascii::dtostr().
69 * @param str The string to convert to a numeric value.
70 * @return The <tt>double</tt> value.
71 * @throw std::overflow_error Thrown if the correct value would cause overflow.
72 * @throw std::underflow_error Thrown if the correct value would cause underflow.
74 double strtod(const std::string& str);
76 /** Converts a string to a <tt>double</tt> value.
77 * @ingroup StringUtils
78 * This function behaves like the standard <tt>%strtod()</tt> function does in
79 * the C locale. It does this without actually changing the current
80 * locale, since that would not be thread-safe.
82 * This function is typically used when reading configuration files or other
83 * non-user input that should be locale independent. To handle input from the
84 * user you should normally use locale-sensitive C++ streams.
86 * To convert from a string to <tt>double</tt> in a locale-insensitive way, use
87 * Glib::Ascii::dtostr().
89 * @param str The string to convert to a numeric value.
90 * @param start_index The index of the first character that should be used in the conversion.
91 * @retval end_index The index of the character after the last character used in the conversion.
92 * @return The <tt>double</tt> value.
93 * @throw std::out_of_range Thrown if @a start_index is out of range.
94 * @throw std::overflow_error Thrown if the correct value would cause overflow.
95 * @throw std::underflow_error Thrown if the correct value would cause underflow.
97 double strtod(const std::string& str,
98 std::string::size_type& end_index,
99 std::string::size_type start_index = 0);
101 /** Converts a <tt>double</tt> to a string, using the <tt>'.'</tt> as decimal point.
102 * @ingroup StringUtils
103 * This functions generates enough precision that converting the string back
104 * using Glib::Ascii::strtod() gives the same machine-number (on machines with
105 * IEEE compatible 64bit doubles).
107 * @param d The <tt>double</tt> value to convert.
108 * @return The converted string.
110 std::string dtostr(double d);
115 /** Escapes all special characters in the string.
116 * @ingroup StringUtils
117 * Escapes the special characters <tt>'\\b'</tt>, <tt>'\\f'</tt>, <tt>'\\n'</tt>,
118 * <tt>'\\r'</tt>, <tt>'\\t'</tt>, <tt>'\\'</tt> and <tt>'"'</tt> in the string
119 * @a source by inserting a <tt>'\\'</tt> before them. Additionally all characters
120 * in the range <tt>0x01</tt> - <tt>0x1F</tt> (everything below <tt>SPACE</tt>)
121 * and in the range <tt>0x80</tt> - <tt>0xFF</tt> (all non-ASCII chars)
122 * are replaced with a <tt>'\\'</tt> followed by their octal representation.
124 * Glib::strcompress() does the reverse conversion.
126 * @param source A string to escape.
127 * @return A copy of @a source with certain characters escaped. See above.
129 std::string strescape(const std::string& source);
131 /** Escapes all special characters in the string.
132 * @ingroup StringUtils
133 * Escapes the special characters <tt>'\\b'</tt>, <tt>'\\f'</tt>, <tt>'\\n'</tt>,
134 * <tt>'\\r'</tt>, <tt>'\\t'</tt>, <tt>'\\'</tt> and <tt>'"'</tt> in the string
135 * @a source by inserting a <tt>'\\'</tt> before them. Additionally all characters
136 * in the range <tt>0x01</tt> - <tt>0x1F</tt> (everything below <tt>SPACE</tt>)
137 * and in the range <tt>0x80</tt> - <tt>0xFF</tt> (all non-ASCII chars)
138 * are replaced with a <tt>'\\'</tt> followed by their octal representation.
139 * Characters supplied in @a exceptions are not escaped.
141 * Glib::strcompress() does the reverse conversion.
143 * @param source A string to escape.
144 * @param exceptions A string of characters not to escape in @a source.
145 * @return A copy of @a source with certain characters escaped. See above.
147 std::string strescape(const std::string& source, const std::string& exceptions);
149 /** Replaces all escaped characters with their one byte equivalent.
150 * @ingroup StringUtils
151 * This function does the reverse conversion of Glib::strescape().
153 * @param source A string to compress.
154 * @return A copy of @a source with all escaped characters compressed.
156 std::string strcompress(const std::string& source);
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.
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.
167 Glib::ustring strerror(int errnum);
169 /** Returns a string describing the given signal, e.g.\ <tt>"Segmentation fault"</tt>.
170 * @ingroup StringUtils
171 * This function is included since not all platforms support the
172 * <tt>%strsignal()</tt> function.
174 * @param signum The signal number. See the <tt>signal()</tt> documentation.
175 * @return A string describing the signal. If the signal is unknown,
176 * <tt>"unknown signal (<em>\<signum\></em>)"</tt> is returned.
178 Glib::ustring strsignal(int signum);
183 #endif /* _GLIBMM_STRINGUTILS_H */