From 8b74db0459062fb92eb199d7e215b4e6d728286f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= <klinkjak@fjfi.cvut.cz>
Date: Wed, 7 Aug 2019 10:25:34 +0200
Subject: [PATCH] Updated documentation for Vector and VectorView
---
src/TNL/Containers/Array.h | 6 +-
src/TNL/Containers/Vector.h | 84 +++++++++++++++++---------
src/TNL/Containers/Vector.hpp | 8 +--
src/TNL/Containers/VectorView.h | 98 +++++++++++++++++++++++++++++--
src/TNL/Containers/VectorView.hpp | 34 +++++------
5 files changed, 172 insertions(+), 58 deletions(-)
diff --git a/src/TNL/Containers/Array.h b/src/TNL/Containers/Array.h
index 52ca90369f..ded017ea5f 100644
--- a/src/TNL/Containers/Array.h
+++ b/src/TNL/Containers/Array.h
@@ -116,14 +116,14 @@ class Array
const AllocatorType& allocator = AllocatorType() );
/**
- * \brief Copy constructor.
+ * \brief Copy constructor (makes a deep copy).
*
* \param array The array to be copied.
*/
explicit Array( const Array& array );
/**
- * \brief Copy constructor with a specific allocator.
+ * \brief Copy constructor with a specific allocator (makes a deep copy).
*
* \param array The array to be copied.
* \param allocator The allocator to be associated with this array.
@@ -131,7 +131,7 @@ class Array
explicit Array( const Array& array, const AllocatorType& allocator );
/**
- * \brief Copy constructor.
+ * \brief Copy constructor (makes a deep copy).
*
* \param array The array to be copied.
* \param begin The first index which should be copied.
diff --git a/src/TNL/Containers/Vector.h b/src/TNL/Containers/Vector.h
index 4d5f6f0527..12e24a229f 100644
--- a/src/TNL/Containers/Vector.h
+++ b/src/TNL/Containers/Vector.h
@@ -22,7 +22,7 @@ namespace Containers {
* The template parameters have the same meaning as in \ref Array, with \e Real
* corresponding to \e Array's \e Value parameter.
*
- * \tparam Real A numeric type for the vector values, e.g. \ref float or
+ * \tparam Real An arithmetic type for the vector values, e.g. \ref float or
* \ref double.
* \tparam Device The device to be used for the execution of vector operations.
* \tparam Index The indexing type.
@@ -51,27 +51,27 @@ public:
using ViewType = VectorView< Real, Device, Index >;
using ConstViewType = VectorView< std::add_const_t< Real >, Device, Index >;
- //! \brief Default constructor.
+ // constructors and assignment operators inherited from the class Array
+ using Array< Real, Device, Index, Allocator >::Array;
+ using Array< Real, Device, Index, Allocator >::operator=;
+
+ //! \brief Constructs an empty array with zero size.
Vector() = default;
- //! \brief Default copy constructor.
+ //! \brief Copy constructor (makes a deep copy).
explicit Vector( const Vector& ) = default;
- //! \brief Copy constructor with a specific allocator.
+ //! \brief Copy constructor with a specific allocator (makes a deep copy).
explicit Vector( const Vector& vector, const AllocatorType& allocator );
//! \brief Default move constructor.
Vector( Vector&& ) = default;
- //! \brief Default copy-assignment operator.
+ //! \brief Copy-assignment operator for copying data from another vector.
Vector& operator=( const Vector& ) = default;
- //! \brief Default move-assignment operator.
+ //! \brief Move-assignment operator for acquiring data from \e rvalues.
Vector& operator=( Vector&& ) = default;
- //! Constructors and assignment operators are inherited from the class \ref Array.
- using Array< Real, Device, Index, Allocator >::Array;
- using Array< Real, Device, Index, Allocator >::operator=;
-
- /** \brief Returns type of vector Real value, Device type and the type of Index. */
+ //! \brief Returns a \ref String representation of the vector type in C++ style.
static String getType();
- /** \brief Returns type of vector Real value, Device type and the type of Index. */
+ //! \brief Returns a \ref String representation of the vector type in C++ style.
virtual String getTypeVirtual() const;
/**
@@ -114,6 +114,15 @@ public:
/**
* \brief Assigns a vector expression to this vector.
+ *
+ * The assignment is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector. If it evaluates to a vector
+ * with a different size than this vector, this vector is reallocated to
+ * match the size of the vector expression.
+ *
+ * \param expression The vector expression to be evaluated and assigned to
+ * this vector.
+ * \return Reference to this vector.
*/
template< typename VectorExpression,
typename...,
@@ -122,6 +131,8 @@ public:
/**
* \brief Assigns a value or an array - same as \ref Array::operator=.
+ *
+ * \return Reference to this vector.
*/
// operator= from the base class should be hidden according to the C++14 standard,
// although GCC does not do that - see https://stackoverflow.com/q/57322624
@@ -135,37 +146,53 @@ public:
}
/**
- * \brief This function subtracts \e vector from this vector and returns the resulting vector.
+ * \brief Adds elements of this vector and a vector expression and
+ * stores the result in this vector.
*
- * The subtraction is applied to all the vector elements separately.
- * \param vector Reference to another vector.
+ * The addition is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector.
*/
template< typename VectorExpression >
- Vector& operator-=( const VectorExpression& expression );
+ Vector& operator+=( const VectorExpression& expression );
/**
- * \brief This function adds \e vector to this vector and returns the resulting vector.
+ * \brief Subtracts elements of this vector and a vector expression and
+ * stores the result in this vector.
*
- * The addition is applied to all the vector elements separately.
- * \param vector Reference to another vector.
+ * The subtraction is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector.
*/
template< typename VectorExpression >
- Vector& operator+=( const VectorExpression& expression );
+ Vector& operator-=( const VectorExpression& expression );
/**
- * \brief This function multiplies this vector by \e c and returns the resulting vector.
+ * \brief Multiplies elements of this vector and a vector expression and
+ * stores the result in this vector.
+ *
+ * The multiplication is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector.
*
- * The multiplication is applied to all the vector elements separately.
- * \param c Multiplicator.
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector.
*/
template< typename VectorExpression >
Vector& operator*=( const VectorExpression& expression );
/**
- * \brief This function divides this vector by \e c and returns the resulting vector.
+ * \brief Divides elements of this vector and a vector expression and
+ * stores the result in this vector.
*
- * The division is applied to all the vector elements separately.
- * \param c Divisor.
+ * The division is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector.
*/
template< typename VectorExpression >
Vector& operator/=( const VectorExpression& expression );
@@ -179,10 +206,11 @@ public:
/**
* \brief Returns specific sums of elements of this vector.
*
+ * FIXME: computePrefixSum does not exist
+ *
* Does the same as \ref computePrefixSum, but computes only sums for elements
* with the index in range from \e begin to \e end. The other elements of this
- * vector remain untouched - with the same value. Therefore this method returns
- * a new vector with the length of this vector.
+ * vector remain untouched - with the same value.
*
* \param begin Index of the element in this vector which to begin with.
* \param end Index of the element in this vector which to end with.
diff --git a/src/TNL/Containers/Vector.hpp b/src/TNL/Containers/Vector.hpp
index 27fb4f8666..87dd93f692 100644
--- a/src/TNL/Containers/Vector.hpp
+++ b/src/TNL/Containers/Vector.hpp
@@ -119,9 +119,9 @@ template< typename Real,
template< typename VectorExpression >
Vector< Real, Device, Index, Allocator >&
Vector< Real, Device, Index, Allocator >::
-operator-=( const VectorExpression& expression )
+operator+=( const VectorExpression& expression )
{
- Algorithms::VectorAssignmentWithOperation< Vector, VectorExpression >::subtraction( *this, expression );
+ Algorithms::VectorAssignmentWithOperation< Vector, VectorExpression >::addition( *this, expression );
return *this;
}
@@ -132,9 +132,9 @@ template< typename Real,
template< typename VectorExpression >
Vector< Real, Device, Index, Allocator >&
Vector< Real, Device, Index, Allocator >::
-operator+=( const VectorExpression& expression )
+operator-=( const VectorExpression& expression )
{
- Algorithms::VectorAssignmentWithOperation< Vector, VectorExpression >::addition( *this, expression );
+ Algorithms::VectorAssignmentWithOperation< Vector, VectorExpression >::subtraction( *this, expression );
return *this;
}
diff --git a/src/TNL/Containers/VectorView.h b/src/TNL/Containers/VectorView.h
index 9f6e8bfd21..5b2b2230a7 100644
--- a/src/TNL/Containers/VectorView.h
+++ b/src/TNL/Containers/VectorView.h
@@ -19,6 +19,17 @@
namespace TNL {
namespace Containers {
+/**
+ * \brief \e VectorView extends \ref ArrayView with algebraic operations.
+ *
+ * The template parameters have the same meaning as in \ref ArrayView, with
+ * \e Real corresponding to \e ArrayView's \e Value parameter.
+ *
+ * \tparam Real An arithmetic type for the vector values, e.g. \ref float or
+ * \ref double.
+ * \tparam Device The device to be used for the execution of vector operations.
+ * \tparam Index The indexing type.
+ */
template< typename Real = double,
typename Device = Devices::Host,
typename Index = int >
@@ -36,22 +47,27 @@ public:
using ViewType = VectorView< Real, Device, Index >;
using ConstViewType = VectorView< std::add_const_t< Real >, Device, Index >;
- //! Constructors and assignment operators are inherited from the class \ref Array.
+ // constructors and assignment operators inherited from the class ArrayView
using ArrayView< Real, Device, Index >::ArrayView;
using ArrayView< Real, Device, Index >::operator=;
// In C++14, default constructors cannot be inherited, although Clang
// and GCC since version 7.0 inherit them.
// https://stackoverflow.com/a/51854172
+ //! \brief Constructs an empty array view with zero size.
__cuda_callable__
VectorView() = default;
+ //! \brief Constructor for the initialization by a base class object.
// initialization by base class is not a copy constructor so it has to be explicit
template< typename Real_ > // template catches both const and non-const qualified Element
__cuda_callable__
VectorView( const ArrayView< Real_, Device, Index >& view )
: BaseType( view ) {}
+ //! \brief Returns a \ref String representation of the vector view type.
+ static String getType();
+
/**
* \brief Returns a modifiable view of the vector view.
*
@@ -82,8 +98,17 @@ public:
__cuda_callable__
ConstViewType getConstView( IndexType begin = 0, IndexType end = 0 ) const;
- static String getType();
-
+ /**
+ * \brief Assigns a vector expression to this vector view.
+ *
+ * The assignment is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector
+ * view.
+ *
+ * \param expression The vector expression to be evaluated and assigned to
+ * this vector view.
+ * \return Reference to this vector view.
+ */
template< typename VectorExpression,
typename...,
typename = std::enable_if_t< Expressions::IsExpressionTemplate< VectorExpression >::value > >
@@ -91,6 +116,8 @@ public:
/**
* \brief Assigns a value or an array - same as \ref ArrayView::operator=.
+ *
+ * \return Reference to this vector view.
*/
// operator= from the base class should be hidden according to the C++14 standard,
// although GCC does not do that - see https://stackoverflow.com/q/57322624
@@ -103,21 +130,80 @@ public:
return ArrayView< Real, Device, Index >::operator=(data);
}
+ /**
+ * \brief Adds elements of this vector view and a vector expression and
+ * stores the result in this vector view.
+ *
+ * The addition is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector
+ * view.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector view.
+ */
template< typename VectorExpression >
- VectorView& operator-=( const VectorExpression& expression );
+ VectorView& operator+=( const VectorExpression& expression );
+ /**
+ * \brief Subtracts elements of this vector view and a vector expression and
+ * stores the result in this vector view.
+ *
+ * The subtraction is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector
+ * view.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector view.
+ */
template< typename VectorExpression >
- VectorView& operator+=( const VectorExpression& expression );
+ VectorView& operator-=( const VectorExpression& expression );
+ /**
+ * \brief Multiplies elements of this vector view and a vector expression and
+ * stores the result in this vector view.
+ *
+ * The multiplication is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector
+ * view.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector view.
+ */
template< typename VectorExpression >
VectorView& operator*=( const VectorExpression& expression );
+ /**
+ * \brief Divides elements of this vector view and a vector expression and
+ * stores the result in this vector view.
+ *
+ * The division is evaluated element-wise. The vector expression must
+ * either evaluate to a scalar or a vector of the same size as this vector
+ * view.
+ *
+ * \param expression Reference to a vector expression.
+ * \return Reference to this vector view.
+ */
template< typename VectorExpression >
VectorView& operator/=( const VectorExpression& expression );
+ /**
+ * \brief Returns sum of all vector elements.
+ */
template< typename ResultType = NonConstReal >
ResultType sum() const;
+ /**
+ * \brief Returns specific sums of elements of this vector view.
+ *
+ * FIXME: computePrefixSum does not exist
+ *
+ * Does the same as \ref computePrefixSum, but computes only sums for elements
+ * with the index in range from \e begin to \e end. The other elements of this
+ * vector remain untouched - with the same value.
+ *
+ * \param begin Index of the element in this vector view which to begin with.
+ * \param end Index of the element in this vector view which to end with.
+ */
template< Algorithms::PrefixSumType Type = Algorithms::PrefixSumType::Inclusive >
void prefixSum( IndexType begin = 0, IndexType end = 0 );
@@ -138,5 +224,5 @@ public:
} // namespace Containers
} // namespace TNL
-#include <TNL/Containers/VectorViewExpressions.h>
#include <TNL/Containers/VectorView.hpp>
+#include <TNL/Containers/VectorViewExpressions.h>
diff --git a/src/TNL/Containers/VectorView.hpp b/src/TNL/Containers/VectorView.hpp
index e9cb16a570..0054f8c755 100644
--- a/src/TNL/Containers/VectorView.hpp
+++ b/src/TNL/Containers/VectorView.hpp
@@ -19,6 +19,19 @@
namespace TNL {
namespace Containers {
+template< typename Real,
+ typename Device,
+ typename Index >
+String
+VectorView< Real, Device, Index >::
+getType()
+{
+ return String( "Containers::VectorView< " ) +
+ TNL::getType< Real >() + ", " +
+ Device::getDeviceType() + ", " +
+ TNL::getType< Index >() + " >";
+}
+
template< typename Real,
typename Device,
typename Index >
@@ -45,19 +58,6 @@ getConstView( const IndexType begin, IndexType end ) const
return ConstViewType( this->getData() + begin, end - begin );;
}
-template< typename Real,
- typename Device,
- typename Index >
-String
-VectorView< Real, Device, Index >::
-getType()
-{
- return String( "Containers::VectorView< " ) +
- TNL::getType< Real >() + ", " +
- Device::getDeviceType() + ", " +
- TNL::getType< Index >() + " >";
-}
-
template< typename Real,
typename Device,
typename Index >
@@ -75,9 +75,9 @@ template< typename Real,
template< typename VectorExpression >
VectorView< Real, Device, Index >&
VectorView< Real, Device, Index >::
-operator-=( const VectorExpression& expression )
+operator+=( const VectorExpression& expression )
{
- Algorithms::VectorAssignmentWithOperation< VectorView, VectorExpression >::subtraction( *this, expression );
+ Algorithms::VectorAssignmentWithOperation< VectorView, VectorExpression >::addition( *this, expression );
return *this;
}
@@ -87,9 +87,9 @@ template< typename Real,
template< typename VectorExpression >
VectorView< Real, Device, Index >&
VectorView< Real, Device, Index >::
-operator+=( const VectorExpression& expression )
+operator-=( const VectorExpression& expression )
{
- Algorithms::VectorAssignmentWithOperation< VectorView, VectorExpression >::addition( *this, expression );
+ Algorithms::VectorAssignmentWithOperation< VectorView, VectorExpression >::subtraction( *this, expression );
return *this;
}
--
GitLab