Package 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

Modifier and Type	Method	Description
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

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