This chapter provides reference material for the String Manager. The String Manager API is declared in the header file StringMgr.h
. This chapter covers:
String Manager Constants
String Manager Functions and Macros
For more information, see Chapter 1, "Text,".
String Manager Constants
String Manager Constants
Purpose
Constants defined in StringMgr.h
.
Declared In
StringMgr.h
Constants
-
#define maxStrIToALen 12
- Maximum length of a string to pass to
StrIToA()
not including the terminating null character. -
#define StrPrintF sprintf
- Convenience macro that maps calls to the old
StrPrintF()
function to the standard C library functionsprintf()
. If you need to ensure the old functionality, useStrPrintFV50()
. -
#define StrVPrintF vsprintf
- Convenience macro that maps calls to the old
StrVPrintF()
function to the standard C library function vsprintf()
. If you need to ensure the old functionality, useStrVPrintFV50()
.
String Manager Functions and Macros
StrAToI Function
Purpose
Converts a string to an integer.
Declared In
StringMgr.h
Prototype
int32_t StrAToI (
const char *str
)
Parameters
Returns
StrCaselessCompare Function
Purpose
Compares two strings with case, size, and accent insensitivity.
Declared In
StringMgr.h
Prototype
int16_t StrCaselessCompare ( const char*s1
, const char*s2
)
Parameters
Returns
Comments
StrCaselessCompare()
correctly performs locale-specific sorting and handles strings with multi-byte characters, whereas the standard C library function stricmp()
does not. If the string to be compared will not be visible to the user and does not contain any locale-sensitive data, it is more efficient to use stricmp()
.
This function differs from TxtCaselessCompare()
in that it always compares the two strings in their entirety and does not return the length of the matching text.
See Also
StrNCaselessCompare()
, StrCompare()
, StrNCompare()
StrCat Function
Purpose
Concatenates one null-terminated string to another.
Declared In
StringMgr.h
Prototype
char *StrCat ( char*dst
, const char*src
)
Parameters
Returns
Comments
This function calls through to the standard strcat()
function.
StrChr Function
Purpose
Looks for a character within a string.
Declared In
StringMgr.h
Prototype
char *StrChr ( const char*str
, wchar32_tchr
)
Parameters
Returns
A pointer to the first occurrence of chr
in str
. Returns NULL
if the character is not found.
Comments
Use this function instead of the standard strchr()
function.
This function can handle both single-byte characters and multi-byte characters correctly. However, you should make sure that you pass a wchar32_t
variable to StrChr()
instead of a char
. If you pass a char
variable, the function sign-extends the variable to a wchar32_t
, which causes problems if the value is 0x80 or higher.
See Also
StrCompare Function
Purpose
Case-sensitive comparison of two strings.
Declared In
StringMgr.h
Prototype
int16_t StrCompare ( const char*s1
, const char*s2
)
Parameters
Returns
A positive number if s1
sorts after s2
alphabetically.
A negative number if s1
sorts before s2
alphabetically.
Comments
StrCompare()
correctly performs locale-specific sorting and handles strings with multi-byte characters, whereas the standard C library function strcmp()
does not. If the string to be compared will not be visible to the user and does not contain any locale-sensitive data, it is more efficient to use strcmp()
.
This function differs form TxtCompare()
in that it always compares the two strings in their entirety and does not return the length of the matching text.
See Also
StrNCompare()
, StrNCaselessCompare()
, TxtCaselessCompare()
StrCompareAscii Function
Purpose
Declared In
StringMgr.h
Prototype
int16_t StrCompareAscii ( const char*s1
, const char*s2
)
Parameters
Returns
A positive number if s1
sorts after s2
alphabetically.
A negative number if s1
sorts before s2
alphabetically.
Comments
This function calls through to the standard strcmp()
function.
See Also
StrCompare()
, StrNCompare()
, TxtCompare()
, StrCaselessCompare()
, StrNCaselessCompare()
, TxtCaselessCompare()
, StrNCompareAscii()
StrCopy Function
Purpose
Declared In
StringMgr.h
Prototype
char *StrCopy ( char*dst
, const char*src
)
Parameters
Returns
Comments
This function calls through to the standard strcpy()
function. It does not work properly with overlapping strings.
StrDelocalizeNumber Function
Purpose
Delocalizes a number passed in as a string. Converts the number from any localized notation to US notation (decimal point and thousandth comma).
Declared In
StringMgr.h
Prototype
char *StrDelocalizeNumber ( char*s
, charthousandSeparator
, chardecimalSeparator
)
Parameters
-
→ s
- The number as an ASCII string.
-
→ thousandSeparator
- Current thousand separator.
-
→ decimalSeparator
- Current decimal separator.
Returns
A pointer to the changed number and modifies the string in s
.
Comments
The current thousandSeparator
and decimalSeparator
can be determined by obtaining the value of the prefNumberFormat
preference using PrefGetPreference()
and then passing the returned NumberFormatType
to LmGetNumberSeparators()
.
Example
The following code shows how to use StrDelocalizeNumber()
.
char *localizedNum; NumberFormatType numFormat; char thousandsSeparator, decimalSeparator; numFormat = (NumberFormatType) PrefGetPreference(prefNumberFormat); LmGetNumberSeparators(numFormat, &thousandsSeparator, &decimalSeparator); StrDelocalizeNumber(localizedNum, thousandsSeparator, decimalSeparator);
See Also
StrLocalizeNumber()
, LmGetNumberSeparators()
StrIToA Function
Purpose
Declared In
StringMgr.h
Prototype
char *StrIToA ( char*s
, int32_ti
)
Parameters
Returns
See Also
StrIToH Function
Purpose
Converts an integer to hexadecimal ASCII.
Declared In
StringMgr.h
Prototype
char *StrIToH ( char*s
, uint32_ti
)
Parameters
Returns
See Also
StrLCat Function
Purpose
Concatenates one string to another, clipping the destination string to a maximum of siz
bytes (including the null character at the end).
Declared In
StringMgr.h
Prototype
size_t StrLCat ( char*dst
, const char*src
, size_tsiz
)
Parameters
-
→ dst
- The null-terminated destination string.
-
→ src
- The null-terminated source string.
-
→ siz
- Maximum length in bytes for
dst
, including the terminating null character.
Returns
The length in bytes of dst
if the entire string src
were appended to it. If siz
is less than the return value of this function, then you know that the src
string is truncated in dst
.
Comments
Use this function instead of the standard C library function strlcat()
. It correctly handles multi-byte character strings. Specifically, it truncates any partial characters that appear at the end of the string and replaces them with null characters.
See Also
StrLCopy Function
Purpose
Multi-byte version of the standard C library function strlcpy()
.
Declared In
StringMgr.h
Prototype
size_t StrLCopy ( char*dst
, const char*src
, size_tsiz
)
Parameters
-
→ dst
- The null-terminated destination string.
-
→ src
- The null-terminated source string.
-
→ siz
- Maximum length in bytes for
dst
, including the terminating null character.
Returns
The number of bytes in the src
string, not including the null terminator. If this value is greater than or equal to siz
, then truncation occurred.
Comments
Use this function instead of the standard C library function strlcpy()
. It correctly handles multi-byte character strings. Specifically, it truncates any partial characters that appear at the end of the string and replaces them with null characters.
See Also
StrLen Function
Purpose
Computes the length of a string.
Declared In
StringMgr.h
Prototype
size_t StrLen (
const char *src
)
Parameters
Returns
The length of the string in bytes.
Comments
This function calls through to the standard strlen()
function. It always correctly returns the number of bytes used to store the string. Remember that on systems that support multi-byte characters, the number returned does not always equal the number of characters.
StrLocalizeNumber Function
Purpose
Converts a number (passed in as a string) to localized format, using a specified thousands separator and decimal separator.
Declared In
StringMgr.h
Prototype
char *StrLocalizeNumber ( char*s
, charthousandSeparator
, chardecimalSeparator
)
Parameters
-
↔ s
- Numeric ASCII string to localize. Upon return, contains the same string with all occurrences of "," replaced by
thousandSeparator
and all occurrences of "." withdecimalSeparator
. -
→ thousandSeparator
- Localized thousand separator.
-
→ decimalSeparator
- Localized decimal separator.
Returns
Comments
The current thousandSeparator
and decimalSeparator
can be determined by obtaining the value of the prefNumberFormat
preference using PrefGetPreference()
and then passing the returned NumberFormatType
to LmGetNumberSeparators()
.
See Also
StrNCaselessCompare Function
Purpose
Compares two strings out to n characters with case, size, and accent insensitivity.
Declared In
StringMgr.h
Prototype
int16_t StrNCaselessCompare ( const char*s1
, const char*s2
, size_tn
)
Parameters
Returns
Comments
StrNCaselessCompare()
correctly performs locale-specific sorting and handles strings with multi-byte characters.
This function differs from TxtCaselessCompare()
only in that it does not return the length of the matching strings.
See Also
StrNCompare()
, StrCaselessCompare()
, TxtCaselessCompare()
, StrCompare()
StrNCat Function
Purpose
Concatenates one string to another clipping the destination string to a maximum of n bytes (including the null character at the end).
IMPORTANT: The Palm OS® implementation of
StrNCat()
differs from the implementation in the standard C library. See the Comments section for details.
Declared In
StringMgr.h
Prototype
char *StrNCat ( char*dst
, const char*src
, size_tn
)
Parameters
-
→ dst
- The null-terminated destination string.
-
→ src
- The source string.
-
→ n
- Maximum length in bytes for
dst
, including the terminating null character.
Returns
Comment
This function differs from the standard C strncat()
function in these ways:
-
StrNCat()
treats the parametern
as the maximum length in bytes fordst
. That means it will copy at mostn –
StrLen(dst
) – 1 bytes fromsrc
. The standard C function always copiesn
bytes fromsrc
intodst
. (It copies the entiresrc
intodst
if the length ofsrc
is less thann
). - If the length of the destination string reaches
n
– 1,StrNCat()
stops copying bytes fromsrc
and appends the terminating null character todst
. If the length of the destination string is already greater than or equal ton
– 1 before the copying begins,StrNCat()
does not copy any data fromsrc
. - In the standard C function, if
src
is less thann
, the entiresrc
string is copied intodst
and then the remaining space is filled with null characters.StrNCat()
does not fill the remaining space with null characters in released ROMs. In debug ROMs,StrNCat()
fills the remaining bytes with the value0xFE
.
On systems with multi-byte character encodings, this function makes sure that it does not copy part of a multi-byte character. If the last byte copied from src
contains the high-order or middle byte of a multi-byte character, StrNCat()
backs up in dst
until the byte after the end of the previous character, and replaces that byte with a null character.
StrNCompare Function
Purpose
Compares two strings out to n bytes. This function is case and accent sensitive.
Declared In
StringMgr.h
Prototype
int16_t StrNCompare ( const char*s1
, const char*s2
, size_tn
)
Parameters
Returns
Comments
StrNCompare()
correctly performs locale-specific sorting and handles strings with multi-byte characters, whereas the standard C library function strncmp()
does not. If the string to be compared will not be visible to the user and does not contain any locale-sensitive data, it is more efficient to use strncmp()
.
This function differs form TxtCompare()
only in that it does not return the length of the matching text.
See Also
StrCompare()
, StrNCaselessCompare()
, StrCaselessCompare()
, TxtCaselessCompare()
, StrNCompareAscii()
StrNCompareAscii Function
Purpose
Compares two ASCII strings out to n bytes. This function calls through to the standard strncmp()
function.
Declared In
StringMgr.h
Prototype
int16_t StrNCompareAscii ( const char*s1
, const char*s2
, size_tn
)
Parameters
Returns
A positive number if s1
sorts after s2
alphabetically.
A negative number if s1
sorts before s2
alphabetically.
StrNCopy Function
Purpose
Copies up to n
bytes from a source string to the destination string. Terminates dst
string at index n
–1 if the source string length was n
–1 or less.
Declared In
StringMgr.h
Prototype
char *StrNCopy ( char*dst
, const char*src
, size_tn
)
Parameters
-
→ dst
- The destination string.
-
→ src
- The source string.
-
→ n
- Maximum number of bytes to copy from
src
string.
Returns
Comments
On systems with multi-byte character encodings, this function makes sure that it does not copy part of a multi-byte character. If the n
th byte of src
contains the high-order or middle byte of a multi-byte character, StrNCopy()
backs up in dst
until the byte after the end of the previous character and replaces the remaining bytes (up to n
–1) with nulls.
Be aware that the n
th byte of dst
upon return may contain the last byte of a multi-byte character. If you plan to terminate the string by setting its last character to null, you must not pass the entire length of the string to StrNCopy()
. If you do, your code may overwrite the final byte of the last character.
// WRONG! You may overwrite part of multi-byte // character. char dst[n]; StrNCopy(dst, src, n); dst[n-1] = chrNull;
Instead, if you write to the last byte of the destination string, pass one less than the size of the string to StrNCopy()
.
// RIGHT. Instead pass n-1 to StrNCopy. char dst[n]; StrNCopy(dst, src, n-1); dst[n-1] = chrNull;
StrPrintFV50 Function
Purpose
Implements a subset of the standard C sprintf()
call, which writes formatted output to a string.
Declared In
StringMgr.h
Prototype
int16_t StrPrintFV50 ( char*s
, const char *formatStr
, ... )
Parameters
-
← s
- A string into which the results are written.
-
→ formatStr
- The format specification string.
-
...
- Zero or more arguments to be formatted as specified by
formatStr
.
Returns
Number of characters written to destination string. Returns a negative number if there is an error.
Comments
This function internally calls StrVPrintFV50()
to do the formatting. See that function's description for details on which format specifications are supported.
Compatibility
This function is obsolete and provided for backward compatibility only. Use the standard C library function sprintf()
instead.
See Also
StrStr Function
Purpose
Looks for a substring within a string.
Declared In
StringMgr.h
Prototype
char *StrStr ( const char*str
, const char*token
)
Parameters
Returns
A pointer to the first occurrence of token
in str
or NULL
if not found.
Comments
Use this function instead of the standard strstr()
function to handle multi-byte character strings. This function makes sure that it does not match only part of a multi-byte character. If the matching strings begins at an inter-character boundary, then this function returns NULL
.
NOTE: If the value of the
token
parameter is the empty string, this function returns NULL
. This is different than the standard strstr()
function, which returns str
when token
is the empty string.
See Also
StrToLower Function
Purpose
Converts all the characters in a string to lowercase.
Declared In
StringMgr.h
Prototype
char *StrToLower ( char*dst
, const char*src
)
Parameters
Returns
StrVPrintFV50 Function
Purpose
Implements a subset of the standard C vsprintf()
call, which writes formatted output to a string.
Declared In
StringMgr.h
Prototype
int16_t StrVPrintFV50 ( char*s
, const char*formatStr
, _Palm_va_listarg
)
Parameters
-
← s
- A string into which the results are written. This string is always terminated by a null terminator.
-
→ formatStr
- The format specification string.
-
→ arg
- Pointer to a list of zero or more parameters to be formatted as specified by the
formatStr
string.
Returns
Number of characters written to destination string, not including the null terminator. Returns a negative number if there is an error.
Comments
Like the C vsprintf()
function, this function is designed to be called by your own function that takes a variable number of arguments and passes them to this function.
Currently, only the conversion specifications %d
, %i
, %u
, %x
, %s
, and %c
are implemented by StrVPrintF()
(and related functions). Optional modifiers that are supported include: +
, -
, <space>, *
, <digits>, h
and l
(long). Refer to a C reference book for more details on how these conversion specifications work.
Compatibility
This function is obsolete and provided for backward compatibility only. Use the standard C library function vsprintf()
instead.
Example
The following code sample shows how to use this call:
#include <unix_stdarg.h> void MyPrintF(char *s, char *formatStr, ...) { va_list args; char text[0x100]; va_start(args, formatStr); StrVPrintFV50(text, formatStr, args); va_end(args); MyPutS(text); }