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

52    String Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 Chapter 8, "Text," of the Palm OS Programmer's Companion, vol. I.

String Manager Functions ^TOP^

StrAToI Function ^TOP^

Purpose

Convert a string to an integer.

Declared In

StringMgr.h

Prototype 

Int32 StrAToI (
   const Char *str
)

Parameters

→ str
Pointer to a string to convert.

Returns

Returns the integer.

Comments

Use this function instead of the standard atoi routine.

StrCaselessCompare Function ^TOP^

Purpose

Compare two strings with case and accent insensitivity.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ s1
Pointer to a string.
→ s2
Pointer to a string.

Returns

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

Purpose

Concatenate one null-terminated string to another.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ dst
Pointer to the null-terminated destination string.
→ src
Pointer to the null-terminated source string.

Returns

Returns a pointer to the destination string.

Comments

Use this function instead of the standard strcat routine.

StrChr Function ^TOP^

Purpose

Look for a character within a string.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ str
Pointer to the string to be searched.
→ chr
Character to search for.

Returns

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

Purpose

Compare two strings.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ s1
Pointer to a string.
→ s2
Pointer to a string.

Returns

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()

StrCompareAscii Function ^TOP^

Purpose

Compare two ASCII strings.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ s1
Pointer to a string.
→ s2
Pointer to a string.

Returns

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

Purpose

Copy one string to another.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ dst
Pointer to the destination string.
→ src
Pointer to the source string.

Returns

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

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.

Declared In

StringMgr.h

Prototype 

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

Parameters

↔ s
Pointer to the number as an ASCII string.
→ thousandSeparator
Current thousand separator.
→ decimalSeparator
Current decimal separator.

Returns

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

Purpose

Convert an integer to ASCII.

Declared In

StringMgr.h

Prototype 

Char *StrIToA (
   Char *s,
   Int32 i
)

Parameters

← s
Pointer to a string of size maxStrIToALen in which to store the results.
→ i
Integer to convert.

Returns

Returns a pointer to the result string.

See Also

StrAToI(), StrIToH()

StrIToH Function ^TOP^

Purpose

Convert an integer to hexadecimal ASCII.

Declared In

StringMgr.h

Prototype 

Char *StrIToH (
   Char *s,
   UInt32 i
)

Parameters

← s
Pointer to a string in which to store the results.
→ i
Integer to convert.

Returns

Returns the string pointer s.

See Also

StrIToA()

StrLen Function ^TOP^

Purpose

Compute the length of a string.

Declared In

StringMgr.h

Prototype 

UInt16 StrLen (
   const Char *src
)

Parameters

→ src
Pointer to a string.

Returns

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.

Compatibility

In Palm OS 3.5 and Palm OS 4.x this function was declared to return an Int16. In Palm OS Garnet, and prior to Palm OS 3.5, this function returns a UInt16.

StrLocalizeNumber Function ^TOP^

Purpose

Convert 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.
→ thousandSeparator
Localized thousand separator.
→ decimalSeparator
Localized decimal separator.

Returns

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

Purpose

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

Declared In

StringMgr.h

Prototype 

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

Parameters

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

Returns

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 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,
   Int16 n
)

Parameters

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

Returns

Returns a pointer to the destination string.

Comments

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

Purpose

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

Declared In

StringMgr.h

Prototype 

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

Parameters

→ s1
Pointer to a string.
→ s2
Pointer to a string.
→ n
Length in bytes of text to compare.

Returns

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()

StrNCompareAscii Function ^TOP^

Purpose

Compare two ASCII strings out to n bytes.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ s1
Pointer to a string.
→ s2
Pointer to a string.
→ n
Length in bytes of text to compare.

Returns

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 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,
   Int16 n
)

Parameters

→ dst
Pointer to the destination string.
→ src
Pointer to the source string.
→ n
Maximum number of bytes to copy from src string.

Returns

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

Purpose

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

Declared In

StringMgr.h

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.

Returns

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's description—specifically, Table 52.1—for details on which format specifications are supported.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrVPrintF()

StrStr Function ^TOP^

Purpose

Look for a substring within a string.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ str
Pointer to the string to be searched.
→ token
Pointer to the string to search for.

Returns

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

Purpose

Convert all the characters in a string to lowercase.

Declared In

StringMgr.h

Prototype 

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

Parameters

→ dst
Pointer to a string.
→ src
Pointer to a null-terminated string.

Returns

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

Purpose

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

Declared In

StringMgr.h

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.
→ 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. For details on how to use it, see "Using the StrVPrintF Function" of the 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 52.1, in sequence.

Table 52.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()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


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