Squashed 'third_party/boostorg/concept_check/' content from commit ed0a0eb
Change-Id: Ib7230965334f9501601efc300242efde8352a380
git-subtree-dir: third_party/boostorg/concept_check
git-subtree-split: ed0a0ebd72f778cfa4931e0538ea34c28db3a42b
diff --git a/using_concept_check.htm b/using_concept_check.htm
new file mode 100644
index 0000000..80c95cb
--- /dev/null
+++ b/using_concept_check.htm
@@ -0,0 +1,186 @@
+<!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" />
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+
+ <title>Using Concept Checks</title>
+ <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="using-concept-checks" id="using-concept-checks">Using Concept
+ Checks</a></h2>
+
+ <p>For each concept there is a concept checking class template that can be
+ used to make sure that a given type (or set of types) models the concept.
+ The Boost Concept Checking Library (BCCL) includes concept checking class
+ templates for all of the concepts used in the C++ standard library and a
+ few more. See the <a href="./reference.htm">Reference</a> section for a
+ complete list. In addition, other boost libraries come with concept
+ checking classes for the concepts that are particular to those libraries.
+ For example, there are <a href="../graph/doc/graph_concepts.html">graph
+ concepts</a> and <a href="../property_map/doc/property_map.html">property map
+ concepts</a>. Also, whenever <b>anyone</b> writing function templates needs
+ to express requirements that are not yet stated by an existing concept, a
+ new concept checking class should be created. How to do this is explained
+ in <a href="./creating_concepts.htm">Creating Concept Checking
+ Classes</a>.</p>
+
+ <p>An example of a concept checking class from the BCCL is the
+ <tt>EqualityComparableConcept</tt> class. The class corresponds to the
+ EqualityComparable requirements described in 20.1.1 of the C++ Standard,
+ and to the <a href=
+ "http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a>
+ concept documented in the SGI STL.</p>
+ <pre>
+template <class T>
+struct EqualityComparable;
+</pre>
+
+ <p>The template argument is the type to be checked. That is, the purpose of
+ <tt>EqualityComparable<<em>T</em>></tt> is to make sure that
+ <tt><em>T</em></tt> models the EqualityComparable concept.</p>
+
+ <h4><tt>BOOST_CONCEPT_ASSERT()</tt></h4>
+
+ <p>The most versatile way of checking concept requirements is to use the
+ <code>BOOST_CONCEPT_ASSERT()</code> macro. You can use this macro at any
+ scope, by passing a concept checking template specialization enclosed in
+ parentheses. <strong>Note:</strong> that means invocations of
+ <code>BOOST_CONCEPT_ASSERT</code> will appear to use <strong>double
+ parentheses</strong>.</p>
+ <pre>
+<font color="green">// In my library:</font>
+template <class T>
+void generic_library_function(T x)
+{
+ BOOST_CONCEPT_ASSERT<strong>((</strong>EqualityComparable<T><strong>))</strong>;
+ <font color="green">// ...</font>
+};
+
+template <class It>
+class generic_library_class
+{
+ BOOST_CONCEPT_ASSERT<strong>((</strong>RandomAccessIterator<It><strong>))</strong>;
+ <font color="green">// ...</font>
+};
+
+<font color="green">// In the user's code:</font>
+class foo {
+ <font color="green">//... </font>
+};
+
+int main() {
+ foo x;
+ generic_library_function(x);
+ generic_library_class<std::vector<char>::iterator> y;
+ <font color="green">//...</font>
+}
+</pre>
+
+ <h4><tt>BOOST_CONCEPT_REQUIRES</tt></h4>
+
+ <p>One of the nice things about the proposed C++0x <a href=
+ "http://www.generic-programming.org/languages/conceptcpp/tutorial">syntax
+ for declaring concept constrained function templates</a> is the way that
+ constraints are part of the function <em>declaration</em>, so clients will
+ see them. <code>BOOST_CONCEPT_ASSERT</code> can only express constraints
+ within the function template definition, which hides the constraint in the
+ function body. Aside from the loss of a self-documenting interface,
+ asserting conformance only in the function body can undesirably delay
+ checking if the function is explicitly instantiated in a different
+ translation unit from the one in which it is called, or if the compiler
+ does link-time instantiation.</p>
+
+ <p>The <tt>BOOST_CONCEPT_REQUIRES</tt> macro can be used in a function
+ template declaration to check whether some type models a concept. It
+ accepts two arguments, a <strong>list of constraints</strong>, and the
+ function template's return type. The list of constraints takes the form of
+ a sequence of adjacent concept checking template specializations,
+ <strong>in double parentheses</strong>, and the function's return type must
+ also be parenthesized. For example, the standard <code>stable_sort</code>
+ algorithm might be declared as follows: </p>
+ <pre>
+template <class RanIter>
+BOOST_CONCEPT_REQUIRES(
+ ((Mutable_RandomAccessIterator<RanIter>))
+ ((LessThanComparable<typename Mutable_RandomAccessIterator<RanIter>::value_type>)),
+ (void)) <font color="green">// return type</font>
+ stable_sort(RanIter,RanIter);
+</pre>
+
+ <p>Note that the algorithm requires that the value type of the iterator be
+ LessThanComparable, and it accesses that value type through the
+ <code>Mutable_RandomAccessIterator</code> concept checking template. In
+ general, the Boost concept checking classes expose associated types as
+ nested member typedefs so that you can use this syntax, which mimics the
+ approach used in the concept support proposed for the next version of
+ C++.</p>
+
+ <h4>Multi-Type Concepts</h4>
+
+ <p>Some concepts deal with more than one type. In this case the
+ corresponding concept checking class will have multiple template
+ parameters. The following example shows how <tt>BOOST_CONCEPT_REQUIRES</tt>
+ is used with the <a href=
+ "../property_map/doc/ReadWritePropertyMap.html">ReadWritePropertyMap</a>
+ concept, which takes two type parameters: a property map and the key type
+ for the map.</p>
+ <pre>
+template <class G, class Buffer, class BFSVisitor,
+ class ColorMap>
+BOOST_CONCEPT_REQUIRES(
+ ((ReadWritePropertyMap<ColorMap, typename IncidenceGraph<G>::vertex_descriptor>)),
+ (void)) <font color="green">// return type</font>
+breadth_first_search(G& g,
+ typename graph_traits<IncidenceGraph>::vertex_descriptor s,
+ Buffer& Q, BFSVisitor vis, ColorMap color)
+{
+ typedef typename IncidenceGraph<G>::vertex_descriptor Vertex;
+ ...
+}
+</pre>
+
+ <p>Although concept checks are designed for use by generic library
+ implementors, they can also be useful to end users. Sometimes one may not
+ be sure whether some type models a particular concept. The syntactic
+ requirements, at least, can easily be checked by creating a small program
+ and using <tt>BOOST_CONCEPT_ASSERT</tt> with the type and concept in
+ question. For example:</p>
+ <pre>
+<font color=
+"green">// Make sure list<int> has bidirectional iterators.</font>
+BOOST_CONCEPT_ASSERT((BidirectionalIterator<std::list<int>::iterator>));
+</pre>
+
+ <p><a href="./concept_check.htm">Prev: Concept Checking
+ Introduction</a><br />
+ <a href="./creating_concepts.htm">Next: Creating Concept Checking
+ Classes</a><br /></p>
+ <hr />
+
+ <table>
+ <tr valign="top">
+ <td nowrap="nowrap">Copyright © 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>.</td>
+ </tr>
+ </table>
+</body>
+</html>