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-2022 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:
123 
124  less(const UList<T>& values)
125  :
126  values_(values)
127  {}
128 
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:
141 
142  greater(const UList<T>& values)
143  :
144  values_(values)
145  {}
146 
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  //- Copy construct
163  inline UList(const UList<T>&) = default;
164 
165 
166  // Member Functions
167 
168  // Access
169 
170  //- Return the forward circular index, i.e. the next index
171  // which returns to the first at the end of the list
172  inline label fcIndex(const label i) const;
173 
174  //- Return the reverse circular index, i.e. the previous index
175  // which returns to the last at the beginning of the list
176  inline label rcIndex(const label i) const;
177 
178  //- Return the binary size in number of characters of the UList
179  // if the element is a primitive type
180  // i.e. contiguous<T>() == true.
181  // Note that is of type streamsize since used in stream ops
182  std::streamsize byteSize() const;
183 
184 
185  //- Return a const pointer to the first data element,
186  // similar to the STL front() method and the string::data() method
187  // This can be used (with caution) when interfacing with C code
188  inline const T* cdata() const;
189 
190  //- Return a pointer to the first data element,
191  // similar to the STL front() method and the string::data() method
192  // This can be used (with caution) when interfacing with C code
193  inline T* data();
194 
195  //- Return the first element of the list
196  inline T& first();
197 
198  //- Return first element of the list
199  inline const T& first() const;
200 
201  //- Return the last element of the list
202  inline T& last();
203 
204  //- Return the last element of the list
205  inline const T& last() const;
206 
207 
208  // Check
209 
210  //- Check start is within valid range (0 ... size-1)
211  inline void checkStart(const label start) const;
212 
213  //- Check size is within valid range (0 ... size)
214  inline void checkSize(const label size) const;
215 
216  //- Check index i is within valid range (0 ... size-1)
217  inline void checkIndex(const label i) const;
218 
219 
220  // Edit
221 
222  //- Copy the pointer held by the given UList
223  inline void shallowCopy(const UList<T>&);
224 
225  //- Copy elements of the given UList
226  void deepCopy(const UList<T>&);
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 specialisation 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 std::reverse_iterator<iterator> 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 std::reverse_iterator<const_iterator> 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 // 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 // ************************************************************************* //
label n
System bool.
An Istream is an abstract base class for all input systems (streams, files, token lists etc)....
Definition: Istream.H:60
A 1D array of objects of type <T>, where the size of the vector is known and used for subscript bound...
Definition: List.H:91
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:57
A List obtained as a section of another List.
Definition: SubList.H:56
Greater function class that can be used for sorting.
Definition: UList.H:136
bool operator()(const label a, const label b)
Definition: UList.H:146
greater(const UList< T > &values)
Definition: UList.H:141
Less function class that can be used for sorting.
Definition: UList.H:118
less(const UList< T > &values)
Definition: UList.H:123
bool operator()(const label a, const label b)
Definition: UList.H:128
A 1D vector of objects of type <T>, where the size of the vector is known and can be used for subscri...
Definition: UList.H:74
label size_type
The type that can represent the size of a UList.
Definition: UList.H:266
UList()
Null constructor.
Definition: UListI.H:33
const_reverse_iterator crbegin() const
Return const_reverse_iterator to begin reverse traversing the UList.
Definition: UListI.H:280
void deepCopy(const UList< T > &)
Copy elements of the given UList.
Definition: UList.C:35
label difference_type
The type that can represent the difference between any two.
Definition: UList.H:263
T & first()
Return the first element of the list.
Definition: UListI.H:114
label max_size() const
Return size of the largest possible UList.
Definition: UListI.H:318
T value_type
Type of values the UList contains.
Definition: UList.H:251
bool operator<(const UList< T > &) const
Compare two ULists lexicographically. Takes linear time.
Definition: UList.C:173
label rcIndex(const label i) const
Return the reverse circular index, i.e. the previous index.
Definition: UListI.H:65
const_reverse_iterator crend() const
Return const_reverse_iterator to end reverse traversing the UList.
Definition: UListI.H:288
const T * const_iterator
Random access iterator for traversing UList.
Definition: UList.H:284
const_iterator cbegin() const
Return const_iterator to begin traversing the constant UList.
Definition: UListI.H:232
void checkIndex(const label i) const
Check index i is within valid range (0 ... size-1)
Definition: UListI.H:96
T * iterator
Random access iterator for traversing UList.
Definition: UList.H:272
bool operator>=(const UList< T > &) const
Return true if !(a < b). Takes linear time.
Definition: UList.C:218
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator for reverse traversal of constant UList.
Definition: UList.H:314
label size() const
Return the number of elements in the UList.
Definition: UListI.H:311
label fcIndex(const label i) const
Return the forward circular index, i.e. the next index.
Definition: UListI.H:58
bool empty() const
Return true if the UList is empty (ie, size() is zero)
Definition: UListI.H:325
reverse_iterator rbegin()
Return reverse_iterator to begin reverse traversing the UList.
Definition: UListI.H:264
T & operator[](const label)
Return element of UList.
Definition: UListI.H:167
iterator begin()
Return an iterator to begin traversing the UList.
Definition: UListI.H:216
const_iterator cend() const
Return const_iterator to end traversing the constant UList.
Definition: UListI.H:240
std::reverse_iterator< iterator > reverse_iterator
Reverse iterator for reverse traversal of UList.
Definition: UList.H:302
bool operator>(const UList< T > &) const
Compare two ULists lexicographically. Takes linear time.
Definition: UList.C:204
T & reference
Type that can be used for storing into.
Definition: UList.H:255
const T * cdata() const
Return a const pointer to the first data element,.
Definition: UListI.H:142
std::streamsize byteSize() const
Return the binary size in number of characters of the UList.
Definition: UList.C:100
void swap(UList< T > &)
Swap two ULists of the same type in constant time.
Definition: UList.C:90
bool operator==(const UList< T > &) const
Equality operation on ULists of the same type.
Definition: UList.C:145
void checkSize(const label size) const
Check size is within valid range (0 ... size)
Definition: UListI.H:84
reverse_iterator rend()
Return reverse_iterator to end reverse traversing the UList.
Definition: UListI.H:272
iterator end()
Return an iterator to end traversing the UList.
Definition: UListI.H:224
T * data()
Return a pointer to the first data element,.
Definition: UListI.H:149
bool operator!=(const UList< T > &) const
The opposite of the equality operation. Takes linear time.
Definition: UList.C:166
void shallowCopy(const UList< T > &)
Copy the pointer held by the given UList.
Definition: UListI.H:156
T & last()
Return the last element of the list.
Definition: UListI.H:128
const T & const_reference
Type that can be used for storing into.
Definition: UList.H:259
void checkStart(const label start) const
Check start is within valid range (0 ... size-1)
Definition: UListI.H:72
bool operator<=(const UList< T > &) const
Return true if !(a > b). Takes linear time.
Definition: UList.C:211
A class for handling words, derived from string.
Definition: word.H:62
A class representing the concept of 0 used to avoid unnecessary manipulations for objects that are kn...
Definition: zero.H:50
volScalarField & b
Definition: createFields.H:25
Namespace for OpenFOAM.
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
void writeListEntry(Ostream &os, const ListType &l)
Definition: UListIO.C:35
void reverse(UList< T > &, const label n)
Definition: UListI.H:334
void writeEntry(Ostream &os, const HashTable< T, Key, Hash > &ht)
Definition: HashTableIO.C:96
void sort(UList< T > &)
Definition: UList.C:115
Istream & operator>>(Istream &, pistonPointEdgeData &)
void writeListEntries(Ostream &os, const ListType &l)
Definition: UListIO.C:58
Ostream & operator<<(Ostream &os, const fvConstraints &constraints)
void stableSort(UList< T > &)
Definition: UList.C:129
UList< label > labelUList
Definition: UList.H:65
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)