Hashes

## Hashes Hashes — Key:Value hashes or dictionaries. |

## Functions

librdf_hash * | librdf_new_hash ()
librdf_hash * | librdf_new_hash_from_string ()
librdf_hash * | librdf_new_hash_from_array_of_strings ()
librdf_hash * | librdf_new_hash_from_hash ()
void | librdf_free_hash ()
char * | librdf_hash_get ()
int | librdf_hash_get_as_boolean ()
long | librdf_hash_get_as_long ()
char * | librdf_hash_get_del ()
int | librdf_hash_put_strings ()
void | librdf_hash_print ()
void | librdf_hash_print_keys ()
void | librdf_hash_print_values ()
unsigned char * | librdf_hash_interpret_template ()
int | librdf_hash_from_string ()
char * | librdf_hash_to_string ()

## Types and Values

typedef | librdf_hash
typedef | librdf_hash_cursor

## Description

Interface to implementations of key:value hashes either in memory, on disk and with persistence. Keys may have multiple and duplicate values.

## Functions

### librdf_new_hash ()

    librdf_hash *
    librdf_new_hash (librdf_world *world,
                     const char *name);

Constructor - create a new librdf_hash object.

#### Parameters

world | redland world object |
name | factory name |

#### Returns

a new librdf_hash object or NULL on failure

### librdf_new_hash_from_string ()

    librdf_hash *
    librdf_new_hash_from_string (librdf_world *world,
                                 const char *name,
                                 const char *string);

Constructor - create a new librdf_hash object from a string.

See librdf_hash_from_string for the string format.

#### Parameters

world | redland world object |
name | hash name |
string | hash encoded as a string |

#### Returns

a new librdf_hash object or NULL on failure

### librdf_new_hash_from_array_of_strings ()

    librdf_hash *
    librdf_new_hash_from_array_of_strings (librdf_world *world,
                                           const char *name,
                                           const char **array);

Constructor - create a new librdf_hash object from an array of strings.

#### Parameters

world | redland world object |
name | hash name |
array | address of the start of the array of char* pointers |

#### Returns

a new librdf_hash object or NULL on failure

### librdf_new_hash_from_hash ()

    librdf_hash *
    librdf_new_hash_from_hash (librdf_hash *old_hash);

Copy Constructor - create a new librdf_hash object from an existing one.

#### Parameters

old_hash | the hash to use to construct the hash |

#### Returns

a new librdf_hash object or NULL on failure

### librdf_free_hash ()

    void
    librdf_free_hash (librdf_hash *hash);

Destructor - destroy a librdf_hash object.

#### Parameters

hash | hash object |

### librdf_hash_get ()

    char *
    librdf_hash_get (librdf_hash *hash,
                     const char *key);

Retrieve one value from hash for a given key as string.

The value returned is from newly allocated memory which the caller must free.

#### Parameters

hash | hash object |
key | pointer to key |

#### Returns

the value or NULL on failure

### librdf_hash_get_as_boolean ()

    int
    librdf_hash_get_as_boolean (librdf_hash *hash,
                                const char *key);

Lookup a hash key and decode value as a boolean.

False values: "no", "false" True values: "yes", "true"

#### Parameters

hash | librdf_hash object |
key | key string to look up |

#### Returns

>0 (for true), 0 (for false) or <0 (for key not found or not known boolean value)

### librdf_hash_get_as_long ()

    long
    librdf_hash_get_as_long (librdf_hash *hash,
                             const char *key);

Lookup a hash key and decode value as a long.

#### Parameters

hash | librdf_hash object |
key | key string to look up |

#### Returns

>0 (for success), <0 (for key not found or not known boolean value)

### librdf_hash_get_del ()

    char *
    librdf_hash_get_del (librdf_hash *hash,
                         const char *key);

Retrieve one value from hash for a given key as string and remove all values with that key.

The value returned is from newly allocated memory which the caller must free.

#### Parameters

hash | hash object |
key | pointer to key |

#### Returns

the value or NULL on failure

### librdf_hash_put_strings ()

    int
    librdf_hash_put_strings (librdf_hash *hash,
                             const char *key,
                             const char *value);

Insert key/value pairs into the hash as strings.

The key and values are copied into the hash, no sharing i s done.

#### Parameters

hash | hash object |
key | key |
value | value |

#### Returns

non 0 on failure

### librdf_hash_print ()

    void
    librdf_hash_print (librdf_hash *hash,
                       FILE *fh);

Pretty print the hash to a file descriptor.

#### Parameters

hash | the hash |
fh | file handle |

### librdf_hash_print_keys ()

    void
    librdf_hash_print_keys (librdf_hash *hash,
                            FILE *fh);

Pretty print the keys to a file descriptor.

#### Parameters

hash | the hash |
fh | file handle |

### librdf_hash_print_values ()

    void
    librdf_hash_print_values (librdf_hash *hash,
                              const char *key_string,
                              FILE *fh);

Pretty print the values of one key to a file descriptor.

#### Parameters

hash | the hash |
key_string | the key as a string |
fh | file handle |

### librdf_hash_interpret_template ()

    unsigned char *
    librdf_hash_interpret_template (const unsigned char *template_string,
                                    librdf_hash *dictionary,
                                    const unsigned char *prefix,
                                    const unsigned char *suffix);

Interpret keys in a template string to their value in a dictionary.

Can be used to do variable substitution for a string where the syntax that marks the variable is defined by the `prefix` and `suffix` strings, and the variables are stored in the `dictionary` hash table.

#### Parameters

template_string | template string to interprate |
dictionary | dictionary of key/values to substitute |
prefix | prefix to mark a key in the template |
suffix | suffix to mark a key in the template |

#### Returns

Newly allocated string, or NULL on failure

### librdf_hash_from_string ()

    int
    librdf_hash_from_string (librdf_hash *hash,
                             const char *string);

Initialise a hash from a string.

The string format is something like: key1='value1',key2='value2', key3='\'quoted value\''

The 's are required and whitespace can appear around the = and ,s

#### Parameters

hash | hash object |
string | hash encoded as a string |

#### Returns

non 0 on failure

### librdf_hash_to_string ()

    char *
    librdf_hash_to_string (librdf_hash *hash,
                           const char *filter[]);

Format the hash as a string, suitable for parsing by librdf_hash_from_string.

Note: this method allocates a new string since this is a _to_ method and the caller must call `librdf_free_memory()` to free the resulting memory.

#### Parameters

hash | librdf_hash object |
filter | NULL terminated list of keys to ignore |

#### Returns

string representation of the hash or NULL on failure

## Types and Values

### librdf_hash

    typedef struct librdf_hash_s librdf_hash;

Redland hash class.

### librdf_hash_cursor

    typedef struct librdf_hash_cursor_s librdf_hash_cursor;

Redland hash cursor class.