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) 1991-2009 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 the
  13     Free Software Foundation; either version 2 of the License, or (at your
  14     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, write to the Free Software Foundation,
  23     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  24
  25 Class
  26     Foam::UList
  27
  28 Description
  29     A 1D vector of objects of type \<T\>, where the size of the vector is
  30     known and can be used for subscript bounds checking, etc.
  31
  32     Storage is not allocated during construction or use but is supplied to
  33     the constructor as an argument.  This type of list is particularly useful
  34     for lists that refer to parts of existing lists such as SubList.
  35
  36 SourceFiles
  37     UList.C
  38     UListI.H
  39     UListIO.C
  40
  41 \*---------------------------------------------------------------------------*/
  42
  43 #ifndef UList_H
  44 #define UList_H
  45
  46 #include <OpenFOAM/bool.H>
  47 #include <OpenFOAM/label.H>
  48 #include <OpenFOAM/uLabel.H>
  49
  50 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  51
  52 namespace Foam
  53 {
  54
  55 // Forward declaration of friend classes
  56 template<class T> class List;
  57 template<class T> class SubList;
  58
  59 // Forward declaration of friend functions and operators
  60 template<class T> class UList;
  61 template<class T> Ostream& operator<<(Ostream&, const UList<T>&);
  62
  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 begining 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
 155         // Check
 156
 157             //- Check start is within valid range (0 ... size-1).
 158             inline void checkStart(const label start) const;
 159
 160             //- Check size is within valid range (0 ... size).
 161             inline void checkSize(const label size) const;
 162
 163             //- Check index i is within valid range (0 ... size-1).
 164             inline void checkIndex(const label i) const;
 165
 166
 167         //- Write the UList as a dictionary entry.
 168         void writeEntry(Ostream&) const;
 169
 170         //- Write the UList as a dictionary entry with keyword.
 171         void writeEntry(const word& keyword, Ostream&) const;
 172
 173         //- Assign elements to those from UList.
 174         void assign(const UList<T>&);
 175
 176
 177     // Member operators
 178
 179         //- Return element of UList.
 180         inline T& operator[](const label);
 181
 182         //- Return element of constant UList.
 183         //  Note that the bool specialization adds lazy evaluation so reading
 184         //  an out-of-range element returns false without any ill-effects
 185         inline const T& operator[](const label) const;
 186
 187         //- Allow cast to a const List<T>&
 188         inline operator const Foam::List<T>&() const;
 189
 190         //- Assignment of all entries to the given value
 191         void operator=(const T&);
 192
 193
 194     // STL type definitions
 195
 196         //- Type of values the UList contains.
 197         typedef T value_type;
 198
 199         //- Type that can be used for storing into
 200         //  UList::value_type objects.
 201         typedef T& reference;
 202
 203         //- Type that can be used for storing into
 204         //  constant UList::value_type objects
 205         typedef const T& const_reference;
 206
 207         //- The type that can represent the difference between any two
 208         //  UList iterator objects.
 209         typedef label difference_type;
 210
 211         //- The type that can represent the size of a UList.
 212         typedef label size_type;
 213
 214
 215     // STL iterator
 216
 217         //- Random access iterator for traversing UList.
 218         typedef T* iterator;
 219
 220         //- Return an iterator to begin traversing the UList.
 221         inline iterator begin();
 222
 223         //- Return an iterator to end traversing the UList.
 224         inline iterator end();
 225
 226
 227     // STL const_iterator
 228
 229         //- Random access iterator for traversing UList.
 230         typedef const T* const_iterator;
 231
 232         //- Return const_iterator to begin traversing the constant UList.
 233         inline const_iterator cbegin() const;
 234
 235         //- Return const_iterator to end traversing the constant UList.
 236         inline const_iterator cend() const;
 237
 238         //- Return const_iterator to begin traversing the constant UList.
 239         inline const_iterator begin() const;
 240
 241         //- Return const_iterator to end traversing the constant UList.
 242         inline const_iterator end() const;
 243
 244
 245     // STL reverse_iterator
 246
 247         //- Reverse iterator for reverse traversal of UList.
 248         typedef T* reverse_iterator;
 249
 250         //- Return reverse_iterator to begin reverse traversing the UList.
 251         inline reverse_iterator rbegin();
 252
 253         //- Return reverse_iterator to end reverse traversing the UList.
 254         inline reverse_iterator rend();
 255
 256
 257     // STL const_reverse_iterator
 258
 259         //- Reverse iterator for reverse traversal of constant UList.
 260         typedef const T* const_reverse_iterator;
 261
 262         //- Return const_reverse_iterator to begin reverse traversing the UList.
 263         inline const_reverse_iterator crbegin() const;
 264
 265         //- Return const_reverse_iterator to end reverse traversing the UList.
 266         inline const_reverse_iterator crend() const;
 267
 268         //- Return const_reverse_iterator to begin reverse traversing the UList.
 269         inline const_reverse_iterator rbegin() const;
 270
 271         //- Return const_reverse_iterator to end reverse traversing the UList.
 272         inline const_reverse_iterator rend() const;
 273
 274
 275     // STL member functions
 276
 277         //- Return the number of elements in the UList.
 278         inline label size() const;
 279
 280         //- Return size of the largest possible UList.
 281         inline label max_size() const;
 282
 283         //- Return true if the UList is empty (ie, size() is zero).
 284         inline bool empty() const;
 285
 286         //- Swap two ULists of the same type in constant time.
 287         void swap(UList<T>&);
 288
 289
 290     // STL member operators
 291
 292         //- Equality operation on ULists of the same type.
 293         //  Returns true when the ULists are elementwise equal
 294         //  (using UList::value_type::operator==).  Takes linear time.
 295         bool operator==(const UList<T>&) const;
 296
 297         //- The opposite of the equality operation. Takes linear time.
 298         bool operator!=(const UList<T>&) const;
 299
 300         //- Compare two ULists lexicographically. Takes linear time.
 301         bool operator<(const UList<T>&) const;
 302
 303         //- Compare two ULists lexicographically. Takes linear time.
 304         bool operator>(const UList<T>&) const;
 305
 306         //- Return true if !(a > b). Takes linear time.
 307         bool operator<=(const UList<T>&) const;
 308
 309         //- Return true if !(a < b). Takes linear time.
 310         bool operator>=(const UList<T>&) const;
 311
 312
 313     // Ostream operator
 314
 315         // Write UList to Ostream.
 316         friend Ostream& operator<< <T>
 317         (
 318             Ostream&,
 319             const UList<T>&
 320         );
 321 };
 322
 323 template<class T>
 324 void sort(UList<T>&);
 325
 326 template<class T, class Cmp>
 327 void sort(UList<T>&, const Cmp&);
 328
 329 template<class T>
 330 void stableSort(UList<T>&);
 331
 332 template<class T, class Cmp>
 333 void stableSort(UList<T>&, const Cmp&);
 334
 335 // Reverse the first n elements of the list
 336 template<class T>
 337 inline void reverse(UList<T>&, const label n);
 338
 339 // Reverse all the elements of the list
 340 template<class T>
 341 inline void reverse(UList<T>&);
 342
 343
 344 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 345
 346 } // End namespace Foam
 347
 348 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 349
 350 #   include "UListI.H"
 351
 352 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 353
 354 /**
 355  * @def forAll(list, i)
 356  * Loop across all elements in @a list
 357  * @par Usage
 358  * @code
 359  * forAll(anyList, i)
 360  * {
 361  *      statements;
 362  * }
 363  * @endcode
 364  * @sa forAllReverse
 365 */
 366 /**
 367  * @def forAllReverse(list, i)
 368  * Reverse loop across all elements in @a list
 369  * @par Usage
 370  * @code
 371  * forAllReverse(anyList, i)
 372  * {
 373  *      statements;
 374  * }
 375  * @endcode
 376  * @sa forAll
 377 */
 378 #define forAll(list, i) \
 379     for (Foam::label i=0; i<(list).size(); i++)
 380
 381 #define forAllReverse(list, i) \
 382     for (Foam::label i=(list).size()-1; i>=0; i--)
 383
 384 /**
 385  * @def forAllIter(Container, container, iter)
 386  * Iterate across all elements in the @a container object of type
 387  * @a Container.
 388  * @par Usage
 389  * @code
 390  * forAll(ContainerType, container, iter)
 391  * {
 392  *     statements;
 393  * }
 394  * @endcode
 395  * @sa forAllConstIter
 396 */
 397 #define forAllIter(Container,container,iter)                                   \
 398     for                                                                        \
 399     (                                                                          \
 400         Container::iterator iter = (container).begin();                        \
 401         iter != (container).end();                                             \
 402         ++iter                                                                 \
 403     )
 404
 405 /**
 406  * @def forAllConstIter(Container, container, iter)
 407  * Iterate across all elements in the @a container object of type
 408  * @a Container with const access.
 409  * @par Usage
 410  * @code
 411  * forAllConstIter(ContainerType, container, iter)
 412  * {
 413  *     statements;
 414  * }
 415  * @endcode
 416  * @sa forAllIter
 417 */
 418 #define forAllConstIter(Container,container,iter)                              \
 419     for                                                                        \
 420     (                                                                          \
 421         Container::const_iterator iter = (container).begin();                  \
 422         iter != (container).end();                                             \
 423         ++iter                                                                 \
 424     )
 425
 426
 427 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 428
 429 #ifdef NoRepository
 430 #   include "UList.C"
 431 #endif
 432
 433 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 434
 435 #endif
 436
 437 // ************************ vim: set sw=4 sts=4 et: ************************ //