gul17/string_util.h

Detailed Description

Various string utility functions.

Functions
template<typename Integer , std::enable_if_t< std::is_integral< Integer >::value, bool > = true>
std::string	gul17::hex_string (Integer v)
	Return the hexadecimal ASCII representation of an integer value.
template<typename Iterator >
std::string	gul17::hex_string (Iterator begin, Iterator end, std::string_view separator="")
	Return the hexadecimal ASCII representation of a range of integer values.
template<typename Integer , size_t num_elements, std::enable_if_t< std::is_integral< Integer >::value, bool > = true>
std::string	gul17::hex_string (const Integer(&array)[num_elements], std::string_view separator="")
	Return the hexadecimal ASCII representation of an array with integer values.
template<typename Container , std::enable_if_t< IsContainerLike< Container >::value, bool > = true>
std::string	gul17::hex_string (const Container &container, std::string_view separator="")
	Return the hexadecimal ASCII representation of a container with integer values.
GUL_EXPORT std::string	gul17::null_safe_string (const char *char_ptr)
	Safely construct a std::string from a C string or a null pointer.
GUL_EXPORT std::string_view	gul17::null_safe_string_view (const char *char_ptr)
	Safely construct a string_view from a char pointer.
GUL_EXPORT std::string	gul17::repeat (std::string_view str, std::size_t n)
	Repeat a string N times.
GUL_EXPORT std::string	gul17::safe_string (const char *char_ptr, std::size_t length)
	Safely construct a std::string from a char pointer and a length.
GUL_EXPORT std::string_view	gul17::safe_string_view (const char *char_ptr, std::size_t length)
	Safely construct a string_view from a char pointer and a length.

Variables
GUL_EXPORT const std::string_view	gul17::default_whitespace_characters { " \t\r\n\a\b\f\v" }
	The default characters that are treated as whitespace by GUL.
GUL_EXPORT const std::array< char, 16 >	gul17::hex_digits
	The 16 digits for hexadecimal numbers ("0123456789abcdef").

Function Documentation

hex_string() [1/4]

template<typename Container , std::enable_if_t< IsContainerLike< Container >::value, bool > = true>

std::string gul17::hex_string ( const Container &  container, std::string_view  separator = ""  )

inline

Return the hexadecimal ASCII representation of a container with integer values.

The letters 'a' to 'f' are used in lowercase, and no separators are inserted between individual values.

std::array<unsigned char, 4> values = { 0, 15, 16, 255 };
assert(hex_string(values) == "000f10ff");

Parameters

container	Input container
separator	A string that is inserted between the elements to separate them visually (empty by default)

Template Parameters

Container

must be a gul17::IsContainerLike class

Since

GUL version 2.6

References gul17::bit_set(), and gul17::hex_string().

hex_string() [2/4]

template<typename Integer , size_t num_elements, std::enable_if_t< std::is_integral< Integer >::value, bool > = true>

std::string gul17::hex_string ( const Integer(&)  array[num_elements], std::string_view  separator = ""  )

inline

Return the hexadecimal ASCII representation of an array with integer values.

The letters 'a' to 'f' are used in lowercase, and a user-defined separator can be inserted between individual values.

uint16_t values[] = { 256, 255 };
assert(hex_string(values) == "010000ff");
assert(hex_string(values, "-") == "0100-00ff");

Parameters

array	Input array
separator	A string that is inserted between the elements to separate them visually (empty by default)

Template Parameters

Integer	must be an integral type.
num_elements	is the number of array elements.

Since

GUL version 2.6

References gul17::bit_set(), and gul17::hex_string().

hex_string() [3/4]

template<typename Integer , std::enable_if_t< std::is_integral< Integer >::value, bool > = true>

std::string gul17::hex_string ( Integer  v )

inline

Return the hexadecimal ASCII representation of an integer value.

The letters 'a' to 'f' are used in lowercase, and the number of hex digits is twice the number of bytes in the input integer type.

hex_string(static_cast<unsigned char>(1)) == "01"
hex_string(static_cast<unsigned char>(255)) == "ff";
hex_string(uint32_t{ 256 }) == "00000100";

Parameters

v	Input value

Template Parameters

Integer

must be an integral type.

Since

GUL version 2.6

References gul17::bit_set(), and gul17::hex_digits.

Referenced by gul17::hex_string(), gul17::hex_string(), and gul17::hex_string().

hex_string() [4/4]

template<typename Iterator >

std::string gul17::hex_string ( Iterator  begin, Iterator  end, std::string_view  separator = ""  )

inline

Return the hexadecimal ASCII representation of a range of integer values.

The letters 'a' to 'f' are used in lowercase, and a user-defined separator can be inserted between individual values.

std::array<unsigned char, 4> values = { 0, 15, 16, 255 };
assert(hex_string(values.begin(), values.end()) == "000f10ff");
assert(hex_string(values.begin(), values.end(), "-") == "00-0f-10-ff");

Parameters

begin	Iterator to the first element of the range
end	Iterator past the last element of the range
separator	A string that is inserted between the elements to separate them visually (empty by default)

Template Parameters

Iterator

must be a forward iterator.

Since

GUL version 2.6

References gul17::bit_set(), and gul17::hex_string().

null_safe_string()

std::string gul17::null_safe_string

(

const char *

char_ptr

)

Safely construct a std::string from a C string or a null pointer.

If the pointer is null, an empty string is constructed. Otherwise, the function assumes to find a zero-terminated C string and constructs a std::string from it.

auto a = safe_string(nullptr);  // a == ""s
auto b = safe_string("ABC");    // b == "ABC"s
auto c = safe_string("AB\0CD"); // c == "AB"s

Parameters

char_ptr

Pointer to a null-terminated string or a null pointer

See also

safe_string(), null_safe_string_view()

Since

GUL version UNRELEASED

References gul17::bit_set().

null_safe_string_view()

std::string_view gul17::null_safe_string_view

(

const char *

char_ptr

)

Safely construct a string_view from a char pointer.

If the pointer is null, an empty string_view is constructed. Otherwise, the function assumes to find a zero-terminated C string and constructs a std::string_view from it.

auto a = safe_string_view(nullptr);  // a == ""sv
auto b = safe_string_view("ABC");    // b == "ABC"sv
auto c = safe_string_view("AB\0CD"); // c == "AB"sv

Parameters

char_ptr

Pointer to a null-terminated string or a null pointer

See also

safe_string_view(), null_safe_string()

Since

GUL version UNRELEASED

References gul17::bit_set().

repeat()

std::string gul17::repeat	(	std::string_view	str,
		std::size_t	n
	)

Repeat a string N times.

std::string str = repeat("du", 3); // str == "dududu"

Parameters

str	String to be repeated
n	Number of repetitions

Returns

the N-fold concatenation of the input string.

Since

GUL version 2.7

References gul17::bit_set().

safe_string()

std::string gul17::safe_string	(	const char *	char_ptr,
		std::size_t	length
	)

Safely construct a std::string from a char pointer and a length.

If the pointer is null, an empty string is constructed. If there are no zero bytes in the input range, a string of length length is constructed. Otherwise, the input string is treated as a C string and the first zero byte is treated as the end of the string.

auto a = safe_string(nullptr, 5);  // a == ""s
auto b = safe_string("ABC", 2);    // b == "AB"s
auto c = safe_string("ABC", 4);    // c == "ABC"s, trailing zero byte ends the string
auto d = safe_string("AB\0CD", 5); // d == "AB"s, intermediate zero byte ends the string

Parameters

char_ptr	Pointer to a string that is either null-terminated or has at least length accessible bytes, or a null pointer
length	Maximum length of the generated string

See also

null_safe_string(), safe_string_view()

Since

GUL version 2.6

References gul17::bit_set().

safe_string_view()

std::string_view gul17::safe_string_view	(	const char *	char_ptr,
		std::size_t	length
	)

Safely construct a string_view from a char pointer and a length.

If the pointer is null, an empty string_view is constructed. If there are no zero bytes in the input range, a string_view of length length is constructed. Otherwise, the input string is treated as a C string and the first zero byte is treated as the end of the string.

auto a = safe_string_view(nullptr, 5);  // a == ""sv
auto b = safe_string_view("ABC", 2);    // b == "AB"sv
auto c = safe_string_view("ABC", 4);    // c == "ABC"sv, trailing zero byte ends the string
auto d = safe_string_view("AB\0CD", 5); // d == "AB"sv, intermediate zero byte ends the string

Parameters

char_ptr	Pointer to a string that is either null-terminated or has at least length accessible bytes, or a null pointer
length	Maximum length of the generated string_view

See also

null_safe_string_view(), safe_string()

Since

GUL version 25.4.0

References gul17::bit_set().

Variable Documentation

default_whitespace_characters

const std::string_view gul17::default_whitespace_characters { " \t\r\n\a\b\f\v" }

The default characters that are treated as whitespace by GUL.

This is a string view that contains the space and the most common control characters, namely (with their ASCII codes):

• Bell/alert (7)
• Backspace (8)
• Horizontal tabulator (9)
• Newline/line feed (10)
• Vertical Tab (11)
• Form feed (12)
• Carriage return (13)
• Space (32)

Note

The null character is not treated as whitespace by default.

hex_digits

const std::array< char, 16 > gul17::hex_digits

Initial value:

{
    { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'} }

The 16 digits for hexadecimal numbers ("0123456789abcdef").

Referenced by gul17::hex_string().