Main Page Widgets Namespaces Book

# String Utility Functions

This section describes a number of utility functions for creating and manipulating strings, as well as other string-related stuff. More...

## Functions

bool | Glib::str_has_prefix (const std::string& str, const std::string& prefix)
| Looks whether the string str begins with prefix.
bool | Glib::str_has_suffix (const std::string& str, const std::string& suffix)
| Looks whether the string str ends with suffix.
double | Glib::Ascii::strtod (const std::string& str)
| Converts a string to a `double` value.
double | Glib::Ascii::strtod (const std::string& str, std::string::size_type& end_index, std::string::size_type start_index=0)
| Converts a string to a `double` value.
std::string | Glib::Ascii::dtostr (double d)
| Converts a `double` to a string, using the `'.'` as decimal point.
std::string | Glib::strescape (const std::string& source)
| Escapes all special characters in the string.
std::string | Glib::strescape (const std::string& source, const std::string& exceptions)
| Escapes all special characters in the string.
std::string | Glib::strcompress (const std::string& source)
| Replaces all escaped characters with their one byte equivalent.
Glib::ustring | Glib::strerror (int errnum)
| Returns a string corresponding to the given error code, e.g. `"no such process"`.
Glib::ustring | Glib::strsignal (int signum)
| Returns a string describing the given signal, e.g. `"Segmentation fault"`.

## Detailed Description

This section describes a number of utility functions for creating and manipulating strings, as well as other string-related stuff.

## Function Documentation

std::string dtostr | ( | double | d | ) |

Converts a `double` to a string, using the `'.'` as decimal point.

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).

Parameters:

  d | The `double` value to convert.

Returns:
  The converted string.

bool str_has_prefix | ( | const std::string& | str,
|  | const std::string& | prefix
| ) |

Looks whether the string str begins with prefix.

Parameters:

  str | A string.
  prefix | The prefix to look for.

Returns:
  `true` if str begins with prefix, `false` otherwise.

bool str_has_suffix | ( | const std::string& | str,
|  | const std::string& | suffix
| ) |

Looks whether the string str ends with suffix.

Parameters:

  str | A string.
  suffix | The suffix to look for.

Returns:
  `true` if str ends with suffix, `false` otherwise.

std::string strcompress | ( | const std::string& | source | ) |

Replaces all escaped characters with their one byte equivalent.

This function does the reverse conversion of Glib::strescape().

Parameters:

  source | A string to compress.

Returns:
  A copy of source with all escaped characters compressed.

Glib::ustring strerror | ( | int | errnum | ) |

Returns a string corresponding to the given error code, e.g. `"no such process"`.

This function is included since not all platforms support the `strerror()` function.

Parameters:

  errnum | The system error number. See the standard C `errno` documentation.

Returns:
  A string describing the error code. If the error code is unknown, `"unknown error (<em>\<errnum\></em>)"` is returned.

std::string strescape | ( | const std::string& | source,
|  | const std::string& | exceptions
| ) |

Escapes all special characters in the string.

Escapes the special characters `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\'` and `'"'` in the string 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 exceptions are not escaped.

Glib::strcompress() does the reverse conversion.

Parameters:

  source | A string to escape.
  exceptions | A string of characters not to escape in source.

Returns:
  A copy of source with certain characters escaped. See above.

std::string strescape | ( | const std::string& | source | ) |

Escapes all special characters in the string.

Escapes the special characters `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\'` and `'"'` in the string 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.

Parameters:

  source | A string to escape.

Returns:
  A copy of source with certain characters escaped. See above.

Glib::ustring strsignal | ( | int | signum | ) |

Returns a string describing the given signal, e.g. `"Segmentation fault"`.

This function is included since not all platforms support the `strsignal()` function.

Parameters:

  signum | The signal number. See the `signal()` documentation.

Returns:
  A string describing the signal. If the signal is unknown, `"unknown signal (<em>\<signum\></em>)"` is returned.

double strtod | ( | const std::string& | str,
|  | std::string::size_type& | end_index,
|  | std::string::size_type | start_index = 0
| ) |

Converts a string to a `double` value.

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().

Parameters:

  str | The string to convert to a numeric value.
  start_index | The index of the first character that should be used in the conversion.

Return values:

  end_index | The index of the character after the last character used in the conversion.

Returns:
  The `double` value.

Exceptions:

  std::out_of_range | Thrown if start_index is out of range.
  std::overflow_error | Thrown if the correct value would cause overflow.
  std::underflow_error | Thrown if the correct value would cause underflow.

double strtod | ( | const std::string& | str | ) |

Converts a string to a `double` value.

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().

Parameters:

  str | The string to convert to a numeric value.

Returns:
  The `double` value.

Exceptions:

  std::overflow_error | Thrown if the correct value would cause overflow.
  std::underflow_error | Thrown if the correct value would cause underflow.