]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 <class T> | |
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<<em>X</em>></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 <class T> | |
68 | void generic_library_function(T x) | |
69 | { | |
70 | BOOST_CONCEPT_ASSERT<strong>((</strong>EqualityComparable<T><strong>))</strong>; | |
71 | <font color="green">// ...</font> | |
72 | }; | |
73 | ||
74 | template <class It> | |
75 | class generic_library_class | |
76 | { | |
77 | BOOST_CONCEPT_ASSERT<strong>((</strong>RandomAccessIterator<It><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<std::vector<char>::iterator> 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<typename RanIter> | |
118 | BOOST_CONCEPT_REQUIRES( | |
119 | ((Mutable_RandomAccessIterator<RanIter>)) | |
120 | ((LessThanComparable<typename Mutable_RandomAccessIterator<RanIter>::value_type>)), | |
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 <class G, class Buffer, class BFSVisitor, | |
144 | class ColorMap> | |
145 | BOOST_CONCEPT_REQUIRES( | |
146 | ((ReadWritePropertyMap<ColorMap, typename IncidenceGraph<G>::vertex_descriptor>)), | |
147 | (void)) <font color="green">// return type</font> | |
148 | breadth_first_search(G& g, | |
149 | typename graph_traits<IncidenceGraph>::vertex_descriptor s, | |
150 | Buffer& Q, BFSVisitor vis, ColorMap color) | |
151 | { | |
152 | typedef typename IncidenceGraph<G>::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<int> has bidirectional iterators.</font> | |
166 | BOOST_CONCEPT_ASSERT((BidirectionalIterator<std::list<int>::iterator>)); | |
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 © 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> |