From 79b824eca481a666c5efe3ab51f03f88d5f2967c Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Thu, 6 Apr 2023 17:25:48 -0600 Subject: [PATCH] Update documentation in IndexSet for a couple of functions. --- include/deal.II/base/index_set.h | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/include/deal.II/base/index_set.h b/include/deal.II/base/index_set.h index e47e055f88..3ff8b14ce5 100644 --- a/include/deal.II/base/index_set.h +++ b/include/deal.II/base/index_set.h @@ -174,6 +174,11 @@ public: /** * Add an individual index to the set of indices. + * + * If you have many indices to add to the set, consider calling the + * add_indices() function below. It is considerably more efficient, + * particularly if the indices to be added are stored in an array + * that is already sorted. */ void add_index(const size_type index); @@ -183,9 +188,17 @@ public: * the iterator range [begin,end). * * @param[in] begin Iterator to the first element of range of indices to be - * added + * added. * @param[in] end The past-the-end iterator for the range of elements to be - * added. @pre The condition begin@<=end needs to be satisfied. + * added. + * + * @pre The condition begin@<=end needs to be satisfied. They + * also obviously have to point into the same container. + * + * @note The operations of this function are substantially more efficient if + * if the indices pointed to by the range of iterators are already sorted. + * As a consequence, it is often worth sorting the range of indices + * before calling this function. */ template void @@ -1726,6 +1739,11 @@ IndexSet::add_indices(const ForwardIterator &begin, const ForwardIterator &end) bool ranges_are_sorted = true; for (ForwardIterator p = begin; p != end;) { + // Starting with the current iterator 'p', find an iterator + // 'q' so that the indices pointed to by the iterators in + // the range [p,q) are consecutive. These indices then form + // a range that is contiguous, and that can be added all + // at once. const size_type begin_index = *p; size_type end_index = begin_index + 1; ForwardIterator q = p; @@ -1736,13 +1754,15 @@ IndexSet::add_indices(const ForwardIterator &begin, const ForwardIterator &end) ++q; } + // Add this range: tmp_ranges.emplace_back(begin_index, end_index); - p = q; - // if the starting index of the next go-around of the for loop is less + // Then move on to the next element in the input range. + // If the starting index of the next go-around of the for loop is less // than the end index of the one just identified, then we will have at // least one pair of ranges that are not sorted, and consequently the // whole collection of ranges is not sorted. + p = q; if (p != end && static_cast(*p) < end_index) ranges_are_sorted = false; } -- 2.39.5