xmlstring: set of routines to process strings

				libxml2 Reference Manual

xmlstring

xmlstring - set of routines to process strings

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

Author(s): Daniel Veillard

Synopsis

#define BAD_CAST;
typedef unsigned char xmlChar;
int	xmlStrcmp			(const xmlChar * str1, 
					 const xmlChar * str2);
xmlChar *	xmlCharStrndup		(const char * cur, 
					 int len);
const xmlChar *	xmlStrcasestr		(const xmlChar * str, 
					 const xmlChar * val);
xmlChar *	xmlStrcat		(xmlChar * cur, 
					 const xmlChar * add);
int	xmlStrPrintf			(xmlChar * buf, 
					 int len, 
					 const char * msg, 
					 ... ...);
const xmlChar *	xmlStrstr		(const xmlChar * str, 
					 const xmlChar * val);
int	xmlUTF8Size			(const xmlChar * utf);
int	xmlStrQEqual			(const xmlChar * pref, 
					 const xmlChar * name, 
					 const xmlChar * str);
xmlChar *	xmlStrncatNew		(const xmlChar * str1, 
					 const xmlChar * str2, 
					 int len);
const xmlChar *	xmlUTF8Strpos		(const xmlChar * utf, 
					 int pos);
xmlChar *	xmlStrdup		(const xmlChar * cur);
xmlChar *	xmlCharStrdup		(const char * cur);
const xmlChar *	xmlStrchr		(const xmlChar * str, 
					 xmlChar val);
int	xmlStrlen			(const xmlChar * str);
int	xmlStrncmp			(const xmlChar * str1, 
					 const xmlChar * str2, 
					 int len);
xmlChar *	xmlStrsub		(const xmlChar * str, 
					 int start, 
					 int len);
xmlChar *	xmlStrncat		(xmlChar * cur, 
					 const xmlChar * add, 
					 int len);
int	xmlGetUTF8Char			(const unsigned char * utf, 
					 int * len);
int	xmlStrcasecmp			(const xmlChar * str1, 
					 const xmlChar * str2);
xmlChar *	xmlStrndup		(const xmlChar * cur, 
					 int len);
int	xmlStrVPrintf			(xmlChar * buf, 
					 int len, 
					 const char * msg, 
					 va_list ap);
int	xmlUTF8Strsize			(const xmlChar * utf, 
					 int len);
int	xmlCheckUTF8			(const unsigned char * utf);
int	xmlStrncasecmp			(const xmlChar * str1, 
					 const xmlChar * str2, 
					 int len);
int	xmlUTF8Strlen			(const xmlChar * utf);
xmlChar *	xmlUTF8Strsub		(const xmlChar * utf, 
					 int start, 
					 int len);
int	xmlStrEqual			(const xmlChar * str1, 
					 const xmlChar * str2);
int	xmlUTF8Charcmp			(const xmlChar * utf1, 
					 const xmlChar * utf2);
xmlChar *	xmlUTF8Strndup		(const xmlChar * utf, 
					 int len);
int	xmlUTF8Strloc			(const xmlChar * utf, 
					 const xmlChar * utfchar);

Description

Details

Macro BAD_CAST

#define BAD_CAST;

Macro to cast a string to an xmlChar * when one know its safe.

Typedef xmlChar

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

xmlCharStrdup ()

xmlChar *	xmlCharStrdup		(const char * cur)

a strdup for char's to xmlChar's

`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

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

`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

`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)

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()

`str1`:	the first xmlChar *
`str2`:	the second xmlChar *
`Returns`:	1 if they are equal, 0 if they are different

xmlStrPrintf ()

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

Formats @msg and places result into @buf.

`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

`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

xmlStrVPrintf ()

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

Formats @msg and places result into @buf.

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

xmlStrcasecmp ()

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

a strcasecmp for xmlChar's

`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

`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'.

`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

`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

`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'.

`cur`:	the input xmlChar *
`Returns`:	a new xmlChar * or NULL

xmlStrlen ()

int	xmlStrlen			(const xmlChar * str)

length of a xmlChar's string

`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

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

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

`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

`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

`cur`:	the input xmlChar *
`len`:	the len of @cur
`Returns`:	a new xmlChar * or NULL

xmlStrstr ()

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

a strstr for xmlChar's

`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

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

xmlUTF8Charcmp ()

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

compares the two UCS4 values

`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

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

`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

`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

`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

`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

`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

`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 any problem