Utils/IteratorTraits.hh

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