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

org.python.core.buffer

## Class SimpleBuffer

- java.lang.Object
- - org.python.core.buffer.BaseBuffer
  - - org.python.core.buffer.Base1DBuffer
    - - org.python.core.buffer.BaseArrayBuffer
      - - org.python.core.buffer.SimpleBuffer

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

      public class SimpleBuffer
      extends BaseArrayBuffer

  Buffer API over a read-only one-dimensional array of one-byte items.

- - ### 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`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleBuffer(int flags, BufferProtocol obj, byte[] storage)` Provide an instance of `SimpleBuffer`, on the entirety of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
    `SimpleBuffer(int flags, BufferProtocol obj, byte[] storage, int index0, int size)` Provide an instance of `SimpleBuffer`, on a slice of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `byteIndex(int index)` Convert an item index (for a one-dimensional buffer) to an absolute byte index in the storage shared by the exporter.
    `PyBuffer` | `getBufferSlice(int flags, int start, int count)` Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
    `PyBuffer` | `getBufferSlice(int flags, int start, int count, int stride)` Get a `PyBuffer` that represents a slice of the current one described in terms of a start index, number of items to include in the slice, and the stride in the current buffer.
    `int` | `getLen()` The total number of bytes represented by the view, which will be the product of the elements of the `shape` array, and the item size in bytes.
    `PyBuffer.Pointer` | `getPointer(int... indices)` Return a structure describing the position in a byte array of a single item from the data being exported to the consumer, in the case that array may be multi-dimensional.
    `PyBuffer.Pointer` | `getPointer(int index)` Return a structure describing the position in a byte array of a single item from the data being exported to the consumer.
    `java.lang.String` | `toString()` The toString() method of a buffer reproduces the values in the buffer (as unsigned integers) as the character codes of a `String`.

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

      `byteIndex, copyFrom, copyFrom, copyTo, getBuf`

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

      `isContiguous`

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

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

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

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

- - ### Constructor Detail

    - #### SimpleBuffer

          public SimpleBuffer(int flags,
                              BufferProtocol obj,
                              byte[] storage,
                              int index0,
                              int size)
                       throws PyException,
                              java.lang.ArrayIndexOutOfBoundsException,
                              java.lang.NullPointerException

      Provide an instance of `SimpleBuffer`, on a slice of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
      Parameters:
        `flags` - consumer requirements
        `obj` - exporting object (or `null`)
        `storage` - the array of bytes storing the implementation of the exporting object
        `index0` - offset where the data starts in that array (item[0])
        `size` - the number of bytes occupied
      Throws:
        `java.lang.NullPointerException` - if `storage` is null
        `java.lang.ArrayIndexOutOfBoundsException` - if `index0` and `size` are inconsistent with `storage.length`
        `PyException` - `BufferError` when expectations do not correspond with the type

    - #### SimpleBuffer

          public SimpleBuffer(int flags,
                              BufferProtocol obj,
                              byte[] storage)
                       throws PyException,
                              java.lang.NullPointerException

      Provide an instance of `SimpleBuffer`, on the entirety of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
      Parameters:
        `flags` - consumer requirements
        `obj` - exporting object (or `null`)
        `storage` - the array of bytes storing the implementation of the exporting object
      Throws:
        `java.lang.NullPointerException` - if `storage` is null
        `PyException` - `BufferError` when expectations do not correspond with the type

  - ### Method Detail

    - #### getLen

          public int getLen()

      The total number of bytes represented by the view, which will be the product of the elements of the `shape` array, and the item size in bytes.

      `SimpleBuffer` provides an implementation optimised for contiguous bytes in one-dimension.

      Specified by:
        `getLen` in interface `PyBUF`
      Overrides:
        `getLen` in class `Base1DBuffer`
      Returns:
        the total number of bytes represented.

    - #### byteIndex

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

      Convert an item index (for a one-dimensional buffer) 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()`). See `PyBuffer.byteIndex(int[])` for discussion of the multi-dimensional case.

      In `SimpleBuffer` the calculation is specialised for one dimension, no striding, and an item size of 1.

      Specified by:
        `byteIndex` in interface `PyBuffer`
      Overrides:
        `byteIndex` in class `BaseBuffer`
      Parameters:
        `index` - item-index from consumer
      Returns:
        corresponding byte-index in actual storage
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### getBufferSlice

          public PyBuffer getBufferSlice(int flags,
                                         int start,
                                         int count)

      Description copied from interface: `PyBuffer`
      Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
      Specified by:
        `getBufferSlice` in interface `PyBuffer`
      Overrides:
        `getBufferSlice` in class `BaseBuffer`
      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
        `start` - index in the current buffer
        `count` - number of items in the required slice
      Returns:
        a buffer representing the slice

    - #### getBufferSlice

          public PyBuffer getBufferSlice(int flags,
                                         int start,
                                         int count,
                                         int stride)

      Get a `PyBuffer` that represents a slice of the current one described in terms of a start index, number of items to include in the slice, and the stride in the current buffer. A consumer that obtains a `PyBuffer` with `getBufferSlice` must release it with `PyBuffer.release()` just as if it had been obtained with `PyBuffer.getBuffer(int)`

      Suppose that x(i) denotes the ith element of the current buffer, that is, the byte retrieved by `this.byteAt(i)` or the unit indicated by `this.getPointer(i)`. A request for a slice where `start` = s, `count` = N and `stride` = m, results in a buffer y such that y(k) = x(s+km) where k=0..(N-1). In Python terms, this is the slice x[s : s+(N-1)m+1 : m] (if m>0) or the slice x[s : s+(N-1)m-1 : m] (if m<0). Implementations should check that this range is entirely within the current buffer.

      In a simple buffer backed by a contiguous byte array, the result is a strided PyBuffer on the same storage but where the offset is adjusted by s and the stride is as supplied. If the current buffer is already strided and/or has an item size larger than single bytes, the new `start` index, `count` and `stride` will be translated from the arguments given, through this buffer's stride and item size. The caller always expresses `start` and `strides` in terms of the abstract view of this buffer.

      `SimpleBuffer` provides an implementation for slicing contiguous bytes in one dimension. In that case, x(i) = u(r+i) for i = 0..L-1 where u is the underlying buffer, and r and L are the start and count with which x was created from u. Thus y(k) = u(r+s+km), that is, the composite offset is r+s and the stride is m.

      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
        `start` - index in the current buffer
        `count` - number of items in the required slice
        `stride` - index-distance in the current buffer between consecutive items in the slice
      Returns:
        a buffer representing the slice

    - #### getPointer

          public PyBuffer.Pointer getPointer(int index)
                                      throws java.lang.IndexOutOfBoundsException

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

           int k = ... ;
           PyBuffer a = obj.getBuffer(PyBUF.FULL);
           int itemsize = a.getItemsize();
           PyBuffer.Pointer b = a.getPointer(k);

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

      Essentially this is a method for computing the offset of a particular index. The client is free to navigate the underlying buffer `b.storage` without respecting these boundaries.

      Specified by:
        `getPointer` in interface `PyBuffer`
      Overrides:
        `getPointer` in class `BaseBuffer`
      Parameters:
        `index` - in the buffer to position the pointer
      Returns:
        structure defining the byte[] slice that is the shared data
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### getPointer

          public PyBuffer.Pointer getPointer(int... indices)
                                      throws java.lang.IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Return a structure describing the position in a byte array of a single item from the data being exported to the consumer, in the case that array may be multi-dimensional. For a 3-dimensional contiguous buffer, assuming the following client code where `obj` has type `BufferProtocol`:

           int i, j, k;
           // ... calculation that assigns i, j, k
           PyBuffer a = obj.getBuffer(PyBUF.FULL);
           int itemsize = a.getItemsize();
           PyBuffer.Pointer b = a.getPointer(i,j,k);

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

      Essentially this is a method for computing the offset of a particular index. The client is free to navigate the underlying buffer `b.storage` without respecting these boundaries. If the buffer is non-contiguous, the above description is still valid (since a multi-byte item must itself be contiguously stored), but in any additional navigation of `b.storage[]` to other items, the client must use the shape, strides and sub-offsets provided by the API. Normally one starts `b = a.getBuf()` in order to establish the offset of index [0,...,0].

      Specified by:
        `getPointer` in interface `PyBuffer`
      Overrides:
        `getPointer` in class `BaseBuffer`
      Parameters:
        `indices` - multidimensional index at which to position the pointer
      Returns:
        structure defining the byte[] slice that is the shared data
      Throws:
        `java.lang.IndexOutOfBoundsException`

    - #### toString

          public java.lang.String toString()

      Description copied from class: `BaseBuffer`
      The toString() method of a buffer reproduces the values in the buffer (as unsigned integers) as the character codes of a `String`.
      Specified by:
        `toString` in interface `PyBuffer`
      Overrides:
        `toString` in class `BaseBuffer`

Jython homepage