org.apache.datasketches.memory

## Interface WritableBuffer

All Superinterfaces:
  AutoCloseable, Buffer, Positional, Resource

    public interface WritableBuffer
    extends Buffer

Defines the writable API for relative positional access to a resource

Author:
  Lee Rhodes

### Field Summary

### Fields inherited from interface org.apache.datasketches.memory.Resource

`defaultMemReqSvr`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`default WritableMemory` `asWritableMemory()` Convert this WritableBuffer to a WritableMemory.
`WritableMemory` `asWritableMemory(ByteOrder byteOrder)` Convert this WritableBuffer to a WritableMemory with the given byte order.
`void` `clear()` Clears all bytes of this Buffer from position to end to zero.
`void` `fill(byte value)` Fills this Buffer from position to end with the given byte value.
`Object` `getArray()` Returns the primitive backing array, otherwise null.
`void` `putBoolean(boolean value)` Puts the boolean value at the current position.
`void` `putBoolean(long offsetBytes, boolean value)` Puts the boolean value at the given offset.
`void` `putByte(byte value)` Puts the byte value at the current position.
`void` `putByte(long offsetBytes, byte value)` Puts the byte value at the given offset.
`void` `putByteArray(byte[] srcArray, int srcOffsetBytes, int lengthBytes)` Puts the byte array at the current position.
`void` `putChar(char value)` Puts the char value at the current position.
`void` `putChar(long offsetBytes, char value)` Puts the char value at the given offset.
`void` `putCharArray(char[] srcArray, int srcOffsetChars, int lengthChars)` Puts the char array at the current position.
`void` `putDouble(double value)` Puts the double value at the current position.
`void` `putDouble(long offsetBytes, double value)` Puts the double value at the given offset.
`void` `putDoubleArray(double[] srcArray, int srcOffsetDoubles, int lengthDoubles)` Puts the double array at the current position.
`void` `putFloat(float value)` Puts the float value at the current position.
`void` `putFloat(long offsetBytes, float value)` Puts the float value at the given offset.
`void` `putFloatArray(float[] srcArray, int srcOffsetFloats, int lengthFloats)` Puts the float array at the current position.
`void` `putInt(int value)` Puts the int value at the current position.
`void` `putInt(long offsetBytes, int value)` Puts the int value at the given offset.
`void` `putIntArray(int[] srcArray, int srcOffsetInts, int lengthInts)` Puts the int array at the current position.
`void` `putLong(long value)` Puts the long value at the current position.
`void` `putLong(long offsetBytes, long value)` Puts the long value at the given offset.
`void` `putLongArray(long[] srcArray, int srcOffsetLongs, int lengthLongs)` Puts the long array at the current position.
`void` `putShort(long offsetBytes, short value)` Puts the short value at the given offset.
`void` `putShort(short value)` Puts the short value at the current position.
`void` `putShortArray(short[] srcArray, int srcOffsetShorts, int lengthShorts)` Puts the short array at the current position.
`WritableBuffer` `writableDuplicate()` Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end.
`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.
`WritableBuffer` `writableRegion()` A writable region is a writable view of this object.
`WritableBuffer` `writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder)` A writable region is a writable view of this object.
`static WritableBuffer` `writableWrap(ByteBuffer byteBuffer)` Provides a view of the given ByteBuffer for write operations.
`static WritableBuffer` `writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder, MemoryRequestServer memReqSvr)` Provides a view of the given ByteBuffer for write operations.

### Methods inherited from interface org.apache.datasketches.memory.Buffer

`asMemory, asMemory, compareTo, duplicate, duplicate, getBoolean, getBoolean, getByte, getByte, getByteArray, getChar, getChar, getCharArray, getDouble, getDouble, getDoubleArray, getFloat, getFloat, getFloatArray, getInt, getInt, getIntArray, getLong, getLong, getLongArray, getShort, getShort, getShortArray, region, region, wrap, wrap`

### Methods inherited from interface org.apache.datasketches.memory.Positional

`getEnd, getPosition, getRemaining, getStart, hasRemaining, incrementPosition, resetPosition, setPosition, setStartPositionEnd`

### Methods inherited from interface org.apache.datasketches.memory.Resource

`close, equalTo, equalTo, force, getCapacity, getCumulativeOffset, getCumulativeOffset, getMemoryRequestServer, getRelativeOffset, getTypeByteOrder, hasByteBuffer, hasMemoryRequestServer, isAlive, isByteOrderCompatible, isCloseable, isDirect, isDuplicate, isHeap, isLoaded, isMapped, isMemory, isNonNativeOrder, isReadOnly, isRegionView, isSameResource, load, setMemoryRequestServer, toString, toString, xxHash64, xxHash64`

### Method Detail

#### writableWrap

    static WritableBuffer writableWrap(ByteBuffer byteBuffer)

Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. However, the returned Buffer will have position and end set to the ByteBuffer's position and limit, respectively. The returned WritableBuffer will use the ByteOrder of the ByteBuffer.

Parameters:
  `byteBuffer` - the given ByteBuffer. It must be non-null and writable.
Returns:
  a new WritableBuffer for write operations on the given ByteBuffer.

#### writableWrap

    static WritableBuffer writableWrap(ByteBuffer byteBuffer,
                                       ByteOrder byteOrder,
                                       MemoryRequestServer memReqSvr)

Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. However, the returned Buffer will have position and end set to the ByteBuffer's position and limit, respectively. The returned WritableBuffer will use the given ByteOrder, independent of the ByteOrder of the given ByteBuffer.

Parameters:
  `byteBuffer` - the given ByteBuffer. It must be non-null and writable.
  `byteOrder` - the byte order to be used. It must be non-null.
  `memReqSvr` - A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request more memory.
Returns:
  a new WritableBuffer for write operations on the given ByteBuffer.
Throws:
  `IllegalArgumentException` - if ByteBuffer is not writable

#### 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. It must be non-null.
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. It must be non-null.
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. It must be non-null.
Returns:
  WritableMemory

#### putBoolean

    void putBoolean(boolean value)

Puts the boolean value at the current position. Increments the position by Byte.BYTES.

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

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