Can

Immutable Iterable , that can specifically represent 3 possible variants of Cardinality .

Java’s Optional , can be seen as a holder of element(s), that is restricted to cardinality ZERO or ONE. Can is the logical extension to that, allowing also a cardinality of MULTIPLE.

Same idiomatic convention applies: References to Can should never be initialized to null .

*IMPORTANT:* A xref:refguide:commons:index/collections/Can.adoc[Can] must not contain _null_ elements. If you need to store _null_ , then use a different data structure, for example a regular _java.util.List java.util.List_ .

API

Can.java
interface Can<T> {
  Optional<T> get(int elementIndex)     (1)
  Optional<T> getRelativeToLast(int offset)     (2)
  T getElseFail(int elementIndex)     (3)
  T getRelativeToLastElseFail(int offset)     (4)
  int compareTo(Can<T> o)     (5)
  Optional<T> getFirst()     (6)
  T getFirstElseFail()     (7)
  Optional<T> getLast()     (8)
  T getLastElseFail()     (9)
  Can<T> empty()     (10)
  Can<T> ofNullable(T element)     (11)
  Can<T> ofSingleton(T element)     (12)
  Can<T> of(T... array)     (13)
  Can<T> ofArray(T[] array)     (14)
  Can<T> ofCollection(Collection<T> collection)     (15)
  Can<T> ofIterable(Iterable<T> iterable)     (16)
  Can<T> ofEnumeration(Enumeration<T> enumeration)     (17)
  Can<T> ofStream(Stream<T> stream)     (18)
  Can<T> sorted(Comparator<? super T> comparator)     (19)
  Can<T> distinct()     (20)
  Can<T> distinct(BiPredicate<T, T> equality)     (21)
  Can<T> reverse()     (22)
  Can<T> filter(Predicate<? super T> predicate)     (23)
  Can<R> map(Function<? super T, R> mapper)     (24)
  Can<R> flatMap(Function<? super T, ? extends Can<? extends R>> mapper)
  Can<T> reduce(BinaryOperator<T> accumulator)     (25)
  Can<T> concat(Can<T> can, T element)     (26)
  Iterator<T> iterator(int skip, int limit)     (27)
  Iterator<T> reverseIterator()
  void forEach(Consumer<? super T> action)
  void zip(Iterable<R> zippedIn, BiConsumer<? super T, ? super R> action)     (28)
  Can<R> zipMap(Iterable<Z> zippedIn, BiFunction<? super T, ? super Z, R> mapper)     (29)
  Can<T> add(T element)
  Can<T> addUnique(T element)     (30)
  Can<T> addAll(Can<T> other)
  Can<T> add(int index, T element)     (31)
  Can<T> replace(int index, T element)
  Can<T> remove(int index)     (32)
  Can<T> remove(T element)
  Can<T> pickByIndex(int... indices)     (33)
  Can<T> pickByIndex(IntStream intStream)     (34)
  Can<T> subCan(int startInclusive)     (35)
  Can<T> subCan(int startInclusive, int endExclusive)     (36)
  Can<Can<T>> partitionInnerBound(int maxInnerSize)     (37)
  Can<Can<T>> partitionOuterBound(int outerSizeYield)     (38)
  int indexOf(T element)     (39)
  boolean isEqualTo(Can<?> other)     (40)
  boolean startsWith(Can<?> other)     (41)
  boolean endsWith(Can<?> other)     (42)
  boolean isEmpty()
  boolean isNotEmpty()
  boolean isCardinalityOne()
  boolean isCardinalityMultiple()
  Collector<T, ?, Can<T>> toCan()
  List<T> toList()     (43)
  List<T> toArrayList()     (44)
  Set<T> toSet()     (45)
  Set<T> toSet(Consumer<T> onDuplicated)     (46)
  C toCollection(Supplier<C> collectionFactory)     (47)
  T[] toArray(T[] a)     (48)
  T[] toArray(Class<T> elementType)     (49)
}
1 get(int)

Will (only ever) return an empty Optional , if the elementIndex is out of bounds.
2 getRelativeToLast(int)

Shortcut for get(this.size() - 1 - (-offset))
3 getElseFail(int)

Shortcut to get(elementIndex).orElseThrow(…​)
4 getRelativeToLastElseFail(int)

Shortcut for getElseFail(this.size() - 1 - (-offset))
5 compareTo(Can)

For convenience allows the argument to be null treating null equivalent to Can#empty() .
6 getFirst()
7 getFirstElseFail()

Shortcut for getFirst().orElseThrow(_Exceptions::noSuchElement)
8 getLast()
9 getLastElseFail()

Shortcut for getLast().orElseThrow(_Exceptions::noSuchElement)
10 empty()

Returns an empty Can .
11 ofNullable(T)

Returns either a Can with the given element or an empty Can if the element is null .
12 ofSingleton(T)

Returns either a Can with the given element or throws if the element is null .
13 of(T)

Var-arg version of Can#ofArray(Object[]) .
14 ofArray(T)

Returns either a Can with all the elements from given array or an empty Can if the array is null .
15 ofCollection(Collection)

Returns either a Can with all the elements from given collection or an empty Can if the collection is null .
16 ofIterable(Iterable)

Returns either a Can with all the elements from given iterable or an empty Can if the iterable is null .
17 ofEnumeration(Enumeration)

Returns either a Can with all the elements from given enumeration or an empty Can if the enumeration is null .
18 ofStream(Stream)

Returns either a Can with all the elements from given stream or an empty Can if the stream is null .
19 sorted(Comparator)

Returns a Can with all the elements from this Can , but sorted based on Comparable#compareTo(Object) order.
20 distinct()

Returns a Can with all the elements from this Can , but duplicated elements removed, based on Object#equals(Object) object equality.
21 distinct(BiPredicate)

Returns a Can with all the elements from this Can , but duplicated elements removed, based on given equality relation.
22 reverse()

Returns a Can with all the elements from this Can , but contained in reversed order.
23 filter(Predicate)

Returns a Can with all the elements from this Can , that are accepted by the given predicate . If predicate is null all elements are accepted.
24 map(Function)

Returns a Can with all the elements from this Can 'transformed' by the given mapper function.
25 reduce(BinaryOperator)

Performs a reduction on all elements, returning a Can containing either a singleton reduction result or an empty Can .
26 concat(Can, T)

Returns a Can with all the elements from given can joined by the given element . If any of given can or element are null these do not contribute any elements and are ignored.
27 iterator(int, int)

Returns an iterator that skips the first skip elements, then returns a maximum of limit elements.
28 zip(Iterable, BiConsumer)

Similar to #forEach(Consumer) , but zipps in zippedIn to iterate through its elements and passes them over as the second argument to the action .
29 zipMap(Iterable, BiFunction)

Similar to #map(Function) , but zipps in zippedIn to iterate through its elements and passes them over as the second argument to the mapper .
30 addUnique(T)

Adds the specified element to the list if it is not already present.
31 add(int, T)

Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
32 remove(int)

Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.
33 pickByIndex(int)

Given n indices, returns an equivalent of(where nulls are being ignored)
34 pickByIndex(IntStream)

Returns a Can that is made of the elements from this Can , picked by index using the given IntStream (in the order of picking).
35 subCan(int)

Returns a sub- Can that is made of elements from this Can , starting with indices from startInclusive .
36 subCan(int, int)

Returns a sub- Can that is made of elements from this Can , when selected by indices from given range [startInclusive, endExclusive) .
37 partitionInnerBound(int)

Returns consecutive #subCan(int, int) subCan , each of the same maxInnerSize, while the final sub- Can may be smaller.
38 partitionOuterBound(int)

Tries to split this Can into outerSizeYield consecutive #subCan(int, int) subCan , each of the same calculated max-inner-size, while the final sub- Can may be smaller.
39 indexOf(T)

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) , or -1 if there is no such index.
40 isEqualTo(Can)
41 startsWith(Can)

Let n be the number of elements in other . Returns whether the first n elements of this Can are element-wise equal to other .
42 endsWith(Can)

Let n be the number of elements in other . Returns whether the last n elements of this Can are element-wise equal to other .
43 toList()
44 toArrayList()
45 toSet()
46 toSet(Consumer)
47 toCollection(Supplier)
48 toArray(T)
49 toArray(Class)

Members

get(int)

Will (only ever) return an empty Optional , if the elementIndex is out of bounds.

getRelativeToLast(int)

Shortcut for get(this.size() - 1 - (-offset))

getElseFail(int)

Shortcut to get(elementIndex).orElseThrow(…​)

Will only ever throw, if the elementIndex is out of bounds.

getRelativeToLastElseFail(int)

Shortcut for getElseFail(this.size() - 1 - (-offset))

compareTo(Can)

For convenience allows the argument to be null treating null equivalent to Can#empty() .

getFirst()

getFirstElseFail()

Shortcut for getFirst().orElseThrow(_Exceptions::noSuchElement)

getLast()

getLastElseFail()

Shortcut for getLast().orElseThrow(_Exceptions::noSuchElement)

empty()

Returns an empty Can .

ofNullable(T)

Returns either a Can with the given element or an empty Can if the element is null .

ofSingleton(T)

Returns either a Can with the given element or throws if the element is null .

of(T)

Var-arg version of Can#ofArray(Object[]) .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

ofArray(T)

Returns either a Can with all the elements from given array or an empty Can if the array is null .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

ofCollection(Collection)

Returns either a Can with all the elements from given collection or an empty Can if the collection is null .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

ofIterable(Iterable)

Returns either a Can with all the elements from given iterable or an empty Can if the iterable is null .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

ofEnumeration(Enumeration)

Returns either a Can with all the elements from given enumeration or an empty Can if the enumeration is null .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
*NOTE:* As side-effect, consumes given _enumeration_ .

ofStream(Stream)

Returns either a Can with all the elements from given stream or an empty Can if the stream is null .

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
*NOTE:* As side-effect, consumes given _stream_ .

sorted(Comparator)

Returns a Can with all the elements from this Can , but sorted based on Comparable#compareTo(Object) order.

distinct()

Returns a Can with all the elements from this Can , but duplicated elements removed, based on Object#equals(Object) object equality.

distinct(BiPredicate)

Returns a Can with all the elements from this Can , but duplicated elements removed, based on given equality relation.

reverse()

Returns a Can with all the elements from this Can , but contained in reversed order.

filter(Predicate)

Returns a Can with all the elements from this Can , that are accepted by the given predicate . If predicate is null all elements are accepted.

map(Function)

Returns a Can with all the elements from this Can 'transformed' by the given mapper function.

*NOTE:* Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

reduce(BinaryOperator)

Performs a reduction on all elements, returning a Can containing either a singleton reduction result or an empty Can .

concat(Can, T)

Returns a Can with all the elements from given can joined by the given element . If any of given can or element are null these do not contribute any elements and are ignored.

iterator(int, int)

Returns an iterator that skips the first skip elements, then returns a maximum of limit elements.

zip(Iterable, BiConsumer)

Similar to #forEach(Consumer) , but zipps in zippedIn to iterate through its elements and passes them over as the second argument to the action .

zipMap(Iterable, BiFunction)

Similar to #map(Function) , but zipps in zippedIn to iterate through its elements and passes them over as the second argument to the mapper .

addUnique(T)

Adds the specified element to the list if it is not already present.

add(int, T)

Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

remove(int)

Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

pickByIndex(int)

Given n indices, returns an equivalent of(where nulls are being ignored)

Can.of(
    this.get(indices[0]).orElse(null),
    this.get(indices[1]).orElse(null),
    ...
    this.get(indices[n-1]).orElse(null)
)

In other words: Out of bounds picking is simply ignored.

pickByIndex(IntStream)

Returns a Can that is made of the elements from this Can , picked by index using the given IntStream (in the order of picking).

Out of bounds picking is simply ignored.

subCan(int)

Returns a sub- Can that is made of elements from this Can , starting with indices from startInclusive .

Out of bounds picking is simply ignored.

subCan(int, int)

Returns a sub- Can that is made of elements from this Can , when selected by indices from given range [startInclusive, endExclusive) .

Out of bounds picking is simply ignored.

partitionInnerBound(int)

Returns consecutive #subCan(int, int) subCan , each of the same maxInnerSize, while the final sub- Can may be smaller.

For example, partitioning a Can containing [a, b, c, d, e] with a partition size of 3 yields  — an outer Can containing two inner Can s of three and two elements, all in the original order.

partitionOuterBound(int)

Tries to split this Can into outerSizeYield consecutive #subCan(int, int) subCan , each of the same calculated max-inner-size, while the final sub- Can may be smaller.

An outer cardinality of outerSizeYield is either exactly met or under-represented, based on how many elements are actually available.

indexOf(T)

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) , or -1 if there is no such index.

isEqualTo(Can)

startsWith(Can)

Let n be the number of elements in other . Returns whether the first n elements of this Can are element-wise equal to other .

endsWith(Can)

Let n be the number of elements in other . Returns whether the last n elements of this Can are element-wise equal to other .

toList()

toArrayList()

toSet()

toSet(Consumer)

toCollection(Supplier)

toArray(T)

toArray(Class)