This is a detail namespace of module ALib Strings.

Functions
template<typename TChar >
ALIB_API uint64_t	ParseBin (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API uint64_t	ParseDec (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
uint64_t	ParseDecDigits (const TString< TChar > &src, integer &idx)

template<typename TChar >
ALIB_API double	ParseFloat (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API uint64_t	ParseHex (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API int64_t	ParseInt (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API uint64_t	ParseOct (const TString< TChar > &src, integer &idx, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteBin (uint64_t value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteDecSigned (int64_t value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteDecUnsigned (uint64_t value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteFloat (double value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteHex (uint64_t value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

template<typename TChar >
ALIB_API integer	WriteOct (uint64_t value, TChar *buffer, integer idx, int minWidth, const TNumberFormat< TChar > &nf)

Function Documentation

◆ ParseBin()

ALIB_API uint64_t aworx::lib::strings::detail::ParseBin	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Reads an unsigned integral value in binary format from the given character array at the given position.
Sign literals '-' or '+' are not accepted and parsing will fail if found. Whitespace and grouping characters, as defined in fields Whitespaces, BinNibbleGroupChar, BinByteGroupChar BinWordGroupChar and BinWord32GroupChar of the NumberFormat object given with nf, will be ignored (tolerated), regardless on their position between digits. To suppress the parsing of group characters, set the fields to '\0'. To suppress whitespace consumption, set field Whitespaces to nulled or empty string.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseDec()

ALIB_API uint64_t aworx::lib::strings::detail::ParseDec	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Reads an unsigned integral value in decimal format from the given character array at the given position.
Sign literals '-' or '+' are not accepted and parsing will fail if found. Whitespace and grouping characters, as defined in fields Whitespaces and ThousandsGroupChar of the NumberFormat object given with nf will be ignored (tolerated) regardless on their position between digits. To suppress the parsing of group characters, set field ThousandsGroupChar to '\0'. To suppress whitespace consumption before reading the value, set field Whitespaces to nulled or empty string.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseDecDigits()

uint64_t aworx::lib::strings::detail::ParseDecDigits	(	const TString< TChar > &	src,
		integer &	idx
	)

Reads digits '0' to '9' into a positive integral value.

Note: The function is very basic, i.e. it does not use an object of type TNumberFormat, does not tolerate group characters and so forth. Instead, it simply reads decimal digits, until a non-digit character is found or the string ends.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found. If out of bounds, `0` is returned.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseFloat()

ALIB_API double aworx::lib::strings::detail::ParseFloat	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Reads a floating point value from the given character array at the given position.
Sign literals '-' or '+' are not accepted and parsing will fail if found.

If the strings defined in fields NANLiteral and INFLiteral are found in the NumberFormat object given with nf, the corresponding double constant (not a number, positive/negative infinity) will be returned.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseHex()

ALIB_API uint64_t aworx::lib::strings::detail::ParseHex	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Reads an unsigned integral value in hexadecimal format from the given character array at the given position.
Sign literals '-' or '+' are not accepted and parsing will fail if found. Whitespace and grouping characters, as defined in fields Whitespaces, HexByteGroupChar, HexWordGroupChar and HexWord32GroupChar of the NumberFormat object given with nf, will be ignored (tolerated) regardless of their position between digits. To suppress the parsing of group characters, set the fields to '\0'. To suppress whitespace consumption, set field Whitespaces to nulled or empty string.

Letters 'a' to 'f' are parsed ignoring their case. This is independent from the setting of field HexLowerCase.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseInt()

ALIB_API int64_t aworx::lib::strings::detail::ParseInt	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Parses signed integer numbers, optionally in binary, hexadecimal or octal format.

Leading characters defined in field Whitespaces of the NumberFormat object given with nf are ignored. An optional sign character '+' or '-' is parsed. If found, again whitespace characters may follow behind such sign and are ignored.

Then, the function detects any literal prefixes as defined in fields BinLiteralPrefix, HexLiteralPrefix and OctLiteralPrefix (usually 0b, 0x and 0o) and invokes one of the functions ParseDec, ParseBin, ParseHex or ParseOct.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ ParseOct()

ALIB_API uint64_t aworx::lib::strings::detail::ParseOct	(	const TString< TChar > &	src,
		integer &	idx,
		const TNumberFormat< TChar > &	nf
	)

Reads an unsigned integral value in binary format from the given character array at the given position.
Sign literals '-' or '+' are not accepted and parsing will fail if found. Whitespace and grouping characters, as defined in fields Whitespaces and OctGroupChar of the NumberFormat object given with nf, will be ignored (tolerated) regardless of their position between digits. To suppress the parsing of group characters, set the field to '\0'. To suppress whitespace consumption, set field Whitespaces to nulled or empty string.

Template Parameters

TChar The character type of the string to parse from.

Parameters

	src	The string to read the value from.
[in,out]	idx	The start point for parsing within src. Will be set to point behind the last character consumed. If unchanged, this indicates that no parsable number was found.
	nf	The number format to use.

Returns: The parsed value. In addition, on success, parameter idx is moved to point to the first character behind the parsed number.

◆ WriteBin()

ALIB_API integer aworx::lib::strings::detail::WriteBin	(	uint64_t	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Converts the given long value to a string representation in binary format.

The maximum number of digits written is 64. In addition, grouping characters may be written according the settings of fields WriteGroupChars, BinNibbleGroupChar, BinByteGroupChar, BinWordGroupChar, BinWord32GroupChar and LeadingGroupCharReplacement of the NumberFormat object given with nf.

The minimum width of the output is taken from field BinFieldWidth unless overwritten by parameter minWidth. If the width is greater than digits found in value, '0' digits are prepended. The width is taking group characters into account.

Attention: The function does not (and can not) check an overflow of the given character buffer when writing.; If the value is greater than can be represented by the output width, these greater digits are cut. This is true for this function as well as for WriteHex and WriteOct. The rationale behind this is that this way, larger numbers do not need to be masked before writing. (In other words: it is assumed that there is a reason for providing the width).

Note: The literal prefix found in field BinLiteralPrefix of nf is not written. The field is only used for detecting formats with function ParseInt.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the output. If `0`, the value of BinFieldWidth of argument nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

◆ WriteDecSigned()

ALIB_API integer aworx::lib::strings::detail::WriteDecSigned	(	int64_t	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Converts the given long value to a string representation into a signed decimal format.
For negative numbers, '-' is written, the sign of positive numbers (if any) depends on field PlusSign of the NumberFormat object given with nf. After that, the value is negated (made positive) and WriteDecUnsigned is invoked.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the output. If `0`, the value of DecMinimumFieldWidth in nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

◆ WriteDecUnsigned()

ALIB_API integer aworx::lib::strings::detail::WriteDecUnsigned	(	uint64_t	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Converts the given long value to a string representation in decimal format.

The maximum number of digits written is 20. In addition, grouping characters may be written according the settings of fields WriteGroupChars, ThousandsGroupChar and LeadingGroupCharReplacement of the NumberFormat object given with nf.

The minimum width of the output is taken from field DecMinimumFieldWidth unless overwritten by parameter minWidth. If the minimum width is greater than the sum of digits and* grouping characters needed to write value, then '0' digits are prepended between the sign and the number.

Attention: The function does not (and can not) check an overflow of the given character buffer when writing.

See also: Function WriteDecSigned to write signed decimals.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the output. If `0`, the value of DecMinimumFieldWidth of argument nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

◆ WriteFloat()

ALIB_API integer aworx::lib::strings::detail::WriteFloat	(	double	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Writes a string representation of the given double value.

Grouping characters are written according the settings of fields WriteGroupChars, ThousandsGroupChar and LeadingGroupCharReplacement of the NumberFormat object given with nf.

The minimum width of the integral part of the output is taken from field IntegralPartMinimumWidth unless overwritten by parameter minWidth. If the width is greater than integral digits found in value, '0' digits are prepended. The width is taking group characters into account.

If field FractionalPartWidth as well as the width of the integral part (provided or set) equals -1 the function may choose scientific notation. This is done for numbers smaller than 10E-4 or larger than 10E+6.

If the given value is not a number, NANLiteral is written. If infinite, INFLiteral.

The output format is dependent on various further settings provided in the fields of parameter nf. Those are DecimalPointChar, ExponentSeparator, ForceDecimalPoint, WriteExponentPlusSign and ForceScientific.

Attention: The function does not (and can not) check an overflow of the given character buffer when writing.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the integral part of the output. If `0`, the value of IntegralPartMinimumWidth of argument nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

◆ WriteHex()

ALIB_API integer aworx::lib::strings::detail::WriteHex	(	uint64_t	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Converts the given long value to a string representation in hexadecimal format.

The maximum number of digits written is 16. In addition, grouping characters may be written according the settings of fields WriteGroupChars, HexByteGroupChar, HexWordGroupChar, HexWord32GroupChar and LeadingGroupCharReplacement of the NumberFormat object given with nf.

The minimum width of the output is taken from field HexFieldWidth unless overwritten by parameter minWidth. If the width is greater than digits found in value, '0' digits are prepended. The width is taking group characters into account.

Attention: The function does not (and can not) check an overflow of the given character buffer when writing.; If the value is greater than can be represented by the output width, these greater digits are cut. This is true for this function as well as WriteBin and writeOct. The rationale behind this is that this way, larger numbers do not need to be masked before writing. (In other words: it is assumed that there is a reason for providing the width).

Note: The literal prefix found in field HexLiteralPrefix of nf is not written. The field is only used for detecting formats with function ParseInt.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the output. If `0`, the value of HexFieldWidth of argument nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

◆ WriteOct()

ALIB_API integer aworx::lib::strings::detail::WriteOct	(	uint64_t	value,
		TChar *	buffer,
		integer	idx,
		int	minWidth,
		const TNumberFormat< TChar > &	nf
	)

Converts the given long value to a string representation in octal format.

The maximum number of digits written is 64. In addition, grouping characters may be written according the settings of fields WriteGroupChars, OctGroupChar and LeadingGroupCharReplacement.

The minimum width of the output is taken from field OctFieldWidth unless overwritten by parameter minWidth. If the width is greater than digits found in value, '0' digits are prepended. The width is taking group characters into account.

Attention: The function does not (and can not) check an overflow of the given character buffer when writing.; If the value is greater than can be represented by the output width, these greater digits are cut. This is true for this function as well as WriteBin and writeHex. The rationale behind this is that this way, larger numbers do not need to be masked before writing. (In other words: it is assumed that there is a reason for providing the width).

Note: The literal prefix found in field OctLiteralPrefix of nf is not written. The field is only used for detecting formats with function ParseInt.

Template Parameters

TChar The character type of the string to write into.

Parameters

value	The value to write.
buffer	The character array to write the value to. Needs to be long enough (after idx) to carry the string written.
idx	The index within buffer to start writing.
minWidth	The minimum width of the output. If `0`, the value of OctFieldWidth of argument nf is used.
nf	Number format definitions.

Returns: The index pointing to behind the last character written in buffer.

Functions

Function Documentation

◆ ParseBin()

◆ ParseDec()

◆ ParseDecDigits()

◆ ParseFloat()

◆ ParseHex()

◆ ParseInt()

◆ ParseOct()

◆ WriteBin()

◆ WriteDecSigned()

◆ WriteDecUnsigned()

◆ WriteFloat()

◆ WriteHex()

◆ WriteOct()