module FunctionChains

Implements chained functions (composed functions) beyond Base.ComposedFunction.

struct FunctionChains.AsFunction{F} <: Function

Wraps a callable object to make it a Function.

User code should typically not instantiate AsFunction objects directly, but use asfunction(f) instead.

struct FunctionChain{FS}<:Function

Represents a chain of composed functions.

A FunctionChain has a single field fs which may be a tuple, array or generator/iterator of functions.

(fc::FunctionChain)(x) applies the functions in the chain in order of iteration over fc.fs.

Use fchain to construct function chains instead of using the constructor FunctionChain(fs) directly.

∘̂(f, n::Integer)
f∘̂ n

Create a chain of function f repeated n times, with support for n <= 0.

If n > 0 then f∘̂ n behaves like frepeat(f, n). If n == 0 then it returns the identity function and if n < 0 then it behaves like frepeat(InverseFunctions.inverse(f), n).

applyf(f, xs...) = f(xs...)

Function application: Apply a function f to one or multiple arguments.

Primarily useful to broadcast collections of function over collections of arguments, e.g. applyf(fs, as, bs, ...) or to calculate derivatives in respect to function parameters (closure contents), e.g. Zygote.gradient(applyf, f_withargs, xs...).

asfunction(f)::Function
asfunction(f::Function) === f

Wraps a callable f to make it a Function.

If f isa Function, simply returns f. If f is A type (constructor), returns a properly typed function object.

fbcast(f)

Return a broadcasted version of the function f, so that fbcast(f)(A, ...) is semantically equivalent to f.(A, ...).

fbcast(f)(A) is also semantically equivalent to fprod( Fill(f, size(A)) )(A).

Typically returns a Broadcast.BroadcastFunction, but may be specialized to return broadcasted implementations depending on the type of f. For example, fbcast(identity) === identity.

The resulting broadcasted function supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if f does so.

fchain()
fchain(fs)
fchain(fs...)

Construct a function chain of functions fs.

Typically returns a FunctionChain, but may be specialized to return other function chain types for specific types of functions.

fs must be iterable, it may be a tuple, vector, generator, etc. fchain(fs)(x) will apply the functions in fs in order of iteration.

The resulting function chain supports with_intermediate_results, and also supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if all functions in the chain do so.

fcomp()
fcomp(fs)
fcomp(fs...)

Construct a composition of the functions fs that is semantically equivalent to fs[1] ∘ fs[2] ∘ ... and fchain(reverse(fs)).

The resulting function composition supports with_intermediate_results, but note that the intermediate results are in order of function evaluation, not in the order of the functions in fs.

The composition also supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if all functions in the composition do so.

frepeat(f, n::Integer)

Create a chain of function f repeated n times.

See also ∘̂(f, n) for a version that supports n <= 0.

The resulting function chain supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if f does so.

typed_callable(f)

Wraps a callable f in a typed function object if necessary, e.g. if f is a type (constructor).

with_intermediate_results(f, x)

Apply multi-step function f to x and return a collection that contains the intermediate results and the final result.