Jive reference manual
Functions
Array selections

Functions for selecting non-regular sections of an array. More...

Functions

template<class T , class I >
ArrayExpr< T, 1 > jem::select (const ArrayExpr< T, 1 > &a, const I &idx)
 Selects a section of a one-dimensional array. More...
 
template<class T , class I , class J >
ArrayExpr< T, 2 > jem::select (const ArrayExpr< T, 2 > &a, const I &idx, const J &jdx)
 Selects a section of a two-dimensional array. More...
 
template<class T , class I , class J , class K >
ArrayExpr< T, 3 > jem::select (const ArrayExpr< T, 3 > &a, const I &idx, const J &jdx, const K &kdx)
 Selects a section of a three-dimensional array. More...
 
template<class T , class I , class J , class K , class L >
ArrayExpr< T, 4 > jem::select (const ArrayExpr< T, 4 > &a, const I &idx, const J &jdx, const K &kdx, const L &ldx)
 Selects a section of a four-dimensional array. More...
 

Detailed Description

#include <jem/base/array/select.h>

This header file exports the select() function that can be used to select non-regular, rectangular sections of Array objects and array expressions. This function is especially handy when writing code that uses an index array to access the elements in an Array or an array expression.

An example:

Array<double,2> matrix ( 10, 100 );
Array<int> index ( 3 );
// ... (initialize the array matrix) ...
index[0] = 2; index[1] = 6; index[2] = 7;
select( matrix, index, slice(ALL) ) = 1.0;

The above select statement is equivalent with:

int i, j;
for ( j = 0; j < 100; j++ )
{
for ( i = 0; i < 3; i++ )
{
matrix( index[i], j ) = 1.0;
}
}

Although the select function provides a similar functionality as the slice operators of the Array class, they differ in three ways. First, the select function returns array expressions whereas the overloaded slice operators return Array objects. Second, the select function can be used to select non-regular sections of an array, while the slice operators can only be used to select regular sections of an array. Third, the select function always returns an array expression that has the same rank as the original array. The slice operators, on the other hand, can return an Array object that has a lower rank than the original array.

Note that the select() function is also available through the general header file <jem/base/Array.h>.

See also
Array slices

Function Documentation

template<class T , class I >
ArrayExpr<T,1> jem::select ( const ArrayExpr< T, 1 > &  a,
const I &  idx 
)

Returns a one-dimensional array expression representing a rectangular section of the one-dimensional array expression a. The parameter idx specifies which elements are selected. This parameter can be a Slice instance (or an instance of a class derived from Slice), an Array<int> object, or a one-dimensional array expression of which the elements have type int. If the parameter idx is a Slice, this function returns an array expression representing the elements selected by the Slice object. Otherwise, this function returns an array expression representing the elements indexed by the array object or the array expression idx.

The returned array expression has the same flavor as the parameter a. That is, the returned expression is an rvalue expression if a is an rvalue expression, and an lvalue expression if a is an lvalue expression. The size of the returned expression is equal to the number of elements selected by the parameter idx.

Here is an example:

Array<float> a ( 30 );
Array<float> b ( 20 );
Array<int> idx ( 10 );
// init a, b, idx ...
select( a, idx + 2 ) = select( b, slice(2,12) );

The last statement is equivalent with:

int i;
for ( i = 0; i < 10; i++ )
{
a[ idx[i] + 2 ] = b[ i + 2 ];
}
Parameters
a- an array expression or an Array object.
idx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
Precondition
If idx is an array or an array expression, then:
idx[i] >= 0 && idx[i] < a.size()
for all valid indices i.
Returns
A one-dimensional array expression that represents a rectangular section of the array expression a.
template<class T , class I , class J >
ArrayExpr<T,2> jem::select ( const ArrayExpr< T, 2 > &  a,
const I &  idx,
const J &  jdx 
)

Returns a two-dimensional array expression representing a rectangular section of the two-dimensional array expression a. The parameters idx and jdx specify the selected array indices in the first and second dimension, respectively. Each parameter can be a Slice instance (or an instance of a class derived from Slice), an Array<int> object, or a one-dimensional array expression of which the elements have type int.

The returned array expression has the same flavor as the parameter a. That is, the returned expression is an rvalue expression if a is an rvalue expression, and an lvalue expression if a is an lvalue expression. The returned expression has shape (m,n) with m the number of indices selected by idx, and n the number of indices selected by jdx.

Here is an example:

Array<float,2> a ( 40, 40 );
Array<float,2> b ( 30, 30 );
Array<int> idx ( 20 );
Array<int> jdx ( 10 );
// init a, b, idx, jdx ...
select( a, idx + 2, slice(2,12) ) = select( b, slice(2,22), 2 * jdx );

The last statement is equivalent with:

int i, j;
for ( j = 0; j < 10; j++ )
{
for ( i = 0; i < 20; i++ )
{
a( idx[i] + 2, j + 2 ) = b( i + 2, 2 * jdx[j] );
}
}
Parameters
a- an array expression or an Array object.
idx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
jdx- a Slice, an Array<int> object, or array expression of which the elements have type int.
Precondition
If idx is an array or array expression, then:
idx[i] >= 0 && idx[i] < a.shape()[0]
for all valid indices i;
and if jdx is an array or array expression, then:
jdx[i] >= 0 && jdx[i] < a.shape()[1]
for all valid indices i.
Returns
A two-dimensional array expression that represents a rectangular section of the array expression a.
template<class T , class I , class J , class K >
ArrayExpr<T,3> jem::select ( const ArrayExpr< T, 3 > &  a,
const I &  idx,
const J &  jdx,
const K &  kdx 
)

Returns a three-dimensional array expression representing a rectangular section of the three-dimensional array expression a. The parameters idx, jdx and kdx specify the selected array indices in the first, second and third dimension, respectively. Each parameter can be a Slice instance (or an instance of a class derived from Slice), an Array<int> object, or a one-dimensional array expression of which the elements have type int.

The returned array expression has the same flavor as the parameter a. That is, the returned expression is an rvalue expression if a is an rvalue expression, and an lvalue expression if a is an lvalue expression. The returned expression has shape (m,n,p) with m, n and p the number of indices selected by idx, jdx and kdx, respectively.

Here is an example:

Array<float,2> a ( 50, 50, 50 );
Array<float,2> b ( 40, 40, 40 );
Array<int> idx ( 30 );
Array<int> jdx ( 20 );
Array<int> kdx ( 10 );
// init a, b, idx, jdx, kdx ...
select( a, idx, slice(2,22), kdx + 2 ) =
select( b, slice(2,32), jdx, kdx - 2 );

The last statement is equivalent with:

int i, j, k;
for ( k = 0; k < 10; k++ )
{
for ( j = 0; j < 20; j++ )
{
for ( i = 0; i < 30; i++ )
{
a( idx[i], j + 2, kdx[k] + 2 ) =
b( i + 2, jdx[j], kdx[k] - 2 );
}
}
}
Parameters
a- an array expression or an Array object.
idx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
jdx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
kdx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
Precondition
If idx is an array or array expression, then:
idx[i] >= 0 && idx[i] < a.shape()[0]
for all valid indices i;
and if jdx is an array or array expression, then:
jdx[i] >= 0 && jdx[i] < a.shape()[1]
for all valid indices i;
and if kdx is an array or array expression, then:
kdx[i] >= 0 && kdx[i] < a.shape()[2]
for all valid indices i.
Returns
A three-dimensional array expression that represents a rectangular section of the array expression a.
template<class T , class I , class J , class K , class L >
ArrayExpr<T,4> jem::select ( const ArrayExpr< T, 4 > &  a,
const I &  idx,
const J &  jdx,
const K &  kdx,
const L &  ldx 
)

Returns a four-dimensional array expression representing a rectangular section of the four-dimensional array expression a. The parameters idx, jdx, kdx and ldx specify the selected array indices in the first, second, third and fourth dimension, respectively. Each parameter can be a Slice instance (or an instance of a class derived from Slice), an Array<int> object, or a one-dimensional array expression of which the elements have type int.

The returned array expression has the same flavor as the parameter a. That is, the returned expression is an rvalue expression if a is an rvalue expression, and an lvalue expression if a is an lvalue expression. The returned expression has shape (m,n,p,q) with m, n, p and q the number of indices selected by idx, jdx, kdx, ldx, respectively.

Here is an example:

Array<float,2> a ( 60, 60, 60, 60 );
Array<float,2> b ( 50, 50, 50, 50 );
Array<int> idx ( 40 );
Array<int> jdx ( 30 );
Array<int> kdx ( 20 );
Array<int> ldx ( 10 );
// init a, b, idx, jdx, kdx, ldx ...
select( a, idx, slice(2,32), kdx + 2, slice(2,12) ) =
select( b, slice(2,42), jdx, kdx - 2, 2 * ldx + 2 );

The last statement is equivalent with:

int i, j, k, l;
for ( l = 0; l < 10; l++ )
{
for ( k = 0; k < 20; k++ )
{
for ( j = 0; j < 30; j++ )
{
for ( i = 0; i < 40; i++ )
{
a( idx[i], j + 2, kdx[k] + 2, l + 2 ) =
b( i + 2, jdx[j], kdx[k] - 2, 2 * ldx[l] + 2 );
}
}
}
}
Parameters
a- an array expression or an Array object.
idx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
jdx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
kdx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
ldx- a Slice, an Array<int> object, or an array expression of which the elements have type int.
Precondition
If idx is an array or array expression, then:
idx[i] >= 0 && idx[i] < a.shape()[0]
for all valid indices i;
and if jdx is an array or array expression, then:
jdx[i] >= 0 && jdx[i] < a.shape()[1]
for all valid indices i;
and if kdx is an array or array expression, then:
kdx[i] >= 0 && kdx[i] < a.shape()[2]
for all valid indices i;
and if kdx is an array or array expression, then:
ldx[i] >= 0 && ldx[i] < a.shape()[3]
for all valid indices i;
Returns
A four-dimensional array expression that represents a rectangular section of the array expression a.
Generated on Fri Jun 19 2015 09:52:49 by Doxygen