le_utf8.h File Reference

Go to the source code of this file.

Functions
ssize_t	le_utf8_NumChars (const char *string)
size_t	le_utf8_NumBytes (const char *string)
le_result_t	le_utf8_Copy (char *destStr, const char *srcStr, const size_t destSize, size_t *numBytesPtr)
le_result_t	le_utf8_Append (char *destStr, const char *srcStr, const size_t destSize, size_t *destStrLenPtr)
le_result_t	le_utf8_CopyUpToSubStr (char *destStr, const char *srcStr, const char *subStr, const size_t destSize, size_t *numBytesPtr)
bool	le_utf8_IsFormatCorrect (const char *string)
le_result_t	le_utf8_ParseInt (int *valuePtr, const char *arg)
le_result_t	le_utf8_GetMonotonicString (const char *currentStr, char *bufPtr, size_t bufSize)

Detailed Description

Legato UTF-8 String Handling API include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Function Documentation

le_result_t le_utf8_Append	(	char *	destStr,
		const char *	srcStr,
		const size_t	destSize,
		size_t *	destStrLenPtr
	)

Appends srcStr to destStr by copying characters from srcStr to the end of destStr. The srcStr must be in UTF-8 format. The number of bytes in the resultant destStr (not including the NULL-terminator) is returned in destStrLenPtr.

A null-character is always added to the end of destStr after all srcStr characters have been copied.

This function will copy as many characters as possible from srcStr to destStr while ensuring that the resultant string (including the null-character) will fit within the destination buffer.

UTF-8 characters may be more than one byte long and this function will only copy whole characters not partial characters.

The destination string will always be Null-terminated, unless destSize is zero.

If destStr and srcStr overlap the behaviour of this function is undefined.

Returns

LE_OK if srcStr was completely copied to the destStr. LE_OVERFLOW if srcStr was truncated when it was copied to destStr.

Parameters

[in]	destStr	Destination string.
[in]	srcStr	UTF-8 source string.
[in]	destSize	Size of the destination buffer in bytes.
[out]	destStrLenPtr	Number of bytes in the resultant destination string (not including the NULL-terminator). Parameter can be set to NULL if the destination string size is not needed.

le_result_t le_utf8_Copy	(	char *	destStr,
		const char *	srcStr,
		const size_t	destSize,
		size_t *	numBytesPtr
	)

Copies the string in srcStr to the start of destStr and returns the number of bytes copied (not including the NULL-terminator) in numBytesPtr. Null can be passed into numBytesPtr if the number of bytes copied is not needed. The srcStr must be in UTF-8 format.

If the size of srcStr is less than or equal to the destination buffer size then the entire srcStr will be copied including the null-character. The rest of the destination buffer is not modified.

If the size of srcStr is larger than the destination buffer then the maximum number of characters (from srcStr) plus a null-character that will fit in the destination buffer is copied.

UTF-8 characters may be more than one byte long and this function will only copy whole characters not partial characters. Even if srcStr is larger than the destination buffer ,the copied characters may not fill the entire destination buffer because the last character copied may not align exactly with the end of the destination buffer.

The destination string will always be Null-terminated, unless destSize is zero.

If destStr and srcStr overlap the behaviour of this function is undefined.

Returns

LE_OK if srcStr was completely copied to the destStr. LE_OVERFLOW if srcStr was truncated when it was copied to destStr.

Parameters

[in]	destStr	Destination where the srcStr is to be copied.
[in]	srcStr	UTF-8 source string.
[in]	destSize	Size of the destination buffer in bytes.
[out]	numBytesPtr	Number of bytes copied not including the NULL-terminator. [Parameter can be set to NULL if the number of bytes copied is not needed.

le_result_t le_utf8_CopyUpToSubStr	(	char *	destStr,
		const char *	srcStr,
		const char *	subStr,
		const size_t	destSize,
		size_t *	numBytesPtr
	)

Copies all characters from the srcStr to destStr up to the first occurrence of subStr. The subStr is not copied and instead a null-terminator is added to the destStr. The number of bytes copied (not including the null-terminator) is returned in numBytesPtr.

The srcStr and subStr must be in null-terminated UTF-8 strings.

The destination string will always be null-terminated.

If subStr is not found in the srcStr then this function behaves just like le_utf8_Copy().

Returns

LE_OK if srcStr was completely copied to the destStr. LE_OVERFLOW if srcStr was truncated when it was copied to destStr.

Parameters

[in]	destStr	Destination where the srcStr is to be copied.
[in]	srcStr	UTF-8 source string.
[in]	subStr	Sub-string to copy up to.
[in]	destSize	Size of the destination buffer in bytes.
[out]	numBytesPtr	Number of bytes copied not including the NULL-terminator. Parameter can be set to NULL if the number of bytes copied is not needed.

le_result_t le_utf8_GetMonotonicString	(	const char *	currentStr,
		char *	bufPtr,
		size_t	bufSize
	)

Gets the next string in the monotonic order.

Calling this function multiple times will produce an ordered set of strings in monotonic order. Each string is guaranteed to be unique.

If an empty string is given as the currentStr then the first string in this order is returned. Otherwise, only strings generated by this function should be used as the currentStr in this function.

The strings generated by this function can be used as identifiers where the meaning of the strings is unimportant but the strings must be unique. All generated strings are NULL-terminated ASCII strings.

Returns

LE_OK if successful. LE_OVERFLOW if the next string will not fit in the buffer. LE_FAULT if the currentStr and/or buffer is invalid.

Parameters

[in]	currentStr	The current string.
[out]	bufPtr	Buffer to store the next string.
[in]	bufSize	Buffer size.

bool le_utf8_IsFormatCorrect

(

const char *

string

)

Checks to see if the string is indeed a UTF-8 encoded, null-terminated string.

Returns

true if the format is correct. false if the format is incorrect.

Parameters

[in]

string

The string.

size_t le_utf8_NumBytes

(

const char *

string

)

Returns the number of bytes in string (not including the null-terminator).

Returns

Number of bytes in string (not including the null-terminator).

Parameters

[in]

string

The string.

ssize_t le_utf8_NumChars

(

const char *

string

)

Returns the number of characters in string.

UTF-8 encoded characters may be larger than 1 byte so the number of characters is not necessarily equal to the the number of bytes in the string.

Returns

Number of characters in string if successful. LE_FORMAT_ERROR if the string is not UTF-8.

Parameters

[in]

string

Pointer to the string.

le_result_t le_utf8_ParseInt	(	int *	valuePtr,
		const char *	arg
	)

Parse an integer value from a string.

Returns

• LE_OK = Success.
• LE_FORMAT_ERROR = The argument string was not an integer value.
• LE_OUT_OF_RANGE = Value is too large to be stored in an int variable.

Parameters

[out]	valuePtr	Ptr to where the value will be stored if successful.
[in]	arg	The string to parse.