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 Description SimpleBuffer(int flags, BufferProtocol obj, byte[] storage)
Provide an instance ofSimpleBuffer
, on the entirety of a byte array, meeting the consumer's expectations as expressed in theflags
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 ofSimpleBuffer
, on a slice of a byte array, meeting the consumer's expectations as expressed in theflags
argument, which is checked against the capabilities of the buffer type.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 toPyBuffer.getBufferSlice(int, int, int, int)
with stride 1.PyBuffer
getBufferSlice(int flags, int start, int count, int stride)
Get aPyBuffer
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 theshape
array, and the item size in bytes.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.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.java.lang.String
toString()
The toString() method of a buffer reproduces the values in the buffer (as unsigned integers) as the character codes of aString
.-
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
-
-
-
-
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 ofSimpleBuffer
, on a slice of a byte array, meeting the consumer's expectations as expressed in theflags
argument, which is checked against the capabilities of the buffer type.- Parameters:
flags
- consumer requirementsobj
- exporting object (ornull
)storage
- the array of bytes storing the implementation of the exporting objectindex0
- offset where the data starts in that array (item[0])size
- the number of bytes occupied- Throws:
java.lang.NullPointerException
- ifstorage
is nulljava.lang.ArrayIndexOutOfBoundsException
- ifindex0
andsize
are inconsistent withstorage.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 ofSimpleBuffer
, on the entirety of a byte array, meeting the consumer's expectations as expressed in theflags
argument, which is checked against the capabilities of the buffer type.- Parameters:
flags
- consumer requirementsobj
- exporting object (ornull
)storage
- the array of bytes storing the implementation of the exporting object- Throws:
java.lang.NullPointerException
- ifstorage
is nullPyException
- (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 theshape
array, and the item size in bytes.SimpleBuffer
provides an implementation optimised for contiguous bytes in one-dimension.- Specified by:
getLen
in interfacePyBUF
- Overrides:
getLen
in classBase1DBuffer
- 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 aPyBuffer
is a linearly-indexed sequence of bytes, although it may not actually be a heap-allocated Javabyte[]
object. The purpose of this method is to allow the exporter to define the relationship between the item index (as used inPyBuffer.byteAt(int)
) and the byte-index (as used with theByteBuffer
returned byPyBuffer.getNIOByteBuffer()
). SeePyBuffer.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 interfacePyBuffer
- Overrides:
byteIndex
in classBaseBuffer
- 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 toPyBuffer.getBufferSlice(int, int, int, int)
with stride 1.- Specified by:
getBufferSlice
in interfacePyBuffer
- Overrides:
getBufferSlice
in classBaseBuffer
- Parameters:
flags
- specifying features demanded and the navigational capabilities of the consumerstart
- index in the current buffercount
- 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 aPyBuffer
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 aPyBuffer
withgetBufferSlice
must release it withPyBuffer.release()
just as if it had been obtained withPyBuffer.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 bythis.getPointer(i)
. A request for a slice wherestart
= s,count
= N andstride
= 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
andstride
will be translated from the arguments given, through this buffer's stride and item size. The caller always expressesstart
andstrides
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 consumerstart
- index in the current buffercount
- number of items in the required slicestride
- 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 whereobj
has typeBufferProtocol
:int k = ... ; PyBuffer a = obj.getBuffer(PyBUF.FULL); int itemsize = a.getItemsize(); PyBuffer.Pointer b = a.getPointer(k);
the item with indexk
is in the arrayb.storage
at index[b.offset]
to[b.offset + itemsize - 1]
inclusive. And ifitemsize==1
, the item is simply the byteb.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 interfacePyBuffer
- Overrides:
getPointer
in classBaseBuffer
- 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 whereobj
has typeBufferProtocol
: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 arrayb.storage
at index[b.offset]
to[b.offset + itemsize - 1]
inclusive. And ifitemsize==1
, the item is simply the byteb.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 ofb.storage[]
to other items, the client must use the shape, strides and sub-offsets provided by the API. Normally one startsb = a.getBuf()
in order to establish the offset of index [0,...,0].- Specified by:
getPointer
in interfacePyBuffer
- Overrides:
getPointer
in classBaseBuffer
- 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 aString
.- Specified by:
toString
in interfacePyBuffer
- Overrides:
toString
in classBaseBuffer
-
-