ceph/src/boost/libs/concept_check/creating_concepts.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5 <!-- Copyright (c) Jeremy Siek and Andrew Lumsdaine 2000 -->
   6 <!-- Distributed under the Boost -->
   7 <!-- Software License, Version 1.0. (See accompanying -->
   8 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
   9
  10 <head>
  11   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  12   <meta name="generator" content=
  13   "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
  14
  15   <title>Creating Concept Checking Classes</title>
  16   <link rel="stylesheet" href="../../rst.css" type="text/css" />
  17 </head>
  18
  19 <body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
  20 "#FF0000">
  21   <img src="../../boost.png" alt="C++ Boost" width="277" height=
  22   "86" /><br clear="none" />
  23
  24   <h2><a name="creating-concept-checks" id="creating-concept-checks">Creating
  25   Concept Checking Classes</a></h2>
  26
  27   <p>As an example of how to create a concept checking class template, we
  28   look at how to create the corresponding checks for the <a href=
  29   "http://www.boost.org/sgi/stl/InputIterator.html">InputIterator</a> concept.
  30   The complete definition is here:</p>
  31   <pre>
  32 template &lt;class X&gt;
  33 struct InputIterator
  34   : Assignable&lt;X&gt;, EqualityComparable&lt;X&gt;
  35 {
  36  private:
  37     typedef std::iterator_traits&lt;X&gt; t;
  38  public:
  39     typedef typename t::value_type value_type;
  40     typedef typename t::difference_type difference_type;
  41     typedef typename t::reference reference;
  42     typedef typename t::pointer pointer;
  43     typedef typename t::iterator_category iterator_category;
  44
  45     BOOST_CONCEPT_ASSERT((SignedInteger&lt;difference_type&gt;));
  46     BOOST_CONCEPT_ASSERT((Convertible&lt;iterator_category, std::input_iterator_tag&gt;));
  47
  48     BOOST_CONCEPT_USAGE(InputIterator)
  49     {
  50         X j(i);             <font color=
  51 "green">// require copy construction</font>
  52         same_type(*i++,v);  <font color=
  53 "green">// require postincrement-dereference returning value_type</font>
  54         X&amp; x = ++j;         <font color=
  55 "green">// require preincrement returning X&amp;</font>
  56     }
  57
  58  private:
  59     X i;
  60     value_type v;
  61
  62     <font color=
  63 "green">// Type deduction will fail unless the arguments have the same type.</font>
  64     template &lt;typename T&gt;
  65     void same_type(T const&amp;, T const&amp;);
  66 };
  67 </pre>
  68
  69   <h3>Walkthrough</h3>
  70
  71   <p>First, as a convention we name the concept checking class after the
  72   concept. Next, since InputIterator is a refinement of Assignable and
  73   EqualityComparable, we derive its concept checking class from the checking
  74   classes for those other concepts. The library will automatically check for
  75   conformance to Assignable and EqualityComparable whenever it checks the
  76   InputIterator concept.</p>
  77
  78   <p>Next, we declare the concept's <a href=
  79   "http://www.boost.org/more/generic_programming.html#associated_type">associated types</a>
  80   as member typedefs. The associated difference type is required to be a
  81   signed integer, and the iterator category has to be convertible to
  82   std::input_iterator_tag, so we assert those relationships. The syntax for
  83   accessing associated types through the concept-checking template mirrors
  84   the <a href=
  85   "http://www.generic-programming.org/languages/conceptcpp/">proposed</a>
  86   syntax for associated type access in C++0x Finally, we use the
  87   <code>BOOST_CONCEPT_USAGE</code> macro to declare the function that
  88   exercises all the concept's valid expressions. Note that at this point you
  89   may sometimes need to be a little creative: for example, to check that
  90   <code>*i++</code> returns the iterator's value type, we pass both values to
  91   the <code>same_type</code> member function template, which requires both
  92   arguments to have the same type, modulo references and cv-qualification.
  93   It's an imperfect check, but it's better than nothing.</p>
  94
  95   <h3>Values for Usage Patterns Should Be Data Members</h3>
  96
  97   <p>You may be wondering why we declared <code>i</code> and <code>v</code>
  98   as data members in the example above. Why didn't we simply write the
  99   following?</p>
 100   <pre>
 101 BOOST_CONCEPT_USAGE(InputIterator)
 102 {
 103     X i;                <font color=
 104 "green">// create the values we need</font>
 105     value_type v;
 106
 107     X j(i);             <font color=
 108 "green">// require copy construction</font>
 109     same_type(*i++,v);  <font color=
 110 "green">// require postincrement-dereference returning value_type</font>
 111     X&amp; x = ++j;         <font color=
 112 "green">// require preincrement returning X&amp;</font>
 113 }
 114 </pre>
 115
 116   <p>Unfortunately, that code wouldn't have worked out so well, because it
 117   unintentionally imposes the requirement that <code>X</code> and its value
 118   type are both default-constructible. On the other hand, since instances of
 119   the <code>InputIterator</code> template will never be constructed, the
 120   compiler never has to check how its data members will be constructed (C++
 121   Standard Section 14.7.1 9). For that reason you should <strong>always
 122   declare values needed for usage patterns as data members</strong>.</p>
 123
 124   <p>These sorts of errors in concept definitions can be detected by the use
 125   of <a href="concept_covering.htm">Concept Archetypes</a>, but it's always
 126   better to avoid them pre-emptively.</p>
 127
 128   <h3>Similarity to Proposed C++0x Language Support for Concepts</h3>
 129
 130   <p>This library's syntaxes for concept refinement and for access of
 131   associated types mirrors the corresponding <a href=
 132   "http://www.generic-programming.org/languages/conceptcpp/">proposed</a>
 133   syntaxes in C++0x. However, C++0x will use
 134   “signatures” rather than usage patterns to
 135   describe the valid operations on types participating in a concept, so when
 136   converting your concept checking classes into language-supported concepts,
 137   you'll need to translate your usage function into a series of
 138   signatures.</p>
 139
 140   <p><a href="./concept_covering.htm">Next: Concept Covering and
 141   Archetypes</a><br />
 142   <a href="./using_concept_check.htm">Prev: Using Concept
 143   Checks</a><br /></p>
 144   <hr />
 145
 146   <table>
 147     <tr valign="top">
 148       <td nowrap="nowrap">Copyright &copy; 2000</td>
 149
 150       <td><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>(<a href=
 151       "mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>) Andrew
 152       Lumsdaine(<a href="mailto:lums@osl.iu.edu">lums@osl.iu.edu</a>),
 153         2007 <a href="mailto:dave@boost-consulting.com">David Abrahams</a>.
 154     </tr>
 155   </table>
 156 </body>
 157 </html>