String Operations [Data Structure.]

Defines
#define	strnicmp_alnum   pj_ansi_strnicmp
#define	pj_stricmp_alnum   pj_stricmp
Functions
pj_str_t	pj_str (char *str)
const pj_str_t *	pj_cstr (pj_str_t *str, const char *s)
pj_str_t *	pj_strset (pj_str_t *str, char *ptr, pj_size_t length)
pj_str_t *	pj_strset2 (pj_str_t *str, char *src)
pj_str_t *	pj_strset3 (pj_str_t *str, char *begin, char *end)
pj_str_t *	pj_strassign (pj_str_t *dst, pj_str_t *src)
pj_str_t *	pj_strcpy (pj_str_t *dst, const pj_str_t *src)
pj_str_t *	pj_strcpy2 (pj_str_t *dst, const char *src)
pj_str_t *	pj_strncpy (pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)
pj_str_t *	pj_strncpy_with_null (pj_str_t *dst, const pj_str_t *src, pj_ssize_t max)
pj_str_t *	pj_strdup (pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)
pj_str_t *	pj_strdup_with_null (pj_pool_t *pool, pj_str_t *dst, const pj_str_t *src)
pj_str_t *	pj_strdup2 (pj_pool_t *pool, pj_str_t *dst, const char *src)
pj_str_t *	pj_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)
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_t *	pj_strltrim (pj_str_t *str)
pj_str_t *	pj_strrtrim (pj_str_t *str)
pj_str_t *	pj_strtrim (pj_str_t *str)
char *	pj_create_random_string (char *str, pj_size_t length)
unsigned long	pj_strtoul (const pj_str_t *str)
unsigned long	pj_strtoul2 (const pj_str_t *str, pj_str_t *endptr, unsigned base)
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_size_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:

• Test: String

---

Define Documentation

#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:

	str1	The string to compare.
	str2	The string to compare.

Returns:

• 0 if str1 is equal to str2
• (-1) if not equal.

#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:

	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.

---

Function Documentation

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.

Referenced by pj_math_stat_init().

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.

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.

References pj_str_t::ptr.

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

Find character in the buffer.

Parameters:

	buf	The buffer.
	c	The character to find.
	size	The size to check.

Returns:

the pointer to location where the character is found, or NULL if not found.

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

Compare buffers.

Parameters:

	buf1	The first buffer.
	buf2	The second buffer.
	size	The size to compare.

Returns:

negative, zero, or positive value.

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.

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.

pj_str_t pj_str

(

char *

str

)

Create string initializer from a normal C string.

Parameters:

str

Null terminated string to be stored.

Returns:

pj_str_t.

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.

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.

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.

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

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_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_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_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.

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

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_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.

pj_str_t* pj_strltrim

(

pj_str_t *

str

)

Remove (trim) leading whitespaces from the string.

Parameters:

str

The string.

Returns:

the string.

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

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.

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

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_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.

References pj_str_t::ptr.

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.

References pj_str_t::ptr.

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.

References pj_str_t::ptr.

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.

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.

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.

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.