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 http-equiv="Content-Type" content="text/html; charset=utf-8" /> 12 <meta name="generator" content= 13 "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" /> 14 15 <title>Creating Concept Checking Classes</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="creating-concept-checks" id="creating-concept-checks">Creating 25 Concept Checking Classes</a></h2> 26 27 <p>As an example of how to create a concept checking class template, we 28 look at how to create the corresponding checks for the <a href= 29 "http://www.boost.org/sgi/stl/InputIterator.html">InputIterator</a> concept. 30 The complete definition is here:</p> 31 <pre> 32template <class X> 33struct InputIterator 34 : Assignable<X>, EqualityComparable<X> 35{ 36 private: 37 typedef std::iterator_traits<X> t; 38 public: 39 typedef typename t::value_type value_type; 40 typedef typename t::difference_type difference_type; 41 typedef typename t::reference reference; 42 typedef typename t::pointer pointer; 43 typedef typename t::iterator_category iterator_category; 44 45 BOOST_CONCEPT_ASSERT((SignedInteger<difference_type>)); 46 BOOST_CONCEPT_ASSERT((Convertible<iterator_category, std::input_iterator_tag>)); 47 48 BOOST_CONCEPT_USAGE(InputIterator) 49 { 50 X j(i); <font color= 51"green">// require copy construction</font> 52 same_type(*i++,v); <font color= 53"green">// require postincrement-dereference returning value_type</font> 54 X& x = ++j; <font color= 55"green">// require preincrement returning X&</font> 56 } 57 58 private: 59 X i; 60 value_type v; 61 62 <font color= 63"green">// Type deduction will fail unless the arguments have the same type.</font> 64 template <typename T> 65 void same_type(T const&, T const&); 66}; 67</pre> 68 69 <h3>Walkthrough</h3> 70 71 <p>First, as a convention we name the concept checking class after the 72 concept. Next, since InputIterator is a refinement of Assignable and 73 EqualityComparable, we derive its concept checking class from the checking 74 classes for those other concepts. The library will automatically check for 75 conformance to Assignable and EqualityComparable whenever it checks the 76 InputIterator concept.</p> 77 78 <p>Next, we declare the concept's <a href= 79 "http://www.boost.org/more/generic_programming.html#associated_type">associated types</a> 80 as member typedefs. The associated difference type is required to be a 81 signed integer, and the iterator category has to be convertible to 82 std::input_iterator_tag, so we assert those relationships. The syntax for 83 accessing associated types through the concept-checking template mirrors 84 the <a href= 85 "http://www.generic-programming.org/languages/conceptcpp/">proposed</a> 86 syntax for associated type access in C++0x Finally, we use the 87 <code>BOOST_CONCEPT_USAGE</code> macro to declare the function that 88 exercises all the concept's valid expressions. Note that at this point you 89 may sometimes need to be a little creative: for example, to check that 90 <code>*i++</code> returns the iterator's value type, we pass both values to 91 the <code>same_type</code> member function template, which requires both 92 arguments to have the same type, modulo references and cv-qualification. 93 It's an imperfect check, but it's better than nothing.</p> 94 95 <h3>Values for Usage Patterns Should Be Data Members</h3> 96 97 <p>You may be wondering why we declared <code>i</code> and <code>v</code> 98 as data members in the example above. Why didn't we simply write the 99 following?</p> 100 <pre> 101BOOST_CONCEPT_USAGE(InputIterator) 102{ 103 X i; <font color= 104"green">// create the values we need</font> 105 value_type v; 106 107 X j(i); <font color= 108"green">// require copy construction</font> 109 same_type(*i++,v); <font color= 110"green">// require postincrement-dereference returning value_type</font> 111 X& x = ++j; <font color= 112"green">// require preincrement returning X&</font> 113} 114</pre> 115 116 <p>Unfortunately, that code wouldn't have worked out so well, because it 117 unintentionally imposes the requirement that <code>X</code> and its value 118 type are both default-constructible. On the other hand, since instances of 119 the <code>InputIterator</code> template will never be constructed, the 120 compiler never has to check how its data members will be constructed (C++ 121 Standard Section 14.7.1 9). For that reason you should <strong>always 122 declare values needed for usage patterns as data members</strong>.</p> 123 124 <p>These sorts of errors in concept definitions can be detected by the use 125 of <a href="concept_covering.htm">Concept Archetypes</a>, but it's always 126 better to avoid them pre-emptively.</p> 127 128 <h3>Similarity to Proposed C++0x Language Support for Concepts</h3> 129 130 <p>This library's syntaxes for concept refinement and for access of 131 associated types mirrors the corresponding <a href= 132 "http://www.generic-programming.org/languages/conceptcpp/">proposed</a> 133 syntaxes in C++0x. However, C++0x will use 134 “signatures” rather than usage patterns to 135 describe the valid operations on types participating in a concept, so when 136 converting your concept checking classes into language-supported concepts, 137 you'll need to translate your usage function into a series of 138 signatures.</p> 139 140 <p><a href="./concept_covering.htm">Next: Concept Covering and 141 Archetypes</a><br /> 142 <a href="./using_concept_check.htm">Prev: Using Concept 143 Checks</a><br /></p> 144 <hr /> 145 146 <table> 147 <tr valign="top"> 148 <td nowrap="nowrap">Copyright © 2000</td> 149 150 <td><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>(<a href= 151 "mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>) Andrew 152 Lumsdaine(<a href="mailto:lums@osl.iu.edu">lums@osl.iu.edu</a>), 153 2007 <a href="mailto:dave@boost-consulting.com">David Abrahams</a>. 154 </tr> 155 </table> 156</body> 157</html> 158
