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

org.python.core.buffer

## Class SimpleWritableBuffer

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

- All Implemented Interfaces:
    AutoCloseable, BufferProtocol, PyBUF, PyBuffer

      public class SimpleWritableBuffer
      extends SimpleBuffer

  Buffer API over a writable one-dimensional array of one-byte items.

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

    Constructors
    Constructor and Description
    `SimpleWritableBuffer(int flags, byte[] storage)` Provide an instance of `SimpleWritableBuffer`, on the entirety of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
    `SimpleWritableBuffer(int flags, byte[] storage, int index0, int size)` Provide an instance of `SimpleWritableBuffer`, on a slice of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `PyBuffer` | `getBufferSlice(int flags, int start, int length)` Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.
    `PyBuffer` | `getBufferSlice(int flags, int start, int length, int stride)` Get a `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.
    `boolean` | `isReadonly()` Determine whether the consumer is entitled to write to the exported storage.
    `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.

    - ### Methods inherited from class org.python.core.buffer.SimpleBuffer

      `byteAt, byteAt, copyTo, getLen, getNIOByteBuffer, getPointer, getPointer, intAt, toString`

    - ### Methods inherited from class org.python.core.buffer.BaseBuffer

      `close, copyTo, getBuf, getBuffer, getBufferAgain, getFormat, getItemsize, getNdim, getShape, getStrides, getSuboffsets, hasArray, intAt, isContiguous, isReleased, release`

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

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

- - ### Constructor Detail

    - #### SimpleWritableBuffer

          public SimpleWritableBuffer(int flags,
                              byte[] storage,
                              int index0,
                              int size)
                               throws PyException,
                                      NullPointerException

      Provide an instance of `SimpleWritableBuffer`, on a slice of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
      Parameters:
        `flags` - consumer requirements
        `storage` - the array of bytes storing the implementation of the exporting object
        `index0` - offset where the data starts in that array (item[0])
        `size` - the number of bytes occupied
      Throws:
        `PyException` - (BufferError) when expectations do not correspond with the type
        `NullPointerException`

    - #### SimpleWritableBuffer

          public SimpleWritableBuffer(int flags,
                              byte[] storage)
                               throws PyException,
                                      NullPointerException

      Provide an instance of `SimpleWritableBuffer`, on the entirety of a byte array, meeting the consumer's expectations as expressed in the `flags` argument, which is checked against the capabilities of the buffer type.
      Parameters:
        `flags` - consumer requirements
        `storage` - the array of bytes storing the implementation of the exporting object
      Throws:
        `PyException` - (BufferError) when expectations do not correspond with the type
        `NullPointerException`

  - ### 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`
      Overrides:
        `isReadonly` in class `SimpleBuffer`
      Returns:
        true if writing is not allowed, false if it is.

    - #### storeAt

          public void storeAt(byte value,
                     int index)

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

      `SimpleBuffer` provides an implementation optimised for contiguous bytes in one-dimension.

      Specified by:
        `storeAt` in interface `PyBuffer`
      Overrides:
        `storeAt` in class `BaseBuffer`
      Parameters:
        `value` - to store
        `index` - to location

    - #### storeAt

          public void storeAt(byte value,
                     int... indices)

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

      `SimpleBuffer` provides an implementation optimised for contiguous bytes in one-dimension.

      Specified by:
        `storeAt` in interface `PyBuffer`
      Overrides:
        `storeAt` in class `BaseBuffer`
      Parameters:
        `value` - to store
        `indices` - specifying location to store at

    - #### copyFrom

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

      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.

      `SimpleBuffer` provides an implementation optimised for contiguous bytes in one-dimension.

      Specified by:
        `copyFrom` in interface `PyBuffer`
      Overrides:
        `copyFrom` in class `BaseBuffer`
      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

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

      `SimpleBuffer` provides an implementation optimised for contiguous bytes in one-dimension.

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

    - #### getBufferSlice

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

      Equivalent to `PyBuffer.getBufferSlice(int, int, int, int)` with stride 1.

      `SimpleWritableBuffer` provides an implementation ensuring the returned slice is writable.

      Specified by:
        `getBufferSlice` in interface `PyBuffer`
      Overrides:
        `getBufferSlice` in class `SimpleBuffer`
      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

    - #### getBufferSlice

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

      Get a `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 `PyBuffer.release()` just as if it had been obtained with `PyBuffer.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, `length` = 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, `length` 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.

      `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 length 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.

      `SimpleWritableBuffer` provides an implementation ensuring the returned slice is writable.

      Specified by:
        `getBufferSlice` in interface `PyBuffer`
      Overrides:
        `getBufferSlice` in class `SimpleBuffer`
      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
        `stride` - index-distance in the current buffer between consecutive items in the slice
      Returns:
        a buffer representing the slice

Jython homepage