MapperUtils (functions API)

java.lang.Object
- org.perro.functions.mapper.MapperUtils

```
public final class MapperUtils
extends java.lang.Object
```
Methods that build functions to map a target element into another result.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static <T,R> java.util.function.Function<T,java.util.stream.Stream<R>>`	`flatArrayMapper(java.util.function.Function<? super T,? extends R[]> function)` Given a `Function` that takes an element of type <T> and returns an array of type <R>, this method builds a `Function` that takes the same argument type, and returns a `Stream<R>`.
`static <T,R> java.util.function.Function<T,java.util.stream.Stream<R>>`	`flatMapper(java.util.function.Function<? super T,? extends java.util.Collection<R>> function)` Given a `Function` that takes an element of type <T> and returns a `Collection<R>`, this method builds a `Function` that takes the same argument type, and returns a `Stream<R>`.
`static <T,K,V> java.util.function.Function<T,V>`	`getValue(java.util.Map<K,V> map, java.util.function.Function<T,K> function)` Retrieves a value of type <R> from a `Map`, using a key retrieved from an element of type <T> using a passed `Function`.
`static <T,U,R> java.util.function.Function<T,R>`	`inverseMapper(java.util.function.BiFunction<? super U,? super T,? extends R> biFunction, U value)` As in the `mapper(BiFunction, Object)` method, builds a `Function` from a passed `BiFunction`, which can be very useful in the common situation where you are streaming through a collection elements, and have a method to call that takes two parameters.
`static <T,K,V> org.perro.functions.mapper.KeyValueMapper<T,K,V>`	`keyValueMapper(java.util.function.Function<T,K> keyMapper, java.util.function.Function<T,V> valueMapper)` Builds an object representing a pair of functions, one to return a key in a `Map`, and the other to return its associated value.
`static <T,U,R> java.util.function.Function<T,R>`	`mapper(java.util.function.BiFunction<? super T,? super U,? extends R> biFunction, U value)` Builds a `Function` from a passed `BiFunction`, which can be very useful in the common situation where you are streaming through a collection of elements, and have a method to call that takes two parameters - the first one being the element on which you are streaming, and the second being some constant value that will be passed to all invocations.
`static <T,U,R> java.util.function.Function<T,R>`	`mapper(java.util.function.Function<? super T,? extends U> left, java.util.function.Function<? super U,? extends R> right)` Applies a series to two `Function` method references, the first taking a parameter of type <T> and returning a value of type <U>, and the second taking a parameter of type <U> and returning a value of type <R>.
`static <T,R> java.util.function.Function<T,R>`	`mapper(java.util.function.Function<T,R> function)` Simply casts a method reference, which takes a single parameter of type <T> and returns <R>, to a `Function`.
`static <T,R> java.util.function.Function<T,R>`	`mapperDefault(java.util.function.Function<? super T,? extends R> function, R defaultValue)` Builds a mapper `Function` that, if the target element is `null`, or the result of the `Function` call on the target element is `null`, then the passed default value is returned.
`static <T,R> java.util.function.Function<T,R>`	`mapperDefault(java.util.function.Function<? super T,? extends R> function, java.util.function.Supplier<R> defaultSupplier)` Builds a mapper `Function` that, if the target element is `null`, or the result of the `Function` call on the target element is `null`, then the passed `defaultSupplier` is called to provide a default value.
`static <T> java.util.function.UnaryOperator<T>`	`mapperDefault(java.util.function.Supplier<T> defaultSupplier)` Given a default value of type <T>, returns a `UnaryOperator<T>` that simply returns the target element if it is not `null`, otherwise it returns a default value retrieved from the passed `defaultSupplier`.
`static <T> java.util.function.UnaryOperator<T>`	`mapperDefault(T defaultValue)` Given a default value of type <T>, returns a `UnaryOperator<T>` that simply returns the target element if it is not `null`, otherwise it returns the passed `defaultValue`.
`static <T,U,R> java.util.function.Function<T,R>`	`mapperIgnoringTarget(java.util.function.Function<U,R> function, U value)` Takes a `Function` with a single parameter of type <U> and returns a `Function` taking a parameter of type <T>.
`static <T,R> java.util.function.Function<T,R>`	`mapperIgnoringTarget(java.util.function.Supplier<R> supplier)` Takes a `Supplier` and returns a `Function` taking a parameter of type <T>.
`static <T,U> java.util.function.Function<T,Pair<T,U>>`	`pairOf(java.util.function.Function<? super T,? extends U> rightFunction)` Given a `Function` that takes an element of type <T> and returns a value of type <U>, this method builds a `Function` that takes the same argument type and returns a value of type `Pair<T, U>`.
`static <T,U,V> java.util.function.Function<T,Pair<U,V>>`	`pairOf(java.util.function.Function<T,U> leftFunction, java.util.function.Function<? super T,? extends V> rightFunction)` Given a pair of functions, one that takes an element of type <T> and returns a value of type <U>, and the other that takes an element of type <T> and returns a value of type <V>, this method builds a `Function` that takes the same argument type and returns a value of type `Pair<U, V>`.
`static <T,U,V> java.util.function.Function<T,Pair<U,V>>`	`pairOf(org.perro.functions.mapper.KeyValueMapper<T,U,V> keyValueMapper)` Given an object consisting of a pair of functions, one that takes an element of type <T> and returns a value of type <U>, and the other that takes an element of type <T> and returns a value of type <V>, this method builds a `Function` that takes the same argument type and returns a value of type `Pair<U, V>`.
`static <T,U,V> java.util.function.Function<T,Pair<U,V>>`	`pairWith(java.util.function.Function<? super T,? extends U> function, java.util.List<V> pairedList)` Given a `Function<T, U>`, and a `List<V>`, this method builds a `Function` that takes an element of type <T>, and returns a `Pair<U, V>`.
`static <T,R> java.util.function.Function<T,Pair<T,R>>`	`pairWith(java.util.List<R> pairedList)` Given a `List<R>`, this methods builds a `Function` that returns a `Pair<T, R>`.
`static <T> java.util.function.Function<T,ObjectIndexPair<T>>`	`pairWithIndex()` Builds a `Function` that, given an element of type <T>, returns an object that represents a pair of values, one being the element itself, and the other a primitive zero-based index of the object in encounter order.
`static <T,R> java.util.function.Function<T,ObjectIndexPair<R>>`	`pairWithIndex(java.util.function.Function<? super T,? extends R> function)` Given a `Function` that takes an element of type <T> and returns a value of type <R>, this method builds a `Function` that, given an element of type <T>, returns an object that represents a pair of values, one being a value returned from the passed `function`, and the other a primitive zero-based index of the object in encounter order.
`static <T,R> java.util.function.Function<T,R>`	`ternary(java.util.function.Predicate<T> predicate, org.perro.functions.mapper.TrueFalseMappers<T,R> ternaryMapper)` Given a Predicate<T> and an object consisting of a pair of functions, each taking an element of type <T> and returning a value of type <R>, one to return a value if the predicate is true, the other returning an alternate value if the predicate is false, this method builds a `Function` that evaluates the predicate and returns a value produced by one or the other of the pair.
`static <T,R> org.perro.functions.mapper.TrueFalseMappers<T,R>`	`trueFalseMappers(java.util.function.Function<T,R> trueExtractor, java.util.function.Function<T,R> falseExtractor)` Builds an object representing a pair of functions, one to return a value if a predicate evaluates to true, the other to return an alternate value if it evaluates to false.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
 - mapper
```
public static <T,R> java.util.function.Function<T,R> mapper(java.util.function.Function<T,R> function)
```
 Simply casts a method reference, which takes a single parameter of type <T> and returns <R>, to a Function. This could be useful in a situation where methods of the Function interface are to be called on a method reference. In the following example, assume that the Widget.getProductType method returns an enum instance, and we ultimately want to get the enum name:
```
 public List<String> getProductTypeNames(Collection<Widget> widgets) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(MapperUtils.mapper(Widget::getProductType)
 .andThen(ProductType::name))
 .distinct()
 .collect(toList());
 }
 
```
 The Function.andThen() method can only be called on the method reference because of the cast. An additional benefit of calling this method is the null-checking performed on the target element passed to the resulting function. For example, the following common idiom is in common use:
```
 Target target = ...
 String str = Optional.of(target).map(Target::someGetter).orElse(null);
 
```
 The same thing could be accomplished in a slightly more simple way with this method:
```
 Target target = ...
 String str = mapper(Target::someGetter).apply(target);
 
```
 It's slightly shorter, and is one fewer method calls. It also works for chained function calls:
```
 Target target = ...
 String str = Optional.of(target)
 .map(Target::someGetter)
 .map(OtherTarget::someOtherGetter)
 .orElse(null);
 
```
 vs.
```
 Target target = ...
 String str = mapper(Target::someGetter)
 .andThen(mapper(OtherTarget::someOtherGetter))
 .apply(target);
 
```
 Type Parameters:
 
 T - The type of the single parameter to the Function.
 
 R - The type of the result of the Function.
 
 Parameters:
 
 function - A method reference to be cast to a Function.
 
 Returns:
 
 A method reference cast to a Function.
 - mapperIgnoringTarget
```
public static <T,R> java.util.function.Function<T,R> mapperIgnoringTarget(java.util.function.Supplier<R> supplier)
```
 Takes a Supplier and returns a Function taking a parameter of type <T>. The parameter is ignored, and the Supplier is used to retrieve the result of the Function instead.
 
 Type Parameters:
 
 T - The type of the single parameter to the returned Function.
 
 R - The return type of the passed Supplier, as well as the Function resulting from a call to this method.
 
 Parameters:
 
 supplier - A Supplier to retrieve the result of the returned Function.
 
 Returns:
 
 A Function that ignores its passed parameter of type <T>, and uses a passed Supplier to retrieve its result instead.
 - mapperIgnoringTarget
```
public static <T,U,R> java.util.function.Function<T,R> mapperIgnoringTarget(java.util.function.Function<U,R> function,
 U value)
```
 Takes a Function with a single parameter of type and returns a Function taking a parameter of type <T>. Also takes a constant value of type , which will be passed to it. A Function taking a parameter of type <T> will be returned, but its value will be ignored, and the passed Function will be called with the constant value, returning its result instead.
 This could be useful in a situation where you are building a key object for a map from another object. If the key exists, you simply want to return the value. However, if the key does not exist, you want to build the value not from the key object, but from the original object. For example, assume that objectMap is an instance variable of type Map<KeyObject, ValueObject> on the current object:
```
 public ValueObject getValue(OriginalObject original) {
 return objectMap.computeIfAbsent(createKeyObject(original), mapperIgnoringTarget(this::createValueObject, original));
 }

 private KeyObject createKeyObject(OriginalObject original) {
 ...
 }

 private ValueObject createValueObject(OriginalObject original) {
 ...
 }
 
```
 Type Parameters:
 
 T - The type of the single parameter to the returned Function.
 
 U - The type of the parameter to the passed function. Also the type of a passed constant value.
 
 R - The return type of the passed Function, as well as the Function resulting from a call to this method.
 
 Parameters:
 
 function - A Function taking a constant value of type , to retrieve the result of the returned Function.
 
 value - A constant value of type to be supplied to the passed function.
 
 Returns:
 
 A Function that ignores its passed parameter of type <T>, and uses a passed Function to retrieve its result instead, passing it a constant value of type .
 - mapperDefault
```
public static <T> java.util.function.UnaryOperator<T> mapperDefault(T defaultValue)
```
 Given a default value of type <T>, returns a UnaryOperator<T> that simply returns the target element if it is not null, otherwise it returns the passed defaultValue. This method can be used in combination with any of the mappers built by this class. In the following example, assume the following code is using static imports for the classes in this library:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(Widget::getProductType)
 .map(mapperDefault(ProductType.NONE))
 .distinct()
 .collect(toList());
 }
 
```
 Note that we could have simply done this:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(mapperDefault(Widget::getProductType, ProductType.NONE))
 .distinct()
 .collect(toList());
 }
 
```
 That would have been simpler in this case. However, when there is already a lot going on in a particular mapper, it may be more clear to simply provide a default in its own map method call. Also, this method can be used in a stream with no other mappers, simply to provide a default for those elements that might be null, for whatever reason:
```
 private List<String> getDefaultedStrings(Collection<String> strings) {
 return defaultStream(strings)
 .map(mapperDefault(""))
 .collect(toList());
 }
 
```
 The most straightforward way to accomplish the above would be to use a TransformUtils method:
```
 ...
 return transform(strings, mapperDefault(""));
 ...
 
```
 Type Parameters:
 
 T - The type of the target element of the UnaryOperator built by this method.
 
 Parameters:
 
 defaultValue - The default value to return if the target element of the UnaryOperator built by this method is null.
 
 Returns:
 
 A UnaryOperator that simply returns the target element if it is not null, otherwise it returns the passed defaultValue. Note that a UnaryOperator can be used in place of a Function, because it extends Function<T, T>, returning an object of the same type as its parameter.
 - mapperDefault
```
public static <T> java.util.function.UnaryOperator<T> mapperDefault(java.util.function.Supplier<T> defaultSupplier)
```
 Given a default value of type <T>, returns a UnaryOperator<T> that simply returns the target element if it is not null, otherwise it returns a default value retrieved from the passed defaultSupplier. This method can be used in combination with any of the mappers built by this class. In the following example, assume the following code is using static imports for the classes in this library:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets, Customer customer) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(Widget::getProductType)
 .map(mapperDefault(supplier(this::getDefaultProductType, customer)))
 .distinct()
 .collect(toList());
 }

 private ProductType getDefaultProductType(Customer customer) {
 ...
 }
 
```
 Note that we could have accomplished the same thing this way:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(mapperDefault(Widget::getProductType, mapperDefault(supplier(this::getDefaultProductType, customer))))
 .distinct()
 .collect(toList());
 }
 
```
 However, the first example is more straightforward and more readable. Also, this method can be used in a stream with no other mappers, simply to provide a default for those elements that might be null, for whatever reason:
```
 private List<String> getDefaultedStrings(Collection<String> strings) {
 return defaultStream(strings)
 .map(mapperDefault(this::getDefaultStr))
 .collect(toList());
 }
 
```
 The most straightforward way to accomplish the above would be to use a TransformUtils method:
```
 ...
 return transform(strings, mapperDefault(this::getDefaultStr));
 ...
 
```
 Type Parameters:
 
 T - The type of the target element of the UnaryOperator built by this method.
 
 Parameters:
 
 defaultSupplier - The default value to return if the target element of the UnaryOperator built by this method is null.
 
 Returns:
 
 A UnaryOperator that simply returns the target element if it is not null, otherwise it returns the passed defaultValue. Note that a UnaryOperator can be used in place of a Function, because it extends Function<T, T>, returning an object of the same type as its parameter.
 - mapperDefault
```
public static <T,R> java.util.function.Function<T,R> mapperDefault(java.util.function.Function<? super T,? extends R> function,
 R defaultValue)
```
 Builds a mapper Function that, if the target element is null, or the result of the Function call on the target element is null, then the passed default value is returned. In the following example, assume that the Widget.getProductType method returns an enum instance, and that if its value is null, then it should default to ProductType.NONE:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(MapperUtils.mapperDefault(Widget::getProductType, ProductType.NONE))
 .distinct()
 .collect(toList());
 }
 
```
 An additional benefit of calling this method is the null-checking performed on the target element passed to the resulting function. For example, the following common idiom is in common use:
```
 Target target = ...
 String str = Optional.of(target).map(Target::someGetter).orElse("");
 
```
 The same thing could be accomplished in a slightly more simple way with this method:
```
 Target target = ...
 Object str = mapperDefault(Target::someGetter, "").apply(target);
 
```
 It's slightly shorter, and is one fewer method calls. As in mapper(Function) above, it also works for chained function calls, although it would be slightly different:
```
 Target target = ...
 String str = Optional.of(target)
 .map(Target::someGetter)
 .map(OtherTarget::someOtherGetter)
 .orElse("");
 
```
 vs.
```
 Target target = ...
 String str = mapper(Target::someGetter)
 .andThen(mapperDefault(OtherTarget::someOtherGetter, ""))
 .apply(target);
 
```
 The second one is a little more flexible, because you can have different defaults for different function calls.
 Type Parameters:
 
 T - The type of the target element on which the mapper Function is to be called.
 
 R - The type of the result to be returned from the mapper Function built by this method.
 
 Parameters:
 
 function - A method reference which takes a single parameter of type <T>, and returns a value of type <R>.
 
 defaultValue - A default value of type <R>, to be returned in case the target element, or the result of the Function call on the target element is null.
 
 Returns:
 
 A mapper Function that returns a default value if the target element, or the result of the Function call on the target element is null.
 - mapperDefault
```
public static <T,R> java.util.function.Function<T,R> mapperDefault(java.util.function.Function<? super T,? extends R> function,
 java.util.function.Supplier<R> defaultSupplier)
```
 Builds a mapper Function that, if the target element is null, or the result of the Function call on the target element is null, then the passed defaultSupplier is called to provide a default value. In the following example, assume that the Widget.getProductType method returns an enum instance, and that if its value is null, then it should default to a default value supplied by a method call:
```
 public List<ProductType> getProductTypes(Collection<Widget> widgets, Customer customer) {
 return Collection<ProductType> productTypes = widgets.stream()
 .map(MapperUtils.mapperDefault(Widget::getProductType, SupplierUtils.supplier(this::getDefaultProductType, customer)))
 .distinct()
 .collect(toList());
 }

 private ProductType getDefaultProductType(Customer customer) {
 ...
 }
 
```
 Or, with static imports:
```
 return Collection<ProductType> productTypes = widgets.stream()
 .map(mapperDefault(Widget::getProductType, supplier(this::getDefaultProductType, customer)))
 .distinct()
 .collect(toList());
 
```
 An additional benefit of calling this method is the null-checking performed on the target element passed to the resulting function. For example, the following common idiom is in common use:
```
 Target target = ...
 String str = Optional.of(target).map(Target::someGetter).orElseGet(this::getDefaultStr);
 
```
 The same thing could be accomplished in a slightly more simple way with this method:
```
 Target target = ...
 Object str = mapperDefault(Target::someGetter, this::getDefaultStr).apply(target);
 
```
 It's slightly shorter, and is one fewer method calls. As in the above mapperDefault(Function, Object) method, it works with chained function calls as well.
 Type Parameters:
 
 T - The type of the target element on which the mapper Function is to be called.
 
 R - The type of the result to be returned from the mapper Function built by this method. Also, the return type of the default Supplier.
 
 Parameters:
 
 function - A method reference which takes a single parameter of type <T>, and returns a value of type <R>.
 
 defaultSupplier - A Supplier of a default value of type <R>, to be called in case the target element, or the result of the Function call on the target element, is null.
 
 Returns:
 
 A mapper Function that returns a default value if the target element, or the result of the Function call on the target element is null.
 - mapper
```
public static <T,U,R> java.util.function.Function<T,R> mapper(java.util.function.BiFunction<? super T,? super U,? extends R> biFunction,
 U value)
```
 Builds a Function from a passed BiFunction, which can be very useful in the common situation where you are streaming through a collection of elements, and have a method to call that takes two parameters - the first one being the element on which you are streaming, and the second being some constant value that will be passed to all invocations. This would typically be called from within a chain of method calls based on a Stream. In the following example, assume the LineItemRequest objects come in from a rest API call, and we want to transform them into a collection of OrderLineItem objects:
```
 private Collection<OrderLineItem> buildOrderLineItems(Collection<LineItemRequest> lineItemRequests, String orderId) {
 return Collection<OrderLineItem> orderLineItems = lineItemRequests.stream()
 .map(MapperUtils.mapper(this::createOrderLineItem, orderId))
 .collect(toList());
 }

 private OrderLineItem createOrderLineItem(LineItemRequest request, String orderId) {
 ...
 }
 
```
 Or, with static imports:
```
 return Collection<OrderLineItem> orderLineItems = requestLineItems.stream()
 .map(mapper(this::createOrderLineItem, orderId))
 .collect(toList());
 
```
 Type Parameters:
 
 T - The target type of the first parameter to the passed biFunction.
 
 U - The type of the constant value to be passed as the second parameter to each invocation of biFunction.
 
 R - The type of the result of the Function built by this method.
 
 Parameters:
 
 biFunction - A method reference (a BiFunction) which takes two parameters - the first of type <T>, and the second of type , either of which can be any type. The method reference will be converted by this method to a Function, taking a single parameter of type <T>. Behind the scenes, this BiFunction will be called, passing the constant value to each invocation as the second parameter.
 
 value - A constant value, in that it will be passed to every invocation of the passed biFunction as the second parameter to it, and will have the same value for each of them.
 
 Returns:
 
 A Function taking a single parameter of type <T>.
 - inverseMapper
```
public static <T,U,R> java.util.function.Function<T,R> inverseMapper(java.util.function.BiFunction<? super U,? super T,? extends R> biFunction,
 U value)
```
 As in the mapper(BiFunction, Object) method, builds a Function from a passed BiFunction, which can be very useful in the common situation where you are streaming through a collection elements, and have a method to call that takes two parameters. In the BiFunction passed to this method, the parameters are basically the same as in mapper(BiFunction, Object), but in the inverse order. Here, the first parameter is a constant value that will be passed to all invocations of the method, and the second parameter is the target element on which you are streaming. This would typically be called from within a chain of method calls based on a Stream. In the following example, assume the LineItemRequest objects come in from a rest API call, and we want to transform them into a collection of OrderLineItem objects:
```
 private Collection<OrderLineItem> buildOrderLineItems(String orderId, Collection<LineItemRequest> requestLineItems) {
 return Collection<OrderLineItem> orderLineItems = requestLineItems.stream()
 .map(MapperUtils.inverseMapper(this::createOrderLineItem, orderId))
 .collect(toList());
 }

 private OrderLineItem createOrderLineItem(String orderId, RequestLineItem request) {
 ...
 }
 
```
 Note how the parameters to the createOrderLineItem(...) are in the inverse order as the ones in the example for the mapper(BiFunction, Object) method.
 Or, with static imports:
```
 return Collection<OrderLineItem> orderLineItems = requestLineItems.stream()
 .map(inverseMapper(this::createOrderLineItem, orderId))
 .collect(toList());
 
```
 Type Parameters:
 
 T - The target type of the second parameter to the passed biFunction.
 
 U - The type of the constant value to be passed as the first parameter to each invocation of biFunction.
 
 R - The type of the result of the Function built by this method.
 
 Parameters:
 
 biFunction - A method reference (a BiFunction) which takes two parameters - the first of type , and the second of type <T>, either of which can be any type. The method reference will be converted by this method to a Function, taking a single parameter of type <T>. Behind the scenes, this BiFunction will be called, passing the constant value to each invocation as the first parameter.
 
 value - A constant value, in that it will be passed to every invocation of the passed biFunction as the first parameter to it, and will have the same value for each of them.
 
 Returns:
 
 A Function taking a single parameter of type <T>.
 - mapper
```
public static <T,U,R> java.util.function.Function<T,R> mapper(java.util.function.Function<? super T,? extends U> left,
 java.util.function.Function<? super U,? extends R> right)
```
 Applies a series to two Function method references, the first taking a parameter of type <T> and returning a value of type , and the second taking a parameter of type and returning a value of type <R>. The following example illustrates its usage (assume there are static imports for the classes from this library):
```
 List<ObjectThree> transformed = transform(objects, mapper(ObjectOne::getObjectTwo, ObjectTwo::getObjectThree));
 
```
 The above are equivalent to:
```
 List<ObjectThree> transformed = transform(objects, mapper(ObjectOne::getObjectTwo).andThen(ObjectTwo::getObjectThree));
 
```
 The first example calling this method is slightly more concise, but which of the above is more readable is up to the individual developer. This method provides an alternative way of accomplishing the above transformation. There is an additional benefit of using this method, however. Not only is there null-checking on the target element, there is also null-checking on the result of the transformation using the left Function.
 Type Parameters:
 
 T - The type of a target element to be passed to the resulting function.
 
 U - The type of an interim result from a first transformation.
 
 R - The type of a final result from a second transformation.
 
 Parameters:
 
 left - A Function to perform a first, preliminary transformation.
 
 right - A Function to perform a second, final transformation.
 
 Returns:
 
 A Function transforming an element of type <T> to a result of type <R>. If the target element is null, or the result of the transformation using the left Function is null, then the Function will return null.
 - getValue
```
public static <T,K,V> java.util.function.Function<T,V> getValue(java.util.Map<K,V> map,
 java.util.function.Function<T,K> function)
```
 Retrieves a value of type <R> from a Map, using a key retrieved from an element of type <T> using a passed Function. The following example illustrates its usage:
```
 private List<Customer> getCustomers(Collection<Order> orders) {
 Map<String, Customer> customerById = ...
 return StreamUtils.transform(orders, MapperUtils.getValue(customerById, Order::getCustomerId));
 }
 
```
 Or, using static imports:
```
 return transform(orders, getValue(customerById, Order::getCustomerId));
 
```
 Type Parameters:
 
 T - The type of the target element on which a Function is to be called to provide a key value.
 
 K - The type of a key value for a passed Map.
 
 V - The type of the value to be returned from the Function built by this method.
 
 Parameters:
 
 map - A map from which a value will be retrieved.
 
 function - A Function whose result will be used as a key to retrieve a value from a Map.
 
 Returns:
 
 A Function that retrieves a value from a passed Map. If passed map, or the target element passed to this Function are null, then the result of this Function will be null.
 - flatMapper
```
public static <T,R> java.util.function.Function<T,java.util.stream.Stream<R>> flatMapper(java.util.function.Function<? super T,? extends java.util.Collection<R>> function)
```
 Given a Function that takes an element of type <T> and returns a Collection<R>, this method builds a Function that takes the same argument type, and returns a Stream<R>. This is useful in the Stream.flatMap() method. For example, let's say you want to retrieve all the line items from all of a customer's orders, assuming that Order.getLineItems() returns a Collection of type <R>:
```
 private List<OrderLineItem> getCustomerLineItems(Collection<Order> customerOrders) {
 return customerOrders.stream()
 .flatMap(MapperUtils.flatMapper(Order::getLineItems))
 .collect(Collectors.toList());
 }
 
```
 Or, with static imports:
```
 return customerOrders.stream()
 .flatMap(flatMapper(Order::getLineItems))
 .collect(toList());
 
```
 Type Parameters:
 
 T - The type of the target element on which a Function is to be called to provide a Collection.
 
 R - The type of the element of a Collection returned by the given function.
 
 Parameters:
 
 function - A function that returns a Collection of type <R>.
 
 Returns:
 
 A Function that, given a target element of type <T>, returns a Stream of type <R>. Returns an empty Stream if the target element is null, or the Collection returned by the given function is null.
 - flatArrayMapper
```
public static <T,R> java.util.function.Function<T,java.util.stream.Stream<R>> flatArrayMapper(java.util.function.Function<? super T,? extends R[]> function)
```
 Given a Function that takes an element of type <T> and returns an array of type <R>, this method builds a Function that takes the same argument type, and returns a Stream<R>. This is useful in the Stream.flatMap() method. For example, let's say you want to retrieve all the line items from all of a customer's orders, assuming that Order.getLineItems() returns an array of OrderLineItem:
```
 private List<OrderLineItem> getCustomerLineItems(Collection<Order> customerOrders) {
 return customerOrders.stream()
 .flatMap(MapperUtils.flatArrayMapper(Order::getLineItems))
 .collect(Collectors.toList());
 }
 
```
 Or, with static imports:
```
 return customerOrders.stream()
 .flatMap(flatArrayMapper(Order::getLineItems))
 .collect(toList());
 
```
 Type Parameters:
 
 T - The type of the target element on which a Function is to be called to provide an array.
 
 R - The type of the element of an array returned by the given function.
 
 Parameters:
 
 function - A function that returns an array of type <R>.
 
 Returns:
 
 A Function that, given a target element of type <T>, returns a Stream of type <R>. Returns an empty Stream if the target element is null, or the array returned by the given function is null.
 - pairOf
```
public static <T,U> java.util.function.Function<T,Pair<T,U>> pairOf(java.util.function.Function<? super T,? extends U> rightFunction)
```
 Given a Function that takes an element of type <T> and returns a value of type , this method builds a Function that takes the same argument type and returns a value of type Pair<T, U>. This pair will consist of the target element itself, and a value returned by the passed rightFunction.
 
 Type Parameters:
 
 T - The type of the target element on which the rightFunction is to be called.
 
 U - The type of the right element of the Pair to be returned by the Function built by this method.
 
 Parameters:
 
 rightFunction - A Function to extract the right value in the Pair<T, U> to be returned by the Function built by this method.
 
 Returns:
 
 A Function that, given a target element of type <T>, returns a Pair of the target element, along with a value returned by the passed rightFunction.
 - pairOf
```
public static <T,U,V> java.util.function.Function<T,Pair<U,V>> pairOf(org.perro.functions.mapper.KeyValueMapper<T,U,V> keyValueMapper)
```
 Given an object consisting of a pair of functions, one that takes an element of type <T> and returns a value of type , and the other that takes an element of type <T> and returns a value of type <V>, this method builds a Function that takes the same argument type and returns a value of type Pair<U, V>. This Pair will consist of the values returned by each of the functions in the passed keyValueMapper. This method does the same thing as the overload that takes a leftFunction and rightFunction, and is included as a convenience when a method already takes a KeyValueMapper. For example, the implementation of the TransformUtils.transformToMap(Collection, KeyValueMapper) method is:
```
 public static <T, K, V> Map<K, V> transformToMap(Collection<T> objects, KeyValueMapper<T, K, V> keyValueMapper) {
 return defaultStream(objects)
 .map(pairOf(keyValueMapper))
 .collect(toMapFromEntry());
 }
 
```
 This works because the Pair object implements the Java Map.Entry interface.
 Type Parameters:
 
 T - The type of the target element on which a pair of functions, represented by the passed keyValueMapper, will be called.
 
 U - The type of the left element of the Pair to be returned by the Function built by this method.
 
 V - The type of the right element of the Pair to be returned by the Function built by this method.
 
 Parameters:
 
 keyValueMapper - An object consisting of a pair of functions that will be used to retrieve a left and right value for a Pair that is a result of the Function built by this method.
 
 Returns:
 
 A Function that, given a target element of type <T>, returns a Pair whose values will be retrieved by a pair of functions represented by the passed keyValueMapper.
 - pairOf
```
public static <T,U,V> java.util.function.Function<T,Pair<U,V>> pairOf(java.util.function.Function<T,U> leftFunction,
 java.util.function.Function<? super T,? extends V> rightFunction)
```
 Given a pair of functions, one that takes an element of type <T> and returns a value of type , and the other that takes an element of type <T> and returns a value of type <V>, this method builds a Function that takes the same argument type and returns a value of type Pair<U, V>. This Pair will consist of the values returned by each of the functions passed to this method.
 
 Type Parameters:
 
 T - The type of the target element on which a pair of passed functions will be called.
 
 U - The type of the left element of the Pair to be returned by the Function built by this method.
 
 V - The type of the right element of the Pair to be returned by the Function built by this method.
 
 Parameters:
 
 leftFunction - A Function that will be used to retrieve a left value for a Pair that is a result of the Function built by this method.
 
 rightFunction - A Function that will be used to retrieve a right value for a Pair that is a result of the Function built by this method.
 
 Returns:
 
 A Function that, given a target element of type <T>, returns a Pair whose values will be retrieved by a pair of functions passed to this method.
 - pairWith
```
public static <T,R> java.util.function.Function<T,Pair<T,R>> pairWith(java.util.List<R> pairedList)
```
 Given a List<R>, this methods builds a Function that returns a Pair<T, R>. It is intended to be used in a stream. The Pair<T, R> built by this Function will consist of a target element, and an object of type <R> whose element in the passed List is associated with the current element, in encounter order. This is most useful in a situation where an ordered collection is being streamed. The function returned from this method is not intended to be used with parallel streams.
 If the passed List has more elements than the collection being streamed, the extra elements are ignored. If it has fewer elements, any target elements being streamed that do not have associated values in the list will be paired with a null value.
 
 Type Parameters:
 
 T - The type of the target element being streamed.
 
 R - The type of the elements in the passed pairedList parameter.
 
 Parameters:
 
 pairedList - A List whose elements are to be paired with collection elements being streamed, by the Function built by this method.
 
 Returns:
 
 A Function that, given an element of type <T>, will return a Pair of that element, along with an associated element from the passed pairedList.
 - pairWith
```
public static <T,U,V> java.util.function.Function<T,Pair<U,V>> pairWith(java.util.function.Function<? super T,? extends U> function,
 java.util.List<V> pairedList)
```
 Given a Function<T, U>, and a List<V>, this method builds a Function that takes an element of type <T>, and returns a Pair<U, V>. It is intended to be used in a stream. The Pair<U, V> built by this Function will consist of an element returned by the passed function, and an object of type <V> whose element in the passed List is associated with the current element, in encounter order. This is most useful in a situation where an ordered collection is being streamed. The function returned from this method is not intended to be used with parallel streams.
 If the passed List has more elements than the collection being streamed, the extra elements are ignored. If it has fewer elements, any values returned by the passed function, that do not have associated values in the list, will be paired with a null value.
 
 Type Parameters:
 
 T - The type of the target element being streamed.
 
 U - The type of the left element, retrieved by the passed function.
 
 V - The type of the right element, retrieved from the passed List.
 
 Parameters:
 
 function - A Function that will return a value of type , which will become the left element in a Pair, returned by the Function built by this method.
 
 pairedList - A List whose elements are to be paired with elements retrieved by the passed function.
 
 Returns:
 
 A Function that, given an element of type <T>, will return a Pair of a value retrieved from the passed function, along with an associated element from the passed pairedList.
 - pairWithIndex
```
public static <T> java.util.function.Function<T,ObjectIndexPair<T>> pairWithIndex()
```
 Builds a Function that, given an element of type <T>, returns an object that represents a pair of values, one being the element itself, and the other a primitive zero-based index of the object in encounter order. The Function built by this method is intended to be used in a stream, and is most useful in a situation where an ordered collection is being streamed. It is not intended to be used with parallel streams.
 
 Type Parameters:
 
 T - The type of the target elements being streamed.
 
 Returns:
 
 A Function that takes an element of type <T>, and returns an object representing a pair of the element itself, along with the primitive zero-based int index of the element.
 - pairWithIndex
```
public static <T,R> java.util.function.Function<T,ObjectIndexPair<R>> pairWithIndex(java.util.function.Function<? super T,? extends R> function)
```
 Given a Function that takes an element of type <T> and returns a value of type <R>, this method builds a Function that, given an element of type <T>, returns an object that represents a pair of values, one being a value returned from the passed function, and the other a primitive zero-based index of the object in encounter order. The Function built by this method is intended to be used in a stream, and is most useful in a situation where an ordered collection is being streamed. It is not intended to be used with parallel streams.
 
 Type Parameters:
 
 T - The type of the target elements being streamed.
 
 R - The type of a value retrieved from the passed function.
 
 Parameters:
 
 function - A Function that takes an element of type <T> and returns a value of type <R>.
 
 Returns:
 
 A Function that takes an element of type <T>, and returns an object representing a pair of a value returned from the passed function, along with the primitive zero-based int index of the target element.
 - ternary
```
public static <T,R> java.util.function.Function<T,R> ternary(java.util.function.Predicate<T> predicate,
 org.perro.functions.mapper.TrueFalseMappers<T,R> ternaryMapper)
```
 Given a Predicate<T> and an object consisting of a pair of functions, each taking an element of type <T> and returning a value of type <R>, one to return a value if the predicate is true, the other returning an alternate value if the predicate is false, this method builds a Function that evaluates the predicate and returns a value produced by one or the other of the pair. For example, suppose you have a collection of objects that represent nodes in a tree. The nodes each represent a folder or document in a hierarchy. You want to collect a set of only the root node ids:
```
 private Set<String> getRootNodeIds(Collection<TreeNode> treeNodes) {
 return treeNodes.stream()
 .map(MapperUtils.ternary(TreeNode::isRoot, MapperUtils.trueFalseMappers(TreeNode::getId, TreeNode::getRootId)))
 .collect(Collectors.toSet());
 }
 
```
 Or, using static imports:
```
 private Set<String> getRootNodeIds(Collection<TreeNode> treeNodes) {
 return treeNodes.stream()
 .map(ternary(TreeNode::isRoot, trueFalseMappers(TreeNode::getId, TreeNode::getRootId)))
 .collect(Collectors.toSet());
 }
 
```
 Type Parameters:
 
 T - The type of the target element for the passed predicate.
 
 R - The type of the values returned by the pair of functions in the passed trueFalseMappers.
 
 Parameters:
 
 predicate - A predicate to be called on an element of type <T>.
 
 ternaryMapper - An object consisting of a pair of functions, one to return a value if the passed predicate evaluates to true, and the other to return an alternate value if it evaluates to false.
 
 Returns:
 
 A value of type <R> returned by one or the other of a pair of functions, depending on whether the passed predicate evaluates to true or false.
 - trueFalseMappers
```
public static <T,R> org.perro.functions.mapper.TrueFalseMappers<T,R> trueFalseMappers(java.util.function.Function<T,R> trueExtractor,
 java.util.function.Function<T,R> falseExtractor)
```
 Builds an object representing a pair of functions, one to return a value if a predicate evaluates to true, the other to return an alternate value if it evaluates to false. This method is meant to be used to build the second argument to the ternary(Predicate, TrueFalseMappers) method.
 
 Type Parameters:
 
 T - The type of the target element on which the extractor methods below are to be called.
 
 R - The type of the value to be returned by the extractor methods below.
 
 Parameters:
 
 trueExtractor - Retrieves a value to be returned by the ternary(Predicate, TrueFalseMappers) method when its predicate evaluates to true.
 
 falseExtractor - Retrieves a value to be returned by the ternary(Predicate, TrueFalseMappers) method when its predicate evaluates to false.
 
 Returns:
 
 An object representing a pair of functions, one to be called if a predicate evaluates to true, the other to be called if it evaluates to false.
 - keyValueMapper
```
public static <T,K,V> org.perro.functions.mapper.KeyValueMapper<T,K,V> keyValueMapper(java.util.function.Function<T,K> keyMapper,
 java.util.function.Function<T,V> valueMapper)
```
 Builds an object representing a pair of functions, one to return a key in a Map, and the other to return its associated value. This method is meant to be used to build the second parameter to the TransformUtils.transformToMap(Collection, KeyValueMapper) method.
 
 Type Parameters:
 
 T - The type of the target element on which the functions below are to be called.
 
 K - The type of a key value for a Map.
 
 V - The type of a value to be associated with a key in a Map.
 
 Parameters:
 
 keyMapper - Function to retrieve a value to be used as a key in a Map
 
 valueMapper - Function to retrieve a value associated with a key in a Map
 
 Returns:
 
 Builds an object representing a pair of functions, one to retrieve a Map key, and the other to retrieve its associated value.

Class MapperUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

mapper

mapperIgnoringTarget

mapperIgnoringTarget

mapperDefault

mapperDefault

mapperDefault

mapperDefault

mapper

inverseMapper

mapper

getValue

flatMapper

flatArrayMapper

pairOf

pairOf

pairOf

pairWith

pairWith

pairWithIndex

pairWithIndex

ternary

trueFalseMappers

keyValueMapper