Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

Module xmlstring from libxml2

API Menu
API Indexes
Related links

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 char * msg,
... ...)
int	xmlStrQEqual			(const xmlChar * pref, 
const xmlChar * name,
const xmlChar * str)
int	xmlStrVPrintf			(xmlChar * buf, 
int len,
const char * 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 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.

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

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. The original @cur is reallocated and should not be freed.

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

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