org.python.core.buffer

## Class BaseArrayBuffer

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

All Implemented Interfaces:
  java.lang.AutoCloseable, BufferProtocol, PyBUF, PyBuffer

Direct Known Subclasses:
  SimpleBuffer, Strided1DBuffer, ZeroByteBuffer

    public abstract class BaseArrayBuffer
    extends Base1DBuffer

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

### 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
`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` `copyFrom(PyBuffer src)` Copy the whole of another `PyBuffer` into this buffer.
`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, 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 implementation in `BaseArrayBuffer` 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

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

#### copyFrom

    public void copyFrom(PyBuffer src)
                  throws java.lang.IndexOutOfBoundsException,
                         PyException

Description copied from class: `BaseBuffer`
Copy the whole of another `PyBuffer` into this buffer. This may validly be done only for buffers that are consistent in their dimensions. When it is necessary to copy partial buffers, this may be achieved using a buffer slice on the source or 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.

Specified by:
  `copyFrom` in interface `PyBuffer`
Overrides:
  `copyFrom` in class `BaseBuffer`
Parameters:
  `src` - source buffer
Throws:
  `java.lang.IndexOutOfBoundsException` - if access out of bounds in source or destination
  `PyException` - `TypeError` if read-only buffer

#### getBuf

    public PyBuffer.Pointer getBuf()

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.

`BaseArrayBuffer` provides a reference to the storage array even when the buffer is intended not to be writable. There can be no enforcement of read-only character once a reference to the byte array has been handed out.

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