Table of Contents
Element-wise selectors do not actually modify the logical domain or the access order of a data, but instead, they apply some operation on-the-fly to each element at the moment when it is requested. Two such selectors are defined at present.
Template parameters : none.
Public members and typedefs:
ncomponents_t component |
0-based index of the vector component to select. |
A
component_selector
is used to select a single component
in a vector-valued array.
The value_type
and reference
types
are changed accordingly, and all the rest remains unchanged.
Template parameters :
template<class T> class UnaryOperator |
The unary operator template, parametrized by its argument type. |
Public members and typedefs: none.
Aunary_operator_selector
applies the given UnaryOperator
on-the-fly
to each element when it is accessed.
The value_type
of the base selector should be a valid template parameter for UnaryOperator
,
and the resulting class should be DefaultConstructible.
For operators that are not DefaultConstructible (for example, raising a number to some undefined integer power),
another mechanism is provided by the item unary_operator_with_parameter_item
,
whose specifications are:
Template parameters :
class UnaryOperator |
The class of the unary operator to apply. |
Public members and typedefs:
UnaryOperator op |
The instance of UnaryOperator to apply. |
Template parameters :
class equations_directions |
MPL sequence of rank_t constants specifying the fixed directions which parametrize the location of the subspace. |
Public members and typedefs:
static const rank_t equations_v = boost::mpl::size<equations_directions>::value |
Number of equations defining the subspace. |
typedef boost::array<size_t,equations_v> coordinates_type |
Type of array defining subspace position. |
coordinates_type coordinates | Coordinates of selected subspace. |
An affine_subspace_selector
makes a cut in the input selector,
such that the indices along certain directions are kept fixed to predefined values, while the indices
along the remaining directions continue to vary.
For those familiar with Matlab, this corresponds to syntaxes of the type A(:,:,i1,:,i2,:)
,
where A
is here a 6D array.
The only difference with Matlab is that affine_subspace_selector
actually
decreases the rank of its output compared to its input.
Here is a simple usage example.
Assume that a4d
is a 4-D array or selector whose domain size is [5,6,7,8].
typedef boost::mpl::vector_c<rank_t,1,2> equations_type; typedef cartesian::affine_subspace_item<equations_type> item_type; boost::array<size_t,1> coordinates = {{3,1}}; result_of::select<a4d_type,item_type>::type s = select(a4d,item_type(coordinates));
As a result, s
is a 2-D selector whose domain size is [5,8],
which points to the elements of a4d
having their second and third indices
respectively equal to 3 and 1.
Template parameters :
class DimOrder |
An MPL sequence of rank_t constants defining the new order for the dimensions. |
Public members and typedefs: none.
This selector is a generalization of logical array transposition: it
provides access to an array as if the order of its dimensions was permuted.
The size of the DimOrder
sequence should match the rank of the input array.
In the example below, a4d
is a 4-D array,
and b4d
is a view of a4d
where
the first and second dimension have been exchanged:
typedef boost::mpl::vector_c<rank_t,1,0,2,3> dim_order_type; typedef cartesian::dim_order_item<dim_order_type> item_type; result_of::select<a4d_type,item_type>::type b4d = select(a4d,item_type());
Template parameters :
rank_t major |
The new major direction in the array. |
Public members and typedefs: none.
A special case of dim_order_selector
, which circularly shifts
the directions so that the one specified by the template parameter major
becomes the first one.
Template parameters :
rank_t mirror_dir |
The direction in which the mirror operation should be applied. |
Public members and typedefs: none.
mirror_selector
provides access to an array as if the indices
in one of its directions were reversed.
Template parameters :
rank_t rank |
The rank of the array in which the subcube will be selected. |
Public members and typedefs:
boost::array<size_t,rank> left |
The number of elements to leave out of the subcube before the retained range. |
boost::array<size_t,rank> right |
The number of elements to leave out of the subcube after the retained range. |
Thanks to this selector, a sub-cube can be selected in the input array, which means that the indices are restricted to vary within a certain range in each direction. The resulting selection has the same rank as the input. The ranges are defined indirectly by the numbers of indices of the input which are left out before them and after them, rather than by their endpoints. Thanks to this convention, there is a natural default behavior, which consists in keeping everything.
For example, if a subcube_selector
with the following parameter values:
boost::array<size_t,3> left = {{ 2,1,0 }} ; boost::array<size_t,3> right = {{ 0,2,0 }} ;
is applied to an array of rank 3, the first direction will get cropped of its 2 leading indices, the second one will get cropped of its first index and of its two tailing ones, and the third direction will be left untouched.
Note that attempting to construct a subcube_selector
with parameters
that would lead to an ill-defined range of indices (that is, if the sum left + right
is bigger than the size of the input array) results in an empty selector.
Template parameters :
rank_t shrink1 |
First direction to be restricted. |
rank_t shrink2 |
Second direction to be restricted. |
Public members and typedefs:
size_t left1 |
Number of indices to be left out before the retained range in the direction shrink1 . |
size_t right1 |
Number of indices to be left out after the retained range in the direction shrink1 . |
size_t left2 |
Number of indices to be left out before the retained range in the direction shrink2 . |
size_t right2 |
Number of indices to be left out after the retained range in the direction shrink2 . |
subrectangle_selector
is a special case of subcube_selector
for which only two directions are affected.
To facilitate block-wise matrix manipulations,
the subrectangle_selector
class defines several additional methods,
named restrict_left1
, restrict_right1
,
translate1
, restrict_left2
, restrict_right2
,
translate2
, restrict_range1
and restrict_range2
.
All the restrict*
functions have the following signature:
subrectangle_selector subrectangle_selector::restrict_left1(size_t amount);
They construct a new selector with the same parameters except that the
quantity amount
is added to the corresponding parameter
(respectively: left1, right1, left2 or right2).
The translate*
functions have the following signature:
subrectangle_selector subrectangle_selector::translate1(ptrdiff_t amount);
In the new selector, the whole selection is translated by the given amount.
Finally, the restrict_range*
functions have the signature
subrectangle_selector subrectangle_selector::restrict_range1(size_t left, size_t right);
and they result in selection, as if a new subrectangle_selector
with
the given parameters left/right
was extracted out
of the domain of the initial one.
Template parameters :
rank_t shrink_dir |
Direction to be restricted. |
Public members and typedefs:
size_t left |
Number of indices to be left out before the retained range in the direction shrink_dir . |
size_t right |
Number of indices to be left out after the retained range in the direction shrink_dir . |
This is an even further simplification of subcube_selector
,
which acts only along one direction.
The same kind of utility methods as for subrectangle_selector
also exist,
except that they are defined without the 1/2 suffixes.
Template parameters : none.
Public members and typedefs:
unsigned int scale |
The scale to be selected. |
This selector works on zig-zag arrays, which have been implemented only in 1D in the present version of the SPAL. It extracts the elements corresponding to a fixed scale in the multi-resolution hierarchical structure of the zig-zag array.
Note that random access is not implemented for this selector,
and the member function at
will systematically throw.
FIXME : missing documentation about iterator.