A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Functions
lookup
ArrayFire Functions | ArrayFire Functions by Category » Functions to create and modify Arrays » Assignment & Indexing operation on arrays

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.
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.

## 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 )

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

Parameters

  [in] | in | is the input array that will be queried
  [in] | idx | are the lookup indices
  [in] | dim | specifies the dimension for indexing

Returns
  an array containing values of `in` at locations specified by `index`