Package it.unimi.dsi.fastutil.floats

Class FloatSpliterators

java.lang.Object
it.unimi.dsi.fastutil.floats.FloatSpliterators
public final class FloatSpliterators extends 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:

  • Field Details

    • COLLECTION_SPLITERATOR_CHARACTERISTICS

      public static final int COLLECTION_SPLITERATOR_CHARACTERISTICS
      See Also:

    • LIST_SPLITERATOR_CHARACTERISTICS

      public static final int LIST_SPLITERATOR_CHARACTERISTICS
      See Also:

    • SET_SPLITERATOR_CHARACTERISTICS

      public static final int SET_SPLITERATOR_CHARACTERISTICS
      See Also:

    • SORTED_SET_SPLITERATOR_CHARACTERISTICS

      public static final int SORTED_SET_SPLITERATOR_CHARACTERISTICS
      See Also:

    • EMPTY_SPLITERATOR

      public static final FloatSpliterators.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 Details

    • singleton

      public static FloatSpliterator singleton(float 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 FloatSpliterator singleton(float element, FloatComparator 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 when Spliterator.getComparator() is called.
      Returns:
      a spliterator that iterates just over element.

    • wrap

      public static FloatSpliterator wrap(float[] 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 index offset.

      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 of array starting at position offset.

    • wrap

      public static FloatSpliterator wrap(float[] 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 FloatSpliterator wrap(float[] 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 index offset.

      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 in additionalCharacteristics (for example, if the caller knows the backing array has distinct elements, they can pass Spliterator.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 of array starting at position offset.

    • wrapPreSorted

      public static FloatSpliterator wrapPreSorted(float[] array, int offset, int length, int additionalCharacteristics, FloatComparator 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 index offset.

      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 in additionalCharacteristics (for example, if the caller knows the backing array has distinct elements, they can pass Spliterator.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 (or null for natural ordering)
      Returns:
      a spliterator that will iterate over length elements of array starting at position offset.

    • wrapPreSorted

      public static FloatSpliterator wrapPreSorted(float[] array, int offset, int length, FloatComparator 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 index offset.

      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 (or null for natural ordering)
      Returns:
      a spliterator that will iterate over length elements of array starting at position offset.

    • wrapPreSorted

      public static FloatSpliterator wrapPreSorted(float[] array, FloatComparator 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 (or null for natural ordering)
      Returns:
      a spliterator that will iterate over length elements of array starting at position offset.

    • asFloatSpliterator

      public static FloatSpliterator asFloatSpliterator(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 by i: 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.

    • asFloatSpliterator

      public static FloatSpliterator asFloatSpliterator(Spliterator i, FloatComparator 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 by i: changes to one of the spliterators will affect the other, too.

      This method will cause the returned spliterator's Spliterator.getComparator() method to always return comparatorOverride, regardless of what the wrapped spliterator's getComparator() 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 a getComparator() that returns a properly typed comparator.

      Parameters:
      i - a spliterator.
      comparatorOverride - the comparator to return when Spliterator.getComparator()
      Returns:
      a type-specific spliterator backed by i.

    • narrow

      public static FloatSpliterator narrow(Spliterator.OfDouble i)
      Wrap a JDK primitive spliterator to a type-specific spliterator, making checked narrowed casts.

      The tryAdvance method throws IllegalArgumentException if any element would underflow or overflow.

      Parameters:
      i - a spiterator
      Returns:
      a type-specific spliterator backed by i

    • widen

      public static DoubleSpliterator widen(FloatSpliterator i)
      Wrap a type-specific spliterator to a JDK compatible primitive spliterator.
      Parameters:
      i - a spliterator
      Returns:
      a JDK compatible primitive spliterator backed by i

    • onEachMatching

      public static void onEachMatching(FloatSpliterator spliterator, FloatPredicate predicate, FloatConsumer action)
      Perform the given action on each element that matches the given predicate.

      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(FloatSpliterator spliterator, DoublePredicate predicate, DoubleConsumer action)
      Perform the given action on each element that matches the given predicate.

      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).

    • concat

      public static FloatSpliterator concat(FloatSpliterator... 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's Spliterator.getComparator() will always throw IllegalStateException, 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 FloatSpliterator concat(FloatSpliterator[] 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 by a[offset + 1], and so on up to a[offset + length - 1].

      Note: Due to there being no way to ensure the Comparator is consistent between each inner spliterator, the returned spliterator's Spliterator.getComparator() will always throw IllegalStateException, 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 of a starting at offset.

    • asSpliterator

      public static FloatSpliterator asSpliterator(FloatIterator iter, long size, int additionalCharacterisitcs)
      Wrap a type-specific Iterator of a known size as a type-specific Spliterator

      The returned spliterator will report characteristics additionalCharacterisitcs, and for primitive types, Spliterator.NONNULL. It will also report Spliterator.SIZED, Spliterator.SUBSIZED, unless Spliterator.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's Spliterator.trySplit() will have linear runtime.

      Parameters:
      iter - the type-specific Iterator to wrap
      size - the number of elements the iterator will return
      additionalCharacterisitcs - any additional characteristics to report
      Returns:
      a type-specific Spliterator that will give the same elements the iterator will return.
      See Also:

    • asSpliteratorFromSorted

      public static FloatSpliterator asSpliteratorFromSorted(FloatIterator iter, long size, int additionalCharacterisitcs, FloatComparator comparator)
      Wrap a type-specific, sorted Iterator of a known size as a type-specific Spliterator

      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 report Spliterator.SIZED, Spliterator.SUBSIZED, unless Spliterator.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's Spliterator.trySplit() will have linear runtime.

      Parameters:
      iter - the type-specific Iterator to wrap
      size - the number of elements the iterator will return
      additionalCharacterisitcs - any additional characteristics to report
      comparator - the comparator the iterator is ordered on (or null for natural ordering)
      Returns:
      a type-specific Spliterator that will give the same elements the iterator will return.

    • asSpliteratorUnknownSize

      public static FloatSpliterator asSpliteratorUnknownSize(FloatIterator iter, int characterisitcs)
      Wrap a type-specific Iterator of an unknown size as a type-specific Spliterator

      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's Spliterator.trySplit() will have linear runtime.

      Parameters:
      iter - the type-specific Iterator to wrap
      characterisitcs - the characteristics to report
      Returns:
      a type-specific Spliterator that will give the same elements the iterator will return.
      See Also:

    • asSpliteratorFromSortedUnknownSize

      public static FloatSpliterator asSpliteratorFromSortedUnknownSize(FloatIterator iter, int additionalCharacterisitcs, FloatComparator comparator)
      Wrap a type-specific, sorted Iterator of an unknown size as a type-specific Spliterator

      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's Spliterator.trySplit() will have linear runtime.

      Parameters:
      iter - the type-specific Iterator to wrap
      additionalCharacterisitcs - the characteristics to report
      comparator - the comparator the iterator is ordered on (or null for natural ordering)
      Returns:
      a type-specific Spliterator that will give the same elements the iterator will return.

    • asIterator

      public static FloatIterator asIterator(FloatSpliterator spliterator)
      Wrap a type-specific Spliterator as a type-specific Iterator
      Parameters:
      spliterator - the type-specific Spliterator to wrap
      Returns:
      a type-specific Iterator that will return the same elements the spliterator will give.
      See Also:

    • wrap

      public static FloatSpliterator wrap(ByteSpliterator spliterator)
      Returns a spliterator backed by the specified byte spliterator.

      Note: Due to the incompatibility of primitive Comparator types, the returned spliterator's Spliterator.getComparator() will always throw IllegalStateException, even when the underlying spliterator is sorted.

      Parameters:
      spliterator - a byte spliterator.
      Returns:
      a spliterator backed by the specified byte spliterator.

    • wrap

      public static FloatSpliterator wrap(ShortSpliterator spliterator)
      Returns a spliterator backed by the specified short spliterator.

      Note: Due to the incompatibility of primitive Comparator types, the returned spliterator's Spliterator.getComparator() will always throw IllegalStateException, even when the underlying spliterator is sorted.

      Parameters:
      spliterator - a short spliterator.
      Returns:
      a spliterator backed by the specified short spliterator.

    • wrap

      public static FloatSpliterator wrap(CharSpliterator spliterator)
      Returns a spliterator backed by the specified char 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.

      Note: Due to the incompatibility of primitive Comparator types, the returned spliterator's Spliterator.getComparator() will always throw IllegalStateException, even when the underlying spliterator is sorted.

      Parameters:
      spliterator - a char spliterator.
      Returns:
      a spliterator backed by the specified char spliterator.