senf/Utils/IteratorTraits.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief IteratorTraits public header */
  25
  26 #ifndef HH_SENF_Utils_IteratorTraits_
  27 #define HH_SENF_Utils_IteratorTraits_ 1
  28
  29 // Custom includes
  30 #include <boost/type_traits/integral_constant.hpp>
  31 #include <vector>
  32 #include <string>
  33
  34 //#include "IteratorTraits.mpp"
  35 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  36
  37 namespace senf {
  38
  39 // The following is *not* standard mandated but it *is* mandated by TR1 and I know of no
  40 // implementation for which this is not correct
  41
  42     /** \brief Check for contiguous mutable storage
  43
  44         This type trait returns \c true, if \a RandomAccessIterator is an iterator into a contiguous
  45         storage area which may be written to. If this is the case, some algorithms may be optimized
  46         by directly modifying the underlying storage instead of relying on the STL interface.
  47
  48         \code
  49         // Generic algorithm
  50         template <class Iterator>
  51         void do(Iterator i, boost::false_type)
  52         {
  53             // Access the iterator 'i' via the standard STL interface
  54         }
  55
  56         template<class Iterator>
  57         void do(Iterator i, boost::true_type)
  58         {
  59             typename Iterator::pointer p (senf::storage_iterator(i));
  60             // Manipulate the container by manipulating the data pointed at via 'p'
  61         }
  62
  63         template <class Iterator>
  64         void foo(Iterator i)
  65         {
  66             // ...
  67             do( i, senf::contiguous_storage_iterator<Iterator>() );
  68             // ...
  69         }
  70         \endcode
  71
  72         Thie \ref senf::storage_iterator helper function will convert an iterator to a pointer to
  73         the same element the iterator is referencing.
  74
  75         This trait will return \c true for pointers. Additonally it should be configured to return
  76         true for all standard containers which obey above implementation restrictions. This
  77         typically includes \c std::vector and \c std::basic_string.
  78
  79         To do so, the template must be specialized for those containers \c iterator type. If
  80         compiling with g++, this is implemented in \ref IteratorTraits.ih. This file should be
  81         extended for further compilers or STL implementations if needed.
  82      */
  83     template <class RandomAccessIterator>
  84     struct contiguous_storage_iterator
  85         : public boost::false_type
  86     {};
  87
  88     /** \brief Check for contiguous mutable storage. Pointer specialization
  89
  90         See \ref contiguous_storage_iterator.
  91      */
  92     template <class T>
  93     struct contiguous_storage_iterator<T *>
  94         : public boost::true_type
  95     {};
  96
  97     /** \brief Convert contiguous storage iterator to pointer
  98
  99         storage_iterator will convert a contiguous storage iterator into a pointer to the same
 100         element in the container. This allows to directly access the containers storage.
 101
 102         \warning This conversion is only safe if \ref contiguous_storage_iterator<Iterator>::value
 103             is \c true for the given iterator type !
 104      */
 105     template <class Iterator>
 106     typename std::iterator_traits<Iterator>::pointer storage_iterator(Iterator i);
 107
 108 }
 109
 110 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 111 //#include "IteratorTraits.cci"
 112 //#include "IteratorTraits.ct"
 113 #include "IteratorTraits.cti"
 114 #include "IteratorTraits.ih"
 115 #endif
 116
 117 \f
 118 // Local Variables:
 119 // mode: c++
 120 // fill-column: 100
 121 // c-file-style: "senf"
 122 // indent-tabs-mode: nil
 123 // ispell-local-dictionary: "american"
 124 // compile-command: "scons -u test"
 125 // comment-column: 40
 126 // End: