Merge pull request #4644 from bangerth/doc-update

Better document the extract_subvector_to() functions.

include/deal.II/lac/block_vector_base.h

@@ -681,18 +681,50 @@ class BlockVectorBase : public Subscriptor
   reference operator[] (const size_type i);
 
   /**
-   * A collective get operation: instead of getting individual elements of a
-   * vector, this function allows to get a whole set of elements at once. The
+   * Instead of getting individual elements of a vector via operator(),
+   * this function allows getting a whole set of elements at once. The
    * indices of the elements to be read are stated in the first argument, the
    * corresponding values are returned in the second.
+   *
+   * If the current vector is called @p v, then this function is the equivalent
+   * to the code
+   * @code
+   *   for (unsigned int i=0; i<indices.size(); ++i)
+   *     values[i] = v[indices[i]];
+   * @endcode
+   *
+   * @pre The sizes of the @p indices and @p values arrays must be identical.
    */
   template <typename OtherNumber>
   void extract_subvector_to (const std::vector<size_type> &indices,
                              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,

include/deal.II/lac/la_parallel_vector.h

@@ -875,18 +875,50 @@ namespace LinearAlgebra
       Number &local_element (const size_type local_index);
 
       /**
-       * A collective get operation: instead of getting individual elements of
-       * a vector, this function allows to get a whole set of elements at
-       * once. The indices of the elements to be read are stated in the first
-       * argument, the corresponding values are returned in the second.
+       * Instead of getting individual elements of a vector via operator(),
+       * this function allows getting a whole set of elements at once. The
+       * indices of the elements to be read are stated in the first argument, the
+       * corresponding values are returned in the second.
+       *
+       * If the current vector is called @p v, then this function is the equivalent
+       * to the code
+       * @code
+       *   for (unsigned int i=0; i<indices.size(); ++i)
+       *     values[i] = v[indices[i]];
+       * @endcode
+       *
+       * @pre The sizes of the @p indices and @p values arrays must be identical.
        */
       template <typename OtherNumber>
       void extract_subvector_to (const std::vector<size_type> &indices,
                                  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,

include/deal.II/lac/petsc_vector_base.h

@@ -415,17 +415,49 @@ namespace PETScWrappers
               const std::vector<PetscScalar>  &values);
 
     /**
-     * A collective get operation: instead of getting individual elements of a
-     * vector, this function allows to get a whole set of elements at once.
-     * The indices of the elements to be read are stated in the first
-     * argument, the corresponding values are returned in the second.
+     * Instead of getting individual elements of a vector via operator(),
+     * this function allows getting a whole set of elements at once. The
+     * indices of the elements to be read are stated in the first argument, the
+     * corresponding values are returned in the second.
+     *
+     * If the current vector is called @p v, then this function is the equivalent
+     * to the code
+     * @code
+     *   for (unsigned int i=0; i<indices.size(); ++i)
+     *     values[i] = v[indices[i]];
+     * @endcode
+     *
+     * @pre The sizes of the @p indices and @p values arrays must be identical.
      */
     void extract_subvector_to (const std::vector<size_type> &indices,
                                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,

include/deal.II/lac/read_write_vector.h

@@ -409,18 +409,50 @@ namespace LinearAlgebra
     Number &operator [] (const size_type global_index);
 
     /**
-     * Instead of getting individual elements of a vector, this function
-     * allows to get a whole set of elements at once. The indices of the
-     * elements to be read are stated in the first argument, the corresponding
-     * values are returned in the second.
+     * Instead of getting individual elements of a vector via operator(),
+     * this function allows getting a whole set of elements at once. The
+     * indices of the elements to be read are stated in the first argument, the
+     * corresponding values are returned in the second.
+     *
+     * If the current vector is called @p v, then this function is the equivalent
+     * to the code
+     * @code
+     *   for (unsigned int i=0; i<indices.size(); ++i)
+     *     values[i] = v[indices[i]];
+     * @endcode
+     *
+     * @pre The sizes of the @p indices and @p values arrays must be identical.
      */
     template <typename Number2>
     void extract_subvector_to (const std::vector<size_type> &indices,
                                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,

include/deal.II/lac/trilinos_precondition.h

@@ -1527,7 +1527,7 @@ namespace TrilinosWrappers
      *
      * This initialization routine is useful in cases where the operator to be
      * preconditioned is not a TrilinosWrappers::SparseMatrix object but still
-     * allows to get a copy of the entries in each of the locally owned matrix
+     * allows getting a copy of the entries in each of the locally owned matrix
      * rows (method ExtractMyRowCopy) and implements a matrix-vector product
      * (methods Multiply or Apply). An example are operators which provide
      * faster matrix-vector multiplications than possible with matrix entries

include/deal.II/lac/trilinos_vector.h

@@ -905,17 +905,49 @@ namespace TrilinosWrappers
       operator[] (const size_type index) const;
 
       /**
-       * A collective get operation: instead of getting individual elements of a
-       * vector, this function allows to get a whole set of elements at once.
-       * The indices of the elements to be read are stated in the first
-       * argument, the corresponding values are returned in the second.
+       * Instead of getting individual elements of a vector via operator(),
+       * this function allows getting a whole set of elements at once. The
+       * indices of the elements to be read are stated in the first argument, the
+       * corresponding values are returned in the second.
+       *
+       * If the current vector is called @p v, then this function is the equivalent
+       * to the code
+       * @code
+       *   for (unsigned int i=0; i<indices.size(); ++i)
+       *     values[i] = v[indices[i]];
+       * @endcode
+       *
+       * @pre The sizes of the @p indices and @p values arrays must be identical.
        */
       void extract_subvector_to (const std::vector<size_type> &indices,
                                  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,

include/deal.II/lac/vector.h

@@ -567,18 +567,50 @@ class Vector : public Subscriptor
   Number &operator[] (const size_type i);
 
   /**
-   * A collective get operation: instead of getting individual elements of a
-   * vector, this function allows to get a whole set of elements at once. The
+   * Instead of getting individual elements of a vector via operator(),
+   * this function allows getting a whole set of elements at once. The
    * indices of the elements to be read are stated in the first argument, the
    * corresponding values are returned in the second.
+   *
+   * If the current vector is called @p v, then this function is the equivalent
+   * to the code
+   * @code
+   *   for (unsigned int i=0; i<indices.size(); ++i)
+   *     values[i] = v[indices[i]];
+   * @endcode
+   *
+   * @pre The sizes of the @p indices and @p values arrays must be identical.
    */
   template <typename OtherNumber>
   void extract_subvector_to (const std::vector<size_type> &indices,
                              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,