List.hpp
1 #ifndef OPALS_LIST_HPP_INCLUDED
2 #define OPALS_LIST_HPP_INCLUDED
3 
4 #include <opals/fwd.hpp>
5 
6 #include <cstddef>
7 
8 namespace std {
9  struct bidirectional_iterator_tag;
10 }
11 
12 namespace opals {
13 
14  /**
15  \class List
16  \tparam T the element type
17 
18  \brief A template class representing an STL-conforming (doubly linked) std::list<T>
19 
20  Symbols for List are exported to opals DLLs as required by their modules' interfaces,
21  meaning that DLL users are able to instantiate List only with the corresponding template arguments.
22  The interface of opals::List differs slightly from std::list:
23  no template constructors, no template functions are provided, but these are represented
24  as non-template overloads for List::iterator, List::const_iterator, List::reverse_iterator, and List::const_reverse_iterator.
25 
26  \author wk
27  \date 02.02.2011
28 
29  \internal
30  Conversion constructors and operators for std::list<T> and its iterators are provided for internal use only.
31  If T is another interface class (e.g. opals::String),
32  then use function toInternal() to convert to std::list<std::string>.
33  opals::List encapsulates STL's std::list, whose implementation it hides from the
34  interface in order to avoid problems when using the interface / opals-DLLs
35  with different STL-implementations.
36  As opals data types are not required to be comparable,
37  no (non-) template member operators are provided in the interface.
38  */
39 
40  template<class T>
41  class List
42  {
43  class Impl;
44  Impl *pimpl_;
45 
46  public:
47 
48  typedef T value_type;
49  typedef T* pointer;
50  typedef T& reference;
51  typedef T const& const_reference;
52  typedef std::size_t size_type;
53  typedef std::ptrdiff_t difference_type;
54 
55  template<bool Const,bool Forward>
56  class Iterator;
57 
58  typedef Iterator<false,true > iterator;
59  typedef Iterator<true ,true > const_iterator;
60  typedef Iterator<false,false> reverse_iterator;
61  typedef Iterator<true ,false> const_reverse_iterator;
62 
63  /// \name construction / destruction
64  ///@{
65  List();
66  List( size_type n );
67  List( size_type n, const T& val );
68  List( const List& other );
69  List( iterator beg, iterator end );
70  List( const_iterator beg, const_iterator end );
71  List( reverse_iterator beg, reverse_iterator end );
72  List( const_reverse_iterator beg, const_reverse_iterator end );
73  ~List();
74  ///}@
75 
76  /// \name assignment, swapping
77  ///@{
78  List& operator=( const List& other );
79  void swap( List& other );
80  ///}@
81 
82  /// \name iterator traversal
83  /// forward/reverse, const/non-const
84  ///@{
85  iterator begin();
86  iterator end();
87  const_iterator begin() const;
88  const_iterator end() const;
89 
90  reverse_iterator rbegin();
91  reverse_iterator rend();
92  const_reverse_iterator rbegin() const;
93  const_reverse_iterator rend() const;
94  ///}@
95 
96  /// \name direct data access
97  ///@{
98  reference front();
99  reference back();
100  const_reference front() const;
101  const_reference back() const;
102  ///}@
103 
104  /// \name size
105  ///@{
106  size_type size() const;
107  size_type max_size() const;
108  bool empty() const;
109  void clear();
110  void resize( size_type n, T val = T() );
111  ///}@
112 
113  /// \name insertion
114  ///@{
115  void push_front( const T& val );
116  void push_back( const T& val );
117 
118  iterator insert( iterator pos, const T& val );
119  void insert( iterator pos, size_type n, const T& val );
120  void insert( iterator pos, iterator beg, iterator end );
121  void insert( iterator pos, const_iterator beg, const_iterator end );
122  void insert( iterator pos, reverse_iterator beg, reverse_iterator end );
123  void insert( iterator pos, const_reverse_iterator beg, const_reverse_iterator end );
124  ///}@
125 
126  /// \name removal
127  ///@{
128  void pop_front();
129  void pop_back();
130  iterator erase( iterator pos );
131  iterator erase( iterator beg, iterator end );
132  ///}@
133 
134  /// \name transfer nodes from another list
135  ///@{
136  void splice( iterator before, List& from );
137  void splice( iterator before, List& from, iterator at );
138  void splice( iterator before, List& from, iterator beg, iterator end );
139  ///}@
140 
141  /// \name remove, unique
142  ///@{
143  void remove( const T& val );
144  void unique();
145  ///}@
146 
147  /// \name merge, reverse, sort
148  ///@{
149  void merge( List& from );
150  void reverse();
151  void sort();
152  ///}@
153 
154  /**
155  \class Iterator
156  \tparam Const constant-ness
157  \tparam Forward forward/reverse traversal
158 
159  \brief A bidirectional iterator class for List
160 
161  \author wk
162  \date 02.02.2011
163  */
164  template<bool Const,bool Forward>
165  class Iterator
166  {
167  class Impl;
168  Impl *pimpl_;
169 
170  template<class T1,bool Const1>
171  struct ConstSel { typedef T1 Type; };
172  template<class T1>
173  struct ConstSel<T1,true> { typedef const T1 Type; };
174 
175  public:
176  typedef std::bidirectional_iterator_tag iterator_category;
177  typedef T value_type;
178  typedef typename List<T>::difference_type difference_type;
179  typedef typename ConstSel<T,Const>::Type& reference;
180  typedef typename ConstSel<T,Const>::Type* pointer;
181  typedef Iterator<true,Forward> ConstIterator;
182 
183  Iterator();
184  Iterator( const Iterator& other );
185  operator ConstIterator() const;
186  ~Iterator();
187  Iterator &operator= ( const Iterator& other );
188  reference operator* () const;
189  pointer operator->() const;
190  Iterator& operator++();
191  Iterator operator++(int);
192  Iterator& operator--();
193  Iterator operator--(int);
194 
195  bool operator==( const Iterator<true, Forward>& other ) const;
196  bool operator==( const Iterator<false,Forward>& other ) const;
197  bool operator!=( const Iterator<true, Forward>& other ) const;
198  bool operator!=( const Iterator<false,Forward>& other ) const;
199 
200  };
201 
202  };
203 
204 }
205 
206 #endif