io.atlassian.fugue

Class Functions

java.lang.Object

io.atlassian.fugue.Functions

public class Functions
extends Object

Utility methods for Functions

Note that this class defines Partial Functions to be functions that return an Option of the result type, and has some methods for creating them.

Since:

1.1

Method Summary

Modifier and Type	Method and Description
static <A,B,C> Function<C,B>	ap(Function<C,A> ca, Function<C,Function<A,B>> cab) Performs function application within a higher-order function (applicative functor pattern).
static <A,B> Function<Function<A,B>,B>	apply(A arg) Function that takes another function and applies it to the argument.
static <A,B> Function<Function<A,B>,B>	apply(Supplier<A> lazyA) Function that takes another function and applies it to the argument supplied by the parameter.
static <A,B,C> Function<A,C>	compose(Function<? super B,? extends C> g, Function<? super A,? extends B> f) Returns the composition of two functions.
static <A,B,C> Function<A,Option<C>>	composeOption(Function<? super B,? extends Option<? extends C>> bc, Function<? super A,? extends Option<? extends B>> ab) Compose two PartialFunctions into one.
static <A,B> Function<A,B>	constant(B constant) Create a function ignores it's input an produces a constant value
static <A,B,C> Function<A,Function<B,C>>	curried(BiFunction<A,B,C> f2) Transforms a function that takes 2 arguments into a function that takes the first argument and return a new function that takes the second argument and return the final result.
static <A,B,C> Function<B,Function<A,C>>	flip(Function<A,Function<B,C>> f2) Transforms a function from A -> (B -> C) into a function from B -> (A -> C).
static <F,T> T	fold(BiFunction<? super T,F,T> f, T zero, Iterable<? extends F> elements) Apply f to each element in elements, with each application using the result of the previous application as the other argument to f.
static <F,S,T extends S> T	fold(Function<Pair<S,F>,T> f, T zero, Iterable<? extends F> elements) Apply f to each element in elements, with each application using the result of the previous application as the other argument to f.
static <A,B> Function<A,Option<B>>	forMap(Map<A,B> map) Create a function that performs a map lookup returning None for null If you do not need a nondefaulted return result using a method reference is preferred map::get
static <A,B> Function<A,B>	forMapWithDefault(Map<A,B> map, B defaultValue) Create a function that performs a map lookup supplying a default value when a Map#get returns null If you do not need a defaulted return result using a method reference is preferred map::get
static <D> Function<D,Unit>	fromConsumer(Consumer<D> consumer) Get a function (with Unit return type) that calls the consumer for all inputs.
static <A> Function<A,A>	identity() Returns the identity function.
static <A,B> Function<A,Option<B>>	isInstanceOf(Class<B> cls) Partial Function that does a type check and matches if the value is of the right type.
static <A,B> Function<A,Option<B>>	mapNullToOption(Function<? super A,? extends B> f) Maps a function that returns nulls into a Partial function that returns an Option of the result.
static <A,B> Function<A,Option<B>>	matches(Function<? super A,? extends Option<? extends B>> f1, Function<? super A,? extends Option<? extends B>> f2) Creates a stack of matcher functions and returns the first result that matches.
static <A,B> Function<A,Option<B>>	matches(Function<? super A,? extends Option<? extends B>> f1, Function<? super A,? extends Option<? extends B>> f2, Function<? super A,? extends Option<? extends B>> f3) Creates a stack of matcher functions and returns the first result that matches.
static <A,B> Function<A,Option<B>>	matches(Function<? super A,? extends Option<? extends B>> f1, Function<? super A,? extends Option<? extends B>> f2, Function<? super A,? extends Option<? extends B>> f3, Function<? super A,? extends Option<? extends B>> f4) Creates a stack of matcher functions and returns the first result that matches.
static <A,B> Function<A,Option<B>>	matches(Function<? super A,? extends Option<? extends B>> f1, Function<? super A,? extends Option<? extends B>> f2, Function<? super A,? extends Option<? extends B>> f3, Function<? super A,? extends Option<? extends B>> f4, Function<? super A,? extends Option<? extends B>> f5, Function<? super A,? extends Option<? extends B>>... fs) Creates a stack of matcher functions and returns the first result that matches.
static <A> Function<A,Option<A>>	nullToOption() Function that turns null inputs into a none, and not-null inputs into some.
static <A,B> Function<A,Option<B>>	partial(Predicate<? super A> p, Function<? super A,? extends B> f) Create a PartialFunction from a Predicate and a Function.
static <A,B,C> BiFunction<A,B,C>	toBiFunction(Function<Pair<A,B>,C> fpair) Converts a function that takes a pair of arguments to a function that takes two arguments
static <A,B> Function<A,B>	weakMemoize(Function<A,B> f) Takes a Function and memoizes (caches) the result for each input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

compose

public static <A,B,C> Function<A,C> compose(Function<? super B,? extends C> g,
                                            Function<? super A,? extends B> f)

Returns the composition of two functions. For f: A->B and g: B->C, composition is defined as the function h such that h(a) == g(f(a)) for each a.

Type Parameters:

A - The start type

B - The intermediate type

C - The finished type

Parameters:

g - the second function to apply, must not be null

f - the first function to apply, must not be null

Returns:

the composition of f and g

See Also:

function composition

ap

public static <A,B,C> Function<C,B> ap(Function<C,A> ca,
                                       Function<C,Function<A,B>> cab)

Performs function application within a higher-order function (applicative functor pattern).

Parameters:

ca - A function to apply within a higher-order function.

cab - The higher-order function to apply a function to.

Returns:

A new function after applying the given higher-order function to the given function.

Since:

4.0

fold

public static <F,T> T fold(BiFunction<? super T,F,T> f,
                           T zero,
                           Iterable<? extends F> elements)

Apply f to each element in elements, with each application using the result of the previous application as the other argument to f. zero is used as the first 'result' value. The final result is returned.

Type Parameters:

F - the element type

T - the final result type

Parameters:

f - the function to apply to all the elements

zero - the starting point for the function

elements - the series of which each element will be accumulated into a result

Returns:

the result of accumulating the application of f to all elements

Since:

1.1

fold

public static <F,S,T extends S> T fold(Function<Pair<S,F>,T> f,
                                       T zero,
                                       Iterable<? extends F> elements)

Apply f to each element in elements, with each application using the result of the previous application as the other argument to f. zero is used as the first 'result' value. The final result is returned.

Type Parameters:

F - the element type

S - the accumulator function input type

T - the return result type

Parameters:

f - the function to apply to all elements

zero - the starting point for the function

elements - the series of which each element will be accumulated into a result

Returns:

the result of accumulating the application of f to all elements

Since:

1.1

apply

public static <A,B> Function<Function<A,B>,B> apply(A arg)

Function that takes another function and applies it to the argument.

Type Parameters:

A - the argument and function input type

B - the result type

Parameters:

arg - the argument that will be applied to any input functions

Returns:

a function that takes a function from A to B , applies the arg and returns the result

Since:

1.1

apply

public static <A,B> Function<Function<A,B>,B> apply(Supplier<A> lazyA)

Function that takes another function and applies it to the argument supplied by the parameter.

Type Parameters:

A - the type of the argument supplied, and the function input type

B - the result type of the function

Parameters:

lazyA - the supplier of the argument that will be applied to any input functions

Returns:

a function that takes a function from A to B, applies the argument from the supplier and returns the result

Since:

2.0

isInstanceOf

public static <A,B> Function<A,Option<B>> isInstanceOf(Class<B> cls)

Partial Function that does a type check and matches if the value is of the right type.

Type Parameters:

A - the input type

B - the type we expect it to be

Parameters:

cls - the type to check against, must not be null

Returns:

a function that returns a Some with the value if of the right type otherwise a None

Since:

1.2

partial

public static <A,B> Function<A,Option<B>> partial(Predicate<? super A> p,
                                                  Function<? super A,? extends B> f)

Create a PartialFunction from a Predicate and a Function.

Type Parameters:

A - the input type

B - the output type

Parameters:

p - the predicate to test the value against, must not be null

f - the function to apply if the predicate passes, must not be null

Returns:

a PartialFunction that tests the supplied predicate before applying the function.

Since:

1.2

composeOption

public static <A,B,C> Function<A,Option<C>> composeOption(Function<? super B,? extends Option<? extends C>> bc,
                                                          Function<? super A,? extends Option<? extends B>> ab)

Compose two PartialFunctions into one.

Kleisli composition. In Haskell it is defined as >=>, AKA "compose, fishy, compose"

Type Parameters:

A - the input type

B - the middle type

C - the output type

Parameters:

bc - partial function from B -> C, must not be null

ab - partial function from A -> B, must not be null

Returns:

a PartialFunction that flatMaps g on to the result of applying f.

Since:

1.2

toBiFunction

public static <A,B,C> BiFunction<A,B,C> toBiFunction(Function<Pair<A,B>,C> fpair)

Converts a function that takes a pair of arguments to a function that takes two arguments

Type Parameters:

A - the type of the left of the pair

B - the type of the right of the pair

C - the result type

Parameters:

fpair - the source function that takes a pair of arguments, must not be null

Returns:

a function that takes two arguments

Since:

2.0

curried

public static <A,B,C> Function<A,Function<B,C>> curried(BiFunction<A,B,C> f2)

Transforms a function that takes 2 arguments into a function that takes the first argument and return a new function that takes the second argument and return the final result.

Type Parameters:

A - the type of the first argument

B - the type of the second argument

C - the type of the final result

Parameters:

f2 - the original function that takes 2 arguments, must not be null

Returns:

the curried form of the original function

Since:

2.0

flip

public static <A,B,C> Function<B,Function<A,C>> flip(Function<A,Function<B,C>> f2)

Transforms a function from A -> (B -> C) into a function from B -> (A -> C).

Type Parameters:

A - the type of the first argument

B - the type of the second argument

C - the type of the final result

Parameters:

f2 - the original function from A -> (B -> C), must not be null

Returns:

the flipped form of the original function

Since:

2.0

mapNullToOption

public static <A,B> Function<A,Option<B>> mapNullToOption(Function<? super A,? extends B> f)

Maps a function that returns nulls into a Partial function that returns an Option of the result.

Type Parameters:

A - the input type

B - the output type

Parameters:

f - the function that may return nulls

Returns:

a function that converts any nulls into Options

Since:

2.0

nullToOption

public static <A> Function<A,Option<A>> nullToOption()

Function that turns null inputs into a none, and not-null inputs into some.

Type Parameters:

A - the input type

Returns:

a function that never returns nulls.

Since:

2.2.1

weakMemoize

public static <A,B> Function<A,B> weakMemoize(Function<A,B> f)

Takes a Function and memoizes (caches) the result for each input. This memoization is weak, so it shouldn't leak memory on its own, but equally it may expunge entries if no-one else is holding the reference in the meantime.

NOTE: it is very important that the docs on the input type are read carefully. Failure to heed adhere to this will lead to unspecified behavior (bugs!)

Type Parameters:

A - the input type, like any cache, this type should be a value, that is it should be immutable and have correct hashcode and equals implementations.

B - the output type

Parameters:

f - the function who's output will be memoized, must not be null

Returns:

a function that memoizes the results of the function using the input as a weak key

Since:

2.2

fromConsumer

public static <D> Function<D,Unit> fromConsumer(Consumer<D> consumer)

Get a function (with Unit return type) that calls the consumer for all inputs.

Type Parameters:

D - the key type

Parameters:

consumer - called for all inputs, must not be null

Returns:

the function

Since:

4.4.0

identity

public static <A> Function<A,A> identity()

Returns the identity function. Consider using Function.identity()

Type Parameters:

A - a A object.

Returns:

a Function that retruns it's input.

constant

public static <A,B> Function<A,B> constant(B constant)

Create a function ignores it's input an produces a constant value

Type Parameters:

A - type of the ignored input

B - type of the constant returned

Parameters:

constant - value to return

Returns:

a function producing a constant value

forMap

public static <A,B> Function<A,Option<B>> forMap(Map<A,B> map)

Create a function that performs a map lookup returning None for null If you do not need a nondefaulted return result using a method reference is preferred map::get

Type Parameters:

A - map key type

B - map value type

Parameters:

map - map to use for lookup

Returns:

result of calling Map#get replacing null with none

See Also:

to supply a default value for none

forMapWithDefault

public static <A,B> Function<A,B> forMapWithDefault(Map<A,B> map,
                                                    B defaultValue)

Create a function that performs a map lookup supplying a default value when a Map#get returns null If you do not need a defaulted return result using a method reference is preferred map::get

Type Parameters:

A - map key type

B - map value type

Parameters:

map - map to use for lookup

defaultValue - a B to use when the map returns null from Map#get.

Returns:

result of calling Map#get returning defaultValue instead if the result was null

matches

public static <A,B> Function<A,Option<B>> matches(Function<? super A,? extends Option<? extends B>> f1,
                                                  Function<? super A,? extends Option<? extends B>> f2)

Creates a stack of matcher functions and returns the first result that matches.

Type Parameters:

A - the input type

B - the output type

Parameters:

f1 - partial function, tried in order.

f2 - partial function, tried in order.

Returns:

a PartialFunction that composes all the functions and tries each one in sequence.

Since:

1.2

matches

public static <A,B> Function<A,Option<B>> matches(Function<? super A,? extends Option<? extends B>> f1,
                                                  Function<? super A,? extends Option<? extends B>> f2,
                                                  Function<? super A,? extends Option<? extends B>> f3)

Creates a stack of matcher functions and returns the first result that matches.

Type Parameters:

A - the input type

B - the output type

Parameters:

f1 - partial function, tried in order.

f2 - partial function, tried in order.

f3 - partial function, tried in order.

Returns:

a PartialFunction that composes all the functions and tries each one in sequence.

Since:

1.2

matches

public static <A,B> Function<A,Option<B>> matches(Function<? super A,? extends Option<? extends B>> f1,
                                                  Function<? super A,? extends Option<? extends B>> f2,
                                                  Function<? super A,? extends Option<? extends B>> f3,
                                                  Function<? super A,? extends Option<? extends B>> f4)

Creates a stack of matcher functions and returns the first result that matches.

Type Parameters:

A - the input type

B - the output type

Parameters:

f1 - partial function, tried in order.

f2 - partial function, tried in order.

f3 - partial function, tried in order.

f4 - partial function, tried in order.

Returns:

a PartialFunction that composes all the functions and tries each one in sequence.

Since:

1.2

matches

@SafeVarargs
public static <A,B> Function<A,Option<B>> matches(Function<? super A,? extends Option<? extends B>> f1,
                                                               Function<? super A,? extends Option<? extends B>> f2,
                                                               Function<? super A,? extends Option<? extends B>> f3,
                                                               Function<? super A,? extends Option<? extends B>> f4,
                                                               Function<? super A,? extends Option<? extends B>> f5,
                                                               Function<? super A,? extends Option<? extends B>>... fs)

Creates a stack of matcher functions and returns the first result that matches.

Type Parameters:

A - the input type

B - the output type

Parameters:

f1 - partial function, tried in order.

f2 - partial function, tried in order.

f3 - partial function, tried in order.

f4 - partial function, tried in order.

f5 - partial function, tried in order.

fs - partial functions, tried in order.

Returns:

a PartialFunction that composes all the functions and tries each one in sequence.

Since:

1.2