Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / bca6d25af494f6ecfb6ecab60094dae251570c14 / . / using_concept_check.htm
blob: 80c95cbd54f36e80a28e60ad6b842f441ad6b644 [file] [log] [blame]
Brian Silvermanbca6d252018-08-04 23:36:16 -0700[diff] [blame^]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>
49template &lt;class T&gt;
50struct 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>T</em>&gt;</tt> is to make sure that
55 <tt><em>T</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>
67template &lt;class T&gt;
68void 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
74template &lt;class It&gt;
75class 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>
82class foo {
83 <font color="green">//... </font>
84};
85
86int 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: </p>
116 <pre>
117template &lt;class RanIter&gt;
118BOOST_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>
143template &lt;class G, class Buffer, class BFSVisitor,
144 class ColorMap&gt;
145BOOST_CONCEPT_REQUIRES(
146 ((ReadWritePropertyMap&lt;ColorMap, typename IncidenceGraph&lt;G&gt;::vertex_descriptor&gt;)),
147 (void)) <font color="green">// return type</font>
148breadth_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>
166BOOST_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>