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 };
 

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]	out	output array containing values of `in` at locations specified by `indices`
[in]	in	is the input array that will be queried
[in]	indices	are the lookup indices
[in]	dim	specifies the dimension for indexing

◆ lookup()

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