xmlstring: set of routines to process strings

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

## 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 the start index is out of bounds or a memory allocation failed. If len is too large, the result is truncated.