String Manager
 

 < Home   < Developers   < Development Support   < Documentation

48 String Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

48 String Manager

String Manager Functions

StrAToI

StrCaselessCompare

StrCat

StrChr

StrCompare

StrCompareAscii

StrCopy

StrDelocalizeNumber

StrIToA

StrIToH

StrLen

StrLocalizeNumber

StrNCaselessCompare

StrNCat

StrNCompare

StrNCompareAscii

StrNCopy

StrPrintF

StrStr

StrToLower

StrVPrintF

       

This chapter provides reference material for the string manager. The string manager API is declared in the header file StringMgr.h.

For more information, see the section "Text" in the Palm OS Programmer's Companion, vol. I.

String Manager Functions

StrAToI

Purpose

Convert a string to an integer.

Prototype

Int32 StrAToI (const Char *str)

Parameters

-> strPointer to a string to convert.

Result

Returns the integer.

Comments

Use this function instead of the standard atoi routine.

StrCaselessCompare

Purpose

Compare two strings with case and accent insensitivity.

Prototype

Int16 StrCaselessCompare (const Char *s1, const Char *s2)

Parameters

-> s1Pointer to a string.
-> s2Pointer to a string.

Result

Returns 0 if the strings match.

Returns a positive number if s1 > s2.

Returns a negative number if s1 < s2.

Comments

Use this function instead of the standard stricmp routine.

To support systems that use multi-byte character encodings, consider using TxtCaselessCompare instead of this function (or TxtCompare for a case-sensitive comparison). Both functions can match single-byte characters with their multi-byte equivalents, but TxtCaselessCompare can also return the length of the matching text.

See Also

StrNCaselessCompare, TxtCaselessCompare, StrCompare, StrNCompare

StrCat

Purpose

Concatenate one null-terminated string to another.

Prototype

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

Parameters

-> dstPointer to the null-terminated destination string.
-> srcPointer to the null-terminated source string.

Result

Returns a pointer to the destination string.

Comments

Use this function instead of the standard strcat routine.

StrChr

Purpose

Look for a character within a string.

Prototype

Char *StrChr (const Char *str, WChar chr)

Parameters

-> strPointer to the string to be searched.
-> chrCharacter to search for.

Result

Returns a pointer to the first occurrence of character in str. Returns NULL if the character is not found.

Comments

Use this function instead of the standard strchr routine.

This function can handle both single-byte characters and multi-byte characters correctly. However, you should make sure that you pass a WChar variable to StrChr instead of a Char. If you pass a Char variable, the function sign-extends the variable to a WChar, which causes problems if the value is 0x80 or higher.

Compatibility

This routine does not correctly find a '\0' character on Palm OS® version 1.0.

See Also

StrStr

StrCompare

Purpose

Compare two strings.

Prototype

Int16 StrCompare (const Char *s1, const Char *s2)

Parameters

-> s1Pointer to a string.
-> s2Pointer to a string.

Result

Returns 0 if the strings match.

Returns a positive number if s1 sorts after s2 alphabetically.

Returns a negative number if s1 sorts before s2 alphabetically.

Comments

Use this function or StrCompareAscii instead of the standard strcmp routine. This function is case sensitive.

To support systems that use multi-byte character encodings, consider using TxtCompare instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but TxtCompare can also return the length of the matching text.

Compatibility

Prior to Palm OS 4.0, StrCompare and TxtCompare only performed one level of comparison and returned as soon as they found two unequal characters. For example, if you compared the string "celery" with the string "Cauliflower," both functions returned a value indicating that "celery" should appear before "Cauliflower" because they sorted "c" before "C."

In Palm OS 4.0, StrCompare calls TxtCompare, and TxtCompare performs a comparison using up to six comparison tables for sorting with increasing precision. As a result, in Palm OS 4.0 and higher, StrCompare sorts "Cauliflower" before "celery."

See Also

StrNCompare, StrNCaselessCompare, TxtCaselessCompare

New StrCompareAscii

Purpose

Compare two ASCII strings.

Prototype

Int16 StrCompareAscii (const Char *s1, const Char *s2)

Parameters

-> s1Pointer to a string.
-> s2Pointer to a string.

Result

Returns 0 if the strings match.

Returns a positive number if s1 sorts after s2 alphabetically.

Returns a negative number if s1 sorts before s2 alphabetically.

Comments

Use this function instead of the standard strcmp routine. Use it to do case-sensitive comparisons on strings that are guaranteed to be 7-bit ASCII strings. This function performs a fast, simple byte-to-byte comparison that is guaranteed never to change.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

StrCompare, StrNCompare, TxtCompare, StrCaselessCompare, StrNCaselessCompare, TxtCaselessCompare, StrNCompareAscii

StrCopy

Purpose

Copy one string to another.

Prototype

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

Parameters

-> dstPointer to the destination string.
-> srcPointer to the source string.

Result

Returns a pointer to the destination string.

Comments

Use this function instead of the standard strcpy routine.

This function does not work properly with overlapping strings.

StrDelocalizeNumber

Purpose

Delocalize a number passed in as a string. Convert the number from any localized notation to US notation (decimal point and thousandth comma). The current thousand and decimal separators have to be passed in.

Prototype

Char *StrDelocalizeNumber (Char *s, Char thousandSeparator, Char decimalSeparator)

Parameters

<-> sPointer to the number as an ASCII string.
-> thousandSeparatorCurrent thousand separator.
-> decimalSeparatorCurrent decimal separator.

Result

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 LocGetNumberSeparators. For example:

Char *localizedNum; 
NumberFormatType numFormat; 
Char thousandsSeparator, decimalSeparator; 
  
numFormat = (NumberFormatType) 
  PrefGetPreference(prefNumberFormat); 
LocGetNumberSeparators(numFormat, 
  &thousandsSeparator, &decimalSeparator); 
StrDelocalizeNumber(localizedNum,  
  thousandsSeparator, decimalSeparator);  

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrLocalizeNumber, LocGetNumberSeparators

StrIToA

Purpose

Convert an integer to ASCII.

Prototype

Char *StrIToA (Char *s, Int32 i)

Parameters

<- sPointer to a string of size maxStrIToALen in which to store the results.
-> iInteger to convert.

Result

Returns a pointer to the result string.

See Also

StrAToI, StrIToH

StrIToH

Purpose

Convert an integer to hexadecimal ASCII.

Prototype

Char *StrIToH (Char *s, UInt32 i)

Parameters

<- sPointer to a string in which to store the results.
-> iInteger to convert.

Result

Returns the string pointer s.

See Also

StrIToA

StrLen

Purpose

Compute the length of a string.

Prototype

Int16 StrLen (const Char *src)

Parameters

-> srcPointer to a string.

Result

Returns the length of the string in bytes.

Comments

Use this function instead of the standard strlen routine.

This function returns the length of the string in bytes. On systems that support multi-byte characters, the number returned does not always equal the number of characters.

StrLocalizeNumber

Purpose

Convert a number (passed in as a string) to localized format, using a specified thousands separator and decimal separator.

Prototype

Char *StrLocalizeNumber (Char *s, Char thousandSeparator, Char decimalSeparator)

Parameters

<-> sNumeric ASCII string to localize.
-> thousandSeparatorLocalized thousand separator.
-> decimalSeparatorLocalized decimal separator.

Result

Returns a pointer to the changed number. Converts the number string in s by replacing all occurrences of "," with thousandSeparator and all occurrences of "." with decimalSeparator.

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 LocGetNumberSeparators. For example:

Char *localizedNum; 
NumberFormatType numFormat; 
Char thousandsSeparator, decimalSeparator; 
  
numFormat = (NumberFormatType) 
  PrefGetPreference(prefNumberFormat); 
LocGetNumberSeparators(numFormat, 
  &thousandsSeparator, &decimalSeparator); 
StrLocalizeNumber(localizedNum,  
  thousandsSeparator, decimalSeparator);  

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrDelocalizeNumber

StrNCaselessCompare

Purpose

Compares two strings out to n characters with case and accent insensitivity.

Prototype

Int16 StrNCaselessCompare (const Char *s1, const Char *s2, Int32 n)

Parameters

-> s1Pointer to the first string.
-> s2 Pointer to the second string.
-> nLength in bytes of the text to compare.

Result

Returns 0 if the strings match.

Returns a positive number if s1 > s2.

Returns a negative number if s1 < s2.

Comments

To support systems that use multi-byte character encodings, consider using TxtCaselessCompare instead of this function (or TxtCompare for a case-sensitive comparison). Both functions can match single-byte characters with their multi-byte equivalents, but TxtCaselessCompare can also return the length of the matching text.

Compatibility

Implemented only if 2.0 New Feature Set is present. As of Palm OS 4.0, both s1 and s2 must be null-terminated strings.

See Also

StrNCompare, StrCaselessCompare, TxtCaselessCompare, StrCompare

StrNCat

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.

Prototype

Char *StrNCat (Char *dst, const Char *src, Int16 n)

Parameters

-> dstPointer to the null-terminated destination string.
-> srcPointer to the source string.
-> nMaximum length in bytes for dst, including the terminating null character.

Result

Returns a pointer to 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.

Compatibility

Implemented only if 2.0 New Feature Set is present.

StrNCompare

Purpose

Compare two strings out to n bytes. This function is case and accent sensitive.

Prototype

Int16 StrNCompare (const Char *s1, const Char *s2, Int32 n)

Parameters

-> s1Pointer to a string.
-> s2Pointer to a string.
-> nLength in bytes of text to compare.

Result

Returns 0 if the strings match.

Returns a positive number if s1 > s2.

Returns a negative number if s1 < s2.

Comments

To support systems that use multi-byte character encodings, consider using TxtCompare instead of this function. Both functions can match single-byte characters with their multi-byte equivalents, but TxtCompare can also return the length of the matching text.

Compatibility

Implemented only if 2.0 New Feature Set is present. As of Palm OS 4.0, both s1 and s2 must be null-terminated strings.

See Also

StrCompare, StrNCaselessCompare, StrCaselessCompare, TxtCaselessCompare, StrNCompareAscii

New StrNCompareAscii

Purpose

Compare two ASCII strings out to n bytes.

Prototype

Int16 StrNCompareAscii (const Char *s1, const Char *s2, Int32 n)

Parameters

-> s1Pointer to a string.
-> s2Pointer to a string.
-> nLength in bytes of text to compare.

Result

Returns 0 if the strings match.

Returns a positive number if s1 sorts after s2 alphabetically.

Returns a negative number if s1 sorts before s2 alphabetically.

Comments

Use this function instead of the standard strncmp routine. Use it to do case-sensitive comparisons on strings that are guaranteed to be 7-bit ASCII strings. This function performs a fast, simple byte-to-byte comparison that is guaranteed never to change.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

StrCompare, StrNCompare, TxtCompare, StrCaselessCompare, StrNCaselessCompare, TxtCaselessCompare, StrCompareAscii

StrNCopy

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.

Prototype

Char *StrNCopy (Char *dst, const Char *src, Int16 n)

Parameters

-> dstPointer to the destination string.
-> srcPointer to the source string.
-> nMaximum number of bytes to copy from src string.

Result

Returns nothing.

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; 

Compatibility

Implemented only if 2.0 New Feature Set is present.

StrPrintF

Purpose

Implements a subset of the ANSI C sprintf call, which writes formatted output to a string.

Prototype

Int16 StrPrintF (Char *s, const Char *formatStr, ...)

Parameters

-> s Pointer to a string into which the results are written.
-> formatStr Pointer to the format specification string.
...Zero or more arguments to be formatted as specified by formatStr.

Result

Number of characters written to destination string. Returns a negative number if there is an error.

Comments

This function internally calls StrVPrintF to do the formatting. See that function for details on which format specifications are supported.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrVPrintF

StrStr

Purpose

Look for a substring within a string.

Prototype

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

Parameters

-> strPointer to the string to be searched.
-> tokenPointer to the string to search for.

Result

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 routine.

On systems with multi-byte character encodings, 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

Purpose

Convert all the characters in a string to lowercase.

Prototype

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

Parameters

-> dstPointer to a string.
-> srcPointer to a null-terminated string.

Result

Returns a pointer to the destination string.

Compatibility

Prior to Palm OS version 3.5, this function only converted accented characters on Japanese devices. On Palm OS version 3.5 and higher, all characters are appropriately lowercased, including accented characters on Latin devices.

StrVPrintF

Purpose

Implements a subset of the ANSI C vsprintf call, which writes formatted output to a string.

Prototype

Int16 StrVPrintF (Char *s, const Char *formatStr, va_list arg)

Parameters

<- s Pointer to a string into which the results are written. This string is always terminated by a null terminator.
-> formatStr Pointer to the format specification string.
-> argPointer to a list of zero or more parameters to be formatted as specified by the formatStr string.

Result

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. For details on how to use it, see "Using the StrVPrintF Function" in Palm OS Programmer's Companion, vol. I, or refer to vsprintf in a standard C reference book.

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). Following is a brief description of how these format specifications work (see a C book for more details).

Each conversion specification begins with the % character. Following the % character, there may be one or more of the characters list in Table 48.1, in sequence.

Table 48.1 StrVPrintF Format Specification 
Character

Description
+
Specifies that a sign always be placed before a number produced by a signed conversion. A + overrides a space if both are used. Example:
StrPrintF(s,"%+d %+d",4,-5);
Output to s:
+4 -5
-
Specifies that the printed value is left justified within the field width allowed for it. Example:
StrPrintF(s,"%5d%-5d%d",6,9,8);
Output to s:
69 8
<space>
Specifies that a minus sign always be placed before a negative number and a space before a positive number. Example:
StrPrintF(s,"% d % d",4,-5);
Output to s:
4 -5
*
Indicates that the next argument (must be an integer) in the list specifies the field width. In this case, the argument following that one is used for the value of this field. Example:
StrPrintF(s,"%*d%d",4,8,5);
Output to s:
8 5
<number>
Specifies a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left justified flag is also specified) to fill out the field width. Example:
StrPrintF(s,"%d%5d",4,3);
Output to s:
4 3
h
Specifies that the following d, i, u, or x conversion corresponds to a short or unsigned short argument. Example:
StrPrintF(s,"%hd",401);
Output to s:
401
l or L
Specifies that the following d, i, u, x, or c conversion corresponds to a long or unsigned long StrPrintF(s,"%ld",999999999);
Output to s:
999999999
<character>
A character that indicates the type of conversion to be performed. The supported conversion characters include:

d
or
i
A signed integer argument is converted to decimal notation. Example:
StrPrintF(s,"%d %d",4,-4);
Output to s:
4 -4

u
An unsigned integer argument is converted to decimal notation. Example:
StrPrintF(s,"%u %u",4,-4);
Output to s:
4 65532

x
An integer argument is converted to hexadecimal notation. Example:
StrPrintF(s,"%x",125);
Output to s:
0000007D

s
A string (char *) argument is copied to the destination string. Example:
StrPrintF(s,"ABC%s","DEF");
Output to s:
ABCDEF

c or C
A single character argument is copied to the destination string. If C is used or if the l modifier is used, the argument must be a WChar. Example:
StrPrintF(s,"Telephone%c",'s');
Output to s:
Telephones

%
A % character is copied to the destination string. Example:
StrPrintF(s,"%%");
Output to s:
%

Example

Here's an example of 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);
  StrVPrintF(text, formatStr, args);
  va_end(args); 
  MyPutS(text); 
} 

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrPrintF, Using the StrVPrintF Function