Nest¶
Collection of Ivy functions for nested objects.

ivy.
all_nested_indices
(nest: Iterable, include_nests: bool = False, _index: Optional[List] = None, _base: bool = True) → Union[Iterable, bool][source]¶ Checks the leaf nodes of nested x via function fn, and returns all nest indices where the method evaluates as True.
 Parameters
nest (nest of any) – The nest to check the leaves of.
include_nests (bool, optional) – Whether to also include indices of the nests themselves, not only leaves. Default is False.
_index (list of tuples of indices, do not set) – The indices detected so far. None at the beginning. Used internally, do not set manually.
_base (bool, do not set) – Whether the current function call is the first function call in the recursive stack. Used internally, do not set manually.
 Returns
A set of indices for the nest where the function evaluated as True.

ivy.
copy_nest
(nest: Union[ivy.Array, ivy.NativeArray, Iterable], include_derived: bool = False, to_mutable: bool = False) → Union[ivy.Array, ivy.NativeArray, Iterable][source]¶ Copies a nest deeply, but without copying leaves of the nest, only the nest lists, tuples and dicts are copied.
 Parameters
nest (nested) – The nest to copy.
include_derived (bool, optional) – Whether to also recursive for classes derived from tuple, list and dict. Default is False.
to_mutable (bool, optional) – Whether to convert the nest to a mutable form, changing all tuples to lists. Default is False.
 Returns
The copied nest.

ivy.
index_nest
(nest, index)[source]¶ Index a nested object, using a tuple of indices or keys in the case of dicts.
 Parameters
nest (nested) – The nested object to index.
index (tuple of indices) – A tuple of indices for indexing.

ivy.
map
(fn: Callable, constant: Optional[Dict[str, Any]] = None, unique: Optional[Dict[str, Iterable[Any]]] = None, mean: bool = False) → List[source]¶ Applies a function on each item of an iterable x.
 Parameters
fn (callable) – The function to map onto x.
constant (dict of any, optional) – keyword arguments which remain constant between each function call. Default is None.
unique (dict of iterables of any, optional) – keyword arguments which are unique for each function call. Default is None.
mean (bool, optional) – Whether to compute the mean across the return values, and return this mean. Default is False.
 Returns
x following the applicable of fn to each of it’s iterated items.

ivy.
map_nest_at_index
(nest, index, fn)[source]¶ Map a function to the value of a nested item at a specified index
 Parameters
nest (nested) – The nested object to update.
index (tuple of indices) – A tuple of indices for the index at which to update.
fn (callable) – The function to perform on the nest at the given index.

ivy.
map_nest_at_indices
(nest, indices, fn)[source]¶ Map a function to the values of a nested item at the specified indices
 Parameters
nest (nested) – The nested object to update.
indices (tuple of tuples of indices) – A tuple of tuples of indices for the indices at which to update.
fn (callable) – The function to perform on the nest at the given index.

ivy.
multi_index_nest
(nest, indices)[source]¶ Repeatedly index a nested object, using a tuple of tuples of indices or keys in the case of dicts.
 Parameters
nest (nested) – The nested object to slice.
indices (tuple of tuples of indices) – A tuple of tuples of indices to apply.

ivy.
nested_indices_where
(nest: Iterable, fn: Callable, check_nests: bool = False, _index: Optional[List] = None, _base: bool = True) → Union[Iterable, bool][source]¶ Checks the leaf nodes of nested x via function fn, and returns all nest indices where the method evaluates as True.
 Parameters
nest (nest of any) – The nest to check the leaves of.
fn (callable) – The conditon function, returning True or False.
check_nests (bool, optional) – Whether to also check the nests for the condition, not only nest leaves. Default is False.
_index (list of tuples of indices, do not set) – The indices detected so far. None at the beginning. Used internally, do not set manually.
_base (bool, do not set) – Whether the current function call is the first function call in the recursive stack. Used internally, do not set manually.
 Returns
A set of indices for the nest where the function evaluated as True.

ivy.
nested_map
(x: Union[ivy.Array, ivy.NativeArray, Iterable], fn: Callable, include_derived: bool = False, to_mutable: bool = False, max_depth: Optional[int] = None, depth: int = 0) → Union[ivy.Array, ivy.NativeArray, Iterable][source]¶ Applies a function on x in a nested manner, whereby all dicts, lists and tuples are traversed to their lowest leaves before applying the method and returning x. If x is not nested, the method is applied to x directly.
 Parameters
x (any) – The item to apply the mapped function to.
fn (callable) – The function to map onto x.
include_derived (bool, optional) – Whether to also recursive for classes derived from tuple, list and dict. Default is False.
to_mutable (bool, optional) – Whether to convert the nest to a mutable form, changing all tuples to lists. Default is False.
max_depth (int, optional) – The maximum nested depth to reach. Default is 1. Increase this if the nest is deeper.
depth (int, used internally) – Placeholder for tracking the recursive depth, do not yet this parameter.
 Returns
x following the applicable of fn to it’s nested leaves, or x itself if x is not nested.

ivy.
set_nest_at_index
(nest, index, value)[source]¶ Set the value of a nested item at a specified index
 Parameters
nest (nested) – The nested object to update.
index (tuple of indices) – A tuple of indices for the index at which to update.
value (any) – The new value for updating.

ivy.
set_nest_at_indices
(nest, indices, values)[source]¶ Set the value of a nested item at specified indices with specified values.
 Parameters
nest (nested) – The nested object to update.
indices (tuple of tuples of indices) – A tuple of tuples of indices for the indices at which to update.
values (sequence of any) – The new values for updating.