libs/glibmm2/glib/glibmm/stringutils.h

   1 // -*- c++ -*-
   2 #ifndef _GLIBMM_STRINGUTILS_H
   3 #define _GLIBMM_STRINGUTILS_H
   4
   5 /* $Id: stringutils.h 116 2004-06-07 17:26:39Z daniel $ */
   6
   7 /* Copyright (C) 2002 The gtkmm Development Team
   8  *
   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.
  13  *
  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.
  18  *
  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.
  22  */
  23
  24 #include <glibmm/ustring.h>
  25
  26
  27 namespace Glib
  28 {
  29
  30 /** @defgroup StringUtils String Utility Functions
  31  *
  32  * This section describes a number of utility functions for creating
  33  * and manipulating strings, as well as other string-related stuff.
  34  */
  35
  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.
  41  */
  42 bool str_has_prefix(const std::string& str, const std::string& prefix);
  43
  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.
  49  */
  50 bool str_has_suffix(const std::string& str, const std::string& suffix);
  51
  52
  53 namespace Ascii
  54 {
  55
  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&nbsp;locale. It does this without actually changing the current
  60  * locale, since that would not be thread-safe.
  61  *
  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.
  65  *
  66  * To convert from a string to <tt>double</tt> in a locale-insensitive way, use
  67  * Glib::Ascii::dtostr().
  68  *
  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.
  73  */
  74 double strtod(const std::string& str);
  75
  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&nbsp;locale. It does this without actually changing the current
  80  * locale, since that would not be thread-safe.
  81  *
  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.
  85  *
  86  * To convert from a string to <tt>double</tt> in a locale-insensitive way, use
  87  * Glib::Ascii::dtostr().
  88  *
  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.
  96  */
  97 double strtod(const std::string&      str,
  98               std::string::size_type& end_index,
  99               std::string::size_type  start_index = 0);
 100
 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).
 106  *
 107  * @param d The <tt>double</tt> value to convert.
 108  * @return The converted string.
 109  */
 110 std::string dtostr(double d);
 111
 112 } // namespace Ascii
 113
 114
 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>&nbsp;-&nbsp;<tt>0x1F</tt> (everything below <tt>SPACE</tt>)
 121  * and in the range <tt>0x80</tt>&nbsp;-&nbsp;<tt>0xFF</tt> (all non-ASCII chars)
 122  * are replaced with a <tt>'\\'</tt> followed by their octal representation.
 123  *
 124  * Glib::strcompress() does the reverse conversion.
 125  *
 126  * @param source A string to escape.
 127  * @return A copy of @a source with certain characters escaped. See above.
 128  */
 129 std::string strescape(const std::string& source);
 130
 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>&nbsp;-&nbsp;<tt>0x1F</tt> (everything below <tt>SPACE</tt>)
 137  * and in the range <tt>0x80</tt>&nbsp;-&nbsp;<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.
 140  *
 141  * Glib::strcompress() does the reverse conversion.
 142  *
 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.
 146  */
 147 std::string strescape(const std::string& source, const std::string& exceptions);
 148
 149 /** Replaces all escaped characters with their one byte equivalent.
 150  * @ingroup StringUtils
 151  * This function does the reverse conversion of Glib::strescape().
 152  *
 153  * @param source A string to compress.
 154  * @return A copy of @a source with all escaped characters compressed.
 155  */
 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>&quot;unknown error (<em>\<errnum\></em>)&quot;</tt> is returned.
 166  */
 167 Glib::ustring strerror(int errnum);
 168
 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.
 173  *
 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>&quot;unknown signal (<em>\<signum\></em>)&quot;</tt> is returned.
 177  */
 178 Glib::ustring strsignal(int signum);
 179
 180 } // namespace Glib
 181
 182
 183 #endif /* _GLIBMM_STRINGUTILS_H */
 184