public interface PyBUF
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:
PyBUF_SIMPLE
, PyBUF_WRITABLE
,
etc., and the trick of defining ours here means we can write PyBUF.SIMPLE
,
PyBUF.WRITABLE
, etc. so source code looks similar.byte
array as storing anything
other than byte
, 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 future FloatBuffer
or TypedBuffer<T>
.
(Compare java.nio.Buffer
.)PyBUF
, except indirectly through other
interfaces. Users of the Jython buffer API can mostly overlook the distinction and just use
PyBuffer
.Modifier and Type | Field and Description |
---|---|
static int |
ANY_CONTIGUOUS
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it will assume a contiguous organisation of the items, but will enquire which
organisation it actually is. |
static int |
AS_ARRAY
A constant used by the consumer in its call to
BufferProtocol.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 int |
C_CONTIGUOUS
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it will assume C-order organisation of the items. |
static int |
CONTIG
Equivalent to
(ND | WRITABLE) |
static int |
CONTIG_RO
Equivalent to
ND |
static int |
CONTIGUITY
Field mask, used as in if
((flags&CONTIGUITY)== ... ) ... . |
static int |
F_CONTIGUOUS
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it will assume Fortran-order organisation of the items. |
static int |
FORMAT
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it requires PyBuffer.getFormat() to return a String indicating
the type of the unit. |
static int |
FULL
Equivalent to
(INDIRECT | WRITABLE | FORMAT) . |
static int |
FULL_RO
Equivalent to
(INDIRECT | FORMAT) . |
static int |
INDIRECT
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it understands the suboffsets array. |
static int |
IS_C_CONTIGUOUS
A constant used by the exporter in processing
BufferProtocol.getBuffer(int) to check
for assumed C-order organisation of the items. |
static int |
IS_F_CONTIGUOUS
A constant used by the exporter in processing
BufferProtocol.getBuffer(int) to check
for assumed C-order Fortran-order organisation of the items. |
static int |
MAX_NDIM
The maximum allowed number of dimensions (CPython restriction).
|
static int |
NAVIGATION
Field mask, used as in
if ((flags&NAVIGATION) == STRIDES) ... . |
static int |
ND
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it is prepared to navigate the buffer as multi-dimensional using the
shape array. |
static int |
RECORDS
Equivalent to
(STRIDES | WRITABLE | FORMAT) |
static int |
RECORDS_RO
Equivalent to
(STRIDES | FORMAT) |
static int |
SIMPLE
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it assumes a simple one-dimensional organisation of the exported storage with
item size of one. |
static int |
STRIDED
Equivalent to
(STRIDES | WRITABLE) |
static int |
STRIDED_RO
Equivalent to
STRIDES |
static int |
STRIDES
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it expects to use the strides array. |
static int |
WRITABLE
A constant used by the consumer in its call to
BufferProtocol.getBuffer(int) to
specify that it expects to write to the buffer contents. |
Modifier and Type | Method and Description |
---|---|
int |
getItemsize()
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 the
shape 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[] |
getStrides()
The
strides array gives the distance in the storage array between adjacent items (in
each dimension). |
int[] |
getSuboffsets()
The
suboffsets 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 |
isReadonly()
Determine whether the consumer is entitled to write to the exported storage.
|
static final int MAX_NDIM
static final int WRITABLE
BufferProtocol.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.static final int SIMPLE
BufferProtocol.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.static final int FORMAT
BufferProtocol.getBuffer(int)
to
specify that it requires PyBuffer.getFormat()
to return a String
indicating
the type of the unit. This exists for compatibility with CPython, as in Jython the format is
always provided by getFormat()
.static final int ND
BufferProtocol.getBuffer(int)
to
specify that it is prepared to navigate the buffer as multi-dimensional using the
shape
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.static final int STRIDES
BufferProtocol.getBuffer(int)
to
specify that it expects to use the strides
array. getBuffer
will raise an
exception if consumer does not specify the flag but the exporter's buffer cannot be navigated
without using the strides
array.static final int C_CONTIGUOUS
BufferProtocol.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
implies
STRIDES
.static final int F_CONTIGUOUS
BufferProtocol.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
implies STRIDES
.static final int ANY_CONTIGUOUS
BufferProtocol.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
implies STRIDES
.static final int INDIRECT
BufferProtocol.getBuffer(int)
to
specify that it understands the suboffsets
array. getBuffer
will raise an
exception if consumer does not specify the flag but the exporter's buffer cannot be navigated
without understanding the suboffsets
array. INDIRECT
implies STRIDES
.static final int CONTIG
(ND | WRITABLE)
static final int CONTIG_RO
ND
static final int STRIDED
(STRIDES | WRITABLE)
static final int STRIDED_RO
STRIDES
static final int RECORDS
(STRIDES | WRITABLE | FORMAT)
static final int RECORDS_RO
(STRIDES | FORMAT)
static final int FULL
(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 calling PyBuffer.getNIOByteBuffer()
or using
PyBuffer.Pointer
.static final int FULL_RO
(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 calling PyBuffer.getNIOByteBuffer()
or using PyBuffer.Pointer
.static final int AS_ARRAY
BufferProtocol.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.static final int NAVIGATION
if ((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.
static final int IS_C_CONTIGUOUS
BufferProtocol.getBuffer(int)
to check
for assumed C-order organisation of the items.
C_CONTIGUOUS = IS_C_CONTIGUOUS | STRIDES
.static final int IS_F_CONTIGUOUS
BufferProtocol.getBuffer(int)
to check
for assumed C-order Fortran-order organisation of the items.
F_CONTIGUOUS = IS_F_CONTIGUOUS | STRIDES
.static final int CONTIGUITY
((flags&CONTIGUITY)== ... ) ...
.boolean isReadonly()
int getNdim()
shape
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.int[] getShape()
shape
array is always
returned (difference from CPython).int getItemsize()
int getLen()
shape
array, and the item size in bytes.int[] getStrides()
strides
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 valid strides
array is always returned (difference from
CPython).int[] getSuboffsets()
suboffsets
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 the strides
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 navigation
null
is returned (as in CPython).null
if not necessary for navigationboolean isContiguous(char order)
order
- 'C', 'F' or 'A', as the storage order is C, Fortran or either.