folding

Folding and Accumulating

Functions to reduce and accumulate items from iterables.

pythonic_fp.iterables.folding.accumulate(iterable: Iterable, f: Callable[[L, D], L], initial: L | NoValue = NoValue()) → Iterator

accumulate

Returns an iterator of partially folded items.

param iterable:

Iterable to be folded.

param f:

Two parameter function, first parameter is for the accumulator.

param initial:

Optional initial item to start fold.

yields:

The intermediate folded items.

Note

A pure Python implementation of the standard library’s itertools.accumulate

  • function f does not default to addition (for typing flexibility)

  • begins accumulation with an optional initial item

pythonic_fp.iterables.folding.reduce_left(iterable: Iterable, f: Callable[[D, D], D]) → D | Never

reduce left

Fold an iterable left with a function.

param iterable:

Iterable to be reduced (folded).

param f:

Two parameter function, first parameter is for the accumulator.

return:

Reduced item from the iterable.

raises StopIteration:

When called on an empty iterable.

raises Exception:

Does not catch any exceptions from f.

Warning

  • never returns if given an infinite iterable

  • does not catch or re-raise exceptions raised by f

pythonic_fp.iterables.folding.fold_left(iterable: Iterable, f: Callable[[L, D], L], initial: L) → L | Never

fold left

Fold an iterable left with a function and initial item.

  • not restricted to __add__ for the folding function

  • initial item is required, does not default to 0

  • handles non-numeric data just find

param iterable:

Iterable to be folded.

param f:

Two parameter function, first parameter is for the accumulator.

param initial:

Mandatory initial item to start fold

return:

The folded item.

Warning

  • never returns if given an infinite iterable

  • does not catch or re-raises exceptions raised by f

pythonic_fp.iterables.folding.maybe_fold_left(iterable: Iterable, f: Callable[[L, D], L], initial: L | NoValue = NoValue()) → MayBe | Never

maybe fold left

Folds an iterable left with an “optional” initial item.

  • when an initial item is not given then L = D

  • if iterable empty and no initial item given, return MayBe()

param iterable:

The iterable to be folded.

param f:

First argument is for the accumulator.

param initial:

Mandatory initial item to start fold.

return:

MayBe of a successfully folded item, otherwise returns MayBe().

Warning

  • never returns if given an infinite iterable

  • any exception f raises is thrown away

pythonic_fp.iterables.folding.sc_reduce_left(iterable: Iterable, f: Callable[[D, D], D], start: Callable[[D], bool] = lambda d: ..., stop: Callable[[D], bool] = lambda d: ..., include_start: bool = True, include_stop: bool = True) → tuple[MayBe, Iterator]

short circuit reduce left

Short circuit version of a left fold.

param iterable:

Iterable to be reduced from the left.

param f:

Two parameter function, first parameter is for the accumulator.

param start:

Delay starting the fold until it returns true.

param stop:

Prematurely stop the fold when it returns true.

param include_start:

If true, include starting item in fold.

param include_stop:

If true, include stopping item in fold.

return:

Tuple of a MayBe of the folded item and iterator of remaining iterables.

Note

Behavior for default arguments will

  • left reduce finite iterable

  • start folding immediately

  • continue folding until end (of a possibly infinite iterable)

Tip

Useful for infinite iterables when Callable stop is provided.

pythonic_fp.iterables.folding.sc_reduce_right(iterable: Iterable, f: Callable[[D, D], D], start: Callable[[D], bool] = lambda d: ..., stop: Callable[[D], bool] = lambda d: ..., include_start: bool = True, include_stop: bool = True) → tuple[MayBe, Iterator]

short circuit reduce right

Short circuit version of a right fold.

param iterable:

Iterable to be reduced from the right.

param f:

Two parameter function, second parameter is for the accumulator.

param start:

Delay starting the fold until it returns true.

param stop:

Prematurely stop the fold when it returns true.

param include_start:

If true, include starting item.

param include_stop:

If true, include stopping item in fold.

return:

Tuple of a MayBe of the folded item and iterator of remaining iterables.

Note

Behavior for default arguments will

  • right reduce finite iterable

  • start folding at end (of a possibly infinite iterable)

  • continue reducing right until beginning

Tip

Useful for infinite and non-reversible iterables.