Class SimpleBuffer

    • Constructor Detail

      • SimpleBuffer

        public SimpleBuffer​(int flags,
                            BufferProtocol obj,
                            byte[] storage,
                            int index0,
                            int size)
                     throws PyException,
                            java.lang.ArrayIndexOutOfBoundsException,
                            java.lang.NullPointerException
        Provide an instance of SimpleBuffer, 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
        obj - exporting object (or null)
        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:
        java.lang.NullPointerException - if storage is null
        java.lang.ArrayIndexOutOfBoundsException - if index0 and size are inconsistent with storage.length
        PyException - (BufferError) when expectations do not correspond with the type
      • SimpleBuffer

        public SimpleBuffer​(int flags,
                            BufferProtocol obj,
                            byte[] storage)
                     throws PyException,
                            java.lang.NullPointerException
        Provide an instance of SimpleBuffer, 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
        obj - exporting object (or null)
        storage - the array of bytes storing the implementation of the exporting object
        Throws:
        java.lang.NullPointerException - if storage is null
        PyException - (BufferError) when expectations do not correspond with the type
    • Method Detail

      • getLen

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

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

        Specified by:
        getLen in interface PyBUF
        Overrides:
        getLen in class Base1DBuffer
        Returns:
        the total number of bytes represented.
      • byteIndex

        public int byteIndex​(int index)
                      throws java.lang.IndexOutOfBoundsException
        Convert an item index (for a one-dimensional buffer) to an absolute byte index in the storage shared by the exporter. The storage exported as a PyBuffer is a linearly-indexed sequence of bytes, although it may not actually be a heap-allocated Java byte[] object. The purpose of this method is to allow the exporter to define the relationship between the item index (as used in PyBuffer.byteAt(int)) and the byte-index (as used with the ByteBuffer returned by PyBuffer.getNIOByteBuffer()). See PyBuffer.byteIndex(int[]) for discussion of the multi-dimensional case.

        In SimpleBuffer the calculation is specialised for one dimension, no striding, and an item size of 1.

        Specified by:
        byteIndex in interface PyBuffer
        Overrides:
        byteIndex in class BaseBuffer
        Parameters:
        index - item-index from consumer
        Returns:
        corresponding byte-index in actual storage
        Throws:
        java.lang.IndexOutOfBoundsException
      • getBufferSlice

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

        public PyBuffer getBufferSlice​(int flags,
                                       int start,
                                       int count,
                                       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, count = 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, count 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 count 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.

        Parameters:
        flags - specifying features demanded and the navigational capabilities of the consumer
        start - index in the current buffer
        count - 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
      • getPointer

        public PyBuffer.Pointer getPointer​(int index)
                                    throws java.lang.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
        Overrides:
        getPointer in class BaseBuffer
        Parameters:
        index - in the buffer to position the pointer
        Returns:
        structure defining the byte[] slice that is the shared data
        Throws:
        java.lang.IndexOutOfBoundsException
      • getPointer

        public PyBuffer.Pointer getPointer​(int... indices)
                                    throws java.lang.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 items, 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
        Overrides:
        getPointer in class BaseBuffer
        Parameters:
        indices - multidimensional index at which to position the pointer
        Returns:
        structure defining the byte[] slice that is the shared data
        Throws:
        java.lang.IndexOutOfBoundsException
      • toString

        public java.lang.String toString()
        Description copied from class: BaseBuffer
        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 BaseBuffer