String Utility
This chapter describes APIs of the utility for string processing.
1. Overview
Strings can be divided into two types: null-terminated strings and fixed-length strings.
-
Null-terminated strings
-
Have a variable length.
-
Ignore characters after a null character ('\0').
-
Example
{'A', 'B', 'C', 'D', 'E', '\0'} == "ABCDEFG"
-
-
Fixed-length strings
-
Have a fixed length.
-
Recognize only as many characters as a given length. However, if a string includes a null character, only characters before the null character are recognized.
-
Example
[{'A', 'B', 'C', 'D', 'E', '\0'}, 2] == "AB" [{'A', 'B', 'C', '\0', 'D', 'E'}, 6] == "ABC"
-
2. pfmStrIsLower
Checks whether all characters in a null-terminated string are lowercase.
-
Prototype
long pfmStrIsLower(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are lowercase.
FALSE
The string includes a uppercase character, or its length is 0.
-
Example
rc = pfmStrIsLower(" abcDEF 1. 23hljk "); /* rc == FALSE */ rc = pfmStrIsLower(" abcdef 1. 23hljk "); /* rc == TRUE */ rc = pfmStrIsLower(""); /* rc == FALSE */
3. pfmStrnIsLower
Checks whether all characters in a fixed-length string are lowercase.
-
Prototype
long pfmStrnIsLower(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are lowercase.
FALSE
The string includes a uppercase character, or its length is 0.
-
Example
/* strlen("abcDEF") == 6 */ rc = pfmStrnIsLower("abcDEF", 1); /* rc == TRUE */ rc = pfmStrnIsLower("abcDEF", 3); /* rc == TRUE */ rc = pfmStrnIsLower("abcDEF", 4); /* rc == FALSE */ rc = pfmStrnIsLower("abcDEF", 6); /* rc == FALSE */ rc = pfmStrnIsLower("abcDEF", 7); /* null position */ /* rc == FALSE */ rc = pfmStrnIsLower("abcDEF", 8); /* after null position */ /* rc == FALSE */ rc = pfmStrnIsLower("", 8); /* rc == FALSE */
4. pfmStrIsUpper
Checks whether all characters in a null-terminated string are uppercase.
-
Prototype
long pfmStrIsUpper(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are uppercase.
FALSE
The string includes a lowercase character.
-
Example
rc = pfmStrIsUpper(" abcDEF 1. 23hljk "); /* rc == FALSE */ rc = pfmStrIsUpper(" abcdef 1. 23hljk "); /* rc == TRUE */ rc = pfmStrIsUpper(""); /* rc == FALSE */
5. pfmStrnIsUpper
Checks whether all characters in a fixed-length string are uppercase.
-
Prototype
long pfmStrnIsUpper(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are uppercase.
FALSE
The string includes a lowercase character, or its first character is null.
-
Example
/* strlen("ABCdef") == 6 */ rc = pfmStrnIsUpper("ABCdef", 1); /* rc == TRUE */ rc = pfmStrnIsUpper("ABCdef", 3); /* rc == TRUE */ rc = pfmStrnIsUpper("ABCdef", 4); /* rc == FALSE */ rc = pfmStrnIsUpper("ABCdef", 6); /* rc == FALSE */ rc = pfmStrnIsUpper("ABCdef", 7); /* null position */ /* rc == FALSE */ rc = pfmStrnIsUpper("ABCdef", 8); /* after null position */ /* rc == FALSE */ rc = pfmStrnIsUpper("", 8); /* rc == FALSE */
6. pfmStrIsAlpha
Checks whether all characters in a null-terminated string are alphabet.
-
Prototype
long pfmStrIsAlpha(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are alphabet.
FALSE
The string includes a chatacter that is not alphabet, or its first character is null.
-
Example
char MIXED_STR[] = " abcDEF @#$! 1. 23hljk "; char ALPHA_ONLY[] = "abcDEF"; char ALPHA_SPACE[] = " ab cDef " char ALPHA_RSPACE[] = "abcDef " char ALPHA_NUM[] = "abcDEF123hljk" rc = pfmStrIsAlpha(MIXED_STR); /* rc == FALSE */ rc = pfmStrIsAlpha(ALPHA_ONLY); /* rc == TRUE */ rc = pfmStringIsAlphabetic(ALPHA_SPACE); /* rc == FALSE */ rc = pfmStrIsAlpha(ALPHA_RSPACE); /* rc == FALSE */ rc = pfmStrIsAlpha(ALPHA_NUM); /* rc == FALSE */ rc = pfmStrIsAlpha(""); /* rc == FALSE */
7. pfmStrnIsAlpha
Checks whether all characters in a fixed-length string are alphabet.
-
Prototype
long pfmStrnIsAlpha(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are alphabet.
FALSE
The string includes a chatacter that is not alphabet, or its first character is null.
-
Example
char MIXED_STR[] = " abcDEF @#$! 1. 23hljk "; char ALPHA_ONLY[] = "abcDEF"; char ALPHA_RSPACE[] = "abcDef " char ALPHA_NUM[] = "abcDEF123hljk" rc = pfmStrnIsAlpha(MIXED_STR, (int)strlen(MIXED_STR)); /* rc == FALSE */ rc = pfmStrnIsAlpha(ALPHA_ONLY, (int)strlen(ALPHA_ONLY)); /* rc == TRUE */ rc = pfmStrnIsAlpha(ALPHA_ONLY, (int)strlen(ALPHA_ONLY) + 1000); /* rc == TRUE */ rc = pfmStrnIsAlpha(ALPHA_RSPACE, 5); /* rc == TRUE */ rc = pfmStrnIsAlpha(ALPHA_NUM, 10); /* null position */ /* rc == FALSE */ rc = pfmStrnIsAlpha(ALPHA_NUM, 5); /* after null position */ /* rc == TRUE */ rc = pfmStrnIsAlpha("", 8); /* rc == FALSE */
8. pfmStrIsAlphaNumeric
Checks whether all characters in a null-terminated string are alphabet or digits.
-
Prototype
long pfmStrIsAlphaNumeric(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are alphabet or digits.
FALSE
The string includes a chatacter that is not alphabet or a digit.
-
Example
char MIXED_STR[] = " abcDEF @#$! 1. 23hljk "; char ALPHA_NUM[] = "abcDEF123hljk" rc = pfmStrIsAlphaNumeric(MIXED_STR); /* rc == FALSE */ rc = pfmStrIsAlphaNumeric(ALPHA_NUM); /* rc == TRUE */ rc = pfmStrIsAlphaNumeric(""); /* rc == FALSE */
9. pfmStrnIsAlphaNumeric
Checks whether all characters in a fixed-length string are alphabet or digits.
-
Prototype
long pfmStrnIsAlphaNumeric(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are alphabet or digits.
FALSE
The string includes a chatacter that is not alphabet or a digit.
-
Example
char MIXED_STR[] = " abcDEF @#$! 1. 23hljk "; char ALPHA_NUM[] = "abcDEF123hljk" rc = pfmStrnIsAlphaNumeric(MIXED_STR, (int)strlen(MIXED_STR)); /* rc == FALSE */ rc = pfmStrnIsAlphaNumeric(MIXED_STR, 5); /* rc == FALSE */ rc = pfmStrnIsAlphaNumeric(ALPHA_NUM, (int)strlen(ALPHA_NUM)); /* rc == TRUE */ rc = pfmStrnIsAlphaNumeric(ALPHA_NUM, (int)strlen(ALPHA_NUM) + 1000); /* rc == TRUE */ rc = pfmStrnIsAlphaNumeric("", 8); /* rc == FALSE */
10. pfmStrIsNull
Checks whether the first character of a string is null ('\0').
-
Prototype
long pfmStrIsNull(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
The first character of the string is null ('\0').
FALSE
The first character of the string is not null ('\0').
-
Example
char STR_NULL[] = "\0\0\0\0\0\0" char STR_NULL _ALPHA[] = "\0\0ABC\0\0\0" rc = pfmStrIsNull(STR_NULL); /* rc == TRUE */ rc = pfmStrIsNull(STR_NULL _ALPHA); /* rc == TRUE */ rc = pfmStrIsNull("GH"); /* rc == FALSE */ rc = pfmStrIsNull(""); /* rc == TRUE */
11. pfmStrnIsNull
Checks whether all characters in a string are null ('\0').
-
Prototype
long pfmStrnIsNull(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are null.
FALSE
The string inlcudes a character that is not null.
-
Example
char STR_NULL[] = "\0\0\0\0\0\0" char STR_NULL _ALPHA[] = "\0\0ABC\0\0\0" rc = pfmStrnIsNull(STR_NULL, (int)sizeof(STR_NULL)); /* rc == TRUE */ rc = pfmStrnIsNull(STR_NULL _ALPHA, (int)sizeof(STR_NULL _ALPHA)); /* rc == FALSE */ rc = pfmStrnIsNull("GH", (int)sizeof("GH")); /* rc == FALSE */ rc = pfmStrnIsNull("", 8); /* rc == TRUE */
12. pfmStrIsNumber
Checks whether all characters in a null-terminated string are digits.
-
Prototype
long pfmStrIsNumber(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are digits.
FALSE
The string includes a chatacter that is not a digit.
-
Example
char STR_NUM[] = "0123456789" rc = pfmStrIsNumber(STR_NUM); /* rc == TRUE */ rc = pfmStrIsNumber(""); /* rc == FALSE */
13. pfmStrnIsNumber
Checks whether all characters in a fixed-length string are digits.
-
Prototype
long pfmStrnIsNumber(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are digits.
FALSE
The string includes a chatacter that is not a digit.
-
Example
char STR_NUM[] = "0123456789" rc = pfmStrnIsNumber(STR_NUM, (int)strlen(STR_NUM)); /* rc == TRUE */ rc = pfmStrnIsNumber("", 8); /* rc == FALSE */
14. pfmStrIsSpace
Checks whether all characters in a null-terminated string are spaces.
-
Prototype
long pfmStrIsSpace(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are spaces or null.
FALSE
The string includes a chatacter that is not a space or null.
-
Example
char STR_SPACE[] = " " char STR_SPACE_ALPHA[] = " abc" char STR_ALPHA_SPACE[] = "asdf abc" rc = pfmStrIsSpace(STR_SPACE); /* rc == TRUE */ rc = pfmStrIsSpace(STR_SPACE_ALPHA); /* rc == FALSE */ rc = pfmStrIsSpace(STR_ALPHA_SPACE); /* rc == FALSE */ rc = pfmStrIsSpace(""); /* rc == FALSE */
15. pfmStrnIsSpace
Checks whether all characters in a fixed-length string are spaces.
-
Prototype
long pfmStrnIsSpace(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are spaces or null.
FALSE
The string includes a chatacter that is not a space or null.
-
Example
char STR_SPACE[] = " " char STR_SPACE_ALPHA[] = " abc" rc = pfmStrnIsSpace(STR_SPACE, (int)strlen(STR_SPACE)); /* rc == TRUE */ rc = pfmStrnIsSpace(STR_SPACE_ALPHA, (int)strlen(STR_SPACE)); /* rc == TRUE */ rc = pfmStrnIsSpace(STR_SPACE_ALPHA, (int)strlen(STR_SPACE_ALPHA)); /* rc == FALSE */ rc = pfmStrnIsSpace("", 8); /* rc == FALSE */
16. pfmStrIsSpaceNull
Checks whether all characters in a null-terminated string are spaces or whether the first character is null.
-
Prototype
long pfmStrIsSpaceNull(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are spaces or the first string is null.
FALSE
The string includes a chatacter that is not a space or the first character is not null.
-
Example
char STR_SPACE[] = " " char STR_SPACE_ALPHA[] = " abc" char STR_ALPHA_SPACE[] = "asdf abc" rc = pfmStrIsSpaceNull("\0\0\0"); /* rc == TRUE */ rc = pfmStrIsSpaceNull(STR_SPACE); /* rc == TRUE */ rc = pfmStrIsSpaceNull(STR_SPACE_ALPHA); /* rc == FALSE */ rc = pfmStrIsSpaceNull(STR_ALPHA_SPACE); /* rc == FALSE */ rc = pfmStrIsSpaceNull(""); /* rc == FALSE */
17. pfmStrnIsSpaceNull
Checks whether all characters in a fixed-length string are spaces or whether the first character is null.
-
Prototype
long pfmStrnIsSpaceNull(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are spaces or the first string is null.
FALSE
The string includes a chatacter that is not a space or the first character is not null.
-
Example
char STR_SPACE[] = " " char STR_SPACE_ALPHA[] = " abc" rc = pfmStrnIsSpaceNull("\0\0\0", 3); /* rc == TRUE */ rc = pfmStrnIsSpaceNull(STR_SPACE, (int)strlen(STR_SPACE)); /* rc == TRUE */ rc = pfmStrnIsSpaceNull(STR_SPACE_ALPHA, (int)strlen(STR_SPACE_ALPHA) - 3); /* rc == TRUE */ rc = pfmStrnIsSpaceNull(STR_SPACE_ALPHA, (int)strlen(STR_SPACE_ALPHA)); /* rc == FALSE */ rc = pfmStrnIsSpaceNull("", 8); /* rc == TRUE */
18. pfmStrIsZero
Checks whether all characters in a null-terminated string are 0.
-
Prototype
long pfmStrIsZero(char *str);
-
Parameters
Parameter Description *str (input)
String to check.
-
Return values
Return Value Description TRUE
All characters in the string are 0.
FALSE
The string includes a chatacter that is not 0.
-
Example
rc = pfmStrIsZero("000000000000"); /* rc == TRUE */ rc = pfmStrIsZero(""); /* rc == FALSE */
19. pfmStrnIsZero
Checks whether all characters in a fixed-length string are 0.
-
Prototype
long pfmStrnIsZero(char *str, long len);
-
Parameters
Parameter Description *str (input)
String to check.
len (input)
String length.
-
Return values
Return Value Description TRUE
All characters in the string are 0.
FALSE
The string includes a chatacter that is not 0.
-
Example
rc = pfmStrnIsZero("00000", 5); /* rc == TRUE */ rc = pfmStrnIsZero("000001234", 5); /* rc == TRUE */ rc = pfmStrnIsZero("000001234", 7); /* rc == FALSE */ rc = pfmStrnIsZero("", 8); /* rc == FALSE */
20. pfmStrIsValidDigit
Checks whether a given registration number or corporate registration number is valid.
-
Prototype
long pfmStrIsValidDigit(long fn_code, char *in_str, long str_len);
-
Parameters
Parameter Description fn_code (input)
-
PFM_VALID_DIGIT_CHK_ID_NO: Resident registration number.
-
PFM_VALID_DIGIT_CHK_CMPY_NO: Corporate registration number.
*in_str (input)
String to check.
str_len (input)
Length of in_str.
-
-
Return values
Return Value Description TRUE
The input string is valid.
FALSE
The input string is not valid.
-
Example
rc = pfmStrIsValidDigit (PFM_VALID_DIGIT_CHK_ID_NO, "00000", 5); /* rc == TRUE */
21. pfmStrLTrim
Trims left spaces of a null-terminated string.
-
Prototype
char * pfmStrLTrim(char *str);
-
Parameters
Parameter Description *str (input/output)
String to check.
-
Return values
Returns a pointer to the result string whose left spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_LTRIM[] = "abcDEF 1. 23hljk "; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrLTrim(STR), sizeof(STR)); /* ostr == STR_LTRIM */ strncpy(ostr, pfmStrLTrim(SPACE), sizeof(SPACE)); /* ostr == STR_EMPTY */
22. pfmStrnLTrim
Trims left spaces of a fixed-length string.
-
Prototype
char * pfmStrnLTrim(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to check.
len (input)
String length.
-
Return values
Returns a pointer to the result string whose left spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_LTRIM[] = "abcDEF 1. 23hljk "; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrnLTrim(STR, sizeof(STR)), sizeof(STR)); /* ostr == STR_LTRIM */ strncpy(ostr, pfmStrnLTrim(SPACE, sizeof(SPACE)), sizeof(SPACE)); /* ostr == STR_EMPTY[] */
23. pfmStrRTrim
Trims right spaces of a null-terminated string.
-
Prototype
char * pfmStrRTrim(char *str);
-
Parameters
Parameter Description *str (input/output)
String to check.
-
Return values
Returns a pointer to the result string whose right spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_RTRIM[] = " abcDEF 1. 23hljk"; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrRTrim(STR), sizeof(STR)); /* ostr == STR_RTRIM */ strncpy(ostr, pfmStrRTrim(SPACE), sizeof(SPACE)); /* ostr == STR_EMPTY */
24. pfmStrnRTrim
Trims right spaces of a fixed-length string.
-
Prototype
char * pfmStrnRTrim(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to check.
len (input)
String length.
-
Return values
Returns a pointer to the result string whose right spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_RTRIM[] = " abcDEF 1. 23hljk"; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrnRTrim(STR, sizeof(STR)), sizeof(STR)); /* ostr == STR_RTRIM */ strncpy(ostr, pfmStrnRTrim(SPACE, sizeof(SPACE)), sizeof(SPACE)); /* ostr == STR_EMPTY */
25. pfmStrTrim
Trims left and right spaces of a null-terminated string.
-
Prototype
char * pfmStrTrim(char *str);
-
Parameters
Parameter Description *str (input/output)
String to check.
-
Return values
Returns a pointer to the result string whose left and right spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_TRIM[] = "abcDEF 1. 23hljk"; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrTrim(STR), sizeof(STR)); /* ostr == STR_TRIM */ strncpy(ostr, pfmStrTrim(SPACE), sizeof(SPACE)); /* ostr == STR_EMPTY */
26. pfmStrnTrim
Trims left and right spaces of a fixed-length string.
-
Prototype
char * pfmStrnTrim(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to check.
len (input)
String length.
-
Return values
Returns a pointer to the result string whose left and right spaces are trimmed.
-
Example
char STR[] = " abcDEF 1. 23hljk "; char STR_TRIM[] = "abcDEF 1. 23hljk"; char SPACE[] = " " char STR_EMPTY[] = ""; strncpy(ostr, pfmStrnTrim(STR, sizeof(STR)), sizeof(STR)); /* ostr == STR_TRIM */ strncpy(ostr, pfmStrnTrim(SPACE, sizeof(SPACE)), sizeof(SPACE)); /* ostr == STR_EMPTY */
27. pfmStrRemoveSpace
Removes spaces (0x20) from a null-terminated string.
-
Prototype
char * pfmStrRemoveSpace(char *str);
-
Parameters
Parameter Description *str (input/output)
String to check.
-
Return values
Returns a pointer to the result string whose spaces are removed.
-
Example
char str[] = " A B C "; pfmStrRemoveSpace(str); /* str == "ABC" */
28. pfmStrnRemoveSpace
Removes spaces (0x20) from a fixed-length string.
-
Prototype
char * pfmStrnRemoveSpace(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to check.
len (input)
String length.
-
Return values
Returns a pointer to the result string whose spaces are removed.
-
Example
char str[] = " A B C "; char str2[] = " A B C "; pfmStrnRemoveSpace(str, 10); /* str == "ABC" */ pfmStrnRemoveSpace(str2, 3); /* str2 == "A" */
29. pfmStrCmpLTrim
Trims left spaces of two strings and then compares them.
-
Prototype
long pfmStrCmpLTrim(char *str1, char *str2, long len);
-
Parameters
Parameter Description *str1 (input)
First string to compare.
*str2 (input)
Second string to compare.
len (input)
Length of the part of the strings to compare.
-
Return values
Returns 0 if the two strings whose left spaces are trimmed are the same. Returns a positive number if the two strings whose left spaces are trimmed are not the same and the ASCII value of the first different character in the first string is greater than that in the second string. Returns a negative value if they are not the same and the ASCII value of the first different character in the first string is less than that in the second string.
-
Example
rc = pfmStrCmpLTrim(" TEST", "TEST", 4); /* Comparing "TEST" and "TEST": rc == 0 */ rc = pfmStrCmpLTrim(" 123", " 234", 3); /* Comparing "123" and "234": rc < 0 */
30. pfmStrCmpRTrim
Trims right spaces of two strings and then compares them.
-
Prototype
long pfmStrCmpRTrim(char *str1, char *str2, long len);
-
Parameters
Parameter Description *str1 (input)
First string to compare.
*str2 (input)
Second string to compare.
len (input)
Length of the part of the strings to compare.
-
Return values
Returns 0 if the two strings whose right spaces are trimmed are the same. Returns a positive number if the two strings whose right spaces are trimmed are not the same and the ASCII value of the first different character in the first string is greater than that in the second string. Returns a negative value if they are not the same and the ASCII value of the first different character in the first string is less than that in the second string.
-
Example
rc = pfmStrCmpRTrim("TEST", "TEST ", 4); /* Comparing "TEST" and "TEST": rc == 0 */ rc = pfmStrCmpRTrim("123 ", "234 ", 3); /* Comparing "123" and "234": rc < 0 */
31. pfmStrCmpTrim
Trims left and right spaces of two strings and then compares them.
-
Prototype
long pfmStrCmpTrim(char *str1, char *str2, long len);
-
Parameters
Parameter Description *str1 (input)
First string to compare.
*str2 (input)
Second string to compare.
len (input)
Length of the part of the strings to compare.
-
Return values
Returns 0 if the two strings whose left and right spaces are trimmed are the same. Returns a positive number if the two strings whose left and right spaces are trimmed are not the same and the ASCII value of the first different character in the first string is greater than that in the second string. Returns a negative value if they are not the same and the ASCII value of the first different character in the first string is less than that in the second string.
-
Example
rc = pfmStrCmpTrim(" TEST", "TEST ", 10); /* Comparing "TEST" and "TEST": rc == 0 */ rc = pfmStrCmpTrim(" 123 ", " 234 ", 10); /* Comparing "123" and "234": rc < 0 */
32. pfmStrCmpRemoveSpace
Removes spaces (0x20) of two strings and then compares them.
-
Prototype
long pfmStrCmpRemoveSpace(char *str1, char *str2, long len);
-
Parameters
Parameter Description *str1 (input)
First string to compare.
*str2 (input)
Second string to compare.
len (input)
Length of the part of the strings to compare.
-
Return values
Returns 0 if the two strings whose spaces are removed are the same. Returns a positive number if the two strings whose spaces are removed are not the same and the ASCII value of the first different character in the first string is greater than that in the second string. Returns a negative value if they are not the same and the ASCII value of the first different character in the first string is less than that in the second string.
-
Example
char str1[12 + 1] = "20051028"; char str2[12 + 1] = "2005 10 28"; if(pfmStrCmpRemoveSpace(str1, str2, 12) == 0) { PFM_DBG("The two dates are the same."); }
33. pfmStrCpyRPadSpace
Copies a string as long as specifed and pads the ending remaining part with spaces (0x20).
-
Prototype
long pfmStrCpyRPadSpace(char *dest, char *src, long len);
-
Parameters
Parameter Description *dest (output)
Result string.
*src (input)
String to copy.
len (input)
Lengh of the string to copy.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char dest[9]; char src[] = "abcde"; long rc; rc = pfmStrCpyRPadSpace(dest, src, sizeof(dest)); if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* dest == "abcde " */
34. pfmStrCpyRPadZero
Copies a string as long as specifed, justifies it right, and pads the starting remaining part with 0.
-
Prototype
long pfmStrCpyRPadZero(char *dest, char *src, long len);
-
Parameters
Parameter Description *dest (output)
Result string.
*src (input)
String to copy.
len (input)
Lengh of the string to copy.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char dest[9]; char src[] = "12345"; long rc; memset(dest, 0x00, sizeof(dest)); rc = pfmStrCpyRPadZero(dest, src, sizeof(dest)); if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* dest == "000012345" */
35. pfmStrCpySkip
Removes a specified character from a string and copies it to another string.
-
Prototype
long pfmStrCpySkip(char *dest, char *src, char toskip, long dest_len);
-
Parameters
Parameter Description *dest (output)
Result string.
*src (input)
String to copy.
toskip (input)
Character to remove.
dest_len (input)
Length of the result string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char ostr[32]; long rc; rc = pfmStrCpySkip(ostr, "123kyj456", 'k', 9); /* ostr == "123yj456" */ rc = pfmStrCpySkip(ostr, "123kyj456", 'k', 5); /* rc == RC_ERR Error if the buffer size is less than the result string length. */ rc = pfmStrCpySkip(ostr, "a/b/c/d/e/f/g/", '/', 32); /* ostr == "abcdefg" */ rc = pfmStrCpySkip(ostr, "a-b-c-d-e-f-g-", '-', 32); /* ostr == "abcdefg" */ if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
36. pfmStrExtractDigitN
Extracts digits from a null-terminated string and converts them to an integer string.
-
Prototype
long pfmStrExtractDigitN(char *dest, long dest_len, char *src, long src_len);
-
Parameters
Parameter Description *dest (output)
Integer string.
dest_len (input)
Length of the integer string.
*src (input)
Null-terminated string.
src_len (input)
Length of the null-terminated string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char src[] = "345 67/33.8-4890/"; char dest[100]; long rc; rc = pfmStrExtractDigitN(dest, 100, src, strlen(src)); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* Normwl conversion: dest = "345673383890" */
37. pfmStrCmpMulti
Compares a string with a base string.
-
Prototype
long pfmStrCmpMulti(char *str, …);
-
Parameters
Parameter Description *str (input)
Base string.
… (input)
String to compare. An empty string ("") indicates the last parameter.
-
Return values
Returns the string’s position where the base string is located if the base string is found. Returns 0 if the base string is not found.
-
Example
char key[] = "test_n"; long rc; rc = pfmStrCmpMulti (key, "test", "n", "asdf", "ccsd", "test_n", ""); if(rc != 1) { return RC_ERR; }
38. pfmStrGetIndex
Searches a base string from N null-terminated strings.
-
Prototype
long pfmStrGetIndex(long cnt, char *str, …);
-
Parameters
Parameter Description cnt (input)
Number of strings to compare.
*str (input)
Base string.
… (input)
String to compare.
-
Return values
Returns the number (1,2, …., cnt) of the string where the base string exists. Returns 0 if the base string is not found.
-
Example
rc = pfmStrGetIndex(4, "a", "a", "ab", "abc", "abcd"); /* rc == 1 */ rc = pfmStrGetIndex(4, "ab", "a", "ab", "abc", "abcd"); /* rc == 2 */ rc = pfmStrGetIndex(4, "abc", "a", "ab", "abc", "abcd"); /* rc == 3 */ rc = pfmStrGetIndex(4, "abcd", "a", "ab", "abc", "abcd"); /* rc == 4 */ rc = pfmStrGetIndex(4, "abcde", "a", "ab", "abc", "abcd"); /* rc == 0 */
39. pfmToLower
Converts a null-terminated string to lowercase regardless of its length.
-
Prototype
char * pfmToLower(char *str);
-
Parameters
Parameter Description *str (input/output)
String to convert.
-
Return values
Returns a pointer to the converted string through *str.
-
Example
char istr[256], ostr[256]; char STR_MIXED[] = "AaBbCc123Dd EeFf"; char STR_LOWER[] = "aabbcc123dd eeff"; strncpy(istr, STR_MIXED, strlen(STR_MIXED)); strncpy(ostr, pfmToLower(istr), strlen(STR_LOWER)); /* Bothe istr and ostr are STR_LOWER. */ strncpy(ostr, pfmToLower("ABCDEFG"), 7); /* ostr is "abcdefg". */
40. pfmToLowern
Converts a fixed-length string to lowercase.
-
Prototype
char * pfmToLowern(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to convert.
len (input)
String length.
-
Return values
Returns a pointer to the converted string through *str.
-
Example
char istr[256]; char STR_MIXED1[] = "AAABBBB"; char STR_LOWER1[] = "aaaBBBB"; char STR_MIXED3[] = "AAABBBB"; pfmToLowern(STR_MIXED1, 3); /* STR_MIXED1 is the same as STR_LOWER1. */ strncpy(istr, pfmToLowern(STR_MIXED3, 3), 7); /* STR_MIXED3 is converted to "aaaBBBB" and then this converted string is copied to istr. */
41. pfmUpper
Converts a null-terminated string to uppercase regardless of its length.
-
Prototype
char * pfmToUpper(char *str);
-
Parameters
Parameter Description *str (input/output)
String to convert.
-
Return values
Returns a pointer to the converted string through *str.
-
Example
char istr[BUF_SIZE], ostr[BUF_SIZE]; char STR_MIXED[] = "AaBbCc123Dd EeFf"; char STR_UPPER[] = "AABBCC123DD EEFF"; strncpy(istr, STR_MIXED, strlen(STR_MIXED)); strncpy(ostr, pfmStrToUpper(istr), strlen(STR_MIXED)); /* Both istr and ostr are STR_UPPER. */ strncpy(ostr, pfmStrToUpper("abcdefg"), 7); /* ostr is "ABCDEFG". */
42. pfmToUppern
Converts a fixed-length string to uppercase.
-
Prototype
char * pfmToUppern(char *str, long len);
-
Parameters
Parameter Description *str (input/output)
String to convert.
len (input)
String length.
-
Return values
Returns a pointer to the converted string through *str.
-
Example
char istr[256]; char STR_MIXED1[] = "aaaBBBB"; char STR_LOWER1[] = "AAABBBB"; char STR_MIXED3[] = "aaaBBBB"; pfmToUppern(STR_MIXED1, 3); /* STR_MIXED1 is the same as STR_LOWER1. */ strncpy(istr, pfmToUppern(STR_MIXED3, 3), 7); /* STR_MIXED3 is converted to "AAABBBB" and then this converted string is copied to istr. */
43. pfmAscToInt
Converts a string to Int type.
-
Prototype
int pfmAscToInt(char *ptr, long len);
-
Parameters
Parameter Description *ptr (input)
String to convert.
len (input)
String length.
-
Return values
Returns the Int value.
-
Example
int num; num = pfmAscToInt("1234", 4); /* num == 1234 */ num = pfmAscToInt("1234", 3); /* num == 123 */
44. pfmAscToLong
Converts a string to Long type.
-
Prototype
long pfmAscToLong(char *ptr, long len);
-
Parameters
Parameter Description *ptr (input)
String to convert.
len (input)
String length.
-
Return values
Returns the Long value.
-
Example
long lnum; lnum = pfmAscToLong("1234567890", 10); /* lnum == 1234567890 */ lnum = pfmAscToLong("1234567890", 6); /* lnum == 123456 */
45. pfmStrToLong
Converts a null-terminated string to Long type.
-
Prototype
long pfmStrToLong(long *num, char *str);
-
Parameters
Parameter Description *num (output)
Pointer to the converted Long value.
*str (input)
String to convert.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char str[] = "2315"; long num, rc; rc = pfmStrToLong(&num, str); /* num == 2315 */ if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
46. pfmStrnToLong
Converts a fixed-length string to Long type.
-
Prototype
long pfmStrnToLong(long *num, char *str, long len);
-
Parameters
Parameter Description *num (output)
Pointer to the converted Long value.
*str (input)
String to convert.
len (input)
Length of the string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char str[] = "2315"; long num, rc; rc = pfmStrnToLong(&num, str, 4); /* num == 2315 */ rc = pfmStrnToLong(&num, str, 3); /* num == 231 */ rc = pfmStrnToLong(&num, str, 2); /* num == 23 */ rc = pfmStrnToLong(&num, "123a", 4); if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
47. pfmLongToStrn
Converts a Long number to a string.
-
Prototype
long pfmLongToStrn(char *str, long num, long buf_size);
-
Parameters
Parameter Description *str (output)
Converted string.
num (input)
Long number.
buf_size (input)
Size of the buffer for the converted string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The size of the converted string exceeds that of the buffer.
-
Example
rc = pfmLongToStrn(ostr, 123456, 10); /* ostr == "123456" */ rc = pfmLongToStrn(ostr, 12345678, 10); /* ostr == "12345678" */ rc = pfmLongToStrn(ostr, 12345678, 6); /* rc == RC_ERR */ if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
48. pfmLongToStrnLpadZero
Converts a Long number to a string, aligns it to the right, and pads spaces with 0.
-
Prototype
long pfmLongToStrnLpadZero(char *str, long num, long buf_size);
-
Parameters
Parameter Description *str (output)
Converted string.
num (input)
Long number.
buf_size (input)
Length of the converted string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The size of the converted string exceeds that of the buffer.
-
Example
rc = pfmLongToStrnLpadZero(ostr, 123456, 10); /* rc == RC_NRM, ostr == "0000123456" */ rc = pfmLongToStrnLpadZero(ostr, 12345678, 10); /* rc == RC_NRM, ostr == "0012345678" */ rc = pfmLongToStrnLpadZero(ostr, 12345678, 6); /* rc == RC_ERR */ if(rc == RC_ERR) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
49. pfmStrAddLong
Adds a Long integer to a given string and then converts it to a string.
-
Prototype
long pfmStrAddLong(char *str, long num);
-
Parameters
Parameter Description *str (input/output)
Input/output string.
num (input)
Long integer to add.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The length of the string after the addition exceeds that of the original string.
-
Example
char str[32] = "100"; long num = 11; long rc = RC_NRM; rc = pfmStrAddLong(str, num); /* str == "111" */ strncpy(str, "999", 3); rc = pfmStrAddLong(str, 10); /* 999 + 10 == 1009 */ /* Because rc == RC_ERR, strlen("999") < strlen("1009") */ strncpy(str, "1", 2); rc = pfmStrAddLong(str, -3); /* 1 + (-3) == -2 */ /* Because rc == RC_ERR, strlen("1") < strlen("-3") */ strncpy(str, "-999", 4); rc = pfmStrAddLong(str, 1000); /* -999 + 1000 == 1 */ /* rc == "0001", 0 padding for leading digits */ if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
50. pfmStrSubLong
Subtracts a Long integer from a given string and then converts it to a string.
-
Prototype
long pfmStrSubLong(char *str, long num);
-
Parameters
Parameter Description *str (input/output)
Input/output string.
num (input)
Long integer to subtract.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The length of the string after the subtraction exceeds that of the original string.
-
Example
char str[32] = "100"; long num = 11; long rc = RC_NRM; rc = pfmStrSubLong(str, num); /* str == "089", 0 padding for leading digits */ strncpy(str, "40", 2); rc = pfmStrSubLong(str, 77); /* 40 - 77 == -37 */ /* Because rc == RC_ERR, strlen("40") < strlen("-37") */ strncpy(str, "10000", 5); rc = pfmStrSubLong(str, 9900); /* 10000 - 9900 == 100 */ /* rc == "00100", 0 padding for leading digits */ if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
51. pfmStrToHex
Converts a null-terminated string to hexadecimal.
-
Prototype
long pfmStrToHex(char *hex, long hex_len, char *str, long in_len);
-
Parameters
Parameter Description *hex (output)
Converted string.
hex_len (input)
Length of the converted string.
*str (input)
String to convert.
in_len (input)
Length of the string to convert.
The address of the string to convert must be different from that of the converted string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char hex[32]; long rc; rc = pfmStrToHex(hex, 32, "jkfl43a-gg", 32); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* 6a 6b 66 6c 34 33 61 2d 67 67 */
52. pfmStrAscToEbc
Converts an ASCII string to EBCDIC.
-
Prototype
long pfmStrAscToEbc (unsigned char *dest, unsigned char *src, long src_len);
-
Parameters
Parameter Description *dest (output)
Converted string.
*src (input)
String to convert.
src_len (input)
Length of the string to convert.
The address of the string to convert must be different from that of the converted string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char src[] = "abcdefg"; char dest[20 + 1]; long len; rc = pfmStrAscToEbc(desc, src, strlen(src)); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
53. pfmStrEbcToAsc
Converts an EBCDIC string to ASCII.
-
Prototype
long pfmStrEbcToAsc(unsigned char *dest, unsigned char *src, long src_len);
-
Parameters
Parameter Description *dest (output)
Converted string.
*src (input)
String to convert.
src_len (input)
Length of the string to convert.
The address of the string to convert must be different from that of the converted string.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char src[] = "\201\202\203\204\205\206\207"; char dest[20 + 1]; rc = pfmStrEbcToAsc(dest, 20, src, strlen(src)); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
54. pfmStrnConv
Converts a string with a given conversion method.
-
Prototype
long pfmStrnConv(char *src, long len, long type);
-
Parameters
Parameter Description *src (input/output)
String to convert.
len (input)
Length of the string to convert.
type (input)
Conversion method.
-
MPFM_STRNCONV_CNTL2SP: Converts control characters in a fixed-length string to spaces (0x20).
-
MPFM_STRNCONV_NULL2SP: Converts null characters in a fixed-length string to spaces (0x20).
-
MPFM_STRNCONV_ONLY_ALNUM_UPPER: Converts alphabet characters in a fixed-length string to uppercase.
-
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char str[] = { 'A', 'b', 0x12, 0x13, 'C', 0x00 }; rc = pfmStrnConv(str, strlen(str), MPFM_STRNCONV_CNTL2SP); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* str = {'A', 'b', 0x12, 0x13, 'C', 0x00 }; */ /*-------------------------------------- */ char str[] = { 'A', 'b', 0x00, 'C', 0x00, 0x00 }; rc = pfmStrnConv(str, 5, MPFM_STRNCONV_NULL2SP); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* str = {'A', 'b', 0x20, 'C', 0x20, 0x00 }; */ /*-------------------------------------- */ char str[] = "2005 11 02 Wed"; rc = pfmStrnConv(str, 5, MPFM_STRNCONV_ONLY_ALNUM_UPPER); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; }
55. pfmStrnCpyConv
Converts a string with a given conversion method and then copies it to another string.
-
Prototype
long pfmStrnCpyConv(char *dest, char *src, long len, long type);
-
Parameters
Parameter Description *dest (output)
String to which the converted string is copied.
*src (input)
String to convert.
len (input)
Length of the string to convert.
type (input)
Conversion method.
-
MPFM_STRNCONV_CNTL2SP: Converts control characters in a fixed-length string to spaces (0x20).
-
MPFM_STRNCONV_NULL2SP: Converts null characters in a fixed-length string to spaces (0x20).
-
MPFM_STRNCONV_ONLY_ALNUM_UPPER: Converts alphabet characters in a fixed-length string to uppercase.
-
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed succesffully.
-
Example
char str[] = { 'A', 'b', 0x12, 0x13, 'C', 0x00 }; char buf[10 + 1]; rc = pfmStrnCopyConv(buf, str, 10, MPFM_STRNCONV_CNTL2SP); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* buf = { 'A', 'b', 0x20, 0x20, 'C', 0x00 }; */ /*-------------------------------------- */ char str[] = { 'A', 'b', 0x00, 'C', 0x00, 0x00 }; char buf[10 + 1]; rc = pfmStrnConv(buf, str, 10, MPFM_STRNCONV_NULL2SP); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* str = { 'A', 'b', 0x20, 'C', 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x00 }; */ /*-------------------------------------- */ char str[] = "2005 11 02 Wed"; char buf[10 + 1]; rc = pfmStrnConv(buf, str, 10, MPFM_STRNCONV_ONLY_ALNUM_UPPER); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); return RC_ERR; } /* buf = "20051102Wed" */
56. pfmStrGetErrorMsg
Returns an error message when a String utility error occurs.
-
Prototype
char * pfmStrGetErrorMsg(void);
-
Return values
Returns the error message.
-
Example
rc = pfmStrCpyRPadSpace(dest, src, sizeof(dest)); if(rc != RC_NRM) { PFM_ERR("%s", pfmStrGetErrorMsg()); /* Or, PFM_ERR("%s", pfmUtilGetErrorMsg()); */ return RC_ERR; }