public abstract class BaseArrayBuffer extends Base1DBuffer
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[]
.PyBuffer.Pointer
Modifier and Type | Field and Description |
---|---|
protected byte[] |
storage
Reference to the underlying
byte[] storage that the exporter is sharing with the
consumer. |
ONE, ZERO
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
Modifier | Constructor and Description |
---|---|
protected |
BaseArrayBuffer(byte[] storage,
int featureFlags,
int index0,
int size,
int stride)
Construct an instance of
BaseArrayBuffer in support of a sub-class, specifying
the 'feature flags', or at least a starting set to be adjusted later. |
Modifier and Type | Method and Description |
---|---|
protected byte |
byteAtImpl(int byteIndex)
Retrieve the byte at the given index in the underlying storage treated as a flat sequence of
bytes.
|
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.
|
protected void |
copyFrom(byte[] src,
int srcPos,
int srcStride,
int destIndex,
int count)
Generalisation of
PyBuffer.copyFrom(byte[], int, int, int) to allow a stride within
the source array. |
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.
|
protected java.nio.ByteBuffer |
getNIOByteBufferImpl()
Create a new
java.nio.ByteBuffer on the underlying storage, such that
positioning this buffer to a particular byte using BaseBuffer.byteIndex(int) or
BaseBuffer.byteIndex(int[]) positions it at the first byte of the item so indexed. |
protected void |
storeAtImpl(byte value,
int byteIndex)
Store the byte at the given index in the underlying storage treated as a flat sequence of
bytes.
|
calcGreatestIndex, calcLeastIndex, getLen, getSize, isContiguous
addFeatureFlags, bufferIsNot, bufferReleased, bufferRequires, byteAt, byteAt, byteIndex, checkHasArray, checkRequestFlags, checkWritable, close, copyTo, differentStructure, getBuffer, getBufferAgain, getBufferSlice, getFeatureFlags, getFormat, getItemsize, getNdim, getNIOByteBuffer, getObj, getPointer, getPointer, getRoot, getShape, getStrides, getSuboffsets, hasArray, intAt, intAt, isReadonly, isReleased, notWritable, release, releaseAction, removeFeatureFlags, setFeatureFlags, storeAt, storeAt, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getBufferSlice
protected byte[] storage
byte[]
storage that the exporter is sharing with the
consumer. The data need not occupy the whole array: in the constructor of a particular type
of buffer, the exporter usually indicates an offset to the first significant byte and length
(contiguous cases) or the index in storage
that should be treated as the item
with index zero (retrieved say by buf.byteAt(0)
).protected BaseArrayBuffer(byte[] storage, int featureFlags, int index0, int size, int stride)
BaseArrayBuffer
in support of a sub-class, specifying
the 'feature flags', or at least a starting set to be adjusted later. Also specify the
navigation ( BaseBuffer.index0
, number of elements, and stride. These 'feature flags' are the
features of the buffer exported, not the flags that form the consumer's request. The buffer
will be read-only unless PyBUF.WRITABLE
is set. PyBUF.FORMAT
and
PyBUF.AS_ARRAY
are implicitly added to the feature flags.
To complete initialisation, the sub-class normally must call BaseBuffer.checkRequestFlags(int)
passing the consumer's request flags.
storage
- the array of bytes storing the implementation of the exporting objectfeatureFlags
- bit pattern that specifies the features allowedindex0
- index into storage of item[0]
size
- number of elements in the viewstride
- byte-index distance from one element to the nextprotected byte byteAtImpl(int byteIndex) throws java.lang.IndexOutOfBoundsException
BaseBuffer
BaseBuffer.index0
, BaseBuffer.shape
, BaseBuffer.strides
,
and the item size. The caller is responsible for validating the original item-index and
raising (typically) an IndexOutOfBoundsException
. Misuse of this method may
still result in unchecked exceptions characteristic of the storage implementation.byteAtImpl
in class BaseBuffer
byteIndex
- byte-index of location to retrievejava.lang.IndexOutOfBoundsException
protected void storeAtImpl(byte value, int byteIndex) throws java.lang.IndexOutOfBoundsException, PyException
BaseBuffer
BaseBuffer.index0
, BaseBuffer.shape
, BaseBuffer.strides
,
and the item size. The caller is responsible for validating the original item-index and
raising (typically) an IndexOutOfBoundsException
. Misuse of this method may
still result in unchecked exceptions characteristic of the storage implementation. This
method must implement the check for read-only character, raising a BufferError
in the case of a violation.storeAtImpl
in class BaseBuffer
value
- to storebyteIndex
- byte-index of location to retrievePyException
- BufferError
if this object is read-only.java.lang.IndexOutOfBoundsException
public int byteIndex(int... indices) throws java.lang.IndexOutOfBoundsException
PyBuffer
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()
).byteIndex
in interface PyBuffer
byteIndex
in class BaseBuffer
indices
- n-dimensional item-index from consumerjava.lang.IndexOutOfBoundsException
public void copyTo(int srcIndex, byte[] dest, int destPos, int count) throws java.lang.IndexOutOfBoundsException
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.
copyTo
in interface PyBuffer
copyTo
in class BaseBuffer
srcIndex
- starting item-index in the source bufferdest
- destination byte arraydestPos
- byte-index in the destination array of the source item [0,...]count
- number of items to copyjava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationpublic void copyFrom(byte[] src, int srcPos, int destIndex, int count) throws java.lang.IndexOutOfBoundsException, PyException
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.
copyFrom
in interface PyBuffer
copyFrom
in class BaseBuffer
src
- source byte arraysrcPos
- location in source of first byte to copydestIndex
- starting item-index in the destination (i.e. this
)count
- number of items to copy injava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
- TypeError
if read-only bufferprotected void copyFrom(byte[] src, int srcPos, int srcStride, int destIndex, int count) throws java.lang.IndexOutOfBoundsException, PyException
PyBuffer.copyFrom(byte[], int, int, int)
to allow a stride within
the source array.src
- source byte arraysrcPos
- byte-index location in source of first byte to copysrcStride
- byte-index increment from one item to the nextdestIndex
- starting item-index in the destination (i.e. this
)count
- number of items to copy injava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
- TypeError
if read-only bufferpublic void copyFrom(PyBuffer src) throws java.lang.IndexOutOfBoundsException, PyException
BaseBuffer
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.
copyFrom
in interface PyBuffer
copyFrom
in class BaseBuffer
src
- source bufferjava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
- TypeError
if read-only bufferprotected java.nio.ByteBuffer getNIOByteBufferImpl()
BaseBuffer
java.nio.ByteBuffer
on the underlying storage, such that
positioning this buffer to a particular byte using BaseBuffer.byteIndex(int)
or
BaseBuffer.byteIndex(int[])
positions it at the first byte of the item so indexed.getNIOByteBufferImpl
in class BaseBuffer
public PyBuffer.Pointer getBuf()
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.
getBuf
in interface PyBuffer
getBuf
in class BaseBuffer