From f4371b787f5aae2ce68fe49ca61be7cc856127a7 Mon Sep 17 00:00:00 2001 From: Lei Qiao Date: Wed, 12 Aug 2015 17:05:35 -0500 Subject: [PATCH] Improve documentation to function copy_from() of class BlockMatrixBase, chunkSparseMatrix, sparseMatrixEz and sparseMatrix --- include/deal.II/lac/block_matrix_base.h | 15 +++++++++------ include/deal.II/lac/chunk_sparse_matrix.h | 15 +++++++++------ include/deal.II/lac/sparse_matrix.h | 16 +++++++++------- include/deal.II/lac/sparse_matrix_ez.h | 15 +++++++++------ 4 files changed, 36 insertions(+), 25 deletions(-) diff --git a/include/deal.II/lac/block_matrix_base.h b/include/deal.II/lac/block_matrix_base.h index 599673b319..080cb654b2 100644 --- a/include/deal.II/lac/block_matrix_base.h +++ b/include/deal.II/lac/block_matrix_base.h @@ -377,12 +377,15 @@ public: ~BlockMatrixBase (); /** - * Copy the given matrix to this one. The operation throws an error if the - * sparsity patterns of the two involved matrices do not point to the same - * object, since in this case the copy operation is cheaper. Since this - * operation is nonetheless not for free, we do not make it available through - * operator=(), since this may lead to unwanted usage, e.g. in copy - * arguments to functions, which should really be arguments by reference. + * Copy the matrix given as argument into the current object. + * + * Copying matrices is an expensive operation that we do not want to happen + * by accident through compiler generated code for operator=. + * (This would happen, for example, if one accidentally declared a function + * argument of the current type by value rather than by reference.) + * The functionality of copying matrices is implemented in this member function + * instead. All copy operations of objects of this type therefore require an + * explicit function call. * * The source matrix may be a matrix of arbitrary type, as long as its data * type is convertible to the data type of this matrix. diff --git a/include/deal.II/lac/chunk_sparse_matrix.h b/include/deal.II/lac/chunk_sparse_matrix.h index 71875f2d6c..9cf4a00395 100644 --- a/include/deal.II/lac/chunk_sparse_matrix.h +++ b/include/deal.II/lac/chunk_sparse_matrix.h @@ -692,12 +692,15 @@ public: void symmetrize (); /** - * Copy the given matrix to this one. The operation throws an error if the - * sparsity patterns of the two involved matrices do not point to the same - * object, since in this case the copy operation is cheaper. Since this - * operation is nonetheless not for free, we do not make it available through - * operator =, since this may lead to unwanted usage, e.g. in copy - * arguments to functions, which should really be arguments by reference. + * Copy the matrix given as argument into the current object. + * + * Copying matrices is an expensive operation that we do not want to happen + * by accident through compiler generated code for operator=. + * (This would happen, for example, if one accidentally declared a function + * argument of the current type by value rather than by reference.) + * The functionality of copying matrices is implemented in this member function + * instead. All copy operations of objects of this type therefore require an + * explicit function call. * * The source matrix may be a matrix of arbitrary type, as long as its data * type is convertible to the data type of this matrix. diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h index 96138f2508..86988585a4 100644 --- a/include/deal.II/lac/sparse_matrix.h +++ b/include/deal.II/lac/sparse_matrix.h @@ -869,13 +869,15 @@ public: void symmetrize (); /** - * Copy the given matrix to this one. The operation triggers an assertion - * if the sparsity patterns of the two involved matrices do not point to the - * same object, since in this case the copy operation is cheaper. Since this - * operation is nonetheless not for free, we do not make it available - * through operator =, since this may lead to unwanted usage, - * e.g. in copy arguments to functions, which should really be arguments by - * reference. + * Copy the matrix given as argument into the current object. + * + * Copying matrices is an expensive operation that we do not want to happen + * by accident through compiler generated code for operator=. + * (This would happen, for example, if one accidentally declared a function + * argument of the current type by value rather than by reference.) + * The functionality of copying matrices is implemented in this member function + * instead. All copy operations of objects of this type therefore require an + * explicit function call. * * The source matrix may be a matrix of arbitrary type, as long as its data * type is convertible to the data type of this matrix. diff --git a/include/deal.II/lac/sparse_matrix_ez.h b/include/deal.II/lac/sparse_matrix_ez.h index 14e3bdcf05..409c296a0f 100644 --- a/include/deal.II/lac/sparse_matrix_ez.h +++ b/include/deal.II/lac/sparse_matrix_ez.h @@ -508,12 +508,15 @@ public: const bool col_indices_are_sorted = false); /** - * Copy the given matrix to this one. The operation throws an error if the - * sparsity patterns of the two involved matrices do not point to the same - * object, since in this case the copy operation is cheaper. Since this - * operation is nonetheless not for free, we do not make it available through - * operator =, since this may lead to unwanted usage, e.g. in copy - * arguments to functions, which should really be arguments by reference. + * Copy the matrix given as argument into the current object. + * + * Copying matrices is an expensive operation that we do not want to happen + * by accident through compiler generated code for operator=. + * (This would happen, for example, if one accidentally declared a function + * argument of the current type by value rather than by reference.) + * The functionality of copying matrices is implemented in this member function + * instead. All copy operations of objects of this type therefore require an + * explicit function call. * * The source matrix may be a matrix of arbitrary type, as long as its data * type is convertible to the data type of this matrix. -- 2.39.5