UList.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2011-2019 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> void writeEntry(Ostream& os, const UList<T>&);
63 template<class T> Ostream& operator<<(Ostream&, const UList<T>&);
64 template<class T> Istream& operator>>(Istream&, UList<T>&);
65 
66 typedef UList<label> labelUList;
67 
68 
69 /*---------------------------------------------------------------------------*\
70  Class UList Declaration
71 \*---------------------------------------------------------------------------*/
72 
73 template<class T>
74 class UList
75 {
76  // Private Data
77 
78  //- Number of elements in UList
79  label size_;
80 
81  //- Vector of values of type T
82  T* __restrict__ v_;
83 
84 
85  // Private Member Functions
86 
87  //- Disallow default shallow-copy assignment
88  //
89  // Assignment of UList<T> may need to be either shallow (copy pointer)
90  // or deep (copy elements) depending on context or the particular type
91  // of list derived from UList and it is confusing and prone to error
92  // for the default assignment to be either. The solution is to
93  // disallow default assignment and provide separate 'shallowCopy' and
94  // 'deepCopy' member functions
95  void operator=(const UList<T>&) = delete;
96 
97 
98 public:
99 
100  // Related types
101 
102  //- Declare friendship with the List class
103  friend class List<T>;
104 
105  //- Declare friendship with the SubList class
106  friend class SubList<T>;
107 
108 
109  // Static Member Functions
110 
111  //- Return a null UList
112  inline static const UList<T>& null();
113 
114 
115  // Public classes
116 
117  //- Less function class that can be used for sorting
118  class less
119  {
120  const UList<T>& values_;
121 
122  public:
124  less(const UList<T>& values)
125  :
126  values_(values)
127  {}
129  bool operator()(const label a, const label b)
130  {
131  return values_[a] < values_[b];
132  }
133  };
134 
135  //- Greater function class that can be used for sorting
136  class greater
137  {
138  const UList<T>& values_;
139 
140  public:
142  greater(const UList<T>& values)
143  :
144  values_(values)
145  {}
147  bool operator()(const label a, const label b)
148  {
149  return values_[a] > values_[b];
150  }
151  };
152 
153 
154  // Constructors
155 
156  //- Null constructor
157  inline UList();
158 
159  //- Construct from components
160  inline UList(T* __restrict__ v, label size);
161 
162 
163  // Member Functions
164 
165  // Access
166 
167  //- Return the forward circular index, i.e. the next index
168  // which returns to the first at the end of the list
169  inline label fcIndex(const label i) const;
170 
171  //- Return the reverse circular index, i.e. the previous index
172  // which returns to the last at the beginning of the list
173  inline label rcIndex(const label i) const;
174 
175  //- Return the binary size in number of characters of the UList
176  // if the element is a primitive type
177  // i.e. contiguous<T>() == true.
178  // Note that is of type streamsize since used in stream ops
179  std::streamsize byteSize() const;
180 
181 
182  //- Return a const pointer to the first data element,
183  // similar to the STL front() method and the string::data() method
184  // This can be used (with caution) when interfacing with C code
185  inline const T* cdata() const;
186 
187  //- Return a pointer to the first data element,
188  // similar to the STL front() method and the string::data() method
189  // This can be used (with caution) when interfacing with C code
190  inline T* data();
191 
192  //- Return the first element of the list
193  inline T& first();
194 
195  //- Return first element of the list
196  inline const T& first() const;
197 
198  //- Return the last element of the list
199  inline T& last();
200 
201  //- Return the last element of the list
202  inline const T& last() const;
203 
204 
205  // Check
206 
207  //- Check start is within valid range (0 ... size-1)
208  inline void checkStart(const label start) const;
209 
210  //- Check size is within valid range (0 ... size)
211  inline void checkSize(const label size) const;
212 
213  //- Check index i is within valid range (0 ... size-1)
214  inline void checkIndex(const label i) const;
215 
216 
217  // Edit
218 
219  //- Copy the pointer held by the given UList
220  inline void shallowCopy(const UList<T>&);
221 
222  //- Copy elements of the given UList
223  void deepCopy(const UList<T>&);
224 
225 
226  // Member Operators
227 
228  //- Return element of UList
229  inline T& operator[](const label);
230 
231  //- Return element of constant UList
232  // Note that the bool specialization adds lazy evaluation so reading
233  // an out-of-range element returns false without any ill-effects
234  inline const T& operator[](const label) const;
235 
236  //- Allow cast to a const List<T>&
237  inline operator const Foam::List<T>&() const;
238 
239  //- Assignment of all entries to the given value
240  void operator=(const T&);
241 
242  //- Assignment of all entries to zero
243  void operator=(const zero);
244 
245 
246  // STL type definitions
247 
248  //- Type of values the UList contains
249  typedef T value_type;
250 
251  //- Type that can be used for storing into
252  // UList::value_type objects
253  typedef T& reference;
254 
255  //- Type that can be used for storing into
256  // constant UList::value_type objects
257  typedef const T& const_reference;
258 
259  //- The type that can represent the difference between any two
260  // UList iterator objects
261  typedef label difference_type;
262 
263  //- The type that can represent the size of a UList
264  typedef label size_type;
265 
266 
267  // STL iterator
268 
269  //- Random access iterator for traversing UList
270  typedef T* iterator;
271 
272  //- Return an iterator to begin traversing the UList
273  inline iterator begin();
274 
275  //- Return an iterator to end traversing the UList
276  inline iterator end();
277 
278 
279  // STL const_iterator
280 
281  //- Random access iterator for traversing UList
282  typedef const T* const_iterator;
283 
284  //- Return const_iterator to begin traversing the constant UList
285  inline const_iterator cbegin() const;
286 
287  //- Return const_iterator to end traversing the constant UList
288  inline const_iterator cend() const;
289 
290  //- Return const_iterator to begin traversing the constant UList
291  inline const_iterator begin() const;
292 
293  //- Return const_iterator to end traversing the constant UList
294  inline const_iterator end() const;
295 
296 
297  // STL reverse_iterator
298 
299  //- Reverse iterator for reverse traversal of UList
300  typedef T* reverse_iterator;
301 
302  //- Return reverse_iterator to begin reverse traversing the UList
303  inline reverse_iterator rbegin();
304 
305  //- Return reverse_iterator to end reverse traversing the UList
306  inline reverse_iterator rend();
307 
308 
309  // STL const_reverse_iterator
310 
311  //- Reverse iterator for reverse traversal of constant UList
312  typedef const T* const_reverse_iterator;
313 
314  //- Return const_reverse_iterator to begin reverse traversing the UList
315  inline const_reverse_iterator crbegin() const;
316 
317  //- Return const_reverse_iterator to end reverse traversing the UList
318  inline const_reverse_iterator crend() const;
319 
320  //- Return const_reverse_iterator to begin reverse traversing the UList
321  inline const_reverse_iterator rbegin() const;
322 
323  //- Return const_reverse_iterator to end reverse traversing the UList
324  inline const_reverse_iterator rend() const;
325 
326 
327  // STL member functions
328 
329  //- Return the number of elements in the UList
330  inline label size() const;
331 
332  //- Return size of the largest possible UList
333  inline label max_size() const;
334 
335  //- Return true if the UList is empty (ie, size() is zero)
336  inline bool empty() const;
337 
338  //- Swap two ULists of the same type in constant time
339  void swap(UList<T>&);
340 
341 
342  // STL member operators
343 
344  //- Equality operation on ULists of the same type.
345  // Returns true when the ULists are element-wise equal
346  // (using UList::value_type::operator==). Takes linear time
347  bool operator==(const UList<T>&) const;
348 
349  //- The opposite of the equality operation. Takes linear time
350  bool operator!=(const UList<T>&) const;
351 
352  //- Compare two ULists lexicographically. 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  //- Return true if !(a > b). 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 
365  // Ostream operator
366 
367  // Write UList to Ostream
368  friend Ostream& operator<< <T>
369  (
370  Ostream&,
371  const UList<T>&
372  );
373 
374  //- Read UList contents from Istream. Requires size to have been set
375  // before
376  friend Istream& operator>> <T>
377  (
378  Istream&,
379  UList<T>&
380  );
381 };
382 
383 template<class T>
384 void sort(UList<T>&);
385 
386 template<class T, class Cmp>
387 void sort(UList<T>&, const Cmp&);
388 
389 template<class T>
390 void stableSort(UList<T>&);
391 
392 template<class T, class Cmp>
393 void stableSort(UList<T>&, const Cmp&);
394 
395 template<class T>
396 void shuffle(UList<T>&);
397 
398 // Reverse the first n elements of the list
399 template<class T>
400 inline void reverse(UList<T>&, const label n);
401 
402 // Reverse all the elements of the list
403 template<class T>
404 inline void reverse(UList<T>&);
405 
406 template<class ListType>
407 void writeListEntry(Ostream& os, const ListType& l);
408 
409 template<class ListType>
410 void writeListEntries(Ostream& os, const ListType& l);
411 
412 template<class ListType>
413 void writeListEntries(Ostream& os, const word& keyword, const ListType& l);
414 
415 
416 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
417 
418 } // End namespace Foam
419 
420 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
421 
422 #include "UListI.H"
423 
424 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
425 
426 //- Loop across all elements in \a list
427 // \par Usage
428 // \code
429 // forAll(anyList, i)
430 // {
431 // statements;
432 // }
433 // \endcode
434 // \sa forAllReverse
435 #define forAll(list, i) \
436  for (Foam::label i=0; i<(list).size(); i++)
437 
438 //- Reverse loop across all elements in \a list
439 // \par Usage
440 // \code
441 // forAllReverse(anyList, i)
442 // {
443 // statements;
444 // }
445 // \endcode
446 // \sa forAll
447 #define forAllReverse(list, i) \
448  for (Foam::label i=(list).size()-1; i>=0; i--)
449 
450 //- Iterate across all elements in the \a container object of type
451 // \a Container.
452 // \par Usage
453 // \code
454 // forAll(ContainerType, container, iter)
455 // {
456 // statements;
457 // }
458 // \endcode
459 // \sa forAllConstIter
460 #define forAllIter(Container,container,iter) \
461  for \
462  ( \
463  Container::iterator iter = (container).begin(); \
464  iter != (container).end(); \
465  ++iter \
466  )
467 
468 //- Iterate across all elements in the \a container object of type
469 // \a Container with const access.
470 // \par Usage
471 // \code
472 // forAllConstIter(ContainerType, container, iter)
473 // {
474 // statements;
475 // }
476 // \endcode
477 // \sa forAllIter
478 #define forAllConstIter(Container,container,iter) \
479  for \
480  ( \
481  Container::const_iterator iter = (container).begin(); \
482  iter != (container).end(); \
483  ++iter \
484  )
485 
486 
487 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
488 
489 #ifdef NoRepository
490  #include "UList.C"
491 #endif
492 
493 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
494 
495 #endif
496 
497 // ************************************************************************* //
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
void writeListEntries(Ostream &os, const ListType &l)
Definition: UListIO.C:59
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:59
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:269
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:65
label difference_type
The type that can represent the difference between any two.
Definition: UList.H:260
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:117
less(const UList< T > &values)
Definition: UList.H:123
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:60
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:299
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:252
static const UList< T > & null()
Return a null UList.
Definition: UListI.H:51
bool operator()(const label a, const label b)
Definition: UList.H:128
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
void writeEntry(Ostream &os, const HashTable< T, Key, Hash > &ht)
Definition: HashTableIO.C:96
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:263
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:281
const T * const_reverse_iterator
Reverse iterator for reverse traversal of constant UList.
Definition: UList.H:311
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:256
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:135
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 writeListEntry(Ostream &os, const ListType &l)
Definition: UListIO.C:35
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:248
System bool.
Namespace for OpenFOAM.