In this section, we consider the class xarray
and its semantic bases (xcontainer_semantic
and
xsemantic_base
) to illustrate how the assignment works. xtensor provides different mechanics of
assignment depending on the type of expression.
xarray
provides an extended copy constructor and an extended assignment operator:
template <class E> xarray(const xexpression<E>&); template <class E> self_type& operator=(const xexpression<E>& e);
The assignment operator forwards to xsemantic_base::operator=
whose implementation is given below:
template <class E> derived_type& operator=(const xexpression<E>& e) { temporary_type tmp(e); return this->derived_cast().assign_temporary(std::move(tmp)); }
Here temporary_type
is xarray
, the assignment operator computes the result of the expression in
a temporary variable and then assigns it to the xarray
instance. This temporary variable avoids aliasing
when the array is involved in the rhs expression where broadcasting happens:
xarray<double> a = {1, 2, 3, 4}; xarray<double> b = {{1, 2, 3, 4}, {5, 6, 7, 8}}; a = a + b;
The extended copy constructor calls xsemantic_base::assign
which calls xcontainer::assign_xexpression
.
This two-steps invocation allows to provide an uniform API (assign, plus_assign, minus_assign, etc) in the
top base class while specializing the implementations in inheriting classes (xcontainer_semantic
and
xview_semantic
). xcontainer::assign_xexpression
eventually calls the free function xt::assign_xexpression
which will be discussed in details later.
The behavior of the extended copy semantic can be summarized with the following diagram:
Computed assignment can be achieved either with traditional operators (operator+=
, operator-=
) or
with the corresponding assign functions (plus_assign
, minus_assign
, etc). The computed assignment
operators forwards to the extended assignment operator as illustrated below:
template <class D> template <class E> inline auto xsemantic_base<D>::operator+=(const xexpression<E>& e) -> derived_type& { return operator=(this->derived_cast() + e.derived_cast()); }
The computed assign functions, like assign
itself, avoid the instantiation of a temporary variable.
They call the overload of computed_assign
which, in the case of xcontainer_semantic
, simply forwards
to the free function xt::computed_assign
:
template <class D> template <class E> inline auto xsemantic_base<D>::plus_assign(const xexpression<E>& e) -> derived_type& { return this->derived_cast().computed_assign(this->derived_cast() + e.derived_cast()); } template <class D> template <class E> inline auto xcontainer_semantic<D>::computed_assign(const xexpression<E>& e) -> derived_type& { xt::computed_assign(*this, e); return this->derived_cast(); }
Again this two-steps invocation allows to provide a uniform API in xsemantic_base
and specializations
in the inheriting semantic classes. Besides this allows some code factorization since the assignment
logic is implemented only once in xt::computed_assign
.
Computed assignment operators involving a scalar are similar to computed assign methods:
template <class D> template <class E> inline auto xsemantic_base<D>::operator+=(const E& e) -> disable_xexpression<E, derived_type&> { return this->derived_cast().scalar_computed_assign(e, std::plus<>()); } template <class D> template <class E, class F> inline auto xcontainer_semantic<D>::scalar_computed_assign(const E& e, F&& f) -> derived_type& { xt::scalar_computed_assign(*this, e, std::forward<F>(f)); return this->derived_cast(); }
The free function xt::scalar_computed_assign
contains optimizations specific to scalars.
The three main functions for assigning expressions (assign_xexpression
, computed_assign
and
scalar_computed_assign
) have a similar implementation: they forward the call to the
xexpression_assigner
, a template class that can be specialized according to the expression
tag:
template <class E1, class E2> inline void assign_xexpression(xexpression<E1>& e1, const xexpression<E2>& e2) { using tag = xexpression_tag_t<E1, E2>; xexpression_assigner<tag>::assign_xexpression(e1, e2); } template <class Tag> class xexpression_assigner : public xexpression_assigner_base<Tag> { public: using base_type = xexpression_assigner_base<Tag>; template <class E1, class E2> static void assign_xexpression(xexpression<E1>& e1, const xexpression<E2>& e2); template <class E1, class E2> static void computed_assign(xexpression<E1>& e1, const xexpression<E2>& e2); template <class E1, class E2, class F> static void scalar_computed_assign(xexpression<E1>& e1, const E2& e2, F&& f); // ... };
xtensor provides specializations for xtensor_expression_tag
and xoptional_expression_tag
.
When implementing a new function type whose API is unrelated to the one of xfunction_base
,
the xexpression_assigner
should be specialized so that the assignment relies on this specific API.
The assign_xexpression
methods first resizes the lhs expression, it chooses an assignment
method depending on many properties of both lhs and rhs expressions. One of these properties, computed
during the resize phase, is the nature of the assignment: trivial or not. The assignment is said to be
trivial when the memory layout of the lhs and rhs are such that assignment can be done by iterating over
a 1-D sequence on both sides. In that case, two options are possible:
- if
xtensor
is compiled with the optionalxsimd
dependency, and if the layout and thevalue_type
of each expression allows it, the assignment is a vectorized index-based loop operating on the expression buffers. - if the
xsimd
assignment is not possible (for any reason), an iterator-based loop operating on the expresion buffers is used instead.
These methods are implemented in specializations of the trivial_assigner
class.
When the assignment is not trivial, :ref:`stepper-label` are used to perform the assignment. Instead of
using xiterator
of each expression, an instance of data_assigner
holds both steppers and makes
them step together.
The computed_assign
method is slightly different from the assign_xexpression
method. After
resizing the lhs member, it checks if some broadcasting is involved. If so, the rhs expression is
evaluated into a temporary and the temporary is assigned to the lhs expression, otherwise rhs is
directly evaluated in lhs. This is because a computed assignment always implies aliasing (meaning
that the lhs is also involved in the rhs): a += b;
is equivalent to a = a + b;
.
The scalar_computed_assign
method simply iterates over the expression and applies the scalar
operation on each value:
template <class Tag> template <class E1, class E2, class F> inline void xexpression_assigner<Tag>::scalar_computed_assign(xexpression<E1>& e1, const E2& e2, F&& f) { E1& d = e1.derived_cast(); std::transform(d.cbegin(), d.cend(), d.begin(), [e2, &f](const auto& v) { return f(v, e2); }); }