< 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 #####
-> str | Pointer 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 #####
-> s1 | Pointer to a string.
#####
-> s2 | Pointer 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 #####
-> dst | Pointer to the null-terminated destination string.
#####
-> src | Pointer 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 #####
-> str | Pointer to the string to be searched.
#####
-> 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 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 #####
-> s1 | Pointer to a string.
#####
-> s2 | Pointer 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 #####
-> s1 | Pointer to a string.
#####
-> s2 | Pointer 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 #####
-> dst | Pointer to the destination string.
#####
-> src | Pointer 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 #####
<-> 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. #### 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 #####
<- s | Pointer to a string of size maxStrIToALen in which to store the 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 | Pointer to a string in which to store the results.
#####
-> i | Integer 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 #####
-> src | Pointer 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 #####
<-> s | Numeric 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. #### 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 #####
-> s1 | Pointer to the first string.
#####
-> s2 | Pointer to the 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 (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 #####
-> 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.
#### 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 #####
-> s1 | Pointer to a string.
#####
-> s2 | Pointer to a 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. 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 #####
-> s1 | Pointer to a string.
#####
-> s2 | Pointer to a string.
#####
-> n | Length 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 #####
-> dst | Pointer to the destination string.
#####
-> src | Pointer to the 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. 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 #####
-> str | Pointer to the string to be searched.
#####
-> token | Pointer 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 #####
-> dst | Pointer to a string.
#####
-> src | Pointer 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.
#####
-> arg | 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, 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 |