more/generic_programming.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">

<html>
<head>
    <meta name="generator" content="HTML Tidy, see www.w3.org">
    <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
    <meta name="ProgId" content="FrontPage.Editor.Document">

    <title>Generic Programming Techniques</title>
</head>

<body bgcolor="#FFFFFF" text="#000000">
    <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
    width="277" height="86"> 

    <h1>Generic Programming Techniques</h1>

    <p>This is an incomplete survey of some of the generic programming
    techniques used in the <a href="../index.htm">boost</a> libraries.

    <h2>Table of Contents</h2>

    <ul>
      <li><a href="#introduction">Introduction</a>

      <li><a href="#concept">The Anatomy of a Concept</a>

      <li><a href="#traits">Traits</a>

      <li><a href="#tag_dispatching">Tag Dispatching</a>

      <li><a href="#type_generator">Type Generators</a>

      <li><a href="#object_generator">Object Generators</a>

      <li><a href="#policies">Policies Classes</a>

      <li><a href="#adaptors">Adaptors</a>
    </ul>


    <h2><a name="introduction">Introduction</a></h2>

    <p>Generic programming is about generalizing software components
    so that they can be easily reused in a wide variety of situations.
    In C++, class and function templates are particularly effective
    mechanisms for generic programming because they make the
    generalization possible without sacrificing efficiency. 
   
    <p>As a simple example of generic programming, we will look at how
    one might generalize the <tt>memcpy()</tt> function of the 
    C standard library. An implementation of <tt>memcpy()</tt>
    might look like the following: 
<p>
<blockquote>
<pre>
void* memcpy(void* region1, const void* region2, size_t n)
{
  const char* first = (const char*)region2;
  const char* last = ((const char*)region2) + n;
  char* result = (char*)region1;
  while (first != last)
    *result++ = *first++;
  return result;
}
</pre>
</blockquote>
    The <tt>memcpy()</tt> function is already generalized to some
    extent by the use of <tt>void*</tt> so that the function can be
    used to copy arrays of different kinds of data. But what if the
    data we would like to copy is not in an array? Perhaps it is in a
    linked list. Can we generalize the notion of copy to any sequence
    of elements? Looking at the body of <tt>memcpy()</tt>, the
    function's <b><i>minimal requirements</i></b> are that it needs to
    to <i>traverse</i> through the sequence using some sort of
    pointer, <i>access</i> elements pointed to, <i>write</i> the
    elements to the destination, and <i>compare</i> pointers to know
    when to stop.  The C++ standard library groups requirements such
    as these into <b><i>concepts</i></b>, in this case the <a
    href="http://www.sgi.com/tech/stl/InputIterator.html"> Input
    Iterator</a> concept (for <tt>region2</tt>) and the <a
    href="http://www.sgi.com/tech/stl/OutputIterator.html"> Output
    Iterator</a> concept (for <tt>region1</tt>).

    <p>If we rewrite the <tt>memcpy()</tt> as a function template, and
    use the <a href="http://www.sgi.com/tech/stl/InputIterator.html">
    Input Iterator</a> and <a
    href="http://www.sgi.com/tech/stl/OutputIterator.html"> Output
    Iterator</a> concepts to describe the requirements on the template
    parameters, we can implement a highly reusable <tt>copy()</tt>
    function in the following way:
<p>
<blockquote>
<pre>
template &lt;typename InputIterator, typename OutputIterator&gt;
OutputIterator
copy(InputIterator first, InputIterator last, OutputIterator result)
{
  while (first != last)
    *result++ = *first++;
  return result;
}
</pre>
</blockquote>

    <p>Using the generic <tt>copy()</tt> function, we can now copy
    elements from any kind of sequence, including a linked list that
    exports iterators such as <tt>std::<a
    href="http://www.sgi.com/tech/stl/List.html">list</a></tt>.
<p>
<blockquote>
<pre>
#include &lt;list&gt;
#include &lt;vector&gt;
#include &lt;iostream&gt;

int main()
{
  const int N = 3;
  std::vector&lt;int&gt; region1(N);
  std::list&lt;int&gt; region2;

  region2.push_back(1);
  region2.push_back(0);
  region2.push_back(3);
  
  std::copy(region2.begin(), region2.end(), region1.begin());

  for (int i = 0; i &lt; N; ++i)
    std::cout &lt;&lt; region1[i] &lt;&lt; " ";
  std::cout &lt;&lt; std::endl;
}
</pre>
</blockquote>


    <h2><a name="concept">Anatomy of a Concept</a></h2>

    A <b><i>concept</i></b> is a set requirements, where the
    requirements consist of valid expressions, associated types,
    invariants, and complexity guarantees. A type that satisfies the
    set of requirements is said to <b><i>model</i></b> the concept.  A
    concept can extend the requirements of another concept, which is
    called <b><i>refinement</i></b>.

    <ul>
       <li><a name="valid_expression"><b>Valid Expressions</b></a> are
	 C++ expressions which must compile successfully for the
	 objects involved in the expression to be considered
	 <i>models</i> of the concept.

      <li><a name="associated_type"><b>Associated Types</b></a> are
	types that are related to the modeling type in that they
	participate in one or more of the valid expressions. Typically
	associated types can be accessed either through typedefs
	nested within a class definition for the modeling type, or
	they are accessed through a <a href="#traits">traits
	class</a>.

      <li><b>Invariants</b> are run-time characteristics of the
	objects that must always be true, that is, the functions involving
	the objects must preserve these characteristics. The invariants
	often take the form of pre-conditions and post-conditions.

      <li><b>Complexity Guarantees</b> are maximum limits on how long
	the execution of one of the valid expressions will take, or how
	much of various resources its computation will use.
    </ul>

    <p>The concepts used in the C++ Standard Library are documented at
    the <a href="http://www.sgi.com/tech/stl/table_of_contents.html">
    SGI STL site</a>.

    <h2><a name="traits">Traits</a></h2>

    <p>A traits class provides a way of associating information with a
    compile-time entity (a type, integral constant, or address). For example,
    the class template <tt><a href=
    "http://www.sgi.com/tech/stl/iterator_traits.html">std::iterator_traits&lt;T&gt;</a></tt>
    looks something like this:

    <blockquote>
<pre>
template &lt;class Iterator&gt;
struct iterator_traits {
  typedef ... iterator_category;
  typedef ... value_type;
  typedef ... difference_type;
  typedef ... pointer;
  typedef ... reference;
};
</pre>
    </blockquote>
    The traits' <tt>value_type</tt> gives generic code the type which the
    iterator is "pointing at", while the <tt>iterator_category</tt> can be used
    to select more efficient algorithms depending on the iterator's
    capabilities. 

    <p>A key feature of traits templates is that they're <i>non-intrusive</i>:
    they allow us to associate information with arbitrary types, including
    built-in types and types defined in third-party libraries, Normally, traits
    are specified for a particular type by (partially) specializing the traits
    template.

    <p>For an in-depth description of <tt>std::iterator_traits</tt>, see <a href=
    "http://www.sgi.com/tech/stl/iterator_traits.html">this page</a> provided
    by SGI. Another very different expression of the traits idiom in the
    standard is <tt>std::numeric_limits&lt;T&gt;</tt> which provides constants
    describing the range and capabilities of numeric types.

    <h2><a name="tag_dispatching">Tag Dispatching</a></h2>

    <p>
     A technique that often goes hand in hand with traits classes is
     tag dispatching, which is a way of using function overloading to
     dispatch based on properties of a type. A good example of this is
     the implementation of the <a
     href="http://www.sgi.com/tech/stl/advance.html"><tt>std::advance()</tt></a>
     function in the C++ Standard Library, which increments an
     iterator <tt>n</tt> times. Depending on the kind of iterator,
     there are different optimizations that can be applied in the
     implementation. If the iterator is <a
     href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">random
     access</a> (can jump forward and backward arbitrary distances),
     then the <tt>advance()</tt> function can simply be implemented
     with <tt>i += n</tt>, and is very efficient: constant time. If
     the iterator is <a
     href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">bidirectional</a>,
     then it makes sense for <tt>n</tt> to be negative, we can
     decrement the iterator <tt>n</tt> times.
     </p>
     <p>
     The relation between tag dispatching and traits classes is
     that the property used for dispatching (in this case the
     <tt>iterator_category</tt>) is accessed through a traits class.
     The main <tt>advance()</tt> function uses the <a
     href="http://www.sgi.com/tech/stl/iterator_traits.html"><tt>iterator_traits</tt></a>
     class to get the <tt>iterator_category</tt>. It then makes a call
     the the overloaded <tt>advance_dispatch()</tt> function. 
     The
     appropriate <tt>advance_dispatch()</tt> is selected by the
     compiler based on whatever type the <tt>iterator_category</tt>
     resolves to, either <a
     href="http://www.sgi.com/tech/stl/input_iterator_tag.html">
     <tt>input_iterator_tag</tt></a>, <a
     href="http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html">
     <tt>bidirectional_iterator_tag</tt></a>, or <a
     href="http://www.sgi.com/tech/stl/random_access_iterator_tag.html">
     <tt>random_access_iterator_tag</tt></a>.  A <b><i>tag</i></b> is
     simply a class whose only purpose is to convey some property for
     use in tag dispatching and similar techniques. Refer to <a
     href="http://www.sgi.com/tech/stl/iterator_tags.html">this
     page</a> for a more detailed description of iterator tags.
     </p>
    <blockquote>
<pre>
namespace std {
  struct input_iterator_tag { };
  struct bidirectional_iterator_tag { };
  struct random_access_iterator_tag { };

  namespace detail {
    template &lt;class InputIterator, class Distance&gt;
    void advance_dispatch(InputIterator&amp; i, Distance n, <b>input_iterator_tag</b>) {
      while (n--) ++i;
    }

    template &lt;class BidirectionalIterator, class Distance&gt;
    void advance_dispatch(BidirectionalIterator&amp; i, Distance n, 
		   <b>bidirectional_iterator_tag</b>) {
      if (n &gt;= 0)
	while (n--) ++i;
      else
	while (n++) --i;
    }

    template &lt;class RandomAccessIterator, class Distance&gt;
    void advance_dispatch(RandomAccessIterator&amp; i, Distance n, 
		   <b>random_access_iterator_tag</b>) {
      i += n;
    }
  }

  template &lt;class InputIterator, class Distance&gt;
  void advance(InputIterator&amp; i, Distance n) {
    typename <b>iterator_traits&lt;InputIterator&gt;::iterator_category</b> category;
    detail::advance_dispatch(i, n, <b>category</b>);
  }
}
</pre>
    </blockquote>

    <h2><a name="type_generator">Type Generators</a></h2>

    <p>A <i>type generator</i> is a template whose only purpose is to
    synthesize a single new type based on its template argument(s)<a
    href="#1">[1]</a>. The generated type is usually expressed as a
    nested typedef named, appropriately <tt>type</tt>. A type
    generator is usually used to consolidate a complicated type
    expression into a simple one, as in <tt>boost::<a href=
    "../libs/utility/filter_iterator.hpp">filter_iterator_generator</a></tt>,
    which looks something like this:

    <blockquote>
<pre>
template &lt;class Predicate, class Iterator, 
    class Value = <i>complicated default</i>,
    class Reference = <i>complicated default</i>,
    class Pointer = <i>complicated default</i>,
    class Category = <i>complicated default</i>,
    class Distance = <i>complicated default</i>
         &gt;
struct filter_iterator_generator {
    typedef iterator_adaptor&lt;
        Iterator,filter_iterator_policies&lt;Predicate,Iterator&gt;,
        Value,Reference,Pointer,Category,Distance&gt; <b>type</b>;
};
</pre>
    </blockquote>

    <p>Now, that's complicated, but producing an adapted filter iterator is
    much easier. You can usually just write:

    <blockquote>
<pre>
boost::filter_iterator_generator&lt;my_predicate,my_base_iterator&gt;::type
</pre>
    </blockquote>


    <h2><a name="object_generator">Object Generators</a></h2>

    <p>An <i>object generator</i> is a function template whose only purpose is
    to construct a new object out of its arguments. Think of it as a kind of
    generic constructor. An object generator may be more useful than a plain
    constructor when the exact type to be generated is difficult or impossible
    to express and the result of the generator can be passed directly to a
    function rather than stored in a variable. Most object generators are named
    with the prefix "<tt>make_</tt>", after <tt>std::<a href=
    "http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const<73>T&amp;,<2C>const<73>U&amp;)</tt>.

    <p>Here is an example, using another standard object generator, <tt>std::<a
    href=
    "http://www.sgi.com/tech/stl/back_insert_iterator.html">back_inserter</a>()</tt>:

    <blockquote>
<pre>
// Append the items in [start, finish) to c
template &lt;class Container, class Iterator&gt;
void append_sequence(Container&amp; c, Iterator start, Iterator finish)
{
   std::copy(start, finish, <b>std::back_inserter</b>(c));
}
</pre>
    </blockquote>

    <p>Without using the object generator the example above would look like:
    write:

    <blockquote>
<pre>
// Append the items in [start, finish) to c
template &lt;class Container, class Iterator&gt;
void append_sequence(Container&amp; c, Iterator start, Iterator finish)
{
   std::copy(start, finish, <b>std::back_insert_iterator&lt;Container&gt;</b>(c));
}
</pre>
    </blockquote>

    <p>As expressions get more complicated the need to reduce the verbosity of
    type specification gets more compelling.

    <h2><a name="policies">Policies Classes</a></h2>

    <p>A policies class is a template parameter used to transmit
    behaviors. An example from the standard library is <tt>std::<a
    href="http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></tt>,
    which supplies memory management behaviors to standard <a
    href="http://www.sgi.com/tech/stl/Container.html">containers</a>.

    <p>Policies classes have been explored in detail by <a href=
    "mailto:andrewalex@hotmail.com">Andrei Alexandrescu</a> in <a href=
    "http://www.cs.ualberta.ca/~hoover/cmput401/XP-Notes/xp-conf/Papers/7_3_Alexandrescu.pdf">
    this paper</a>. He writes:

    <blockquote>
      <p>Policy classes are implementations of punctual design choices. They
      are inherited from, or contained within, other classes. They provide
      different strategies under the same syntactic interface. A class using
      policies is templated having one template parameter for each policy it
      uses. This allows the user to select the policies needed.

      <p>The power of policy classes comes from their ability to combine
      freely. By combining several policy classes in a template class with
      multiple parameters, one achieves combinatorial behaviors with a linear
      amount of code.
    </blockquote>

    <p>Andrei's description of policies describe their power as being derived
    from their granularity and orthogonality. Boost has probably diluted the
    distinction in the <a href="../libs/utility/iterator_adaptors.htm">Iterator
    Adaptors</a> library, where we transmit all of an adapted iterator's
    behavior in a single policies class. There is precedent for this, however:
    <tt><a
    href="http://www.dinkumware.com/htm_cpl/string2.html#char_traits">std::char_traits</a></tt>,
    despite its name, acts as a policies class that determines the behaviors of
    <a
    href="http://www.dinkumware.com/htm_cpl/string2.html#basic_string">std::basic_string</a>.

    <h2><a name="adaptors">Adaptors</a></h2>

    <p>An <i>adaptor</i> is a class template which builds on another type or
    types to provide a new interface or behavioral variant. Examples of
    standard adaptors are <a href=
    "http://www.sgi.com/tech/stl/ReverseIterator.html">std::reverse_iterator</a>,
    which adapts an iterator type by reversing its motion upon
    increment/decrement, and <a href=
    "http://www.sgi.com/tech/stl/stack.html">std::stack</a>, which adapts a
    container to provide a simple stack interface.

    <p>A more comprehensive review of the adaptors in the standard can be found
    <a href=
    "http://www.cs.rpi.edu/~wiseb/xrds/ovp2-3b.html#SECTION00015000000000000000">
    here</a>.

    <h2>Notes</h2>

    <a name="1">[1]</a> Type generators are a workaround for the lack
    of ``templated typedefs'' in C++.

    <hr>

    <p>Revised 
    <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->12 Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14377" -->


    <p>&copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
    sell and distribute this document is granted provided this copyright notice
    appears in all copies. This document is provided "as is" without express or
    implied warranty, and with no claim as to its suitability for any purpose.

<!--  LocalWords:  HTML html charset gif alt htm struct SGI namespace std libs
 -->
<!--  LocalWords:  InputIterator BidirectionalIterator RandomAccessIterator pdf
 -->
<!--  LocalWords:  typename Alexandrescu templated Andrei's Abrahams memcpy int
 -->
</body>
</html>
<!--  LocalWords:  const OutputIterator iostream pre cpl
 -->
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
-												make HTML more conforming


[SVN r9169]

											
										
										
											2001-02-13 03:12:40 +08:00
+								<html>
 								<head>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    <meta name="generator" content="HTML Tidy, see www.w3.org">
 								    <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
 								    <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
 								    <meta name="ProgId" content="FrontPage.Editor.Document">
 								    <title>Generic Programming Techniques</title>
-												make HTML more conforming


[SVN r9169]

											
										
										
											2001-02-13 03:12:40 +08:00
+								</head>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
-												make HTML more conforming


[SVN r9169]

											
										
										
											2001-02-13 03:12:40 +08:00
+								<body bgcolor="#FFFFFF" text="#000000">
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
 								    width="277" height="86">
 								    <h1>Generic Programming Techniques</h1>
 								    <p>This is an incomplete survey of some of the generic programming
 								    techniques used in the <a href="../index.htm">boost</a> libraries.
 								    <h2>Table of Contents</h2>
 								    <ul>
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
+								      <li><a href="#introduction">Introduction</a>
 								      <li><a href="#concept">The Anatomy of a Concept</a>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								      <li><a href="#traits">Traits</a>
-												added section on "tag dispatching"


[SVN r9154]

											
										
										
											2001-02-12 13:04:28 +08:00
+								      <li><a href="#tag_dispatching">Tag Dispatching</a>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								      <li><a href="#type_generator">Type Generators</a>
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
+								      <li><a href="#object_generator">Object Generators</a>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
 								      <li><a href="#policies">Policies Classes</a>
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
 								      <li><a href="#adaptors">Adaptors</a>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    </ul>
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
 								    <h2><a name="introduction">Introduction</a></h2>
 								    <p>Generic programming is about generalizing software components
 								    so that they can be easily reused in a wide variety of situations.
 								    In C++, class and function templates are particularly effective
 								    mechanisms for generic programming because they make the
 								    generalization possible without sacrificing efficiency.
 								    <p>As a simple example of generic programming, we will look at how
 								    one might generalize the <tt>memcpy()</tt> function of the
 								    C standard library. An implementation of <tt>memcpy()</tt>
 								    might look like the following:
 								<p>
 								<blockquote>
 								<pre>
 								void* memcpy(void* region1, const void* region2, size_t n)
 								{
 								  const char* first = (const char*)region2;
 								  const char* last = ((const char*)region2) + n;
 								  char* result = (char*)region1;
 								  while (first != last)
 								    *result++ = *first++;
 								  return result;
 								}
 								</pre>
 								</blockquote>
 								    The <tt>memcpy()</tt> function is already generalized to some
 								    extent by the use of <tt>void*</tt> so that the function can be
 								    used to copy arrays of different kinds of data. But what if the
 								    data we would like to copy is not in an array? Perhaps it is in a
 								    linked list. Can we generalize the notion of copy to any sequence
 								    of elements? Looking at the body of <tt>memcpy()</tt>, the
 								    function's <b><i>minimal requirements</i></b> are that it needs to
 								    to <i>traverse</i> through the sequence using some sort of
 								    pointer, <i>access</i> elements pointed to, <i>write</i> the
 								    elements to the destination, and <i>compare</i> pointers to know
 								    when to stop.  The C++ standard library groups requirements such
 								    as these into <b><i>concepts</i></b>, in this case the <a
 								    href="http://www.sgi.com/tech/stl/InputIterator.html"> Input
 								    Iterator</a> concept (for <tt>region2</tt>) and the <a
 								    href="http://www.sgi.com/tech/stl/OutputIterator.html"> Output
 								    Iterator</a> concept (for <tt>region1</tt>).
 								    <p>If we rewrite the <tt>memcpy()</tt> as a function template, and
 								    use the <a href="http://www.sgi.com/tech/stl/InputIterator.html">
 								    Input Iterator</a> and <a
 								    href="http://www.sgi.com/tech/stl/OutputIterator.html"> Output
 								    Iterator</a> concepts to describe the requirements on the template
 								    parameters, we can implement a highly reusable <tt>copy()</tt>
 								    function in the following way:
 								<p>
 								<blockquote>
 								<pre>
 								template &lt;typename InputIterator, typename OutputIterator&gt;
 								OutputIterator
 								copy(InputIterator first, InputIterator last, OutputIterator result)
 								{
 								  while (first != last)
 								    *result++ = *first++;
 								  return result;
 								}
 								</pre>
 								</blockquote>
 								    <p>Using the generic <tt>copy()</tt> function, we can now copy
 								    elements from any kind of sequence, including a linked list that
-												added link for std::list


[SVN r9190]

											
										
										
											2001-02-14 01:45:31 +08:00
+								    exports iterators such as <tt>std::<a
 								    href="http://www.sgi.com/tech/stl/List.html">list</a></tt>.
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
+								<p>
 								<blockquote>
 								<pre>
 								#include &lt;list&gt;
 								#include &lt;vector&gt;
 								#include &lt;iostream&gt;
 								int main()
 								{
 								  const int N = 3;
 								  std::vector&lt;int&gt; region1(N);
 								  std::list&lt;int&gt; region2;
 								  region2.push_back(1);
 								  region2.push_back(0);
 								  region2.push_back(3);
 								  std::copy(region2.begin(), region2.end(), region1.begin());
 								  for (int i = 0; i &lt; N; ++i)
 								    std::cout &lt;&lt; region1[i] &lt;&lt; " ";
 								  std::cout &lt;&lt; std::endl;
 								}
 								</pre>
 								</blockquote>
 								    <h2><a name="concept">Anatomy of a Concept</a></h2>
 								    A <b><i>concept</i></b> is a set requirements, where the
 								    requirements consist of valid expressions, associated types,
 								    invariants, and complexity guarantees. A type that satisfies the
 								    set of requirements is said to <b><i>model</i></b> the concept.  A
 								    concept can extend the requirements of another concept, which is
 								    called <b><i>refinement</i></b>.
 								    <ul>
-												added name tags for valid expressions and associated types


[SVN r9189]

											
										
										
											2001-02-14 01:36:10 +08:00
+								       <li><a name="valid_expression"><b>Valid Expressions</b></a> are
 									 C++ expressions which must compile successfully for the
 									 objects involved in the expression to be considered
 									 <i>models</i> of the concept.
 								      <li><a name="associated_type"><b>Associated Types</b></a> are
 									types that are related to the modeling type in that they
 									participate in one or more of the valid expressions. Typically
 									associated types can be accessed either through typedefs
 									nested within a class definition for the modeling type, or
 									they are accessed through a <a href="#traits">traits
 									class</a>.
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
 								      <li><b>Invariants</b> are run-time characteristics of the
 									objects that must always be true, that is, the functions involving
 									the objects must preserve these characteristics. The invariants
 									often take the form of pre-conditions and post-conditions.
 								      <li><b>Complexity Guarantees</b> are maximum limits on how long
 									the execution of one of the valid expressions will take, or how
 									much of various resources its computation will use.
 								    </ul>
 								    <p>The concepts used in the C++ Standard Library are documented at
 								    the <a href="http://www.sgi.com/tech/stl/table_of_contents.html">
 								    SGI STL site</a>.
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    <h2><a name="traits">Traits</a></h2>
-												add fixes from Peter Dimov and Kevlin Henney.


[SVN r9158]

											
										
										
											2001-02-12 22:20:58 +08:00
+								    <p>A traits class provides a way of associating information with a
 								    compile-time entity (a type, integral constant, or address). For example,
 								    the class template <tt><a href=
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    "http://www.sgi.com/tech/stl/iterator_traits.html">std::iterator_traits&lt;T&gt;</a></tt>
 								    looks something like this:
 								    <blockquote>
 								<pre>
 								template &lt;class Iterator&gt;
 								struct iterator_traits {
 								  typedef ... iterator_category;
 								  typedef ... value_type;
 								  typedef ... difference_type;
 								  typedef ... pointer;
 								  typedef ... reference;
 								};
 								</pre>
 								    </blockquote>
 								    The traits' <tt>value_type</tt> gives generic code the type which the
 								    iterator is "pointing at", while the <tt>iterator_category</tt> can be used
 								    to select more efficient algorithms depending on the iterator's
 								    capabilities.
 								    <p>A key feature of traits templates is that they're <i>non-intrusive</i>:
 								    they allow us to associate information with arbitrary types, including
 								    built-in types and types defined in third-party libraries, Normally, traits
 								    are specified for a particular type by (partially) specializing the traits
 								    template.
-												add fixes from Peter Dimov and Kevlin Henney.


[SVN r9158]

											
										
										
											2001-02-12 22:20:58 +08:00
+								    <p>For an in-depth description of <tt>std::iterator_traits</tt>, see <a href=
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    "http://www.sgi.com/tech/stl/iterator_traits.html">this page</a> provided
 								    by SGI. Another very different expression of the traits idiom in the
 								    standard is <tt>std::numeric_limits&lt;T&gt;</tt> which provides constants
 								    describing the range and capabilities of numeric types.
-												added section on "tag dispatching"


[SVN r9154]

											
										
										
											2001-02-12 13:04:28 +08:00
+								    <h2><a name="tag_dispatching">Tag Dispatching</a></h2>
 								    <p>
 								     A technique that often goes hand in hand with traits classes is
 								     tag dispatching, which is a way of using function overloading to
 								     dispatch based on properties of a type. A good example of this is
 								     the implementation of the <a
 								     href="http://www.sgi.com/tech/stl/advance.html"><tt>std::advance()</tt></a>
 								     function in the C++ Standard Library, which increments an
 								     iterator <tt>n</tt> times. Depending on the kind of iterator,
 								     there are different optimizations that can be applied in the
 								     implementation. If the iterator is <a
 								     href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">random
 								     access</a> (can jump forward and backward arbitrary distances),
 								     then the <tt>advance()</tt> function can simply be implemented
 								     with <tt>i += n</tt>, and is very efficient: constant time. If
 								     the iterator is <a
 								     href="http://www.sgi.com/tech/stl/BidirectionalIterator.html">bidirectional</a>,
 								     then it makes sense for <tt>n</tt> to be negative, we can
 								     decrement the iterator <tt>n</tt> times.
 								     </p>
 								     <p>
 								     The relation between tag dispatching and traits classes is
 								     that the property used for dispatching (in this case the
 								     <tt>iterator_category</tt>) is accessed through a traits class.
 								     The main <tt>advance()</tt> function uses the <a
 								     href="http://www.sgi.com/tech/stl/iterator_traits.html"><tt>iterator_traits</tt></a>
 								     class to get the <tt>iterator_category</tt>. It then makes a call
 								     the the overloaded <tt>advance_dispatch()</tt> function.
 								     The
 								     appropriate <tt>advance_dispatch()</tt> is selected by the
 								     compiler based on whatever type the <tt>iterator_category</tt>
 								     resolves to, either <a
 								     href="http://www.sgi.com/tech/stl/input_iterator_tag.html">
 								     <tt>input_iterator_tag</tt></a>, <a
 								     href="http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html">
 								     <tt>bidirectional_iterator_tag</tt></a>, or <a
 								     href="http://www.sgi.com/tech/stl/random_access_iterator_tag.html">
 								     <tt>random_access_iterator_tag</tt></a>.  A <b><i>tag</i></b> is
 								     simply a class whose only purpose is to convey some property for
 								     use in tag dispatching and similar techniques. Refer to <a
 								     href="http://www.sgi.com/tech/stl/iterator_tags.html">this
 								     page</a> for a more detailed description of iterator tags.
 								     </p>
 								    <blockquote>
 								<pre>
 								namespace std {
 								  struct input_iterator_tag { };
 								  struct bidirectional_iterator_tag { };
 								  struct random_access_iterator_tag { };
 								  namespace detail {
 								    template &lt;class InputIterator, class Distance&gt;
 								    void advance_dispatch(InputIterator&amp; i, Distance n, <b>input_iterator_tag</b>) {
 								      while (n--) ++i;
 								    }
 								    template &lt;class BidirectionalIterator, class Distance&gt;
 								    void advance_dispatch(BidirectionalIterator&amp; i, Distance n,
 										   <b>bidirectional_iterator_tag</b>) {
 								      if (n &gt;= 0)
 									while (n--) ++i;
 								      else
 									while (n++) --i;
 								    }
 								    template &lt;class RandomAccessIterator, class Distance&gt;
 								    void advance_dispatch(RandomAccessIterator&amp; i, Distance n,
 										   <b>random_access_iterator_tag</b>) {
 								      i += n;
 								    }
 								  }
 								  template &lt;class InputIterator, class Distance&gt;
 								  void advance(InputIterator&amp; i, Distance n) {
 								    typename <b>iterator_traits&lt;InputIterator&gt;::iterator_category</b> category;
 								    detail::advance_dispatch(i, n, <b>category</b>);
 								  }
 								}
 								</pre>
 								    </blockquote>
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    <h2><a name="type_generator">Type Generators</a></h2>
 								    <p>A <i>type generator</i> is a template whose only purpose is to
-												added a note about type generators being a workaround for no templated
typedefs


[SVN r9185]

											
										
										
											2001-02-13 12:32:00 +08:00
+								    synthesize a single new type based on its template argument(s)<a
 								    href="#1">[1]</a>. The generated type is usually expressed as a
 								    nested typedef named, appropriately <tt>type</tt>. A type
 								    generator is usually used to consolidate a complicated type
 								    expression into a simple one, as in <tt>boost::<a href=
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    "../libs/utility/filter_iterator.hpp">filter_iterator_generator</a></tt>,
 								    which looks something like this:
 								    <blockquote>
 								<pre>
 								template &lt;class Predicate, class Iterator,
 								    class Value = <i>complicated default</i>,
 								    class Reference = <i>complicated default</i>,
 								    class Pointer = <i>complicated default</i>,
 								    class Category = <i>complicated default</i>,
 								    class Distance = <i>complicated default</i>
 								         &gt;
 								struct filter_iterator_generator {
 								    typedef iterator_adaptor&lt;
 								        Iterator,filter_iterator_policies&lt;Predicate,Iterator&gt;,
 								        Value,Reference,Pointer,Category,Distance&gt; <b>type</b>;
 								};
 								</pre>
 								    </blockquote>
 								    <p>Now, that's complicated, but producing an adapted filter iterator is
 								    much easier. You can usually just write:
 								    <blockquote>
 								<pre>
 								boost::filter_iterator_generator&lt;my_predicate,my_base_iterator&gt;::type
 								</pre>
 								    </blockquote>
-												added a note about type generators being a workaround for no templated
typedefs


[SVN r9185]

											
										
										
											2001-02-13 12:32:00 +08:00
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    <h2><a name="object_generator">Object Generators</a></h2>
 								    <p>An <i>object generator</i> is a function template whose only purpose is
 								    to construct a new object out of its arguments. Think of it as a kind of
 								    generic constructor. An object generator may be more useful than a plain
 								    constructor when the exact type to be generated is difficult or impossible
 								    to express and the result of the generator can be passed directly to a
 								    function rather than stored in a variable. Most object generators are named
 								    with the prefix "<tt>make_</tt>", after <tt>std::<a href=
 								    "http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const<73>T&amp;,<2C>const<73>U&amp;)</tt>.
 								    <p>Here is an example, using another standard object generator, <tt>std::<a
 								    href=
 								    "http://www.sgi.com/tech/stl/back_insert_iterator.html">back_inserter</a>()</tt>:
 								    <blockquote>
 								<pre>
 								// Append the items in [start, finish) to c
 								template &lt;class Container, class Iterator&gt;
 								void append_sequence(Container&amp; c, Iterator start, Iterator finish)
 								{
 								   std::copy(start, finish, <b>std::back_inserter</b>(c));
 								}
 								</pre>
 								    </blockquote>
 								    <p>Without using the object generator the example above would look like:
 								    write:
 								    <blockquote>
 								<pre>
 								// Append the items in [start, finish) to c
 								template &lt;class Container, class Iterator&gt;
 								void append_sequence(Container&amp; c, Iterator start, Iterator finish)
 								{
 								   std::copy(start, finish, <b>std::back_insert_iterator&lt;Container&gt;</b>(c));
 								}
 								</pre>
 								    </blockquote>
 								    <p>As expressions get more complicated the need to reduce the verbosity of
 								    type specification gets more compelling.
 								    <h2><a name="policies">Policies Classes</a></h2>
-												add fixes from Peter Dimov and Kevlin Henney.


[SVN r9158]

											
										
										
											2001-02-12 22:20:58 +08:00
+								    <p>A policies class is a template parameter used to transmit
 								    behaviors. An example from the standard library is <tt>std::<a
-												Added missing 'allocator'


[SVN r9179]

											
										
										
											2001-02-13 10:01:35 +08:00
+								    href="http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></tt>,
-												add fixes from Peter Dimov and Kevlin Henney.


[SVN r9158]

											
										
										
											2001-02-12 22:20:58 +08:00
+								    which supplies memory management behaviors to standard <a
 								    href="http://www.sgi.com/tech/stl/Container.html">containers</a>.
 								    <p>Policies classes have been explored in detail by <a href=
 								    "mailto:andrewalex@hotmail.com">Andrei Alexandrescu</a> in <a href=
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    "http://www.cs.ualberta.ca/~hoover/cmput401/XP-Notes/xp-conf/Papers/7_3_Alexandrescu.pdf">
 								    this paper</a>. He writes:
 								    <blockquote>
 								      <p>Policy classes are implementations of punctual design choices. They
 								      are inherited from, or contained within, other classes. They provide
 								      different strategies under the same syntactic interface. A class using
 								      policies is templated having one template parameter for each policy it
 								      uses. This allows the user to select the policies needed.
 								      <p>The power of policy classes comes from their ability to combine
 								      freely. By combining several policy classes in a template class with
 								      multiple parameters, one achieves combinatorial behaviors with a linear
 								      amount of code.
 								    </blockquote>
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
+								    <p>Andrei's description of policies describe their power as being derived
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
+								    from their granularity and orthogonality. Boost has probably diluted the
 								    distinction in the <a href="../libs/utility/iterator_adaptors.htm">Iterator
 								    Adaptors</a> library, where we transmit all of an adapted iterator's
-												add fixes from Peter Dimov and Kevlin Henney.


[SVN r9158]

											
										
										
											2001-02-12 22:20:58 +08:00
+								    behavior in a single policies class. There is precedent for this, however:
 								    <tt><a
 								    href="http://www.dinkumware.com/htm_cpl/string2.html#char_traits">std::char_traits</a></tt>,
 								    despite its name, acts as a policies class that determines the behaviors of
 								    <a
 								    href="http://www.dinkumware.com/htm_cpl/string2.html#basic_string">std::basic_string</a>.
-												Initial checkin


[SVN r9146]

											
										
										
											2001-02-12 11:17:54 +08:00
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
+								    <h2><a name="adaptors">Adaptors</a></h2>
 								    <p>An <i>adaptor</i> is a class template which builds on another type or
 								    types to provide a new interface or behavioral variant. Examples of
 								    standard adaptors are <a href=
 								    "http://www.sgi.com/tech/stl/ReverseIterator.html">std::reverse_iterator</a>,
 								    which adapts an iterator type by reversing its motion upon
 								    increment/decrement, and <a href=
 								    "http://www.sgi.com/tech/stl/stack.html">std::stack</a>, which adapts a
 								    container to provide a simple stack interface.
 								    <p>A more comprehensive review of the adaptors in the standard can be found
 								    <a href=
 								    "http://www.cs.rpi.edu/~wiseb/xrds/ovp2-3b.html#SECTION00015000000000000000">
 								    here</a>.
-												added a note about type generators being a workaround for no templated
typedefs


[SVN r9185]

											
										
										
											2001-02-13 12:32:00 +08:00
 								    <h2>Notes</h2>
 								    <a name="1">[1]</a> Type generators are a workaround for the lack
 								    of ``templated typedefs'' in C++.
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
+								    <hr>
 								    <p>Revised
-												Added link, fixed background


[SVN r9164]

											
										
										
											2001-02-13 02:37:48 +08:00
+								    <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->12 Feb 2001<!--webbot bot="Timestamp" endspan i-checksum="14377" -->
-												Added copyright and Adaptors section.


[SVN r9147]

											
										
										
											2001-02-12 12:03:20 +08:00
 								    <p>&copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
 								    sell and distribute this document is granted provided this copyright notice
 								    appears in all copies. This document is provided "as is" without express or
 								    implied warranty, and with no claim as to its suitability for any purpose.
-												added section on "tag dispatching"


[SVN r9154]

											
										
										
											2001-02-12 13:04:28 +08:00
+								<!--  LocalWords:  HTML html charset gif alt htm struct SGI namespace std libs
 								 -->
 								<!--  LocalWords:  InputIterator BidirectionalIterator RandomAccessIterator pdf
 								 -->
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
+								<!--  LocalWords:  typename Alexandrescu templated Andrei's Abrahams memcpy int
-												added section on "tag dispatching"


[SVN r9154]

											
										
										
											2001-02-12 13:04:28 +08:00
+								 -->
-												make HTML more conforming


[SVN r9169]

											
										
										
											2001-02-13 03:12:40 +08:00
+								</body>
 								</html>
-												added intro and def. of "concept"


[SVN r9188]

											
										
										
											2001-02-14 01:29:39 +08:00
+								<!--  LocalWords:  const OutputIterator iostream pre cpl
 								 -->