Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/concept_check/using_concept_check.htm @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost
File size: 7.6 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.
104
105<pre>
106  // In my library:
107  template &lt;class T&gt;
108  struct generic_library_class
109  {
110    BOOST_CLASS_REQUIRE(T, boost, EqualityComparableConcept);
111    // ...
112  };
113
114  // In the user's code: 
115  class foo {
116    //...
117  };
118
119  int main() {
120    generic_library_class&lt;foo&gt; glc;
121    // ...
122    return 0;
123  }
124</pre>
125
126
127<h4>Example</h4>
128
129<p>
130Getting back to the earlier <a
131href="./concept_check.htm#motivating-example">motivating example</a>,
132one good application of concept checks would be to insert
133<tt>function_requires()</tt> at the top of <tt>std::stable_sort()</tt>
134to make sure the template parameter type models <a
135href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">
136RandomAccessIterator</a>. In addition, <tt>std::stable_sort()</tt>
137requires that the <tt>value_type</tt> of the iterators be
138<a href="http://www.sgi.com/tech/stl/LessThanComparable.html">
139LessThanComparable</a>, so we also use <tt>function_requires()</tt> to
140check this.
141
142<pre>
143  template &lt;class RandomAccessIter&gt;
144  void stable_sort(RandomAccessIter first, RandomAccessIter last)
145  {
146    function_requires&lt; RandomAccessIteratorConcept&lt;RandomAccessIter&gt; &gt;();
147    typedef typename std::iterator_traits&lt;RandomAccessIter&gt;::value_type value_type;
148    function_requires&lt; LessThanComparableConcept&lt;value_type&gt; &gt;();
149    ...
150  }
151</pre>
152
153
154
155<!-- There are a few places where the SGI STL documentation differs
156from the corresponding requirements described in the C++ Standard. In
157these cases we use the definition from the C++ Standard.  -->
158
159<p>
160Some concepts deal with more than one type. In this case the
161corresponding concept checking class will have multiple template
162parameters.  The following example shows how
163<tt>function_requires()</tt> is used with the <a
164href="../property_map/ReadWritePropertyMap.html">ReadWritePropertyMap</a>
165concept which takes two type parameters: a property map and the key
166type for the map.
167
168<pre>
169  template &lt;class IncidenceGraph, class Buffer, class BFSVisitor,
170            class ColorMap&gt;
171  void breadth_first_search(IncidenceGraph& g,
172    typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor s,
173    Buffer& Q, BFSVisitor vis, ColorMap color)
174  {
175    typedef typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor Vertex;
176    function_requires&lt; ReadWritePropertyMap&lt;ColorMap, Vertex&gt; &gt;();
177    ...
178  }
179</pre>
180
181
182As an example of using <tt>BOOST_CLASS_REQUIRE</tt> we look at a concept
183check that could be added to <tt>std::vector</tt>. One requirement
184that is placed on the element type is that it must be <a
185href="http://www.sgi.com/tech/stl/Assignable.html">Assignable</a>.
186We can check this by inserting
187<tt>class_requires&lt;AssignableConcept&lt;T&gt; &gt;</tt> at the top
188of the definition for <tt>std::vector</tt>.
189
190<pre>
191  namespace std {
192    template &lt;class T&gt;
193    struct vector {
194      BOOST_CLASS_REQUIRE(T, boost, AssignableConcept);
195      ...
196    };
197  }
198</pre>
199
200
201Although the concept checks are designed for use by generic library
202implementors, they can also be useful to end users. Sometimes one may
203not be sure whether some type models a particular concept. This can
204easily be checked by creating a small program and using
205<tt>function_requires()</tt> with the type and concept in question.
206The file <a
207href="./stl_concept_check.cpp"><tt>stl_concept_checks.cpp</tt></a>
208gives and example of applying the concept checks to STL containers.
209
210<p>
211<a href="./concept_check.htm">Prev: Concept Checking Introduction</a> <br>
212<a href="./creating_concepts.htm">Next: Creating Concept Checking Classes</a>
213
214<br>
215<HR>
216<TABLE>
217<TR valign=top>
218<TD nowrap>Copyright &copy 2000</TD><TD>
219<A HREF="../../people/jeremy_siek.htm">Jeremy Siek</A>(<A
220HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)
221Andrew Lumsdaine</A>(<A HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>)
222</TD></TR></TABLE>
223
224</BODY>
225</HTML> 
Note: See TracBrowser for help on using the repository browser.