|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ResultReturns 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. CommentsUse 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. CompatibilityImplemented only if 4.0 New Feature Set is present. See AlsoStrCompare, StrNCompare, TxtCompare, StrCaselessCompare, StrNCaselessCompare, TxtCaselessCompare, StrNCompareAscii
StrCopy
PurposePrototypeChar *StrCopy (Char *dst, const Char *src) Parameters
ResultReturns a pointer to the destination string. CommentsUse this function instead of the standard strcpy routine. This function does not work properly with overlapping strings.
StrDelocalizeNumber
PurposeDelocalize 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. PrototypeChar *StrDelocalizeNumber (Char *s, Char thousandSeparator, Char decimalSeparator) Parameters
ResultReturns a pointer to the changed number and modifies the string in s. CommentsThe 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); CompatibilityImplemented only if 2.0 New Feature Set is present. See AlsoStrLocalizeNumber, LocGetNumberSeparators
StrIToA
PurposePrototypeChar *StrIToA (Char *s, Int32 i) Parameters
ResultReturns a pointer to the result string. See Also
StrIToH
PurposeConvert an integer to hexadecimal ASCII. PrototypeChar *StrIToH (Char *s, UInt32 i) Parameters
ResultSee Also
StrLen
PurposeCompute the length of a string. PrototypeInt16 StrLen (const Char *src) Parameters
ResultReturns the length of the string in bytes. CommentsUse 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
PurposeConvert a number (passed in as a string) to localized format, using a specified thousands separator and decimal separator. PrototypeChar *StrLocalizeNumber (Char *s, Char thousandSeparator, Char decimalSeparator) Parameters
ResultReturns 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. CommentsThe 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); CompatibilityImplemented only if 2.0 New Feature Set is present. See Also
StrNCaselessCompare
PurposeCompares two strings out to n characters with case and accent insensitivity. PrototypeInt16 StrNCaselessCompare (const Char *s1, const Char *s2, Int32 n) Parameters
ResultReturns 0 if the strings match. Returns a positive number if s1 > s2. Returns a negative number if s1 < s2. CommentsTo 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. CompatibilityImplemented 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 AlsoStrNCompare, StrCaselessCompare, TxtCaselessCompare, StrCompare
StrNCat
PurposeConcatenates 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. PrototypeChar *StrNCat (Char *dst, const Char *src, Int16 n) Parameters
ResultReturns a pointer to the destination string. CommentThis function differs from the standard C strncat function in these ways: 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. CompatibilityImplemented only if 2.0 New Feature Set is present.
StrNCompare
PurposeCompare two strings out to n bytes. This function is case and accent sensitive. PrototypeInt16 StrNCompare (const Char *s1, const Char *s2, Int32 n) Parameters
ResultReturns 0 if the strings match. Returns a positive number if s1 > s2. Returns a negative number if s1 < s2. CommentsTo 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. CompatibilityImplemented 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 AlsoStrCompare, StrNCaselessCompare, StrCaselessCompare, TxtCaselessCompare, StrNCompareAscii
|
-> s1 | Pointer to a string. |
-> s2 | Pointer to a string. |
-> n | Length in bytes of text to compare. |
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.
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.
Implemented only if 4.0 New Feature Set is present.
StrCompare, StrNCompare, TxtCompare, StrCaselessCompare, StrNCaselessCompare, TxtCaselessCompare, StrCompareAscii
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.
Char *StrNCopy (Char *dst, const Char *src, Int16 n)
-> dst | Pointer to the destination string. |
-> src | Pointer to the source string. |
-> n | Maximum number of bytes to copy from src string. |
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;
Implemented only if 2.0 New Feature Set is present.
Implements a subset of the ANSI C sprintf call, which writes formatted output to a string.
Int16 StrPrintF (Char *s, const Char *formatStr, ...)
-> 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. |
Number of characters written to destination string. Returns a negative number if there is an error.
This function internally calls StrVPrintF to do the formatting. See that function for details on which format specifications are supported.
Implemented only if 2.0 New Feature Set is present.
Look for a substring within a string.
Char *StrStr (const Char *str, const Char *token)
-> str | Pointer to the string to be searched. |
-> token | Pointer to the string to search for. |
Returns a pointer to the first occurrence of token in str or NULL if not found.
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.
Convert all the characters in a string to lowercase.
Char *StrToLower (Char *dst, const Char *src)
-> dst | Pointer to a string. |
-> src | Pointer to a null-terminated string. |
Returns a pointer to the destination string.
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.
Implements a subset of the ANSI C vsprintf call, which writes formatted output to a string.
Int16 StrVPrintF (Char *s, const Char *formatStr, va_list arg)
<- 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. |
Number of characters written to destination string, not including the null terminator. Returns a negative number if there is an error.
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.
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); }
Implemented only if 2.0 New Feature Set is present.
StrPrintF, Using the StrVPrintF Function
|