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. More...
bool | Glib::str_has_suffix (const std::string& str, const std::string& suffix)
| Looks whether the string str ends with suffix. More...
double | Glib::Ascii::strtod (const std::string& str)
| Converts a string to a `double` value. More...
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. More...
std::string | Glib::Ascii::dtostr (double d)
| Converts a `double` to a string, using the `'`. More...
std::string | Glib::strescape (const std::string& source)
| Escapes all special characters in the string. More...
std::string | Glib::strescape (const std::string& source, const std::string& exceptions)
| Escapes all special characters in the string. More...
std::string | Glib::strcompress (const std::string& source)
| Replaces all escaped characters with their one byte equivalent. More...
Glib::ustring | Glib::strerror (int errnum)
| Returns a string corresponding to the given error code, e.g. `"no such process"`. More...
Glib::ustring | Glib::strsignal (int signum)
| Returns a string describing the given signal, e.g. `"Segmentation fault"`. More...

## Detailed Description

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

## Function Documentation

## dtostr()

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.

## str_has_prefix()

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.

## str_has_suffix()

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.

## strcompress()

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.

## strerror()

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.

## strescape() [1/2]

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.

## strescape() [2/2]

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.

## strsignal()

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.

## strtod() [1/2]

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.

## strtod() [2/2]

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.