Prev Up Home Next libxml2 Reference Manual

hash

hash - Chained hash tables

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

Author(s): Bjorn Reese <bjorn.reese@systematic.dk>

Synopsis

#define XML_CAST_FPTR(fptr);
typedef struct _xmlHashTable xmlHashTable;
typedef xmlHashTable * xmlHashTablePtr;
int	xmlHashAdd			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 void * payload);
int	xmlHashAdd2			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 void * payload);
int	xmlHashAdd3			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 void * payload);
int	xmlHashAddEntry			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 void * payload);
int	xmlHashAddEntry2		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 void * payload);
int	xmlHashAddEntry3		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 void * payload);
typedef void * xmlHashCopier			(void * payload, 
					 const xmlChar * name);
xmlHashTablePtr	xmlHashCopy		(xmlHashTablePtr hash, 
					 xmlHashCopier copy);
xmlHashTablePtr	xmlHashCopySafe		(xmlHashTablePtr hash, 
					 xmlHashCopier copyFunc, 
					 xmlHashDeallocator deallocFunc);
xmlHashTablePtr	xmlHashCreate		(int size);
xmlHashTablePtr	xmlHashCreateDict	(int size, 
					 xmlDictPtr dict);
typedef void xmlHashDeallocator		(void * payload, 
					 const xmlChar * name);
void	xmlHashDefaultDeallocator	(void * entry, 
					 const xmlChar * key);
void	xmlHashFree			(xmlHashTablePtr hash, 
					 xmlHashDeallocator dealloc);
void *	xmlHashLookup			(xmlHashTablePtr hash, 
					 const xmlChar * key);
void *	xmlHashLookup2			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2);
void *	xmlHashLookup3			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3);
void *	xmlHashQLookup			(xmlHashTablePtr hash, 
					 const xmlChar * prefix, 
					 const xmlChar * name);
void *	xmlHashQLookup2			(xmlHashTablePtr hash, 
					 const xmlChar * prefix, 
					 const xmlChar * name, 
					 const xmlChar * prefix2, 
					 const xmlChar * name2);
void *	xmlHashQLookup3			(xmlHashTablePtr hash, 
					 const xmlChar * prefix, 
					 const xmlChar * name, 
					 const xmlChar * prefix2, 
					 const xmlChar * name2, 
					 const xmlChar * prefix3, 
					 const xmlChar * name3);
int	xmlHashRemoveEntry		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 xmlHashDeallocator dealloc);
int	xmlHashRemoveEntry2		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 xmlHashDeallocator dealloc);
int	xmlHashRemoveEntry3		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 xmlHashDeallocator dealloc);
void	xmlHashScan			(xmlHashTablePtr hash, 
					 xmlHashScanner scan, 
					 void * data);
void	xmlHashScan3			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 xmlHashScanner scan, 
					 void * data);
void	xmlHashScanFull			(xmlHashTablePtr hash, 
					 xmlHashScannerFull scan, 
					 void * data);
void	xmlHashScanFull3		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 xmlHashScannerFull scan, 
					 void * data);
typedef void xmlHashScanner			(void * payload, 
					 void * data, 
					 const xmlChar * name);
typedef void xmlHashScannerFull		(void * payload, 
					 void * data, 
					 const xmlChar * name, 
					 const xmlChar * name2, 
					 const xmlChar * name3);
int	xmlHashSize			(xmlHashTablePtr hash);
int	xmlHashUpdateEntry		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 void * payload, 
					 xmlHashDeallocator dealloc);
int	xmlHashUpdateEntry2		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 void * payload, 
					 xmlHashDeallocator dealloc);
int	xmlHashUpdateEntry3		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 void * payload, 
					 xmlHashDeallocator dealloc);

Description

Details

Macro XML_CAST_FPTR

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

fptr: pointer to a function

Structure xmlHashTable

struct _xmlHashTable {
The content of this structure is not made public by the API.
} xmlHashTable;

Typedef xmlHashTablePtr

xmlHashTable * xmlHashTablePtr;

Function type xmlHashCopier

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

Callback to copy data from a hash.

payload: the data in the hash
name: the name associated
Returns: a copy of the data or NULL in case of error.

Function type xmlHashDeallocator

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

Callback to free data from a hash.

payload: the data in the hash
name: the name associated

Function type xmlHashScanner

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

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

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

Function type xmlHashScannerFull

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.

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

xmlHashAdd ()

int	xmlHashAdd			(xmlHashTablePtr 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. Available since 2.13.0.

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			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 void * payload)

Add a hash table entry with two strings as key. See xmlHashAdd. Available since 2.13.0.

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			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 void * payload)

Add a hash table entry with three strings as key. See xmlHashAdd. Available since 2.13.0.

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			(xmlHashTablePtr 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.

hash: hash table
key: string key
payload: pointer to the payload
Returns: 0 on success and -1 in case of error.

xmlHashAddEntry2 ()

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

Add a hash table entry with two strings as key. See xmlHashAddEntry.

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		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 void * payload)

Add a hash table entry with three strings as key. See xmlHashAddEntry.

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 ()

xmlHashTablePtr	xmlHashCopy		(xmlHashTablePtr hash, 
					 xmlHashCopier copy)

DEPRECATED: Leaks memory in error case. Copy the hash table using @copy to copy payloads.

hash: hash table
copy: copier function for items in the hash
Returns: the new table or NULL if a memory allocation failed.

xmlHashCopySafe ()

xmlHashTablePtr	xmlHashCopySafe		(xmlHashTablePtr hash, 
					 xmlHashCopier copyFunc, 
					 xmlHashDeallocator deallocFunc)

Copy the hash table using @copyFunc to copy payloads. Available since 2.13.0.

hash: hash table
copyFunc: copier function for items in the hash
deallocFunc: deallocation function in case of errors
Returns: the new table or NULL if a memory allocation failed.

xmlHashCreate ()

xmlHashTablePtr	xmlHashCreate		(int size)

Create a new hash table. Set size to zero if the number of entries can't be estimated.

size: initial size of the hash table
Returns: the newly created object, or NULL if a memory allocation failed.

xmlHashCreateDict ()

xmlHashTablePtr	xmlHashCreateDict	(int size, 
					 xmlDictPtr 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.

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.

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

xmlHashFree ()

void	xmlHashFree			(xmlHashTablePtr hash, 
					 xmlHashDeallocator dealloc)

Free the hash and its contents. The payload is deallocated with @dealloc if provided.

hash: hash table
dealloc: deallocator function or NULL

xmlHashLookup ()

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

Find the entry specified by @key.

hash: hash table
key: string key
Returns: a pointer to the payload or NULL if no entry was found.

xmlHashLookup2 ()

void *	xmlHashLookup2			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2)

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

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			(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3)

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

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			(xmlHashTablePtr hash, 
					 const xmlChar * prefix, 
					 const xmlChar * name)

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

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			(xmlHashTablePtr hash, 
					 const xmlChar * prefix, 
					 const xmlChar * name, 
					 const xmlChar * prefix2, 
					 const xmlChar * name2)

Find the payload specified by the QNames tuple.

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			(xmlHashTablePtr 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.

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		(xmlHashTablePtr 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.

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		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 xmlHashDeallocator dealloc)

Remove an entry with two strings as key. See xmlHashRemoveEntry.

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		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 const xmlChar * key3, 
					 xmlHashDeallocator dealloc)

Remove an entry with three strings as key. See xmlHashRemoveEntry.

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			(xmlHashTablePtr hash, 
					 xmlHashScanner scan, 
					 void * data)

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

hash: hash table
scan: scanner function for items in the hash
data: extra data passed to @scan

xmlHashScan3 ()

void	xmlHashScan3			(xmlHashTablePtr 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.

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			(xmlHashTablePtr hash, 
					 xmlHashScannerFull scan, 
					 void * data)

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

hash: hash table
scan: scanner function for items in the hash
data: extra data passed to @scan

xmlHashScanFull3 ()

void	xmlHashScanFull3		(xmlHashTablePtr 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.

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			(xmlHashTablePtr hash)

Query the number of elements in the hash table.

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

xmlHashUpdateEntry ()

int	xmlHashUpdateEntry		(xmlHashTablePtr 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.

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		(xmlHashTablePtr hash, 
					 const xmlChar * key, 
					 const xmlChar * key2, 
					 void * payload, 
					 xmlHashDeallocator dealloc)

Add a hash table entry with two strings as key. See xmlHashUpdateEntry.

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		(xmlHashTablePtr 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.

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.