uk.ac.starlink.table

## Class EmptyRowSequence

- java.lang.Object
- - uk.ac.starlink.table.EmptyRowSequence

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, RowAccess, RowData, RowSequence, RowSplittable, Sequence, Splittable<RowSplittable>

      public class EmptyRowSequence
      extends java.lang.Object
      implements RowSplittable, RowAccess

  Implementation of both RowSequence and RowAccess which has no rows. Singleton class.
  Since:
    28 Oct 2004

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Does nothing.
    `java.lang.Object` | `getCell(int icol)` Always throws IllegalStateException.
    `static EmptyRowSequence` | `getInstance()` Returns singleton instance of this class.
    `java.lang.Object[]` | `getRow()` Always throws IllegalStateException.
    `boolean` | `next()` Always returns false.
    `java.util.function.LongSupplier` | `rowIndex()` Returns a supplier for the index of the row currently being processed, if possible.
    `void` | `setRowIndex(long irow)` Sets the row index to which subsequent data accesses will refer.
    `RowSplittable` | `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### next

          public boolean next()

      Always returns false.
      Specified by:
        `next` in interface `RowSequence`
      Specified by:
        `next` in interface `Sequence`
      Returns:
        `true` iff this sequence has been advanced to the next row

    - #### setRowIndex

          public void setRowIndex(long irow)

      Description copied from interface: `RowAccess`
      Sets the row index to which subsequent data accesses will refer.

      This method must be called before the first invocation of `RowAccess.getCell(int)`/`RowAccess.getRow()`, otherwise behaviour is undefined (but implementations will likely throw an unchecked exception on subsequent getCell/getRow calls). The effect of setting the value to an out of range value is undefined; it may throw an exception here, or during subsequent calls, or behave otherwise.

      Specified by:
        `setRowIndex` in interface `RowAccess`
      Parameters:
        `irow` - row index

    - #### rowIndex

          public java.util.function.LongSupplier rowIndex()

      Description copied from interface: `RowSplittable`
      Returns a supplier for the index of the row currently being processed, if possible. The row index is a global value; when accessing the first row of a top-level RowSplittable, the value returned by this supplier should be the first index in the table. But for objects resulting from splitting a top-level instance into sub-instances, the return value should reflect the index in the original sequence of rows; each index should be returned from only one of the splittables resulting from splitting a top-level instance.

      Typically, the row index will start at 0 and increment for each row, but the numbering may be different depending on the requirements of the implementation or usage.

      Before the `RowSequence.next()` method has been called, the return value will be one less than the first row index. After `RowSequence.next` has returned false, the value is undefined.

      Depending on the implementation, it may not be possible to determine the row index (for instance if the sequence is split into sub-splittables of unknown size). In such cases, this method returns null. The null-ness of the return value must be the same for all instances of the splittable hierarchy for a given sequence, so don't return a non-null value for the first splittable and then null values for some or all of its children.

      Specified by:
        `rowIndex` in interface `RowSplittable`
      Returns:
        supplier for the globally-referenced row index value of the current row of this sequence, or null

    - #### split

          public RowSplittable split()

      Description copied from interface: `Splittable`
      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.

      Specified by:
        `split` in interface `Splittable<RowSplittable>`
      Returns:
        other half of this splittable, or null
      See Also:
        `Spliterator.trySplit()`

    - #### splittableSize

          public long splittableSize()

      Description copied from interface: `Splittable`
      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.

      Specified by:
        `splittableSize` in interface `Splittable<RowSplittable>`
      Returns:
        approximate size, or negative value if not known

    - #### getCell

          public java.lang.Object getCell(int icol)

      Always throws IllegalStateException.
      Specified by:
        `getCell` in interface `RowAccess`
      Specified by:
        `getCell` in interface `RowData`
      Specified by:
        `getCell` in interface `RowSequence`
      Parameters:
        `icol` - column index
      Returns:
        the contents of cell `icol` in the current row

    - #### getRow

          public java.lang.Object[] getRow()

      Always throws IllegalStateException.
      Specified by:
        `getRow` in interface `RowAccess`
      Specified by:
        `getRow` in interface `RowData`
      Specified by:
        `getRow` in interface `RowSequence`
      Returns:
        an array of the objects in each cell in row `irow`

    - #### close

          public void close()

      Does nothing.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `RowAccess`
      Specified by:
        `close` in interface `RowSequence`

    - #### getInstance

          public static EmptyRowSequence getInstance()

      Returns singleton instance of this class.
      Returns:
        instance