UList.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 2011-2016 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::UList
26 
27 Description
28  A 1D vector of objects of type <T>, where the size of the vector is
29  known and can be used for subscript bounds checking, etc.
30 
31  Storage is not allocated during construction or use but is supplied to
32  the constructor as an argument. This type of list is particularly useful
33  for lists that refer to parts of existing lists such as SubList.
34 
35 SourceFiles
36  UList.C
37  UListI.H
38  UListIO.C
39 
40 \*---------------------------------------------------------------------------*/
41 
42 #ifndef UList_H
43 #define UList_H
44 
45 #include "bool.H"
46 #include "label.H"
47 #include "uLabel.H"
48 #include "nullObject.H"
49 #include "zero.H"
50 
51 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
52 
53 namespace Foam
54 {
55 
56 // Forward declaration of friend classes
57 template<class T> class List;
58 template<class T> class SubList;
59 
60 // Forward declaration of friend functions and operators
61 template<class T> class UList;
62 template<class T> Ostream& operator<<(Ostream&, const UList<T>&);
63 template<class T> Istream& operator>>(Istream&, UList<T>&);
64 
65 typedef UList<label> labelUList;
66 
67 /*---------------------------------------------------------------------------*\
68  Class UList Declaration
69 \*---------------------------------------------------------------------------*/
70 
71 template<class T>
72 class UList
73 {
74  // Private data
75 
76  //- Number of elements in UList
77  label size_;
78 
79  //- Vector of values of type T
80  T* __restrict__ v_;
81 
82 
83  // Private Member Functions
84 
85  //- Disallow default shallow-copy assignment
86  //
87  // Assignment of UList<T> may need to be either shallow (copy pointer)
88  // or deep (copy elements) depending on context or the particular type
89  // of list derived from UList and it is confusing and prone to error
90  // for the default assignment to be either. The solution is to
91  // disallow default assignment and provide separate 'shallowCopy' and
92  // 'deepCopy' member functions
93  void operator=(const UList<T>&) = delete;
94 
95 
96 public:
97 
98  // Related types
99 
100  //- Declare friendship with the List class
101  friend class List<T>;
102 
103  //- Declare friendship with the SubList class
104  friend class SubList<T>;
105 
106 
107  // Static Member Functions
108 
109  //- Return a null UList
110  inline static const UList<T>& null();
111 
112 
113  // Public classes
114 
115  //- Less function class that can be used for sorting
116  class less
117  {
118  const UList<T>& values_;
119 
120  public:
122  less(const UList<T>& values)
123  :
124  values_(values)
125  {}
127  bool operator()(const label a, const label b)
128  {
129  return values_[a] < values_[b];
130  }
131  };
132 
133  //- Greater function class that can be used for sorting
134  class greater
135  {
136  const UList<T>& values_;
137 
138  public:
140  greater(const UList<T>& values)
141  :
142  values_(values)
143  {}
145  bool operator()(const label a, const label b)
146  {
147  return values_[a] > values_[b];
148  }
149  };
150 
151 
152  // Constructors
153 
154  //- Null constructor
155  inline UList();
156 
157  //- Construct from components
158  inline UList(T* __restrict__ v, label size);
159 
160 
161  // Member Functions
162 
163 
164  // Access
165 
166  //- Return the forward circular index, i.e. the next index
167  // which returns to the first at the end of the list
168  inline label fcIndex(const label i) const;
169 
170  //- Return the reverse circular index, i.e. the previous index
171  // which returns to the last at the beginning of the list
172  inline label rcIndex(const label i) const;
173 
174  //- Return the binary size in number of characters of the UList
175  // if the element is a primitive type
176  // i.e. contiguous<T>() == true.
177  // Note that is of type streamsize since used in stream ops
178  std::streamsize byteSize() const;
179 
180 
181  //- Return a const pointer to the first data element,
182  // similar to the STL front() method and the string::data() method
183  // This can be used (with caution) when interfacing with C code
184  inline const T* cdata() const;
185 
186  //- Return a pointer to the first data element,
187  // similar to the STL front() method and the string::data() method
188  // This can be used (with caution) when interfacing with C code
189  inline T* data();
190 
191  //- Return the first element of the list
192  inline T& first();
193 
194  //- Return first element of the list
195  inline const T& first() const;
196 
197  //- Return the last element of the list
198  inline T& last();
199 
200  //- Return the last element of the list
201  inline const T& last() const;
202 
203 
204  // Check
205 
206  //- Check start is within valid range (0 ... size-1)
207  inline void checkStart(const label start) const;
208 
209  //- Check size is within valid range (0 ... size)
210  inline void checkSize(const label size) const;
211 
212  //- Check index i is within valid range (0 ... size-1)
213  inline void checkIndex(const label i) const;
214 
215 
216  //- Copy the pointer held by the given UList
217  inline void shallowCopy(const UList<T>&);
218 
219  //- Copy elements of the given UList
220  void deepCopy(const UList<T>&);
221 
222  //- Write the UList as a dictionary entry
223  void writeEntry(Ostream&) const;
224 
225  //- Write the UList as a dictionary entry with keyword
226  void writeEntry(const word& keyword, Ostream&) const;
227 
228 
229  // Member operators
230 
231  //- Return element of UList
232  inline T& operator[](const label);
233 
234  //- Return element of constant UList
235  // Note that the bool specialization adds lazy evaluation so reading
236  // an out-of-range element returns false without any ill-effects
237  inline const T& operator[](const label) const;
238 
239  //- Allow cast to a const List<T>&
240  inline operator const Foam::List<T>&() const;
241 
242  //- Assignment of all entries to the given value
243  void operator=(const T&);
244 
245  //- Assignment of all entries to zero
246  void operator=(const zero);
247 
248 
249  // STL type definitions
250 
251  //- Type of values the UList contains
252  typedef T value_type;
253 
254  //- Type that can be used for storing into
255  // UList::value_type objects
256  typedef T& reference;
257 
258  //- Type that can be used for storing into
259  // constant UList::value_type objects
260  typedef const T& const_reference;
261 
262  //- The type that can represent the difference between any two
263  // UList iterator objects
264  typedef label difference_type;
265 
266  //- The type that can represent the size of a UList
267  typedef label size_type;
268 
269 
270  // STL iterator
271 
272  //- Random access iterator for traversing UList
273  typedef T* iterator;
274 
275  //- Return an iterator to begin traversing the UList
276  inline iterator begin();
277 
278  //- Return an iterator to end traversing the UList
279  inline iterator end();
280 
281 
282  // STL const_iterator
283 
284  //- Random access iterator for traversing UList
285  typedef const T* const_iterator;
286 
287  //- Return const_iterator to begin traversing the constant UList
288  inline const_iterator cbegin() const;
289 
290  //- Return const_iterator to end traversing the constant UList
291  inline const_iterator cend() const;
292 
293  //- Return const_iterator to begin traversing the constant UList
294  inline const_iterator begin() const;
295 
296  //- Return const_iterator to end traversing the constant UList
297  inline const_iterator end() const;
298 
299 
300  // STL reverse_iterator
301 
302  //- Reverse iterator for reverse traversal of UList
303  typedef T* reverse_iterator;
304 
305  //- Return reverse_iterator to begin reverse traversing the UList
306  inline reverse_iterator rbegin();
307 
308  //- Return reverse_iterator to end reverse traversing the UList
309  inline reverse_iterator rend();
310 
311 
312  // STL const_reverse_iterator
313 
314  //- Reverse iterator for reverse traversal of constant UList
315  typedef const T* const_reverse_iterator;
316 
317  //- Return const_reverse_iterator to begin reverse traversing the UList
318  inline const_reverse_iterator crbegin() const;
319 
320  //- Return const_reverse_iterator to end reverse traversing the UList
321  inline const_reverse_iterator crend() const;
322 
323  //- Return const_reverse_iterator to begin reverse traversing the UList
324  inline const_reverse_iterator rbegin() const;
325 
326  //- Return const_reverse_iterator to end reverse traversing the UList
327  inline const_reverse_iterator rend() const;
328 
329 
330  // STL member functions
331 
332  //- Return the number of elements in the UList
333  inline label size() const;
334 
335  //- Return size of the largest possible UList
336  inline label max_size() const;
337 
338  //- Return true if the UList is empty (ie, size() is zero)
339  inline bool empty() const;
340 
341  //- Swap two ULists of the same type in constant time
342  void swap(UList<T>&);
343 
344 
345  // STL member operators
346 
347  //- Equality operation on ULists of the same type.
348  // Returns true when the ULists are element-wise equal
349  // (using UList::value_type::operator==). Takes linear time
350  bool operator==(const UList<T>&) const;
351 
352  //- The opposite of the equality operation. Takes linear time
353  bool operator!=(const UList<T>&) const;
354 
355  //- Compare two ULists lexicographically. Takes linear time
356  bool operator<(const UList<T>&) const;
357 
358  //- Compare two ULists lexicographically. Takes linear time
359  bool operator>(const UList<T>&) const;
360 
361  //- Return true if !(a > b). Takes linear time
362  bool operator<=(const UList<T>&) const;
363 
364  //- Return true if !(a < b). Takes linear time
365  bool operator>=(const UList<T>&) const;
366 
367 
368  // Ostream operator
369 
370  // Write UList to Ostream
371  friend Ostream& operator<< <T>
372  (
373  Ostream&,
374  const UList<T>&
375  );
376 
377  //- Read UList contents from Istream. Requires size to have been set
378  // before
379  friend Istream& operator>> <T>
380  (
381  Istream&,
382  UList<T>&
383  );
384 };
385 
386 template<class T>
387 void sort(UList<T>&);
388 
389 template<class T, class Cmp>
390 void sort(UList<T>&, const Cmp&);
391 
392 template<class T>
393 void stableSort(UList<T>&);
394 
395 template<class T, class Cmp>
396 void stableSort(UList<T>&, const Cmp&);
397 
398 template<class T>
399 void shuffle(UList<T>&);
400 
401 // Reverse the first n elements of the list
402 template<class T>
403 inline void reverse(UList<T>&, const label n);
404 
405 // Reverse all the elements of the list
406 template<class T>
407 inline void reverse(UList<T>&);
408 
409 
410 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
411 
412 } // End namespace Foam
413 
414 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
415 
416 #include "UListI.H"
417 
418 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
419 
420 //- Loop across all elements in \a list
421 // \par Usage
422 // \code
423 // forAll(anyList, i)
424 // {
425 // statements;
426 // }
427 // \endcode
428 // \sa forAllReverse
429 #define forAll(list, i) \
430  for (Foam::label i=0; i<(list).size(); i++)
431 
432 //- Reverse loop across all elements in \a list
433 // \par Usage
434 // \code
435 // forAllReverse(anyList, i)
436 // {
437 // statements;
438 // }
439 // \endcode
440 // \sa forAll
441 #define forAllReverse(list, i) \
442  for (Foam::label i=(list).size()-1; i>=0; i--)
443 
444 //- Iterate across all elements in the \a container object of type
445 // \a Container.
446 // \par Usage
447 // \code
448 // forAll(ContainerType, container, iter)
449 // {
450 // statements;
451 // }
452 // \endcode
453 // \sa forAllConstIter
454 #define forAllIter(Container,container,iter) \
455  for \
456  ( \
457  Container::iterator iter = (container).begin(); \
458  iter != (container).end(); \
459  ++iter \
460  )
461 
462 //- Iterate across all elements in the \a container object of type
463 // \a Container with const access.
464 // \par Usage
465 // \code
466 // forAllConstIter(ContainerType, container, iter)
467 // {
468 // statements;
469 // }
470 // \endcode
471 // \sa forAllIter
472 #define forAllConstIter(Container,container,iter) \
473  for \
474  ( \
475  Container::const_iterator iter = (container).begin(); \
476  iter != (container).end(); \
477  ++iter \
478  )
479 
480 
481 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
482 
483 #ifdef NoRepository
484  #include "UList.C"
485 #endif
486 
487 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
488 
489 #endif
490 
491 // ************************************************************************* //
void shuffle(UList< T > &)
Definition: UList.C:143
bool operator!=(const UList< T > &) const
The opposite of the equality operation. Takes linear time.
Definition: UList.C:173
bool empty() const
Return true if the UList is empty (ie, size() is zero)
Definition: UListI.H:313
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:59
reverse_iterator rend()
Return reverse_iterator to end reverse traversing the UList.
Definition: UListI.H:279
reverse_iterator rbegin()
Return reverse_iterator to begin reverse traversing the UList.
Definition: UListI.H:258
T & operator[](const label)
Return element of UList.
Definition: UListI.H:167
label rcIndex(const label i) const
Return the reverse circular index, i.e. the previous index.
Definition: UListI.H:65
A 1D array of objects of type <T>, where the size of the vector is known and used for subscript bound...
Definition: HashTable.H:60
const T * cdata() const
Return a const pointer to the first data element,.
Definition: UListI.H:142
UList()
Null constructor.
Definition: UListI.H:33
An Istream is an abstract base class for all input systems (streams, files, token lists etc)...
Definition: Istream.H:57
label fcIndex(const label i) const
Return the forward circular index, i.e. the next index.
Definition: UListI.H:58
const_iterator cbegin() const
Return const_iterator to begin traversing the constant UList.
Definition: UListI.H:230
T * iterator
Random access iterator for traversing UList.
Definition: UList.H:272
iterator end()
Return an iterator to end traversing the UList.
Definition: UListI.H:237
T & first()
Return the first element of the list.
Definition: UListI.H:114
void deepCopy(const UList< T > &)
Copy elements of the given UList.
Definition: UList.C:35
UList< label > labelUList
Definition: UList.H:64
label difference_type
The type that can represent the difference between any two.
Definition: UList.H:263
bool operator==(const UList< T > &) const
Equality operation on ULists of the same type.
Definition: UList.C:152
A List obtained as a section of another List.
Definition: SubList.H:53
Less function class that can be used for sorting.
Definition: UList.H:115
less(const UList< T > &values)
Definition: UList.H:121
const dimensionedScalar b
Wien displacement law constant: default SI units: [m.K].
Definition: createFields.H:27
A class for handling words, derived from string.
Definition: word.H:59
bool operator>(const UList< T > &) const
Compare two ULists lexicographically. Takes linear time.
Definition: UList.C:211
Istream & operator>>(Istream &, directionInfo &)
void sort(UList< T > &)
Definition: UList.C:115
iterator begin()
Return an iterator to begin traversing the UList.
Definition: UListI.H:216
A 1D vector of objects of type <T>, where the size of the vector is known and can be used for subscri...
Definition: HashTable.H:61
label max_size() const
Return size of the largest possible UList.
Definition: UListI.H:306
void swap(UList< T > &)
Swap two ULists of the same type in constant time.
Definition: UList.C:90
An Ostream is an abstract base class for all output systems (streams, files, token lists...
Definition: Ostream.H:53
bool operator>=(const UList< T > &) const
Return true if !(a < b). Takes linear time.
Definition: UList.C:225
void reverse(UList< T > &, const label n)
Definition: UListI.H:322
T * reverse_iterator
Reverse iterator for reverse traversal of UList.
Definition: UList.H:302
const_reverse_iterator crbegin() const
Return const_reverse_iterator to begin reverse traversing the UList.
Definition: UListI.H:272
T & reference
Type that can be used for storing into.
Definition: UList.H:255
static const UList< T > & null()
Return a null UList.
Definition: UListI.H:51
bool operator()(const label a, const label b)
Definition: UList.H:126
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
const_reverse_iterator crend() const
Return const_reverse_iterator to end reverse traversing the UList.
Definition: UListI.H:293
label size_type
The type that can represent the size of a UList.
Definition: UList.H:266
T * data()
Return a pointer to the first data element,.
Definition: UListI.H:149
void shallowCopy(const UList< T > &)
Copy the pointer held by the given UList.
Definition: UListI.H:156
const T * const_iterator
Random access iterator for traversing UList.
Definition: UList.H:284
const T * const_reverse_iterator
Reverse iterator for reverse traversal of constant UList.
Definition: UList.H:314
std::streamsize byteSize() const
Return the binary size in number of characters of the UList.
Definition: UList.C:100
const T & const_reference
Type that can be used for storing into.
Definition: UList.H:259
A class representing the concept of 0 used to avoid unnecessary manipulations for objects that are kn...
Definition: zero.H:49
void checkSize(const label size) const
Check size is within valid range (0 ... size)
Definition: UListI.H:84
label n
Greater function class that can be used for sorting.
Definition: UList.H:133
const_iterator cend() const
Return const_iterator to end traversing the constant UList.
Definition: UListI.H:251
T & last()
Return the last element of the list.
Definition: UListI.H:128
label size() const
Return the number of elements in the UList.
Definition: UListI.H:299
void stableSort(UList< T > &)
Definition: UList.C:129
void checkStart(const label start) const
Check start is within valid range (0 ... size-1)
Definition: UListI.H:72
void checkIndex(const label i) const
Check index i is within valid range (0 ... size-1)
Definition: UListI.H:96
T value_type
Type of values the UList contains.
Definition: UList.H:251
System bool.
void writeEntry(Ostream &) const
Write the UList as a dictionary entry.
Definition: UListIO.C:35
Namespace for OpenFOAM.