senf/Utils/IteratorTraits.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief IteratorTraits public header */
  30
  31 #ifndef HH_SENF_Utils_IteratorTraits_
  32 #define HH_SENF_Utils_IteratorTraits_ 1
  33
  34 // Custom includes
  35 #include <boost/type_traits/integral_constant.hpp>
  36 #include <vector>
  37 #include <string>
  38
  39 //#include "IteratorTraits.mpp"
  40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  41
  42 namespace senf {
  43
  44 // The following is *not* standard mandated but it *is* mandated by TR1 and I know of no
  45 // implementation for which this is not correct
  46
  47     /** \brief Check for contiguous mutable storage
  48
  49         This type trait returns \c true, if \a RandomAccessIterator is an iterator into a contiguous
  50         storage area which may be written to. If this is the case, some algorithms may be optimized
  51         by directly modifying the underlying storage instead of relying on the STL interface.
  52
  53         \code
  54         // Generic algorithm
  55         template <class Iterator>
  56         void do(Iterator i, boost::false_type)
  57         {
  58             // Access the iterator 'i' via the standard STL interface
  59         }
  60
  61         template<class Iterator>
  62         void do(Iterator i, boost::true_type)
  63         {
  64             typename Iterator::pointer p (senf::storage_iterator(i));
  65             // Manipulate the container by manipulating the data pointed at via 'p'
  66         }
  67
  68         template <class Iterator>
  69         void foo(Iterator i)
  70         {
  71             // ...
  72             do( i, senf::contiguous_storage_iterator<Iterator>() );
  73             // ...
  74         }
  75         \endcode
  76
  77         Thie \ref senf::storage_iterator helper function will convert an iterator to a pointer to
  78         the same element the iterator is referencing.
  79
  80         This trait will return \c true for pointers. Additonally it should be configured to return
  81         true for all standard containers which obey above implementation restrictions. This
  82         typically includes \c std::vector and \c std::basic_string.
  83
  84         To do so, the template must be specialized for those containers \c iterator type. If
  85         compiling with g++, this is implemented in \ref IteratorTraits.ih. This file should be
  86         extended for further compilers or STL implementations if needed.
  87      */
  88     template <class RandomAccessIterator>
  89     struct contiguous_storage_iterator
  90         : public boost::false_type
  91     {};
  92
  93     /** \brief Check for contiguous mutable storage. Pointer specialization
  94
  95         See \ref contiguous_storage_iterator.
  96      */
  97     template <class T>
  98     struct contiguous_storage_iterator<T *>
  99         : public boost::true_type
 100     {};
 101
 102     /** \brief Convert contiguous storage iterator to pointer
 103
 104         storage_iterator will convert a contiguous storage iterator into a pointer to the same
 105         element in the container. This allows to directly access the containers storage.
 106
 107         \warning This conversion is only safe if \ref contiguous_storage_iterator<Iterator>::value
 108             is \c true for the given iterator type !
 109      */
 110     template <class Iterator>
 111     typename std::iterator_traits<Iterator>::pointer storage_iterator(Iterator i);
 112
 113 }
 114
 115 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 116 //#include "IteratorTraits.cci"
 117 //#include "IteratorTraits.ct"
 118 #include "IteratorTraits.cti"
 119 #include "IteratorTraits.ih"
 120 #endif
 121
 122 \f
 123 // Local Variables:
 124 // mode: c++
 125 // fill-column: 100
 126 // c-file-style: "senf"
 127 // indent-tabs-mode: nil
 128 // ispell-local-dictionary: "american"
 129 // compile-command: "scons -u test"
 130 // comment-column: 40
 131 // End: