= Can
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Immutable _Iterable_ , that can specifically represent 3 possible variants of xref:refguide:commons:index/collections/Cardinality.adoc[Cardinality] .

Java's _Optional_ , can be seen as a holder of element(s), that is restricted to cardinality ZERO or ONE. xref:refguide:commons:index/collections/Can.adoc[Can] is the logical extension to that, allowing also a cardinality of MULTIPLE.

Same idiomatic convention applies: References to xref:refguide:commons:index/collections/Can.adoc[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 use store null, then use a different data structure, for example a regular _java.util.List java.util.List_ .

== API

[source,java]
.Can.java
----
interface Can<T> {
  Optional<T> get(int elementIndex)     // <.>
  T getElseFail(int elementIndex)     // <.>
  int compareTo(Can<T> o)     // <.>
  Optional<T> getFirst()     // <.>
  T getFirstElseFail()     // <.>
  Optional<T> getLast()     // <.>
  T getLastElseFail()     // <.>
  Can<T> empty()     // <.>
  Can<T> ofNullable(T element)     // <.>
  Can<T> ofSingleton(T element)     // <.>
  Can<T> of(T... array)     // <.>
  Can<T> ofArray(T[] array)     // <.>
  Can<T> ofCollection(Collection<T> collection)     // <.>
  Can<T> ofIterable(Iterable<T> iterable)     // <.>
  Can<T> ofEnumeration(Enumeration<T> enumeration)     // <.>
  Can<T> ofStream(Stream<T> stream)     // <.>
  Can<T> sorted(Comparator<? super T> comparator)     // <.>
  Can<T> distinct()     // <.>
  Can<T> distinct(BiPredicate<T, T> equality)     // <.>
  Can<T> reverse()     // <.>
  Can<T> filter(Predicate<? super T> predicate)     // <.>
  Can<R> map(Function<? super T, R> mapper)     // <.>
  Can<R> flatMap(Function<? super T, ? extends Can<? extends R>> mapper)
  Can<T> reduce(BinaryOperator<T> accumulator)     // <.>
  Can<T> concat(Can<T> can, T element)     // <.>
  Iterator<T> iterator(int skip, int limit)     // <.>
  Iterator<T> reverseIterator()
  void forEach(Consumer<? super T> action)
  void zip(Iterable<R> zippedIn, BiConsumer<? super T, ? super R> action)     // <.>
  Can<R> zipMap(Iterable<Z> zippedIn, BiFunction<? super T, ? super Z, R> mapper)     // <.>
  Can<T> add(T element)
  Can<T> addUnique(T element)     // <.>
  Can<T> addAll(Can<T> other)
  Can<T> add(int index, T element)     // <.>
  Can<T> replace(int index, T element)
  Can<T> remove(int index)     // <.>
  Can<T> remove(T element)
  Can<T> pickByIndex(int... indices)     // <.>
  Can<T> pickByIndex(IntStream intStream)     // <.>
  Can<T> subCan(int startInclusive, int endExclusive)     // <.>
  Can<Can<T>> partitionInnerBound(int maxInnerSize)     // <.>
  Can<Can<T>> partitionOuterBound(int outerSizeYield)     // <.>
  int indexOf(T element)     // <.>
  boolean isEqualTo(Can<?> other)     // <.>
  boolean startsWith(Can<?> other)     // <.>
  boolean endsWith(Can<?> other)     // <.>
  boolean isEmpty()
  boolean isNotEmpty()
  boolean isCardinalityOne()
  boolean isCardinalityMultiple()
  Collector<T, ?, Can<T>> toCan()
  List<T> toList()     // <.>
  List<T> toArrayList()     // <.>
  Set<T> toSet()     // <.>
  Set<T> toSet(Consumer<T> onDuplicated)     // <.>
  C toCollection(Supplier<C> collectionFactory)     // <.>
  T[] toArray(T[] a)     // <.>
  T[] toArray(Class<T> elementType)     // <.>
}
----

<.> xref:#get_int[get(int)]
+
--
Will only ever return an empty Optional, if the elementIndex is out of bounds.
--
<.> xref:#getElseFail_int[getElseFail(int)]
+
--
Shortcut to _get(elementIndex).orElseThrow(...)_
--
<.> xref:#compareTo_Can[compareTo(Can)]
+
--
For convenience allows the argument to be _null_ treating _null_ equivalent to _Can#empty()_ .
--
<.> xref:#getFirst_[getFirst()]
<.> xref:#getFirstElseFail_[getFirstElseFail()]
+
--
Shortcut for _getFirst().orElseThrow(_Exceptions::noSuchElement)_
--
<.> xref:#getLast_[getLast()]
<.> xref:#getLastElseFail_[getLastElseFail()]
+
--
Shortcut for _getLast().orElseThrow(_Exceptions::noSuchElement)_
--
<.> xref:#empty_[empty()]
+
--
Returns an empty _Can_ .
--
<.> xref:#ofNullable_T[ofNullable(T)]
+
--
Returns either a _Can_ with the given _element_ or an empty _Can_ if the _element_ is _null_ .
--
<.> xref:#ofSingleton_T[ofSingleton(T)]
+
--
Returns either a _Can_ with the given _element_ or throws if the _element_ is _null_ .
--
<.> xref:#of_T[of(T)]
+
--
Var-arg version of _Can#ofArray(Object[])_ .
--
<.> xref:#ofArray_T[ofArray(T)]
+
--
Returns either a _Can_ with all the elements from given _array_ or an empty _Can_ if the _array_ is _null_ .
--
<.> xref:#ofCollection_Collection[ofCollection(Collection)]
+
--
Returns either a _Can_ with all the elements from given _collection_ or an empty _Can_ if the _collection_ is _null_ .
--
<.> xref:#ofIterable_Iterable[ofIterable(Iterable)]
+
--
Returns either a _Can_ with all the elements from given _iterable_ or an empty _Can_ if the _iterable_ is _null_ .
--
<.> xref:#ofEnumeration_Enumeration[ofEnumeration(Enumeration)]
+
--
Returns either a _Can_ with all the elements from given _enumeration_ or an empty _Can_ if the _enumeration_ is _null_ .
--
<.> xref:#ofStream_Stream[ofStream(Stream)]
+
--
Returns either a _Can_ with all the elements from given _stream_ or an empty _Can_ if the _stream_ is _null_ .
--
<.> xref:#sorted_Comparator[sorted(Comparator)]
+
--
Returns a _Can_ with all the elements from this _Can_ , but sorted based on _Comparable#compareTo(Object)_ order.
--
<.> xref:#distinct_[distinct()]
+
--
Returns a _Can_ with all the elements from this _Can_ , but duplicated elements removed, based on _Object#equals(Object)_ object equality.
--
<.> xref:#distinct_BiPredicate[distinct(BiPredicate)]
+
--
Returns a _Can_ with all the elements from this _Can_ , but duplicated elements removed, based on given _equality_ relation.
--
<.> xref:#reverse_[reverse()]
+
--
Returns a _Can_ with all the elements from this _Can_ , but contained in reversed order.
--
<.> xref:#filter_Predicate[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.
--
<.> xref:#map_Function[map(Function)]
+
--
Returns a _Can_ with all the elements from this _Can_ 'transformed' by the given _mapper_ function.
--
<.> xref:#reduce_BinaryOperator[reduce(BinaryOperator)]
+
--
Performs a reduction on all elements, returning a xref:refguide:commons:index/collections/Can.adoc[Can] containing either a singleton reduction result or an empty xref:refguide:commons:index/collections/Can.adoc[Can] .
--
<.> xref:#concat_Can_T[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.
--
<.> xref:#iterator_int_int[iterator(int, int)]
+
--
Returns an iterator that skips the first _skip_ elements, then returns a maximum of _limit_ elements.
--
<.> xref:#zip_Iterable_BiConsumer[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_ .
--
<.> xref:#zipMap_Iterable_BiFunction[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_ .
--
<.> xref:#addUnique_T[addUnique(T)]
+
--
Adds the specified element to the list if it is not already present.
--
<.> xref:#add_int_T[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).
--
<.> xref:#remove_int[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.
--
<.> xref:#pickByIndex_int[pickByIndex(int)]
+
--
Given _n_ indices, returns an equivalent of(where nulls are being ignored)
--
<.> xref:#pickByIndex_IntStream[pickByIndex(IntStream)]
+
--
Returns a xref:refguide:commons:index/collections/Can.adoc[Can] that is made of the elements from this xref:refguide:commons:index/collections/Can.adoc[Can] , picked by index using the given _IntStream_ (in the order of picking).
--
<.> xref:#subCan_int_int[subCan(int, int)]
+
--
Returns a sub- xref:refguide:commons:index/collections/Can.adoc[Can] that is made of elements from this xref:refguide:commons:index/collections/Can.adoc[Can] , when selected by those indices, that result from given range _endExclusive)_ .
--
<.> xref:#partitionInnerBound_int[partitionInnerBound(int)]
+
--
Returns consecutive _#subCan(int, int) subCan_ , each of the same maxInnerSize, while the final sub- xref:refguide:commons:index/collections/Can.adoc[Can] may be smaller.
--
<.> xref:#partitionOuterBound_int[partitionOuterBound(int)]
+
--
Tries to split this xref:refguide:commons:index/collections/Can.adoc[Can] into outerSizeYield consecutive _#subCan(int, int) subCan_ , each of the same calculated max-inner-size, while the final sub- xref:refguide:commons:index/collections/Can.adoc[Can] may be smaller.
--
<.> xref:#indexOf_T[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.
--
<.> xref:#isEqualTo_Can[isEqualTo(Can)]
<.> xref:#startsWith_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_ .
--
<.> xref:#endsWith_Can[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_ .
--
<.> xref:#toList_[toList()]
<.> xref:#toArrayList_[toArrayList()]
<.> xref:#toSet_[toSet()]
<.> xref:#toSet_Consumer[toSet(Consumer)]
<.> xref:#toCollection_Supplier[toCollection(Supplier)]
<.> xref:#toArray_T[toArray(T)]
<.> xref:#toArray_Class[toArray(Class)]

== Members

[#get_int]
=== get(int)

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

[#getElseFail_int]
=== getElseFail(int)

Shortcut to _get(elementIndex).orElseThrow(...)_

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

[#compareTo_Can]
=== compareTo(Can)

For convenience allows the argument to be _null_ treating _null_ equivalent to _Can#empty()_ .

[#getFirst_]
=== getFirst()

[#getFirstElseFail_]
=== getFirstElseFail()

Shortcut for _getFirst().orElseThrow(_Exceptions::noSuchElement)_

[#getLast_]
=== getLast()

[#getLastElseFail_]
=== getLastElseFail()

Shortcut for _getLast().orElseThrow(_Exceptions::noSuchElement)_

[#empty_]
=== empty()

Returns an empty _Can_ .

[#ofNullable_T]
=== ofNullable(T)

Returns either a _Can_ with the given _element_ or an empty _Can_ if the _element_ is _null_ .

[#ofSingleton_T]
=== ofSingleton(T)

Returns either a _Can_ with the given _element_ or throws if the _element_ is _null_ .

[#of_T]
=== 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]
=== 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]
=== 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]
=== 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]
=== 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]
=== 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]
=== sorted(Comparator)

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

[#distinct_]
=== distinct()

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

[#distinct_BiPredicate]
=== distinct(BiPredicate)

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

[#reverse_]
=== reverse()

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

[#filter_Predicate]
=== 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]
=== 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]
=== reduce(BinaryOperator)

Performs a reduction on all elements, returning a xref:refguide:commons:index/collections/Can.adoc[Can] containing either a singleton reduction result or an empty xref:refguide:commons:index/collections/Can.adoc[Can] .

[#concat_Can_T]
=== 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]
=== iterator(int, int)

Returns an iterator that skips the first _skip_ elements, then returns a maximum of _limit_ elements.

[#zip_Iterable_BiConsumer]
=== 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]
=== 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]
=== addUnique(T)

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

[#add_int_T]
=== 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]
=== 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]
=== 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]
=== pickByIndex(IntStream)

Returns a xref:refguide:commons:index/collections/Can.adoc[Can] that is made of the elements from this xref:refguide:commons:index/collections/Can.adoc[Can] , picked by index using the given _IntStream_ (in the order of picking).

Out of bounds picking is simply ignored.

[#subCan_int_int]
=== subCan(int, int)

Returns a sub- xref:refguide:commons:index/collections/Can.adoc[Can] that is made of elements from this xref:refguide:commons:index/collections/Can.adoc[Can] , when selected by those indices, that result from given range _endExclusive)_ .

Out of bounds picking is simply ignored.

[#partitionInnerBound_int]
=== partitionInnerBound(int)

Returns consecutive _#subCan(int, int) subCan_ , each of the same maxInnerSize, while the final sub- xref:refguide:commons:index/collections/Can.adoc[Can] may be smaller.

For example, partitioning a xref:refguide:commons:index/collections/Can.adoc[Can] containing _[a, b, c, d, e]_ with a partition size of 3 yields _[[a, b, c], [d, e]]_ -- an outer xref:refguide:commons:index/collections/Can.adoc[Can] containing two inner xref:refguide:commons:index/collections/Can.adoc[Can] s of three and two elements, all in the original order.

[#partitionOuterBound_int]
=== partitionOuterBound(int)

Tries to split this xref:refguide:commons:index/collections/Can.adoc[Can] into outerSizeYield consecutive _#subCan(int, int) subCan_ , each of the same calculated max-inner-size, while the final sub- xref:refguide:commons:index/collections/Can.adoc[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]
=== 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]
=== isEqualTo(Can)

[#startsWith_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]
=== 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_]
=== toList()

[#toArrayList_]
=== toArrayList()

[#toSet_]
=== toSet()

[#toSet_Consumer]
=== toSet(Consumer)

[#toCollection_Supplier]
=== toCollection(Supplier)

[#toArray_T]
=== toArray(T)

[#toArray_Class]
=== toArray(Class)
