string.bond

A collection of functions for manipulating strings of characters. More...

Functions
uint	Bond::Strlen (const char *str)
	Returns the length of a string in bytes, not in characters.
int	Bond::Strcmp (const char *str1, const char *str2)
	Compares two strings byte by byte. For UTF-8 strings, this orders them by code point. The order is stable, but it is not a locale's collation order.
uint	Bond::Utf8Length (const char *str)
	Returns the number of code points in a UTF-8 string. Each invalid byte sequence counts as one, as if it were replaced with U+FFFD.
bool	Bond::Utf8IsValid (const char *str)
	Returns whether a string is valid UTF-8. Overlong encodings, UTF-16 surrogates and values beyond U+10FFFF are invalid.
uint	Bond::Utf8Decode (const char *str, uint *codePoint)
	Decodes the UTF-8 encoded code point at the start of a string.
uint	Bond::Utf8Encode (uint codePoint, char *buffer)
	Encodes a code point in UTF-8.
bool	Bond::TryParseInt (const char *str, int *result)
	Parses a base-10 integer from the start of a string as an int.
bool	Bond::TryParseLong (const char *str, long *result)
	Parses a base-10 integer from the start of a string as a long.
bool	Bond::TryParseFloat (const char *str, float *result)
	Parses a floating-point number from the start of a string as a float.
bool	Bond::TryParseDouble (const char *str, double *result)
	Parses a floating-point number from the start of a string as a double.

Detailed Description

A collection of functions for manipulating strings of characters.

Strings are null-terminated and encoded in UTF-8. A char holds a single byte, which is one UTF-8 code unit rather than one character. The Utf8 functions operate on code points.

include "string.bond";

Function Documentation

Strcmp()

int Bond::Strcmp	(	const char *	str1,
		const char *	str2 )

Compares two strings byte by byte. For UTF-8 strings, this orders them by code point. The order is stable, but it is not a locale's collation order.

Parameters

str1	The first string to compare.
str2	The second string to compare.

Returns

A negative value if str1 orders before str2, zero if they are equal, or a positive value if str1 orders after str2.

Strlen()

uint Bond::Strlen

(

const char *

str

)

Returns the length of a string in bytes, not in characters.

Parameters

str	The string whose length is returned.

See also

Utf8Length

TryParseDouble()

bool Bond::TryParseDouble	(	const char *	str,
		double *	result )

Parses a floating-point number from the start of a string as a double.

Leading whitespace is skipped, and any characters after the number are ignored. The accepted syntax is that of the C library's strtod, which depends on the C locale unless the host has replaced the parser. A value out of the range of a double is not an error: it is parsed as infinity or zero.

Parameters

str	The string to parse.
result	Receives the parsed value on success. It is left unchanged on failure.

Returns

Whether a number was parsed. False is returned if the string does not start with a number or if either pointer is null.

TryParseFloat()

bool Bond::TryParseFloat	(	const char *	str,
		float *	result )

Parses a floating-point number from the start of a string as a float.

Leading whitespace is skipped, and any characters after the number are ignored. The accepted syntax is that of the C library's strtof, which depends on the C locale unless the host has replaced the parser. A value out of the range of a float is not an error: it is parsed as infinity or zero.

Parameters

str	The string to parse.
result	Receives the parsed value on success. It is left unchanged on failure.

Returns

Whether a number was parsed. False is returned if the string does not start with a number or if either pointer is null.

TryParseInt()

bool Bond::TryParseInt	(	const char *	str,
		int *	result )

Parses a base-10 integer from the start of a string as an int.

Leading whitespace is skipped, and any characters after the number are ignored.

Parameters

str	The string to parse.
result	Receives the parsed value on success. It is left unchanged on failure.

Returns

Whether a number was parsed. False is returned if the string does not start with a number, if the value is out of the range of an int, or if either pointer is null.

TryParseLong()

bool Bond::TryParseLong	(	const char *	str,
		long *	result )

Parses a base-10 integer from the start of a string as a long.

Leading whitespace is skipped, and any characters after the number are ignored.

Parameters

str	The string to parse.
result	Receives the parsed value on success. It is left unchanged on failure.

Returns

Whether a number was parsed. False is returned if the string does not start with a number, if the value is out of the range of a long, or if either pointer is null.

Utf8Decode()

uint Bond::Utf8Decode	(	const char *	str,
		uint *	codePoint )

Decodes the UTF-8 encoded code point at the start of a string.

Parameters

str	The string to decode.
codePoint	Receives the decoded code point, or U+FFFD if the sequence is invalid. May be null to skip over a code point without reading it.

Returns

The number of bytes consumed, from 1 to 4, or 0 at the end of the string. For an invalid sequence, it is the length of the invalid sequence, which is at least 1, so the string can be iterated with for (uint n; (n = Utf8Decode(str, &cp)) > 0u; str += n).

Utf8Encode()

uint Bond::Utf8Encode	(	uint	codePoint,
		char *	buffer )

Encodes a code point in UTF-8.

Parameters

codePoint	The code point to encode.
buffer	Receives from 1 to 4 bytes, without a null terminator. May be null to just compute the length.

Returns

The number of bytes in the encoding, or 0 if the code point is a UTF-16 surrogate or is beyond U+10FFFF, in which case nothing is written.

Utf8IsValid()

bool Bond::Utf8IsValid

(

const char *

str

)

Returns whether a string is valid UTF-8. Overlong encodings, UTF-16 surrogates and values beyond U+10FFFF are invalid.

Parameters

str	The string to validate.

Utf8Length()

uint Bond::Utf8Length

(

const char *

str

)

Returns the number of code points in a UTF-8 string. Each invalid byte sequence counts as one, as if it were replaced with U+FFFD.

Parameters

str	The string whose length is returned.