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.boost.org/sgi/stl/EqualityComparable.html">EqualityComparable</a> 47 concept documented in the SGI STL.</p> 48 <pre> 49template <class T> 50struct EqualityComparable; 51</pre> 52 53 <p>The template argument is the type to be checked. That is, the purpose of 54 <tt>EqualityComparable<<em>T</em>></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 <class T> 68void generic_library_function(T x) 69{ 70 BOOST_CONCEPT_ASSERT<strong>((</strong>EqualityComparable<T><strong>))</strong>; 71 <font color="green">// ...</font> 72}; 73 74template <class It> 75class 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> 82class foo { 83 <font color="green">//... </font> 84}; 85 86int 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: </p> 116 <pre> 117template <class RanIter> 118BOOST_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> 143template <class G, class Buffer, class BFSVisitor, 144 class ColorMap> 145BOOST_CONCEPT_REQUIRES( 146 ((ReadWritePropertyMap<ColorMap, typename IncidenceGraph<G>::vertex_descriptor>)), 147 (void)) <font color="green">// return type</font> 148breadth_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> 166BOOST_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> 187
