<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="redland-hash">
<refmeta>
<refentrytitle role="top_of_page" id="redland-hash.top_of_page">Hashes</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>REDLAND Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Hashes</refname>
<refpurpose>Key:Value hashes or dictionaries.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="redland-hash.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
typedef             <link linkend="librdf-hash">librdf_hash</link>;
typedef             <link linkend="librdf-hash-cursor">librdf_hash_cursor</link>;
<link linkend="librdf-hash">librdf_hash</link>*        <link linkend="librdf-new-hash-from-string">librdf_new_hash_from_string</link>         (<link linkend="librdf-world">librdf_world</link> *world,
                                                         const <link linkend="char">char</link> *name,
                                                         const <link linkend="char">char</link> *string);
<link linkend="librdf-hash">librdf_hash</link>*        <link linkend="librdf-new-hash-from-array-of-strings">librdf_new_hash_from_array_of_strings</link>
                                                        (<link linkend="librdf-world">librdf_world</link> *world,
                                                         const <link linkend="char">char</link> *name,
                                                         const <link linkend="char">char</link> **array);
<link linkend="librdf-hash">librdf_hash</link>*        <link linkend="librdf-new-hash-from-hash">librdf_new_hash_from_hash</link>           (<link linkend="librdf-hash">librdf_hash</link> *old_hash);
<link linkend="void">void</link>                <link linkend="librdf-free-hash">librdf_free_hash</link>                    (<link linkend="librdf-hash">librdf_hash</link> *hash);
<link linkend="char">char</link>*               <link linkend="librdf-hash-get">librdf_hash_get</link>                     (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);
<link linkend="int">int</link>                 <link linkend="librdf-hash-get-as-boolean">librdf_hash_get_as_boolean</link>          (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);
<link linkend="long">long</link>                <link linkend="librdf-hash-get-as-long">librdf_hash_get_as_long</link>             (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);
<link linkend="char">char</link>*               <link linkend="librdf-hash-get-del">librdf_hash_get_del</link>                 (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);
<link linkend="int">int</link>                 <link linkend="librdf-hash-put-strings">librdf_hash_put_strings</link>             (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *value);
<link linkend="void">void</link>                <link linkend="librdf-hash-print">librdf_hash_print</link>                   (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>                <link linkend="librdf-hash-print-keys">librdf_hash_print_keys</link>              (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>                <link linkend="librdf-hash-print-values">librdf_hash_print_values</link>            (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key_string,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
unsigned <link linkend="char">char</link>*      <link linkend="librdf-hash-interpret-template">librdf_hash_interpret_template</link>      (unsigned <link linkend="char">char</link> *template_string,
                                                         <link linkend="librdf-hash">librdf_hash</link> *dictionary,
                                                         unsigned <link linkend="char">char</link> *prefix,
                                                         unsigned <link linkend="char">char</link> *suffix);
</synopsis>
</refsynopsisdiv>









<refsect1 id="redland-hash.description" role="desc">
<title role="desc.title">Description</title>
<para>
Interface to implementations of key:value hashes either in memory, on
disk and with persistence.  Keys may have multiple and duplicate values.
</para>
</refsect1>

<refsect1 id="redland-hash.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="librdf-hash" role="typedef">
<title>librdf_hash</title>
<indexterm zone="librdf-hash"><primary>librdf_hash</primary></indexterm><programlisting>typedef struct librdf_hash_s librdf_hash;
</programlisting>
<para>
Redland hash class.</para>
<para>

</para></refsect2>
<refsect2 id="librdf-hash-cursor" role="typedef">
<title>librdf_hash_cursor</title>
<indexterm zone="librdf-hash-cursor"><primary>librdf_hash_cursor</primary></indexterm><programlisting>typedef struct librdf_hash_cursor_s librdf_hash_cursor;
</programlisting>
<para>
Redland hash cursor class.</para>
<para>

</para></refsect2>
<refsect2 id="librdf-new-hash-from-string" role="function">
<title>librdf_new_hash_from_string ()</title>
<indexterm zone="librdf-new-hash-from-string"><primary>librdf_new_hash_from_string</primary></indexterm><programlisting><link linkend="librdf-hash">librdf_hash</link>*        librdf_new_hash_from_string         (<link linkend="librdf-world">librdf_world</link> *world,
                                                         const <link linkend="char">char</link> *name,
                                                         const <link linkend="char">char</link> *string);</programlisting>
<para>
Constructor - create a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object from a string.
</para>
<para>
See <link linkend="librdf-hash-from-string"><type>librdf_hash_from_string</type></link> for the string format.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> redland world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> hash name
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> hash encoded as a string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-new-hash-from-array-of-strings" role="function">
<title>librdf_new_hash_from_array_of_strings ()</title>
<indexterm zone="librdf-new-hash-from-array-of-strings"><primary>librdf_new_hash_from_array_of_strings</primary></indexterm><programlisting><link linkend="librdf-hash">librdf_hash</link>*        librdf_new_hash_from_array_of_strings
                                                        (<link linkend="librdf-world">librdf_world</link> *world,
                                                         const <link linkend="char">char</link> *name,
                                                         const <link linkend="char">char</link> **array);</programlisting>
<para>
Constructor - create a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object from an array of strings.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> redland world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> hash name
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara> address of the start of the array of char* pointers
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-new-hash-from-hash" role="function">
<title>librdf_new_hash_from_hash ()</title>
<indexterm zone="librdf-new-hash-from-hash"><primary>librdf_new_hash_from_hash</primary></indexterm><programlisting><link linkend="librdf-hash">librdf_hash</link>*        librdf_new_hash_from_hash           (<link linkend="librdf-hash">librdf_hash</link> *old_hash);</programlisting>
<para>
Copy Constructor - create a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object from an existing one.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>old_hash</parameter>&nbsp;:</term>
<listitem><simpara> the hash to use to construct the hash
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="librdf-hash"><type>librdf_hash</type></link> object or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-free-hash" role="function">
<title>librdf_free_hash ()</title>
<indexterm zone="librdf-free-hash"><primary>librdf_free_hash</primary></indexterm><programlisting><link linkend="void">void</link>                librdf_free_hash                    (<link linkend="librdf-hash">librdf_hash</link> *hash);</programlisting>
<para>
Destructor - destroy a <link linkend="librdf-hash"><type>librdf_hash</type></link> object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> hash object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-get" role="function">
<title>librdf_hash_get ()</title>
<indexterm zone="librdf-hash-get"><primary>librdf_hash_get</primary></indexterm><programlisting><link linkend="char">char</link>*               librdf_hash_get                     (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Retrieve one value from hash for a given key as string.
</para>
<para>
The value returned is from newly allocated memory which the
caller must free.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> hash object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
<listitem><simpara> pointer to key
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the value or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-get-as-boolean" role="function">
<title>librdf_hash_get_as_boolean ()</title>
<indexterm zone="librdf-hash-get-as-boolean"><primary>librdf_hash_get_as_boolean</primary></indexterm><programlisting><link linkend="int">int</link>                 librdf_hash_get_as_boolean          (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Lookup a hash key and decode value as a boolean.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="librdf-hash"><type>librdf_hash</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
<listitem><simpara> key string to look up
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> &gt;0 (for true), 0 (for false) or &lt;0 (for key not found or not known boolean value)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-get-as-long" role="function">
<title>librdf_hash_get_as_long ()</title>
<indexterm zone="librdf-hash-get-as-long"><primary>librdf_hash_get_as_long</primary></indexterm><programlisting><link linkend="long">long</link>                librdf_hash_get_as_long             (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Lookup a hash key and decode value as a long.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="librdf-hash"><type>librdf_hash</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
<listitem><simpara> key string to look up
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> &gt;0 (for success), &lt;0 (for key not found or not known boolean value)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-get-del" role="function">
<title>librdf_hash_get_del ()</title>
<indexterm zone="librdf-hash-get-del"><primary>librdf_hash_get_del</primary></indexterm><programlisting><link linkend="char">char</link>*               librdf_hash_get_del                 (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Retrieve one value from hash for a given key as string and remove all values with that key.
</para>
<para>
The value returned is from newly allocated memory which the
caller must free.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> hash object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
<listitem><simpara> pointer to key
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the value or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-put-strings" role="function">
<title>librdf_hash_put_strings ()</title>
<indexterm zone="librdf-hash-put-strings"><primary>librdf_hash_put_strings</primary></indexterm><programlisting><link linkend="int">int</link>                 librdf_hash_put_strings             (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *value);</programlisting>
<para>
Insert key/value pairs into the hash as strings.
</para>
<para>
The key and values are copied into the hash, no sharing i s done.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> hash object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
<listitem><simpara> key 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> value
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non 0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-print" role="function">
<title>librdf_hash_print ()</title>
<indexterm zone="librdf-hash-print"><primary>librdf_hash_print</primary></indexterm><programlisting><link linkend="void">void</link>                librdf_hash_print                   (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Pretty print the hash to a file descriptor.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> the hash
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-print-keys" role="function">
<title>librdf_hash_print_keys ()</title>
<indexterm zone="librdf-hash-print-keys"><primary>librdf_hash_print_keys</primary></indexterm><programlisting><link linkend="void">void</link>                librdf_hash_print_keys              (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Pretty print the keys to a file descriptor.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> the hash
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-print-values" role="function">
<title>librdf_hash_print_values ()</title>
<indexterm zone="librdf-hash-print-values"><primary>librdf_hash_print_values</primary></indexterm><programlisting><link linkend="void">void</link>                librdf_hash_print_values            (<link linkend="librdf-hash">librdf_hash</link> *hash,
                                                         const <link linkend="char">char</link> *key_string,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Pretty print the values of one key to a file descriptor.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>hash</parameter>&nbsp;:</term>
<listitem><simpara> the hash
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key_string</parameter>&nbsp;:</term>
<listitem><simpara> the key as a string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="librdf-hash-interpret-template" role="function">
<title>librdf_hash_interpret_template ()</title>
<indexterm zone="librdf-hash-interpret-template"><primary>librdf_hash_interpret_template</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>*      librdf_hash_interpret_template      (unsigned <link linkend="char">char</link> *template_string,
                                                         <link linkend="librdf-hash">librdf_hash</link> *dictionary,
                                                         unsigned <link linkend="char">char</link> *prefix,
                                                         unsigned <link linkend="char">char</link> *suffix);</programlisting>
<para>
Interpret keys in a template string to their value in a dictionary.
</para>
<para>
Can be used to do variable substitution for a string where
the syntax that marks the variable is defined by the <parameter>prefix</parameter>
and <parameter>suffix</parameter> strings, and the variables are stored in the <parameter>dictionary</parameter>
hash table.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>template_string</parameter>&nbsp;:</term>
<listitem><simpara> template string to interprate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dictionary</parameter>&nbsp;:</term>
<listitem><simpara> dictionary of key/values to substitute
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter>&nbsp;:</term>
<listitem><simpara> prefix to mark a key in the template
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>suffix</parameter>&nbsp;:</term>
<listitem><simpara> suffix to mark a key in the template
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> Newly allocated string, or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
