[ceph.git] / ceph / src / boost / libs / concept_check / concept_covering.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<!-- Copyright (c) Jeremy Siek and Andrew Lumsdaine 2000 -->
<!-- Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->

<head>
  <meta name="generator" content=
  "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />

  <title>Concept Covering and Archetypes</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>

<body bgcolor="#FFFFFF" link="#0000EE" text="#000000" vlink="#551A8B" alink=
"#FF0000">
  <img src="../../boost.png" alt="C++ Boost" width="277" height=
  "86" /><br clear="none" />

  <h2><a name="concept-covering" id="concept-covering">Concept Covering and
  Archetypes</a></h2>

  <p>We have discussed how it is important to select the minimal requirements
  (concepts) for the inputs to a component, but it is equally important to
  verify that the chosen concepts <i>cover</i> the algorithm. That is, any
  possible user error should be caught by the concept checks and not let slip
  through. Concept coverage can be verified through the use of <i>archetype
  classes</i>. An archetype class is an exact implementation of the interface
  associated with a particular concept. The run-time behavior of the
  archetype class is not important, the functions can be left empty. A simple
  test program can then be compiled with the archetype classes as the inputs
  to the component. If the program compiles then one can be sure that the
  concepts cover the component. The following code shows the archetype class
  for the <a href="http://www.boost.org/sgi/stl/InputIterator.html">Input
  Iterator</a> concept. Some care must be taken to ensure that the archetype
  is an exact match to the concept. For example, the concept states that the
  return type of <tt>operator*()</tt> must be convertible to the value type.
  It does not state the more stringent requirement that the return type be
  <tt>T&amp;</tt> or <tt>const T&amp;</tt>. That means it would be a mistake
  to use <tt>T&amp;</tt> or <tt>const T&amp;</tt> for the return type of the
  archetype class. The correct approach is to create an artificial return
  type that is convertible to <tt>T</tt>, as we have done here with
  <tt>reference</tt>. The validity of the archetype class test is completely
  dependent on it being an exact match with the concept, which must be
  verified by careful (manual) inspection.</p>
  <pre>
template &lt;class T&gt;
class input_iterator_archetype
{
private:
  typedef input_iterator_archetype self;
public:
  typedef std::input_iterator_tag iterator_category;
  typedef T value_type;
  struct reference {
    operator const value_type&amp;() const { return static_object&lt;T&gt;::get(); }
  };
  typedef const T* pointer;
  typedef std::ptrdiff_t difference_type;
  self&amp; operator=(const self&amp;) { return *this;  }
  bool operator==(const self&amp;) const { return true; }
  bool operator!=(const self&amp;) const { return true; }
  reference operator*() const { return reference(); }
  self&amp; operator++() { return *this; }
  self operator++(int) { return *this; }
};
</pre>

  <p>Generic algorithms are often tested by being instantiated with a number
  of common input types. For example, one might apply
  <tt>std::stable_sort()</tt> with basic pointer types as the iterators.
  Though appropriate for testing the run-time behavior of the algorithm, this
  is not helpful for ensuring concept coverage because C++ types never match
  particular concepts exactly. Instead, they often provide more than the
  minimal functionality required by any one concept. Even though the function
  template has concept checks, and compiles with a given type, the checks may
  still fall short of covering all the functionality that is actually used.
  This is why it is important to compile with archetype classes in addition
  to testing with common input types.</p>

  <p>The following is an excerpt from <a href=
  "./stl_concept_covering.cpp"><tt>stl_concept_covering.cpp</tt></a> that
  shows how archetypes can be used to check the requirement documentation for
  <a href=
  "http://www.boost.org/sgi/stl/stable_sort.html"><tt>std::stable_sort()</tt></a>.
  In this case, it looks like the <a href=
  "../utility/CopyConstructible.html">CopyConstructible</a> and <a href=
  "../utility/Assignable.html">Assignable</a> requirements were forgotten in
  the SGI STL documentation (try removing those archetypes). The Boost
  archetype classes have been designed so that they can be layered. In this
  example the value type of the iterator is composed out of three archetypes.
  In the <a href="reference.htm#basic-archetype">archetype class
  reference</a>, template parameters named <tt>Base</tt> indicate where the
  layered archetype paradigm can be used.</p>
  <pre>
{
  typedef less_than_comparable_archetype&lt; 
      sgi_assignable_archetype&lt;&gt; &gt; ValueType;
  random_access_iterator_archetype&lt;ValueType&gt; ri;
  std::stable_sort(ri, ri);
}
</pre>

  <p><a href="./prog_with_concepts.htm">Next: Programming with
  Concepts</a><br />
  <a href="./creating_concepts.htm">Prev: Creating Concept Checking
  Classes</a><br />
  <hr />

  <table>
    <tr valign="top">
      <td nowrap="nowrap">Copyright &copy; 2000</td>

      <td><a href="http://www.boost.org/people/jeremy_siek.htm">Jeremy Siek</a>(<a href=
      "mailto:jsiek@osl.iu.edu">jsiek@osl.iu.edu</a>) Andrew
      Lumsdaine(<a href="mailto:lums@osl.iu.edu">lums@osl.iu.edu</a>),
        2007 <a href="mailto:dave@boost-consulting.com">David Abrahams</a>.
    </tr>
  </table>
</body>
</html>
Commit	Line	Data
7c673cae FG	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
92f5a8d4	38	for the <a href="http://www.boost.org/sgi/stl/InputIterator.html">Input
7c673cae FG	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>
	51	template <class T>
	52	class input_iterator_archetype
	53	{
	54	private:
	55	typedef input_iterator_archetype self;
	56	public:
	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=
92f5a8d4	89	"http://www.boost.org/sgi/stl/stable_sort.html"><tt>std::stable_sort()</tt></a>.
7c673cae FG	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>