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