libxml2: xmlstring.h File Reference

libxml2

Loading...
Searching...
No Matches
Macros | Typedefs | Functions
xmlstring.h File Reference

set of routines to process strings More...

## Macros
#define | BAD_CAST (xmlChar *)
| Macro to cast a string to an xmlChar * when one know its safe.

## Typedefs
typedef unsigned char | xmlChar
| This is a basic byte in an UTF-8 encoded string.

## Functions
xmlChar * | xmlStrdup (const xmlChar *cur)
| a strdup for array of xmlChar's.
xmlChar * | xmlStrndup (const xmlChar *cur, int len)
| a strndup for array of xmlChar's
xmlChar * | xmlCharStrndup (const char *cur, int len)
| a strndup for char's to xmlChar's
xmlChar * | xmlCharStrdup (const char *cur)
| a strdup for char's to xmlChar's
xmlChar * | xmlStrsub (const xmlChar *str, int start, int len)
| Extract a substring of a given string.
const xmlChar * | xmlStrchr (const xmlChar *str, xmlChar val)
| a strchr for xmlChar's
const xmlChar * | xmlStrstr (const xmlChar *str, const xmlChar *val)
| a strstr for xmlChar's
const xmlChar * | xmlStrcasestr (const xmlChar *str, const xmlChar *val)
| a case-ignoring strstr for xmlChar's
int | xmlStrcmp (const xmlChar *str1, const xmlChar *str2)
| a strcmp for xmlChar's
int | xmlStrncmp (const xmlChar *str1, const xmlChar *str2, int len)
| a strncmp for xmlChar's
int | xmlStrcasecmp (const xmlChar *str1, const xmlChar *str2)
| a strcasecmp for xmlChar's
int | xmlStrncasecmp (const xmlChar *str1, const xmlChar *str2, int len)
| a strncasecmp for xmlChar's
int | xmlStrEqual (const xmlChar *str1, const xmlChar *str2)
| Check if both strings are equal of have same content.
int | xmlStrQEqual (const xmlChar *pref, const xmlChar *name, const xmlChar *str)
| Check if a QName is Equal to a given string.
int | xmlStrlen (const xmlChar *str)
| length of a xmlChar's string
xmlChar * | xmlStrcat (xmlChar *cur, const xmlChar *add)
| a strcat for array of xmlChar's.
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`.
xmlChar * | xmlStrncatNew (const xmlChar *str1, const xmlChar *str2, int len)
| same as xmlStrncat, but creates a new string.
int | xmlStrPrintf (xmlChar *buf, int len, const char *msg,...)
| Formats `msg` and places result into `buf`.
int | xmlStrVPrintf (xmlChar *buf, int len, const char *msg, va_list ap)
| Formats `msg` and places result into `buf`.
int | xmlGetUTF8Char (const unsigned char *utf, int *len)
| Read the first UTF8 character from `utf`
int | xmlCheckUTF8 (const unsigned char *utf)
| Checks `utf` for being valid UTF-8.
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
xmlChar * | xmlUTF8Strndup (const xmlChar *utf, int len)
| a strndup for array of UTF8's
const xmlChar * | xmlUTF8Strpos (const xmlChar *utf, int pos)
| a function to provide the equivalent of fetching a character from a string array
int | xmlUTF8Strloc (const xmlChar *utf, const xmlChar *utfchar)
| a function to provide the relative location of a UTF8 char
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.
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.
int | xmlUTF8Size (const xmlChar *utf)
| calculates the internal size of a UTF8 character
int | xmlUTF8Charcmp (const xmlChar *utf1, const xmlChar *utf2)
| compares the two UCS4 values

## Detailed Description

set of routines to process strings

type and interfaces needed for the internal string handling of the library, especially UTF8 processing.

Copyright
  See Copyright for the status of this software.

Author
  Daniel Veillard

## Typedef Documentation

## ◆ xmlChar

typedef 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).

## Function Documentation

## ◆ xmlCharStrdup()

xmlChar * xmlCharStrdup | ( | const char * | cur | ) |

a strdup for char's to xmlChar's

Parameters

  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

Parameters

  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.

Parameters

  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`

Parameters

  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)

## ◆ xmlStrcasecmp()

int xmlStrcasecmp | ( | const xmlChar * | str1,
|  | const xmlChar * | str2
| ) |  |

a strcasecmp for xmlChar's

Parameters

  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

Parameters

  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'.

Parameters

  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

Parameters

  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

Parameters

  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'.

Parameters

  cur | the input xmlChar *

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

Parameters

  str1 | the first xmlChar *
  str2 | the second xmlChar *

Returns
  1 if they are equal, 0 if they are different

## ◆ xmlStrlen()

int xmlStrlen | ( | const xmlChar * | str | ) |

length of a xmlChar's string

Parameters

  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

Parameters

  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.

Parameters

  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.

Parameters

  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

Parameters

  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

Parameters

  cur | the input xmlChar *
  len | the len of `cur`

Returns
  a new xmlChar * or NULL

## ◆ xmlStrPrintf()

int xmlStrPrintf | ( | xmlChar * | buf,
|  | int | len,
|  | const char * | msg,
|  |  | ...
| ) |  |

Formats `msg` and places result into `buf`.

Parameters

  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.

Parameters

  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

## ◆ xmlStrstr()

const xmlChar * xmlStrstr | ( | const xmlChar * | str,
|  | const xmlChar * | val
| ) |  |

a strstr for xmlChar's

Parameters

  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.

Parameters

  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.

## ◆ xmlStrVPrintf()

int xmlStrVPrintf | ( | xmlChar * | buf,
|  | int | len,
|  | const char * | msg,
|  | va_list | ap
| ) |  |

Formats `msg` and places result into `buf`.

Parameters

  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.

## ◆ xmlUTF8Charcmp()

int xmlUTF8Charcmp | ( | const xmlChar * | utf1,
|  | const xmlChar * | utf2
| ) |  |

compares the two UCS4 values

Parameters

  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

Parameters

  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.

Parameters

  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

Parameters

  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

Parameters

  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

Parameters

  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

Parameters

  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.

Parameters

  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.