// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2009 - 2024 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_synchronous_iterator_h #define dealii_synchronous_iterator_h #include #include #include #include DEAL_II_NAMESPACE_OPEN /** * A class that represents a set of iterators each of which are incremented by * one at the same time. This is typically used in calls like * std::transform(a.begin(), a.end(), b.begin(), functor); where * we have synchronous iterators marching through the containers * a,b. If an object of this type represents the end of a range, * only the first element is considered (we only have a.end(), * not b.end()). An example of how this class is used is given * in step-35. * * The template argument of the current class shall be of type * std::tuple with arguments equal to the iterator types. * * The individual iterators can be accessed using * std::get(synchronous_iterator.iterators) where X is * the number corresponding to the desired iterator. * * This type, and the helper functions associated with it, are used as the * Value concept for the blocked_range type of the Threading Building Blocks. */ template struct SynchronousIterators { /** * Constructor. */ SynchronousIterators(const Iterators &i); /** * Dereference const operator. Returns a const reference to the iterators * represented by the current class. */ const Iterators & operator*() const; /** * Dereference operator. Returns a reference to the iterators * represented by the current class. */ Iterators & operator*(); /** * The following traits are necessary for std::distance() to * work with SynchronousIterators. */ using difference_type = std::size_t; using iterator_category = std::bidirectional_iterator_tag; using value_type = Iterators; using pointer = Iterators *; using reference = Iterators &; private: /** * Storage for the iterators represented by the current class. */ Iterators iterators; }; template inline SynchronousIterators::SynchronousIterators(const Iterators &i) : iterators(i) {} template inline const Iterators & SynchronousIterators::operator*() const { return iterators; } template inline Iterators & SynchronousIterators::operator*() { return iterators; } /** * Return whether the first element of the first argument is less than the * first element of the second argument. Since the objects compared march * forward all elements at the same time, comparing the first element is * sufficient. * * @relatesalso SynchronousIterators */ template inline bool operator<(const SynchronousIterators &a, const SynchronousIterators &b) { return std::get<0>(*a) < std::get<0>(*b); } /** * Return the distance between the first and the second argument. Since the * objects compared march forward all elements at the same time, differencing * the first element is sufficient. * * @relatesalso SynchronousIterators */ template inline std::size_t operator-(const SynchronousIterators &a, const SynchronousIterators &b) { Assert(std::distance(std::get<0>(*b), std::get<0>(*a)) >= 0, ExcInternalError()); return std::distance(std::get<0>(*b), std::get<0>(*a)); } /** * Advance a tuple of iterators by $n$. * * @relatesalso SynchronousIterators */ template inline void advance(std::tuple &t, const unsigned int n) { std::advance(std::get<0>(t), n); std::advance(std::get<1>(t), n); } /** * Advance a tuple of iterators by $n$. * * @relatesalso SynchronousIterators */ template inline void advance(std::tuple &t, const unsigned int n) { std::advance(std::get<0>(t), n); std::advance(std::get<1>(t), n); std::advance(std::get<2>(t), n); } /** * Advance a tuple of iterators by $n$. * * @relatesalso SynchronousIterators */ template inline void advance(std::tuple &t, const unsigned int n) { std::advance(std::get<0>(t), n); std::advance(std::get<1>(t), n); std::advance(std::get<2>(t), n); std::advance(std::get<3>(t), n); } /** * Reverse a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void prev(std::tuple &t) { --std::get<0>(t); --std::get<1>(t); } /** * Reverse a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void prev(std::tuple &t) { --std::get<0>(t); --std::get<1>(t); --std::get<2>(t); } /** * Reverse a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void prev(std::tuple &t) { --std::get<0>(t); --std::get<1>(t); --std::get<2>(t); --std::get<3>(t); } /** * Advance a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void advance_by_one(std::tuple &t) { ++std::get<0>(t); ++std::get<1>(t); } /** * Advance a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void advance_by_one(std::tuple &t) { ++std::get<0>(t); ++std::get<1>(t); ++std::get<2>(t); } /** * Advance a tuple of iterators by 1. * * @relatesalso SynchronousIterators */ template inline void advance_by_one(std::tuple &t) { ++std::get<0>(t); ++std::get<1>(t); ++std::get<2>(t); ++std::get<3>(t); } /** * Advance the elements of this iterator by $n$. * * @relatesalso SynchronousIterators */ template inline SynchronousIterators operator+(const SynchronousIterators &a, const std::size_t n) { SynchronousIterators x(a); dealii::advance(*x, n); return x; } /** * Advance the elements of this iterator by 1 (pre-increment). * * @relatesalso SynchronousIterators */ template inline SynchronousIterators & operator++(SynchronousIterators &a) { dealii::advance_by_one(*a); return a; } /** * Reverse the elements of this iterator by 1 (pre-decrement). * * @relatesalso SynchronousIterators */ template inline SynchronousIterators & operator--(SynchronousIterators &a) { dealii::prev(*a); return a; } /** * Advance the elements of this iterator by 1 (post-increment). * * @relatesalso SynchronousIterators */ template inline SynchronousIterators operator++(SynchronousIterators &a, int) { SynchronousIterators b = a; dealii::advance_by_one(*a); return b; } /** * Compare synch iterators for inequality. Since they march in synch, * comparing only the first element is sufficient. * * @relatesalso SynchronousIterators */ template inline bool operator!=(const SynchronousIterators &a, const SynchronousIterators &b) { return (std::get<0>(*a) != std::get<0>(*b)); } DEAL_II_NAMESPACE_CLOSE #endif