## EXMLHash

EXMLHash — Functions for manipulating xml as a hash table.

## Synopsis

    enum                EXmlHashType;
    GHashTable *	       e_xml_to_hash                       (xmlDoc *doc,
                                                             EXmlHashType type);
    xmlDoc *	           e_xml_from_hash                     (GHashTable *hash,
                                                             EXmlHashType type,
                                                             const gchar *root_name);
    void                e_xml_destroy_hash                  (GHashTable *hash);
    enum                EXmlHashStatus;
    void                (*EXmlHashFunc)                     (const gchar *key,
                                                             const gchar *value,
                                                             gpointer user_data);
    gboolean            (*EXmlHashRemoveFunc)               (const gchar *key,
                                                             const gchar *value,
                                                             gpointer user_data);
    typedef             EXmlHash;
    EXmlHash *	         e_xmlhash_new                       (const gchar *filename);
    void                e_xmlhash_add                       (EXmlHash *hash,
                                                             const gchar *key,
                                                             const gchar *data);
    void                e_xmlhash_remove                    (EXmlHash *hash,
                                                             const gchar *key);
    EXmlHashStatus      e_xmlhash_compare                   (EXmlHash *hash,
                                                             const gchar *key,
                                                             const gchar *compare_data);
    void                e_xmlhash_foreach_key               (EXmlHash *hash,
                                                             EXmlHashFunc func,
                                                             gpointer user_data);
    void                e_xmlhash_foreach_key_remove        (EXmlHash *hash,
                                                             EXmlHashRemoveFunc func,
                                                             gpointer user_data);
    void                e_xmlhash_write                     (EXmlHash *hash);
    void                e_xmlhash_destroy                   (EXmlHash *hash);

## Description

## Details

### enum EXmlHashType

    typedef enum {
    	E_XML_HASH_TYPE_OBJECT_UID,
    	E_XML_HASH_TYPE_PROPERTY
    } EXmlHashType;

`E_XML_HASH_TYPE_OBJECT_UID` | Use the object UID as the hash key.
`E_XML_HASH_TYPE_PROPERTY` | Use the property name as the hash key.

### e_xml_to_hash ()

    GHashTable *	       e_xml_to_hash                       (xmlDoc *doc,
                                                             EXmlHashType type);

Creates a GHashTable representation of the xmlDoc `doc`. If `type` is * `E_XML_HASH_TYPE_PROPERTY`, all XML nodes will be indexed in the GHashTable by name. If `type` is `E_XML_HASH_TYPE_OBJECT_UID`, then XML objects will be indexed in the hash by their UID (other nodes will still be indexed by name).

`doc` : | The xmlDoc to store in a hash table.
`type` : | The value type to use as a key in the hash table.
Returns : | The newly-created GHashTable representation of `doc`. [transfer full]

### e_xml_from_hash ()

    xmlDoc *	           e_xml_from_hash                     (GHashTable *hash,
                                                             EXmlHashType type,
                                                             const gchar *root_name);

Uses the key/value pair representation of an XML structure in `hash` to build an equivalent xmlDoc. This is the reverse of `e_xml_to_hash()`.

`hash` : | The GHashTable to extract the XML from
`type` : | The EXmlHashType used to store the XML
`root_name` : | The name to call the new xmlDoc
Returns : | the xmlDoc created from the data in `hash`

### e_xml_destroy_hash ()

    void                e_xml_destroy_hash                  (GHashTable *hash);

Frees the memory used by `hash` and its contents.

`hash` : | the GHashTable to destroy

### enum EXmlHashStatus

    typedef enum {
    	E_XMLHASH_STATUS_SAME,
    	E_XMLHASH_STATUS_DIFFERENT,
    	E_XMLHASH_STATUS_NOT_FOUND
    } EXmlHashStatus;

`E_XMLHASH_STATUS_SAME` | The compared values are the same.
`E_XMLHASH_STATUS_DIFFERENT` | The compared values are different.
`E_XMLHASH_STATUS_NOT_FOUND` | The key to compare against was not found.

### EXmlHashFunc ()

    void                (*EXmlHashFunc)                     (const gchar *key,
                                                             const gchar *value,
                                                             gpointer user_data);

### EXmlHashRemoveFunc ()

    gboolean            (*EXmlHashRemoveFunc)               (const gchar *key,
                                                             const gchar *value,
                                                             gpointer user_data);

### EXmlHash

    typedef struct EXmlHash EXmlHash;

A hash table representation of an XML file.

### e_xmlhash_new ()

    EXmlHash *	         e_xmlhash_new                       (const gchar *filename);

Creates a new EXmlHash from the file `filename`. If `filename` does not already exist, an empty EXmlHash will be created.

`filename` : | the name of an XML file
Returns : | The new EXmlHash structure, or `NULL` if unable to parse `filename`.

### e_xmlhash_add ()

    void                e_xmlhash_add                       (EXmlHash *hash,
                                                             const gchar *key,
                                                             const gchar *data);

Adds a new key/value pair to the EXmlHash `hash`.

`hash` : | the EXmlHash to add an entry to
`key` : | the key to use for the entry
`data` : | the value of the new entry

### e_xmlhash_remove ()

    void                e_xmlhash_remove                    (EXmlHash *hash,
                                                             const gchar *key);

Remove the entry in `hash` with key equal to `key`, if it exists.

`hash` : | the EXmlHash to remove an entry from
`key` : | the key of the entry to remove

### e_xmlhash_compare ()

    EXmlHashStatus      e_xmlhash_compare                   (EXmlHash *hash,
                                                             const gchar *key,
                                                             const gchar *compare_data);

Compares the value with key equal to `key` in `hash` against `compare_data`.

`hash` : | the EXmlHash to compare against
`key` : | the key of the hash entry to compare with
`compare_data` : | the data to compare against the hash entry
Returns : | E_XMLHASH_STATUS_SAME if the value and `compare_data` are equal,E_XMLHASH_STATUS_DIFFERENT if they are different, or E_XMLHASH_STATUS_NOT_FOUND if there is no entry in `hash` with its key equal to `key`.

### e_xmlhash_foreach_key ()

    void                e_xmlhash_foreach_key               (EXmlHash *hash,
                                                             EXmlHashFunc func,
                                                             gpointer user_data);

Executes `func` against each key/value pair in `hash`.

`hash` : | an EXmlHash
`func` : | the EXmlHashFunc to execute on the data in `hash`. [scope async]
`user_data` : | the data to pass to `func`

### e_xmlhash_foreach_key_remove ()

    void                e_xmlhash_foreach_key_remove        (EXmlHash *hash,
                                                             EXmlHashRemoveFunc func,
                                                             gpointer user_data);

Calls `g_hash_table_foreach_remove()` on `hash`<!-- -->'s internal hash table. See `g_hash_table_foreach_remove()` for details.

`hash` : | an EXmlHash
`func` : | the EXmlHashFunc to execute on the data in `hash`. [scope async]
`user_data` : | the data to pass to `func`

### e_xmlhash_write ()

    void                e_xmlhash_write                     (EXmlHash *hash);

Writes the XML represented by `hash` to the file originally passed to `e_xmlhash_new()`.

`hash` : | The EXmlHash to write.

### e_xmlhash_destroy ()

    void                e_xmlhash_destroy                   (EXmlHash *hash);

Frees the memory associated with `hash`.

`hash` : | The EXmlHash to destroy.