uk.ac.starlink.util

## Interface Splittable<S extends Splittable<S>>

- All Known Subinterfaces:
    RowSplittable
  All Known Implementing Classes:
    EmptyRowSequence, MappingRowSplittable, ProgressRowSplittable, RandomRowSplittable, SequentialRowSplittable

      public interface Splittable<S extends Splittable<S>>

  Defines an object which can be split into two for subdivided processing.

  This does a similar job to `Spliterator`, but it imposes no assumptions about the form of the split objects, for instance that they form a sequence that can be iterated over internally, which idiom forms the basis of the Java 8 streams framework. Collections or sequences based on Splittable can use external iteration, which allows better control in some cases.

  Since:
    12 Sep 2019

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `S` | `split()` Attempts to partition this object into two halves, ideally of similar size.
    `long` | `splittableSize()` Provides an estimate of the number of processable items in this object.

- - ### Method Detail

    - #### split

          S split()

      Attempts to partition this object into two halves, ideally of similar size. If a non-null value is returned, then the content previously contained by this object is now split between this object and the returned object. If for any reason a split is not carried out, null is returned.

      Following a successful call, the two parts may be processed in different threads.

      Returns:
        other half of this splittable, or null
      See Also:
        `Spliterator.trySplit()`

    - #### splittableSize

          long splittableSize()

      Provides an estimate of the number of processable items in this object. A processable item is not a well-defined quantity, but it should generally be something that can be processed fast. For instance, if this object represents a collection of collections, the value that should be returned is the total number of elements rather than the number of collections.

      If no estimate for the size is available, a negative value should be returned.

      Returns:
        approximate size, or negative value if not known