Better document the extract_subvector_to() functions.

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

diff --git a/include/deal.II/lac/block_vector_base.h b/include/deal.II/lac/block_vector_base.h
index 2e61d86c032fa2a57e7ab79ea76c9e70edbaf925..e68248f13df37ec237a1f6f82a4702e71cfcc19c 100644 (file)
--- a/include/deal.II/lac/block_vector_base.h
+++ b/include/deal.II/lac/block_vector_base.h
@@ -681,10 +681,19 @@ public:
   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,

diff --git a/include/deal.II/lac/la_parallel_vector.h b/include/deal.II/lac/la_parallel_vector.h
index 7edb31bee41dfa1cedd3ef496cfb96db21e4e533..1ed2f5ef1e771e175f058c1b0d3467be6904ddda 100644 (file)
--- a/include/deal.II/lac/la_parallel_vector.h
+++ b/include/deal.II/lac/la_parallel_vector.h
@@ -875,10 +875,19 @@ 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,

diff --git a/include/deal.II/lac/petsc_vector_base.h b/include/deal.II/lac/petsc_vector_base.h
index e3eefbba8d68f537f13a85c8556b9dfb67bbccab..046add94816f8aa5fa2f7e5f1fc009fb05d6c907 100644 (file)
--- a/include/deal.II/lac/petsc_vector_base.h
+++ b/include/deal.II/lac/petsc_vector_base.h
@@ -415,10 +415,19 @@ 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;

diff --git a/include/deal.II/lac/read_write_vector.h b/include/deal.II/lac/read_write_vector.h
index 80f29e242593414687471bc37c6e551ca1634287..4d3ee82d39f4d32a7b8fa5830a4d005e2db9d7aa 100644 (file)
--- a/include/deal.II/lac/read_write_vector.h
+++ b/include/deal.II/lac/read_write_vector.h
@@ -409,10 +409,19 @@ 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,

diff --git a/include/deal.II/lac/trilinos_precondition.h b/include/deal.II/lac/trilinos_precondition.h
index 1bec3c5c73f78eb3ee8456a9987668c0dbd131b5..f5380c15941f20d1500edbc68d8d6c20f34363c6 100644 (file)
--- a/include/deal.II/lac/trilinos_precondition.h
+++ b/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

diff --git a/include/deal.II/lac/trilinos_vector.h b/include/deal.II/lac/trilinos_vector.h
index a2bfbd686c99c82a6746031e8daf916a99a4bcd1..812f712b39ed34c12f27651d4a48c8128f4cca76 100644 (file)
--- a/include/deal.II/lac/trilinos_vector.h
+++ b/include/deal.II/lac/trilinos_vector.h
@@ -905,10 +905,19 @@ 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;

diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h
index d81bb464ef07a938d9e582830d4b2ff3bd9096b0..55632272870b3f16449331bf9d18a775c30cddf5 100644 (file)
--- a/include/deal.II/lac/vector.h
+++ b/include/deal.II/lac/vector.h
@@ -567,10 +567,19 @@ public:
   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,