org.python.core.buffer

## Class SimpleBuffer

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

All Implemented Interfaces:
  AutoCloseable, BufferProtocol, PyBUF, PyBuffer

Direct Known Subclasses:
  SimpleStringBuffer, SimpleWritableBuffer

    public class SimpleBuffer
    extends BaseBuffer

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(byte[] storage)` Provide an instance of `SimpleBuffer`, on the entirety of a byte array, with navigation variables initialised, for sub-class use.
`SimpleBuffer(byte[] storage, int index0, int size)` Provide an instance of `SimpleBuffer` with navigation variables initialised, for sub-class use.
`SimpleBuffer(int flags, 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, 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

Methods
`byte` `byteAt(int... indices)` Return the byte indexed from an N-dimensional buffer with item size one.
`byte` `byteAt(int index)` Return the byte indexed from a one-dimensional buffer with item size one.
`void` `copyTo(int srcIndex, byte[] dest, int destPos, int length)` Copy a simple slice of the buffer to the destination byte array, defined by a starting index and length in the source buffer.
`PyBuffer` `getBufferSlice(int flags, int start, int length)` Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
`PyBuffer` `getBufferSlice(int flags, int start, int length, 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 units (bytes) stored, which will be the product of the elements of the `shape` array, and the item size in units.
`ByteBuffer` `getNIOByteBuffer()` Obtain a `ByteBuffer` giving access to the bytes that hold the data being exported to the consumer.
`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.
`int` `intAt(int index)` Return the unsigned byte value indexed from a one-dimensional buffer with item size one.
`boolean` `isReadonly()` Determine whether the consumer is entitled to write to the exported storage.
`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.BaseBuffer

`close, copyFrom, copyFrom, copyTo, getBuf, getBuffer, getBufferAgain, getFormat, getItemsize, getNdim, getShape, getStrides, getSuboffsets, hasArray, intAt, isContiguous, isReleased, release, storeAt, storeAt`

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

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

### Constructor Detail

#### SimpleBuffer

    public SimpleBuffer(byte[] storage,
                int index0,
                int size)
                 throws PyException,
                        ArrayIndexOutOfBoundsException

Provide an instance of `SimpleBuffer` with navigation variables initialised, for sub-class use. The buffer (`BaseBuffer.storage`, `BaseBuffer.index0`), and the `BaseBuffer.shape` array will be initialised from the arguments (which are checked for range). The `BaseBuffer.strides` is set for (one-byte) unit stride. Only the call to `BaseBuffer.checkRequestFlags(int)`, passing the consumer's request flags really remains for the sub-class constructor to do.

     super(storage, index0, size);
     checkRequestFlags(flags);        // Check request is compatible with type

Parameters:
  `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:
  `NullPointerException` - if `storage` is null
  `ArrayIndexOutOfBoundsException` - if `index0` and `size` are inconsistent with `storage.length`
  `PyException`

#### SimpleBuffer

    public SimpleBuffer(int flags,
                byte[] storage,
                int index0,
                int size)
                 throws PyException,
                        ArrayIndexOutOfBoundsException,
                        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
  `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:
  `NullPointerException` - if `storage` is null
  `ArrayIndexOutOfBoundsException` - if `index0` and `size` are inconsistent with `storage.length`
  `PyException` - (BufferError) when expectations do not correspond with the type

#### SimpleBuffer

    public SimpleBuffer(byte[] storage)
                 throws NullPointerException

Provide an instance of `SimpleBuffer`, on the entirety of a byte array, with navigation variables initialised, for sub-class use. The buffer ( `BaseBuffer.storage`, `BaseBuffer.index0`), and the navigation (`BaseBuffer.shape` array) will be initialised from the array argument.

Parameters:
  `storage` - the array of bytes storing the implementation of the exporting object
Throws:
  `NullPointerException` - if `storage` is null

#### SimpleBuffer

    public SimpleBuffer(int flags,
                byte[] storage)
                 throws PyException,
                        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
  `storage` - the array of bytes storing the implementation of the exporting object
Throws:
  `NullPointerException` - if `storage` is null
  `PyException` - (BufferError) when expectations do not correspond with the type

### Method Detail

#### isReadonly

    public boolean isReadonly()

Description copied from interface: `PyBUF`
Determine whether the consumer is entitled to write to the exported storage.

Specified by:
  `isReadonly` in interface `PyBUF`
Overrides:
  `isReadonly` in class `BaseBuffer`
Returns:
  true if writing is not allowed, false if it is.

#### getLen

    public int getLen()

The total number of units (bytes) stored, which will be the product of the elements of the `shape` array, and the item size in units.

The default implementation in `BaseBuffer` deals with the general one-dimensional case, with any item size and stride.

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

Specified by:
  `getLen` in interface `PyBUF`
Overrides:
  `getLen` in class `BaseBuffer`
Returns:
  the total number of units stored.

#### byteAt

    public byte byteAt(int index)
                throws IndexOutOfBoundsException

Return the byte indexed from a one-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. Results are undefined where the number of dimensions is not one or if `itemsize>1`.

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

Specified by:
  `byteAt` in interface `PyBuffer`
Overrides:
  `byteAt` in class `BaseBuffer`
Parameters:
  `index` - to retrieve from
Returns:
  the item at index, which is a byte
Throws:
  `IndexOutOfBoundsException`

#### intAt

    public int intAt(int index)
              throws IndexOutOfBoundsException

Return the unsigned byte value indexed from a one-dimensional buffer with item size one. This is part of the fully-encapsulated API: the exporter takes care of navigating the structure of the buffer. Results are undefined where the number of dimensions is not one or if `itemsize>1`.

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

Specified by:
  `intAt` in interface `PyBuffer`
Overrides:
  `intAt` in class `BaseBuffer`
Parameters:
  `index` - to retrieve from
Returns:
  the item at index, treated as an unsigned byte, `=0xff & byteAt(index)`
Throws:
  `IndexOutOfBoundsException`

#### byteAt

    public byte byteAt(int... indices)
                throws IndexOutOfBoundsException

Return the byte indexed from an N-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. The indices must be correct in number and range for the array shape. Results are undefined where `itemsize>1`.

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

Specified by:
  `byteAt` in interface `PyBuffer`
Overrides:
  `byteAt` in class `BaseBuffer`
Parameters:
  `indices` - specifying location to retrieve from
Returns:
  the item at location, which is a byte
Throws:
  `IndexOutOfBoundsException`

#### copyTo

    public void copyTo(int srcIndex,
              byte[] dest,
              int destPos,
              int length)
                throws IndexOutOfBoundsException

Copy a simple slice of the buffer to the destination byte array, defined by a starting index and length in the source buffer. This may validly be done only for a one-dimensional buffer, as the meaning of the starting index is otherwise not defined. The length (like the source index) is in source buffer items: `length*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.

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

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

#### getBufferSlice

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

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
  `length` - number of items in the required slice
Returns:
  a buffer representing the slice

#### getBufferSlice

    public PyBuffer getBufferSlice(int flags,
                          int start,
                          int length,
                          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, `length` = 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, `length` 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 length 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
  `length` - 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

#### getNIOByteBuffer

    public ByteBuffer getNIOByteBuffer()

Description copied from interface: `PyBuffer`
Obtain a `ByteBuffer` giving access to the bytes that hold 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();
     ByteBuffer bb = a.getNIOBuffer();

the item with index `bb.pos()+k` is in the buffer `bb` at positions `bb.pos()+k*itemsize` to `bb.pos()+(k+1)*itemsize - 1` inclusive. And if `itemsize==1`, the item is simply the byte at position `bb.pos()+k`. The buffer limit is set to the first byte beyond the valid data. A block read or write will therefore access the contents sequentially.

If the buffer is multidimensional or non-contiguous (strided), the buffer position is still the (first byte of) the item at index `[0]` or `[0,...,0]`, and the limit is one item beyond the valid data. However, it is necessary to navigate `bb` using the `shape`, `strides` and maybe `suboffsets` provided by the API.

Specified by:
  `getNIOByteBuffer` in interface `PyBuffer`
Overrides:
  `getNIOByteBuffer` in class `BaseBuffer`
Returns:
  a ByteBuffer equivalent to the exported data contents.

#### getPointer

    public PyBuffer.Pointer getPointer(int index)
                                throws 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:
  `IndexOutOfBoundsException`

#### getPointer

    public PyBuffer.Pointer getPointer(int... indices)
                                throws 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 units, 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:
  `IndexOutOfBoundsException`

#### toString

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