xmlstring.h File Reference

set of routines to process strings More...

Macros
#define	BAD_CAST   (xmlChar *)
	Macro to cast a string to an xmlChar * when one know its safe.

Typedefs
typedef unsigned char	xmlChar
	This is a basic byte in an UTF-8 encoded string.

Functions
xmlChar *	xmlStrdup (const xmlChar *cur)
	a strdup for array of xmlChar's.
xmlChar *	xmlStrndup (const xmlChar *cur, int len)
	a strndup for array of xmlChar's
xmlChar *	xmlCharStrndup (const char *cur, int len)
	a strndup for char's to xmlChar's
xmlChar *	xmlCharStrdup (const char *cur)
	a strdup for char's to xmlChar's
xmlChar *	xmlStrsub (const xmlChar *str, int start, int len)
	Extract a substring of a given string.
const xmlChar *	xmlStrchr (const xmlChar *str, xmlChar val)
	a strchr for xmlChar's
const xmlChar *	xmlStrstr (const xmlChar *str, const xmlChar *val)
	a strstr for xmlChar's
const xmlChar *	xmlStrcasestr (const xmlChar *str, const xmlChar *val)
	a case-ignoring strstr for xmlChar's
int	xmlStrcmp (const xmlChar *str1, const xmlChar *str2)
	a strcmp for xmlChar's
int	xmlStrncmp (const xmlChar *str1, const xmlChar *str2, int len)
	a strncmp for xmlChar's
int	xmlStrcasecmp (const xmlChar *str1, const xmlChar *str2)
	a strcasecmp for xmlChar's
int	xmlStrncasecmp (const xmlChar *str1, const xmlChar *str2, int len)
	a strncasecmp for xmlChar's
int	xmlStrEqual (const xmlChar *str1, const xmlChar *str2)
	Check if both strings are equal of have same content.
int	xmlStrQEqual (const xmlChar *pref, const xmlChar *name, const xmlChar *str)
	Check if a QName is Equal to a given string.
int	xmlStrlen (const xmlChar *str)
	length of a xmlChar's string
xmlChar *	xmlStrcat (xmlChar *cur, const xmlChar *add)
	a strcat for array of xmlChar's.
xmlChar *	xmlStrncat (xmlChar *cur, const xmlChar *add, int len)
	a strncat for array of xmlChar's, it will extend cur with the len first bytes of add.
xmlChar *	xmlStrncatNew (const xmlChar *str1, const xmlChar *str2, int len)
	same as xmlStrncat, but creates a new string.
int	xmlStrPrintf (xmlChar *buf, int len, const char *msg,...)
	Formats msg and places result into buf.
int	xmlStrVPrintf (xmlChar *buf, int len, const char *msg, va_list ap)
	Formats msg and places result into buf.
int	xmlGetUTF8Char (const unsigned char *utf, int *len)
	Read the first UTF8 character from utf
int	xmlCheckUTF8 (const unsigned char *utf)
	Checks utf for being valid UTF-8.
int	xmlUTF8Strsize (const xmlChar *utf, int len)
	storage size of an UTF8 string the behaviour is not guaranteed if the input string is not UTF-8
xmlChar *	xmlUTF8Strndup (const xmlChar *utf, int len)
	a strndup for array of UTF8's
const xmlChar *	xmlUTF8Strpos (const xmlChar *utf, int pos)
	a function to provide the equivalent of fetching a character from a string array
int	xmlUTF8Strloc (const xmlChar *utf, const xmlChar *utfchar)
	a function to provide the relative location of a UTF8 char
xmlChar *	xmlUTF8Strsub (const xmlChar *utf, int start, int len)
	Create a substring from a given UTF-8 string Note: positions are given in units of UTF-8 chars.
int	xmlUTF8Strlen (const xmlChar *utf)
	compute the length of an UTF8 string, it doesn't do a full UTF8 checking of the content of the string.
int	xmlUTF8Size (const xmlChar *utf)
	calculates the internal size of a UTF8 character
int	xmlUTF8Charcmp (const xmlChar *utf1, const xmlChar *utf2)
	compares the two UCS4 values

Detailed Description

set of routines to process strings

type and interfaces needed for the internal string handling of the library, especially UTF8 processing.

Copyright

See Copyright for the status of this software.

Author

Daniel Veillard

Typedef Documentation

xmlChar

typedef unsigned char xmlChar

This is a basic byte in an UTF-8 encoded string.

It's unsigned allowing to pinpoint case where char * are assigned to xmlChar * (possibly making serialization back impossible).

Function Documentation

xmlCharStrdup()

xmlChar * xmlCharStrdup

(

const char *

cur

)

a strdup for char's to xmlChar's

Parameters

cur	the input char *

Returns

a new xmlChar * or NULL

xmlCharStrndup()

xmlChar * xmlCharStrndup	(	const char *	cur,
		int	len
	)

a strndup for char's to xmlChar's

Parameters

cur	the input char *
len	the len of cur

Returns

a new xmlChar * or NULL

xmlCheckUTF8()

int xmlCheckUTF8

(

const unsigned char *

utf

)

Checks utf for being valid UTF-8.

utf is assumed to be null-terminated. This function is not super-strict, as it will allow longer UTF-8 sequences than necessary. Note that Java is capable of producing these sequences if provoked. Also note, this routine checks for the 4-byte maximum size, but does not check for 0x10ffff maximum value.

Parameters

utf	Pointer to putative UTF-8 encoded string.

Returns

value: true if utf is valid.

xmlGetUTF8Char()

int xmlGetUTF8Char	(	const unsigned char *	utf,
		int *	len
	)

Read the first UTF8 character from utf

Parameters

utf	a sequence of UTF-8 encoded bytes
len	a pointer to the minimum number of bytes present in the sequence. This is used to assure the next character is completely contained within the sequence.

Returns

the char value or -1 in case of error, and sets *len to the actual number of bytes consumed (0 in case of error)

xmlStrcasecmp()

int xmlStrcasecmp	(	const xmlChar *	str1,
		const xmlChar *	str2
	)

a strcasecmp for xmlChar's

Parameters

str1	the first xmlChar *
str2	the second xmlChar *

Returns

the integer result of the comparison

xmlStrcasestr()

const xmlChar * xmlStrcasestr	(	const xmlChar *	str,
		const xmlChar *	val
	)

a case-ignoring strstr for xmlChar's

Parameters

str	the xmlChar * array (haystack)
val	the xmlChar to search (needle)

Returns

the xmlChar * for the first occurrence or NULL.

xmlStrcat()

xmlChar * xmlStrcat	(	xmlChar *	cur,
		const xmlChar *	add
	)

a strcat for array of xmlChar's.

Since they are supposed to be encoded in UTF-8 or an encoding with 8bit based chars, we assume a termination mark of '0'.

Parameters

cur	the original xmlChar * array
add	the xmlChar * array added

Returns

a new xmlChar * containing the concatenated string. The original cur is reallocated and should not be freed.

xmlStrchr()

const xmlChar * xmlStrchr	(	const xmlChar *	str,
		xmlChar	val
	)

a strchr for xmlChar's

Parameters

str	the xmlChar * array
val	the xmlChar to search

Returns

the xmlChar * for the first occurrence or NULL.

xmlStrcmp()

int xmlStrcmp	(	const xmlChar *	str1,
		const xmlChar *	str2
	)

a strcmp for xmlChar's

Parameters

str1	the first xmlChar *
str2	the second xmlChar *

Returns

the integer result of the comparison

xmlStrdup()

xmlChar * xmlStrdup

(

const xmlChar *

cur

)

a strdup for array of xmlChar's.

Since they are supposed to be encoded in UTF-8 or an encoding with 8bit based chars, we assume a termination mark of '0'.

Parameters

cur	the input xmlChar *

Returns

a new xmlChar * or NULL

xmlStrEqual()

int xmlStrEqual	(	const xmlChar *	str1,
		const xmlChar *	str2
	)

Check if both strings are equal of have same content.

Should be a bit more readable and faster than xmlStrcmp

Parameters

str1	the first xmlChar *
str2	the second xmlChar *

Returns

1 if they are equal, 0 if they are different

xmlStrlen()

int xmlStrlen

(

const xmlChar *

str

)

length of a xmlChar's string

Parameters

str	the xmlChar * array

Returns

the number of xmlChar contained in the ARRAY.

xmlStrncasecmp()

int xmlStrncasecmp	(	const xmlChar *	str1,
		const xmlChar *	str2,
		int	len
	)

a strncasecmp for xmlChar's

Parameters

str1	the first xmlChar *
str2	the second xmlChar *
len	the max comparison length

Returns

the integer result of the comparison

xmlStrncat()

xmlChar * xmlStrncat	(	xmlChar *	cur,
		const xmlChar *	add,
		int	len
	)

a strncat for array of xmlChar's, it will extend cur with the len first bytes of add.

Note that if len < 0 then this is an API error and NULL will be returned.

Parameters

cur	the original xmlChar * array
add	the xmlChar * array added
len	the length of add

Returns

a new xmlChar *, the original cur is reallocated and should not be freed.

xmlStrncatNew()

xmlChar * xmlStrncatNew	(	const xmlChar *	str1,
		const xmlChar *	str2,
		int	len
	)

same as xmlStrncat, but creates a new string.

The original two strings are not freed. If len is < 0 then the length will be calculated automatically.

Parameters

str1	first xmlChar string
str2	second xmlChar string
len	the len of str2 or < 0

Returns

a new xmlChar * or NULL

xmlStrncmp()

int xmlStrncmp	(	const xmlChar *	str1,
		const xmlChar *	str2,
		int	len
	)

a strncmp for xmlChar's

Parameters

str1	the first xmlChar *
str2	the second xmlChar *
len	the max comparison length

Returns

the integer result of the comparison

xmlStrndup()

xmlChar * xmlStrndup	(	const xmlChar *	cur,
		int	len
	)

a strndup for array of xmlChar's

Parameters

cur	the input xmlChar *
len	the len of cur

Returns

a new xmlChar * or NULL

xmlStrPrintf()

int xmlStrPrintf	(	xmlChar *	buf,
		int	len,
		const char *	msg,
			...
	)

Formats msg and places result into buf.

Parameters

buf	the result buffer.
len	the result buffer length.
msg	the message with printf formatting.
...	extra parameters for the message.

Returns

the number of characters written to buf or -1 if an error occurs.

xmlStrQEqual()

int xmlStrQEqual	(	const xmlChar *	pref,
		const xmlChar *	name,
		const xmlChar *	str
	)

Check if a QName is Equal to a given string.

Parameters

pref	the prefix of the QName
name	the localname of the QName
str	the second xmlChar *

Returns

1 if they are equal, 0 if they are different

xmlStrstr()

const xmlChar * xmlStrstr	(	const xmlChar *	str,
		const xmlChar *	val
	)

a strstr for xmlChar's

Parameters

str	the xmlChar * array (haystack)
val	the xmlChar to search (needle)

Returns

the xmlChar * for the first occurrence or NULL.

xmlStrsub()

xmlChar * xmlStrsub	(	const xmlChar *	str,
		int	start,
		int	len
	)

Extract a substring of a given string.

Parameters

str	the xmlChar * array (haystack)
start	the index of the first char (zero based)
len	the length of the substring

Returns

the xmlChar * for the first occurrence or NULL.

xmlStrVPrintf()

int xmlStrVPrintf	(	xmlChar *	buf,
		int	len,
		const char *	msg,
		va_list	ap
	)

Formats msg and places result into buf.

Parameters

buf	the result buffer.
len	the result buffer length.
msg	the message with printf formatting.
ap	extra parameters for the message.

Returns

the number of characters written to buf or -1 if an error occurs.

xmlUTF8Charcmp()

int xmlUTF8Charcmp	(	const xmlChar *	utf1,
		const xmlChar *	utf2
	)

compares the two UCS4 values

Parameters

utf1	pointer to first UTF8 char
utf2	pointer to second UTF8 char

Returns

result of the compare as with xmlStrncmp

xmlUTF8Size()

int xmlUTF8Size

(

const xmlChar *

utf

)

calculates the internal size of a UTF8 character

Parameters

utf	pointer to the UTF8 character

Returns

the numbers of bytes in the character, -1 on format error

xmlUTF8Strlen()

int xmlUTF8Strlen

(

const xmlChar *

utf

)

compute the length of an UTF8 string, it doesn't do a full UTF8 checking of the content of the string.

Parameters

utf	a sequence of UTF-8 encoded bytes

Returns

the number of characters in the string or -1 in case of error

xmlUTF8Strloc()

int xmlUTF8Strloc	(	const xmlChar *	utf,
		const xmlChar *	utfchar
	)

a function to provide the relative location of a UTF8 char

Parameters

utf	the input UTF8 *
utfchar	the UTF8 character to be found

Returns

the relative character position of the desired char or -1 if not found

xmlUTF8Strndup()

xmlChar * xmlUTF8Strndup	(	const xmlChar *	utf,
		int	len
	)

a strndup for array of UTF8's

Parameters

utf	the input UTF8 *
len	the len of utf (in chars)

Returns

a new UTF8 * or NULL

xmlUTF8Strpos()

const xmlChar * xmlUTF8Strpos	(	const xmlChar *	utf,
		int	pos
	)

a function to provide the equivalent of fetching a character from a string array

Parameters

utf	the input UTF8 *
pos	the position of the desired UTF8 char (in chars)

Returns

a pointer to the UTF8 character or NULL

xmlUTF8Strsize()

int xmlUTF8Strsize	(	const xmlChar *	utf,
		int	len
	)

storage size of an UTF8 string the behaviour is not guaranteed if the input string is not UTF-8

Parameters

utf	a sequence of UTF-8 encoded bytes
len	the number of characters in the array

Returns

the storage size of the first 'len' characters of ARRAY

xmlUTF8Strsub()

xmlChar * xmlUTF8Strsub	(	const xmlChar *	utf,
		int	start,
		int	len
	)

Create a substring from a given UTF-8 string Note: positions are given in units of UTF-8 chars.

Parameters

utf	a sequence of UTF-8 encoded bytes
start	relative pos of first char
len	total number to copy

Returns

a pointer to a newly created string or NULL if the start index is out of bounds or a memory allocation failed. If len is too large, the result is truncated.