string.h File Reference

#include <mupnp/typedef.h>
#include <stdlib.h>

Data Structures
struct	_mUpnpString
struct	_mUpnpStringTokenizer

Macros
#define	MUPNP_STRING_MEMORY_ALLOCATION_UNIT   64
#define	MUPNP_STRING_INTEGER_BUFLEN   16
#define	MUPNP_STRING_LONG_BUFLEN   32
#define	MUPNP_STRING_LONGLONG_BUFLEN   32
#define	MUPNP_STRING_FLOAT_BUFLEN   64
#define	MUPNP_STRING_DOUBLE_BUFLEN   64
#define	mupnp_str2int(value)
	Convert string to integer (NULL-safe)
#define	mupnp_str2long(value)
	Convert string to long (NULL-safe)
#define	mupnp_strhex2long(value)
	Convert hexadecimal string to long (NULL-safe)
#define	mupnp_strhex2ulong(value)
	Convert hexadecimal string to unsigned long (NULL-safe)
#define	mupnp_str2float(value)
	Convert string to float (NULL-safe)
#define	mupnp_str2double(value)
	Convert string to double (NULL-safe)
#define	mupnp_str2sizet(value)
	Convert string to size_t (NULL-safe)
#define	mupnp_str2ssizet(value)
	Convert string to ssize_t (NULL-safe)
#define	mupnp_string_getintvalue(str)
#define	mupnp_string_getlongvalue(str)
#define	mupnp_string_getfloatvalue(str)
#define	mupnp_string_getdoublevalue(str)

Typedefs
typedef struct _mUpnpString	mUpnpString
typedef struct _mUpnpStringTokenizer	mUpnpStringTokenizer

Functions
char *	mupnp_strdup (const char *str)
	Duplicate a string (NULL-safe wrapper for strdup)
size_t	mupnp_strlen (const char *str)
	Get the length of a string (NULL-safe wrapper for strlen)
char *	mupnp_strcpy (char *dest, const char *src)
	Copy a string (NULL-safe wrapper for strcpy)
char *	mupnp_strcat (char *dest, const char *src)
	Concatenate strings (NULL-safe wrapper for strcat)
int	mupnp_strcmp (const char *str1, const char *str2)
	Compare two strings (NULL-safe wrapper for strcmp)
int	mupnp_strncmp (const char *str1, const char *str2, int nchars)
	Compare first n characters of two strings (NULL-safe)
int	mupnp_strcasecmp (const char *str1, const char *str2)
	Compare two strings case-insensitively (NULL-safe)
bool	mupnp_streq (const char *str1, const char *str2)
	Test if two strings are equal (NULL-safe)
bool	mupnp_strcaseeq (const char *str1, const char *str2)
	Test if two strings are equal case-insensitively (NULL-safe)
ssize_t	mupnp_strchr (const char *str, const char *chars, size_t nchars)
	Find first occurrence of any character from a set (strcspn variant)
ssize_t	mupnp_strrchr (const char *str, const char *chars, size_t nchars)
	Find last occurrence of any character from a set.
ssize_t	mupnp_strstr (const char *haystack, const char *needle)
	Find substring (NULL-safe wrapper for strstr)
char *	mupnp_strtrimwhite (char *str)
	Trim whitespace from both ends of a string (in-place)
char *	mupnp_strtrim (char *str, char *delim, size_t ndelim)
	Trim specified delimiter characters from both ends (in-place)
char *	mupnp_strltrim (char *str, char *delim, size_t ndelim)
	Trim delimiter characters from the left (start) of string (in-place)
char *	mupnp_strrtrim (char *str, char *delim, size_t ndelim)
	Trim delimiter characters from the right (end) of string (in-place)
char *	mupnp_strncpy (char *str1, const char *str2, size_t cnt)
	Copy at most n characters from one string to another (NULL-safe)
char *	mupnp_strncat (char *str1, const char *str2, size_t cnt)
	Append at most n characters from one string to another (NULL-safe)
const char *	mupnp_int2str (int value, char *buf, size_t bufSize)
	Convert integer to string.
const char *	mupnp_long2str (long value, char *buf, size_t bufSize)
	Convert long integer to string.
const char *	mupnp_float2str (float value, char *buf, size_t bufSize)
	Convert float to string.
const char *	mupnp_double2str (double value, char *buf, size_t bufSize)
	Convert double to string.
const char *	mupnp_sizet2str (size_t value, char *buf, size_t bufSize)
	Convert size_t to string.
const char *	mupnp_ssizet2str (ssize_t value, char *buf, size_t bufSize)
	Convert ssize_t to string.
mUpnpStringTokenizer *	mupnp_string_tokenizer_new (const char *str, const char *delim)
void	mupnp_string_tokenizer_delete (mUpnpStringTokenizer *strToken)
bool	mupnp_string_tokenizer_hasmoretoken (mUpnpStringTokenizer *strToken)
char *	mupnp_string_tokenizer_nexttoken (mUpnpStringTokenizer *strToken)
char *	mupnp_string_tokenizer_nextalltoken (mUpnpStringTokenizer *strToken)
void	mupnp_string_tokenizer_print (mUpnpStringTokenizer *strToken)
mUpnpString *	mupnp_string_new (void)
void	mupnp_string_delete (mUpnpString *str)
void	mupnp_string_clear (mUpnpString *str)
void	mupnp_string_setvalue (mUpnpString *str, const char *value)
void	mupnp_string_setintvalue (mUpnpString *str, int value)
void	mupnp_string_setlongvalue (mUpnpString *str, long value)
void	mupnp_string_setfloatvalue (mUpnpString *str, float value)
void	mupnp_string_setdoublevalue (mUpnpString *str, double value)
void	mupnp_string_setnvalue (mUpnpString *str, const char *value, size_t len)
void	mupnp_string_setpointervalue (mUpnpString *str, char *value, size_t len)
char *	mupnp_string_getvalue (mUpnpString *str)
size_t	mupnp_string_length (mUpnpString *str)
char *	mupnp_string_addvalue (mUpnpString *str, const char *value)
char *	mupnp_string_naddvalue (mUpnpString *str, const char *value, size_t valueLen)
char *	mupnp_string_addrepvalue (mUpnpString *str, const char *value, size_t repeatCnt)
char *	mupnp_string_naddrepvalue (mUpnpString *str, const char *value, size_t valueLen, size_t repeatCnt)
char *	mupnp_string_replace (mUpnpString *str, char *fromStr[], char *toStr[], size_t fromStrCnt)
size_t	mupnp_string_getmemorysize (mUpnpString *str)

Macro Definition Documentation

mupnp_str2double

#define mupnp_str2double

(

value

)

Value:

(value ? atof(value) : 0.0)

Convert string to double (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted double value, or 0.0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_str2float

#define mupnp_str2float

(

value

)

Value:

((float)(value ? atof(value) : 0.0))

Convert string to float (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted float value, or 0.0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_str2int

#define mupnp_str2int

(

value

)

Value:

(value ? atoi(value) : 0)

Convert string to integer (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted integer value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_str2long

#define mupnp_str2long

(

value

)

Value:

(value ? atol(value) : 0)

Convert string to long (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted long value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_str2sizet

#define mupnp_str2sizet

(

value

)

Value:

((size_t)(value ? atol(value) : 0))

Convert string to size_t (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted size_t value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_str2ssizet

#define mupnp_str2ssizet

(

value

)

Value:

((ssize_t)(value ? atol(value) : 0))

Convert string to ssize_t (NULL-safe)

Parameters

value

String to convert. May be NULL.

Returns

Converted ssize_t value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_strhex2long

#define mupnp_strhex2long

(

value

)

Value:

(value ? strtol(value, NULL, 16) : 0)

Convert hexadecimal string to long (NULL-safe)

Parameters

value

Hexadecimal string to convert (e.g., "1A3F"). May be NULL.

Returns

Converted long value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

mupnp_strhex2ulong

#define mupnp_strhex2ulong

(

value

)

Value:

(value ? strtoul(value, NULL, 16) : 0)

Convert hexadecimal string to unsigned long (NULL-safe)

Parameters

value

Hexadecimal string to convert. May be NULL.

Returns

Converted unsigned long value, or 0 if value is NULL or invalid.

Note

Thread-safe macro.

MUPNP_STRING_DOUBLE_BUFLEN

#define MUPNP_STRING_DOUBLE_BUFLEN   64

MUPNP_STRING_FLOAT_BUFLEN

#define MUPNP_STRING_FLOAT_BUFLEN   64

mupnp_string_getdoublevalue

#define mupnp_string_getdoublevalue

(

str

)

Value:

mupnp_str2double(mupnp_string_getvalue(str))

mupnp_string_getfloatvalue

#define mupnp_string_getfloatvalue

(

str

)

Value:

mupnp_str2float(mupnp_string_getvalue(str))

mupnp_string_getintvalue

#define mupnp_string_getintvalue

(

str

)

Value:

mupnp_str2int(mupnp_string_getvalue(str))

mupnp_string_getlongvalue

#define mupnp_string_getlongvalue

(

str

)

Value:

mupnp_str2long(mupnp_string_getvalue(str))

MUPNP_STRING_INTEGER_BUFLEN

#define MUPNP_STRING_INTEGER_BUFLEN   16

MUPNP_STRING_LONG_BUFLEN

#define MUPNP_STRING_LONG_BUFLEN   32

MUPNP_STRING_LONGLONG_BUFLEN

#define MUPNP_STRING_LONGLONG_BUFLEN   32

MUPNP_STRING_MEMORY_ALLOCATION_UNIT

#define MUPNP_STRING_MEMORY_ALLOCATION_UNIT   64

Typedef Documentation

mUpnpString

typedef struct _mUpnpString mUpnpString

mUpnpStringTokenizer

typedef struct _mUpnpStringTokenizer mUpnpStringTokenizer

Function Documentation

mupnp_double2str()

const char * mupnp_double2str	(	double	value,
		char *	buf,
		size_t	bufSize )

Convert double to string.

Parameters

value	The double value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_DOUBLE_BUFLEN (64) to safely hold any double.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

mupnp_float2str()

const char * mupnp_float2str	(	float	value,
		char *	buf,
		size_t	bufSize )

Convert float to string.

Parameters

value	The float value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_FLOAT_BUFLEN (64) to safely hold any float.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

mupnp_int2str()

const char * mupnp_int2str	(	int	value,
		char *	buf,
		size_t	bufSize )

Convert integer to string.

Parameters

value	The integer value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_INTEGER_BUFLEN (16) to safely hold any int.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

The buffer is always null-terminated if bufSize > 0.

mupnp_long2str()

const char * mupnp_long2str	(	long	value,
		char *	buf,
		size_t	bufSize )

Convert long integer to string.

Parameters

value	The long value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_LONG_BUFLEN (32) to safely hold any long.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

mupnp_sizet2str()

const char * mupnp_sizet2str	(	size_t	value,
		char *	buf,
		size_t	bufSize )

Convert size_t to string.

Parameters

value	The size_t value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_LONG_BUFLEN (32) bytes.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

mupnp_ssizet2str()

const char * mupnp_ssizet2str	(	ssize_t	value,
		char *	buf,
		size_t	bufSize )

Convert ssize_t to string.

Parameters

value	The ssize_t value to convert.
buf	Buffer to store the result. Must not be NULL.
bufSize	Size of buf in bytes. Should be at least MUPNP_STRING_LONG_BUFLEN (32) bytes.

Returns

Pointer to buf containing the converted string.

Note

Thread-safe: Can be called from any thread.

mupnp_strcasecmp()

int mupnp_strcasecmp	(	const char *	str1,
		const char *	str2 )

Compare two strings case-insensitively (NULL-safe)

Parameters

str1	First string. May be NULL.
str2	Second string. May be NULL.

Returns

Negative if str1 < str2, 0 if equal, positive if str1 > str2 (case-insensitive comparison).

Note

Thread-safe: Can be called from any thread.

mupnp_strcaseeq()

bool mupnp_strcaseeq	(	const char *	str1,
		const char *	str2 )

Test if two strings are equal case-insensitively (NULL-safe)

Parameters

str1	First string. May be NULL.
str2	Second string. May be NULL.

Returns

true if strings are equal (case-insensitive), false otherwise.

Note

Thread-safe: Can be called from any thread.

mupnp_strcat()

char * mupnp_strcat	(	char *	dest,
		const char *	src )

Concatenate strings (NULL-safe wrapper for strcat)

Parameters

dest	Destination buffer. Must not be NULL and must have sufficient space.
src	Source string to append. May be NULL (no-op if NULL).

Returns

dest pointer.

Note

Thread-safe: Can be called from any thread.

Warning

No bounds checking is performed. Ensure dest has enough space for the concatenated result plus null terminator.

mupnp_strchr()

ssize_t mupnp_strchr	(	const char *	str,
		const char *	chars,
		size_t	nchars )

Find first occurrence of any character from a set (strcspn variant)

Parameters

str	The string to search. Must not be NULL.
chars	Array of characters to search for. Must not be NULL.
nchars	Number of characters in chars array.

Returns

Index of first matching character, or -1 if not found.

Note

Thread-safe: Can be called from any thread.

mupnp_strcmp()

int mupnp_strcmp	(	const char *	str1,
		const char *	str2 )

Compare two strings (NULL-safe wrapper for strcmp)

Parameters

str1	First string. May be NULL.
str2	Second string. May be NULL.

Returns

Negative if str1 < str2, 0 if equal, positive if str1 > str2. NULL is considered less than any non-NULL string.

Note

Thread-safe: Can be called from any thread.

mupnp_strcpy()

char * mupnp_strcpy	(	char *	dest,
		const char *	src )

Copy a string (NULL-safe wrapper for strcpy)

Parameters

dest	Destination buffer. Must not be NULL and must be large enough.
src	Source string. May be NULL (dest will be set to empty string).

Returns

dest pointer.

Note

Thread-safe: Can be called from any thread.

Warning

No bounds checking is performed. Ensure dest is large enough to hold src plus null terminator.

mupnp_strdup()

char * mupnp_strdup

(

const char *

str

)

Duplicate a string (NULL-safe wrapper for strdup)

Allocates memory and creates a copy of the input string. The caller is responsible for freeing the returned string with free().

Parameters

str	The string to duplicate. May be NULL.

Returns

A newly-allocated copy of str, or NULL if str is NULL or memory allocation fails.

Note

Thread-safe: Can be called from any thread.

The returned string must be freed with free() to avoid memory leaks.

See also

free()

mupnp_streq()

bool mupnp_streq	(	const char *	str1,
		const char *	str2 )

Test if two strings are equal (NULL-safe)

Parameters

str1	First string. May be NULL.
str2	Second string. May be NULL.

Returns

true if strings are equal, false otherwise. Two NULL strings are considered equal.

Note

Thread-safe: Can be called from any thread.

mupnp_string_addrepvalue()

char * mupnp_string_addrepvalue	(	mUpnpString *	str,
		const char *	value,
		size_t	repeatCnt )

mupnp_string_addvalue()

char * mupnp_string_addvalue	(	mUpnpString *	str,
		const char *	value )

mupnp_string_clear()

void mupnp_string_clear

(

mUpnpString *

str

)

mupnp_string_delete()

void mupnp_string_delete

(

mUpnpString *

str

)

mupnp_string_getmemorysize()

size_t mupnp_string_getmemorysize

(

mUpnpString *

str

)

mupnp_string_getvalue()

char * mupnp_string_getvalue

(

mUpnpString *

str

)

mupnp_string_length()

size_t mupnp_string_length

(

mUpnpString *

str

)

mupnp_string_naddrepvalue()

char * mupnp_string_naddrepvalue	(	mUpnpString *	str,
		const char *	value,
		size_t	valueLen,
		size_t	repeatCnt )

mupnp_string_naddvalue()

char * mupnp_string_naddvalue	(	mUpnpString *	str,
		const char *	value,
		size_t	valueLen )

mupnp_string_new()

mUpnpString * mupnp_string_new

(

void

)

mupnp_string_replace()

char * mupnp_string_replace	(	mUpnpString *	str,
		char *	fromStr[],
		char *	toStr[],
		size_t	fromStrCnt )

mupnp_string_setdoublevalue()

void mupnp_string_setdoublevalue	(	mUpnpString *	str,
		double	value )

mupnp_string_setfloatvalue()

void mupnp_string_setfloatvalue	(	mUpnpString *	str,
		float	value )

mupnp_string_setintvalue()

void mupnp_string_setintvalue	(	mUpnpString *	str,
		int	value )

mupnp_string_setlongvalue()

void mupnp_string_setlongvalue	(	mUpnpString *	str,
		long	value )

mupnp_string_setnvalue()

void mupnp_string_setnvalue	(	mUpnpString *	str,
		const char *	value,
		size_t	len )

mupnp_string_setpointervalue()

void mupnp_string_setpointervalue	(	mUpnpString *	str,
		char *	value,
		size_t	len )

mupnp_string_setvalue()

void mupnp_string_setvalue	(	mUpnpString *	str,
		const char *	value )

mupnp_string_tokenizer_delete()

void mupnp_string_tokenizer_delete

(

mUpnpStringTokenizer *

strToken

)

mupnp_string_tokenizer_hasmoretoken()

bool mupnp_string_tokenizer_hasmoretoken

(

mUpnpStringTokenizer *

strToken

)

mupnp_string_tokenizer_new()

mUpnpStringTokenizer * mupnp_string_tokenizer_new	(	const char *	str,
		const char *	delim )

mupnp_string_tokenizer_nextalltoken()

char * mupnp_string_tokenizer_nextalltoken

(

mUpnpStringTokenizer *

strToken

)

mupnp_string_tokenizer_nexttoken()

char * mupnp_string_tokenizer_nexttoken

(

mUpnpStringTokenizer *

strToken

)

mupnp_string_tokenizer_print()

void mupnp_string_tokenizer_print

(

mUpnpStringTokenizer *

strToken

)

mupnp_strlen()

size_t mupnp_strlen

(

const char *

str

)

Get the length of a string (NULL-safe wrapper for strlen)

Parameters

str	The string to measure. May be NULL.

Returns

The length of str (excluding null terminator), or 0 if str is NULL.

Note

Thread-safe: Can be called from any thread.

mupnp_strltrim()

char * mupnp_strltrim	(	char *	str,
		char *	delim,
		size_t	ndelim )

Trim delimiter characters from the left (start) of string (in-place)

Parameters

str	The string to trim. Must not be NULL. Will be modified.
delim	Array of delimiter characters to remove. Must not be NULL.
ndelim	Number of characters in delim array.

Returns

Pointer to the trimmed string.

Note

Thread-safe: Can be called from any thread.

Side effect: Modifies the input string in place.

mupnp_strncat()

char * mupnp_strncat	(	char *	str1,
		const char *	str2,
		size_t	cnt )

Append at most n characters from one string to another (NULL-safe)

Parameters

str1	Destination buffer. Must not be NULL and must have sufficient space.
str2	Source string to append. May be NULL (no-op if NULL).
cnt	Maximum number of characters to append (excluding null terminator).

Returns

str1 pointer.

Note

Thread-safe: Can be called from any thread.

mupnp_strncmp()

int mupnp_strncmp	(	const char *	str1,
		const char *	str2,
		int	nchars )

Compare first n characters of two strings (NULL-safe)

Parameters

str1	First string. May be NULL.
str2	Second string. May be NULL.
nchars	Maximum number of characters to compare.

Returns

Negative if str1 < str2, 0 if equal, positive if str1 > str2.

Note

Thread-safe: Can be called from any thread.

mupnp_strncpy()

char * mupnp_strncpy	(	char *	str1,
		const char *	str2,
		size_t	cnt )

Copy at most n characters from one string to another (NULL-safe)

Parameters

str1	Destination buffer. Must not be NULL and must have space for cnt+1 bytes.
str2	Source string. May be NULL (str1 will be set to empty string).
cnt	Maximum number of characters to copy (excluding null terminator).

Returns

str1 pointer.

Note

Thread-safe: Can be called from any thread.

Always null-terminates the destination string.

mupnp_strrchr()

ssize_t mupnp_strrchr	(	const char *	str,
		const char *	chars,
		size_t	nchars )

Find last occurrence of any character from a set.

Parameters

str	The string to search. Must not be NULL.
chars	Array of characters to search for. Must not be NULL.
nchars	Number of characters in chars array.

Returns

Index of last matching character, or -1 if not found.

Note

Thread-safe: Can be called from any thread.

mupnp_strrtrim()

char * mupnp_strrtrim	(	char *	str,
		char *	delim,
		size_t	ndelim )

Trim delimiter characters from the right (end) of string (in-place)

Parameters

str	The string to trim. Must not be NULL. Will be modified.
delim	Array of delimiter characters to remove. Must not be NULL.
ndelim	Number of characters in delim array.

Returns

Pointer to the trimmed string (same as str).

Note

Thread-safe: Can be called from any thread.

Side effect: Modifies the input string in place.

mupnp_strstr()

ssize_t mupnp_strstr	(	const char *	haystack,
		const char *	needle )

Find substring (NULL-safe wrapper for strstr)

Parameters

haystack	The string to search in. May be NULL.
needle	The substring to search for. May be NULL.

Returns

Index of first occurrence of needle in haystack, or -1 if not found or if either parameter is NULL.

Note

Thread-safe: Can be called from any thread.

mupnp_strtrim()

char * mupnp_strtrim	(	char *	str,
		char *	delim,
		size_t	ndelim )

Trim specified delimiter characters from both ends (in-place)

Parameters

str	The string to trim. Must not be NULL. Will be modified.
delim	Array of delimiter characters to remove. Must not be NULL.
ndelim	Number of characters in delim array.

Returns

Pointer to the trimmed string.

Note

Thread-safe: Can be called from any thread.

Side effect: Modifies the input string in place.

mupnp_strtrimwhite()

char * mupnp_strtrimwhite

(

char *

str

)

Trim whitespace from both ends of a string (in-place)

Removes leading and trailing whitespace characters (space, tab, newline, carriage return) from the string by modifying it in place.

Parameters

str	The string to trim. Must not be NULL. Will be modified.

Returns

Pointer to the trimmed string (same as str, but offset to start of non-whitespace).

Note

Thread-safe: Can be called from any thread.

Side effect: Modifies the input string in place.