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;
    void	xmlHashScanFull			(xmlHashTablePtr table,
    					 xmlHashScannerFull f,
    					 void * data);
    void	xmlHashScan			(xmlHashTablePtr table,
    					 xmlHashScanner f,
    					 void * data);
    typedef void xmlHashScannerFull		(void * payload,
    					 void * data,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3);
    xmlHashTablePtr	xmlHashCreateDict	(int size,
    					 xmlDictPtr dict);
    int	xmlHashAddEntry			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 void * userdata);
    int	xmlHashUpdateEntry		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 void * userdata,
    					 xmlHashDeallocator f);
    void *	xmlHashQLookup3			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name,
    					 const xmlChar * prefix2,
    					 const xmlChar * name2,
    					 const xmlChar * prefix3,
    					 const xmlChar * name3);
    void *	xmlHashQLookup2			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name,
    					 const xmlChar * prefix2,
    					 const xmlChar * name2);
    void	xmlHashScan3			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashScanner f,
    					 void * data);
    typedef void xmlHashScanner			(void * payload,
    					 void * data,
    					 xmlChar * name);
    typedef void xmlHashDeallocator		(void * payload,
    					 xmlChar * name);
    xmlHashTablePtr	xmlHashCreate		(int size);
    void	xmlHashFree			(xmlHashTablePtr table,
    					 xmlHashDeallocator f);
    void *	xmlHashLookup			(xmlHashTablePtr table,
    					 const xmlChar * name);
    void *	xmlHashQLookup			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name);
    int	xmlHashUpdateEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 void * userdata,
    					 xmlHashDeallocator f);
    int	xmlHashRemoveEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 xmlHashDeallocator f);
    int	xmlHashRemoveEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashDeallocator f);
    xmlHashTablePtr	xmlHashCopy		(xmlHashTablePtr table,
    					 xmlHashCopier f);
    void	xmlHashScanFull3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashScannerFull f,
    					 void * data);
    int	xmlHashUpdateEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 void * userdata,
    					 xmlHashDeallocator f);
    void *	xmlHashLookup3			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3);
    void *	xmlHashLookup2			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2);
    int	xmlHashRemoveEntry		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 xmlHashDeallocator f);
    typedef void * xmlHashCopier			(void * payload,
    					 xmlChar * name);
    int	xmlHashAddEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 void * userdata);
    int	xmlHashAddEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 void * userdata);
    int	xmlHashSize			(xmlHashTablePtr table);

## 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,
    					 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,
    					 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,
    					 xmlChar * name)

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

`payload`: | the data in the hash
`data`: | extra scannner 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 scannner data
`name`: | the name associated
`name2`: | the second name associated
`name3`: | the third name associated

### xmlHashAddEntry ()

    int	xmlHashAddEntry			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 void * userdata)

Add the @userdata to the hash @table. This can later be retrieved by using the @name. Duplicate names generate errors.

`table`: | the hash table
`name`: | the name of the userdata
`userdata`: | a pointer to the userdata
`Returns`: | 0 the addition succeeded and -1 in case of error.

### xmlHashAddEntry2 ()

    int	xmlHashAddEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 void * userdata)

Add the @userdata to the hash @table. This can later be retrieved by using the (@name, @name2) tuple. Duplicate tuples generate errors.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`userdata`: | a pointer to the userdata
`Returns`: | 0 the addition succeeded and -1 in case of error.

### xmlHashAddEntry3 ()

    int	xmlHashAddEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 void * userdata)

Add the @userdata to the hash @table. This can later be retrieved by using the tuple (@name, @name2, @name3). Duplicate entries generate errors.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`name3`: | a third name of the userdata
`userdata`: | a pointer to the userdata
`Returns`: | 0 the addition succeeded and -1 in case of error.

### xmlHashCopy ()

    xmlHashTablePtr	xmlHashCopy		(xmlHashTablePtr table,
    					 xmlHashCopier f)

Scan the hash @table and applied @f to each value.

`table`: | the hash table
`f`: | the copier function for items in the hash
`Returns`: | the new table or NULL in case of error.

### xmlHashCreate ()

    xmlHashTablePtr	xmlHashCreate		(int size)

Create a new xmlHashTablePtr.

`size`: | the size of the hash table
`Returns`: | the newly created object, or NULL if an error occured.

### xmlHashCreateDict ()

    xmlHashTablePtr	xmlHashCreateDict	(int size,
    					 xmlDictPtr dict)

Create a new xmlHashTablePtr which will use @dict as the internal dictionary

`size`: | the size of the hash table
`dict`: | a dictionary to use for the hash
`Returns`: | the newly created object, or NULL if an error occured.

### xmlHashFree ()

    void	xmlHashFree			(xmlHashTablePtr table,
    					 xmlHashDeallocator f)

Free the hash @table and its contents. The userdata is deallocated with @f if provided.

`table`: | the hash table
`f`: | the deallocator function for items in the hash

### xmlHashLookup ()

    void *	xmlHashLookup			(xmlHashTablePtr table,
    					 const xmlChar * name)

Find the userdata specified by the @name.

`table`: | the hash table
`name`: | the name of the userdata
`Returns`: | the pointer to the userdata

### xmlHashLookup2 ()

    void *	xmlHashLookup2			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2)

Find the userdata specified by the (@name, @name2) tuple.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`Returns`: | the pointer to the userdata

### xmlHashLookup3 ()

    void *	xmlHashLookup3			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3)

Find the userdata specified by the (@name, @name2, @name3) tuple.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`name3`: | a third name of the userdata
`Returns`: | the a pointer to the userdata

### xmlHashQLookup ()

    void *	xmlHashQLookup			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name)

Find the userdata specified by the QName @prefix:@name/@name.

`table`: | the hash table
`prefix`: | the prefix of the userdata
`name`: | the name of the userdata
`Returns`: | the pointer to the userdata

### xmlHashQLookup2 ()

    void *	xmlHashQLookup2			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name,
    					 const xmlChar * prefix2,
    					 const xmlChar * name2)

Find the userdata specified by the QNames tuple

`table`: | the hash table
`prefix`: | the prefix of the userdata
`name`: | the name of the userdata
`prefix2`: | the second prefix of the userdata
`name2`: | a second name of the userdata
`Returns`: | the pointer to the userdata

### xmlHashQLookup3 ()

    void *	xmlHashQLookup3			(xmlHashTablePtr table,
    					 const xmlChar * prefix,
    					 const xmlChar * name,
    					 const xmlChar * prefix2,
    					 const xmlChar * name2,
    					 const xmlChar * prefix3,
    					 const xmlChar * name3)

Find the userdata specified by the (@name, @name2, @name3) tuple.

`table`: | the hash table
`prefix`: | the prefix of the userdata
`name`: | the name of the userdata
`prefix2`: | the second prefix of the userdata
`name2`: | a second name of the userdata
`prefix3`: | the third prefix of the userdata
`name3`: | a third name of the userdata
`Returns`: | the a pointer to the userdata

### xmlHashRemoveEntry ()

    int	xmlHashRemoveEntry		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 xmlHashDeallocator f)

Find the userdata specified by the @name and remove it from the hash @table. Existing userdata for this tuple will be removed and freed with @f.

`table`: | the hash table
`name`: | the name of the userdata
`f`: | the deallocator function for removed item (if any)
`Returns`: | 0 if the removal succeeded and -1 in case of error or not found.

### xmlHashRemoveEntry2 ()

    int	xmlHashRemoveEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 xmlHashDeallocator f)

Find the userdata specified by the (@name, @name2) tuple and remove it from the hash @table. Existing userdata for this tuple will be removed and freed with @f.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`f`: | the deallocator function for removed item (if any)
`Returns`: | 0 if the removal succeeded and -1 in case of error or not found.

### xmlHashRemoveEntry3 ()

    int	xmlHashRemoveEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashDeallocator f)

Find the userdata specified by the (@name, @name2, @name3) tuple and remove it from the hash @table. Existing userdata for this tuple will be removed and freed with @f.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`name3`: | a third name of the userdata
`f`: | the deallocator function for removed item (if any)
`Returns`: | 0 if the removal succeeded and -1 in case of error or not found.

### xmlHashScan ()

    void	xmlHashScan			(xmlHashTablePtr table,
    					 xmlHashScanner f,
    					 void * data)

Scan the hash @table and applied @f to each value.

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

### xmlHashScan3 ()

    void	xmlHashScan3			(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashScanner f,
    					 void * data)

Scan the hash @table and applied @f to each value matching (@name, @name2, @name3) tuple. If one of the names is null, the comparison is considered to match.

`table`: | the hash table
`name`: | the name of the userdata or NULL
`name2`: | a second name of the userdata or NULL
`name3`: | a third name of the userdata or NULL
`f`: | the scanner function for items in the hash
`data`: | extra data passed to f

### xmlHashScanFull ()

    void	xmlHashScanFull			(xmlHashTablePtr table,
    					 xmlHashScannerFull f,
    					 void * data)

Scan the hash @table and applied @f to each value.

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

### xmlHashScanFull3 ()

    void	xmlHashScanFull3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 xmlHashScannerFull f,
    					 void * data)

Scan the hash @table and applied @f to each value matching (@name, @name2, @name3) tuple. If one of the names is null, the comparison is considered to match.

`table`: | the hash table
`name`: | the name of the userdata or NULL
`name2`: | a second name of the userdata or NULL
`name3`: | a third name of the userdata or NULL
`f`: | the scanner function for items in the hash
`data`: | extra data passed to f

### xmlHashSize ()

    int	xmlHashSize			(xmlHashTablePtr table)

Query the number of elements installed in the hash @table.

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

### xmlHashUpdateEntry ()

    int	xmlHashUpdateEntry		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 void * userdata,
    					 xmlHashDeallocator f)

Add the @userdata to the hash @table. This can later be retrieved by using the @name. Existing entry for this @name will be removed and freed with @f if found.

`table`: | the hash table
`name`: | the name of the userdata
`userdata`: | a pointer to the userdata
`f`: | the deallocator function for replaced item (if any)
`Returns`: | 0 the addition succeeded and -1 in case of error.

### xmlHashUpdateEntry2 ()

    int	xmlHashUpdateEntry2		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 void * userdata,
    					 xmlHashDeallocator f)

Add the @userdata to the hash @table. This can later be retrieved by using the (@name, @name2) tuple. Existing entry for this tuple will be removed and freed with @f if found.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`userdata`: | a pointer to the userdata
`f`: | the deallocator function for replaced item (if any)
`Returns`: | 0 the addition succeeded and -1 in case of error.

### xmlHashUpdateEntry3 ()

    int	xmlHashUpdateEntry3		(xmlHashTablePtr table,
    					 const xmlChar * name,
    					 const xmlChar * name2,
    					 const xmlChar * name3,
    					 void * userdata,
    					 xmlHashDeallocator f)

Add the @userdata to the hash @table. This can later be retrieved by using the tuple (@name, @name2, @name3). Existing entry for this tuple will be removed and freed with @f if found.

`table`: | the hash table
`name`: | the name of the userdata
`name2`: | a second name of the userdata
`name3`: | a third name of the userdata
`userdata`: | a pointer to the userdata
`f`: | the deallocator function for replaced item (if any)
`Returns`: | 0 the addition succeeded and -1 in case of error.