BaseNIOBuffer (Jython API documentation)
Date: 2024-08-18

org.python.core.buffer

## Class BaseNIOBuffer

- java.lang.Object
- - org.python.core.buffer.BaseBuffer
  - - org.python.core.buffer.Base1DBuffer
    - - org.python.core.buffer.BaseNIOBuffer

- All Implemented Interfaces:
    java.lang.AutoCloseable, BufferProtocol, PyBUF, PyBuffer
  Direct Known Subclasses:
    SimpleNIOBuffer, Strided1DNIOBuffer

      public abstract class BaseNIOBuffer
      extends Base1DBuffer

  Base implementation of the Buffer API for when the storage implementation is `java.nio.ByteBuffer`. The description of `BaseBuffer` mostly applies. Methods provided or overridden here are appropriate to 1-dimensional arrays, of any item size, backed by a `ByteBuffer`.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.python.core.PyBuffer

      `PyBuffer.Pointer`

  - ### Field Summary

    - ### Fields inherited from interface org.python.core.PyBUF

      `ANY_CONTIGUOUS, AS_ARRAY, C_CONTIGUOUS, CONTIG, CONTIG_RO, CONTIGUITY, F_CONTIGUOUS, FORMAT, FULL, FULL_RO, INDIRECT, IS_C_CONTIGUOUS, IS_F_CONTIGUOUS, MAX_NDIM, NAVIGATION, ND, RECORDS, RECORDS_RO, SIMPLE, STRIDED, STRIDED_RO, STRIDES, WRITABLE`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `byteIndex(int... indices)` Convert a multi-dimensional item index to an absolute byte index in the storage shared by the exporter.
    `void` | `copyFrom(byte[] src, int srcPos, int destIndex, int count)` Copy from a slice of a (Java) byte array into the buffer starting at a given destination item-index.
    `void` | `copyTo(java.nio.ByteBuffer dest)` Copy all items in this buffer into a `ByteBuffer`, starting at its current position.
    `void` | `copyTo(int srcIndex, byte[] dest, int destPos, int count)` Copy a simple slice of the buffer-view to the destination byte array, defined by a starting item-index in the source buffer and the `count` of items to copy.
    `PyBuffer.Pointer` | `getBuf()` Return a structure describing the slice of a byte array that holds the data being exported to the consumer.

    - ### Methods inherited from class org.python.core.buffer.Base1DBuffer

      `getLen, isContiguous`

    - ### Methods inherited from class org.python.core.buffer.BaseBuffer

      `byteAt, byteAt, byteIndex, close, copyFrom, copyTo, getBuffer, getBufferAgain, getBufferSlice, getFormat, getItemsize, getNdim, getNIOByteBuffer, getObj, getPointer, getPointer, getShape, getStrides, getSuboffsets, hasArray, intAt, intAt, isReadonly, isReleased, release, storeAt, storeAt, toString`

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.python.core.PyBuffer

      `getBufferSlice`

- - ### Method Detail

    - #### byteIndex

          public int byteIndex(int... indices)
                        throws java.lang.IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Convert a multi-dimensional item index to an absolute byte index in the storage shared by the exporter. The storage exported as a `PyBuffer` is a linearly-indexed sequence of bytes, although it may not actually be a heap-allocated Java `byte[]` object. The purpose of this method is to allow the exporter to define the relationship between the item index (as used in `PyBuffer.byteAt(int...)` and the byte-index (as used with the `ByteBuffer` returned by `PyBuffer.getNIOByteBuffer()`).
      Specified by:
        `byteIndex` in interface `PyBuffer`
      Overrides:
        `byteIndex` in class `BaseBuffer`
      Parameters:
        `indices` - n-dimensional item-index from consumer
      Returns:
        corresponding byte-index in actual storage
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### copyTo

          public void copyTo(int srcIndex,
                             byte[] dest,
                             int destPos,
                             int count)
                      throws java.lang.IndexOutOfBoundsException

      Copy a simple slice of the buffer-view to the destination byte array, defined by a starting item-index in the source buffer and the `count` of items to copy. This may validly be done only for a one-dimensional buffer, as the meaning of the starting item-index is otherwise not defined. `count*itemsize` bytes will be occupied in the destination.

      The default implementation in `BaseBuffer` deals with the general one-dimensional case of arbitrary item size and stride, but is unable to optimise access to sequential bytes.

      The default implementation in `BaseNIOBuffer` deals with the general one-dimensional case of arbitrary item size and stride.

      Specified by:
        `copyTo` in interface `PyBuffer`
      Overrides:
        `copyTo` in class `BaseBuffer`
      Parameters:
        `srcIndex` - starting item-index in the source buffer
        `dest` - destination byte array
        `destPos` - byte-index in the destination array of the source item [0,...]
        `count` - number of items to copy
      Throws:
        `java.lang.IndexOutOfBoundsException` - if access out of bounds in source or destination

    - #### copyTo

          public void copyTo(java.nio.ByteBuffer dest)
                      throws java.nio.BufferOverflowException,
                             java.nio.ReadOnlyBufferException

      Copy all items in this buffer into a `ByteBuffer`, starting at its current position.
      Parameters:
        `dest` - destination buffer
      Throws:
        `java.nio.BufferOverflowException`
        `java.nio.ReadOnlyBufferException`

    - #### copyFrom

          public void copyFrom(byte[] src,
                               int srcPos,
                               int destIndex,
                               int count)
                        throws java.lang.IndexOutOfBoundsException,
                               PyException

      Copy from a slice of a (Java) byte array into the buffer starting at a given destination item-index. This may validly be done only for a one-dimensional buffer, as the meaning of the destination index is not otherwise defined. `count*itemsize` bytes will be read from the source.

      The default implementation in `BaseBuffer` deals with the general one-dimensional case of arbitrary item size and stride, but is unable to optimise access to sequential bytes.

      The default implementation in `BaseNIOBuffer` deals with the general one-dimensional case of arbitrary item size and stride.

      Specified by:
        `copyFrom` in interface `PyBuffer`
      Overrides:
        `copyFrom` in class `BaseBuffer`
      Parameters:
        `src` - source byte array
        `srcPos` - location in source of first byte to copy
        `destIndex` - starting item-index in the destination (i.e. `this`)
        `count` - number of items to copy in
      Throws:
        `java.lang.IndexOutOfBoundsException` - if access out of bounds in source or destination
        `PyException` - `TypeError` if read-only buffer

    - #### getBuf

          public PyBuffer.Pointer getBuf()

      Description copied from interface: `PyBuffer`
      Return a structure describing the slice of a byte array that holds the data being exported to the consumer. For a one-dimensional contiguous buffer, assuming the following client code where `obj` has type `BufferProtocol`:

           PyBuffer a = obj.getBuffer(PyBUF.SIMPLE);
           int itemsize = a.getItemsize();
           PyBuffer.Pointer b = a.getBuf();

      the item with index `k` is in the array `b.storage` at index `[b.offset + k*itemsize]` to `[b.offset + (k+1)*itemsize - 1]` inclusive. And if `itemsize==1`, the item is simply the byte `b.storage[b.offset + k]`

      If the buffer is multidimensional or non-contiguous, `storage[offset]` is still the (first byte of) the item at index [0] or [0,...,0]. However, it is necessary to navigate `b.storage` using the `shape`, `strides` and maybe `suboffsets` provided by the API.

      Specified by:
        `getBuf` in interface `PyBuffer`
      Overrides:
        `getBuf` in class `BaseBuffer`
      Returns:
        structure defining the byte[] slice that is the shared data

Jython homepage