Package org.apache.datasketches.memory

Interface WritableBuffer

  • All Superinterfaces:
    BaseBuffer, BaseState, Buffer
    public interface WritableBuffer
extends Buffer
    Defines the writable API for relative positional access to a resource
    Author:
    Lee Rhodes

    • Method Detail

      • writableWrap

        static WritableBuffer writableWrap​(ByteBuffer byteBuf)
        Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has the same byte order, as the given ByteBuffer.
        Parameters:
        byteBuf - the given ByteBuffer. It must be non-null and with capacity ≥ 0.
        Returns:
        a new WritableBuffer for write operations on the given ByteBuffer.

      • writableWrap

        static WritableBuffer writableWrap​(ByteBuffer byteBuf,
                                   ByteOrder byteOrder,
                                   MemoryRequestServer memReqSvr)
        Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has the given byte order, ignoring the byte order of the given ByteBuffer for future writes and following reads. However, this does not change the byte order of data already in the ByteBuffer.
        Parameters:
        byteBuf - the given ByteBuffer. It must be non-null and with capacity ≥ 0.
        byteOrder - the byte order to be used.
        memReqSvr - A user-specified MemoryRequestServer, which must not be null. This is a callback mechanism for a user client to request a larger WritableBuffer.
        Returns:
        a new WritableBuffer for write operations on the given ByteBuffer.

      • writableDuplicate

        WritableBuffer writableDuplicate()
        Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end.
        • Returned object's origin = this object's origin
        • Returned object's start = this object's start
        • Returned object's position = this object's position
        • Returned object's end = this object's end
        • Returned object's capacity = this object' capacityBytes
        • Returned object's start, position and end are mutable and independent of this object's start, position and end
        Returns:
        a duplicate writable view of this Buffer with the same but independent values of start, position and end.

      • writableDuplicate

        WritableBuffer writableDuplicate​(ByteOrder byteOrder)
        Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end, but with the specified byteOrder.
        • Returned object's origin = this object's origin
        • Returned object's start = this object's start
        • Returned object's position = this object's position
        • Returned object's end = this object's end
        • Returned object's capacity = this object' capacityBytes
        • Returned object's start, position and end are mutable and independent of this object's start, position and end
        Parameters:
        byteOrder - the given ByteOrder.
        Returns:
        a duplicate writable view of this Buffer with the same but independent values of start, position and end.

      • writableRegion

        WritableBuffer writableRegion()
        A writable region is a writable view of this object.
        • Returned object's origin = this object's position
        • Returned object's start = 0
        • Returned object's position = 0
        • Returned object's end = this object's (end - position)
        • Returned object's capacity = this object's (end - position)
        • Returned object's start, position and end are mutable and independent of this object's start, position and end
        Returns:
        a new WritableBuffer representing the defined writable region.

      • writableRegion

        WritableBuffer writableRegion​(long offsetBytes,
                              long capacityBytes,
                              ByteOrder byteOrder)
        A writable region is a writable view of this object.
        • Returned object's origin = this objects' origin + offsetBytes
        • Returned object's start = 0
        • Returned object's position = 0
        • Returned object's end = capacityBytes
        • Returned object's capacity = capacityBytes
        • Returned object's start, position and end are mutable and independent of this object's start, position and end
        • Returned object's byte order = byteOrder

        Note: asWritableMemory() and asMemory() will return the originating Memory byte order.

        Parameters:
        offsetBytes - the starting offset with respect to the origin of this WritableBuffer
        capacityBytes - the capacity of the returned region in bytes
        byteOrder - the given byte order
        Returns:
        a new WritableBuffer representing the defined writable region with the given offsetBytes, capacityBytes and byte order.

      • asWritableMemory

        default WritableMemory asWritableMemory()
        Convert this WritableBuffer to a WritableMemory. If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
        Returns:
        WritableMemory

      • asWritableMemory

        WritableMemory asWritableMemory​(ByteOrder byteOrder)
        Convert this WritableBuffer to a WritableMemory with the given byte order. If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.
        Parameters:
        byteOrder - the byte order to be used.
        Returns:
        WritableMemory

      • putBoolean

        void putBoolean​(boolean value)
        Puts the boolean value at the current position. Increments the position by 1.
        Parameters:
        value - the value to put

      • putBoolean

        void putBoolean​(long offsetBytes,
                boolean value)
        Puts the boolean value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start.
        value - the value to put

      • putBooleanArray

        void putBooleanArray​(boolean[] srcArray,
                     int srcOffsetBooleans,
                     int lengthBooleans)
        Puts the boolean array at the current position. Increments the position by lengthBooleans - srcOffsetBooleans.
        Parameters:
        srcArray - The source array.
        srcOffsetBooleans - offset in array units
        lengthBooleans - number of array units to transfer

      • putByte

        void putByte​(byte value)
        Puts the byte value at the current position. Increments the position by Byte.BYTES.
        Parameters:
        value - the value to put

      • putByte

        void putByte​(long offsetBytes,
             byte value)
        Puts the byte value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putByteArray

        void putByteArray​(byte[] srcArray,
                  int srcOffsetBytes,
                  int lengthBytes)
        Puts the byte array at the current position. Increments the position by Byte.BYTES * (lengthBytes - srcOffsetBytes).
        Parameters:
        srcArray - The source array.
        srcOffsetBytes - offset in array units
        lengthBytes - number of array units to transfer

      • putChar

        void putChar​(char value)
        Puts the char value at the current position. Increments the position by Character.BYTES.
        Parameters:
        value - the value to put

      • putChar

        void putChar​(long offsetBytes,
             char value)
        Puts the char value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putCharArray

        void putCharArray​(char[] srcArray,
                  int srcOffsetChars,
                  int lengthChars)
        Puts the char array at the current position. Increments the position by Character.BYTES * (lengthChars - srcOffsetChars).
        Parameters:
        srcArray - The source array.
        srcOffsetChars - offset in array units
        lengthChars - number of array units to transfer

      • putDouble

        void putDouble​(double value)
        Puts the double value at the current position. Increments the position by Double.BYTES.
        Parameters:
        value - the value to put

      • putDouble

        void putDouble​(long offsetBytes,
               double value)
        Puts the double value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putDoubleArray

        void putDoubleArray​(double[] srcArray,
                    int srcOffsetDoubles,
                    int lengthDoubles)
        Puts the double array at the current position. Increments the position by Double.BYTES * (lengthDoubles - srcOffsetDoubles).
        Parameters:
        srcArray - The source array.
        srcOffsetDoubles - offset in array units
        lengthDoubles - number of array units to transfer

      • putFloat

        void putFloat​(float value)
        Puts the float value at the current position. Increments the position by Float.BYTES.
        Parameters:
        value - the value to put

      • putFloat

        void putFloat​(long offsetBytes,
              float value)
        Puts the float value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putFloatArray

        void putFloatArray​(float[] srcArray,
                   int srcOffsetFloats,
                   int lengthFloats)
        Puts the float array at the current position. Increments the position by Float.BYTES * (lengthFloats - srcOffsetFloats).
        Parameters:
        srcArray - The source array.
        srcOffsetFloats - offset in array units
        lengthFloats - number of array units to transfer

      • putInt

        void putInt​(int value)
        Puts the int value at the current position. Increments the position by Integer.BYTES.
        Parameters:
        value - the value to put

      • putInt

        void putInt​(long offsetBytes,
            int value)
        Puts the int value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putIntArray

        void putIntArray​(int[] srcArray,
                 int srcOffsetInts,
                 int lengthInts)
        Puts the int array at the current position. Increments the position by Integer.BYTES * (lengthInts - srcOffsetInts).
        Parameters:
        srcArray - The source array.
        srcOffsetInts - offset in array units
        lengthInts - number of array units to transfer

      • putLong

        void putLong​(long value)
        Puts the long value at the current position. Increments the position by Long.BYTES.
        Parameters:
        value - the value to put

      • putLong

        void putLong​(long offsetBytes,
             long value)
        Puts the long value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putLongArray

        void putLongArray​(long[] srcArray,
                  int srcOffsetLongs,
                  int lengthLongs)
        Puts the long array at the current position. Increments the position by Long.BYTES * (lengthLongs - srcOffsetLongs).
        Parameters:
        srcArray - The source array.
        srcOffsetLongs - offset in array units
        lengthLongs - number of array units to transfer

      • putShort

        void putShort​(short value)
        Puts the short value at the current position. Increments the position by Short.BYTES.
        Parameters:
        value - the value to put

      • putShort

        void putShort​(long offsetBytes,
              short value)
        Puts the short value at the given offset. This does not change the position.
        Parameters:
        offsetBytes - offset bytes relative to this WritableMemory start
        value - the value to put

      • putShortArray

        void putShortArray​(short[] srcArray,
                   int srcOffsetShorts,
                   int lengthShorts)
        Puts the short array at the current position. Increments the position by Short.BYTES * (lengthShorts - srcOffsetShorts).
        Parameters:
        srcArray - The source array.
        srcOffsetShorts - offset in array units
        lengthShorts - number of array units to transfer

      • getArray

        Object getArray()
        Returns the primitive backing array, otherwise null.
        Returns:
        the primitive backing array, otherwise null.

      • clear

        void clear()
        Clears all bytes of this Buffer from position to end to zero. The position will be set to end.

      • fill

        void fill​(byte value)
        Fills this Buffer from position to end with the given byte value. The position will be set to end.
        Parameters:
        value - the given byte value

      • getMemoryRequestServer

        MemoryRequestServer getMemoryRequestServer()
        WritableBuffer enables this for ByteBuffer backed resources. However, the object returned is in the form of a WritableMemory. To convert to WritableBuffer use asWritableBuffer(). To enable for Heap and Direct Memory resources, use the WritableMemory to configure and then call asWritableBuffer(). Map backed resources will always return null. Gets the MemoryRequestServer object, if set, for the above resources to request additional memory. The user must customize the actions of the MemoryRequestServer by implementing the MemoryRequestServer interface and set using the following method: Simple implementation examples include the DefaultMemoryRequestServer in the main tree, as well as the ExampleMemoryRequestServerTest and the use with ByteBuffer documented in the DruidIssue11544Test in the test tree.
        Returns:
        the MemoryRequestServer object or null.