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;
int	xmlStrcmp			(const xmlChar * str1, 
const xmlChar * str2); xmlChar * xmlCharStrndup (const char * cur,
int len); const xmlChar * xmlStrcasestr (const xmlChar * str,
const xmlChar * val); xmlChar * xmlStrcat (xmlChar * cur,
const xmlChar * add); int xmlStrPrintf (xmlChar * buf,
int len,
const char * msg,
... ...); const xmlChar * xmlStrstr (const xmlChar * str,
const xmlChar * val); int xmlUTF8Size (const xmlChar * utf); int xmlStrQEqual (const xmlChar * pref,
const xmlChar * name,
const xmlChar * str); xmlChar * xmlStrncatNew (const xmlChar * str1,
const xmlChar * str2,
int len); const xmlChar * xmlUTF8Strpos (const xmlChar * utf,
int pos); xmlChar * xmlStrdup (const xmlChar * cur); xmlChar * xmlCharStrdup (const char * cur); const xmlChar * xmlStrchr (const xmlChar * str,
xmlChar val); int xmlStrlen (const xmlChar * str); int xmlStrncmp (const xmlChar * str1,
const xmlChar * str2,
int len); xmlChar * xmlStrsub (const xmlChar * str,
int start,
int len); xmlChar * xmlStrncat (xmlChar * cur,
const xmlChar * add,
int len); int xmlGetUTF8Char (const unsigned char * utf,
int * len); int xmlStrcasecmp (const xmlChar * str1,
const xmlChar * str2); xmlChar * xmlStrndup (const xmlChar * cur,
int len); int xmlStrVPrintf (xmlChar * buf,
int len,
const char * msg,
va_list ap); int xmlUTF8Strsize (const xmlChar * utf,
int len); int xmlCheckUTF8 (const unsigned char * utf); int xmlStrncasecmp (const xmlChar * str1,
const xmlChar * str2,
int len); int xmlUTF8Strlen (const xmlChar * utf); xmlChar * xmlUTF8Strsub (const xmlChar * utf,
int start,
int len); int xmlStrEqual (const xmlChar * str1,
const xmlChar * str2); int xmlUTF8Charcmp (const xmlChar * utf1,
const xmlChar * utf2); xmlChar * xmlUTF8Strndup (const xmlChar * utf,
int len); int xmlUTF8Strloc (const xmlChar * utf,
const xmlChar * utfchar);

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



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.

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

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