# ## Module xmlstring from libxml2

API Menu
Main Menu Developer Menu Code Examples API Menu Parser API Tree API Reader API XML Guidelines ChangeLog
API Indexes
Alphabetic Constructors Functions/Types Modules Symbols
Related links
Mail archive XSLT libxslt DOM gdome2 XML-DSig xmlsec FTP Windows binaries Solaris binaries MacOsX binaries lxml Python bindings Perl bindings C++ bindings PHP bindings Pascal bindings Ruby bindings Tcl bindings Bug Tracker
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.
### 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