ceph/src/boost/libs/concept_check/using_concept_check.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 name="generator" content=
  12   "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
  13   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
  14
  15   <title>Using Concept Checks</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="using-concept-checks" id="using-concept-checks">Using Concept
  25   Checks</a></h2>
  26
  27   <p>For each concept there is a concept checking class template that can be
  28   used to make sure that a given type (or set of types) models the concept.
  29   The Boost Concept Checking Library (BCCL) includes concept checking class
  30   templates for all of the concepts used in the C++ standard library and a
  31   few more. See the <a href="./reference.htm">Reference</a> section for a
  32   complete list. In addition, other boost libraries come with concept
  33   checking classes for the concepts that are particular to those libraries.
  34   For example, there are <a href="../graph/doc/graph_concepts.html">graph
  35   concepts</a> and <a href="../property_map/doc/property_map.html">property map
  36   concepts</a>. Also, whenever <b>anyone</b> writing function templates needs
  37   to express requirements that are not yet stated by an existing concept, a
  38   new concept checking class should be created. How to do this is explained
  39   in <a href="./creating_concepts.htm">Creating Concept Checking
  40   Classes</a>.</p>
  41
  42   <p>An example of a concept checking class from the BCCL is the
  43   <tt>EqualityComparableConcept</tt> class. The class corresponds to the
  44   EqualityComparable requirements described in 20.1.1 of the C++ Standard,
  45   and to the <a href=
  46   "http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a>
  47   concept documented in the SGI STL.</p>
  48   <pre>
  49 template &lt;class T&gt;
  50 struct EqualityComparable;
  51 </pre>
  52
  53   <p>The template argument is the type to be checked. That is, the purpose of
  54   <tt>EqualityComparable&lt;<em>X</em>&gt;</tt> is to make sure that
  55   <tt><em>X</em></tt> models the EqualityComparable concept.</p>
  56
  57   <h4><tt>BOOST_CONCEPT_ASSERT()</tt></h4>
  58
  59   <p>The most versatile way of checking concept requirements is to use the
  60   <code>BOOST_CONCEPT_ASSERT()</code> macro. You can use this macro at any
  61   scope, by passing a concept checking template specialization enclosed in
  62   parentheses. <strong>Note:</strong> that means invocations of
  63   <code>BOOST_CONCEPT_ASSERT</code> will appear to use <strong>double
  64   parentheses</strong>.</p>
  65   <pre>
  66 <font color="green">// In my library:</font>
  67 template &lt;class T&gt;
  68 void generic_library_function(T x)
  69 {
  70   BOOST_CONCEPT_ASSERT<strong>((</strong>EqualityComparable&lt;T&gt;<strong>))</strong>;
  71   <font color="green">// ...</font>
  72 };
  73
  74 template &lt;class It&gt;
  75 class generic_library_class
  76 {
  77   BOOST_CONCEPT_ASSERT<strong>((</strong>RandomAccessIterator&lt;It&gt;<strong>))</strong>;
  78   <font color="green">// ...</font>
  79 };
  80
  81 <font color="green">// In the user's code:</font>
  82 class foo {
  83   <font color="green">//... </font>
  84 };
  85
  86 int main() {
  87   foo x;
  88   generic_library_function(x);
  89   generic_library_class&lt;std::vector&lt;char&gt;::iterator&gt; y;
  90   <font color="green">//...</font>
  91 }
  92 </pre>
  93
  94   <h4><tt>BOOST_CONCEPT_REQUIRES</tt></h4>
  95
  96   <p>One of the nice things about the proposed C++0x <a href=
  97   "http://www.generic-programming.org/languages/conceptcpp/tutorial">syntax
  98   for declaring concept constrained function templates</a> is the way that
  99   constraints are part of the function <em>declaration</em>, so clients will
 100   see them. <code>BOOST_CONCEPT_ASSERT</code> can only express constraints
 101   within the function template definition, which hides the constraint in the
 102   function body. Aside from the loss of a self-documenting interface,
 103   asserting conformance only in the function body can undesirably delay
 104   checking if the function is explicitly instantiated in a different
 105   translation unit from the one in which it is called, or if the compiler
 106   does link-time instantiation.</p>
 107
 108   <p>The <tt>BOOST_CONCEPT_REQUIRES</tt> macro can be used in a function
 109   template declaration to check whether some type models a concept. It
 110   accepts two arguments, a <strong>list of constraints</strong>, and the
 111   function template's return type. The list of constraints takes the form of
 112   a sequence of adjacent concept checking template specializations,
 113   <strong>in double parentheses</strong>, and the function's return type must
 114   also be parenthesized. For example, the standard <code>stable_sort</code>
 115   algorithm might be declared as follows: class</p>
 116   <pre>
 117 template&lt;typename RanIter&gt;
 118 BOOST_CONCEPT_REQUIRES(
 119     ((Mutable_RandomAccessIterator&lt;RanIter&gt;))
 120     ((LessThanComparable&lt;typename Mutable_RandomAccessIterator&lt;RanIter&gt;::value_type&gt;)),
 121     (void)) <font color="green">// return type</font>
 122     stable_sort(RanIter,RanIter);
 123 </pre>
 124
 125   <p>Note that the algorithm requires that the value type of the iterator be
 126   LessThanComparable, and it accesses that value type through the
 127   <code>Mutable_RandomAccessIterator</code> concept checking template. In
 128   general, the Boost concept checking classes expose associated types as
 129   nested member typedefs so that you can use this syntax, which mimics the
 130   approach used in the concept support proposed for the next version of
 131   C++.</p>
 132
 133   <h4>Multi-Type Concepts</h4>
 134
 135   <p>Some concepts deal with more than one type. In this case the
 136   corresponding concept checking class will have multiple template
 137   parameters. The following example shows how <tt>BOOST_CONCEPT_REQUIRES</tt>
 138   is used with the <a href=
 139   "../property_map/doc/ReadWritePropertyMap.html">ReadWritePropertyMap</a>
 140   concept, which takes two type parameters: a property map and the key type
 141   for the map.</p>
 142   <pre>
 143 template &lt;class G, class Buffer, class BFSVisitor,
 144           class ColorMap&gt;
 145 BOOST_CONCEPT_REQUIRES(
 146   ((ReadWritePropertyMap&lt;ColorMap, typename IncidenceGraph&lt;G&gt;::vertex_descriptor&gt;)),
 147   (void)) <font color="green">// return type</font>
 148 breadth_first_search(G&amp; g,
 149   typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor s,
 150   Buffer&amp; Q, BFSVisitor vis, ColorMap color)
 151 {
 152   typedef typename IncidenceGraph&lt;G&gt;::vertex_descriptor Vertex;
 153   ...
 154 }
 155 </pre>
 156
 157   <p>Although concept checks are designed for use by generic library
 158   implementors, they can also be useful to end users. Sometimes one may not
 159   be sure whether some type models a particular concept. The syntactic
 160   requirements, at least, can easily be checked by creating a small program
 161   and using <tt>BOOST_CONCEPT_ASSERT</tt> with the type and concept in
 162   question. For example:</p>
 163   <pre>
 164 <font color=
 165 "green">// Make sure list&lt;int&gt; has bidirectional iterators.</font>
 166 BOOST_CONCEPT_ASSERT((BidirectionalIterator&lt;std::list&lt;int&gt;::iterator&gt;));
 167 </pre>
 168
 169   <p><a href="./concept_check.htm">Prev: Concept Checking
 170   Introduction</a><br />
 171   <a href="./creating_concepts.htm">Next: Creating Concept Checking
 172   Classes</a><br /></p>
 173   <hr />
 174
 175   <table>
 176     <tr valign="top">
 177       <td nowrap="nowrap">Copyright &copy; 2000</td>
 178
 179       <td><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>(<a href=
 180       "mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>) Andrew
 181       Lumsdaine(<a href="mailto:lums@osl.iu.edu">lums@osl.iu.edu</a>), 2007
 182       <a href="mailto:dave@boost-consulting.com">David Abrahams</a>.</td>
 183     </tr>
 184   </table>
 185 </body>
 186 </html>