44 String Manager

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 "Text" section in the Palm OS Programmer's Companion.

String Manager Functions

StrAToI

Purpose

Convert a string to an integer.

Prototype

Int32 StrAToI (const Char* str)

Parameters

str

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

s1, s2

Two string pointers.

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. Use it to find strings, or use it with StrCompare to sort strings. (See the comments in StrCompare for a example code.)

To support systems that use multi-byte character encodings, consider using TxtCaselessCompare instead of this function. 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, TxtCompare

StrCat

Purpose

Concatenate one string to another.

Prototype

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

Parameters

dst

Destination string pointer.

src

Source string pointer.

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

str

String to search.

chr

Character 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 routine does not correctly find a `\0' character on Palm OS^® version 1.0.

This function can handle both single-byte characters and multi-byte characters.

StrChr displays a non-fatal error message if chr is greater than 0xFF.

See Also

StrStr

StrCompare

Purpose

Compare two strings.

Prototype

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

Parameters

s1, s2

Two string pointers.

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.

This function is case sensitive. Use it to sort strings but not to find them.

This function performs a character-by-character comparison of s1 and s2 and returns as soon as it finds two unequal characters. For example, if you are comparing the string "celery" with the string "Cauliflower," StrCompare returns that "celery" should appear before "Cauliflower" because it sorts the letter "c" before "C."

If you need to perform a true alphabetical sort, use StrCaselessCompare before using StrCompare, as in the following code:

Int16 result = StrCaselessCompare(a, b);

if (result == 0)
    result = StrCompare(a, b);
return(result);

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.

See Also

StrNCompare, TxtCompare, StrCaselessCompare, StrNCaselessCompare, TxtCaselessCompare

StrCopy

Purpose

Copy one string to another.

Prototype

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

Parameters

dst, src

Two string pointers.

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

s

Pointer to the number as an ASCII string.

thousandSeparator

Current thousand separator.

decimalSeparator

Current decimal separator.

Result

Returns a pointer to the changed number and modifies the string in s.

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

s

String pointer to store results.

i

Integer 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

s

String pointer to store results.

i

Integer to convert.

Result

Returns the string pointer s.

See Also

StrIToA

StrLen

Purpose

Compute the length of a string.

Prototype

UInt16 StrLen (const Char* src)

Parameters

src

String pointer

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

s

Number ASCII string to localize.

thousandSeparator

Localized thousand separator.

decimalSeparator

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

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

s1

Pointer to first string.

s2

Pointer to second string.

n

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

See Also

StrNCompare, StrCaselessCompare, TxtCaselessCompare, StrCompare, TxtCompare

StrNCat

Purpose

Concatenates one string to another clipping the destination string to a maximum of n bytes (including the null character at the end).

Prototype

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

Parameters

dst

Pointer to destination string.

src

Pointer to source string.

n

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

Compatibility

Implemented only if 2.0 New Feature Set is present.

StrNCompare

Purpose

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

Prototype

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

Parameters

s1

Pointer to first string.

s2

Pointer to second string.

n

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

See Also

StrCompare, TxtCompare, StrNCaselessCompare, StrCaselessCompare, TxtCaselessCompare

StrNCopy

Purpose

Copies up to n characters 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

dst

Destination string.

src

Source string.

n

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

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 where 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

str

String to search.

token

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.

See Also

StrChr

StrToLower

Purpose

Convert all the characters in a string to lowercase.

Prototype

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

Parameters

dst, src

Two string pointers.

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, _Palm_va_list argParam)

Parameters

s

Pointer to a string where the results are written. This string is always terminated by a null terminator.

formatStr

Pointer to the format specification string.

argParam

Pointer 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, 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 44.1, in sequence.

Table 44.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, or x 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	A single character (int) argument is copied to the destination string. 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 <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