Module xmlstring from libxml2
Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

Module xmlstring from libxml2

API Menu
API Indexes
Related links
PrevxmlschemastypesUpAPI documentationHomeThe XML C parser and toolkit of GnomexmlunicodeNext

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

Table of Contents

#define BAD_CAST
Typedef unsigned char xmlChar

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

Description

Macro: BAD_CAST

#define BAD_CAST

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

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

xmlChar *	xmlCharStrdup		(const char * cur)

a strdup for char's to xmlChar's

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

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

Function: 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.

Function: 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)

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

Function: xmlStrPrintf

int	xmlStrPrintf			(xmlChar * buf, 
					 int len, 
					 const xmlChar * 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.

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

Function: xmlStrVPrintf

int	xmlStrVPrintf			(xmlChar * buf, 
					 int len, 
					 const xmlChar * 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.

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

Function: 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.

Function: 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.

Function: 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.

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

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

Function: 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.

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

Function: 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 if needed and should not be freed

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

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

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

Function: 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.

Function: 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.

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

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

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

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

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

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

Function: xmlUTF8Strsize

int	xmlUTF8Strsize			(const xmlChar * utf, 
					 int len)

storage size of an UTF8 string the behaviour is not garanteed 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

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

Daniel Veillard