BaseBuffer (Jython API documentation)
Date: 2015-04-29

org.python.core.buffer

## Class BaseBuffer

- java.lang.Object
- - org.python.core.buffer.BaseBuffer

- All Implemented Interfaces:
    AutoCloseable, BufferProtocol, PyBUF, PyBuffer
  Direct Known Subclasses:
    SimpleBuffer, Strided1DBuffer, ZeroByteBuffer

      public abstract class BaseBuffer
      extends Object
      implements PyBuffer

  Base implementation of the Buffer API providing variables and accessors for the navigational arrays, methods for expressing and checking the buffer request flags, methods and mechanism for get-release counting, boilerplate error checks and their associated exceptions, and default implementations of some methods for access to the buffer content. The design aim is to ensure unglamorous common code need only be implemented once.

  Where provided, the buffer access methods are appropriate to 1-dimensional arrays where the units are single bytes, stored contiguously. Sub-classes that deal with N-dimensional arrays, non-contiguous storage and items that are not single bytes must override the default implementations.

  This base implementation is writable only if `PyBUF.WRITABLE` is in the feature flags passed to the constructor. Otherwise, all methods for write access raise a `BufferError` read-only exception and `isReadonly()` returns `true`. Sub-classes can follow the same pattern, setting `PyBUF.WRITABLE` in the constructor and, if they have to, overriding the operations that write (`storeAt` and `copyFrom`). The recommended pattern is:

       if (isReadonly()) {
           throw notWritable();
       }
       // ... implementation of the write operation

  Another approach, used in the standard library, is to have distinct classes for the writable and read-only variants. The implementors of simple buffers will find it efficient to override the generic access methods to which performance might be sensitive, with a calculation specific to their actual type.

  At the time of writing, only one-dimensional buffers of item size one are used in the Jython core.

- - ### 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`

  - ### Method Summary

    Methods
    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.
    `void` | `close()` An alias for `PyBuffer.release()` to satisfy `AutoCloseable`.
    `void` | `copyFrom(byte[] src, int srcPos, int destIndex, int length)` Copy bytes from a slice of a (Java) byte array into the buffer.
    `void` | `copyFrom(PyBuffer src)` Copy the whole of another PyBuffer into 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 length)` Copy a simple slice of the buffer to the destination byte array, defined by a starting index and length in the source buffer.
    `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.
    `BaseBuffer` | `getBufferAgain(int flags)` Allow an exporter to re-use a BaseBytes even if it has been "finally" released.
    `PyBuffer` | `getBufferSlice(int flags, int start, int length)` Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
    `String` | `getFormat()` A format string in the language of Python structs describing how the bytes of each item should be interpreted.
    `int` | `getItemsize()` The number of units (bytes) stored in each indexable item.
    `int` | `getLen()` The total number of units (bytes) stored, which will be the product of the elements of the `shape` array, and the item size in units.
    `int` | `getNdim()` The number of dimensions to the buffer.
    `ByteBuffer` | `getNIOByteBuffer()` Obtain a `ByteBuffer` giving access to the bytes that hold the data being exported to the consumer.
    `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.
    `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` | `hasArray()` Determine 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` | `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.
    `boolean` | `isReleased()` True only if the buffer has been released with (the required number of calls to) `PyBuffer.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 values in the buffer (as unsigned integers) as the character codes of a `String`.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.python.core.PyBuffer

      `getBufferSlice`

- - ### Method Detail

    - #### isReadonly

          public boolean isReadonly()

      Description copied from interface: `PyBUF`
      Determine whether the consumer is entitled to write to the exported storage.
      Specified by:
        `isReadonly` in interface `PyBUF`
      Returns:
        true if writing is not allowed, false if it is.

    - #### hasArray

          public boolean hasArray()

      Description copied from interface: `PyBuffer`
      Determine 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. See also `PyBUF.AS_ARRAY`.
      Specified by:
        `hasArray` in interface `PyBuffer`
      Returns:
        true if array access is supported, false if it is not.

    - #### getNdim

          public int getNdim()

      Description copied from interface: `PyBUF`
      The number of dimensions to the buffer. This number is the length of the `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.
      Specified by:
        `getNdim` in interface `PyBUF`
      Returns:
        number of dimensions

    - #### getShape

          public int[] getShape()

      Description copied from interface: `PyBUF`
      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 valid `shape` array is always returned (difference from CPython).
      Specified by:
        `getShape` in interface `PyBUF`
      Returns:
        the dimensions of the buffer as an array

    - #### getLen

          public int getLen()

      The total number of units (bytes) stored, which will be the product of the elements of the `shape` array, and the item size in units.

      The default implementation in `BaseBuffer` deals with the general one-dimensional case, with any item size and stride.

      Specified by:
        `getLen` in interface `PyBUF`
      Returns:
        the total number of units stored.

    - #### byteAt

          public byte byteAt(int index)
                      throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Return the byte indexed from a one-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. Results are undefined where the number of dimensions is not one or if `itemsize>1`.
      Specified by:
        `byteAt` in interface `PyBuffer`
      Parameters:
        `index` - to retrieve from
      Returns:
        the item at index, which is a byte
      Throws:
        `IndexOutOfBoundsException`

    - #### intAt

          public int intAt(int index)
                    throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Return the unsigned byte value indexed from a one-dimensional buffer with item size one. This is part of the fully-encapsulated API: the exporter takes care of navigating the structure of the buffer. Results are undefined where the number of dimensions is not one or if `itemsize>1`.
      Specified by:
        `intAt` in interface `PyBuffer`
      Parameters:
        `index` - to retrieve from
      Returns:
        the item at index, treated as an unsigned byte, `=0xff & byteAt(index)`
      Throws:
        `IndexOutOfBoundsException`

    - #### storeAt

          public void storeAt(byte value,
                     int index)
                       throws IndexOutOfBoundsException,
                              PyException

      Description copied from interface: `PyBuffer`
      Store the given byte at the indexed location in of a one-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. Results are undefined where the number of dimensions is not one or if `itemsize>1`.
      Specified by:
        `storeAt` in interface `PyBuffer`
      Parameters:
        `value` - to store
        `index` - to location
      Throws:
        `IndexOutOfBoundsException`
        `PyException`

    - #### byteAt

          public byte byteAt(int... indices)
                      throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Return the byte indexed from an N-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. The indices must be correct in number and range for the array shape. Results are undefined where `itemsize>1`.
      Specified by:
        `byteAt` in interface `PyBuffer`
      Parameters:
        `indices` - specifying location to retrieve from
      Returns:
        the item at location, which is a byte
      Throws:
        `IndexOutOfBoundsException`

    - #### intAt

          public int intAt(int... indices)
                    throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      Return the unsigned byte value indexed from an N-dimensional buffer with item size one. This is part of the fully-encapsulated API: the buffer implementation exported takes care of navigating the structure of the buffer. The indices must be correct in number and range for the array shape. Results are undefined where `itemsize>1`.
      Specified by:
        `intAt` in interface `PyBuffer`
      Parameters:
        `indices` - specifying location to retrieve from
      Returns:
        the item at location, treated as an unsigned byte, `=0xff & byteAt(index)`
      Throws:
        `IndexOutOfBoundsException`

    - #### storeAt

          public void storeAt(byte value,
                     int... indices)
                       throws IndexOutOfBoundsException,
                              PyException

      Description copied from interface: `PyBuffer`
      Store the given byte at the indexed location in of an N-dimensional buffer with item size one. This is part of the fully-encapsulated API: the exporter takes care of navigating the structure of the buffer. The indices must be correct in number and range for the array shape. Results are undefined where `itemsize>1`.
      Specified by:
        `storeAt` in interface `PyBuffer`
      Parameters:
        `value` - to store
        `indices` - specifying location to store at
      Throws:
        `IndexOutOfBoundsException`
        `PyException`

    - #### copyTo

          public void copyTo(byte[] dest,
                    int destPos)
                      throws IndexOutOfBoundsException

      Copy the contents of the buffer to the destination byte array. The number of bytes will be that returned by `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.)

      The default implementation in `BaseBuffer` deals with the general one-dimensional case of arbitrary item size and stride.

      Specified by:
        `copyTo` in interface `PyBuffer`
      Parameters:
        `dest` - destination byte array
        `destPos` - 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 length)
                      throws IndexOutOfBoundsException

      Copy a simple slice of the buffer to the destination byte array, defined by a starting index and length in the source buffer. This may validly be done only for a one-dimensional buffer, as the meaning of the starting index is otherwise not defined. The length (like the source index) is in source buffer items: `length*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.

      Specified by:
        `copyTo` in interface `PyBuffer`
      Parameters:
        `srcIndex` - starting index in the source buffer
        `dest` - destination byte array
        `destPos` - index in the destination array of the item [0,...]
        `length` - number of items to copy
      Throws:
        `IndexOutOfBoundsException` - if access out of bounds in source or destination

    - #### copyFrom

          public void copyFrom(byte[] src,
                      int srcPos,
                      int destIndex,
                      int length)
                        throws IndexOutOfBoundsException,
                               PyException

      Copy bytes from a slice of a (Java) byte array into the buffer. This may validly be done only for a one-dimensional buffer, as the meaning of the starting index is not otherwise defined. The length (like the destination index) is in buffer items: `length*itemsize` bytes will be read from the source.

      The default implementation in `BaseBuffer` deals with the general one-dimensional case of arbitrary item size and stride.

      Specified by:
        `copyFrom` in interface `PyBuffer`
      Parameters:
        `src` - source byte array
        `srcPos` - location in source of first byte to copy
        `destIndex` - starting index in the destination (i.e. `this`)
        `length` - number of bytes to copy in
      Throws:
        `IndexOutOfBoundsException` - if access out of bounds in source or destination
        `PyException` - (TypeError) if read-only buffer

    - #### copyFrom

          public void copyFrom(PyBuffer src)
                        throws IndexOutOfBoundsException,
                               PyException

      Copy the whole of another 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.

      The default implementation in `BaseBuffer` deals with the general one-dimensional case.

      Specified by:
        `copyFrom` in interface `PyBuffer`
      Parameters:
        `src` - source buffer
      Throws:
        `IndexOutOfBoundsException` - if access out of bounds in source or destination
        `PyException` - (TypeError) if read-only buffer

    - #### getBuffer

          public PyBuffer getBuffer(int flags)

      Description copied from interface: `PyBuffer`
      Method by which the consumer requests the buffer from the exporter. The consumer provides information on its intended method of navigation and the features the buffer object is asked (or assumed) to provide. Each consumer requesting a buffer in this way, when it has finished using it, should make a corresponding call to `PyBuffer.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 `PyBuffer.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.

      Specified by:
        `getBuffer` in interface `BufferProtocol`
      Specified by:
        `getBuffer` in interface `PyBuffer`
      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
      Returns:
        exported buffer

    - #### getBufferAgain

          public BaseBuffer getBufferAgain(int flags)

      Allow an exporter to re-use a BaseBytes even if it has been "finally" released. Many sub-classes of `BaseBytes` can be re-used even after a final release by consumers, simply by incrementing the `exports` count again: the navigation arrays and the buffer view of the exporter's state all remain valid. We do not let consumers do this through the `PyBuffer` interface: from their perspective, calling `PyBuffer.release()` should mean the end of their access, although we can't stop them holding a reference to the PyBuffer. Only the exporting object, which handles the implementation type is trusted to know when re-use is safe.

      An exporter will use this method as part of its implementation of `BufferProtocol.getBuffer(int)`. On return from that, the buffer and the exporting object must then be in effectively the same state as if the buffer had just been constructed by that method. Exporters that destroy related resources on final release of their buffer (by overriding `releaseAction()`), or permit themselves structural change invalidating the buffer, must either reconstruct the missing resources or avoid `getBufferAgain`.

    - #### release

          public 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. The consumer must therefore say when it has finished with the buffer if the exporting object is to be released from this constraint. Each consumer that obtains a reference to a buffer by means of a call to `BufferProtocol.getBuffer(int)` or `PyBuffer.getBuffer(int)` should make a matching call to `PyBuffer.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`.

      When the final matching release occurs (that is the number of `release` calls equals the number of `getBuffer` calls), the implementation here calls `releaseAction()`, which the implementer of a specific buffer type should override if it needs specific actions to take place.

      Specified by:
        `release` in interface `PyBuffer`

    - #### close

          public void close()

      Description copied from interface: `PyBuffer`
      An alias for `PyBuffer.release()` to satisfy `AutoCloseable`.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `PyBuffer`

    - #### isReleased

          public boolean isReleased()

      Description copied from interface: `PyBuffer`
      True only if the buffer has been released with (the required number of calls to) `PyBuffer.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`.
      Specified by:
        `isReleased` in interface `PyBuffer`

    - #### getBufferSlice

          public PyBuffer getBufferSlice(int flags,
                                int start,
                                int length)

      Description copied from interface: `PyBuffer`
      Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
      Specified by:
        `getBufferSlice` in interface `PyBuffer`
      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
        `start` - index in the current buffer
        `length` - number of items in the required slice
      Returns:
        a buffer representing the slice

    - #### getNIOByteBuffer

          public ByteBuffer getNIOByteBuffer()

      Description copied from interface: `PyBuffer`
      Obtain a `ByteBuffer` giving access to the bytes that hold the data being exported to the consumer. For a one-dimensional contiguous buffer, 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 `bb.pos()+k` is in the buffer `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`. The buffer limit is set to the first byte beyond the valid data. A block read or write will therefore access the contents sequentially.

      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]`, and the limit is one item beyond the valid data. However, it is necessary to navigate `bb` using the `shape`, `strides` and maybe `suboffsets` provided by the API.

      Specified by:
        `getNIOByteBuffer` in interface `PyBuffer`
      Returns:
        a ByteBuffer equivalent to the exported data contents.

    - #### getBuf

          public PyBuffer.Pointer getBuf()

      Description copied from interface: `PyBuffer`
      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 where `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.

      Specified by:
        `getBuf` in interface `PyBuffer`
      Returns:
        structure defining the byte[] slice that is the shared data

    - #### getPointer

          public PyBuffer.Pointer getPointer(int index)
                                      throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      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 where `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.

      Specified by:
        `getPointer` in interface `PyBuffer`
      Parameters:
        `index` - in the buffer to position the pointer
      Returns:
        structure defining the byte[] slice that is the shared data
      Throws:
        `IndexOutOfBoundsException`

    - #### getPointer

          public PyBuffer.Pointer getPointer(int... indices)
                                      throws IndexOutOfBoundsException

      Description copied from interface: `PyBuffer`
      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 where `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 units, 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].

      Specified by:
        `getPointer` in interface `PyBuffer`
      Parameters:
        `indices` - multidimensional index at which to position the pointer
      Returns:
        structure defining the byte[] slice that is the shared data
      Throws:
        `IndexOutOfBoundsException`

    - #### getStrides

          public int[] getStrides()

      Description copied from interface: `PyBUF`
      The `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).
      Specified by:
        `getStrides` in interface `PyBUF`
      Returns:
        the distance in the storage array between adjacent items (in each dimension)

    - #### getSuboffsets

          public int[] getSuboffsets()

      Description copied from interface: `PyBUF`
      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). 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).
      Specified by:
        `getSuboffsets` in interface `PyBUF`
      Returns:
        suboffsets array or `null` if not necessary for navigation

    - #### isContiguous

          public boolean isContiguous(char order)

      Description copied from interface: `PyBUF`
      Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering. A one-dimensional contiguous array is both.
      Specified by:
        `isContiguous` in interface `PyBUF`
      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

    - #### getFormat

          public String getFormat()

      Description copied from interface: `PyBuffer`
      A format string in the language of Python structs describing how the bytes of each item should be interpreted. Irrespective of the `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.

      Specified by:
        `getFormat` in interface `PyBuffer`
      Returns:
        the format string

    - #### getItemsize

          public int getItemsize()

      Description copied from interface: `PyBUF`
      The number of units (bytes) stored in each indexable item.
      Specified by:
        `getItemsize` in interface `PyBUF`
      Returns:
        the number of units (bytes) comprising each item.

    - #### toString

          public String toString()

      The toString() method of a buffer reproduces the values in the buffer (as unsigned integers) as the character codes of a `String`.
      Specified by:
        `toString` in interface `PyBuffer`
      Overrides:
        `toString` in class `Object`

Jython homepage