Package org.python.core
Interface PyBUF
- All Known Subinterfaces:
PyBuffer
- All Known Implementing Classes:
Base1DBuffer
,BaseArrayBuffer
,BaseBuffer
,BaseNIOBuffer
,SimpleBuffer
,SimpleNIOBuffer
,SimpleStringBuffer
,SimpleWritableBuffer
,Strided1DBuffer
,Strided1DNIOBuffer
,Strided1DWritableBuffer
,ZeroByteBuffer
public interface PyBUF
This interface provides a base for the key interface of the buffer API,
PyBuffer
,
including symbolic constants used by the consumer of a PyBuffer
to specify its
requirements and assumptions. The Jython buffer API emulates the CPython buffer API. There are
two reasons for separating parts of PyBuffer
into this interface:
- The constants defined in CPython have the names
PyBUF_SIMPLE
,PyBUF_WRITABLE
, etc., and the trick of defining ours here means we can writePyBUF.SIMPLE
,PyBUF.WRITABLE
, etc. so source code looks similar. - It is not so easy in Java as it is in C to treat a
byte
array as storing anything other thanbyte
, and we prepare for the possibility of buffers with a series of different primitive types by defining here those methods that would be in common between (Byte)Buffer
and an assumed futureFloatBuffer
orTypedBuffer<T>
. (Comparejava.nio.Buffer
.)
PyBUF
, except indirectly through other
interfaces. Users of the Jython buffer API can mostly overlook the distinction and just use
PyBuffer
.-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume a contiguous organisation of the items, but will enquire which organisation it actually is.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to access the buffer contents directly as an array (rather than through the purely abstract part of the API).static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume C-order organisation of the items.static final int
Equivalent to(ND | WRITABLE)
static final int
Equivalent toND
static final int
Field mask, used as in if((flags&CONTIGUITY)== ... ) ...
.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume Fortran-order organisation of the items.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it requiresPyBuffer.getFormat()
to return aString
indicating the type of the unit.static final int
Equivalent to(INDIRECT | WRITABLE | FORMAT)
.static final int
Equivalent to(INDIRECT | FORMAT)
.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it understands thesuboffsets
array.static final int
A constant used by the exporter in processingBufferProtocol.getBuffer(int)
to check for assumed C-order organisation of the items.static final int
A constant used by the exporter in processingBufferProtocol.getBuffer(int)
to check for assumed C-order Fortran-order organisation of the items.static final int
The maximum allowed number of dimensions (CPython restriction).static final int
Field mask, used as inif ((flags&NAVIGATION) == STRIDES) ...
.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it is prepared to navigate the buffer as multi-dimensional using theshape
array.static final int
Equivalent to(STRIDES | WRITABLE | FORMAT)
static final int
Equivalent to(STRIDES | FORMAT)
static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it assumes a simple one-dimensional organisation of the exported storage with item size of one.static final int
Equivalent to(STRIDES | WRITABLE)
static final int
Equivalent toSTRIDES
static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to use thestrides
array.static final int
A constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to write to the buffer contents. -
Method Summary
Modifier and TypeMethodDescriptionint
The number of bytes stored in each indexable item.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.int
getNdim()
The number of dimensions to the buffer.int[]
getShape()
An array reporting the size of the buffer, considered as a multidimensional array, in each dimension and (by its length) giving the number of dimensions.int[]
Thestrides
array gives the distance in the storage array between adjacent items (in each dimension).int[]
Thesuboffsets
array is a further part of the support for interpreting the buffer as an n-dimensional array of items, where the array potentially uses indirect addressing (like a real Java array of arrays, in fact).boolean
isContiguous
(char order) Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering.boolean
Determine whether the consumer is entitled to write to the exported storage.
-
Field Details
-
MAX_NDIM
static final int MAX_NDIMThe maximum allowed number of dimensions (CPython restriction).- See Also:
-
WRITABLE
static final int WRITABLEA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to write to the buffer contents.getBuffer
will raise an exception if the exporter's buffer cannot meet this requirement.- See Also:
-
SIMPLE
static final int SIMPLEA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it assumes a simple one-dimensional organisation of the exported storage with item size of one.getBuffer
will raise an exception if the consumer sets this flag and the exporter cannot represent itself as byte array data.- See Also:
-
FORMAT
static final int FORMATA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it requiresPyBuffer.getFormat()
to return aString
indicating the type of the unit. This exists for compatibility with CPython, as in Jython the format is always provided bygetFormat()
.- See Also:
-
ND
static final int NDA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it is prepared to navigate the buffer as multi-dimensional using theshape
array.getBuffer
will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without taking into account its multiple dimensions.- See Also:
-
STRIDES
static final int STRIDESA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to use thestrides
array.getBuffer
will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without using thestrides
array.- See Also:
-
C_CONTIGUOUS
static final int C_CONTIGUOUSA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume C-order organisation of the items.getBuffer
will raise an exception if the exporter's buffer is not C-ordered.C_CONTIGUOUS
impliesSTRIDES
.- See Also:
-
F_CONTIGUOUS
static final int F_CONTIGUOUSA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume Fortran-order organisation of the items.getBuffer
will raise an exception if the exporter's buffer is not Fortran-ordered.F_CONTIGUOUS
impliesSTRIDES
.- See Also:
-
ANY_CONTIGUOUS
static final int ANY_CONTIGUOUSA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it will assume a contiguous organisation of the items, but will enquire which organisation it actually is.getBuffer
will raise an exception if the exporter's buffer is not contiguous.ANY_CONTIGUOUS
impliesSTRIDES
.- See Also:
-
INDIRECT
static final int INDIRECTA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it understands thesuboffsets
array.getBuffer
will raise an exception if consumer does not specify the flag but the exporter's buffer cannot be navigated without understanding thesuboffsets
array.INDIRECT
impliesSTRIDES
.- See Also:
-
CONTIG
static final int CONTIGEquivalent to(ND | WRITABLE)
- See Also:
-
CONTIG_RO
static final int CONTIG_ROEquivalent toND
- See Also:
-
STRIDED
static final int STRIDEDEquivalent to(STRIDES | WRITABLE)
- See Also:
-
STRIDED_RO
static final int STRIDED_ROEquivalent toSTRIDES
- See Also:
-
RECORDS
static final int RECORDSEquivalent to(STRIDES | WRITABLE | FORMAT)
- See Also:
-
RECORDS_RO
static final int RECORDS_ROEquivalent to(STRIDES | FORMAT)
- See Also:
-
FULL
static final int FULLEquivalent to(INDIRECT | WRITABLE | FORMAT)
. Also use this in the request if you plan only to use the fully-encapsulated API (byteAt
,storeAt
,copyTo
,copyFrom
, etc.), without ever callingPyBuffer.getNIOByteBuffer()
or usingPyBuffer.Pointer
.- See Also:
-
FULL_RO
static final int FULL_ROEquivalent to(INDIRECT | FORMAT)
. Also use this in the request if you plan only to use the fully-encapsulated API (byteAt
,copyTo
, etc.), read only, without ever callingPyBuffer.getNIOByteBuffer()
or usingPyBuffer.Pointer
.- See Also:
-
AS_ARRAY
static final int AS_ARRAYA constant used by the consumer in its call toBufferProtocol.getBuffer(int)
to specify that it expects to access the buffer contents directly as an array (rather than through the purely abstract part of the API).getBuffer
will raise an exception if the exporter cannot expose its storage as Java array.- See Also:
-
NAVIGATION
static final int NAVIGATIONField mask, used as inif ((flags&NAVIGATION) == STRIDES) ...
. The importance of the subset of flags defined by this mask is not so much in their "navigational" character as in the way they are treated in a buffer request.The
NAVIGATION
set are used to specify which navigation arrays the consumer will use, and therefore the consumer must ask for all those necessary to use the buffer successfully (which is a function of the buffer's actual type). Asking for extra ones is not an error, since all are supplied (in Jython): asking for too few is an error.Flags outside the
NAVIGATION
set, work the other way round. Asking for one the buffer cannot match is an error: not asking for a feature the buffer does not have is an error.- See Also:
-
IS_C_CONTIGUOUS
static final int IS_C_CONTIGUOUSA constant used by the exporter in processingBufferProtocol.getBuffer(int)
to check for assumed C-order organisation of the items.C_CONTIGUOUS = IS_C_CONTIGUOUS | STRIDES
.- See Also:
-
IS_F_CONTIGUOUS
static final int IS_F_CONTIGUOUSA constant used by the exporter in processingBufferProtocol.getBuffer(int)
to check for assumed C-order Fortran-order organisation of the items.F_CONTIGUOUS = IS_F_CONTIGUOUS | STRIDES
.- See Also:
-
CONTIGUITY
static final int CONTIGUITYField mask, used as in if((flags&CONTIGUITY)== ... ) ...
.- See Also:
-
-
Method Details
-
isReadonly
boolean isReadonly()Determine whether the consumer is entitled to write to the exported storage.- Returns:
- true if writing is not allowed, false if it is.
-
getNdim
int getNdim()The number of dimensions to the buffer. This number is the length of theshape
array. The actual storage may be a linear array, but this is the number of dimensions in the interpretation that the exporting object gives the data.- Returns:
- number of dimensions
-
getShape
int[] getShape()An array reporting the size of the buffer, considered as a multidimensional array, in each dimension and (by its length) giving the number of dimensions. The size of the buffer is its size in "items". An item is the amount of buffer content addressed by one index or set of indices. In the simplest case an item is a single unit (byte), and there is one dimension. In complex cases, the array is multi-dimensional, and the item at each location is multi-unit (multi-byte). The consumer must not modify this array. A validshape
array is always returned (difference from CPython).- Returns:
- the dimensions of the buffer as an array
-
getItemsize
int getItemsize()The number of bytes stored in each indexable item.- Returns:
- the number of bytes comprising each item.
-
getLen
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.- Returns:
- the total number of bytes represented.
-
getStrides
int[] getStrides()Thestrides
array gives the distance in the storage array between adjacent items (in each dimension). In the rawest parts of the buffer API, the consumer of the buffer is able to navigate the exported storage. The "strides" array is part of the support for interpreting the buffer as an n-dimensional array of items. It provides the coefficients of the "addressing polynomial". (More on this in the CPython documentation.) The consumer must not modify this array. A validstrides
array is always returned (difference from CPython).- Returns:
- the distance in the storage array between adjacent items (in each dimension)
-
getSuboffsets
int[] getSuboffsets()Thesuboffsets
array is a further part of the support for interpreting the buffer as an n-dimensional array of items, where the array potentially uses indirect addressing (like a real Java array of arrays, in fact). This is only applicable when there is more than 1 dimension, and it works in conjunction with thestrides
array. (More on this in the CPython documentation.) When used,suboffsets[k]
is an integer index, not a byte offset as in CPython. The consumer must not modify this array. When not needed for navigationnull
is returned (as in CPython).- Returns:
- suboffsets array or
null
if not necessary for navigation
-
isContiguous
boolean isContiguous(char order) Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering. A one-dimensional contiguous array is both.- Parameters:
order
- 'C', 'F' or 'A', as the storage order is C, Fortran or either.- Returns:
- true iff the array is stored contiguously in the order specified
-