Class SimpleStringBuffer
- All Implemented Interfaces:
AutoCloseable
,BufferProtocol
,PyBUF
,PyBuffer
ByteBuffer
or
PyBuffer.Pointer
result), and therefore this class must create a byte array from the
String for them. However, it defers creation of a byte array until that part of the API is
actually used. Where possible, this class overrides those methods in SimpleBuffer that would
otherwise access the byte array attribute to use the String instead.-
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
ConstructorDescriptionSimpleStringBuffer
(int flags, BufferProtocol obj, String bufString) Provide an instance of SimpleStringBuffer meeting the consumer's expectations as expressed in the flags argument. -
Method Summary
Modifier and TypeMethodDescriptionfinal byte
byteAtImpl
(int index) final 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.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) Equivalent toPyBuffer.getBufferSlice(int, int, int, int)
with stride 1.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.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.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.toString()
ThetoString()
method of aSimpleStringBuffer
simply produces the underlyingString
.Methods inherited from class org.python.core.buffer.BaseArrayBuffer
byteIndex, copyFrom, copyFrom
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 Details
-
SimpleStringBuffer
Provide an instance of SimpleStringBuffer meeting the consumer's expectations as expressed in the flags argument.- Parameters:
flags
- consumer requirementsobj
- exporting object (ornull
)bufString
- storing the implementation of the object
-
-
Method Details
-
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.This method uses
String.length()
rather than create an actual byte buffer.- Specified by:
getLen
in interfacePyBUF
- Overrides:
getLen
in classSimpleBuffer
- Returns:
- the total number of bytes represented.
-
byteAtImpl
public final byte byteAtImpl(int index) This method uses
String.charAt(int)
rather than create an actual byte buffer. -
byteIndex
public final 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. 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.In
SimpleStringBuffer
we can simply return the argument.- Specified by:
byteIndex
in interfacePyBuffer
- Overrides:
byteIndex
in classSimpleBuffer
- Parameters:
index
- item-index from consumer- Returns:
- corresponding byte-index in actual storage
-
copyTo
public void copyTo(int srcIndex, byte[] dest, int destPos, int count) throws 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 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.This method uses
String.charAt(int)
rather than create an actual byte buffer.- 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 destination
-
getBufferSlice
Equivalent toPyBuffer.getBufferSlice(int, int, int, int)
with stride 1.The
SimpleStringBuffer
implementation avoids creation of a byte buffer.- Specified by:
getBufferSlice
in interfacePyBuffer
- Overrides:
getBufferSlice
in classSimpleBuffer
- 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
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.The
SimpleStringBuffer
implementation creates an actual byte buffer.- Specified by:
getBufferSlice
in interfacePyBuffer
- Overrides:
getBufferSlice
in classSimpleBuffer
- 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.This method creates an actual byte array from the underlying String if none yet exists.
- Specified by:
getBuf
in interfacePyBuffer
- Overrides:
getBuf
in classBaseArrayBuffer
- Returns:
- structure defining the byte[] slice that is the shared data
-
getPointer
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.This method creates an actual byte array from the underlying String if none yet exists.
- Specified by:
getPointer
in interfacePyBuffer
- Overrides:
getPointer
in classSimpleBuffer
- Parameters:
index
- in the buffer to position the pointer- Returns:
- structure defining the byte[] slice that is the shared data
-
getPointer
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].This method creates an actual byte array from the underlying String if none yet exists.
- Specified by:
getPointer
in interfacePyBuffer
- Overrides:
getPointer
in classSimpleBuffer
- Parameters:
indices
- multidimensional index at which to position the pointer- Returns:
- structure defining the byte[] slice that is the shared data
-
toString
ThetoString()
method of aSimpleStringBuffer
simply produces the underlyingString
.- Specified by:
toString
in interfacePyBuffer
- Overrides:
toString
in classSimpleBuffer
-