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