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.