Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/concept_check/using_concept_check.htm @ 33

Last change on this file since 33 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 7.7 KB
Line 
1<HTML>
2<!--
3  -- Copyright (c) Jeremy Siek and Andrew Lumsdaine 2000
4  --
5  -- Permission to use, copy, modify, distribute and sell this software
6  -- and its documentation for any purpose is hereby granted without fee,
7  -- provided that the above copyright notice appears in all copies and
8  -- that both that copyright notice and this permission notice appear
9  -- in supporting documentation.  We make no
10  -- representations about the suitability of this software for any
11  -- purpose.  It is provided "as is" without express or implied warranty.
12  -->
13<Head>
14<Title>Using Concept Checks</Title>
15<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
16        ALINK="#ff0000"> 
17<IMG SRC="../../boost.png" 
18     ALT="C++ Boost" width="277" height="86"> 
19
20<BR Clear>
21
22
23<h2><a name="using-concept-checks">Using Concept Checks</a></h2>
24
25For each concept there is a concept checking class which can be used
26to make sure that a given type (or set of types) models the concept.
27The Boost Concept Checking Library (BCCL) includes concept checking classes
28for all of the concepts used in the C++ standard library and a few
29more. The <a href="./reference.htm">Reference</a> section lists these
30concept checking classes. In addition, other boost libraries come with
31concept checking classes for the concepts that are particular to those
32libraries. For example, there are <a
33href="../graph/doc/graph_concepts.html">graph concepts</a> and <a
34href="../property_map/property_map.html">property map concepts</a>.
35Also, whenever <b>anyone</b> writing a class of function template
36needs to express requirements that are not yet stated by an existing
37concept, a new concept checking class should be created. How
38to do this is explained in <a href="./creating_concepts.htm">Creating
39Concept Checking Classes</a>.
40
41<p>
42An example of a concept checking class from the BCCL is the
43<tt>EqualityComparableConcept</tt> class. The class corresponds to the
44EqualityComparable requirements described in 20.1.1 of the C++
45Standard, and to the <a
46href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a>
47concept documented in the SGI STL.
48
49<pre>
50  template &lt;class T&gt;
51  struct EqualityComparableConcept;
52</pre>
53
54The template argument <tt>T</tt> will the type to be checked. That is,
55the purpose of <tt>EqualityComparableConcept</tt> is to make sure that
56the template argument given for <tt>T</tt> models the
57EqualityComparable concept.
58
59<p>
60Each concept checking class has a member function named
61<tt>constraints()</tt> which contains the valid expressions for the
62concept. To check whether some type is EqualityComparable we need to
63instantiate the concept checking class with the type and then find a
64way to get the compiler to compile the <tt>constraints()</tt> function
65without actually executing the function. The Boost Concept Checking
66Library defines two utilities that make this easy:
67<tt>function_requires()</tt> and <tt>BOOST_CLASS_REQUIRE</tt>.
68
69<h4><tt>function_requires()</tt></h4>
70
71The <tt>function_requires()</tt> function can be used in function bodies
72and the <tt>BOOST_CLASS_REQUIRE</tt> macro can be used inside class
73bodies. The <tt>function_requires()</tt> function takes no arguments,
74but has a template parameter for the concept checking class. This
75means that the instantiated concept checking class must be given as an
76explicit template argument, as shown below.
77
78<pre>
79  // In my library:
80  template &lt;class T&gt;
81  void generic_library_function(T x)
82  {
83    function_requires&lt; EqualityComparableConcept&lt;T&gt; &gt;();
84    // ...
85  };
86
87  // In the user's code: 
88  class foo {
89    //...
90  };
91
92  int main() {
93    foo f;
94    generic_library_function(f);
95    return 0;
96  }
97</pre>
98
99
100<h4><tt>BOOST_CLASS_REQUIRE</tt></h4>
101
102The <tt>BOOST_CLASS_REQUIRE</tt> macro can be used inside a class
103definition to check whether some type models a concept.  Make sure
104that the arguments to this macro are simply identifiers. You may need
105to use typedef to get your types into this form.
106
107<pre>
108  // In my library:
109  template &lt;class T&gt;
110  struct generic_library_class
111  {
112    BOOST_CLASS_REQUIRE(T, boost, EqualityComparableConcept);
113    // ...
114  };
115
116  // In the user's code: 
117  class foo {
118    //...
119  };
120
121  int main() {
122    generic_library_class&lt;foo&gt; glc;
123    // ...
124    return 0;
125  }
126</pre>
127
128
129<h4>Example</h4>
130
131<p>
132Getting back to the earlier <a
133href="./concept_check.htm#motivating-example">motivating example</a>,
134one good application of concept checks would be to insert
135<tt>function_requires()</tt> at the top of <tt>std::stable_sort()</tt>
136to make sure the template parameter type models <a
137href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">
138RandomAccessIterator</a>. In addition, <tt>std::stable_sort()</tt>
139requires that the <tt>value_type</tt> of the iterators be
140<a href="http://www.sgi.com/tech/stl/LessThanComparable.html">
141LessThanComparable</a>, so we also use <tt>function_requires()</tt> to
142check this.
143
144<pre>
145  template &lt;class RandomAccessIter&gt;
146  void stable_sort(RandomAccessIter first, RandomAccessIter last)
147  {
148    function_requires&lt; RandomAccessIteratorConcept&lt;RandomAccessIter&gt; &gt;();
149    typedef typename std::iterator_traits&lt;RandomAccessIter&gt;::value_type value_type;
150    function_requires&lt; LessThanComparableConcept&lt;value_type&gt; &gt;();
151    ...
152  }
153</pre>
154
155
156
157<!-- There are a few places where the SGI STL documentation differs
158from the corresponding requirements described in the C++ Standard. In
159these cases we use the definition from the C++ Standard.  -->
160
161<p>
162Some concepts deal with more than one type. In this case the
163corresponding concept checking class will have multiple template
164parameters.  The following example shows how
165<tt>function_requires()</tt> is used with the <a
166href="../property_map/ReadWritePropertyMap.html">ReadWritePropertyMap</a>
167concept which takes two type parameters: a property map and the key
168type for the map.
169
170<pre>
171  template &lt;class IncidenceGraph, class Buffer, class BFSVisitor,
172            class ColorMap&gt;
173  void breadth_first_search(IncidenceGraph& g,
174    typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor s,
175    Buffer& Q, BFSVisitor vis, ColorMap color)
176  {
177    typedef typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor Vertex;
178    function_requires&lt; ReadWritePropertyMap&lt;ColorMap, Vertex&gt; &gt;();
179    ...
180  }
181</pre>
182
183
184As an example of using <tt>BOOST_CLASS_REQUIRE</tt> we look at a concept
185check that could be added to <tt>std::vector</tt>. One requirement
186that is placed on the element type is that it must be <a
187href="http://www.sgi.com/tech/stl/Assignable.html">Assignable</a>.
188We can check this by inserting
189<tt>class_requires&lt;AssignableConcept&lt;T&gt; &gt;</tt> at the top
190of the definition for <tt>std::vector</tt>.
191
192<pre>
193  namespace std {
194    template &lt;class T&gt;
195    struct vector {
196      BOOST_CLASS_REQUIRE(T, boost, AssignableConcept);
197      ...
198    };
199  }
200</pre>
201
202
203Although the concept checks are designed for use by generic library
204implementors, they can also be useful to end users. Sometimes one may
205not be sure whether some type models a particular concept. This can
206easily be checked by creating a small program and using
207<tt>function_requires()</tt> with the type and concept in question.
208The file <a
209href="./stl_concept_check.cpp"><tt>stl_concept_checks.cpp</tt></a>
210gives and example of applying the concept checks to STL containers.
211
212<p>
213<a href="./concept_check.htm">Prev: Concept Checking Introduction</a> <br>
214<a href="./creating_concepts.htm">Next: Creating Concept Checking Classes</a>
215
216<br>
217<HR>
218<TABLE>
219<TR valign=top>
220<TD nowrap>Copyright &copy 2000</TD><TD>
221<A HREF="../../people/jeremy_siek.htm">Jeremy Siek</A>(<A
222HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)
223Andrew Lumsdaine</A>(<A HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>)
224</TD></TR></TABLE>
225
226</BODY>
227</HTML> 
Note: See TracBrowser for help on using the repository browser.