doc/devhelp/libxml2-dict.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <html>
   3   <head>
   4     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   5     <title>dict: string dictionnary</title>
   6     <meta name="generator" content="Libxml2 devhelp stylesheet"/>
   7     <link rel="start" href="index.html" title="libxml2 Reference Manual"/>
   8     <link rel="up" href="general.html" title="API"/>
   9     <link rel="stylesheet" href="style.css" type="text/css"/>
  10     <link rel="chapter" href="general.html" title="API"/>
  11   </head>
  12   <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13     <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  14       <tr valign="middle">
  15         <td>
  16           <a accesskey="p" href="libxml2-debugXML.html">
  17             <img src="left.png" width="24" height="24" border="0" alt="Prev"/>
  18           </a>
  19         </td>
  20         <td>
  21           <a accesskey="u" href="general.html">
  22             <img src="up.png" width="24" height="24" border="0" alt="Up"/>
  23           </a>
  24         </td>
  25         <td>
  26           <a accesskey="h" href="index.html">
  27             <img src="home.png" width="24" height="24" border="0" alt="Home"/>
  28           </a>
  29         </td>
  30         <td>
  31           <a accesskey="n" href="libxml2-encoding.html">
  32             <img src="right.png" width="24" height="24" border="0" alt="Next"/>
  33           </a>
  34         </td>
  35         <th width="100%" align="center">libxml2 Reference Manual</th>
  36       </tr>
  37     </table>
  38     <h2>
  39       <span class="refentrytitle">dict</span>
  40     </h2>
  41     <p>dict - string dictionnary</p>
  42     <p>dictionary of reusable strings, just used to avoid allocation and freeing operations. </p>
  43     <p>Author(s): Daniel Veillard </p>
  44     <div class="refsynopsisdiv">
  45       <h2>Synopsis</h2>
  46       <pre class="synopsis">typedef struct _xmlDict <a href="#xmlDict">xmlDict</a>;
  47 typedef <a href="libxml2-dict.html#xmlDict">xmlDict</a> * <a href="#xmlDictPtr">xmlDictPtr</a>;
  48 size_t  <a href="#xmlDictGetUsage">xmlDictGetUsage</a>                  (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict);
  49 int     <a href="#xmlDictReference">xmlDictReference</a>                (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict);
  50 void    <a href="#xmlDictCleanup">xmlDictCleanup</a>                    (void);
  51 int     <a href="#xmlDictSize">xmlDictSize</a>                  (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict);
  52 const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *    <a href="#xmlDictExists">xmlDictExists</a>              (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        int len);
  53 size_t  <a href="#xmlDictSetLimit">xmlDictSetLimit</a>                  (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       size_t limit);
  54 int     <a href="#xmlDictOwns">xmlDictOwns</a>                  (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * str);
  55 const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *    <a href="#xmlDictQLookup">xmlDictQLookup</a>            (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * prefix, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name);
  56 int     <a href="#xmlInitializeDict">xmlInitializeDict</a>              (void);
  57 <a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a>   <a href="#xmlDictCreateSub">xmlDictCreateSub</a>        (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> sub);
  58 void    <a href="#xmlDictFree">xmlDictFree</a>                  (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict);
  59 const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *    <a href="#xmlDictLookup">xmlDictLookup</a>              (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        int len);
  60 <a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a>   <a href="#xmlDictCreate">xmlDictCreate</a>              (void);
  61 </pre>
  62     </div>
  63     <div class="refsect1" lang="en">
  64       <h2>Description</h2>
  65     </div>
  66     <div class="refsect1" lang="en">
  67       <h2>Details</h2>
  68       <div class="refsect2" lang="en">
  69         <div class="refsect2" lang="en"><h3><a name="xmlDict">Structure </a>xmlDict</h3><pre class="programlisting">struct _xmlDict {
  70 The content of this structure is not made public by the API.
  71 } xmlDict;
  72 </pre><p/>
  73 </div>
  74         <hr/>
  75         <div class="refsect2" lang="en"><h3><a name="xmlDictPtr">Typedef </a>xmlDictPtr</h3><pre class="programlisting"><a href="libxml2-dict.html#xmlDict">xmlDict</a> * xmlDictPtr;
  76 </pre><p/>
  77 </div>
  78         <hr/>
  79         <div class="refsect2" lang="en"><h3><a name="xmlDictCleanup"/>xmlDictCleanup ()</h3><pre class="programlisting">void    xmlDictCleanup                  (void)<br/>
  80 </pre><p>Free the dictionary mutex. Do not call unless sure the library is not in use anymore !</p>
  81 </div>
  82         <hr/>
  83         <div class="refsect2" lang="en"><h3><a name="xmlDictCreate"/>xmlDictCreate ()</h3><pre class="programlisting"><a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a>     xmlDictCreate           (void)<br/>
  84 </pre><p>Create a new dictionary</p>
  85 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the newly created dictionnary, or NULL if an error occured.</td></tr></tbody></table></div></div>
  86         <hr/>
  87         <div class="refsect2" lang="en"><h3><a name="xmlDictCreateSub"/>xmlDictCreateSub ()</h3><pre class="programlisting"><a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a>       xmlDictCreateSub        (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> sub)<br/>
  88 </pre><p>Create a new dictionary, inheriting strings from the read-only dictionnary @sub. On lookup, strings are first searched in the new dictionnary, then in @sub, and if not found are created in the new dictionnary.</p>
  89 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>sub</tt></i>:</span></td><td>an existing dictionnary</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the newly created dictionnary, or NULL if an error occured.</td></tr></tbody></table></div></div>
  90         <hr/>
  91         <div class="refsect2" lang="en"><h3><a name="xmlDictExists"/>xmlDictExists ()</h3><pre class="programlisting">const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *      xmlDictExists           (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        int len)<br/>
  92 </pre><p>Check if the @name exists in the dictionnary @dict.</p>
  93 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the name of the userdata</td></tr><tr><td><span class="term"><i><tt>len</tt></i>:</span></td><td>the length of the name, if -1 it is recomputed</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the internal copy of the name or NULL if not found.</td></tr></tbody></table></div></div>
  94         <hr/>
  95         <div class="refsect2" lang="en"><h3><a name="xmlDictFree"/>xmlDictFree ()</h3><pre class="programlisting">void  xmlDictFree                     (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict)<br/>
  96 </pre><p>Free the hash @dict and its contents. The userdata is deallocated with @f if provided.</p>
  97 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr></tbody></table></div></div>
  98         <hr/>
  99         <div class="refsect2" lang="en"><h3><a name="xmlDictGetUsage"/>xmlDictGetUsage ()</h3><pre class="programlisting">size_t        xmlDictGetUsage                 (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict)<br/>
 100 </pre><p>Get how much memory is used by a dictionary for strings Added in 2.9.0</p>
 101 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the amount of strings allocated</td></tr></tbody></table></div></div>
 102         <hr/>
 103         <div class="refsect2" lang="en"><h3><a name="xmlDictLookup"/>xmlDictLookup ()</h3><pre class="programlisting">const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *      xmlDictLookup           (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name, <br/>                                        int len)<br/>
 104 </pre><p>Add the @name to the dictionnary @dict if not present.</p>
 105 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the name of the userdata</td></tr><tr><td><span class="term"><i><tt>len</tt></i>:</span></td><td>the length of the name, if -1 it is recomputed</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the internal copy of the name or NULL in case of internal error</td></tr></tbody></table></div></div>
 106         <hr/>
 107         <div class="refsect2" lang="en"><h3><a name="xmlDictOwns"/>xmlDictOwns ()</h3><pre class="programlisting">int   xmlDictOwns                     (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * str)<br/>
 108 </pre><p>check if a string is owned by the disctionary</p>
 109 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>str</tt></i>:</span></td><td>the string</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>1 if true, 0 if false and -1 in case of error -1 in case of error</td></tr></tbody></table></div></div>
 110         <hr/>
 111         <div class="refsect2" lang="en"><h3><a name="xmlDictQLookup"/>xmlDictQLookup ()</h3><pre class="programlisting">const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> *    xmlDictQLookup          (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * prefix, <br/>                                      const <a href="libxml2-xmlstring.html#xmlChar">xmlChar</a> * name)<br/>
 112 </pre><p>Add the QName @prefix:@name to the hash @dict if not present.</p>
 113 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>prefix</tt></i>:</span></td><td>the prefix</td></tr><tr><td><span class="term"><i><tt>name</tt></i>:</span></td><td>the name</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the internal copy of the QName or NULL in case of internal error</td></tr></tbody></table></div></div>
 114         <hr/>
 115         <div class="refsect2" lang="en"><h3><a name="xmlDictReference"/>xmlDictReference ()</h3><pre class="programlisting">int xmlDictReference                (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict)<br/>
 116 </pre><p>Increment the <a href="libxml2-SAX.html#reference">reference</a> counter of a dictionary</p>
 117 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of error</td></tr></tbody></table></div></div>
 118         <hr/>
 119         <div class="refsect2" lang="en"><h3><a name="xmlDictSetLimit"/>xmlDictSetLimit ()</h3><pre class="programlisting">size_t        xmlDictSetLimit                 (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict, <br/>                                       size_t limit)<br/>
 120 </pre><p>Set a size limit for the dictionary Added in 2.9.0</p>
 121 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>limit</tt></i>:</span></td><td>the limit in bytes</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the previous limit of the dictionary or 0</td></tr></tbody></table></div></div>
 122         <hr/>
 123         <div class="refsect2" lang="en"><h3><a name="xmlDictSize"/>xmlDictSize ()</h3><pre class="programlisting">int   xmlDictSize                     (<a href="libxml2-dict.html#xmlDictPtr">xmlDictPtr</a> dict)<br/>
 124 </pre><p>Query the number of elements installed in the hash @dict.</p>
 125 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>dict</tt></i>:</span></td><td>the dictionnary</td></tr><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>the number of elements in the dictionnary or -1 in case of error</td></tr></tbody></table></div></div>
 126         <hr/>
 127         <div class="refsect2" lang="en"><h3><a name="xmlInitializeDict"/>xmlInitializeDict ()</h3><pre class="programlisting">int       xmlInitializeDict               (void)<br/>
 128 </pre><p>Do the dictionary mutex initialization. this function is deprecated</p>
 129 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span class="term"><i><tt>Returns</tt></i>:</span></td><td>0 if initialization was already done, and 1 if that call led to the initialization</td></tr></tbody></table></div></div>
 130         <hr/>
 131       </div>
 132     </div>
 133   </body>
 134 </html>