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

org.python.core.buffer

## Class Strided1DWritableBuffer

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

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

      public class Strided1DWritableBuffer
      extends Strided1DBuffer

  Read-write buffer API over a one-dimensional array of one-byte items, that are evenly-spaced in a storage array. The storage conventions are described in `Strided1DBuffer` of which this is an extension providing write operations and a writable slice.

- - ### 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
    `Strided1DWritableBuffer(int flags, byte[] storage, int index0, int length, int stride)` Provide an instance of `Strided1DWritableBuffer` on a particular array of bytes specifying a starting index, the number of items in the result, and a byte-indexing stride.

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

      `byteAt, copyTo, getPointer, getPointer, getStrides`

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

      `byteAt, close, copyFrom, copyTo, getBuf, getBuffer, getBufferAgain, getBufferSlice, getFormat, getItemsize, getLen, getNdim, getNIOByteBuffer, getShape, getSuboffsets, hasArray, intAt, intAt, isContiguous, isReleased, release, storeAt, toString`

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

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

- - ### Constructor Detail

    - #### Strided1DWritableBuffer

          public Strided1DWritableBuffer(int flags,
                                 byte[] storage,
                                 int index0,
                                 int length,
                                 int stride)
                                  throws ArrayIndexOutOfBoundsException,
                                         NullPointerException,
                                         PyException

      Provide an instance of `Strided1DWritableBuffer` on a particular array of bytes specifying a starting index, the number of items in the result, and a byte-indexing stride. The result of `byteAt(i)` will be equal to `storage[index0+stride*i]` (whatever the sign of `stride>0`), valid for `0<=i<length`.

      The constructed `PyBuffer` meets the consumer's expectations as expressed in the `flags` argument, or an exception will be thrown if these are incompatible with the type (e.g. the consumer does not specify that it understands the strides array). Note that the actual range in the `storage` array, the lowest and highest index, is not explicitly passed, but is implicit in `index0`, `length` and `stride`. The caller is responsible for checking these fall within the array, or the sub-range the caller is allowed to use.

      Parameters:
        `flags` - consumer requirements
        `storage` - raw byte array containing exported data
        `index0` - index into storage of item[0]
        `length` - number of items in the slice
        `stride` - in between successive elements of the new PyBuffer
      Throws:
        `NullPointerException` - if `storage` is null
        `ArrayIndexOutOfBoundsException` - if `index0`, `length` and `stride` are inconsistent with `storage.length`
        `PyException` - (BufferError) when expectations do not correspond with the type

  - ### 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 `Strided1DBuffer`
      Returns:
        true if writing is not allowed, false if it is.

    - #### 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`
      Overrides:
        `storeAt` in class `BaseBuffer`
      Parameters:
        `value` - to store
        `index` - to location
      Throws:
        `IndexOutOfBoundsException`
        `PyException`

    - #### 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. `Strided1DWritableBuffer` provides a version optimised for strided 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
      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,
                                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.

      `Strided1DBuffer` provides an implementation for slicing already-strided bytes in one dimension. In that case, x(i) = u(r+ip) for i = 0..L-1 where u is the underlying buffer, and r, p and L are the start, stride and length with which x was created from u. Thus y(k) = u(r+sp+kmp), that is, the composite `index0` is r+sp and the composite `stride` is mp.

      `Strided1DWritableBuffer` provides an implementation that returns a writable slice.

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