org.apache.datasketches.memory

Interface Buffer

All Superinterfaces:

AutoCloseable, Positional, Resource

All Known Subinterfaces:

WritableBuffer

public interface Buffer
extends Positional

Defines the read-only 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 and Description
default Memory	asMemory() Convert this Buffer to a Memory.
Memory	asMemory(ByteOrder byteOrder) Convert this Buffer to a Memory with the given byte order.
int	compareTo(long thisOffsetBytes, long thisLengthBytes, Buffer that, long thatOffsetBytes, long thatLengthBytes) Compares the bytes of this Buffer to that Buffer.
default Buffer	duplicate() Returns a read-only duplicate view of this Buffer with the same byte order, but independent values of start, position and end.
Buffer	duplicate(ByteOrder byteOrder) Returns a read-only duplicate view of this Buffer with the same but independent values of start, position and end, but with the specified byteOrder.
boolean	getBoolean() Gets the boolean value at the current position.
boolean	getBoolean(long offsetBytes) Gets the boolean value at the given offset.
byte	getByte() Gets the byte value at the current position.
byte	getByte(long offsetBytes) Gets the byte value at the given offset.
void	getByteArray(byte[] dstArray, int dstOffsetBytes, int lengthBytes) Gets the byte array at the current position.
char	getChar() Gets the char value at the current position.
char	getChar(long offsetBytes) Gets the char value at the given offset.
void	getCharArray(char[] dstArray, int dstOffsetChars, int lengthChars) Gets the char array at the current position.
double	getDouble() Gets the double value at the current position.
double	getDouble(long offsetBytes) Gets the double value at the given offset.
void	getDoubleArray(double[] dstArray, int dstOffsetDoubles, int lengthDoubles) Gets the double array at the current position.
float	getFloat() Gets the float value at the current position.
float	getFloat(long offsetBytes) Gets the float value at the given offset.
void	getFloatArray(float[] dstArray, int dstOffsetFloats, int lengthFloats) Gets the float array at the current position.
int	getInt() Gets the int value at the current position.
int	getInt(long offsetBytes) Gets the int value at the given offset.
void	getIntArray(int[] dstArray, int dstOffsetInts, int lengthInts) Gets the int array at the current position.
long	getLong() Gets the long value at the current position.
long	getLong(long offsetBytes) Gets the long value at the given offset.
void	getLongArray(long[] dstArray, int dstOffsetLongs, int lengthLongs) Gets the long array at the current position.
short	getShort() Gets the short value at the current position.
short	getShort(long offsetBytes) Gets the short value at the given offset.
void	getShortArray(short[] dstArray, int dstOffsetShorts, int lengthShorts) Gets the short array at the current position.
default Buffer	region() A region is a read-only view of this object from position to end and with the same byte order.
Buffer	region(long offsetBytes, long capacityBytes, ByteOrder byteOrder) A region is a read-only view of this object from offsetBytes and with a length of capacityBytes and with the given byte order.
static Buffer	wrap(ByteBuffer byteBuffer) Provides a view of the given ByteBuffer for read-only operations.
static Buffer	wrap(ByteBuffer byteBuffer, ByteOrder byteOrder) Provides a view of the given ByteBuffer for read-only operations.

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

wrap

static Buffer wrap(ByteBuffer byteBuffer)

Provides a view of the given ByteBuffer for read-only 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 Buffer will use the ByteOrder of the ByteBuffer.

Parameters:

byteBuffer - the given ByteBuffer, must not be null.

Returns:

a new Buffer for read-only operations on the given ByteBuffer.

wrap

static Buffer wrap(ByteBuffer byteBuffer,
                   ByteOrder byteOrder)

Provides a view of the given ByteBuffer for read-only 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 Buffer will use the given ByteOrder, independent of the ByteOrder of the given ByteBuffer. This does not affect the ByteOrder of data already in the ByteBuffer.

Parameters:

byteBuffer - the given ByteBuffer. It must be non-null

byteOrder - the ByteOrder to be used. It must be non-null.

Returns:

a new Buffer for read-only operations on the given ByteBuffer.

duplicate

default Buffer duplicate()

Returns a read-only duplicate view of this Buffer with the same byte order, 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 read-only duplicate view of this Buffer with the same but independent values of start, position and end.

duplicate

Buffer duplicate(ByteOrder byteOrder)

Returns a read-only duplicate 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 read-only duplicate view of this Buffer with the same but independent values of start, position and end.

region

default Buffer region()

A region is a read-only view of this object from position to end and with the same byte order.

• 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 Buffer representing the defined region based on the current position and end.

region

Buffer region(long offsetBytes,
              long capacityBytes,
              ByteOrder byteOrder)

A region is a read-only view of this object from offsetBytes and with a length of capacityBytes and with the given byte order.

• 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

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 Buffer representing the defined writable region based on the current position, end and byteOrder.

asMemory

default Memory asMemory()

Convert this Buffer to a Memory. The current start, position and end are ignored.

Returns:

Memory

asMemory

Memory asMemory(ByteOrder byteOrder)

Convert this Buffer to a Memory with the given byte order. The current start, position and end are ignored.

Parameters:

byteOrder - the given byte order.

Returns:

Memory

getBoolean

boolean getBoolean()

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

Returns:

the boolean at the current position

getBoolean

boolean getBoolean(long offsetBytes)

Gets the boolean value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the boolean at the given offset

getByte

byte getByte()

Gets the byte value at the current position. Increments the position by Byte.BYTES.

Returns:

the byte at the current position

getByte

byte getByte(long offsetBytes)

Gets the byte value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the byte at the given offset

getByteArray

void getByteArray(byte[] dstArray,
                  int dstOffsetBytes,
                  int lengthBytes)

Gets the byte array at the current position. Increments the position by Byte.BYTES * (lengthBytes - dstOffsetBytes).

Parameters:

dstArray - The preallocated destination array.

dstOffsetBytes - offset in array units

lengthBytes - number of array units to transfer

getChar

char getChar()

Gets the char value at the current position. Increments the position by Character.BYTES.

Returns:

the char at the current position

getChar

char getChar(long offsetBytes)

Gets the char value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the char at the given offset

getCharArray

void getCharArray(char[] dstArray,
                  int dstOffsetChars,
                  int lengthChars)

Gets the char array at the current position. Increments the position by Character.BYTES * (lengthChars - dstOffsetChars).

Parameters:

dstArray - The preallocated destination array.

dstOffsetChars - offset in array units

lengthChars - number of array units to transfer

getDouble

double getDouble()

Gets the double value at the current position. Increments the position by Double.BYTES.

Returns:

the double at the current position

getDouble

double getDouble(long offsetBytes)

Gets the double value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the double at the given offset

getDoubleArray

void getDoubleArray(double[] dstArray,
                    int dstOffsetDoubles,
                    int lengthDoubles)

Gets the double array at the current position. Increments the position by Double.BYTES * (lengthDoubles - dstOffsetDoubles).

Parameters:

dstArray - The preallocated destination array.

dstOffsetDoubles - offset in array units

lengthDoubles - number of array units to transfer

getFloat

float getFloat()

Gets the float value at the current position. Increments the position by Float.BYTES.

Returns:

the float at the current position

getFloat

float getFloat(long offsetBytes)

Gets the float value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the float at the given offset

getFloatArray

void getFloatArray(float[] dstArray,
                   int dstOffsetFloats,
                   int lengthFloats)

Gets the float array at the current position. Increments the position by Float.BYTES * (lengthFloats - dstOffsetFloats).

Parameters:

dstArray - The preallocated destination array.

dstOffsetFloats - offset in array units

lengthFloats - number of array units to transfer

getInt

int getInt()

Gets the int value at the current position. Increments the position by Integer.BYTES.

Returns:

the int at the current position

getInt

int getInt(long offsetBytes)

Gets the int value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the int at the given offset

getIntArray

void getIntArray(int[] dstArray,
                 int dstOffsetInts,
                 int lengthInts)

Gets the int array at the current position. Increments the position by Integer.BYTES * (lengthInts - dstOffsetInts).

Parameters:

dstArray - The preallocated destination array.

dstOffsetInts - offset in array units

lengthInts - number of array units to transfer

getLong

long getLong()

Gets the long value at the current position. Increments the position by Long.BYTES.

Returns:

the long at the current position

getLong

long getLong(long offsetBytes)

Gets the long value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the long at the given offset

getLongArray

void getLongArray(long[] dstArray,
                  int dstOffsetLongs,
                  int lengthLongs)

Gets the long array at the current position. Increments the position by Long.BYTES * (lengthLongs - dstOffsetLongs).

Parameters:

dstArray - The preallocated destination array.

dstOffsetLongs - offset in array units

lengthLongs - number of array units to transfer

getShort

short getShort()

Gets the short value at the current position. Increments the position by Short.BYTES.

Returns:

the short at the current position

getShort

short getShort(long offsetBytes)

Gets the short value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the short at the given offset

getShortArray

void getShortArray(short[] dstArray,
                   int dstOffsetShorts,
                   int lengthShorts)

Gets the short array at the current position. Increments the position by Short.BYTES * (lengthShorts - dstOffsetShorts).

Parameters:

dstArray - The preallocated destination array.

dstOffsetShorts - offset in array units

lengthShorts - number of array units to transfer

compareTo

int compareTo(long thisOffsetBytes,
              long thisLengthBytes,
              Buffer that,
              long thatOffsetBytes,
              long thatLengthBytes)

Compares the bytes of this Buffer to that Buffer. This uses absolute offsets not the start, position and end. Returns (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;. If all bytes are equal up to the shorter of the two lengths, the shorter length is considered to be less than the other.

Parameters:

thisOffsetBytes - the starting offset for this Buffer

thisLengthBytes - the length of the region to compare from this Buffer

that - the other Buffer to compare with

thatOffsetBytes - the starting offset for that Buffer

thatLengthBytes - the length of the region to compare from that Buffer

Returns:

(this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;