0381c5fc54
Some documentation links currently point to pages that HP retired along with the rest of the SGI STL website. These links now point to the Boost mirror site.
187 lines
7.8 KiB
HTML
187 lines
7.8 KiB
HTML
<!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.boost.org/sgi/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>
|