libxml2
Loading...
Searching...
No Matches
hash.h File Reference

Chained hash tables. More...

Macros

#define XML_CAST_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

xmlHashTablexmlHashCreate (int size)
 Create a new hash table.
xmlHashTablexmlHashCreateDict (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.
xmlHashTablexmlHashCopySafe (xmlHashTable *hash, xmlHashCopier copy, xmlHashDeallocator dealloc)
xmlHashTablexmlHashCopy (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.

Macro Definition Documentation

◆ XML_CAST_FPTR

#define XML_CAST_FPTR ( fptr)
Value:
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
fptrpointer to a function

Typedef Documentation

◆ xmlHashCopier

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

Callback to copy data from a hash.

Parameters
payloadthe data in the hash
namethe 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
payloadthe data in the hash
namethe 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
payloadthe data in the hash
dataextra scanner data
namethe 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
payloadthe data in the hash
dataextra scanner data
namethe name associated
name2the second name associated
name3the 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
hashhash table
keystring key
payloadpointer 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
hashhash table
keyfirst string key
key2second string key
payloadpointer 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
hashhash table
keyfirst string key
key2second string key
key3third string key
payloadpointer 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
hashhash table
keystring key
payloadpointer 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
hashhash table
keyfirst string key
key2second string key
payloadpointer 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
hashhash table
keyfirst string key
key2second string key
key3third string key
payloadpointer to the payload
Returns
0 on success and -1 in case of error.

◆ xmlHashCopy()

xmlHashTable * xmlHashCopy ( xmlHashTable * hash,
xmlHashCopier copy )
Parameters
hashhash table
copycopier 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
hashhash table
copyFunccopier function for items in the hash
deallocFuncdeallocation 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
sizeinitial 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
sizethe size of the hash table
dicta 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
entryhash table entry
keythe 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
hashhash table
deallocdeallocator function or NULL

◆ xmlHashLookup()

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

Find the entry specified by key.

Parameters
hashhash table
keystring 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
hashhash table
keyfirst string key
key2second 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
hashhash table
keyfirst string key
key2second string key
key3third 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
hashhash table
prefixprefix of the string key
namelocal 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
hashhash table
prefixfirst prefix
namefirst local name
prefix2second prefix
name2second 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
hashhash table
prefixfirst prefix
namefirst local name
prefix2second prefix
name2second local name
prefix3third prefix
name3third 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
hashhash table
keystring key
deallocdeallocator 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
hashhash table
keyfirst string key
key2second string key
deallocdeallocator 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
hashhash table
keyfirst string key
key2second string key
key3third string key
deallocdeallocator 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
hashhash table
scanscanner function for items in the hash
dataextra 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
hashhash table
keyfirst string key or NULL
key2second string key or NULL
key3third string key or NULL
scanscanner function for items in the hash
dataextra data passed to scan

◆ xmlHashScanFull()

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

Scan the hash table and apply scan to each value.

Parameters
hashhash table
scanscanner function for items in the hash
dataextra 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
hashhash table
keyfirst string key or NULL
key2second string key or NULL
key3third string key or NULL
scanscanner function for items in the hash
dataextra data passed to scan

◆ xmlHashSize()

int xmlHashSize ( xmlHashTable * hash)

Query the number of elements in the hash table.

Parameters
hashhash 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
hashhash table
keystring key
payloadpointer to the payload
deallocdeallocator 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
hashhash table
keyfirst string key
key2second string key
payloadpointer to the payload
deallocdeallocator 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
hashhash table
keyfirst string key
key2second string key
key3third string key
payloadpointer to the payload
deallocdeallocator function for replaced item or NULL
Returns
0 on success and -1 in case of error.