Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

7    String Manager

Text and Localization

Exploring Palm OS®

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 ^TOP^

String Manager Constants ^TOP^

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 function sprintf(). If you need to ensure the old functionality, use StrPrintFV50().
#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, use StrVPrintFV50().

String Manager Functions and Macros ^TOP^

StrAToI Function ^TOP^

Purpose

Converts a string to an integer.

Declared In

StringMgr.h

Prototype

int32_t StrAToI (
   const char *str
)

Parameters

str
A string to convert.

Returns

The integer.

StrCaselessCompare Function ^TOP^

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

s1
A string.
s2
A string.

Returns

0 if the strings match.

A positive number if s1 > s2.

A negative number if s1 < s2.

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 ^TOP^

Purpose

Concatenates one null-terminated string to another.

Declared In

StringMgr.h

Prototype

char *StrCat (
   char *dst,
   const char *src
)

Parameters

dst
The null-terminated destination string.
src
The null-terminated source string.

Returns

The destination string.

Comments

This function calls through to the standard strcat() function.

StrChr Function ^TOP^

Purpose

Looks for a character within a string.

Declared In

StringMgr.h

Prototype

char *StrChr (
   const char *str,
   wchar32_t chr
)

Parameters

str
The string to be searched.
chr
The character to search for.

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

StrStr()

StrCompare Function ^TOP^

Purpose

Case-sensitive comparison of two strings.

Declared In

StringMgr.h

Prototype

int16_t StrCompare (
   const char *s1,
   const char *s2
)

Parameters

s1
A string.
s2
Another string.

Returns

0 if the strings match.

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 ^TOP^

Purpose

Compares two ASCII strings.

Declared In

StringMgr.h

Prototype

int16_t StrCompareAscii (
   const char *s1,
   const char *s2
)

Parameters

s1
A string.
s2
Another string.

Returns

0 if the strings match.

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 ^TOP^

Purpose

Copies one string to another.

Declared In

StringMgr.h

Prototype

char *StrCopy (
   char *dst,
   const char *src
)

Parameters

dst
The destination string.
src
The source string.

Returns

The destination string.

Comments

This function calls through to the standard strcpy() function. It does not work properly with overlapping strings.

StrDelocalizeNumber Function ^TOP^

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,
   char thousandSeparator,
   char decimalSeparator
)

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 ^TOP^

Purpose

Converts an integer to ASCII.

Declared In

StringMgr.h

Prototype

char *StrIToA (
   char *s,
   int32_t i
)

Parameters

s
A string of length maxStrIToALen+1 in which to store the results.
i
Integer to convert.

Returns

The result string.

See Also

StrAToI(), StrIToH()

StrIToH Function ^TOP^

Purpose

Converts an integer to hexadecimal ASCII.

Declared In

StringMgr.h

Prototype

char *StrIToH (
   char *s,
   uint32_t i
)

Parameters

s
A string in which to store the results.
i
Integer to convert.

Returns

The string s.

See Also

StrIToA()

StrLCat Function ^TOP^

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_t siz
)

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

StrNCat(), StrCat()

StrLCopy Function ^TOP^

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_t siz
)

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

StrCopy(), StrNCopy()

StrLen Function ^TOP^

Purpose

Computes the length of a string.

Declared In

StringMgr.h

Prototype

size_t StrLen (
   const char *src
)

Parameters

src
A string.

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 ^TOP^

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,
   char thousandSeparator,
   char decimalSeparator
)

Parameters

s
Numeric ASCII string to localize. Upon return, contains the same string with all occurrences of "," replaced by thousandSeparator and all occurrences of "." with decimalSeparator.
thousandSeparator
Localized thousand separator.
decimalSeparator
Localized decimal separator.

Returns

The changed string.

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

StrDelocalizeNumber()

StrNCaselessCompare Function ^TOP^

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_t n
)

Parameters

s1
The first string.
s2
The second string.
n
Length in bytes of the text to compare.

Returns

0 if the strings match.

A positive number if s1 > s2.

A negative number if s1 < s2.

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 ^TOP^

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_t n
)

Parameters

dst
The null-terminated destination string.
src
The source string.
n
Maximum length in bytes for dst, including the terminating null character.

Returns

The destination string.

Comment

This function differs from the standard C strncat() function in these ways:

  • StrNCat() treats the parameter n as the maximum length in bytes for dst. That means it will copy at most n – StrLen(dst) – 1 bytes from src. The standard C function always copies n bytes from src into dst. (It copies the entire src into dst if the length of src is less than n).
  • If the length of the destination string reaches n – 1, StrNCat() stops copying bytes from src and appends the terminating null character to dst. If the length of the destination string is already greater than or equal to n – 1 before the copying begins, StrNCat() does not copy any data from src.
  • In the standard C function, if src is less than n, the entire src string is copied into dst 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 value 0xFE.

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 ^TOP^

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_t n
)

Parameters

s1
A string.
s2
A string.
n
Length in bytes of text to compare.

Returns

0 if the strings match.

A positive number if s1 > s2.

A negative number if s1 < s2.

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 ^TOP^

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_t n
)

Parameters

s1
A string.
s2
A string.
n
Length in bytes of text to compare.

Returns

0 if the strings match.

A positive number if s1 sorts after s2 alphabetically.

A negative number if s1 sorts before s2 alphabetically.

StrNCopy Function ^TOP^

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_t n
)

Parameters

dst
The destination string.
src
The source string.
n
Maximum number of bytes to copy from src string.

Returns

The destination string.

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 nth 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 nth 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 ^TOP^

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

StrVPrintFV50()

StrStr Function ^TOP^

Purpose

Looks for a substring within a string.

Declared In

StringMgr.h

Prototype

char *StrStr (
   const char *str,
   const char *token
)

Parameters

str
The string to be searched.
token
The string to search for.

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

StrChr()

StrToLower Function ^TOP^

Purpose

Converts all the characters in a string to lowercase.

Declared In

StringMgr.h

Prototype

char *StrToLower (
   char *dst,
   const char *src
)

Parameters

dst
A string.
src
A null-terminated string.

Returns

The destination string.

StrVPrintFV50 Function ^TOP^

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_list arg
)

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); 
} 

See Also

StrPrintFV50()