#

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