libs/tuple/doc/html/design_decisions_rationale.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Design decisions rationale</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="tuple_users_guide.html" title="Chapter&#160;1.&#160;Boost.Tuple">
   8 <link rel="up" href="tuple_users_guide.html" title="Chapter&#160;1.&#160;Boost.Tuple">
   9 <link rel="prev" href="tuple_advanced_interface.html" title="Tuple library advanced features">
  10 </head>
  11 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  12 <table cellpadding="2" width="100%"><tr>
  13 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  14 <td align="center"><a href="../../../../index.html">Home</a></td>
  15 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  16 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  18 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  19 </tr></table>
  20 <hr>
  21 <div class="spirit-nav">
  22 <a accesskey="p" href="tuple_advanced_interface.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a>
  23 </div>
  24 <div class="article">
  25 <div class="titlepage">
  26 <div>
  27 <div><h2 class="title">
  28 <a name="design_decisions_rationale"></a>Design decisions rationale</h2></div>
  29 <div><p class="copyright">Copyright &#169; 2001 Jaakko J&#228;rvi</p></div>
  30 <div><div class="legalnotice">
  31 <a name="design_decisions_rationale.legal"></a><p>
  32           Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
  33           Software License, Version 1.0</a>.
  34         </p>
  35 </div></div>
  36 </div>
  37 <hr>
  38 </div>
  39 <div class="toc">
  40 <p><b>Table of Contents</b></p>
  41 <dl class="toc">
  42 <dt><span class="section"><a href="design_decisions_rationale.html#design_decisions_rationale.about_namespaces">About namespaces</a></span></dt>
  43 <dt><span class="section"><a href="design_decisions_rationale.html#design_decisions_rationale.the_end_mark_of_the_cons_list_ni">The
  44       end mark of the cons list (<code class="computeroutput"><span class="identifier">nil</span></code>,
  45       <code class="computeroutput"><span class="identifier">null_type</span></code>, ...)</a></span></dt>
  46 <dt><span class="section"><a href="design_decisions_rationale.html#design_decisions_rationale.element_indexing">Element
  47       indexing</a></span></dt>
  48 <dt><span class="section"><a href="design_decisions_rationale.html#design_decisions_rationale.tuple_comparison">Tuple comparison</a></span></dt>
  49 <dt><span class="section"><a href="design_decisions_rationale.html#design_decisions_rationale.streaming">Streaming</a></span></dt>
  50 </dl>
  51 </div>
  52 <div class="section">
  53 <div class="titlepage"><div><div><h3 class="title">
  54 <a name="design_decisions_rationale.about_namespaces"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.about_namespaces" title="About namespaces">About namespaces</a>
  55 </h3></div></div></div>
  56 <p>
  57         There was a discussion about whether tuples should be in a separate namespace
  58         or directly in the <code class="computeroutput"><span class="identifier">boost</span></code>
  59         namespace. The common principle is that domain libraries (like <span class="emphasis"><em>graph</em></span>,
  60         <span class="emphasis"><em>python</em></span>) should be on a separate subnamespace, while
  61         utility like libraries directly in the boost namespace. Tuples are somewhere
  62         in between, as the tuple template is clearly a general utility, but the library
  63         introduces quite a lot of names in addition to just the tuple template. Tuples
  64         were originally under a subnamespace. As a result of the discussion, tuple
  65         definitions were moved directly under the <code class="computeroutput"><span class="identifier">boost</span></code>
  66         namespace. As a result of a continued discussion, the subnamespace was reintroduced.
  67         The final (I truly hope so) solution is now to have all definitions in namespace
  68         <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuples</span></code>,
  69         and the most common names in the <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span></code> namespace as well. This is accomplished
  70         with using declarations (suggested by Dave Abrahams):
  71       </p>
  72 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
  73   <span class="keyword">namespace</span> <span class="identifier">tuples</span> <span class="special">{</span>
  74       <span class="special">...</span>
  75     <span class="comment">// All library code</span>
  76       <span class="special">...</span>
  77   <span class="special">}</span>
  78   <span class="keyword">using</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">;</span>
  79   <span class="keyword">using</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">;</span>
  80   <span class="keyword">using</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">tie</span><span class="special">;</span>
  81   <span class="keyword">using</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">get</span><span class="special">;</span>
  82 <span class="special">}</span>
  83 </pre>
  84 <p>
  85         With this arrangement, tuple creation with direct constructor calls, <code class="computeroutput"><span class="identifier">make_tuple</span></code> or <code class="computeroutput"><span class="identifier">tie</span></code>
  86         functions do not need the namespace qualifier. Further, all functions that
  87         manipulate tuples are found with Koenig-lookup. The only exceptions are the
  88         <code class="computeroutput"><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;</span></code> functions,
  89         which are always called with an explicitly qualified template argument, and
  90         thus Koenig-lookup does not apply. Therefore, <code class="computeroutput"><span class="identifier">get</span></code>
  91         is lifted to <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span></code>
  92         namespace with a using declaration. Hence, the interface for an application
  93         programmer is in practice under the namespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span></code>.
  94       </p>
  95 <p>
  96         The other names, forming an interface for library writers (cons lists, metafunctions
  97         manipulating cons lists, ...) remain in the subnamespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuples</span></code>. Note, that the names <code class="computeroutput"><span class="identifier">ignore</span></code>, <code class="computeroutput"><span class="identifier">set_open</span></code>,
  98         <code class="computeroutput"><span class="identifier">set_close</span></code> and <code class="computeroutput"><span class="identifier">set_delimiter</span></code> are considered to be part
  99         of the application programmer's interface, but are still not under <code class="computeroutput"><span class="identifier">boost</span></code> namespace. The reason being the danger
 100         for name clashes for these common names. Further, the usage of these features
 101         is probably not very frequent.
 102       </p>
 103 <div class="section">
 104 <div class="titlepage"><div><div><h4 class="title">
 105 <a name="design_decisions_rationale.about_namespaces.for_those_who_are_really_interes"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.about_namespaces.for_those_who_are_really_interes" title="For those who are really interested in namespaces">For
 106         those who are really interested in namespaces</a>
 107 </h4></div></div></div>
 108 <p>
 109           The subnamespace name <span class="emphasis"><em>tuples</em></span> raised some discussion.
 110           The rationale for not using the most natural name 'tuple' is to avoid having
 111           an identical name with the tuple template. Namespace names are, however,
 112           not generally in plural form in Boost libraries. First, no real trouble
 113           was reported for using the same name for a namespace and a class and we
 114           considered changing the name 'tuples' to 'tuple'. But we found some trouble
 115           after all. Both gcc and edg compilers reject using declarations where the
 116           namespace and class names are identical:
 117         </p>
 118 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
 119   <span class="keyword">namespace</span> <span class="identifier">tuple</span> <span class="special">{</span>
 120     <span class="special">...</span> <span class="identifier">tie</span><span class="special">(...);</span>
 121     <span class="keyword">class</span> <span class="identifier">tuple</span><span class="special">;</span>
 122       <span class="special">...</span>
 123   <span class="special">}</span>
 124   <span class="keyword">using</span> <span class="identifier">tuple</span><span class="special">::</span><span class="identifier">tie</span><span class="special">;</span> <span class="comment">// ok</span>
 125   <span class="keyword">using</span> <span class="identifier">tuple</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">;</span> <span class="comment">// error</span>
 126     <span class="special">...</span>
 127 <span class="special">}</span>
 128 </pre>
 129 <p>
 130           Note, however, that a corresponding using declaration in the global namespace
 131           seems to be ok:
 132         </p>
 133 <pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">;</span> <span class="comment">// ok;</span>
 134 </pre>
 135 </div>
 136 </div>
 137 <div class="section">
 138 <div class="titlepage"><div><div><h3 class="title">
 139 <a name="design_decisions_rationale.the_end_mark_of_the_cons_list_ni"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.the_end_mark_of_the_cons_list_ni" title="The end mark of the cons list (nil, null_type, ...)">The
 140       end mark of the cons list (<code class="computeroutput"><span class="identifier">nil</span></code>,
 141       <code class="computeroutput"><span class="identifier">null_type</span></code>, ...)</a>
 142 </h3></div></div></div>
 143 <p>
 144         Tuples are internally represented as cons lists:
 145       </p>
 146 <pre class="programlisting"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span>
 147 </pre>
 148 <p>
 149         inherits from
 150       </p>
 151 <pre class="programlisting"><span class="identifier">cons</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">cons</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">null_type</span><span class="special">&gt;</span> <span class="special">&gt;</span>
 152 </pre>
 153 <p>
 154         <code class="computeroutput"><span class="identifier">null_type</span></code> is the end mark
 155         of the list. Original proposition was <code class="computeroutput"><span class="identifier">nil</span></code>,
 156         but the name is used in MacOS, and might have caused problems, so <code class="computeroutput"><span class="identifier">null_type</span></code> was chosen instead. Other names
 157         considered were <span class="emphasis"><em>null_t</em></span> and <span class="emphasis"><em>unit</em></span>
 158         (the empty tuple type in SML).
 159       </p>
 160 <p>
 161         Note that <code class="computeroutput"><span class="identifier">null_type</span></code> is the
 162         internal representation of an empty tuple: <code class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;&gt;</span></code> inherits from <code class="computeroutput"><span class="identifier">null_type</span></code>.
 163       </p>
 164 </div>
 165 <div class="section">
 166 <div class="titlepage"><div><div><h3 class="title">
 167 <a name="design_decisions_rationale.element_indexing"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.element_indexing" title="Element indexing">Element
 168       indexing</a>
 169 </h3></div></div></div>
 170 <p>
 171         Whether to use <code class="computeroutput"><span class="number">0</span></code>- or <code class="computeroutput"><span class="number">1</span></code>-based indexing was discussed more than thoroughly,
 172         and the following observations were made:
 173       </p>
 174 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 175 <li class="listitem">
 176             <code class="computeroutput"><span class="number">0</span></code>-based indexing is 'the
 177             C++ way' and used with arrays etc.
 178           </li>
 179 <li class="listitem">
 180             <code class="computeroutput"><span class="number">1</span></code>-based 'name like' indexing
 181             exists as well, eg. <code class="computeroutput"><span class="identifier">bind1st</span></code>,
 182             <code class="computeroutput"><span class="identifier">bind2nd</span></code>, <code class="computeroutput"><span class="identifier">pair</span><span class="special">::</span><span class="identifier">first</span></code>, etc.
 183           </li>
 184 </ul></div>
 185 <p>
 186         Tuple access with the syntax <code class="computeroutput"><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;(</span><span class="identifier">a</span><span class="special">)</span></code>, or
 187         <code class="computeroutput"><span class="identifier">a</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;()</span></code>
 188         (where <code class="computeroutput"><span class="identifier">a</span></code> is a tuple and
 189         <code class="computeroutput"><span class="identifier">N</span></code> an index), was considered
 190         to be of the first category, hence, the index of the first element in a tuple
 191         is <code class="computeroutput"><span class="number">0</span></code>.
 192       </p>
 193 <p>
 194         A suggestion to provide <code class="computeroutput"><span class="number">1</span></code>-based
 195         'name like' indexing with constants like <code class="computeroutput"><span class="identifier">_1st</span></code>,
 196         <code class="computeroutput"><span class="identifier">_2nd</span></code>, <code class="computeroutput"><span class="identifier">_3rd</span></code>,
 197         ... was made. By suitably chosen constant types, this would allow alternative
 198         syntaxes:
 199       </p>
 200 <pre class="programlisting"><span class="identifier">a</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;()</span> <span class="special">==</span> <span class="identifier">a</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">_1st</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">a</span><span class="special">[</span><span class="identifier">_1st</span><span class="special">]</span> <span class="special">==</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">_1st</span><span class="special">);</span>
 201 </pre>
 202 <p>
 203         We chose not to provide more than one indexing method for the following reasons:
 204       </p>
 205 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 206 <li class="listitem">
 207             <code class="computeroutput"><span class="number">0</span></code>-based indexing might not
 208             please everyone, but once its fixed, it is less confusing than having
 209             two different methods (would anyone want such constants for arrays?).
 210           </li>
 211 <li class="listitem">
 212             Adding the other indexing scheme doesn't really provide anything new
 213             (like a new feature) to the user of the library.
 214           </li>
 215 <li class="listitem">
 216             C++ variable and constant naming rules don't give many possibilities
 217             for defining short and nice index constants (like <code class="computeroutput"><span class="identifier">_1st</span></code>,
 218             ...). Let the binding and lambda libraries use these for a better purpose.
 219           </li>
 220 <li class="listitem">
 221             The access syntax a<span class="underline">1st</span> (or a(_1st))
 222             is appealing, and almost made us add the index constants after all. However,
 223             <code class="computeroutput"><span class="number">0</span></code>-based subscripting is so
 224             deep in C++, that we had a fear for confusion.
 225           </li>
 226 <li class="listitem">
 227             Such constants are easy to add.
 228           </li>
 229 </ul></div>
 230 </div>
 231 <div class="section">
 232 <div class="titlepage"><div><div><h3 class="title">
 233 <a name="design_decisions_rationale.tuple_comparison"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.tuple_comparison" title="Tuple comparison">Tuple comparison</a>
 234 </h3></div></div></div>
 235 <p>
 236         The comparison operator implements lexicographical order. Other orderings
 237         were considered, mainly dominance <span class="emphasis"><em>(a &lt; b iff for each i a(i)
 238         &lt; b(i))</em></span>. Our belief is, that lexicographical ordering, though
 239         not mathematically the most natural one, is the most frequently needed ordering
 240         in everyday programming.
 241       </p>
 242 </div>
 243 <div class="section">
 244 <div class="titlepage"><div><div><h3 class="title">
 245 <a name="design_decisions_rationale.streaming"></a><a class="link" href="design_decisions_rationale.html#design_decisions_rationale.streaming" title="Streaming">Streaming</a>
 246 </h3></div></div></div>
 247 <p>
 248         The characters specified with tuple stream manipulators are stored within
 249         the space allocated by <code class="computeroutput"><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">xalloc</span></code>,
 250         which allocates storage for <code class="computeroutput"><span class="keyword">long</span></code>
 251         type objects. <code class="computeroutput"><span class="keyword">static_cast</span></code> is
 252         used in casting between <code class="computeroutput"><span class="keyword">long</span></code>
 253         and the stream's character type. Streams that have character types not convertible
 254         back and forth to long thus fail to compile.
 255       </p>
 256 <p>
 257         This may be revisited at some point. The two possible solutions are:
 258       </p>
 259 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 260 <li class="listitem">
 261             Allow only plain <code class="computeroutput"><span class="keyword">char</span></code> types
 262             as the tuple delimiters and use <code class="computeroutput"><span class="identifier">widen</span></code>
 263             and <code class="computeroutput"><span class="identifier">narrow</span></code> to convert
 264             between the real character type of the stream. This would always compile,
 265             but some calls to set manipulators might result in a different character
 266             than expected (some default character).
 267           </li>
 268 <li class="listitem">
 269             Allocate enough space to hold the real character type of the stream.
 270             This means memory for holding the delimiter characters must be allocated
 271             separately, and that pointers to this memory are stored in the space
 272             allocated with <code class="computeroutput"><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">xalloc</span></code>.
 273             Any volunteers?
 274           </li>
 275 </ul></div>
 276 </div>
 277 </div>
 278 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 279 <td align="left"><p><small>Last revised: December 10, 2019 at 00:21:48 GMT</small></p></td>
 280 <td align="right"><div class="copyright-footer">Copyright &#169; 2001 Jaakko J&#228;rvi<p>
 281         Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
 282         Software License, Version 1.0</a>.
 283       </p>
 284 </div></td>
 285 </tr></table>
 286 <hr>
 287 <div class="spirit-nav">
 288 <a accesskey="p" href="tuple_advanced_interface.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a>
 289 </div>
 290 </body>
 291 </html>