MultiElement (Nary 3.0.0 API)

Type Parameters:

T - Type of contained elements

All Superinterfaces:

AutoCloseable, BaseStream<T,Stream<T>>, Iterable<T>, NaryStream<T>, Stream<T>

All Known Subinterfaces:

Nary<T>, Unary<T>

All Known Implementing Classes:

EmptyNary, NarySupport, OneElementNary, StreamBasedNary
```
public interface MultiElement<T>
extends Iterable<T>, NaryStream<T>
```
This type defines the protocol that Nary offers to manipulate its elements beyond those of Stream. This is the extended api that Nary offers over a native Stream.
Date: 12/10/19 - 21:42

Nested Class Summary
- Nested classes/interfaces inherited from interface java.util.stream.Stream
 Stream.Builder<T>

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`Nary<T>`	`add(T... others)` Creates a new Nary with the elements of this instance and the ones passed as var arg array
`<R> R`	`collect(Supplier<R> supplier, BiConsumer<R,? super T> accumulator)` Performs a mutable reduction operation on the elements of this stream.
`List<T>`	`collectToList()` Returns the content of this nary in a list. This method is a shorthand of calling collect(Collectors.toList()). This nary, as stream, will be consumed in the operation.
`Set<T>`	`collectToSet()` Returns the content of this nary in a set. This method is a shorthand of calling collect(Collectors.toSet()) This nary, as stream, will be consumed in the operation.
`Nary<T>`	`concat(Optional<? extends T> other)` Creates a concatenated Nary with the elements of this instance and the one (if any) on the given `Optional`
`Nary<T>`	`concat(Stream<? extends T> other)` Creates another nary that will contain the elements of this instance and the given stream
`Unary<T>`	`findAnyNary()` Alternative to `Stream.findAny()` that returns `Nary` instead of `Optional`
`Unary<T>`	`findFirstNary()` Alternative to `Stream.findFirst()` that returns `Nary` instead of `Optional`
`Unary<T>`	`findLast()` Returns the last element in this nary, if present. Depending on the amount of elements on this Nary, the result may be empty or contain the last element
`<U> Nary<U>`	`flatMapOptional(Function<? super T,Optional<U>> mapper)` Makes a normal `Stream.flatMap(Function)` transformation but accepts `Optional` as result for the mapper instead of `Stream`. This method is the semantic equivalent of `Optional.flatMap(Function)` but it can be applied to more than one element.
`default void`	`forEach(Consumer<? super T> action)` Solves conflict between `Iterable` and `Stream` because `Iterable` defines a default implementation. We use `Iterable.forEach(Consumer)` definition
`<U> Nary<U>`	`mapFilteringNullResult(Function<? super T,? extends U> mapper)` Map each element on this instance and filter null results out. If the result of mapping an element produces `null`, then it's skipped, reducing the amount of elements contained in the returned Nary. This is semantically equivalent to `Optional.map(Function)` and different from `Stream.map(Function)` that takes null as valid results
`Unary<T>`	`maxNary(Comparator<? super T> comparator)` Alternative to `Stream.max(Comparator)` that returns `Nary` instead of `Optional`
`Unary<T>`	`minNary(Comparator<? super T> comparator)` Alternative to `Stream.min(Comparator)` that returns `Nary` instead of `Optional`
`Unary<T>`	`reduceNary(BinaryOperator<T> accumulator)` Alternative to `Stream.reduce(BinaryOperator)` that returns `Unary` instead of `Optional`
`default Spliterator<T>`	`spliterator()` Solves conflict between `Iterable` and `Stream` because `Iterable` defines a default implementation. We use `Iterable.spliterator()` definition
`Unary<T>`	`unique()` Treats this instance as having a single element.

Methods inherited from interface java.lang.Iterable
iterator

Methods inherited from interface ar.com.kfgodel.nary.api.arity.NaryStream
distinct, filter, flatMap, limit, map, peek, skip, sorted, sorted

Methods inherited from interface java.util.stream.Stream
allMatch, anyMatch, builder, collect, collect, concat, count, empty, findAny, findFirst, flatMapToDouble, flatMapToInt, flatMapToLong, forEachOrdered, generate, iterate, mapToDouble, mapToInt, mapToLong, max, min, noneMatch, of, of, reduce, reduce, reduce, toArray, toArray

Methods inherited from interface java.util.stream.BaseStream
close, isParallel, iterator, onClose, parallel, sequential, unordered

- Method Detail
 - spliterator
```
default Spliterator<T> spliterator()
```
 Solves conflict between Iterable and Stream because Iterable defines a default implementation.
 We use Iterable.spliterator() definition
 
 Specified by:
 
 spliterator in interface BaseStream<T,Stream<T>>
 
 Specified by:
 
 spliterator in interface Iterable<T>
 - forEach
```
default void forEach(Consumer<? super T> action)
```
 Solves conflict between Iterable and Stream because Iterable defines a default implementation.
 We use Iterable.forEach(Consumer) definition
 
 Specified by:
 
 forEach in interface Iterable<T>
 
 Specified by:
 
 forEach in interface Stream<T>
 - collectToList
```
List<T> collectToList()
```
 Returns the content of this nary in a list.
 This method is a shorthand of calling collect(Collectors.toList()).
 
 This nary, as stream, will be consumed in the operation.
 
 Returns:
 
 The list with the elements of this nary
 - collectToSet
```
Set<T> collectToSet()
```
 Returns the content of this nary in a set.
 This method is a shorthand of calling collect(Collectors.toSet())
 This nary, as stream, will be consumed in the operation.
 
 Returns:
 
 The set with the elements of this nary
 - concat
```
Nary<T> concat(Stream<? extends T> other)
```
 Creates another nary that will contain the elements of this instance and the given stream
 
 Parameters:
 
 other - The stream to combine after this
 
 Returns:
 
 A nary with these elements first and the one on the stream later. Or empty if both are empty
 - concat
```
Nary<T> concat(Optional<? extends T> other)
```
 Creates a concatenated Nary with the elements of this instance and the one (if any) on the given Optional
 
 Parameters:
 
 other - The optional to join elements with
 
 Returns:
 
 A new Nary with the elements from both instances
 - add
```
Nary<T> add(T... others)
```
 Creates a new Nary with the elements of this instance and the ones passed as var arg array
 
 Parameters:
 
 others - The elements to append to this stream
 
 Returns:
 
 A new Nary with the elements from this instance plus the ones on the given array
 - collect
```
<R> R collect(Supplier<R> supplier,
 BiConsumer<R,? super T> accumulator)
```
 Performs a mutable reduction operation on the elements of this stream. A mutable reduction is one in which the reduced value is a mutable result container, such as an ArrayList, and elements are incorporated by updating the state of the result rather than by replacing the result. This produces a result equivalent to:
```
 R result = supplier.asUni().get();
 for (T element : this stream)
 accumulator.accept(result, element);
 return result;
 
```
 This is a terminal operation.
 There are many existing classes in the JDK whose signatures are well-suited for use with method references as arguments to collect(). For example, the following will accumulate strings into an ArrayList:
```
 List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add);
 
```
 The following will take a stream of strings and concatenates them into a single string:
```
 String concat = stringStream.collect(StringBuilder::new, StringBuilder::append)
 .toString();
 
```
 Type Parameters:
 
 R - type of the result
 
 Parameters:
 
 supplier - a function that creates a new result container. For a parallel execution, this function may be called multiple times and must return a fresh value each time.
 
 accumulator - an associative, non-interfering, stateless function for incorporating an additional element into a result
 
 Returns:
 
 the result of the reduction
 - findLast
```
Unary<T> findLast()
```
 Returns the last element in this nary, if present.
 Depending on the amount of elements on this Nary, the result may be empty or contain the last element
 
 Returns:
 
 The optional last element
 - reduceNary
```
Unary<T> reduceNary(BinaryOperator<T> accumulator)
```
 Alternative to Stream.reduce(BinaryOperator) that returns Unary instead of Optional
 
 Parameters:
 
 accumulator - The associative function to reduce the elements of this nary to a result of the same type
 
 Returns:
 
 The optional result of the reduction (or an empty nary)
 
 See Also:
 
 for a complete reference
 - minNary
```
Unary<T> minNary(Comparator<? super T> comparator)
```
 Alternative to Stream.min(Comparator) that returns Nary instead of Optional
 
 Parameters:
 
 comparator - a non-interfering, stateless Comparator to compare elements of this stream
 
 Returns:
 
 a Nary describing the minimum element of this stream, or an empty if there are no elements
 
 Throws:
 
 NullPointerException - if the minimum element is null
 - maxNary
```
Unary<T> maxNary(Comparator<? super T> comparator)
```
 Alternative to Stream.max(Comparator) that returns Nary instead of Optional
 
 Parameters:
 
 comparator - a non-interfering, stateless Comparator to compare elements of this stream
 
 Returns:
 
 a Nary describing the maximum element of this stream, or an empty if there are no elements
 
 Throws:
 
 NullPointerException - if the maximum element is null
 - findFirstNary
```
Unary<T> findFirstNary()
```
 Alternative to Stream.findFirst() that returns Nary instead of Optional
 
 Returns:
 
 a Nary describing the first element of this stream, or an empty Nary if the stream is empty
 
 Throws:
 
 NullPointerException - if the element selected is null
 - findAnyNary
```
Unary<T> findAnyNary()
```
 Alternative to Stream.findAny() that returns Nary instead of Optional
 
 Returns:
 
 an Nary describing some element of this stream, or an empty Nary if the stream is empty
 
 Throws:
 
 NullPointerException - if the element selected is null
 
 See Also:
 
 Stream.findFirst()
 - mapFilteringNullResult
```
 Nary mapFilteringNullResult(Function<? super T,? extends U> mapper)
```
 Map each element on this instance and filter null results out.
 If the result of mapping an element produces null, then it's skipped, reducing the amount of elements contained in the returned Nary.
 
 This is semantically equivalent to Optional.map(Function) and different from Stream.map(Function) that takes null as valid results
 
 Type Parameters:
 
 U - The type of the result of the mapping function
 
 Parameters:
 
 mapper - a mapping function to apply to the value, if present
 
 Returns:
 
 a Nary with the mapped results excluding the ones that returned null
 - flatMapOptional
```
 Nary flatMapOptional(Function<? super T,Optional> mapper)
```
 Makes a normal Stream.flatMap(Function) transformation but accepts Optional as result for the mapper instead of Stream.
 This method is the semantic equivalent of Optional.flatMap(Function) but it can be applied to more than one element.
 
 Type Parameters:
 
 U - The type parameter to the Optional returned by
 
 Parameters:
 
 mapper - a mapping function to apply to the value, if present the mapping function
 
 Returns:
 
 the result of applying an Optional-bearing mapping function to the elements of this instance which may be 0, 1, or more elements
 - unique
```
Unary<T> unique()
 throws MoreThanOneElementException
```
 Treats this instance as having a single element. Returns an object that can be used to extend the operations available once we know there are not more elements than 1.
 If this instance has more than 1 element then this method will fail when trying to return a Unary because expectations between runtime and compile time won't match
 
 Returns:
 
 The extended api for mono element
 
 Throws:
 
 MoreThanOneElementException - If this instance has more than one element

Interface MultiElement<T>

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.stream.Stream

Method Summary

Methods inherited from interface java.lang.Iterable

Methods inherited from interface ar.com.kfgodel.nary.api.arity.NaryStream

Methods inherited from interface java.util.stream.Stream

Methods inherited from interface java.util.stream.BaseStream

Method Detail

spliterator

forEach

collectToList

collectToSet

concat

concat

add

collect

findLast

reduceNary

minNary

maxNary

findFirstNary

findAnyNary

mapFilteringNullResult

flatMapOptional

unique