Group PJ_PSTR¶
-
group
PJ_PSTR
This module provides string manipulation API.
PJLIB String is NOT Null Terminated!¶
That is the first information that developers need to know. Instead of using normal C string, strings in PJLIB are represented as pj_str_t structure below:
There are some advantages of using this approach:
the string can point to arbitrary location in memory even if the string in that location is not null terminated. This is most usefull for text parsing, where the parsed text can just point to the original text in the input. If we use C string, then we will have to copy the text portion from the input to a string variable.
because the length of the string is known, string copy operation can be made more efficient.
Most of APIs in PJLIB that expect or return string will represent the string as pj_str_t instead of normal C string.
Defines
-
strnicmp_alnum
¶ Perform lowercase comparison to the strings which consists of only alnum characters. More over, it will only return non-zero if both strings are not equal, not the usual negative or positive value.
If non-alnum inputs are given, then the function may mistakenly treat two strings as equal.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
len – The length to compare.
- Returns
0 if str1 is equal to str2
(-1) if not equal.
-
pj_stricmp_alnum
¶ Perform lowercase comparison to the strings which consists of only alnum characters. More over, it will only return non-zero if both strings are not equal, not the usual negative or positive value.
If non-alnum inputs are given, then the function may mistakenly treat two strings as equal.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
- Returns
0 if str1 is equal to str2
(-1) if not equal.
Functions
-
pj_str_t
pj_str
(char *str)¶ Create string initializer from a normal C string.
- Parameters
str – Null terminated string to be stored.
- Returns
-
const pj_str_t *
pj_cstr
(pj_str_t *str, const char *s)¶ Create constant string from normal C string.
- Parameters
str – The string to be initialized.
s – Null terminated string.
- Returns
-
pj_str_t *
pj_strset
(pj_str_t *str, char *ptr, pj_size_t length)¶ Set the pointer and length to the specified value.
- Parameters
str – the string.
ptr – pointer to set.
length – length to set.
- Returns
the string.
-
pj_str_t *
pj_strset2
(pj_str_t *str, char *src)¶ Set the pointer and length of the string to the source string, which must be NULL terminated.
- Parameters
str – the string.
src – pointer to set.
- Returns
the string.
-
pj_str_t *
pj_strset3
(pj_str_t *str, char *begin, char *end)¶ Set the pointer and the length of the string.
- Parameters
str – The target string.
begin – The start of the string.
end – The end of the string.
- Returns
the target string.
-
pj_str_t *
pj_strassign
(pj_str_t *dst, pj_str_t *src)¶ Assign string.
- Parameters
dst – The target string.
src – The source string.
- Returns
the target string.
-
pj_str_t *
pj_strcpy
(pj_str_t *dst, const pj_str_t *src)¶ Copy string contents.
- Parameters
dst – The target string.
src – The source string.
- Returns
the target string.
-
pj_str_t *
pj_strcpy2
(pj_str_t *dst, const char *src)¶ Copy string contents.
- Parameters
dst – The target string.
src – The source string.
- Returns
the target string.
-
pj_str_t *
pj_strncpy
(pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)¶ Copy source string to destination up to the specified max length.
- Parameters
dst – The target string.
src – The source string.
max – Maximum characters to copy.
- Returns
the target string.
-
pj_str_t *
pj_strncpy_with_null
(pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)¶ Copy source string to destination up to the specified max length, and NULL terminate the destination. If source string length is greater than or equal to max, then max-1 will be copied.
- Parameters
dst – The target string.
src – The source string.
max – Maximum characters to copy.
- Returns
the target string.
-
pj_str_t *
pj_strdup
(pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)¶ Duplicate string.
- Parameters
pool – The pool.
dst – The string result.
src – The string to duplicate.
- Returns
the string result.
-
pj_str_t *
pj_strdup_with_null
(pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)¶ Duplicate string and NULL terminate the destination string.
- Parameters
pool – The pool.
dst – The string result.
src – The string to duplicate.
- Returns
The string result.
-
pj_str_t *
pj_strdup2
(pj_pool_t *pool, pj_str_t *dst, const char *src)¶ Duplicate string.
- Parameters
pool – The pool.
dst – The string result.
src – The string to duplicate.
- Returns
the string result.
-
pj_str_t *
pj_strdup2_with_null
(pj_pool_t *pool, pj_str_t *dst, const char *src)¶ Duplicate string and NULL terminate the destination string.
- Parameters
pool – The pool.
dst – The string result.
src – The string to duplicate.
- Returns
The string result.
-
pj_str_t
pj_strdup3
(pj_pool_t *pool, const char *src)¶ Duplicate string.
- Parameters
pool – The pool.
src – The string to duplicate.
- Returns
the string result.
-
pj_size_t
pj_strlen
(const pj_str_t *str)¶ Return the length of the string.
- Parameters
str – The string.
- Returns
the length of the string.
-
const char *
pj_strbuf
(const pj_str_t *str)¶ Return the pointer to the string data.
- Parameters
str – The string.
- Returns
the pointer to the string buffer.
-
int
pj_strcmp
(const pj_str_t *str1, const pj_str_t *str2)¶ Compare strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_strcmp2
(const pj_str_t *str1, const char *str2)¶ Compare strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_strncmp
(const pj_str_t *str1, const pj_str_t *str2, pj_size_t len)¶ Compare strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
len – The maximum number of characters to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_strncmp2
(const pj_str_t *str1, const char *str2, pj_size_t len)¶ Compare strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
len – The maximum number of characters to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_stricmp
(const pj_str_t *str1, const pj_str_t *str2)¶ Perform case-insensitive comparison to the strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is equal to str2
> 0 if str1 is greater than str2
-
int
pj_stricmp2
(const pj_str_t *str1, const char *str2)¶ Perform case-insensitive comparison to the strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_strnicmp
(const pj_str_t *str1, const pj_str_t *str2, pj_size_t len)¶ Perform case-insensitive comparison to the strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
len – The maximum number of characters to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
int
pj_strnicmp2
(const pj_str_t *str1, const char *str2, pj_size_t len)¶ Perform case-insensitive comparison to the strings.
- Parameters
str1 – The string to compare.
str2 – The string to compare.
len – The maximum number of characters to compare.
- Returns
< 0 if str1 is less than str2
0 if str1 is identical to str2
> 0 if str1 is greater than str2
-
void
pj_strcat
(pj_str_t *dst, const pj_str_t *src)¶ Concatenate strings.
- Parameters
dst – The destination string.
src – The source string.
-
void
pj_strcat2
(pj_str_t *dst, const char *src)¶ Concatenate strings.
- Parameters
dst – The destination string.
src – The source string.
-
char *
pj_strchr
(const pj_str_t *str, int chr)¶ Finds a character in a string.
- Parameters
str – The string.
chr – The character to find.
- Returns
the pointer to first character found, or NULL.
-
char *
pj_strstr
(const pj_str_t *str, const pj_str_t *substr)¶ Find the occurence of a substring substr in string str.
- Parameters
str – The string to search.
substr – The string to search fo.
- Returns
the pointer to the position of substr in str, or NULL. Note that if str is not NULL terminated, the returned pointer is pointing to non-NULL terminated string.
-
char *
pj_stristr
(const pj_str_t *str, const pj_str_t *substr)¶ Performs substring lookup like pj_strstr() but ignores the case of both strings.
- Parameters
str – The string to search.
substr – The string to search fo.
- Returns
the pointer to the position of substr in str, or NULL. Note that if str is not NULL terminated, the returned pointer is pointing to non-NULL terminated string.
-
pj_str_t *
pj_strltrim
(pj_str_t *str)¶ Remove (trim) leading whitespaces from the string.
- Parameters
str – The string.
- Returns
the string.
-
pj_str_t *
pj_strrtrim
(pj_str_t *str)¶ Remove (trim) the trailing whitespaces from the string.
- Parameters
str – The string.
- Returns
the string.
-
pj_str_t *
pj_strtrim
(pj_str_t *str)¶ Remove (trim) leading and trailing whitespaces from the string.
- Parameters
str – The string.
- Returns
the string.
-
char *
pj_create_random_string
(char *str, pj_size_t length)¶ Initialize the buffer with some random string. Note that the generated string is not NULL terminated.
- Parameters
str – the string to store the result.
length – the length of the random string to generate.
- Returns
the string.
-
unsigned long
pj_strtoul
(const pj_str_t *str)¶ Convert string to unsigned integer. The conversion will stop as soon as non-digit character is found or all the characters have been processed.
- Parameters
str – the string.
- Returns
the unsigned integer.
-
unsigned long
pj_strtoul2
(const pj_str_t *str, pj_str_t *endptr, unsigned base)¶ Convert strings to an unsigned long-integer value. This function stops reading the string input either when the number of characters has exceeded the length of the input or it has read the first character it cannot recognize as part of a number, that is a character greater than or equal to base.
- Parameters
str – The input string.
endptr – Optional pointer to receive the remainder/unparsed portion of the input.
base – Number base to use.
- Returns
the unsigned integer number.
-
int
pj_utoa
(unsigned long val, char *buf)¶ Utility to convert unsigned integer to string. Note that the string will be NULL terminated.
- Parameters
val – the unsigned integer value.
buf – the buffer
- Returns
the number of characters written
-
int
pj_utoa_pad
(unsigned long val, char *buf, int min_dig, int pad)¶ Convert unsigned integer to string with minimum digits. Note that the string will be NULL terminated.
- Parameters
val – The unsigned integer value.
buf – The buffer.
min_dig – Minimum digits to be printed, or zero to specify no minimum digit.
pad – The padding character to be put in front of the string when the digits is less than minimum.
- Returns
the number of characters written.
-
void
pj_bzero
(void *dst, pj_size_t size)¶ Fill the memory location with zero.
- Parameters
dst – The destination buffer.
size – The number of bytes.
-
void *
pj_memset
(void *dst, int c, pj_size_t size)¶ Fill the memory location with value.
- Parameters
dst – The destination buffer.
c – Character to set.
size – The number of characters.
- Returns
the value of dst.
-
void *
pj_memcpy
(void *dst, const void *src, pj_size_t size)¶ Copy buffer.
- Parameters
dst – The destination buffer.
src – The source buffer.
size – The size to copy.
- Returns
the destination buffer.
-
void *
pj_memmove
(void *dst, const void *src, pj_size_t size)¶ Move memory.
- Parameters
dst – The destination buffer.
src – The source buffer.
size – The size to copy.
- Returns
the destination buffer.