public interface IntCountable extends PrimitiveIntIterable, Sizeable
Having a known size usually helps in optimization, e.g. when copying.
This is meant to be used as a read-only interface, although Iterable
basically exports mutability via Iterator.remove().
This interface extends Iterable nevertheless so
implementations can be used in enhanced for loops.
In an ideal world Java collections should implement this interface to provide
a better compile-time read-only access compared to the
Collections#unmodifiableCollection() which will result
in runtime errors when mutating.
To allow living in a standard Java environment this interface provides
methods asCollection() to view it as an unmodifiable
collection and viewCollection(Collection) allowing
to view a collection as IntCountable.
A countable can also view an array or part of it (IntIndexable.viewArray(int[])
and IntIndexable.viewArray(int[], int, int)), and can be converted to
an array.
Last not least an empty countable is useful sometimes.
| Modifier and Type | Interface and Description |
|---|---|
static class |
IntCountable.Base
Abstract base class which provides useful implementations
for
Object.equals(Object), Object.hashCode(),
Object.toString(). |
| Modifier and Type | Field and Description |
|---|---|
static IntCountable |
EMPTY
Basic implementation of an empty countable
Don't use this, use
empty(). |
EMPTY_INT_ITERATOR| Modifier and Type | Method and Description |
|---|---|
default void |
addAllTo(java.util.Collection<? super java.lang.Integer> collection)
Add all entries of this countable to the given collection.
|
default int |
addToArray(int[] array,
int arrayPos)
Add the complete content of this countable to the given array.
|
default IntCountable.Base |
asBase()
Convert this into a base countable.
|
default java.util.Collection<java.lang.Integer> |
asCollection()
View this countable as an unmodifiable standard Java collection.
|
static IntCountable |
empty()
Get an empty countable.
|
default PrimitiveIntIterable |
filtered(java.util.function.IntPredicate filter)
Get a filtered view of this countable.
|
default int |
first()
Get the first value.
|
default IntIndexable |
frozen()
Get a frozen version of this countable.
|
default boolean |
isEmpty()
Is this countable empty?
|
default <E> boolean |
isEqual(IntCountable other)
Does this countable equal another one?
|
default boolean |
isSorted(IntOrdering order)
Is this countable ordered according to the given sort order?
|
default boolean |
isStrictlySorted(IntOrdering order)
Is this countable strictly ordered according to the given sort order?
|
default int |
last()
Get the last value.
|
static IntCountable |
singleton(int singleValue)
Get an int countable with a single value.
|
default IntIndexable |
sorted(IntOrdering order)
Get a sorted frozen version of this countable.
|
default int[] |
toArray()
Copy the content of this countable to an array.
|
default java.util.ArrayList<java.lang.Integer> |
toList()
Get a list which is the copy of this countable.
|
static java.lang.String |
toString(IntCountable countable)
Create a string representation of the given countable.
|
static IntCountable |
uniform(int value,
int count)
Get a countable which is returning the same value multiple times.
|
default <R> Countable<R> |
view(java.util.function.IntFunction<? extends R> mapper)
View this int countable as if it has another type.
|
static IntCountable |
viewCollection(java.util.Collection<? extends java.lang.Number> collection)
View a collection as if it were a countable.
|
static <E> IntCountable |
viewCollection(java.util.Collection<E> collection,
java.util.function.ToIntFunction<? super E> intMapper)
View a collection as if it were a countable.
|
static IntCountable |
viewCollectionN(java.util.Collection<? extends java.lang.Number> collection)
View a collection which is potentially
null as if it were a countable. |
static <E> IntCountable |
viewCollectionN(java.util.Collection<E> collection,
java.util.function.ToIntFunction<? super E> intMapper)
View a collection which is potentially {qcode null}as if it were a countable.
|
average, containsInt, forEachInt, forEachIntFragile, intIterator, iterator, longSum, longSumX, spliterator, stream, sum, sumXstatic final IntCountable EMPTY
empty().default boolean isEmpty()
Sizeable.size()
will return 0.
This default implementation just checks for Sizeable.size() returning 0
true if this countable is empty, false otherwise.
Because calculating the size might be expensive sometimes in these cases
implementations should override this method if possible.
@NotNull default java.util.Collection<java.lang.Integer> asCollection()
Collection view of this countable@NotNull default java.util.ArrayList<java.lang.Integer> toList()
default void addAllTo(@NotNull java.util.Collection<? super java.lang.Integer> collection)
collection - collection where all entries are added@NotNull default int[] toArray()
default int addToArray(@NotNull int[] array, int arrayPos)
array - array where the content is addedarrayPos - start position in hte array where the content is added@NotNull default <R> Countable<R> view(@NotNull java.util.function.IntFunction<? extends R> mapper)
R - resulting element typemapper - converter from elements of this countable to elements of the returned countable@NotNull default PrimitiveIntIterable filtered(@NotNull java.util.function.IntPredicate filter)
filter - check which defines the elements which are included in the returned Iterable.filter accepts@NotNull default IntIndexable sorted(@NotNull IntOrdering order)
Often Indexables are used as a view to underlying collections. Although this interface is immutable, the underlying collection might nevertheless change. This method copies the current state of this countable into an unmodifiable state, and returns an Indexable which is sorted, stable in size and will always return the same elements in the given order.
order - ordering condition for the returned indexabledefault boolean isSorted(@NotNull IntOrdering order)
isStrictlySorted(IntOrdering) for a check which does not accept that.
Empty or 1-element countables will always return true.order - order which is checkedtrue if the elements in this countable are ordered considering the given orderfalse if notdefault boolean isStrictlySorted(@NotNull IntOrdering order)
isSorted(IntOrdering) for a check which is more relaxed.
Empty or 1-element countables will always return true.order - order which is checkedtrue if the elements in this countable are ordered considering the given orderfalse if not@NotNull default IntIndexable frozen()
Often Countables are used as a view to underlying collections. Although this interface is immutable, the underlying collection might nevertheless change. This copies the current state of this countable into an unmodifiable state, and returns a Countable which is stable in size and will returns always the same elements. This method also takes care of possibly mutable elements, which are copied when freezing and possibly also on getting.
Calling frozen() again on the returned object will just return
the object itself, but calling this method again will always create a
new object.
default int first()
java.util.NoSuchElementException - if this countable is emptydefault int last()
@NotNull default IntCountable.Base asBase()
Object.equals(Object), Object.hashCode(),
and Object.toString().default <E> boolean isEqual(@NotNull IntCountable other)
This method is more flexible than standard Object.equals(Object)
because it allows to define the check for element equality.
E - element type of other countableother - other countabletrue if this and the other countable are considered equal regarding the given element checkfalse if not@NotNull static IntCountable viewCollection(@NotNull java.util.Collection<? extends java.lang.Number> collection)
As this is a view any changes in the underlying collection
will be reflected from the returned Countable.
If this may pose a problem copy the collection first:
Countable.viewCollection(new ArrayList<>(collection));
collection - collection to viewcollection@NotNull static IntCountable viewCollectionN(@Nullable java.util.Collection<? extends java.lang.Number> collection)
null as if it were a countable.
This creates read-only access to the underlying collection.
As this is a view any changes in the underlying collection
will be reflected from the returned Countable.
If this may pose a problem copy the collection first:
or call frozen() on the returned countableCountable.viewCollection(new ArrayList<>(collection));
collection - collection to viewcollection, empty
if collection is null@NotNull static <E> IntCountable viewCollection(@NotNull java.util.Collection<E> collection, @NotNull java.util.function.ToIntFunction<? super E> intMapper)
As this is a view any changes in the underlying collection
will be reflected from the returned Countable.
If this may pose a problem copy the collection first:
Countable.viewCollection(new ArrayList<>(collection));
E - valeu type of the collectioncollection - collection to viewintMapper - mapper from the collection's value type to intcollection@NotNull static <E> IntCountable viewCollectionN(@Nullable java.util.Collection<E> collection, @NotNull java.util.function.ToIntFunction<? super E> intMapper)
As this is a view any changes in the underlying collection
will be reflected from the returned Countable.
If this may pose a problem copy the collection first:
Countable.viewCollection(new ArrayList<>(collection));
E - valeu type of the collectioncollection - collection to viewintMapper - mapper from the collection's value type to intcollection@NotNull static IntCountable empty()
null.@NotNull static IntCountable singleton(int singleValue)
singleValue - single value of this countable@NotNull static IntCountable uniform(int value, int count)
value - value returned from this countable on each next() call of its iteratorcount - number of times the same value is returned from the iterator, must not be negativevalue count times during iteration@NotNull static java.lang.String toString(@NotNull IntCountable countable)
countable - countable