Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/concept_check/concept_covering.htm @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 5.4 KB
Line 
1<HTML>
2<!--
3  -- Copyright (c) Jeremy Siek and Andrew Lumsdaine 2000
4  --
5  -- Permission to use, copy, modify, distribute and sell this software
6  -- and its documentation for any purpose is hereby granted without fee,
7  -- provided that the above copyright notice appears in all copies and
8  -- that both that copyright notice and this permission notice appear
9  -- in supporting documentation.  We make no
10  -- representations about the suitability of this software for any
11  -- purpose.  It is provided "as is" without express or implied warranty.
12  -->
13<Head>
14<Title>Concept Covering and Archetypes</Title>
15<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
16        ALINK="#ff0000"> 
17<IMG SRC="../../boost.png" 
18     ALT="C++ Boost" width="277" height="86"> 
19
20<BR Clear>
21
22<h2><a name="concept-covering">Concept Covering and Archetypes</a></h2>
23
24We have discussed how it is important to select the minimal
25requirements (concepts) for the inputs to a component, but it is
26equally important to verify that the chosen concepts <i>cover</i> the
27algorithm. That is, any possible user error should be caught by the
28concept checks and not let slip through.  Concept coverage can be
29verified through the use of <i>archetype classes</i>. An archetype
30class is an exact implementation of the interface associated with a
31particular concept.  The run-time behavior of the archetype class is
32not important, the functions can be left empty. A simple test program
33can then be compiled with the archetype classes as the inputs to the
34component. If the program compiles then one can be sure that the
35concepts cover the component.
36
37The following code shows the archetype class for the <a
38href="http://www.sgi.com/tech/stl/InputIterator.html">Input
39Iterator</a> concept. Some care must be taken to ensure that the
40archetype is an exact match to the concept. For example, the concept
41states that the return type of <tt>operator*()</tt> must be
42convertible to the value type. It does not state the more stringent
43requirement that the return type be <tt>T&amp;</tt> or <tt>const
44T&amp;</tt>. That means it would be a mistake to use <tt>T&amp;</tt>
45or <tt>const T&amp;</tt> for the return type of the archetype
46class. The correct approach is to create an artificial return type
47that is convertible to <tt>T</tt>, as we have done here with
48<tt>reference</tt>. The validity of the archetype class test is
49completely dependent on it being an exact match with the concept,
50which must be verified by careful (manual) inspection.
51
52<pre>
53  template &lt;class T&gt;
54  class input_iterator_archetype
55  {
56  private:
57    typedef input_iterator_archetype self;
58  public:
59    typedef std::input_iterator_tag iterator_category;
60    typedef T value_type;
61    struct reference {
62      operator const value_type&amp;() const { return static_object&lt;T&gt;::get(); }
63    };
64    typedef const T* pointer;
65    typedef std::ptrdiff_t difference_type;
66    self&amp; operator=(const self&amp;) { return *this;  }
67    bool operator==(const self&amp;) const { return true; }
68    bool operator!=(const self&amp;) const { return true; }
69    reference operator*() const { return reference(); }
70    self&amp; operator++() { return *this; }
71    self operator++(int) { return *this; }
72  };
73</pre>
74
75Generic algorithms are often tested by being instantiated with a
76number of common input types. For example, one might apply
77<tt>std::stable_sort()</tt> with basic pointer types as the iterators.
78Though appropriate for testing the run-time behavior of the algorithm,
79this is not helpful for ensuring concept coverage because C++ types
80never match particular concepts, they often provide much more than the
81minimal functionality required by any one concept. That is, even
82though the function template compiles with a given type, the concept
83requirements may still fall short of covering the functions actual
84requirements. This is why it is important to compile with archetype
85classes in addition to testing with common input types.
86
87<p>
88The following is an excerpt from <a
89href="./stl_concept_covering.cpp"><tt>stl_concept_covering.cpp</tt></a>
90that shows how archetypes can be used to check the requirement
91documentation for
92<a href="http://www.sgi.com/tech/stl/stable_sort.html">
93<tt>std::stable_sort()</tt></a>. In this case, it looks like the <a
94href="../utility/CopyConstructible.html">CopyConstructible</a> and <a
95href="../utility/Assignable.html">Assignable</a> requirements were
96forgotten in the SGI STL documentation (try removing those
97archetypes).  The Boost archetype classes have been designed so that
98they can be layered.  In this example the value type of the iterator
99is composed out of three archetypes. In the archetype class reference
100below, template parameters named <tt>Base</tt> indicate where the
101layered archetype can be used.
102
103<pre>
104  {
105    typedef less_than_comparable_archetype&lt; 
106        sgi_assignable_archetype&lt;&gt; &gt; ValueType;
107    random_access_iterator_archetype&lt;ValueType&gt; ri;
108    std::stable_sort(ri, ri);
109  }
110</pre>
111
112<a href="./prog_with_concepts.htm">Next: Programming with Concepts</a><br>
113<a href="./creating_concepts.htm">Prev: Creating Concept Checking Classes</a>
114
115<br>
116<HR>
117<TABLE>
118<TR valign=top>
119<TD nowrap>Copyright &copy 2000</TD><TD>
120<A HREF="../../people/jeremy_siek.htm">Jeremy Siek</A>(<A
121HREF="mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</A>)
122Andrew Lumsdaine</A>(<A HREF="mailto:lums@osl.iu.edu">lums@osl.iu.edu</A>)
123</TD></TR></TABLE>
124
125</BODY>
126</HTML> 
Note: See TracBrowser for help on using the repository browser.