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

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`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;