List.hpp

#pragma once
 
#include <opals/fwd.hpp>
 
#include <cstddef>
 
namespace std {
  struct bidirectional_iterator_tag;
}
 
namespace opals {
 
  /**
  \class  List
  \tparam T the element type
 
  \brief A template class representing an STL-conforming (doubly linked) std::list<T>
 
  Symbols for List are exported to opals DLLs as required by their modules' interfaces,
    meaning that DLL users are able to instantiate List only with the corresponding template arguments.
    The interface of opals::List differs slightly from std::list:
    no template constructors, no template functions are provided, but these are represented
    as non-template overloads for List::iterator, List::const_iterator, List::reverse_iterator, and List::const_reverse_iterator.
 
  \author wk
  \date   02.02.2011
 
  \internal
  Conversion constructors and operators for std::list<T> and its iterators are provided for internal use only.
  If T is another interface class (e.g. opals::String),
  then use function toInternal() to convert to std::list<std::string>.
  opals::List encapsulates STL's std::list, whose implementation it hides from the
  interface in order to avoid problems when using the interface / opals-DLLs
  with different STL-implementations.
  As opals data types are not required to be comparable,
  no (non-) template member operators are provided in the interface.
  */
 
  template<class T>
  class List
  {
    class Impl;
    Impl *pimpl_;
 
  public:
 
    typedef T                     value_type;
    typedef T*                    pointer;
    typedef T&                    reference;
    typedef T const&              const_reference;
    typedef std::size_t           size_type;
    typedef std::ptrdiff_t        difference_type;
 
    template<bool Const,bool Forward>
    class Iterator;
 
    typedef Iterator<false,true > iterator;
    typedef Iterator<true ,true > const_iterator;
    typedef Iterator<false,false> reverse_iterator;
    typedef Iterator<true ,false> const_reverse_iterator;
 
    /// \name construction / destruction
    ///@{
    List();
    List( size_type n );
    List( size_type n, const T& val );
    List( const List& other );
    List( iterator               beg, iterator               end );
    List( const_iterator         beg, const_iterator         end );
    List( reverse_iterator       beg, reverse_iterator       end );
    List( const_reverse_iterator beg, const_reverse_iterator end );
    ~List();
    ///@}
 
    /// \name assignment, swapping
    ///@{
    List& operator=( const List& other );
    void swap( List& other );
    ///@}
 
    /// \name iterator traversal
    /// forward/reverse, const/non-const
    ///@{
    iterator       begin();
    iterator       end();
    const_iterator begin() const;
    const_iterator end()   const;
 
    reverse_iterator       rbegin();
    reverse_iterator       rend();
    const_reverse_iterator rbegin() const;
    const_reverse_iterator rend()   const;
    ///@}
 
    /// \name direct data access
    ///@{
    reference       front();
    reference       back();
    const_reference front() const;
    const_reference back()  const;
    ///@}
 
    /// \name size
    ///@{
    size_type size()     const;
    size_type max_size() const;
    bool      empty()    const;
    void clear();
    void resize( size_type n, T val = T() );
    ///@}
 
    /// \name insertion
    ///@{
    void push_front( const T& val );
    void push_back( const T& val );
 
    iterator insert( iterator pos, const T& val );
    void insert( iterator pos, size_type n, const T& val );
    void insert( iterator pos, iterator               beg, iterator               end );
    void insert( iterator pos, const_iterator         beg, const_iterator         end );
    void insert( iterator pos, reverse_iterator       beg, reverse_iterator       end );
    void insert( iterator pos, const_reverse_iterator beg, const_reverse_iterator end );
    ///@}
 
    /// \name removal
    ///@{
    void pop_front();
    void pop_back();
    iterator erase( iterator pos );
    iterator erase( iterator beg, iterator end );
    ///@}
 
    /// \name transfer nodes from another list
    ///@{
    void splice( iterator before, List& from );
    void splice( iterator before, List& from, iterator at );
    void splice( iterator before, List& from, iterator beg, iterator end );
    ///@}
 
    /// \name remove, unique
    ///@{
    void remove( const T& val );
    void unique();
    ///@}
 
    /// \name merge, reverse, sort
    ///@{
    void merge( List& from );
    void reverse();
    void sort();
    ///@}
 
    /**
    \class Iterator
    \tparam Const constant-ness
    \tparam Forward forward/reverse traversal
 
    \brief A bidirectional iterator class for List
 
    \author wk
    \date   02.02.2011
    */
    template<bool Const,bool Forward>
    class Iterator
    {
      class Impl;
      Impl *pimpl_;
 
      template<class T1,bool Const1>
      struct ConstSel         { typedef       T1 Type; };
      template<class T1>
      struct ConstSel<T1,true> { typedef const T1 Type; };
 
    public:
      typedef std::bidirectional_iterator_tag    iterator_category;
      typedef T                                  value_type;
      typedef typename List<T>::difference_type  difference_type;
      typedef typename ConstSel<T,Const>::Type&  reference;
      typedef typename ConstSel<T,Const>::Type*  pointer;
      typedef Iterator<true,Forward>             ConstIterator;
 
      Iterator();
      Iterator( const Iterator& other );
      operator ConstIterator() const;
      ~Iterator();
      Iterator &operator= ( const Iterator& other );
      reference operator* () const;
      pointer   operator->() const;
      Iterator& operator++();
      Iterator  operator++(int);
      Iterator& operator--();
      Iterator  operator--(int);
 
      bool operator==( const Iterator<true, Forward>& other ) const;
      bool operator==( const Iterator<false,Forward>& other ) const;
      bool operator!=( const Iterator<true, Forward>& other ) const;
      bool operator!=( const Iterator<false,Forward>& other ) const;
 
    };
 
  };
 
}