String functions

This category contains tons of functions for converting/manipulating strings. More...

Functions

Type	Name
fpl_common_api size_t	fplCopyString (const char *source, char *dest, const size_t maxDestLen) Copies the given source string into a destination string.
fpl_common_api size_t	fplCopyStringLen (const char *source, const size_t sourceLen, char *dest, const size_t maxDestLen) Copies the given source string with a constrained length into a destination string.
fpl_common_api size_t	fplEnforcePathSeparator (char *path) Ensures that the given string always ends with a path separator.
fpl_common_api size_t	fplEnforcePathSeparatorLen (char *path, size_t maxPathLen) Ensures that the given string always ends with a path separator with length constrained.
fpl_common_api size_t	fplGetStringLength (const char *str) Counts the number of characters without including the zero terminator.
fpl_common_api bool	fplIsStringEqual (const char *a, const char *b) Compares two strings and returns a boolean indicating the equality.
fpl_common_api bool	fplIsStringEqualLen (const char *a, const size_t aLen, const char *b, const size_t bLen) Compares two strings with constrained lengths and returns a boolean indicating the equality.
fpl_common_api bool	fplIsStringMatchWildcard (const char *source, const char *wildcard) Matches the given string by the given wildcard and returns a boolean indicating the match.
fpl_common_api size_t	fplS32ToString (const int32_t value, char *buffer, const size_t maxBufferLen) Converts the given 32-bit integer value into a string.
fpl_common_api size_t	fplStringAppend (const char *appended, char *buffer, size_t maxBufferLen) Appends the source string to the given buffer.
fpl_common_api size_t	fplStringAppendLen (const char *appended, const size_t appendedLen, char *buffer, size_t maxBufferLen) Appends the source string to the given buffer constrained by length.
fpl_common_api size_t	fplStringFormat (char *destBuffer, const size_t maxDestBufferLen, const char *format,...) Fills out the given destination string buffer with a formatted string, using the format specifier and variable arguments.
fpl_common_api size_t	fplStringFormatArgs (char *destBuffer, const size_t maxDestBufferLen, const char *format, va_list argList) Fills out the given destination string buffer with a formatted string, using the format specifier and the arguments list.
fpl_common_api int32_t	fplStringToS32 (const char *str) Converts the given string into a 32-bit integer.
fpl_common_api int32_t	fplStringToS32Len (const char *str, const size_t len) Converts the given string into a 32-bit integer constrained by string length.
fpl_common_api bool	fplTryStringToS32 (const char *str, int32_t *outValue) Try to convert the given NUL-terminated string into a 32-bit integer.
fpl_common_api bool	fplTryStringToS32Len (const char *str, const size_t len, int32_t *outValue) Try to convert the given string into a 32-bit integer constrained by string length.
fpl_platform_api size_t	fplUTF8StringToWideString (const char *utf8Source, const size_t utf8SourceLen, wchar_t *wideDest, const size_t maxWideDestLen) Converts the given 8-bit UTF-8 source ANSI string with length into a 16-bit wide string.
fpl_platform_api size_t	fplWideStringToUTF8String (const wchar_t *wideSource, const size_t wideSourceLen, char *utf8Dest, const size_t maxUtf8DestLen) Converts the given 16-bit source wide string with length into an 8-bit UTF-8 ANSI string.

Detailed Description

This category contains tons of functions for converting/manipulating strings.

Function Documentation

fplCopyString()

fpl_common_api size_t fplCopyString ( const char * source, char * dest, const size_t maxDestLen )

Copies the given source string into a destination string.

Parameters

Direction	Parameter	Description
[in]	source	The source string.
[in,out]	dest	The destination string buffer (may be null to query the required size only).
[in]	maxDestLen	The total number of characters available in the destination buffer.

Returns: Returns the total number of characters required (excluding NUL). Returns 0 on hard error or when the buffer is too small.

Note: Null terminator is always included when written.

fplCopyStringLen()

fpl_common_api size_t fplCopyStringLen ( const char * source, const size_t sourceLen, char * dest, const size_t maxDestLen )

Copies the given source string with a constrained length into a destination string.

Parameters

Direction	Parameter	Description
[in]	source	The source string.
[in]	sourceLen	The number of characters to copy.
[in,out]	dest	The destination string buffer (may be null to query the required size only).
[in]	maxDestLen	The total number of characters available in the destination buffer.

Returns: Returns the total number of characters required (excluding NUL). Returns 0 on hard error or when the buffer is too small.

Note: Null terminator is always included when written.

fplEnforcePathSeparator()

fpl_common_api size_t fplEnforcePathSeparator ( char * path)

Ensures that the given string always ends with a path separator.

Parameters

Direction	Parameter	Description
[in,out]	path	The path string.

Returns: Returns the total number of characters of the resulting string (excluding NUL).

Note: This function is unsafe as it does not know the maximum length of the string!

fplEnforcePathSeparatorLen()

fpl_common_api size_t fplEnforcePathSeparatorLen ( char * path, size_t maxPathLen )

Ensures that the given string always ends with a path separator with length constrained.

Parameters

Direction	Parameter	Description
[in,out]	path	The target path string.
[in]	maxPathLen	The max length of the target path.

Returns: Returns the total number of characters required (excluding NUL).

Note: Returns 0 if

path is null,

maxPathLen is 0, or the buffer is too small to hold the separator + NUL. The destination is left unmodified on too-small buffer.

fplGetStringLength()

fpl_common_api size_t fplGetStringLength ( const char * str)

Counts the number of characters without including the zero terminator.

Parameters

Direction	Parameter	Description
[in]	str	The string source.

Returns: Returns the number of characters of the given string or zero when the input string is null.

fplIsStringEqual()

fpl_common_api bool fplIsStringEqual ( const char * a, const char * b )

Compares two strings and returns a boolean indicating the equality.

Parameters

Direction	Parameter	Description
[in]	a	The first string.
[in]	b	The second string.

Returns: Returns true when both strings are equal, false otherwise.

fplIsStringEqualLen()

fpl_common_api bool fplIsStringEqualLen ( const char * a, const size_t aLen, const char * b, const size_t bLen )

Compares two strings with constrained lengths and returns a boolean indicating the equality.

Parameters

Direction	Parameter	Description
[in]	a	The first string.
[in]	aLen	The number of characters for the first string.
[in]	b	The second string.
[in]	bLen	The number of characters for the second string.

Returns: Returns true when both strings are equal, false otherwise.

Note: Length parameters do not include the null-terminator!

fplIsStringMatchWildcard()

fpl_common_api bool fplIsStringMatchWildcard ( const char * source, const char * wildcard )

Matches the given string by the given wildcard and returns a boolean indicating the match.

Parameters

Direction	Parameter	Description
[in]	source	The source string.
[in]	wildcard	The wildcard string.

Returns: Returns true when the source string matches the wildcard, false otherwise.

fplS32ToString()

fpl_common_api size_t fplS32ToString ( const int32_t value, char * buffer, const size_t maxBufferLen )

Converts the given 32-bit integer value into a string.

Parameters

Direction	Parameter	Description
[in]	value	The source value.
[in]	maxBufferLen	The maximum length of the buffer.
[in,out]	buffer	The target buffer.

Returns: Returns the number of required/written characters, excluding the null-terminator.

fplStringAppend()

fpl_common_api size_t fplStringAppend ( const char * appended, char * buffer, size_t maxBufferLen )

Appends the source string to the given buffer.

Parameters

Direction	Parameter	Description
[in]	appended	The appending source string.
[in,out]	buffer	The target buffer (may be null to query the required size only).
[in]	maxBufferLen	The max length of the target buffer.

Returns: Returns the total number of characters required (excluding NUL). Returns 0 on hard error or when the buffer is too small.

fplStringAppendLen()

fpl_common_api size_t fplStringAppendLen ( const char * appended, const size_t appendedLen, char * buffer, size_t maxBufferLen )

Appends the source string to the given buffer constrained by length.

Parameters

Direction	Parameter	Description
[in]	appended	The appending source string.
[in]	appendedLen	The length of the appending source string.
[in,out]	buffer	The target buffer (may be null to query the required size only).
[in]	maxBufferLen	The max length of the target buffer.

Returns: Returns the total number of characters required (excluding NUL). Returns 0 on hard error or when the buffer is too small (buffer is left untouched).

fplStringFormat()

fpl_common_api size_t fplStringFormat ( char * destBuffer, const size_t maxDestBufferLen, const char * format, ... )

Fills out the given destination string buffer with a formatted string, using the format specifier and variable arguments.

Parameters

Direction	Parameter	Description
[in,out]	destBuffer	The destination string buffer.
[in]	maxDestBufferLen	The total number of characters available in the destination buffer.
[in]	format	The string format.
[in]	...	The variable arguments.

Returns: Returns the number of required/written characters, excluding the null-terminator.

Note: Follows C99 vsnprintf format specifiers. Returns the required length excluding NUL; returns 0 if destBuffer is too small.

fplStringFormatArgs()

fpl_common_api size_t fplStringFormatArgs ( char * destBuffer, const size_t maxDestBufferLen, const char * format, va_list argList )

Fills out the given destination string buffer with a formatted string, using the format specifier and the arguments list.

Parameters

Direction	Parameter	Description
[in,out]	destBuffer	The destination string buffer.
[in]	maxDestBufferLen	The total number of characters available in the destination buffer.
[in]	format	The string format.
[in]	argList	The arguments list.

Returns: Returns the number of required/written characters, excluding the null-terminator.

Note: Follows C99 vsnprintf format specifiers. Returns the required length excluding NUL; returns 0 if destBuffer is too small.

fplStringToS32()

fpl_common_api int32_t fplStringToS32 ( const char * str)

Converts the given string into a 32-bit integer.

Parameters

Direction	Parameter	Description
[in]	str	The source string.

Returns: Returns a 32-bit integer converted from the given string. Overflow is clamped to INT32_MAX/INT32_MIN. Invalid input returns 0 — use

fplTryStringToS32() to distinguish a valid "0" from an invalid string.

fplStringToS32Len()

fpl_common_api int32_t fplStringToS32Len ( const char * str, const size_t len )

Converts the given string into a 32-bit integer constrained by string length.

Parameters

Direction	Parameter	Description
[in]	str	The source string.
[in]	len	The length of the source string.

Returns: Returns a 32-bit integer converted from the given string. Overflow is clamped to INT32_MAX/INT32_MIN. Invalid input returns 0 — use

fplTryStringToS32Len() to distinguish a valid "0" from an invalid string.

fplTryStringToS32()

fpl_common_api bool fplTryStringToS32 ( const char * str, int32_t * outValue )

Try to convert the given NUL-terminated string into a 32-bit integer.

Parameters

Direction	Parameter	Description
[in]	str	The source string.
[out]	outValue	Receives the converted value. On overflow, clamped to INT32_MAX/INT32_MIN. May be null to validate without retrieving the value.

Returns: Returns true if

str was a valid integer literal, false otherwise.

fplTryStringToS32Len()

fpl_common_api bool fplTryStringToS32Len ( const char * str, const size_t len, int32_t * outValue )

Try to convert the given string into a 32-bit integer constrained by string length.

Parameters

Direction	Parameter	Description
[in]	str	The source string.
[in]	len	The length of the source string.
[out]	outValue	Receives the converted value. On overflow, clamped to INT32_MAX/INT32_MIN. May be null to validate without retrieving the value.

Returns: Returns true if

str was a valid integer literal (optional sign + at least one digit), false otherwise.

fplUTF8StringToWideString()

fpl_platform_api size_t fplUTF8StringToWideString ( const char * utf8Source, const size_t utf8SourceLen, wchar_t * wideDest, const size_t maxWideDestLen )

Converts the given 8-bit UTF-8 source ANSI string with length into a 16-bit wide string.

Parameters

Direction	Parameter	Description
[in]	utf8Source	The 8-bit source ANSI string.
[in]	utf8SourceLen	The number of characters of the UTF-8 source ANSI string.
[in,out]	wideDest	The 16-bit destination wide string buffer.
[in]	maxWideDestLen	The total number of characters available in the destination buffer.

Returns: Returns the number of required/written characters, excluding the null-terminator.

Note: Null terminator is always included.

fplWideStringToUTF8String()

fpl_platform_api size_t fplWideStringToUTF8String ( const wchar_t * wideSource, const size_t wideSourceLen, char * utf8Dest, const size_t maxUtf8DestLen )

Converts the given 16-bit source wide string with length into an 8-bit UTF-8 ANSI string.

Parameters

Direction	Parameter	Description
[in]	wideSource	The 16-bit source wide string.
[in]	wideSourceLen	The number of characters of the source wide string.
[in,out]	utf8Dest	The 8-bit destination ANSI string buffer.
[in]	maxUtf8DestLen	The total number of characters available in the destination buffer.

Returns: Returns the number of required/written characters, excluding the null-terminator.

Note: Null terminator is always included.