Contains conversion utilities to transform data between different formats and types. Functions here handle string conversions, encoding manipulations, and the creation of string representations for various C++ types. They help ensure consistent serialization and text output across the library. More...

Classes
struct	has_insertion_operator
	The `has_insertion_operator` trait provides static meta-information about whether a type T has overloaded the `operator<<` for insertion into an output stream. More...

struct	has_insertion_operator< T, std::void_t< decltype(std::declval< std::ostream & >()<< std::declval< T >())> >

struct	has_key_and_mapped_type
	Type trait to check if a given type supports key_type and mapped_type, similar to std::map. More...

struct	has_key_and_mapped_type< T, std::void_t< typename T::key_type, typename T::mapped_type > >

struct	is_nested_map
	Type trait to check if a given type is a nested map. More...

struct	is_nested_map< T, std::void_t< typename T::nested_tables, typename T::table_of_values > >

Functions
std::string	to_string (const container::buffer &b)
	Creates a `std::string` from the contents of a `container::buffer`.

template<typename T>
std::enable_if< has_key_and_mapped_type< T >::value &&!is_nested_map< T >::value, std::string >::type	to_string (const T &table, const int indentation)
	Converts a container supporting key_type and mapped_type to a formatted std::string.

template<typename T>
std::enable_if< has_key_and_mapped_type< T >::value &&!is_nested_map< T >::value, std::string >::type	to_string (const T &table)
	Converts a container supporting key_type and mapped_type to a formatted std::string.

template<typename Key, typename Value>
std::string	to_string (const container::nested_map< Key, Value > &map, const int indentation)
	Converts a nested_map to a formatted std::string with specified indentation.

template<typename Key, typename Value>
std::string	to_string (container::nested_map< Key, Value > &map, const int indentation)

template<typename Key, typename Value>
std::string	to_string (const std::map< Key, container::nested_map< Key, Value > > &nested_maps, const int indentation)
	Converts a std::map of nested_maps to a formatted std::string with specified indentation.

template<typename Key, typename Value>
std::string	to_string (const std::map< Key, container::nested_map< Key, Value > > &nested_maps)
	Converts a std::map of nested_maps to a formatted std::string.

template<typename Key, typename Value>
std::string	to_string (const container::nested_map< Key, Value > &map)
	Converts a nested_map to a formatted std::string.

template<typename T>
std::enable_if< is_nested_map< T >::value, std::string >::type	to_string (const T &table)
	Converts a table to a formatted std::string, provided the table is a nested_map.

std::string	indent (int indentation)
	Returns a string consisting of `indentation` tab characters.

std::string	to_lower (std::string s)
	Converts characters A-Z in the given string to lower case and returns the modified string.

std::string	escape_string (const std::string &input, const char escape_character, const std::string &characters_to_escape)

std::string	unescape_string (const std::string &input, char escape_character, const std::string &characters_to_unescape)

template<typename T>
T	from_string (const std::string &str)
	Converts a given std::string to a specified type.

template<>
std::wstring	from_string< std::wstring > (const std::string &str)
	Converts the given std::string to std::wstring using UTF-8 to UTF-16 encoding.

template<typename T>
std::enable_if< has_insertion_operator< T >::value, std::string >::type	to_string (const T &value)
	Converts the value to a string, using the C-locale (i.e., '.' as a decimal separator).

template<typename T>
std::string	to_string (T *const &val)
	Converts a pointer to a string in hex syntax with a leading "0x".

std::string	to_string (const std::wstring &str)
	Converts the given std::wstring to std::string using UTF-16 to UTF-8 encoding.

template<typename T>
std::string	to_string (std::chrono::time_point< T > time)

template<typename T>
std::wstring	to_wstring (T value)
	Converts any value that can be handled by `to_string(...)` into a std::wstring.

std::string	to_string (const container::xpod::type &val)
	Converts an `xpod::type` variant to a `std::string`.

	TEST (ToLowerTest, HandlesUmlautsAndAccents)

	TEST (FromStringTest, ConvertToInt)

	TEST (FromStringTest, ConvertToDouble)

	TEST (FromStringTest, ConvertToBool)

	TEST (FromStringTest, ConvertToVoidPointer)

	TEST (FromStringTest, ConvertToWString_ValidUTF8)

	TEST (FromStringTest, ConvertToWString_InvalidUTF8)

	TEST (FromStringTest, ConvertToWString_EmptyString)

	TEST (FromStringTest, ConvertToWString_SpecialCharacters)

	TEST (ToStringTest, ConvertIntToString)

	TEST (ToStringTest, ConvertNegativeIntToString)

	TEST (ToStringTest, ConvertDoubleToString)

	TEST (ToStringTest, ConvertBooleanToString)

	TEST (ToStringTest, ConvertPointerToString)

	TEST (ToStringTest, ConvertCharToString)

	TEST (ToStringWStringTest, ConvertValidUTF16ToString)

	TEST (ToStringWStringTest, ConvertSpecialCharacters)

	TEST (ToStringWStringTest, ConvertEmptyWString)

	TEST (ToStringWStringTest, ConvertInvalidUTF16)

	TEST (TimePointToStringTest, ConvertTimePointToString)

	TEST (ToWStringTest, ConvertIntToWString)

	TEST (ToWStringTest, ConvertDoubleToWString)

	TEST (ToWStringTest, ConvertBoolToWString)

	TEST (ConvertMap, Basic)

	TEST (ConvertNestedMap, Basic)

Detailed Description

Contains conversion utilities to transform data between different formats and types. Functions here handle string conversions, encoding manipulations, and the creation of string representations for various C++ types. They help ensure consistent serialization and text output across the library.

Function Documentation

◆ escape_string()

std::string cbeam::convert::escape_string	(	const std::string &	input,
		const char	escape_character,
		const std::string &	characters_to_escape )

inline

◆ from_string()

template<typename T>

T cbeam::convert::from_string ( const std::string & str )

Converts a given std::string to a specified type.

This function template facilitates the conversion of a std::string to a variety of types, including fundamental types (like int, float, double) and pointer types (e.g., void*).

For floating point types such as float and double, a period ('.') is used as the decimal separator, independent of the current locale setting. For void* type, the string is interpreted as a hexadecimal number with an optional leading "0x". This function leverages std::istringstream for conversion, imbuing it with the "C" locale to ensure consistent parsing behavior across different locales.

Note: Refer to https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt for detailed behavior of the extraction operator used in this function.

Template Parameters

T	The target type for the conversion. The type must support extraction via std::istringstream.

Parameters

str	The string to be converted.

Returns: The converted value of type T.

◆ from_string< std::wstring >()

template<>

std::wstring cbeam::convert::from_string< std::wstring > ( const std::string & str )

inline

Converts the given std::string to std::wstring using UTF-8 to UTF-16 encoding.

This function utilizes std::wstring_convert with std::codecvt_utf8_utf16 to perform the conversion from string to wide string. It attempts the conversion and returns the resultant wide string if successful. In case of a range error (due to invalid UTF-8 input), it falls back to an element-wise conversion.

Note: The std::wstring_convert is deprecated in C++17. See the proposal to remove it at https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2872r2.pdf for more details.

Parameters

str	The string to be converted.

Returns: The converted wide string in UTF-16 encoding, or the element-wise conversion result in case of error.

Warning: The fallback conversion retains byte sequences that do not represent valid Unicode characters unaltered.

◆ indent()

std::string cbeam::convert::indent ( int indentation )

inline

Returns a string consisting of indentation tab characters.

Parameters

indentation The number of tabs to generate.

Returns: A std::string composed of indentation tab characters.

◆ TEST() [1/25]

cbeam::convert::TEST	(	ConvertMap	,
		Basic	)

◆ TEST() [2/25]

cbeam::convert::TEST	(	ConvertNestedMap	,
		Basic	)

◆ TEST() [3/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToBool	)

◆ TEST() [4/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToDouble	)

◆ TEST() [5/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToInt	)

◆ TEST() [6/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToVoidPointer	)

◆ TEST() [7/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToWString_EmptyString	)

◆ TEST() [8/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToWString_InvalidUTF8	)

◆ TEST() [9/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToWString_SpecialCharacters	)

◆ TEST() [10/25]

cbeam::convert::TEST	(	FromStringTest	,
		ConvertToWString_ValidUTF8	)

◆ TEST() [11/25]

cbeam::convert::TEST	(	TimePointToStringTest	,
		ConvertTimePointToString	)

◆ TEST() [12/25]

cbeam::convert::TEST	(	ToLowerTest	,
		HandlesUmlautsAndAccents	)

◆ TEST() [13/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertBooleanToString	)

◆ TEST() [14/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertCharToString	)

◆ TEST() [15/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertDoubleToString	)

◆ TEST() [16/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertIntToString	)

◆ TEST() [17/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertNegativeIntToString	)

◆ TEST() [18/25]

cbeam::convert::TEST	(	ToStringTest	,
		ConvertPointerToString	)

◆ TEST() [19/25]

cbeam::convert::TEST	(	ToStringWStringTest	,
		ConvertEmptyWString	)

◆ TEST() [20/25]

cbeam::convert::TEST	(	ToStringWStringTest	,
		ConvertInvalidUTF16	)

◆ TEST() [21/25]

cbeam::convert::TEST	(	ToStringWStringTest	,
		ConvertSpecialCharacters	)

◆ TEST() [22/25]

cbeam::convert::TEST	(	ToStringWStringTest	,
		ConvertValidUTF16ToString	)

◆ TEST() [23/25]

cbeam::convert::TEST	(	ToWStringTest	,
		ConvertBoolToWString	)

◆ TEST() [24/25]

cbeam::convert::TEST	(	ToWStringTest	,
		ConvertDoubleToWString	)

◆ TEST() [25/25]

cbeam::convert::TEST	(	ToWStringTest	,
		ConvertIntToWString	)

◆ to_lower()

std::string cbeam::convert::to_lower ( std::string s )

inline

Converts characters A-Z in the given string to lower case and returns the modified string.

This function is compatible with UTF-8-encoded strings (because the byte representations of A-Z only occur in ASCII range, which is unaffected by multi-byte sequences).

Parameters

s	The string to be transformed to lower case.

Returns: A new string with all A-Z characters converted to lower case.

◆ to_string() [1/14]

std::string cbeam::convert::to_string ( const container::buffer & b )

inline

Creates a std::string from the contents of a container::buffer.

Parameters

b	A reference to a `container::buffer`.

Returns: A std::string with the same size and contents as the provided buffer.

◆ to_string() [2/14]

template<typename Key, typename Value>

std::string cbeam::convert::to_string ( const container::nested_map< Key, Value > & map )

inline

Converts a nested_map to a formatted std::string.

This overload takes a const reference to a nested_map. It converts both the direct key-value pairs and the sub-tables of nested_maps into a formatted string.

Template Parameters

Key	The type of the keys in the nested_map.
Value	The type of the values in the nested_map.

Parameters

map	The nested_map to be converted.

Returns: A formatted string representation of the nested_map.

◆ to_string() [3/14]

template<typename Key, typename Value>

std::string cbeam::convert::to_string	(	const container::nested_map< Key, Value > &	map,
		const int	indentation )

inline

Converts a nested_map to a formatted std::string with specified indentation.

This overload takes a const reference to a nested_map and an indentation level. It converts both the direct key-value pairs and the sub-tables of nested_maps into a formatted string.

Template Parameters

Key	The type of the keys in the nested_map.
Value	The type of the values in the nested_map.

Parameters

map	The nested_map to be converted.
indentation	The indentation level for formatting the output.

Returns: A formatted string representation of the nested_map.

◆ to_string() [4/14]

std::string cbeam::convert::to_string ( const container::xpod::type & val )

inline

Converts an xpod::type variant to a std::string.

Depending on the variant's active index, this function:

Converts integers, doubles, and booleans via convert::to_string(...)
Converts pointers by calling static_cast<std::string> on the memory::pointer
Returns the string directly if the variant is holding a std::string

Parameters

val	The xpod::type variant to convert.

Returns: A string representation of the variant's value.

◆ to_string() [5/14]

template<typename Key, typename Value>

std::string cbeam::convert::to_string ( const std::map< Key, container::nested_map< Key, Value > > & nested_maps )

inline

Converts a std::map of nested_maps to a formatted std::string.

This function template converts a std::map where each value is a nested_map. It formats each key-value pair of the outer map and recursively calls to_string on each nested_map, increasing the indentation level with each recursive call for clarity and readability.

Template Parameters

Key	The type of the keys in the outer std::map.
Value	The type of the nested_maps in the outer std::map.

Parameters

nested_maps The std::map of nested_maps to be converted.

Returns: A formatted string representation of the std::map of nested_maps.

◆ to_string() [6/14]

template<typename Key, typename Value>

std::string cbeam::convert::to_string	(	const std::map< Key, container::nested_map< Key, Value > > &	nested_maps,
		const int	indentation )

inline

Converts a std::map of nested_maps to a formatted std::string with specified indentation.

This function template converts a std::map where each value is a nested_map. It formats each key-value pair of the outer map and recursively calls to_string on each nested_map, increasing the indentation level with each recursive call for clarity and readability.

Template Parameters

Key	The type of the keys in the outer std::map.
Value	The type of the nested_maps in the outer std::map.

Parameters

nested_maps	The std::map of nested_maps to be converted.
indentation	The initial indentation level for formatting the output.

Returns: A formatted string representation of the std::map of nested_maps.

◆ to_string() [7/14]

std::string cbeam::convert::to_string ( const std::wstring & str )

inline

Converts the given std::wstring to std::string using UTF-16 to UTF-8 encoding.

This function utilizes std::wstring_convert with std::codecvt_utf8_utf16 to perform the conversion from wide string to string. It attempts the conversion and returns the resultant string if successful. In case of a range error (due to invalid UTF-16 input), it falls back to an element-wise conversion.

Note: The std::wstring_convert is deprecated in C++17. See the proposal to remove it at https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2872r2.pdf for more details.

Parameters

str	The wide string to be converted.

Returns: The converted string in UTF-8 encoding, or the element-wise conversion result in case of error.

Warning: The fallback conversion retains byte sequences that do not represent valid Unicode characters unaltered.

◆ to_string() [8/14]

template<typename T>

std::enable_if< has_key_and_mapped_type< T >::value &&!is_nested_map< T >::value, std::string >::type cbeam::convert::to_string ( const T & table )

inline

Converts a container supporting key_type and mapped_type to a formatted std::string.

This function template converts a container, which supports key_type and mapped_type (like std::map), to a formatted std::string. It excludes containers of type cbeam::container::nested_map. The conversion relies on the existence of to_string methods for key_type and mapped_type. Each key-value pair is converted to a string and concatenated.

Template Parameters

T	The container type.

Parameters

table The container to be converted.

Returns: A formatted string representation of the container.

◆ to_string() [9/14]

template<typename T>

std::enable_if< is_nested_map< T >::value, std::string >::type cbeam::convert::to_string ( const T & table )

inline

Converts a table to a formatted std::string, provided the table is a nested_map.

This template function converts a table to a formatted std::string, but only if the table type is identified as a nested_map using the is_nested_map trait. It leverages the specific to_string overload for nested_map types to perform the conversion.

Template Parameters

T	The table type, expected to be a nested_map.

Parameters

table The table to be converted.

Returns: A formatted string representation of the table if it is a nested_map, otherwise an empty string.

◆ to_string() [10/14]

template<typename T>

std::enable_if< has_key_and_mapped_type< T >::value &&!is_nested_map< T >::value, std::string >::type cbeam::convert::to_string	(	const T &	table,
		const int	indentation )

inline

Converts a container supporting key_type and mapped_type to a formatted std::string.

This function template converts a container, which supports key_type and mapped_type (like std::map), to a formatted std::string. It excludes containers of type cbeam::container::nested_map. The conversion relies on the existence of to_string methods for key_type and mapped_type. Each key-value pair is converted to a string and concatenated, with indentation provided to align with surrounding context.

Template Parameters

T	The container type.

Parameters

table	The container to be converted.
indentation	The indentation level for formatting the output.

Returns: A formatted string representation of the container.

◆ to_string() [11/14]

template<typename T>

std::enable_if< has_insertion_operator< T >::value, std::string >::type cbeam::convert::to_string ( const T & value )

inline

Converts the value to a string, using the C-locale (i.e., '.' as a decimal separator).

Template Parameters

T	The type of the value, which must be valid for insertion into a std::ostream.

Parameters

value The value to be converted.

Returns: A string representation of the value.

◆ to_string() [12/14]

template<typename Key, typename Value>

std::string cbeam::convert::to_string	(	container::nested_map< Key, Value > &	map,
		const int	indentation )

inline

◆ to_string() [13/14]

template<typename T>

std::string cbeam::convert::to_string ( std::chrono::time_point< T > time )

inline

◆ to_string() [14/14]

template<typename T>

std::string cbeam::convert::to_string ( T *const & val )

inline

Converts a pointer to a string in hex syntax with a leading "0x".

Template Parameters

T	The pointed-to type.

Parameters

val	A pointer to an object of type T.

Returns: A string in hexadecimal representation, prefixed with "0x".

◆ to_wstring()

template<typename T>

std::wstring cbeam::convert::to_wstring ( T value )

Converts any value that can be handled by to_string(...) into a std::wstring.

Internally calls convert::to_string(value) and then from_string<std::wstring>(...).

Template Parameters

T	The type of the value to convert.

Parameters

value The value to convert to std::wstring.

Returns: A std::wstring representation of the input value.

◆ unescape_string()

std::string cbeam::convert::unescape_string	(	const std::string &	input,
		char	escape_character,
		const std::string &	characters_to_unescape )

inline

Classes

Functions

Detailed Description

Function Documentation

◆ escape_string()

◆ from_string()

◆ from_string< std::wstring >()

◆ indent()

◆ TEST() [1/25]

◆ TEST() [2/25]

◆ TEST() [3/25]

◆ TEST() [4/25]

◆ TEST() [5/25]

◆ TEST() [6/25]

◆ TEST() [7/25]

◆ TEST() [8/25]

◆ TEST() [9/25]

◆ TEST() [10/25]

◆ TEST() [11/25]

◆ TEST() [12/25]

◆ TEST() [13/25]

◆ TEST() [14/25]

◆ TEST() [15/25]

◆ TEST() [16/25]

◆ TEST() [17/25]

◆ TEST() [18/25]

◆ TEST() [19/25]

◆ TEST() [20/25]

◆ TEST() [21/25]

◆ TEST() [22/25]

◆ TEST() [23/25]

◆ TEST() [24/25]

◆ TEST() [25/25]

◆ to_lower()

◆ to_string() [1/14]

◆ to_string() [2/14]

◆ to_string() [3/14]

◆ to_string() [4/14]

◆ to_string() [5/14]

◆ to_string() [6/14]

◆ to_string() [7/14]

◆ to_string() [8/14]

◆ to_string() [9/14]

◆ to_string() [10/14]

◆ to_string() [11/14]

◆ to_string() [12/14]

◆ to_string() [13/14]

◆ to_string() [14/14]

◆ to_wstring()

◆ unescape_string()