= 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_ .

A xref:refguide:commons:index/collections/Can.adoc[Can] must not contain elements equal to _null_ .

== 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 getFirstOrFail()     // <.>
  Optional<T> getLast()     // <.>
  T getLastOrFail()     // <.>
  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> 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)     // <.>
  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:#getFirstOrFail_[getFirstOrFail()]
+
--
Shortcut for _getFirst().orElseThrow(_Exceptions::noSuchElement)_
--
<.> xref:#getLast_[getLast()]
<.> xref:#getLastOrFail_[getLastOrFail()]
+
--
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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
--
<.> 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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
--
<.> 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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
--
<.> 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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
--
<.> 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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .
--
<.> 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. Any resulting elements equal to _null_ are ignored and will not be contained in the resulting _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:#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()

[#getFirstOrFail_]
=== getFirstOrFail()

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

[#getLast_]
=== getLast()

[#getLastOrFail_]
=== getLastOrFail()

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[])_ .

[#ofArray_T]
=== ofArray(T)

Returns either a _Can_ with all the elements from given _array_ or an empty _Can_ if the _array_ is _null_ . 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_ . 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_ . 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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

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_ . Any elements equal to _null_ are ignored and will not be contained in the resulting _Can_ .

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. Any resulting elements equal to _null_ are ignored and will not be contained in the resulting _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)
)
----

[#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)
