Class CharSpliterators
- java.lang.Object
-
- it.unimi.dsi.fastutil.chars.CharSpliterators
-
public final class CharSpliterators extends java.lang.Object
A class providing static methods and objects that do useful things with type-specific spliterators.- Since:
- 8.5.0
- Author:
- C. Sean Young <csyoung@google.com>
- See Also:
Spliterators
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
CharSpliterators.AbstractIndexBasedSpliterator
A skeletal implementation for a spliterator backed by an index based data store.static class
CharSpliterators.EarlyBindingSizeIndexBasedSpliterator
A skeletal implementation for a spliterator backed by an index based data store.static class
CharSpliterators.EmptySpliterator
A class returning no elements and a type-specific spliterator interface.static class
CharSpliterators.LateBindingSizeIndexBasedSpliterator
A skeletal implementation for a spliterator backed by an index based data store.
-
Field Summary
Fields Modifier and Type Field Description static int
COLLECTION_SPLITERATOR_CHARACTERISTICS
static CharSpliterators.EmptySpliterator
EMPTY_SPLITERATOR
An empty spliterator.static int
LIST_SPLITERATOR_CHARACTERISTICS
static int
SET_SPLITERATOR_CHARACTERISTICS
static int
SORTED_SET_SPLITERATOR_CHARACTERISTICS
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static CharSpliterator
asCharSpliterator(java.util.Spliterator i)
Wraps a standard spliterator into a type-specific spliterator.static CharSpliterator
asCharSpliterator(java.util.Spliterator i, CharComparator comparatorOverride)
Wraps a standard spliterator into a type-specific spliterator.static CharIterator
asIterator(CharSpliterator spliterator)
Wrap a type-specificSpliterator
as a type-specificIterator
static CharSpliterator
asSpliterator(CharIterator iter, long size, int additionalCharacterisitcs)
Wrap a type-specificIterator
of a known size as a type-specificSpliterator
static CharSpliterator
asSpliteratorFromSorted(CharIterator iter, long size, int additionalCharacterisitcs, CharComparator comparator)
Wrap a type-specific, sortedIterator
of a known size as a type-specificSpliterator
static CharSpliterator
asSpliteratorFromSortedUnknownSize(CharIterator iter, int additionalCharacterisitcs, CharComparator comparator)
Wrap a type-specific, sortedIterator
of an unknown size as a type-specificSpliterator
static CharSpliterator
asSpliteratorUnknownSize(CharIterator iter, int characterisitcs)
Wrap a type-specificIterator
of an unknown size as a type-specificSpliterator
static CharSpliterator
concat(CharSpliterator... a)
Concatenates all spliterators contained in an array.static CharSpliterator
concat(CharSpliterator[] a, int offset, int length)
Concatenates a sequence of spliterators contained in an array.static CharSpliterator
fromTo(char from, char to)
Creates a type-specific spliterator over an interval.static CharSpliterator
narrow(java.util.Spliterator.OfInt i)
Wrap a JDK primitive spliterator to a type-specific spliterator, making checked narrowed casts.static void
onEachMatching(CharSpliterator spliterator, CharPredicate predicate, CharConsumer action)
Perform the givenaction
on each element that matches the givenpredicate
.static void
onEachMatching(CharSpliterator spliterator, java.util.function.IntPredicate predicate, java.util.function.IntConsumer action)
Perform the givenaction
on each element that matches the givenpredicate
.static CharSpliterator
singleton(char element)
Returns a spliterator that iterates just over the given element.static CharSpliterator
singleton(char element, CharComparator comparator)
Returns a spliterator that iterates just over the given element.static IntSpliterator
widen(CharSpliterator i)
Wrap a type-specific spliterator to a JDK compatible primitive spliterator.static CharSpliterator
wrap(char[] array)
Wraps the given array into a type-specific spliterator.static CharSpliterator
wrap(char[] array, int offset, int length)
Wraps the given part of an array into a type-specific spliterator.static CharSpliterator
wrap(char[] array, int offset, int length, int additionalCharacteristics)
Wraps the given part of an array into a type-specific spliterator.static CharSpliterator
wrapPreSorted(char[] array, int offset, int length, int additionalCharacteristics, CharComparator comparator)
Wraps the given part of a sorted array into a type-specific spliterator.static CharSpliterator
wrapPreSorted(char[] array, int offset, int length, CharComparator comparator)
Wraps the given part of a sorted array into a type-specific spliterator.static CharSpliterator
wrapPreSorted(char[] array, CharComparator comparator)
Wraps the given sorted array into a type-specific spliterator.
-
-
-
Field Detail
-
COLLECTION_SPLITERATOR_CHARACTERISTICS
public static final int COLLECTION_SPLITERATOR_CHARACTERISTICS
- See Also:
- Constant Field Values
-
LIST_SPLITERATOR_CHARACTERISTICS
public static final int LIST_SPLITERATOR_CHARACTERISTICS
- See Also:
- Constant Field Values
-
SET_SPLITERATOR_CHARACTERISTICS
public static final int SET_SPLITERATOR_CHARACTERISTICS
- See Also:
- Constant Field Values
-
SORTED_SET_SPLITERATOR_CHARACTERISTICS
public static final int SORTED_SET_SPLITERATOR_CHARACTERISTICS
- See Also:
- Constant Field Values
-
EMPTY_SPLITERATOR
public static final CharSpliterators.EmptySpliterator EMPTY_SPLITERATOR
An empty spliterator. It is serializable and cloneable.The class of this objects represent an abstract empty spliterator that can iterate as a type-specific spliterator.
-
-
Method Detail
-
singleton
public static CharSpliterator singleton(char element)
Returns a spliterator that iterates just over the given element.- Parameters:
element
- the only element to be returned by a type-specific spliterator.- Returns:
- a spliterator that iterates just over
element
.
-
singleton
public static CharSpliterator singleton(char element, CharComparator comparator)
Returns a spliterator that iterates just over the given element.The
Spliterator.getComparator()
method will return the given comparator. This is within spec because sequences of size 1 are trivially sorted for any comparison function.- Parameters:
element
- the only element to be returned by a type-specific spliterator.comparator
- the comparator to return whenSpliterator.getComparator()
is called.- Returns:
- a spliterator that iterates just over
element
.
-
wrap
public static CharSpliterator wrap(char[] array, int offset, int length)
Wraps the given part of an array into a type-specific spliterator.The type-specific spliterator returned by this method will iterate
length
times, advancing over consecutive elements of the given array starting from the one with indexoffset
.The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
, and for primitive arrays,Spliterator.NONNULL
.- Parameters:
array
- an array to wrap into a type-specific spliterator.offset
- the first element of the array to be returned.length
- the number of elements to return.- Returns:
- a spliterator that will iterate over
length
elements ofarray
starting at positionoffset
.
-
wrap
public static CharSpliterator wrap(char[] array)
Wraps the given array into a type-specific spliterator.The type-specific spliterator returned by this method will advance over all elements of the given array.
The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
, and for primitive arrays,Spliterator.NONNULL
.- Parameters:
array
- an array to wrap into a type-specific spliterator.- Returns:
- a spliterator that will iterate over the elements of
array
.
-
wrap
public static CharSpliterator wrap(char[] array, int offset, int length, int additionalCharacteristics)
Wraps the given part of an array into a type-specific spliterator.The type-specific spliterator returned by this method will iterate
length
times, advancing over consecutive elements of the given array starting from the one with indexoffset
.The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
, and for primitive arrays,Spliterator.NONNULL
, on top of any additional characteristics given inadditionalCharacteristics
(for example, if the caller knows the backing array has distinct elements, they can passSpliterator.DISTINCT
).- Parameters:
array
- an array to wrap into a type-specific spliterator.offset
- the first element of the array to be returned.length
- the number of elements to return.additionalCharacteristics
- any additional characteristics to report.- Returns:
- a spliterator that will iterate over
length
elements ofarray
starting at positionoffset
.
-
wrapPreSorted
public static CharSpliterator wrapPreSorted(char[] array, int offset, int length, int additionalCharacteristics, CharComparator comparator)
Wraps the given part of a sorted array into a type-specific spliterator.It is the caller's responsibility to ensure the array is actually sorted using the comparator given.
The type-specific spliterator returned by this method will iterate
length
times, advancing over consecutive elements of the given array starting from the one with indexoffset
.The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
,Spliterator.SORTED
, and for primitive arrays,Spliterator.NONNULL
, on top of any additional characteristics given inadditionalCharacteristics
(for example, if the caller knows the backing array has distinct elements, they can passSpliterator.DISTINCT
).- Parameters:
array
- an array to wrap into a type-specific spliterator.offset
- the first element of the array to be returned.length
- the number of elements to return.additionalCharacteristics
- any additional characteristics to report.comparator
- the comparator the array was sorted with (ornull
for natural ordering)- Returns:
- a spliterator that will iterate over
length
elements ofarray
starting at positionoffset
.
-
wrapPreSorted
public static CharSpliterator wrapPreSorted(char[] array, int offset, int length, CharComparator comparator)
Wraps the given part of a sorted array into a type-specific spliterator.It is the caller's responsibility to ensure the array is actually sorted using the comparator given.
The type-specific spliterator returned by this method will iterate
length
times, advancing over consecutive elements of the given array starting from the one with indexoffset
.The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
,Spliterator.SORTED
, and for primitive arrays,Spliterator.NONNULL
.- Parameters:
array
- an array to wrap into a type-specific spliterator.offset
- the first element of the array to be returned.length
- the number of elements to return.comparator
- the comparator the array was sorted with (ornull
for natural ordering)- Returns:
- a spliterator that will iterate over
length
elements ofarray
starting at positionoffset
.
-
wrapPreSorted
public static CharSpliterator wrapPreSorted(char[] array, CharComparator comparator)
Wraps the given sorted array into a type-specific spliterator.It is the caller's responsibility to ensure the array is actually sorted using the comparator given.
The type-specific spliterator returned by this method will advance over all elements of the given array.
The returned spliterator will report characteristics
Spliterator.SIZED
,Spliterator.SUBSIZED
,Spliterator.ORDERED
,Spliterator.SORTED
, and for primitive arrays,Spliterator.NONNULL
.- Parameters:
array
- an array to wrap into a type-specific spliterator.comparator
- the comparator the array was sorted with (ornull
for natural ordering)- Returns:
- a spliterator that will iterate over
length
elements ofarray
starting at positionoffset
.
-
asCharSpliterator
public static CharSpliterator asCharSpliterator(java.util.Spliterator i)
Wraps a standard spliterator into a type-specific spliterator.This method wraps a standard spliterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap a spliterator returning the instances of the wrong class will generate a
ClassCastException
. The returned spliterator is backed byi
: changes to one of the spliterators will affect the other, too.If
i
is already type-specific, it will returned and no new object will be generated.- Parameters:
i
- a spliterator.- Returns:
- a type-specific spliterator backed by
i
.
-
asCharSpliterator
public static CharSpliterator asCharSpliterator(java.util.Spliterator i, CharComparator comparatorOverride)
Wraps a standard spliterator into a type-specific spliterator.This method wraps a standard spliterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap a spliterator returning the instances of the wrong class will generate a
ClassCastException
. The returned spliterator is backed byi
: changes to one of the spliterators will affect the other, too.This method will cause the returned spliterator's
Spliterator.getComparator()
method to always returncomparatorOverride
, regardless of what the wrapped spliterator'sgetComparator()
method returns.NOTE:This is mostly intended for supporting default implementations in interfaces that wrap JDK spliterators, and not a general purpose method.
If
i
is already type-specific, this method will throw, as such spliterators already have agetComparator()
that returns a properly typed comparator.- Parameters:
i
- a spliterator.comparatorOverride
- the comparator to return whenSpliterator.getComparator()
- Returns:
- a type-specific spliterator backed by
i
.
-
narrow
public static CharSpliterator narrow(java.util.Spliterator.OfInt i)
Wrap a JDK primitive spliterator to a type-specific spliterator, making checked narrowed casts.The
tryAdvance
method throwsIllegalArgumentException
if any element would underflow or overflow.- Parameters:
i
- a spiterator- Returns:
- a type-specific spliterator backed by
i
-
widen
public static IntSpliterator widen(CharSpliterator i)
Wrap a type-specific spliterator to a JDK compatible primitive spliterator.WARNING: This is not the same as converting the source to a sequence of code points. This returned instance literally performs
(int)(charValue)
casts. Surrogate pairs will be left as separate elements instead of combined into a single element with the code point it represents.- Parameters:
i
- a spliterator- Returns:
- a JDK compatible primitive spliterator backed by
i
-
onEachMatching
public static void onEachMatching(CharSpliterator spliterator, CharPredicate predicate, CharConsumer action)
Perform the givenaction
on each element that matches the givenpredicate
.This is equivalent to
java.util.stream.StreamSupport.stream(spliterator).filter(predicate).forEach(action)
(substitute the proper primitive stream as needed), except it may perform better (but no potential for parallelism).
-
onEachMatching
public static void onEachMatching(CharSpliterator spliterator, java.util.function.IntPredicate predicate, java.util.function.IntConsumer action)
Perform the givenaction
on each element that matches the givenpredicate
.This is equivalent to
java.util.stream.StreamSupport.stream(spliterator).filter(predicate).forEach(action)
(substitute the proper primitive stream as needed), except it may perform better (but no potential for parallelism).
-
fromTo
public static CharSpliterator fromTo(char from, char to)
Creates a type-specific spliterator over an interval.The type-specific spliterator returned by this method will return the elements
from
,from+1
,…,to-1
.- Parameters:
from
- the starting element (inclusive).to
- the ending element (exclusive).- Returns:
- a type-specific spliterator enumerating the elements from
from
toto
.
-
concat
public static CharSpliterator concat(CharSpliterator... a)
Concatenates all spliterators contained in an array.This method returns a spliterator that will enumerate in order the elements returned by all spliterators contained in the given array.
Note: Due to there being no way to ensure the
Comparator
is consistent between each inner spliterator, the returned spliterator'sSpliterator.getComparator()
will always throwIllegalStateException
, even when if the current or even all the inner spliterators are sorted.- Parameters:
a
- an array of spliterators.- Returns:
- a spliterator obtained by concatenation.
-
concat
public static CharSpliterator concat(CharSpliterator[] a, int offset, int length)
Concatenates a sequence of spliterators contained in an array.This method returns a spliterator that will enumerate in order the elements returned by
a[offset]
, then those returned bya[offset + 1]
, and so on up toa[offset + length - 1]
.Note: Due to there being no way to ensure the
Comparator
is consistent between each inner spliterator, the returned spliterator'sSpliterator.getComparator()
will always throwIllegalStateException
, even when if the current or even all the inner spliterators are sorted.- Parameters:
a
- an array of spliterators.offset
- the index of the first spliterator to concatenate.length
- the number of spliterators to concatenate.- Returns:
- a spliterator obtained by concatenation of
length
elements ofa
starting atoffset
.
-
asSpliterator
public static CharSpliterator asSpliterator(CharIterator iter, long size, int additionalCharacterisitcs)
Wrap a type-specificIterator
of a known size as a type-specificSpliterator
The returned spliterator will report
characteristics
additionalCharacterisitcs
, and for primitive types,Spliterator.NONNULL
. It will also reportSpliterator.SIZED
,Spliterator.SUBSIZED
, unlessSpliterator.CONCURRENT
is to be reported, in which case these two are not implicitly reported.Because
Iterator
is an inherently linear API, the returned spliterator will yield limited performance gains when run in parallel contexts, as the returned spliterator'sSpliterator.trySplit()
will have linear runtime.- Parameters:
iter
- the type-specificIterator
to wrapsize
- the number of elements the iterator will returnadditionalCharacterisitcs
- any additional characteristics to report- Returns:
- a type-specific
Spliterator
that will give the same elements the iterator will return. - See Also:
Spliterators.spliterator(java.util.Iterator, long, int)
-
asSpliteratorFromSorted
public static CharSpliterator asSpliteratorFromSorted(CharIterator iter, long size, int additionalCharacterisitcs, CharComparator comparator)
Wrap a type-specific, sortedIterator
of a known size as a type-specificSpliterator
It is the caller's responsibility to ensure the iterator's order is actually sorted according to the comparator given.
The returned spliterator will report
characteristics
additionalCharacterisitcs
,Spliterator.ORDERED
,Spliterator.SORTED
, and for primitive types,Spliterator.NONNULL
. It will also reportSpliterator.SIZED
,Spliterator.SUBSIZED
, unlessSpliterator.CONCURRENT
is to be reported, in which case these two are not implicitly reported.Because
Iterator
is an inherently linear API, the returned spliterator will yield limited performance gains when run in parallel contexts, as the returned spliterator'sSpliterator.trySplit()
will have linear runtime.- Parameters:
iter
- the type-specificIterator
to wrapsize
- the number of elements the iterator will returnadditionalCharacterisitcs
- any additional characteristics to reportcomparator
- the comparator the iterator is ordered on (ornull
for natural ordering)- Returns:
- a type-specific
Spliterator
that will give the same elements the iterator will return.
-
asSpliteratorUnknownSize
public static CharSpliterator asSpliteratorUnknownSize(CharIterator iter, int characterisitcs)
Wrap a type-specificIterator
of an unknown size as a type-specificSpliterator
The returned spliterator will report
additionalCharacterisitcs
, and for primitive types,Spliterator.NONNULL
.Because
Iterator
is an inherently linear API, the returned spliterator will yield limited performance gains when run in parallel contexts, as the returned spliterator'sSpliterator.trySplit()
will have linear runtime.- Parameters:
iter
- the type-specificIterator
to wrapcharacterisitcs
- the characteristics to report- Returns:
- a type-specific
Spliterator
that will give the same elements the iterator will return. - See Also:
Spliterators.spliteratorUnknownSize(java.util.Iterator, int)
-
asSpliteratorFromSortedUnknownSize
public static CharSpliterator asSpliteratorFromSortedUnknownSize(CharIterator iter, int additionalCharacterisitcs, CharComparator comparator)
Wrap a type-specific, sortedIterator
of an unknown size as a type-specificSpliterator
It is the caller's responsibility to ensure the iterator's order is actually sorted according to the comparator given.
The returned spliterator will report
characteristics
additionalCharacterisitcs
,Spliterator.ORDERED
,Spliterator.SORTED
, and for primitive types,Spliterator.NONNULL
.Because
Iterator
is an inherently linear API, the returned spliterator will yield limited performance gains when run in parallel contexts, as the returned spliterator'sSpliterator.trySplit()
will have linear runtime.- Parameters:
iter
- the type-specificIterator
to wrapadditionalCharacterisitcs
- the characteristics to reportcomparator
- the comparator the iterator is ordered on (ornull
for natural ordering)- Returns:
- a type-specific
Spliterator
that will give the same elements the iterator will return.
-
asIterator
public static CharIterator asIterator(CharSpliterator spliterator)
Wrap a type-specificSpliterator
as a type-specificIterator
- Parameters:
spliterator
- the type-specificSpliterator
to wrap- Returns:
- a type-specific
Iterator
that will return the same elements the spliterator will give. - See Also:
Spliterators.iterator(java.util.Spliterator)
-
-