docs/programmer_reference/stl_misc.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <head>
   5     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6     <title>Dbstl miscellaneous notes</title>
   7     <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
   8     <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
   9     <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
  10     <link rel="up" href="stl.html" title="Chapter 7. Standard Template Library API" />
  11     <link rel="prev" href="stl_memory_mgmt.html" title="Dbstl memory management" />
  12     <link rel="next" href="stl_known_issues.html" title="Dbstl known issues" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Dbstl miscellaneous notes</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="stl_memory_mgmt.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 7. Standard Template Library API</th>
  26           <td width="20%" align="right"> <a accesskey="n" href="stl_known_issues.html">Next</a></td>
  27         </tr>
  28       </table>
  29       <hr />
  30     </div>
  31     <div class="sect1" lang="en" xml:lang="en">
  32       <div class="titlepage">
  33         <div>
  34           <div>
  35             <h2 class="title" style="clear: both"><a id="stl_misc"></a>Dbstl miscellaneous notes</h2>
  36           </div>
  37         </div>
  38       </div>
  39       <div class="toc">
  40         <dl>
  41           <dt>
  42             <span class="sect2">
  43               <a href="stl_misc.html#idp1407848">Special notes about trivial methods</a>
  44             </span>
  45           </dt>
  46           <dt>
  47             <span class="sect2">
  48               <a href="stl_misc.html#idp1421568">Using correct container and iterator public types</a>
  49             </span>
  50           </dt>
  51         </dl>
  52       </div>
  53       <div class="sect2" lang="en" xml:lang="en">
  54         <div class="titlepage">
  55           <div>
  56             <div>
  57               <h3 class="title"><a id="idp1407848"></a>Special notes about trivial methods</h3>
  58             </div>
  59           </div>
  60         </div>
  61         <p>
  62         There are some standard STL methods which are meaningless in dbstl, but they are kept in
  63         dbstl as no-ops so as to stay consistent with the standard. These are:
  64         </p>
  65         <table class="simplelist" border="0" summary="Simple list">
  66           <tr>
  67             <td>
  68               <code class="methodname">db_vecter::reserve();</code>
  69             </td>
  70           </tr>
  71           <tr>
  72             <td>
  73               <code class="methodname">db_vector::max_size();</code>
  74             </td>
  75           </tr>
  76           <tr>
  77             <td>
  78               <code class="methodname">db_vector::capacity();</code>
  79             </td>
  80           </tr>
  81           <tr>
  82             <td>
  83               <code class="methodname">db_map::reserve();</code>
  84             </td>
  85           </tr>
  86           <tr>
  87             <td>
  88               <code class="methodname">db_map::max_size();</code>
  89             </td>
  90           </tr>
  91         </table>
  92         <p>
  93         <code class="methodname">db_vector&lt;&gt;::max_size()</code> and
  94         <code class="methodname">db_map&lt;&gt;::max_size()</code> both return 2^30. This does not mean
  95         that Berkeley DB can only hold that much data. This value is returned to conform to some
  96         compilers' overflow rules — if we set bigger numbers like 2^32 or 2^31, some compilers
  97         complain that the number has overflowed.
  98         </p>
  99         <p>
 100         See the Berkeley DB documentation for information about limitations on how much data a
 101         database can store.
 102         </p>
 103         <p>
 104         There are also some read-only functions. You set the configuration
 105         for these using the Berkeley DB API. You access them using the container's methods. Again,
 106         this is to keep consistent with C++ standard STL containers, such as:
 107         </p>
 108         <table class="simplelist" border="0" summary="Simple list">
 109           <tr>
 110             <td>
 111               <code class="methodname">db_map::key_comp();</code>
 112             </td>
 113           </tr>
 114           <tr>
 115             <td>
 116               <code class="methodname">db_map::value_comp();</code>
 117             </td>
 118           </tr>
 119           <tr>
 120             <td>
 121               <code class="methodname">db_map::hash_funct();</code>
 122             </td>
 123           </tr>
 124           <tr>
 125             <td>
 126               <code class="methodname">db_map::key_eq();</code>
 127             </td>
 128           </tr>
 129         </table>
 130       </div>
 131       <div class="sect2" lang="en" xml:lang="en">
 132         <div class="titlepage">
 133           <div>
 134             <div>
 135               <h3 class="title"><a id="idp1421568"></a>Using correct container and iterator public types</h3>
 136             </div>
 137           </div>
 138         </div>
 139         <p>
 140         All public types defined by the C++ STL specification are present in dbstl. One thing to
 141         note is the <span class="bold"><strong>value_type</strong></span>. dbstl defines the <span class="bold"><strong>value_type</strong></span> for each iterator and container class to be the raw
 142         type without the <code class="classname">ElementRef</code>/<code class="classname">ElementHolder</code>
 143         wrapper, so this type of variable can not be used to store data in a database.  There is a
 144         <span class="bold"><strong>value_type_wrap</strong></span> type for each container and iterator type,
 145         with the raw type wrapped by the
 146         <code class="classname">ElementRef</code>/<code class="classname">ElementHolder</code>.
 147         </p>
 148         <p>
 149         For example, when type <code class="literal">int_vector_t</code> is defined as
 150     </p>
 151         <pre class="programlisting">db_vector&lt;int, ElementHolder&lt;int&gt; &gt;</pre>
 152         <p>
 153         its <span class="bold"><strong>value_type</strong></span> is <code class="literal">int</code>, its
 154         <span class="bold"><strong>value_type_wrap</strong></span> is <code class="literal">ElementHolder&lt;int&gt;</code>,
 155         and its reference and pointer types are <code class="literal">ElementHolder&lt;int&gt;&amp;</code> and
 156         <code class="literal">ElementHolder&lt;int&gt;*</code> respectively.  If you need to store data, use
 157         <span class="bold"><strong>value_type_wrap</strong></span> to make use of the wrapper to store data
 158         into database.
 159         </p>
 160         <p>
 161         The reason we leave <span class="bold"><strong>value_type</strong></span> as the raw type is that we
 162         want the existing algorithms in the STL library to work with dbstl because we have seen that
 163         without doing so, a few tests will fail.
 164         </p>
 165         <p>
 166         You need to use the same type as the return type of the data element retrieval functions to
 167         hold a value in order to properly manipulate the data element. For example, when calling
 168     </p>
 169         <pre class="programlisting">db_vector&lt;T&gt;::operator[]</pre>
 170         <p>
 171         check that the return type for this function is
 172     </p>
 173         <pre class="programlisting">db_vector&lt;T&gt;::datatype_wrap</pre>
 174         <p>
 175         Then,  hold the return value using an object of the same type:
 176     </p>
 177         <pre class="programlisting">db_vector&lt;T&gt;::datatype_wrap refelem = vctr[3];</pre>
 178       </div>
 179     </div>
 180     <div class="navfooter">
 181       <hr />
 182       <table width="100%" summary="Navigation footer">
 183         <tr>
 184           <td width="40%" align="left"><a accesskey="p" href="stl_memory_mgmt.html">Prev</a> </td>
 185           <td width="20%" align="center">
 186             <a accesskey="u" href="stl.html">Up</a>
 187           </td>
 188           <td width="40%" align="right"> <a accesskey="n" href="stl_known_issues.html">Next</a></td>
 189         </tr>
 190         <tr>
 191           <td width="40%" align="left" valign="top">Dbstl memory management </td>
 192           <td width="20%" align="center">
 193             <a accesskey="h" href="index.html">Home</a>
 194           </td>
 195           <td width="40%" align="right" valign="top"> Dbstl known issues</td>
 196         </tr>
 197       </table>
 198     </div>
 199   </body>
 200 </html>