libxml2

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

Chained hash tables. More...

## Macros
#define | XML_CAST_FPTR(fptr) fptr
| Macro to do a casting from an object pointer to a function pointer without encountering a warning from gcc.

## Typedefs
typedef struct _xmlHashTable | xmlHashTable
| Hash table mapping strings to pointers.
typedef void(* | xmlHashDeallocator) (void *payload, const xmlChar *name)
| Callback to free data from a hash.
typedef void *(* | xmlHashCopier) (void *payload, const xmlChar *name)
| Callback to copy data from a hash.
typedef void(* | xmlHashScanner) (void *payload, void *data, const xmlChar *name)
| Callback when scanning data in a hash with the simple scanner.
typedef void(* | xmlHashScannerFull) (void *payload, void *data, const xmlChar *name, const xmlChar *name2, const xmlChar *name3)
| Callback when scanning data in a hash with the full scanner.

## Functions
xmlHashTable * | xmlHashCreate (int size)
| Create a new hash table.
xmlHashTable * | xmlHashCreateDict (int size, xmlDict *dict)
| Create a new hash table backed by a dictionary.
void | xmlHashFree (xmlHashTable *hash, xmlHashDeallocator dealloc)
| Free the hash and its contents.
void | xmlHashDefaultDeallocator (void *entry, const xmlChar *name)
| Free a hash table entry with xmlFree.
int | xmlHashAdd (xmlHashTable *hash, const xmlChar *name, void *userdata)
| Add a hash table entry.
int | xmlHashAddEntry (xmlHashTable *hash, const xmlChar *name, void *userdata)
| Add a hash table entry.
int | xmlHashUpdateEntry (xmlHashTable *hash, const xmlChar *name, void *userdata, xmlHashDeallocator dealloc)
| Add a hash table entry.
int | xmlHashAdd2 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, void *userdata)
| Add a hash table entry with two strings as key.
int | xmlHashAddEntry2 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, void *userdata)
| Add a hash table entry with two strings as key.
int | xmlHashUpdateEntry2 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, void *userdata, xmlHashDeallocator dealloc)
| Add a hash table entry with two strings as key.
int | xmlHashAdd3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, void *userdata)
| Add a hash table entry with three strings as key.
int | xmlHashAddEntry3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, void *userdata)
| Add a hash table entry with three strings as key.
int | xmlHashUpdateEntry3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, void *userdata, xmlHashDeallocator dealloc)
| Add a hash table entry with three strings as key.
int | xmlHashRemoveEntry (xmlHashTable *hash, const xmlChar *name, xmlHashDeallocator dealloc)
| Find the entry specified by the `key` and remove it from the hash table.
int | xmlHashRemoveEntry2 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, xmlHashDeallocator dealloc)
| Remove an entry with two strings as key.
int | xmlHashRemoveEntry3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, xmlHashDeallocator dealloc)
| Remove an entry with three strings as key.
void * | xmlHashLookup (xmlHashTable *hash, const xmlChar *name)
| Find the entry specified by `key`.
void * | xmlHashLookup2 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2)
| Find the payload specified by the (`key`, `key2`) tuple.
void * | xmlHashLookup3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3)
| Find the payload specified by the (`key`, `key2`, `key3`) tuple.
void * | xmlHashQLookup (xmlHashTable *hash, const xmlChar *prefix, const xmlChar *name)
| Find the payload specified by the QName `prefix:name` or `name`.
void * | xmlHashQLookup2 (xmlHashTable *hash, const xmlChar *prefix, const xmlChar *name, const xmlChar *prefix2, const xmlChar *name2)
| Find the payload specified by the QNames tuple.
void * | xmlHashQLookup3 (xmlHashTable *hash, const xmlChar *prefix, const xmlChar *name, const xmlChar *prefix2, const xmlChar *name2, const xmlChar *prefix3, const xmlChar *name3)
| Find the payload specified by the QNames tuple.
xmlHashTable * | xmlHashCopySafe (xmlHashTable *hash, xmlHashCopier copy, xmlHashDeallocator dealloc)
xmlHashTable * | xmlHashCopy (xmlHashTable *hash, xmlHashCopier copy)
int | xmlHashSize (xmlHashTable *hash)
| Query the number of elements in the hash table.
void | xmlHashScan (xmlHashTable *hash, xmlHashScanner scan, void *data)
| Scan the hash `table` and apply `scan` to each value.
void | xmlHashScan3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, xmlHashScanner scan, void *data)
| Scan the hash `table` and apply `scan` to each value matching (`key`, `key2`, `key3`) tuple.
void | xmlHashScanFull (xmlHashTable *hash, xmlHashScannerFull scan, void *data)
| Scan the hash `table` and apply `scan` to each value.
void | xmlHashScanFull3 (xmlHashTable *hash, const xmlChar *name, const xmlChar *name2, const xmlChar *name3, xmlHashScannerFull scan, void *data)
| Scan the hash `table` and apply `scan` to each value matching (`key`, `key2`, `key3`) tuple.

## Detailed Description

Chained hash tables.

This module implements the hash table support used in various places in the library.

Copyright
  See Copyright for the status of this software.

## Macro Definition Documentation

## ◆ XML_CAST_FPTR

#define XML_CAST_FPTR | ( |  | fptr | ) | fptr

Macro to do a casting from an object pointer to a function pointer without encountering a warning from gcc.

#define XML_CAST_FPTR(fptr) (*(void **)(&fptr)) This macro violated ISO C aliasing rules (gcc4 on s390 broke) so it is disabled now

Parameters

  fptr | pointer to a function

## Typedef Documentation

## ◆ xmlHashCopier

typedef void *(* xmlHashCopier) (void *payload, const xmlChar *name)

Callback to copy data from a hash.

Parameters

  payload | the data in the hash
  name | the name associated

Returns
  a copy of the data or NULL in case of error.

## ◆ xmlHashDeallocator

typedef void(* xmlHashDeallocator) (void *payload, const xmlChar *name)

Callback to free data from a hash.

Parameters

  payload | the data in the hash
  name | the name associated

## ◆ xmlHashScanner

typedef void(* xmlHashScanner) (void *payload, void *data, const xmlChar *name)

Callback when scanning data in a hash with the simple scanner.

Parameters

  payload | the data in the hash
  data | extra scanner data
  name | the name associated

## ◆ xmlHashScannerFull

typedef void(* xmlHashScannerFull) (void *payload, void *data, const xmlChar *name, const xmlChar *name2, const xmlChar *name3)

Callback when scanning data in a hash with the full scanner.

Parameters

  payload | the data in the hash
  data | extra scanner data
  name | the name associated
  name2 | the second name associated
  name3 | the third name associated

## ◆ xmlHashTable

typedef struct _xmlHashTable xmlHashTable

Hash table mapping strings to pointers.

Also supports lookup using two or three strings as key.

## Function Documentation

## ◆ xmlHashAdd()

int xmlHashAdd | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | void * | payload
| ) |  |

Add a hash table entry.

If an entry with this key already exists, payload will not be updated and 0 is returned. This return value can't be distinguished from out-of-memory errors, so this function should be used with care.

Since
  2.13.0

Parameters

  hash | hash table
  key | string key
  payload | pointer to the payload

Returns
  1 on success, 0 if an entry exists and -1 in case of error.

## ◆ xmlHashAdd2()

int xmlHashAdd2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | void * | payload
| ) |  |

Add a hash table entry with two strings as key.

See xmlHashAdd.

Since
  2.13.0

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  payload | pointer to the payload

Returns
  1 on success, 0 if an entry exists and -1 in case of error.

## ◆ xmlHashAdd3()

int xmlHashAdd3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | void * | payload
| ) |  |

Add a hash table entry with three strings as key.

See xmlHashAdd.

Since
  2.13.0

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  key3 | third string key
  payload | pointer to the payload

Returns
  1 on success, 0 if an entry exists and -1 in case of error.

## ◆ xmlHashAddEntry()

int xmlHashAddEntry | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | void * | payload
| ) |  |

Add a hash table entry.

If an entry with this key already exists, payload will not be updated and -1 is returned. This return value can't be distinguished from out-of-memory errors, so this function should be used with care.

NOTE: This function doesn't allow to distinguish malloc failures from existing entries. Use xmlHashAdd instead.

Parameters

  hash | hash table
  key | string key
  payload | pointer to the payload

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashAddEntry2()

int xmlHashAddEntry2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | void * | payload
| ) |  |

Add a hash table entry with two strings as key.

See xmlHashAddEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  payload | pointer to the payload

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashAddEntry3()

int xmlHashAddEntry3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | void * | payload
| ) |  |

Add a hash table entry with three strings as key.

See xmlHashAddEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  key3 | third string key
  payload | pointer to the payload

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashCopy()

xmlHashTable * xmlHashCopy | ( | xmlHashTable * | hash,
|  | xmlHashCopier | copy
| ) |  |

Parameters

  hash | hash table
  copy | copier function for items in the hash

Deprecated:
  Leaks memory in error case.

Copy the hash table using `copy` to copy payloads.

Returns
  the new table or NULL if a memory allocation failed.

## ◆ xmlHashCopySafe()

xmlHashTable * xmlHashCopySafe | ( | xmlHashTable * | hash,
|  | xmlHashCopier | copyFunc,
|  | xmlHashDeallocator | deallocFunc
| ) |  |

Parameters

  hash | hash table
  copyFunc | copier function for items in the hash
  deallocFunc | deallocation function in case of errors

Copy the hash table using `copyFunc` to copy payloads.

Since
  2.13.0

Returns
  the new table or NULL if a memory allocation failed.

## ◆ xmlHashCreate()

xmlHashTable * xmlHashCreate | ( | int | size | ) |

Create a new hash table.

Set size to zero if the number of entries can't be estimated.

Parameters

  size | initial size of the hash table

Returns
  the newly created object, or NULL if a memory allocation failed.

## ◆ xmlHashCreateDict()

xmlHashTable * xmlHashCreateDict | ( | int | size,
|  | xmlDict * | dict
| ) |  |

Create a new hash table backed by a dictionary.

This can reduce resource usage considerably if most keys passed to API functions originate from this dictionary.

Parameters

  size | the size of the hash table
  dict | a dictionary to use for the hash

Returns
  the newly created object, or NULL if a memory allocation failed.

## ◆ xmlHashDefaultDeallocator()

void xmlHashDefaultDeallocator | ( | void * | entry,
|  | const xmlChar * | key
| ) |  |

Free a hash table entry with xmlFree.

Parameters

  entry | hash table entry
  key | the entry's string key

## ◆ xmlHashFree()

void xmlHashFree | ( | xmlHashTable * | hash,
|  | xmlHashDeallocator | dealloc
| ) |  |

Free the hash and its contents.

The payload is deallocated with `dealloc` if provided.

Parameters

  hash | hash table
  dealloc | deallocator function or NULL

## ◆ xmlHashLookup()

void * xmlHashLookup | ( | xmlHashTable * | hash,
|  | const xmlChar * | key
| ) |  |

Find the entry specified by `key`.

Parameters

  hash | hash table
  key | string key

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashLookup2()

void * xmlHashLookup2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2
| ) |  |

Find the payload specified by the (`key`, `key2`) tuple.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashLookup3()

void * xmlHashLookup3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3
| ) |  |

Find the payload specified by the (`key`, `key2`, `key3`) tuple.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  key3 | third string key

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashQLookup()

void * xmlHashQLookup | ( | xmlHashTable * | hash,
|  | const xmlChar * | prefix,
|  | const xmlChar * | name
| ) |  |

Find the payload specified by the QName `prefix:name` or `name`.

Parameters

  hash | hash table
  prefix | prefix of the string key
  name | local name of the string key

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashQLookup2()

void * xmlHashQLookup2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | prefix,
|  | const xmlChar * | name,
|  | const xmlChar * | prefix2,
|  | const xmlChar * | name2
| ) |  |

Find the payload specified by the QNames tuple.

Parameters

  hash | hash table
  prefix | first prefix
  name | first local name
  prefix2 | second prefix
  name2 | second local name

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashQLookup3()

void * xmlHashQLookup3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | prefix,
|  | const xmlChar * | name,
|  | const xmlChar * | prefix2,
|  | const xmlChar * | name2,
|  | const xmlChar * | prefix3,
|  | const xmlChar * | name3
| ) |  |

Find the payload specified by the QNames tuple.

Parameters

  hash | hash table
  prefix | first prefix
  name | first local name
  prefix2 | second prefix
  name2 | second local name
  prefix3 | third prefix
  name3 | third local name

Returns
  a pointer to the payload or NULL if no entry was found.

## ◆ xmlHashRemoveEntry()

int xmlHashRemoveEntry | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | xmlHashDeallocator | dealloc
| ) |  |

Find the entry specified by the `key` and remove it from the hash table.

Payload will be freed with `dealloc`.

Parameters

  hash | hash table
  key | string key
  dealloc | deallocator function for removed item or NULL

Returns
  0 on success and -1 if no entry was found.

## ◆ xmlHashRemoveEntry2()

int xmlHashRemoveEntry2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | xmlHashDeallocator | dealloc
| ) |  |

Remove an entry with two strings as key.

See xmlHashRemoveEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  dealloc | deallocator function for removed item or NULL

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashRemoveEntry3()

int xmlHashRemoveEntry3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | xmlHashDeallocator | dealloc
| ) |  |

Remove an entry with three strings as key.

See xmlHashRemoveEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  key3 | third string key
  dealloc | deallocator function for removed item or NULL

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashScan()

void xmlHashScan | ( | xmlHashTable * | hash,
|  | xmlHashScanner | scan,
|  | void * | data
| ) |  |

Scan the hash `table` and apply `scan` to each value.

Parameters

  hash | hash table
  scan | scanner function for items in the hash
  data | extra data passed to `scan`

## ◆ xmlHashScan3()

void xmlHashScan3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | xmlHashScanner | scan,
|  | void * | data
| ) |  |

Scan the hash `table` and apply `scan` to each value matching (`key`, `key2`, `key3`) tuple.

If one of the keys is null, the comparison is considered to match.

Parameters

  hash | hash table
  key | first string key or NULL
  key2 | second string key or NULL
  key3 | third string key or NULL
  scan | scanner function for items in the hash
  data | extra data passed to `scan`

## ◆ xmlHashScanFull()

void xmlHashScanFull | ( | xmlHashTable * | hash,
|  | xmlHashScannerFull | scan,
|  | void * | data
| ) |  |

Scan the hash `table` and apply `scan` to each value.

Parameters

  hash | hash table
  scan | scanner function for items in the hash
  data | extra data passed to `scan`

## ◆ xmlHashScanFull3()

void xmlHashScanFull3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | xmlHashScannerFull | scan,
|  | void * | data
| ) |  |

Scan the hash `table` and apply `scan` to each value matching (`key`, `key2`, `key3`) tuple.

If one of the keys is null, the comparison is considered to match.

Parameters

  hash | hash table
  key | first string key or NULL
  key2 | second string key or NULL
  key3 | third string key or NULL
  scan | scanner function for items in the hash
  data | extra data passed to `scan`

## ◆ xmlHashSize()

int xmlHashSize | ( | xmlHashTable * | hash | ) |

Query the number of elements in the hash table.

Parameters

  hash | hash table

Returns
  the number of elements in the hash table or -1 in case of error.

## ◆ xmlHashUpdateEntry()

int xmlHashUpdateEntry | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | void * | payload,
|  | xmlHashDeallocator | dealloc
| ) |  |

Add a hash table entry.

If an entry with this key already exists, the old payload will be freed and updated with the new value.

Parameters

  hash | hash table
  key | string key
  payload | pointer to the payload
  dealloc | deallocator function for replaced item or NULL

Returns
  0 in case of success, -1 if a memory allocation failed.

## ◆ xmlHashUpdateEntry2()

int xmlHashUpdateEntry2 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | void * | payload,
|  | xmlHashDeallocator | dealloc
| ) |  |

Add a hash table entry with two strings as key.

See xmlHashUpdateEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  payload | pointer to the payload
  dealloc | deallocator function for replaced item or NULL

Returns
  0 on success and -1 in case of error.

## ◆ xmlHashUpdateEntry3()

int xmlHashUpdateEntry3 | ( | xmlHashTable * | hash,
|  | const xmlChar * | key,
|  | const xmlChar * | key2,
|  | const xmlChar * | key3,
|  | void * | payload,
|  | xmlHashDeallocator | dealloc
| ) |  |

Add a hash table entry with three strings as key.

See xmlHashUpdateEntry.

Parameters

  hash | hash table
  key | first string key
  key2 | second string key
  key3 | third string key
  payload | pointer to the payload
  dealloc | deallocator function for replaced item or NULL

Returns
  0 on success and -1 in case of error.