glibmm: 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.

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 )

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.

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.

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.