Manipulation Functions ¶
Array API specification for manipulating arrays.
A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.

Positional parameters must be positionalonly parameters. Positionalonly parameters have no externallyusable name. When a function accepting positionalonly parameters is called, positional arguments are mapped to these parameters based solely on their order.

Optional parameters must be keywordonly arguments.

Unless stated otherwise, functions must adhere to the type promotion rules defined in Type Promotion Rules .
Objects in API ¶
concat(arrays, /, *, axis=0) ¶
Joins a sequence of arrays along an existing axis.
Parameters ¶

arrays : Union[Tuple[ <array>, … ], List[ <array> ] ]

input arrays to join. The arrays must have the same shape, except in the dimension specified by
axis
.


axis : Optional[ int ]

axis along which the arrays will be joined. If
axis
isNone
, arrays must be flattened before concatenation. Ifaxis
is negative, the function must determine the axis along which to join by counting from the last dimension. Default:0
.

Returns ¶

out : <array>

an output array containing the concatenated values. If the input arrays have different data types, normal type promotion rules must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays.
Note
This specification leaves type promotion between data type families (i.e.,
intxx
andfloatxx
) unspecified.

expand_dims(x, /, axis) ¶
Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by
axis
.
Parameters ¶

x : <array>

input array.


axis : int

axis position. Must follow Python’s indexing rules: zerobased and negative indices must be counted backward from the last dimension. If
x
has rankN
, a validaxis
must reside on the interval[N1, N+1]
. AnIndexError
exception must be raised if provided an invalidaxis
position.

Returns ¶

out : <array>

an expanded output array having the same data type as
x
.

flip(x, /, *, axis=None) ¶
Reverses the order of elements in an array along the given axis. The shape of the array must be preserved.
Parameters ¶

x : <array>

input array.


axis : Optional[ Union[ int, Tuple[ int, … ] ] ]

axis (or axes) along which to flip. If
axis
isNone
, the function must flip all input array axes. Ifaxis
is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default:None
.

Returns ¶

out : <array>

an output array having the same data type and shape as
x
and whose elements, relative tox
, are reordered.

permute_dims(x, /, axes) ¶
Permutes the axes (dimensions) of an array
x
.
Parameters ¶

x : <array>

input array.


axes : Tuple[ int, … ]

tuple containing a permutation of
(0, 1, ..., N1)
whereN
is the number of axes (dimensions) ofx
.

Returns ¶

out : <array>

an array containing the axes permutation. The returned array must have the same data type as
x
.

reshape(x, /, shape) ¶
Reshapes an array without changing its data.
Parameters ¶

x : <array>

input array to reshape.


shape : Tuple[ int, … ]

a new shape compatible with the original shape. One shape dimension is allowed to be
1
. When a shape dimension is1
, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions.

Returns ¶

out : <array>

an output array having the same data type, elements, and underlying element order as
x
.

roll(x, /, shift, *, axis=None) ¶
Rolls array elements along a specified axis. Array elements that roll beyond the last position are reintroduced at the first position. Array elements that roll beyond the first position are reintroduced at the last position.
Parameters ¶

x : <array>

input array.


shift : Union[ int, Tuple[ int, … ] ]

number of places by which the elements are shifted. If
shift
is a tuple, thenaxis
must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element inshift
. Ifshift
is anint
andaxis
a tuple, then the sameshift
must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension ofaxis
. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension ofaxis
.


axis : Optional[ Union[ int, Tuple[ int, … ] ] ]

axis (or axes) along which elements to shift. If
axis
isNone
, the array must be flattened, shifted, and then restored to its original shape. Default:None
.

Returns ¶

out : <array>

an output array having the same data type as
x
and whose elements, relative tox
, are shifted.

squeeze(x, /, axis) ¶
Removes singleton dimensions (axes) from
x
.
Parameters ¶

x : <array>

input array.


axis : Union[ int, Tuple[ int, … ] ]

axis (or axes) to squeeze. If a specified axis has a size greater than one, a
ValueError
must be raised.

Returns ¶

out : <array>

an output array having the same data type and elements as
x
.

stack(arrays, /, *, axis=0) ¶
Joins a sequence of arrays along a new axis.
Parameters ¶

arrays : Union[Tuple[ <array>, … ], List[ <array> ] ]

input arrays to join. Each array must have the same shape.


axis : int

axis along which the arrays will be joined. Providing an
axis
specifies the index of the new axis in the dimensions of the result. For example, ifaxis
is0
, the new axis will be the first dimension and the output array will have shape(N, A, B, C)
; ifaxis
is1
, the new axis will be the second dimension and the output array will have shape(A, N, B, C)
; and, ifaxis
is1
, the new axis will be the last dimension and the output array will have shape(A, B, C, N)
. A validaxis
must be on the interval[N, N)
, whereN
is the rank (number of dimensions) ofx
. If provided anaxis
outside of the required interval, the function must raise an exception. Default:0
.

Returns ¶

out : <array>

an output array having rank
N+1
, whereN
is the rank (number of dimensions) ofx
. If the input arrays have different data types, normal type promotion rules must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays.Note
This specification leaves type promotion between data type families (i.e.,
intxx
andfloatxx
) unspecified.
