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>
|