Better document the extract_subvector_to() functions.

This commit deals with the variant of the function that takes iterators.

diff --git a/include/deal.II/lac/block_vector_base.h b/include/deal.II/lac/block_vector_base.h
index e68248f13df37ec237a1f6f82a4702e71cfcc19c..91325613cac8a258be03f3912ef6413ec7cdbf99 100644 (file)
--- a/include/deal.II/lac/block_vector_base.h
+++ b/include/deal.II/lac/block_vector_base.h
@@ -700,8 +700,31 @@ public:
                              std::vector<OtherNumber> &values) const;
 
   /**
-   * Just as the above, but with pointers. Useful in minimizing copying of
-   * data around.
+   * Instead of getting individual elements of a vector via operator(),
+   * this function allows getting a whole set of elements at once. In
+   * contrast to the previous function, this function obtains the
+   * indices of the elements by dereferencing all elements of the iterator
+   * range provided by the first two arguments, and puts the vector
+   * values into memory locations obtained by dereferencing a range
+   * of iterators starting at the location pointed to by the third
+   * argument.
+   *
+   * If the current vector is called @p v, then this function is the equivalent
+   * to the code
+   * @code
+   *   ForwardIterator indices_p = indices_begin;
+   *   OutputIterator  values_p  = values_begin;
+   *   while (indices_p != indices_end)
+   *   {
+   *     *values_p = v[*indices_p];
+   *     ++indices_p;
+   *     ++values_p;
+   *   }
+   * @endcode
+   *
+   * @pre It must be possible to write into as many memory locations
+   *   starting at @p values_begin as there are iterators between
+   *   @p indices_begin and @p indices_end.
    */
   template <typename ForwardIterator, typename OutputIterator>
   void extract_subvector_to (ForwardIterator          indices_begin,

diff --git a/include/deal.II/lac/la_parallel_vector.h b/include/deal.II/lac/la_parallel_vector.h
index 1ed2f5ef1e771e175f058c1b0d3467be6904ddda..1a5eeba4f679d917b8c839695da7df04f02f8b66 100644 (file)
--- a/include/deal.II/lac/la_parallel_vector.h
+++ b/include/deal.II/lac/la_parallel_vector.h
@@ -894,8 +894,31 @@ namespace LinearAlgebra
                                  std::vector<OtherNumber> &values) const;
 
       /**
-       * Just as the above, but with pointers. Useful in minimizing copying of
-       * data around.
+       * Instead of getting individual elements of a vector via operator(),
+       * this function allows getting a whole set of elements at once. In
+       * contrast to the previous function, this function obtains the
+       * indices of the elements by dereferencing all elements of the iterator
+       * range provided by the first two arguments, and puts the vector
+       * values into memory locations obtained by dereferencing a range
+       * of iterators starting at the location pointed to by the third
+       * argument.
+       *
+       * If the current vector is called @p v, then this function is the equivalent
+       * to the code
+       * @code
+       *   ForwardIterator indices_p = indices_begin;
+       *   OutputIterator  values_p  = values_begin;
+       *   while (indices_p != indices_end)
+       *   {
+       *     *values_p = v[*indices_p];
+       *     ++indices_p;
+       *     ++values_p;
+       *   }
+       * @endcode
+       *
+       * @pre It must be possible to write into as many memory locations
+       *   starting at @p values_begin as there are iterators between
+       *   @p indices_begin and @p indices_end.
        */
       template <typename ForwardIterator, typename OutputIterator>
       void extract_subvector_to (ForwardIterator          indices_begin,

diff --git a/include/deal.II/lac/petsc_vector_base.h b/include/deal.II/lac/petsc_vector_base.h
index 046add94816f8aa5fa2f7e5f1fc009fb05d6c907..1be039fde5d6e2b01d83af3140084ac0a7c65690 100644 (file)
--- a/include/deal.II/lac/petsc_vector_base.h
+++ b/include/deal.II/lac/petsc_vector_base.h
@@ -433,8 +433,31 @@ namespace PETScWrappers
                                std::vector<PetscScalar> &values) const;
 
     /**
-     * Just as the above, but with pointers. Useful in minimizing copying of
-     * data around.
+     * Instead of getting individual elements of a vector via operator(),
+     * this function allows getting a whole set of elements at once. In
+     * contrast to the previous function, this function obtains the
+     * indices of the elements by dereferencing all elements of the iterator
+     * range provided by the first two arguments, and puts the vector
+     * values into memory locations obtained by dereferencing a range
+     * of iterators starting at the location pointed to by the third
+     * argument.
+     *
+     * If the current vector is called @p v, then this function is the equivalent
+     * to the code
+     * @code
+     *   ForwardIterator indices_p = indices_begin;
+     *   OutputIterator  values_p  = values_begin;
+     *   while (indices_p != indices_end)
+     *   {
+     *     *values_p = v[*indices_p];
+     *     ++indices_p;
+     *     ++values_p;
+     *   }
+     * @endcode
+     *
+     * @pre It must be possible to write into as many memory locations
+     *   starting at @p values_begin as there are iterators between
+     *   @p indices_begin and @p indices_end.
      */
     template <typename ForwardIterator, typename OutputIterator>
     void extract_subvector_to (const ForwardIterator    indices_begin,

diff --git a/include/deal.II/lac/read_write_vector.h b/include/deal.II/lac/read_write_vector.h
index 4d3ee82d39f4d32a7b8fa5830a4d005e2db9d7aa..9a4ae1eef86d70093a2ead933f17c3483a70a3cf 100644 (file)
--- a/include/deal.II/lac/read_write_vector.h
+++ b/include/deal.II/lac/read_write_vector.h
@@ -428,8 +428,31 @@ namespace LinearAlgebra
                                std::vector<Number2> &values) const;
 
     /**
-     * Just as the above, but with pointers. Useful in minimizing copying of
-     * data around.
+     * Instead of getting individual elements of a vector via operator(),
+     * this function allows getting a whole set of elements at once. In
+     * contrast to the previous function, this function obtains the
+     * indices of the elements by dereferencing all elements of the iterator
+     * range provided by the first two arguments, and puts the vector
+     * values into memory locations obtained by dereferencing a range
+     * of iterators starting at the location pointed to by the third
+     * argument.
+     *
+     * If the current vector is called @p v, then this function is the equivalent
+     * to the code
+     * @code
+     *   ForwardIterator indices_p = indices_begin;
+     *   OutputIterator  values_p  = values_begin;
+     *   while (indices_p != indices_end)
+     *   {
+     *     *values_p = v[*indices_p];
+     *     ++indices_p;
+     *     ++values_p;
+     *   }
+     * @endcode
+     *
+     * @pre It must be possible to write into as many memory locations
+     *   starting at @p values_begin as there are iterators between
+     *   @p indices_begin and @p indices_end.
      */
     template <typename ForwardIterator, typename OutputIterator>
     void extract_subvector_to (ForwardIterator          indices_begin,

diff --git a/include/deal.II/lac/trilinos_vector.h b/include/deal.II/lac/trilinos_vector.h
index 812f712b39ed34c12f27651d4a48c8128f4cca76..39f420bbdb92e62dd5f020ddac66fe10cca9a95d 100644 (file)
--- a/include/deal.II/lac/trilinos_vector.h
+++ b/include/deal.II/lac/trilinos_vector.h
@@ -923,8 +923,31 @@ namespace TrilinosWrappers
                                  std::vector<TrilinosScalar> &values) const;
 
       /**
-       * Just as the above, but with pointers.  Useful in minimizing copying of
-       * data around.
+       * Instead of getting individual elements of a vector via operator(),
+       * this function allows getting a whole set of elements at once. In
+       * contrast to the previous function, this function obtains the
+       * indices of the elements by dereferencing all elements of the iterator
+       * range provided by the first two arguments, and puts the vector
+       * values into memory locations obtained by dereferencing a range
+       * of iterators starting at the location pointed to by the third
+       * argument.
+       *
+       * If the current vector is called @p v, then this function is the equivalent
+       * to the code
+       * @code
+       *   ForwardIterator indices_p = indices_begin;
+       *   OutputIterator  values_p  = values_begin;
+       *   while (indices_p != indices_end)
+       *   {
+       *     *values_p = v[*indices_p];
+       *     ++indices_p;
+       *     ++values_p;
+       *   }
+       * @endcode
+       *
+       * @pre It must be possible to write into as many memory locations
+       *   starting at @p values_begin as there are iterators between
+       *   @p indices_begin and @p indices_end.
        */
       template <typename ForwardIterator, typename OutputIterator>
       void extract_subvector_to (ForwardIterator          indices_begin,

diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h
index 55632272870b3f16449331bf9d18a775c30cddf5..b3f05fa510af7448300d2f0cf7e44660017cd25a 100644 (file)
--- a/include/deal.II/lac/vector.h
+++ b/include/deal.II/lac/vector.h
@@ -586,8 +586,31 @@ public:
                              std::vector<OtherNumber> &values) const;
 
   /**
-   * Just as the above, but with pointers. Useful in minimizing copying of
-   * data around.
+   * Instead of getting individual elements of a vector via operator(),
+   * this function allows getting a whole set of elements at once. In
+   * contrast to the previous function, this function obtains the
+   * indices of the elements by dereferencing all elements of the iterator
+   * range provided by the first two arguments, and puts the vector
+   * values into memory locations obtained by dereferencing a range
+   * of iterators starting at the location pointed to by the third
+   * argument.
+   *
+   * If the current vector is called @p v, then this function is the equivalent
+   * to the code
+   * @code
+   *   ForwardIterator indices_p = indices_begin;
+   *   OutputIterator  values_p  = values_begin;
+   *   while (indices_p != indices_end)
+   *   {
+   *     *values_p = v[*indices_p];
+   *     ++indices_p;
+   *     ++values_p;
+   *   }
+   * @endcode
+   *
+   * @pre It must be possible to write into as many memory locations
+   *   starting at @p values_begin as there are iterators between
+   *   @p indices_begin and @p indices_end.
    */
   template <typename ForwardIterator, typename OutputIterator>
   void extract_subvector_to (ForwardIterator       indices_begin,