From: Wolfgang Bangerth Date: Sat, 22 Jul 2017 19:42:12 +0000 (-0600) Subject: Better document the extract_subvector_to() functions. X-Git-Tag: v9.0.0-rc1~1395^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=47d1c7d3657e6bcf3d10a2c3029bb1c1aa634cb8;p=dealii.git 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 e68248f13d..91325613ca 100644 --- 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 &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 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 1ed2f5ef1e..1a5eeba4f6 100644 --- 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 &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 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 046add9481..1be039fde5 100644 --- 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 &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 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 4d3ee82d39..9a4ae1eef8 100644 --- 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 &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 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 812f712b39..39f420bbdb 100644 --- a/include/deal.II/lac/trilinos_vector.h +++ b/include/deal.II/lac/trilinos_vector.h @@ -923,8 +923,31 @@ namespace TrilinosWrappers std::vector &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 void extract_subvector_to (ForwardIterator indices_begin, diff --git a/include/deal.II/lac/vector.h b/include/deal.II/lac/vector.h index 5563227287..b3f05fa510 100644 --- a/include/deal.II/lac/vector.h +++ b/include/deal.II/lac/vector.h @@ -586,8 +586,31 @@ public: std::vector &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 void extract_subvector_to (ForwardIterator indices_begin,