A high-performance general-purpose compute library

Lookup values of an array by indexing with another array. More...

Functions

AFAPI array lookup (const array &in, const array &idx, const int dim=-1)
 Lookup the values of an input array by indexing with another array. More...
 
AFAPI af_err af_lookup (af_array *out, const af_array in, const af_array indices, const unsigned dim)
 Lookup the values of an input array by indexing with another array. More...
 

Detailed Description

Lookup values of an array by indexing with another array.

Will return an array with the values in the in array from the locations specified in the idx array. The resulting array contains values corresponding to each of the provided indices. Locations of the input data are assumed to be in the range [0, n). Indexing outside of this range will result in mirrored wrap-around behavior.

A simple example of one-dimension indexing can be seen in the following example.

// input array
float in_[5] = {10, 20, 30, 40, 50};
af::array in(5, in_);
// indices to lookup
int idx_[3] = {1, 3, 2};
af::array idx(3, idx_);
af::array indexed = af::lookup(in, idx);
// indexed == { 20, 40, 30 };
A multi dimensional data container.
Definition: array.h:37
AFAPI array lookup(const array &in, const array &idx, const int dim=-1)
Lookup the values of an input array by indexing with another array.

Index locations can also be out of bounds.

// input array
float in_[5] = {10, 20, 30, 40, 50};
af::array in(5, in_);
// indexing past end of array
int idx_outofbounds_p_[8] = {4, 5, 6, 7, 8, 9, 10, 11};
af::array idx_outofbounds_p(8, idx_outofbounds_p_);
// and indexing before beginning of array
int idx_outofbounds_n_[8] = {0, -1, -2, -3, -4, -5, -6, -7};
af::array idx_outofbounds_n(8, idx_outofbounds_n_);
af::array indexed_out_of_bounds_pos = af::lookup(in, idx_outofbounds_p);
af::array indexed_out_of_bounds_neg = af::lookup(in, idx_outofbounds_n);
// indexed_out_of_bounds_pos == { 50, 50, 40, 30, 20, 10, 50, 40 }
// indexed_out_of_bounds_neg == { 10, 10, 20, 30, 40, 50, 10, 20 }

The axis along which to query the indices can also be specified. The resulting array will be of the same size as the input, except for the queried dimension which will match the number of elements in the index array.

// constant input data
float input_vals[9] = {10, 20, 30, 11, 21, 31, 12, 22, 32};
array input(3, 3, input_vals);
// {{10 11 12},
// {20 21 22},
// {30 31 32}},
// indices to lookup
int idx_[6] = {0, 0, 1, 1, 2, 2};
af::array idx(6, idx_);
// will look up all indices along specified dimension
af::array indexed = af::lookup(input, idx); //(dim = 0)
// indexed == { 10, 11, 12,
// 10, 11, 12,
// 20, 21, 22,
// 20, 21, 22,
// 30, 31, 32,
// 30, 31, 32 };
af::array indexed_dim1 = af::lookup(input, idx, 1);
// indexed_dim1 == { 10, 10, 11, 11, 12, 12,
// 20, 20, 21, 21, 22, 22,
// 30, 30, 31, 31, 32, 32 };

Function Documentation

◆ af_lookup()

AFAPI af_err af_lookup ( af_array out,
const af_array  in,
const af_array  indices,
const unsigned  dim 
)

Lookup the values of an input array by indexing with another array.

Parameters
[out]outoutput array containing values of in at locations specified by indices
[in]inis the input array that will be queried
[in]indicesare the lookup indices
[in]dimspecifies the dimension for indexing

◆ lookup()

AFAPI array lookup ( const array in,
const array idx,
const int  dim = -1 
)

Lookup the values of an input array by indexing with another array.

Parameters
[in]inis the input array that will be queried
[in]idxare the lookup indices
[in]dimspecifies the dimension for indexing
Returns
an array containing values of in at locations specified by index