MicroStrain Strings [CPP]

String manipulation in C++. More...

Functions
bool	microstrain::strings::concat (Span< char > buffer, size_t *index, const char *str, size_t len)
	Concatenate a string into a buffer. More...
bool	microstrain::strings::concat (Span< char > buffer, size_t *index, Span< const char > str)
	Concatenate an array of characters into a buffer. More...
bool	microstrain::strings::concat_z (Span< char > buffer, size_t *index, const char *str, size_t maxLen=size_t(-1))
	Concatenate a NULL-terminated C string into a buffer. More...
template<size_t N>
bool	microstrain::strings::concat_l (Span< char > buffer, size_t *index, const char(&str)[N])
	Concatenate a string literal into a buffer. More...
bool	microstrain::strings::format_v (Span< char > buffer, size_t *index, const char *fmt, va_list args)
	Wrapper for std::vsnprintf with a better interface. More...
bool	microstrain::strings::format (Span< char > buffer, size_t *index, const char *fmt,...)
	Wrapper for std::snprintf with a better interface. More...
bool	microstrain::strings::bytesToHexStr (Span< char > buffer, size_t *index, Span< const uint8_t > data, unsigned int byte_grouping)
	Formats a byte array to a text buffer in hexadecimal. More...

Detailed Description

String manipulation in C++.

Function Documentation

bytesToHexStr()

bool microstrain::strings::bytesToHexStr ( Span< char >  buffer, size_t *  index, Span< const uint8_t >  data, unsigned int  byte_grouping  )

inline

Formats a byte array to a text buffer in hexadecimal.

No additional characters are printed other than the hex values and spaces (if byte_grouping is positive). No leading or trailing space is printed.

Examples:

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index and will point to the new NULL terminator position. If insufficient space is available in buffer, index will still be updated even if it exceeds buffer_size.
	data	Data to be formatted. Can be NULL if data_size is 0.
	data_size	Number of bytes from data to print. Must be 0 if data is NULL.
	byte_grouping	If greater than zero, a space will be printed every byte_grouping bytes. E.g. a group of 2 will print pairs of bytes separated by spaces.

Returns

True if successful

False if an encoding error occurs (see snprintf). The index is unchanged in this case.

False if insufficient space is available, unless buffer is NULL.

concat() [1/2]

bool microstrain::strings::concat ( Span< char >  buffer, size_t *  index, const char *  str, size_t  len  )

inline

Concatenate a string into a buffer.

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index in all cases.
	str	String to be appended. Cannot be NULL unless str_len is 0. Does NOT require NULL termination, and any such termination is ignored. NULL characters will be appended just like any other character.
	str_len	Length of string (number of characters to copy). Usually you would set this to strlen(str). This overrides any NULL terminator in str.

Returns

True if sufficient buffer space exists or if buffer is NULL.

False if buffer is not NULL and insufficient space is available.

concat() [2/2]

bool microstrain::strings::concat ( Span< char >  buffer, size_t *  index, Span< const char >  str  )

inline

Concatenate an array of characters into a buffer.

Equivalent to concat(buffer, buffer_size, index, str.data(), str.size());. This version accepts a Span of characters.

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index in all cases.
	str	String to be appended. Embedded NULL chars are allowed; Use concat_z for strings which are terminated before the end of the span.

Returns

True if sufficient buffer space exists or if buffer is NULL.

False if buffer is not NULL and insufficient space is available.

concat_l()

template<size_t N>

bool microstrain::strings::concat_l	(	Span< char >	buffer,
		size_t *	index,
		const char(&)	str[N]
	)

Concatenate a string literal into a buffer.

Equivalent to concat(buffer, buffer_size, index, str, sizeof(str)-1);.

Use this by passing a string literal directly so that the compiler is able to deduce the size of the string. This avoids the need to call std::strlen.

Example: concat_l(buffer, &index, "append this string");

Note that this also works with C arrays, in which case the entire array is appended (NULLs and all).

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index in all cases.
	str	String to be appended. Embedded NULL chars are allowed. Use concat_z for strings which are terminated before N characters.

Returns

True if sufficient buffer space exists or if buffer is NULL.

False if buffer is not NULL and insufficient space is available.

concat_z()

bool microstrain::strings::concat_z ( Span< char >  buffer, size_t *  index, const char *  str, size_t  maxLen = size_t(-1)  )

inline

Concatenate a NULL-terminated C string into a buffer.

Equivalent to concat(buffer, buffer_size, index, str, strlen(str));.

Copies up to maxLen characters, or the first NULL character is reached, whichever comes first. maxLen can be used when it's uncertain if the source buffer is properly terminated.

Examples:

const char* str = "To be appended";
concat_z(buffer, &index, str);    // NULL-terminated, no maxlen
concat_z(buffer, &index, str, 5); // Only copies "To be"

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index in all cases.
	str	String to be appended. NULL-termination is required unless maxLen is given.
	maxLen	If given, limit to this many characters. Defaults to unlimited.

Returns

True if sufficient buffer space exists or if buffer is NULL.

False if buffer is not NULL and insufficient space is available.

format()

bool microstrain::strings::format ( Span< char >  buffer, size_t *  index, const char *  fmt,   ...  )

inline

Wrapper for std::snprintf with a better interface.

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index and will point to the new NULL terminator position. If insufficient space is available in buffer, index will still be updated even if it exceeds buffer_size.
	fmt	Format string similar to printf.

Returns

True if successful

False if an encoding error occurs (see snprintf). The index is unchanged in this case.

False if insufficient space is available, unless buffer is NULL.

format_v()

bool microstrain::strings::format_v ( Span< char >  buffer, size_t *  index, const char *  fmt, va_list  args  )

inline

Wrapper for std::vsnprintf with a better interface.

Parameters

	buffer	Buffer of characters. The size should be the number of characters, including the NULL terminator, that will fit in the buffer. If the pointer is NULL and size is 0, this function will just compute the required buffer size and not write any characters.
[in,out]	index	Position in buffer where string data will be written. It will be updated with the new index and will point to the new NULL terminator position. If insufficient space is available in buffer, index will still be updated even if it exceeds buffer_size.
	fmt	Format string similar to printf.
	args	List of formatting arguments similar to vprintf.

Returns

True if successful

False if an encoding error occurs (see snprintf). The index is unchanged in this case.

False if insufficient space is available, unless buffer is NULL.