public interface PyBuffer extends PyBUF, BufferProtocol, AutoCloseable
Py_buffer struct. Several concrete types implement
 this interface in order to provide tailored support for different storage organisations.| Modifier and Type | Interface and Description | 
|---|---|
| static class  | PyBuffer.PointerDeprecated.  | 
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 and Type | Method and Description | 
|---|---|
| byte | byteAt(int... indices)Return the byte indexed from an N-dimensional buffer with item size one. | 
| byte | byteAt(int index)Return the byte indexed from a one-dimensional buffer with item size one. | 
| int | byteIndex(int... indices)Convert a multi-dimensional item index to an absolute byte index in the storage shared by the
 exporter. | 
| 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 | close()An alias for  release()to satisfyAutoCloseable. | 
| 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  PyBufferinto this buffer. | 
| 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 the  countof 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. | 
| PyBuffer | getBuffer(int flags)Method by which the consumer requests the buffer from the exporter. | 
| PyBuffer | getBufferSlice(int flags,
              int start,
              int count)Equivalent to  getBufferSlice(int, int, int, int)with stride 1. | 
| PyBuffer | getBufferSlice(int flags,
              int start,
              int count,
              int stride)Get a  PyBufferthat 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. | 
| String | getFormat()A format string in the language of Python structs describing how the bytes of each item
 should be interpreted. | 
| ByteBuffer | getNIOByteBuffer()Obtain a  ByteBuffergiving access to the bytes that hold the data being
 exported by the original object. | 
| BufferProtocol | getObj()Return the underlying exporting object (or  nullif no object implementing theBufferProtocolis in that role). | 
| 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. | 
| 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. | 
| boolean | hasArray()Report whether the exporter is able to offer direct access to the exported storage as a Java
 byte array (through the API that involves class  PyBuffer.Pointer), or only supports the
 abstract API. | 
| int | intAt(int... indices)Return the unsigned byte value indexed from an N-dimensional buffer with item size one. | 
| int | intAt(int index)Return the unsigned byte value indexed from a one-dimensional buffer with item size one. | 
| boolean | isReleased()True only if the buffer has been released with (the required number of calls to)
  release()or some equivalent operation. | 
| void | release()A buffer is (usually) a view onto to the internal state of an exporting object, and that
 object may have to restrict its behaviour while the buffer exists. | 
| void | storeAt(byte value,
       int... indices)Store the given byte at the indexed location in of an N-dimensional buffer with item size
 one. | 
| void | storeAt(byte value,
       int index)Store the given byte at the indexed location in of a one-dimensional buffer with item size
 one. | 
| String | toString()The toString() method of a buffer reproduces the byte values in the buffer (treated as
 unsigned integers) as the character codes of a  String. | 
getItemsize, getLen, getNdim, getShape, getStrides, getSuboffsets, isContiguous, isReadonlyBufferProtocol getObj()
null if no object implementing the
 BufferProtocol is in that role). This will often be a PyObject.null)byte byteAt(int index)
     throws IndexOutOfBoundsException
itemsize>1.index - to retrieve fromIndexOutOfBoundsExceptionint intAt(int index) throws IndexOutOfBoundsException
itemsize>1.index - to retrieve from=0xff & byteAt(index)IndexOutOfBoundsExceptionvoid storeAt(byte value,
             int index)
      throws IndexOutOfBoundsException
itemsize>1.value - to storeindex - to locationIndexOutOfBoundsExceptionbyte byteAt(int... indices)
     throws IndexOutOfBoundsException
itemsize>1.indices - specifying location to retrieve fromIndexOutOfBoundsExceptionint intAt(int... indices) throws IndexOutOfBoundsException
itemsize>1.indices - specifying location to retrieve from=0xff & byteAt(index)IndexOutOfBoundsExceptionvoid storeAt(byte value,
             int... indices)
      throws IndexOutOfBoundsException
itemsize>1.value - to storeindices - specifying location to store atIndexOutOfBoundsExceptionvoid copyTo(byte[] dest,
            int destPos)
     throws IndexOutOfBoundsException,
            PyException
PyBUF.getLen(), and the order is the storage order in the exporter.
 (Note: Correct ordering for multidimensional arrays, including those with indirection needs
 further study.)dest - destination byte arraydestPos - byte-index in the destination array of the byte [0]IndexOutOfBoundsException - if the destination cannot hold itPyExceptionvoid copyTo(int srcIndex,
            byte[] dest,
            int destPos,
            int count)
     throws IndexOutOfBoundsException,
            PyException
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.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 copyIndexOutOfBoundsException - if access out of bounds in source or destinationPyExceptionvoid copyFrom(byte[] src,
              int srcPos,
              int destIndex,
              int count)
       throws IndexOutOfBoundsException,
              PyException
count*itemsize bytes will be read
 from the source.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 inIndexOutOfBoundsException - if access out of bounds in source or destinationPyException - (TypeError) if read-only buffervoid copyFrom(PyBuffer src) throws IndexOutOfBoundsException, PyException
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.src - source bufferIndexOutOfBoundsException - if access out of bounds in source or destinationPyException - (TypeError) if read-only bufferPyBuffer getBuffer(int flags) throws PyException
release() on the buffer it
 obtained, since some objects alter their behaviour while buffers are exported.
 
 When a PyBuffer is the target, the same checks are carried out on the consumer
 flags, and a return will normally be a reference to that buffer. A Jython
 PyBuffer keeps count of these re-exports in order to match them with the number
 of calls to release(). When the last matching release() arrives it is
 considered "final", and release actions may then take place on the exporting object. After
 the final release of a buffer, a call to getBuffer should raise an exception.
getBuffer in interface BufferProtocolflags - specifying features demanded and the navigational capabilities of the consumerPyException - (BufferError) when expectations do not correspond with the buffervoid release()
BufferProtocol.getBuffer(int) or getBuffer(int) should make a
 matching call to release(). The consumer may be sharing the PyBuffer
 with other consumers and the buffer uses the pairing of getBuffer and
 release to manage the lock on behalf of the exporter. It is an error to make
 more than one call to release for a single call to getBuffer.void close()
release() to satisfy AutoCloseable.close in interface AutoCloseableboolean isReleased()
release() or some equivalent operation. The consumer may be sharing the reference
 with other consumers and the buffer only achieves the released state when all consumers who
 called getBuffer have called release.PyBuffer getBufferSlice(int flags, int start, int count)
getBufferSlice(int, int, int, int) with stride 1.flags - specifying features demanded and the navigational capabilities of the consumerstart - index in the current buffercount - number of items in the required slicePyBuffer getBufferSlice(int flags, int start, int count, int stride)
PyBuffer 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 a PyBuffer with getBufferSlice must release
 it with release() just as if it had been obtained with
 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 by
 this.getPointer(i). A request for a slice where start = s,
 count = N and stride = 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 and stride will be translated
 from the arguments given, through this buffer's stride and item size. The caller always
 expresses start and strides in terms of the abstract view of this
 buffer.
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 sliceint byteIndex(int index)
       throws IndexOutOfBoundsException
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 byteAt(int)) and the byte-index (as used with the
 ByteBuffer returned by getNIOByteBuffer()). See
 byteIndex(int[]) for discussion of the multi-dimensional case.index - item-index from consumerIndexOutOfBoundsExceptionint byteIndex(int... indices)
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 byteAt(int...) and the byte-index (as used with the
 ByteBuffer returned by getNIOByteBuffer()).indices - n-dimensional item-index from consumerByteBuffer getNIOByteBuffer()
ByteBuffer giving access to the bytes that hold the data being
 exported by the original object. The position of the buffer is at the first byte of the item
 with zero index (quite possibly not the lowest valid byte-index), the limit of the buffer is
 beyond the largest valid byte index, and the mark is undefined.
 
 For a one-dimensional contiguous buffer, the limit is one byte beyond the last item, so that
 consecutive reads from the ByteBuffer return the data in order. Assuming the
 following client code where obj has type BufferProtocol:
 
PyBuffer a = obj.getBuffer(PyBUF.SIMPLE); int itemsize = a.getItemsize(); ByteBuffer bb = a.getNIOBuffer();the item with index
k is in bb at positions
 bb.pos()+k*itemsize to bb.pos()+(k+1)*itemsize - 1 inclusive. And
 if itemsize==1, the item is simply the byte at position bb.pos()+k.
 
 If the buffer is multidimensional or non-contiguous (strided), the buffer position is still
 the (first byte of) the item at index [0] or [0,...,0]. However, it
 is necessary to navigate bb using the shape, strides
 and maybe suboffsets provided by the API.
ByteBuffer onto the exported data contents.boolean hasArray()
PyBuffer.Pointer), or only supports the
 abstract API. See also PyBUF.AS_ARRAY.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.
PyBuffer.Pointer getPointer(int index)
obj has type BufferProtocol:
 int k = ... ; PyBuffer a = obj.getBuffer(PyBUF.FULL); int itemsize = a.getItemsize(); PyBuffer.Pointer b = a.getPointer(k);the item with index
k is in the array b.storage at index
 [b.offset] to [b.offset + itemsize - 1] inclusive. And if
 itemsize==1, the item is simply the byte b.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.
index - in the buffer to position the pointerPyBuffer.Pointer getPointer(int... indices)
obj
 has type BufferProtocol:
 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 array b.storage at index
 [b.offset] to [b.offset + itemsize - 1] inclusive. And if
 itemsize==1, the item is simply the byte b.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 of
 b.storage[] to other items, the client must use the shape, strides and
 sub-offsets provided by the API. Normally one starts b = a.getBuf() in order to
 establish the offset of index [0,...,0].
indices - multidimensional index at which to position the pointerString getFormat()
PyBUF.FORMAT bit in the consumer's call to
 getBuffer, a valid format string is always returned (difference
 from CPython).
 Jython only implements "B" so far, and it is debatable whether anything fancier than "<n>B" can be supported in Java.