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 14 <title>Concept Covering and Archetypes</title> 15 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 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="concept-covering" id="concept-covering">Concept Covering and 25 Archetypes</a></h2> 26 27 <p>We have discussed how it is important to select the minimal requirements 28 (concepts) for the inputs to a component, but it is equally important to 29 verify that the chosen concepts <i>cover</i> the algorithm. That is, any 30 possible user error should be caught by the concept checks and not let slip 31 through. Concept coverage can be verified through the use of <i>archetype 32 classes</i>. An archetype class is an exact implementation of the interface 33 associated with a particular concept. The run-time behavior of the 34 archetype class is not important, the functions can be left empty. A simple 35 test program can then be compiled with the archetype classes as the inputs 36 to the component. If the program compiles then one can be sure that the 37 concepts cover the component. The following code shows the archetype class 38 for the <a href="http://www.boost.org/sgi/stl/InputIterator.html">Input 39 Iterator</a> concept. Some care must be taken to ensure that the archetype 40 is an exact match to the concept. For example, the concept states that the 41 return type of <tt>operator*()</tt> must be convertible to the value type. 42 It does not state the more stringent requirement that the return type be 43 <tt>T&</tt> or <tt>const T&</tt>. That means it would be a mistake 44 to use <tt>T&</tt> or <tt>const T&</tt> for the return type of the 45 archetype class. The correct approach is to create an artificial return 46 type that is convertible to <tt>T</tt>, as we have done here with 47 <tt>reference</tt>. The validity of the archetype class test is completely 48 dependent on it being an exact match with the concept, which must be 49 verified by careful (manual) inspection.</p> 50 <pre> 51template <class T> 52class input_iterator_archetype 53{ 54private: 55 typedef input_iterator_archetype self; 56public: 57 typedef std::input_iterator_tag iterator_category; 58 typedef T value_type; 59 struct reference { 60 operator const value_type&() const { return static_object<T>::get(); } 61 }; 62 typedef const T* pointer; 63 typedef std::ptrdiff_t difference_type; 64 self& operator=(const self&) { return *this; } 65 bool operator==(const self&) const { return true; } 66 bool operator!=(const self&) const { return true; } 67 reference operator*() const { return reference(); } 68 self& operator++() { return *this; } 69 self operator++(int) { return *this; } 70}; 71</pre> 72 73 <p>Generic algorithms are often tested by being instantiated with a number 74 of common input types. For example, one might apply 75 <tt>std::stable_sort()</tt> with basic pointer types as the iterators. 76 Though appropriate for testing the run-time behavior of the algorithm, this 77 is not helpful for ensuring concept coverage because C++ types never match 78 particular concepts exactly. Instead, they often provide more than the 79 minimal functionality required by any one concept. Even though the function 80 template has concept checks, and compiles with a given type, the checks may 81 still fall short of covering all the functionality that is actually used. 82 This is why it is important to compile with archetype classes in addition 83 to testing with common input types.</p> 84 85 <p>The following is an excerpt from <a href= 86 "./stl_concept_covering.cpp"><tt>stl_concept_covering.cpp</tt></a> that 87 shows how archetypes can be used to check the requirement documentation for 88 <a href= 89 "http://www.boost.org/sgi/stl/stable_sort.html"><tt>std::stable_sort()</tt></a>. 90 In this case, it looks like the <a href= 91 "../utility/CopyConstructible.html">CopyConstructible</a> and <a href= 92 "../utility/Assignable.html">Assignable</a> requirements were forgotten in 93 the SGI STL documentation (try removing those archetypes). The Boost 94 archetype classes have been designed so that they can be layered. In this 95 example the value type of the iterator is composed out of three archetypes. 96 In the <a href="reference.htm#basic-archetype">archetype class 97 reference</a>, template parameters named <tt>Base</tt> indicate where the 98 layered archetype paradigm can be used.</p> 99 <pre> 100{ 101 typedef less_than_comparable_archetype< 102 sgi_assignable_archetype<> > ValueType; 103 random_access_iterator_archetype<ValueType> ri; 104 std::stable_sort(ri, ri); 105} 106</pre> 107 108 <p><a href="./prog_with_concepts.htm">Next: Programming with 109 Concepts</a><br /> 110 <a href="./creating_concepts.htm">Prev: Creating Concept Checking 111 Classes</a><br /> 112 <hr /> 113 114 <table> 115 <tr valign="top"> 116 <td nowrap="nowrap">Copyright © 2000</td> 117 118 <td><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>(<a href= 119 "mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>) Andrew 120 Lumsdaine(<a href="mailto:lums@osl.iu.edu">lums@osl.iu.edu</a>), 121 2007 <a href="mailto:dave@boost-consulting.com">David Abrahams</a>. 122 </tr> 123 </table> 124</body> 125</html> 126
