Class ZeroByteBuffer
- All Implemented Interfaces:
AutoCloseable
,BufferProtocol
,PyBUF
,PyBuffer
IndexOutOfBoundsException
. This class exists mostly to represent zero-length arrays,
and particularly, zero-length slices for which implementations of
PyBuffer.getBufferSlice(int, int, int, int)
in any case need special logic. Bulk
operations like copyTo(byte[], int)
) and toString()
efficiently do nothing,
instead of calling complicated logic that finally does nothing.-
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
ConstructorDescriptionZeroByteBuffer
(int flags, BufferProtocol obj, boolean readonly, boolean hasArray) Construct an instance of a zero-length buffer, choosing whether it should report itself to be read-only throughBaseBuffer.isReadonly()
or as having a backing array throughBaseBuffer.hasArray()
. -
Method Summary
Modifier and TypeMethodDescriptionint
byteIndex
(int index) In a ZeroByteBuffer, the index is always out of bounds.int
byteIndex
(int... indices) In a ZeroByteBuffer, if the dimensions are right, the index is out of bounds anyway.void
copyFrom
(byte[] src, int srcPos, int destIndex, int count) In a ZeroByteBuffer, there is no room for anything, so this throws unless the source count is zero.void
In a ZeroByteBuffer, there is no room for anything, so this throws unless the source count is zero.void
copyTo
(byte[] dest, int destPos) Copy the contents of the buffer to the destination byte array.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 thecount
of items to copy.getBuf()
Return a structure describing the slice of a byte array that holds the data being exported to the consumer.getBufferSlice
(int flags, int start, int count) Only a zero-length slice at zero is valid (in which case, the present buffer will do nicely as a result, with the export count incremented.getBufferSlice
(int flags, int start, int count, int stride) Only a zero-length slice at zero is valid (in which case, the present buffer will do nicely as a result, with the export count incremented.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.toString()
For a ZeroByteBuffer, it's the empty string.Methods inherited from class org.python.core.buffer.Base1DBuffer
isContiguous
Methods inherited from class org.python.core.buffer.BaseBuffer
byteAt, byteAt, close, getBuffer, getBufferAgain, getFormat, getItemsize, getNdim, getNIOByteBuffer, getObj, getPointer, getPointer, getShape, getStrides, getSuboffsets, hasArray, intAt, intAt, isReadonly, isReleased, release, storeAt, storeAt
-
Constructor Details
-
ZeroByteBuffer
public ZeroByteBuffer(int flags, BufferProtocol obj, boolean readonly, boolean hasArray) throws PyException Construct an instance of a zero-length buffer, choosing whether it should report itself to be read-only throughBaseBuffer.isReadonly()
or as having a backing array throughBaseBuffer.hasArray()
. These properties are moot, as any attempt to write to the pretended backing array produces anIndexOutOfBoundsException
, but it is less surprising for client code that may ask, if the results are customary for the exporting object.- Parameters:
flags
- consumer requirementsobj
- exporting object (ornull
)readonly
- set true if not to be considered writablehasArray
- set true if to be considered as backed by an array- Throws:
PyException
-BufferError
when client expectations do not correspond with the type
-
-
Method Details
-
getLen
public int getLen()Description copied from interface:PyBUF
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.- Specified by:
getLen
in interfacePyBUF
- Overrides:
getLen
in classBase1DBuffer
- Returns:
- the total number of bytes represented.
-
byteIndex
In a ZeroByteBuffer, the index is always out of bounds.- Specified by:
byteIndex
in interfacePyBuffer
- Overrides:
byteIndex
in classBaseBuffer
- Parameters:
index
- item-index from consumer- Returns:
- corresponding byte-index in actual storage
- Throws:
IndexOutOfBoundsException
-
byteIndex
In a ZeroByteBuffer, if the dimensions are right, the index is out of bounds anyway.- Specified by:
byteIndex
in interfacePyBuffer
- Overrides:
byteIndex
in classBaseArrayBuffer
- Parameters:
indices
- n-dimensional item-index from consumer- Returns:
- corresponding byte-index in actual storage
- Throws:
IndexOutOfBoundsException
-
copyTo
Copy the contents of the buffer to the destination byte array. The number of bytes will be that returned byPyBUF.getLen()
, and the order is the storage order in the exporter. (Note: Correct ordering for multidimensional arrays, including those with indirection needs further study.)The default implementation in
BaseBuffer
deals with the general one-dimensional case of arbitrary item size and stride.In a ZeroByteBuffer, there is simply nothing to copy.
- Specified by:
copyTo
in interfacePyBuffer
- Overrides:
copyTo
in classBaseBuffer
- Parameters:
dest
- destination byte arraydestPos
- byte-index in the destination array of the byte [0]- Throws:
IndexOutOfBoundsException
- if the destination cannot hold it
-
copyTo
public void copyTo(int srcIndex, byte[] dest, int destPos, int count) throws IndexOutOfBoundsException, PyException Copy a simple slice of the buffer-view to the destination byte array, defined by a starting item-index in the source buffer and thecount
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.In a ZeroByteBuffer, there is simply nothing to copy.
- Specified by:
copyTo
in interfacePyBuffer
- Overrides:
copyTo
in classBaseArrayBuffer
- Parameters:
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 copy- Throws:
IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
-
copyFrom
public void copyFrom(byte[] src, int srcPos, int destIndex, int count) throws IndexOutOfBoundsException, PyException In a ZeroByteBuffer, there is no room for anything, so this throws unless the source count is zero.- Specified by:
copyFrom
in interfacePyBuffer
- Overrides:
copyFrom
in classBaseArrayBuffer
- Parameters:
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 in- Throws:
IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
-TypeError
if read-only buffer
-
copyFrom
In a ZeroByteBuffer, there is no room for anything, so this throws unless the source count is zero.- Specified by:
copyFrom
in interfacePyBuffer
- Overrides:
copyFrom
in classBaseArrayBuffer
- Parameters:
src
- source buffer- Throws:
IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
-TypeError
if read-only buffer
-
getBufferSlice
Only a zero-length slice at zero is valid (in which case, the present buffer will do nicely as a result, with the export count incremented.- 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
Only a zero-length slice at zero is valid (in which case, the present buffer will do nicely as a result, with the export count incremented.- 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
-
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 whereobj
has typeBufferProtocol
:PyBuffer a = obj.getBuffer(PyBUF.SIMPLE); int itemsize = a.getItemsize(); PyBuffer.Pointer b = a.getBuf();
the item with indexk
is in the arrayb.storage
at index[b.offset + k*itemsize]
to[b.offset + (k+1)*itemsize - 1]
inclusive. And ifitemsize==1
, the item is simply the byteb.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 navigateb.storage
using theshape
,strides
and maybesuboffsets
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.The implementation in
ZeroByteBuffer
efficiently returns an empty buffer.- Specified by:
getBuf
in interfacePyBuffer
- Overrides:
getBuf
in classBaseArrayBuffer
- Returns:
- structure defining the byte[] slice that is the shared data
-
toString
For a ZeroByteBuffer, it's the empty string.- Specified by:
toString
in interfacePyBuffer
- Overrides:
toString
in classBaseBuffer
-