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

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