From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Thu, 6 Apr 2023 23:25:48 +0000 (-0600)
Subject: Update documentation in IndexSet for a couple of functions.
X-Git-Tag: v9.5.0-rc1~366^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=79b824eca481a666c5efe3ab51f03f88d5f2967c;p=dealii.git

Update documentation in IndexSet for a couple of functions.
---

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 <code>[begin,end)</code>.
    *
    * @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 <code>begin@<=end</code> needs to be satisfied.
+   * added.
+   *
+   * @pre The condition <code>begin@<=end</code> 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 <typename ForwardIterator>
   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<size_type>(*p) < end_index)
         ranges_are_sorted = false;
     }