WARNING: The online documentation has moved to https://docs.pjsip.org.

Visit the new documentation at https://docs.pjsip.org:

BLOG | DOCUMENTATION | GITHUB

Home --> Documentations --> PJLIB Reference

String Operations

Macros

#define PJ_CHECK_TRUNC_STR(ret, str, len)    if ((ret) >= (len) || (ret) < 0) pj_ansi_strcpy((str) + (len) - 3, "..")
 
#define strnicmp_alnum   pj_ansi_strnicmp
 
#define pj_stricmp_alnum   pj_stricmp
 

Functions

pj_str_t pj_str (char *str)
 
const pj_str_tpj_cstr (pj_str_t *str, const char *s)
 
pj_str_tpj_strset (pj_str_t *str, char *ptr, pj_size_t length)
 
pj_str_tpj_strset2 (pj_str_t *str, char *src)
 
pj_str_tpj_strset3 (pj_str_t *str, char *begin, char *end)
 
pj_str_tpj_strassign (pj_str_t *dst, pj_str_t *src)
 
pj_str_tpj_strcpy (pj_str_t *dst, const pj_str_t *src)
 
pj_str_tpj_strcpy2 (pj_str_t *dst, const char *src)
 
pj_str_tpj_strncpy (pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)
 
pj_str_tpj_strncpy_with_null (pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)
 
pj_str_tpj_strdup (pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)
 
pj_str_tpj_strdup_with_null (pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)
 
pj_str_tpj_strdup2 (pj_pool_t *pool, pj_str_t *dst, const char *src)
 
pj_str_tpj_strdup2_with_null (pj_pool_t *pool, pj_str_t *dst, const char *src)
 
pj_str_t pj_strdup3 (pj_pool_t *pool, const char *src)
 
pj_size_t pj_strlen (const pj_str_t *str)
 
const char * pj_strbuf (const pj_str_t *str)
 
int pj_strcmp (const pj_str_t *str1, const pj_str_t *str2)
 
int pj_strcmp2 (const pj_str_t *str1, const char *str2)
 
int pj_strncmp (const pj_str_t *str1, const pj_str_t *str2, pj_size_t len)
 
int pj_strncmp2 (const pj_str_t *str1, const char *str2, pj_size_t len)
 
int pj_stricmp (const pj_str_t *str1, const pj_str_t *str2)
 
int pj_stricmp2 (const pj_str_t *str1, const char *str2)
 
int pj_strnicmp (const pj_str_t *str1, const pj_str_t *str2, pj_size_t len)
 
int pj_strnicmp2 (const pj_str_t *str1, const char *str2, pj_size_t len)
 
void pj_strcat (pj_str_t *dst, const pj_str_t *src)
 
void pj_strcat2 (pj_str_t *dst, const char *src)
 
char * pj_strchr (const pj_str_t *str, int chr)
 
pj_ssize_t pj_strspn (const pj_str_t *str, const pj_str_t *set_char)
 
pj_ssize_t pj_strspn2 (const pj_str_t *str, const char *set_char)
 
pj_ssize_t pj_strcspn (const pj_str_t *str, const pj_str_t *set_char)
 
pj_ssize_t pj_strcspn2 (const pj_str_t *str, const char *set_char)
 
pj_ssize_t pj_strtok (const pj_str_t *str, const pj_str_t *delim, pj_str_t *tok, pj_size_t start_idx)
 
pj_ssize_t pj_strtok2 (const pj_str_t *str, const char *delim, pj_str_t *tok, pj_size_t start_idx)
 
char * pj_strstr (const pj_str_t *str, const pj_str_t *substr)
 
char * pj_stristr (const pj_str_t *str, const pj_str_t *substr)
 
pj_str_tpj_strltrim (pj_str_t *str)
 
pj_str_tpj_strrtrim (pj_str_t *str)
 
pj_str_tpj_strtrim (pj_str_t *str)
 
char * pj_create_random_string (char *str, pj_size_t length)
 
long pj_strtol (const pj_str_t *str)
 
pj_status_t pj_strtol2 (const pj_str_t *str, long *value)
 
unsigned long pj_strtoul (const pj_str_t *str)
 
unsigned long pj_strtoul2 (const pj_str_t *str, pj_str_t *endptr, unsigned base)
 
pj_status_t pj_strtoul3 (const pj_str_t *str, unsigned long *value, unsigned base)
 
float pj_strtof (const pj_str_t *str)
 
int pj_utoa (unsigned long val, char *buf)
 
int pj_utoa_pad (unsigned long val, char *buf, int min_dig, int pad)
 
void pj_bzero (void *dst, pj_size_t size)
 
void * pj_memset (void *dst, int c, pj_size_t size)
 
void * pj_memcpy (void *dst, const void *src, pj_size_t size)
 
void * pj_memmove (void *dst, const void *src, pj_size_t size)
 
int pj_memcmp (const void *buf1, const void *buf2, pj_size_t size)
 
void * pj_memchr (const void *buf, int c, pj_size_t size)
 

Detailed Description

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:

  typedef struct pj_str_t
  {
      char      *ptr;
      pj_ssize_t  slen;
  } pj_str_t;

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.

Examples

For some examples, please see:

Macro Definition Documentation

◆ PJ_CHECK_TRUNC_STR

#define PJ_CHECK_TRUNC_STR (   ret,
  str,
  len 
)     if ((ret) >= (len) || (ret) < 0) pj_ansi_strcpy((str) + (len) - 3, "..")

Check if a string is truncated and if yes, put a suffix of ".." to indicate the truncation. This macro is used to check the result of pj_ansi_snprintf().

Parameters
retThe return value of pj_ansi_snprintf().
strThe string.
lenThe length of the string buffer.

◆ pj_stricmp_alnum

#define pj_stricmp_alnum   pj_stricmp

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
str1The string to compare.
str2The string to compare.
Returns
  • 0 if str1 is equal to str2
  • (-1) if not equal.

◆ strnicmp_alnum

#define strnicmp_alnum   pj_ansi_strnicmp

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
str1The string to compare.
str2The string to compare.
lenThe length to compare.
Returns
  • 0 if str1 is equal to str2
  • (-1) if not equal.

Function Documentation

◆ pj_bzero()

void pj_bzero ( void *  dst,
pj_size_t  size 
)

Fill the memory location with zero.

Parameters
dstThe destination buffer.
sizeThe number of bytes.

Referenced by pj_enum_ip_option_default(), and pj_math_stat_init().

◆ pj_create_random_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
strthe string to store the result.
lengththe length of the random string to generate.
Returns
the string.

◆ pj_cstr()

const pj_str_t * pj_cstr ( pj_str_t str,
const char *  s 
)

Create constant string from normal C string.

Parameters
strThe string to be initialized.
sNull terminated string.
Returns
pj_str_t.

References pj_str_t::ptr, and pj_str_t::slen.

◆ pj_memchr()

void * pj_memchr ( const void *  buf,
int  c,
pj_size_t  size 
)

Find character in the buffer.

Parameters
bufThe buffer.
cThe character to find.
sizeThe size to check.
Returns
the pointer to location where the character is found, or NULL if not found.

◆ pj_memcmp()

int pj_memcmp ( const void *  buf1,
const void *  buf2,
pj_size_t  size 
)

Compare buffers.

Parameters
buf1The first buffer.
buf2The second buffer.
sizeThe size to compare.
Returns
negative, zero, or positive value.

◆ pj_memcpy()

void * pj_memcpy ( void *  dst,
const void *  src,
pj_size_t  size 
)

Copy buffer.

Parameters
dstThe destination buffer.
srcThe source buffer.
sizeThe size to copy.
Returns
the destination buffer.

◆ pj_memmove()

void * pj_memmove ( void *  dst,
const void *  src,
pj_size_t  size 
)

Move memory.

Parameters
dstThe destination buffer.
srcThe source buffer.
sizeThe size to copy.
Returns
the destination buffer.

◆ pj_memset()

void * pj_memset ( void *  dst,
int  c,
pj_size_t  size 
)

Fill the memory location with value.

Parameters
dstThe destination buffer.
cCharacter to set.
sizeThe number of characters.
Returns
the value of dst.

◆ pj_str()

pj_str_t pj_str ( char *  str)

Create string initializer from a normal C string.

Parameters
strNull terminated string to be stored.
Returns
pj_str_t.

◆ pj_strassign()

pj_str_t * pj_strassign ( pj_str_t dst,
pj_str_t src 
)

Assign string.

Parameters
dstThe target string.
srcThe source string.
Returns
the target string.

◆ pj_strbuf()

const char * pj_strbuf ( const pj_str_t str)

Return the pointer to the string data.

Parameters
strThe string.
Returns
the pointer to the string buffer.

References pj_str_t::ptr.

◆ pj_strcat()

void pj_strcat ( pj_str_t dst,
const pj_str_t src 
)

Concatenate strings.

Parameters
dstThe destination string.
srcThe source string.

◆ pj_strcat2()

void pj_strcat2 ( pj_str_t dst,
const char *  src 
)

Concatenate strings.

Parameters
dstThe destination string.
srcThe source string.

◆ pj_strchr()

char * pj_strchr ( const pj_str_t str,
int  chr 
)

Finds a character in a string.

Parameters
strThe string.
chrThe character to find.
Returns
the pointer to first character found, or NULL.

References pj_str_t::ptr, and pj_str_t::slen.

◆ pj_strcmp()

int pj_strcmp ( const pj_str_t str1,
const pj_str_t str2 
)

Compare strings.

Parameters
str1The string to compare.
str2The 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

◆ pj_strcmp2()

int pj_strcmp2 ( const pj_str_t str1,
const char *  str2 
)

Compare strings.

Parameters
str1The string to compare.
str2The 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

◆ pj_strcpy()

pj_str_t * pj_strcpy ( pj_str_t dst,
const pj_str_t src 
)

Copy string contents.

Parameters
dstThe target string.
srcThe source string.
Returns
the target string.

◆ pj_strcpy2()

pj_str_t * pj_strcpy2 ( pj_str_t dst,
const char *  src 
)

Copy string contents.

Parameters
dstThe target string.
srcThe source string.
Returns
the target string.

◆ pj_strcspn()

pj_ssize_t pj_strcspn ( const pj_str_t str,
const pj_str_t set_char 
)

Find the first index of character, in a string, that belong to a set of characters.

Parameters
strThe string.
set_charThe string containing the set of characters.
Returns
the index of the first character in the str that belong to set_char. If no match is found, return the length of str.

◆ pj_strcspn2()

pj_ssize_t pj_strcspn2 ( const pj_str_t str,
const char *  set_char 
)

Find the first index of character, in a string, that belong to a set of characters.

Parameters
strThe string.
set_charThe string containing the set of characters.
Returns
the index of the first character in the str that belong to set_char. If no match is found, return the length of str.

◆ pj_strdup()

pj_str_t * pj_strdup ( pj_pool_t pool,
pj_str_t dst,
const pj_str_t src 
)

Duplicate string.

Parameters
poolThe pool.
dstThe string result.
srcThe string to duplicate.
Returns
the string result.

◆ pj_strdup2()

pj_str_t * pj_strdup2 ( pj_pool_t pool,
pj_str_t dst,
const char *  src 
)

Duplicate string.

Parameters
poolThe pool.
dstThe string result.
srcThe string to duplicate.
Returns
the string result.

◆ pj_strdup2_with_null()

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
poolThe pool.
dstThe string result.
srcThe string to duplicate.
Returns
The string result.

◆ pj_strdup3()

pj_str_t pj_strdup3 ( pj_pool_t pool,
const char *  src 
)

Duplicate string.

Parameters
poolThe pool.
srcThe string to duplicate.
Returns
the string result.

◆ pj_strdup_with_null()

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
poolThe pool.
dstThe string result.
srcThe string to duplicate.
Returns
The string result.

◆ pj_stricmp()

int pj_stricmp ( const pj_str_t str1,
const pj_str_t str2 
)

Perform case-insensitive comparison to the strings.

Parameters
str1The string to compare.
str2The 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

◆ pj_stricmp2()

int pj_stricmp2 ( const pj_str_t str1,
const char *  str2 
)

Perform case-insensitive comparison to the strings.

Parameters
str1The string to compare.
str2The 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

◆ pj_stristr()

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
strThe string to search.
substrThe 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_strlen()

pj_size_t pj_strlen ( const pj_str_t str)

Return the length of the string.

Parameters
strThe string.
Returns
the length of the string.

References pj_str_t::slen.

◆ pj_strltrim()

pj_str_t * pj_strltrim ( pj_str_t str)

Remove (trim) leading whitespaces from the string.

Parameters
strThe string.
Returns
the string.

◆ pj_strncmp()

int pj_strncmp ( const pj_str_t str1,
const pj_str_t str2,
pj_size_t  len 
)

Compare strings.

Parameters
str1The string to compare.
str2The string to compare.
lenThe 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

◆ pj_strncmp2()

int pj_strncmp2 ( const pj_str_t str1,
const char *  str2,
pj_size_t  len 
)

Compare strings.

Parameters
str1The string to compare.
str2The string to compare.
lenThe 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

◆ pj_strncpy()

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
dstThe target string.
srcThe source string.
maxMaximum characters to copy.
Returns
the target string.

◆ pj_strncpy_with_null()

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
dstThe target string.
srcThe source string.
maxMaximum characters to copy.
Returns
the target string.

◆ pj_strnicmp()

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
str1The string to compare.
str2The string to compare.
lenThe 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

◆ pj_strnicmp2()

int pj_strnicmp2 ( const pj_str_t str1,
const char *  str2,
pj_size_t  len 
)

Perform case-insensitive comparison to the strings.

Parameters
str1The string to compare.
str2The string to compare.
lenThe 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

◆ pj_strrtrim()

pj_str_t * pj_strrtrim ( pj_str_t str)

Remove (trim) the trailing whitespaces from the string.

Parameters
strThe string.
Returns
the string.

◆ pj_strset()

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
strthe string.
ptrpointer to set.
lengthlength to set.
Returns
the string.

References pj_str_t::ptr, and pj_str_t::slen.

◆ pj_strset2()

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
strthe string.
srcpointer to set.
Returns
the string.

References pj_str_t::ptr, and pj_str_t::slen.

◆ pj_strset3()

pj_str_t * pj_strset3 ( pj_str_t str,
char *  begin,
char *  end 
)

Set the pointer and the length of the string.

Parameters
strThe target string.
beginThe start of the string.
endThe end of the string.
Returns
the target string.

References pj_str_t::ptr, and pj_str_t::slen.

◆ pj_strspn()

pj_ssize_t pj_strspn ( const pj_str_t str,
const pj_str_t set_char 
)

Find the first index of character, in a string, that does not belong to a set of characters.

Parameters
strThe string.
set_charThe string containing the set of characters.
Returns
the index of the first character in the str that doesn't belong to set_char. If str starts with a character not in set_char, return 0.

◆ pj_strspn2()

pj_ssize_t pj_strspn2 ( const pj_str_t str,
const char *  set_char 
)

Find the first index of character, in a string, that does not belong to a set of characters.

Parameters
strThe string.
set_charThe string containing the set of characters.
Returns
the index of the first character in the str that doesn't belong to set_char. If str starts with a character not in set_char, return 0.

◆ pj_strstr()

char * pj_strstr ( const pj_str_t str,
const pj_str_t substr 
)

Find the occurence of a substring substr in string str.

Parameters
strThe string to search.
substrThe 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_strtof()

float pj_strtof ( const pj_str_t str)

Convert string to float.

Parameters
strthe string.
Returns
the value.

◆ pj_strtok()

pj_ssize_t pj_strtok ( const pj_str_t str,
const pj_str_t delim,
pj_str_t tok,
pj_size_t  start_idx 
)

Find tokens from a string using the delimiter.

Parameters
strThe string.
delimThe string containing the delimiter. It might contain multiple character treated as unique set. If same character was found on the set, it will be skipped.
tokThe string containing the token.
start_idxThe search will start from this index.
Returns
the index of token from the str, or the length of the str if the token is not found.

◆ pj_strtok2()

pj_ssize_t pj_strtok2 ( const pj_str_t str,
const char *  delim,
pj_str_t tok,
pj_size_t  start_idx 
)

Find tokens from a string using the delimiter.

Parameters
strThe string.
delimThe string containing the delimiter. It might contain multiple character treated as unique set. If same character was found on the set, it will be skipped.
tokThe string containing the token.
start_idxThe search will start from this index.
Returns
the index of token from the str, or the length of the str if the token is not found.

◆ pj_strtol()

long pj_strtol ( const pj_str_t str)

Convert string to signed integer. The conversion will stop as soon as non-digit character is found or all the characters have been processed.

Parameters
strthe string.
Returns
the integer.

◆ pj_strtol2()

pj_status_t pj_strtol2 ( const pj_str_t str,
long *  value 
)

Convert string to signed long integer. The conversion will stop as soon as non-digit character is found or all the characters have been processed.

Parameters
strthe string.
valuePointer to a long to receive the value.
Returns
PJ_SUCCESS if successful. Otherwise: PJ_ETOOSMALL if the value was an impossibly long negative number. In this case *value will be set to LONG_MIN.
PJ_ETOOBIG if the value was an impossibly long positive number. In this case, *value will be set to LONG_MAX.
PJ_EINVAL if the input string was NULL, the value pointer was NULL or the input string could not be parsed at all such as starting with a character other than a '+', '-' or not in the '0' - '9' range. In this case, *value will be left untouched.

◆ pj_strtoul()

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
strthe string.
Returns
the unsigned integer.

◆ pj_strtoul2()

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
strThe input string.
endptrOptional pointer to receive the remainder/unparsed portion of the input.
baseNumber base to use.
Returns
the unsigned integer number.

◆ pj_strtoul3()

pj_status_t pj_strtoul3 ( const pj_str_t str,
unsigned long *  value,
unsigned  base 
)

Convert string to unsigned long integer. The conversion will stop as soon as non-digit character is found or all the characters have been processed.

Parameters
strThe input string.
valuePointer to an unsigned long to receive the value.
baseNumber base to use.
Returns
PJ_SUCCESS if successful. Otherwise: PJ_ETOOBIG if the value was an impossibly long positive number. In this case, *value will be set to ULONG_MAX.
PJ_EINVAL if the input string was NULL, the value pointer was NULL or the input string could not be parsed at all such as starting with a character outside the base character range. In this case, *value will be left untouched.

◆ pj_strtrim()

pj_str_t * pj_strtrim ( pj_str_t str)

Remove (trim) leading and trailing whitespaces from the string.

Parameters
strThe string.
Returns
the string.

◆ pj_utoa()

int pj_utoa ( unsigned long  val,
char *  buf 
)

Utility to convert unsigned integer to string. Note that the string will be NULL terminated.

Parameters
valthe unsigned integer value.
bufthe buffer
Returns
the number of characters written

◆ pj_utoa_pad()

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
valThe unsigned integer value.
bufThe buffer.
min_digMinimum digits to be printed, or zero to specify no minimum digit.
padThe padding character to be put in front of the string when the digits is less than minimum.
Returns
the number of characters written.

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.