src/OpenFOAM/containers/Lists/UList/UList.H

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