---
title: "BNNSGather(_:_:_:_:_:)"
framework: accelerate
role: symbol
role_heading: Function
path: "accelerate/bnnsgather(_:_:_:_:_:)"
---

# BNNSGather(_:_:_:_:_:)

Gathers the elements of a tensor along a single axis.

## Declaration

```swift
func BNNSGather(_ axis: Int, _ input: UnsafePointer<BNNSNDArrayDescriptor>, _ indices: UnsafePointer<BNNSNDArrayDescriptor>, _ output: UnsafeMutablePointer<BNNSNDArrayDescriptor>, _ filter_params: UnsafePointer<BNNSFilterParameters>?) -> Int32
```

## Parameters

- `axis`: The axis along which the operation gathers the indices.
- `input`: A pointer to the input descriptor.
- `indices`: A pointer to the indices descriptor.
- `output`: A pointer to the output descriptor.
- `filter_params`: The filter runtime parameters.

## Discussion

Discussion Use BNNSGather(_:_:_:_:_:) to gather elements — that you specify by index — into an output tensor. In the simplest case, use BNNSGather(_:_:_:_:_:) to gather elements from a 1D vector with indices defined as a 1D vector. The following code gathers the four elements at indices [1, 3, 7, 5]: let values: [Float] = [10, 20, 30, 40, 50, 60, 70, 80] var inputDescriptor = BNNSNDArrayDescriptor.allocate(     initializingFrom: values,     shape: .vector(values.count))

let indices: [Int32] = [1, 3, 7, 5] var indicesDescriptor = BNNSNDArrayDescriptor.allocate(     initializingFrom: indices,     shape: .vector(indices.count))

var outputDescriptor = BNNSNDArrayDescriptor.allocateUninitialized(     scalarType: Float.self,     shape: indicesDescriptor.shape)

let error = BNNSGather(0,                        &inputDescriptor,                        &indicesDescriptor,                        &outputDescriptor,                        nil)

On return, outputDescriptor contains the values [20.0, 40.0, 80.0, 60.0]. BNNSGather(_:_:_:_:_:) supports gathering from a tensor with two or more dimensions using indices defined as a 1D vector. In this case, the indices correspond to the values along an entire axis and the input and output shapes must match. The following code generates a 3 x 4 matrix from the rows of a 3 x 3 matrix: let values: [Float] = [10, 20, 30,                        40, 50, 60,                        70, 80, 90] var inputDescriptor = BNNSNDArrayDescriptor.allocate(     initializingFrom: values,     shape: .matrixRowMajor(3, 3))

let indices: [Int32] = [0, 1, // Elements `0, 1` from row `0` = `10, 20`                         2, 0, // Elements `2, 0` from row `1` = `60, 40`                         1, 1] // Elements `1, 1` from row `2` = `80, 80` var indicesDescriptor = BNNSNDArrayDescriptor.allocate(     initializingFrom: indices,     shape: .matrixRowMajor(2, 3))

var outputDescriptor = BNNSNDArrayDescriptor.allocateUninitialized(     scalarType: Float.self,     shape: indicesDescriptor.shape)

let error = BNNSGather(1, // axis                        &inputDescriptor,                        &indicesDescriptor,                        &outputDescriptor,                        nil) On return, outputDescriptor contains the following values:  [ 10.0, 20.0,    60.0, 40.0,    80.0, 80.0 ] The function returns an error if any of the indices are out of range.

## See Also

### Gather and scatter operations

- [Calculating the dominant colors in an image](accelerate/calculating-the-dominant-colors-in-an-image.md)
- [gather(input:indices:output:axis:filterParameters:)](accelerate/bnns/gather(input:indices:output:axis:filterparameters:).md)
- [gatherND(input:indices:output:filterParameters:)](accelerate/bnns/gathernd(input:indices:output:filterparameters:).md)
- [scatter(input:indices:output:axis:reductionFunction:filterParameters:)](accelerate/bnns/scatter(input:indices:output:axis:reductionfunction:filterparameters:).md)
- [scatterND(input:indices:output:reductionFunction:filterParameters:)](accelerate/bnns/scatternd(input:indices:output:reductionfunction:filterparameters:).md)
- [BNNSGatherND(_:_:_:_:)](accelerate/bnnsgathernd(_:_:_:_:).md)
- [BNNSScatter(_:_:_:_:_:_:)](accelerate/bnnsscatter(_:_:_:_:_:_:).md)
- [BNNSScatterND(_:_:_:_:_:)](accelerate/bnnsscatternd(_:_:_:_:_:).md)