Functions (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.function, class: Functions

# Class Functions

java.lang.Object
org.apache.commons.lang3.function.Functions

public final class Functions extends Object
Factory for `Function`.

Since:
  3.14.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T,R> R`
  `apply(Function<T,R> function, T object)`
  Applies the `Function` on the object if the function is not `null`.
  `static <T,R> R`
  `applyNonNull(T value, Function<? super T, ? extends R> mapper)`
  Applies a value to a function if the value isn't `null`, otherwise the method returns `null`.
  `static <T,U,R> R`
  `applyNonNull(T value1, Function<? super T, ? extends U> mapper1, Function<? super U, ? extends R> mapper2)`
  Applies values to a chain of functions, where a `null` can short-circuit each step.
  `static <T,U,V,R> R`
  `applyNonNull(T value1, Function<? super T, ? extends U> mapper1, Function<? super U, ? extends V> mapper2, Function<? super V, ? extends R> mapper3)`
  Applies values to a chain of functions, where a `null` can short-circuit each step.
  `static <T,R> Function<T,R>`
  `function(Function<T,R> function)`
  Starts a fluent chain like `function(foo::bar).andThen(...).andThen(...).apply(...);`

  ### Methods inherited from class Object

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

- ## Method Details

  - ### apply

    public static <T,R> R apply(Function<T,R> function, T object)
    Applies the `Function` on the object if the function is not `null`. Otherwise, does nothing and returns `null`.
    Type Parameters:
      `T` - the type of the argument the function applies.
      `R` - the type of the result the function returns.
    Parameters:
      `function` - the function to apply.
      `object` - the object to apply the function.
    Returns:
      the value the function returns if the function is not `null`; `null` otherwise.
    Since:
      3.15.0

  - ### applyNonNull

    public static <T,R> R applyNonNull(T value, Function<? super T, ? extends R> mapper)
    Applies a value to a function if the value isn't `null`, otherwise the method returns `null`. If the value isn't `null` then return the result of the applying function.

        Functions.applyNonNull("a", String::toUpperCase)  = "A"
        Functions.applyNonNull(null, String::toUpperCase) = null
        Functions.applyNonNull("a", s -> null)            = null

    Useful when working with expressions that may return `null` as it allows a single-line expression without using temporary local variables or evaluating expressions twice. Provides an alternative to using `Optional` that is shorter and has less allocation.

    Type Parameters:
      `T` - The type of the input of this method and the function.
      `R` - The type of the result of the function and this method.
    Parameters:
      `value` - The value to apply the function to, may be `null`.
      `mapper` - The function to apply, must not be `null`.
    Returns:
      The result of the function (which may be `null`) or `null` if the input value is `null`.
    Since:
      3.19.0
    See Also:
      - `applyNonNull(Object, Function, Function)`
      - `applyNonNull(Object, Function, Function, Function)`

  - ### applyNonNull

    public static <T,U,R> R applyNonNull(T value1, Function<? super T, ? extends U> mapper1, Function<? super U, ? extends R> mapper2)
    Applies values to a chain of functions, where a `null` can short-circuit each step. A function is only applied if the previous value is not `null`, otherwise this method returns `null`.

        Functions.applyNonNull(" a ", String::toUpperCase, String::trim) = "A"
        Functions.applyNonNull(null, String::toUpperCase, String::trim)  = null
        Functions.applyNonNull(" a ", s -> null, String::trim)           = null
        Functions.applyNonNull(" a ", String::toUpperCase, s -> null)    = null

    Useful when working with expressions that may return `null` as it allows a single-line expression without using temporary local variables or evaluating expressions twice. Provides an alternative to using `Optional` that is shorter and has less allocation.

    Type Parameters:
      `T` - The type of the input of this method and the first function.
      `U` - The type of the result of the first function and the input to the second function.
      `R` - The type of the result of the second function and this method.
    Parameters:
      `value1` - The value to apply the functions to, may be `null`.
      `mapper1` - The first function to apply, must not be `null`.
      `mapper2` - The second function to apply, must not be `null`.
    Returns:
      The result of the final function (which may be `null`) or `null` if the input value or any intermediate value is `null`.
    Since:
      3.19.0
    See Also:
      - `applyNonNull(Object, Function)`
      - `applyNonNull(Object, Function, Function, Function)`

  - ### applyNonNull

    public static <T,U,V,R> R applyNonNull(T value1, Function<? super T, ? extends U> mapper1, Function<? super U, ? extends V> mapper2, Function<? super V, ? extends R> mapper3)
    Applies values to a chain of functions, where a `null` can short-circuit each step. A function is only applied if the previous value is not `null`, otherwise this method returns `null`.

        Functions.applyNonNull(" abc ", String::toUpperCase, String::trim, StringUtils::reverse) = "CBA"
        Functions.applyNonNull(null, String::toUpperCase, String::trim, StringUtils::reverse)    = null
        Functions.applyNonNull(" abc ", s -> null, String::trim, StringUtils::reverse)           = null
        Functions.applyNonNull(" abc ", String::toUpperCase, s -> null, StringUtils::reverse)    = null
        Functions.applyNonNull(" abc ", String::toUpperCase, String::trim, s -> null)            = null

    Useful when working with expressions that may return `null` as it allows a single-line expression without using temporary local variables or evaluating expressions twice. Provides an alternative to using `Optional` that is shorter and has less allocation.

    Type Parameters:
      `T` - The type of the input of this method and the first function.
      `U` - The type of the result of the first function and the input to the second function.
      `V` - The type of the result of the second function and the input to the third function.
      `R` - The type of the result of the third function and this method.
    Parameters:
      `value1` - The value to apply the first function, may be `null`.
      `mapper1` - The first function to apply, must not be `null`.
      `mapper2` - The second function to apply, must not be `null`.
      `mapper3` - The third function to apply, must not be `null`.
    Returns:
      The result of the final function (which may be `null`) or `null` if the input value or any intermediate value is `null`.
    Since:
      3.19.0
    See Also:
      - `applyNonNull(Object, Function)`
      - `applyNonNull(Object, Function, Function)`

  - ### function

    public static <T,R> Function<T,R> function(Function<T,R> function)
    Starts a fluent chain like `function(foo::bar).andThen(...).andThen(...).apply(...);`
    Type Parameters:
      `T` - Input type.
      `R` - Return type.
    Parameters:
      `function` - the argument to return.
    Returns:
      the argument