hash: Chained hash tables

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