# 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 `'.`
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 Glib::Ascii::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 Glib::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 Glib::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 Glib::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 Glib::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 (<errnum>)"` is returned.

std::string Glib::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 Glib::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 Glib::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 (<signum>)"` is returned.

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.

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 Glib::Ascii::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.