Package org.apache.datasketches.memory

# Interface Memory

All Superinterfaces:
  `Resource`

All Known Subinterfaces:
  `WritableMemory`

public interface Memory extends Resource
`Memory` relies on preview features of the Java platform:

- `Memory` refers to one or more preview APIs: `Arena`.

Programs can only use `Memory` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
Defines the read-only API for offset 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 Buffer`
`asBuffer()`
Returns a new Buffer view of this object.
`Buffer`
`asBuffer(ByteOrder byteOrder)`
Returns a new Buffer view of this object, with the given byte order.
`void`
`copyTo(long srcOffsetBytes, WritableMemory destination, long dstOffsetBytes, long lengthBytes)`
Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method `System.arraycopy(Object, int, Object, int, int)` has.
`boolean`
`getBoolean(long offsetBytes)`
Gets the boolean value at the given offset
`byte`
`getByte(long offsetBytes)`
Gets the byte value at the given offset
`void`
`getByteArray(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int lengthBytes)`
Gets the byte array at the given offset
`char`
`getChar(long offsetBytes)`
Gets the char value at the given offset
`void`
`getCharArray(long offsetBytes, char[] dstArray, int dstOffsetChars, int lengthChars)`
Gets the char array at the given offset
`double`
`getDouble(long offsetBytes)`
Gets the double value at the given offset
`void`
`getDoubleArray(long offsetBytes, double[] dstArray, int dstOffsetDoubles, int lengthDoubles)`
Gets the double array at the given offset
`float`
`getFloat(long offsetBytes)`
Gets the float value at the given offset
`void`
`getFloatArray(long offsetBytes, float[] dstArray, int dstOffsetFloats, int lengthFloats)`
Gets the float array at the given offset
`int`
`getInt(long offsetBytes)`
Gets the int value at the given offset
`void`
`getIntArray(long offsetBytes, int[] dstArray, int dstOffsetInts, int lengthInts)`
Gets the int array at the given offset
`long`
`getLong(long offsetBytes)`
Gets the long value at the given offset
`void`
`getLongArray(long offsetBytes, long[] dstArray, int dstOffsetLongs, int lengthLongs)`
Gets the long array at the given offset
`short`
`getShort(long offsetBytes)`
Gets the short value at the given offset
`void`
`getShortArray(long offsetBytes, short[] dstArray, int dstOffsetShorts, int lengthShorts)`
Gets the short array at the given offset
`static Memory`
`map(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder, ArenaPREVIEW arena)`
Maps the specified portion of the given file into Memory for read operations.
`static Memory`
`map(File file, ArenaPREVIEW arena)`
Maps the given file into Memory for read operations Calling this method is equivalent to calling `map(file, 0, file.length(), scope, ByteOrder.nativeOrder())`PREVIEW.
`default Memory`
`region(long offsetBytes, long capacityBytes)`
A region is a read-only view of this object.
`Memory`
`region(long offsetBytes, long capacityBytes, ByteOrder byteOrder)`
A region is a read-only view of this object.
`static Memory`
`wrap(byte[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)`
Wraps the given primitive array for read operations with the given byte order.
`static Memory`
`wrap(byte[] array, ByteOrder byteOrder)`
Wraps the given primitive array for read operations with the given byte order.
`static Memory`
`wrap(char[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(double[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(float[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(int[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(long[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(short[] array)`
Wraps the given primitive array for read operations assuming native byte order.
`static Memory`
`wrap(ByteBuffer byteBuffer)`
Provides a view of the given ByteBuffer for read-only operations.
`static Memory`
`wrap(ByteBuffer byteBuffer, ByteOrder byteOrder)`
Provides a view of the given ByteBuffer for read-only operations.
`void`
`writeToByteStream(long offsetBytes, int lengthBytes, ByteArrayOutputStream out)`
Writes bytes from a source range of this Memory to the given `WritableByteChannel`.

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

`asByteBufferView, compareTo, equalTo, equalTo, force, getArena, getCapacity, getMemoryRequestServer, getMemorySegment, getRelativeOffset, getTypeByteOrder, hasByteBuffer, hasMemoryRequestServer, isAlive, isBuffer, isByteOrderCompatible, isDirect, isDuplicate, isHeap, isLoaded, isMapped, isMemory, isReadOnly, isRegion, isSameResource, load, mismatch, mismatch, nativeOverlap, scope, setMemoryRequestServer, toByteBuffer, toMemorySegment, toString, toString, unload, xxHash64, xxHash64`

## Method Details

### wrap

static Memory 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. The returned WritableMemory will use the native 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.
Returns:
  a new Memory for read-only operations on the given ByteBuffer.

### wrap

static Memory 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. The returned WritableMemory will use the native 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 byte order to be used. It must be non-null.
Returns:
  a new Memory for read-only operations on the given ByteBuffer.

### map

static Memory map(File file, ArenaPREVIEW arena) throws IOException
Maps the given file into Memory for read operations Calling this method is equivalent to calling `map(file, 0, file.length(), scope, ByteOrder.nativeOrder())`PREVIEW.

Parameters:
  `file` - the given file to map. It must be non-null with a non-negative length and readable.
  `arena` - the given arena. It must be non-null. Warning: This class is not thread-safe. Specifying an Arena that allows multiple threads is not recommended.
Returns:
  Memory for managing the mapped memory.
Throws:
  `IllegalArgumentException` - if path is not associated with the default file system.
  `IllegalStateException` - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
  `IOException` - if the specified path does not point to an existing file, or if some other I/O error occurs.
  `SecurityException` - If a security manager is installed and it denies an unspecified permission required by the implementation.

### map

static Memory map(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder, ArenaPREVIEW arena) throws IOException
Maps the specified portion of the given file into Memory for read operations.

Parameters:
  `file` - the given file to map. It must be non-null,readable and length ≥ 0.
  `fileOffsetBytes` - the position in the given file in bytes. It must not be negative.
  `capacityBytes` - the size of the mapped memory. It must not be negative..
  `byteOrder` - the byte order to be used. It must be non-null.
  `arena` - the given arena. It must be non-null. Warning: This class is not thread-safe. Specifying an Arena that allows multiple threads is not recommended.
Returns:
  Memory for managing the mapped memory.
Throws:
  `IllegalArgumentException` - if path is not associated with the default file system.
  `IllegalStateException` - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
  `IOException` - if the specified path does not point to an existing file, or if some other I/O error occurs.
  `SecurityException` - If a security manager is installed and it denies an unspecified permission required by the implementation.

### region

default Memory region(long offsetBytes, long capacityBytes)
A region is a read-only view of this object.

- Returned object's origin = this object's origin + offsetBytes
- Returned object's capacity = capacityBytes

Parameters:
  `offsetBytes` - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
  `capacityBytes` - the capacity of the region in bytes. It must be ≥ 0.
Returns:
  a new Memory representing the defined region based on the given offsetBytes and capacityBytes.

### region

Memory region(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
A region is a read-only view of this object.

- Returned object's origin = this object's origin + offsetBytes
- Returned object's capacity = capacityBytes
- Returned object's byte order = byteOrder

Parameters:
  `offsetBytes` - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
  `capacityBytes` - the capacity of the region in bytes. It must be ≥ 0.
  `byteOrder` - the given byte order. It must be non-null.
Returns:
  a new Memory representing the defined region based on the given offsetBytes, capacityBytes and byteOrder.

### asBuffer

default Buffer asBuffer()
Returns a new Buffer view of this object.

- Returned object's origin = this object's origin
- Returned object's start = 0
- Returned object's position = 0
- Returned object's end = this object's capacity
- Returned object's capacity = this object's capacity
- Returned object's start, position and end are mutable

Returns:
  a new Buffer

### asBuffer

Buffer asBuffer(ByteOrder byteOrder)
Returns a new Buffer view of this object, with the given byte order.

- Returned object's origin = this object's origin
- Returned object's start = 0
- Returned object's position = 0
- Returned object's end = this object's capacity
- Returned object's capacity = this object's capacity
- Returned object's start, position and end are mutable

Parameters:
  `byteOrder` - the given byte order. It must be non-null.
Returns:
  a new Buffer with the given byteOrder.

### wrap

static Memory wrap(byte[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(byte[] array, ByteOrder byteOrder)
Wraps the given primitive array for read operations with the given byte order.

Parameters:
  `array` - the given primitive array.
  `byteOrder` - the byte order to be used
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
Wraps the given primitive array for read operations with the given byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
  `offsetBytes` - the byte offset into the given array
  `lengthBytes` - the number of bytes to include from the given array.
  `byteOrder` - the byte order to be used. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(char[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(short[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(int[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(long[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(float[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### wrap

static Memory wrap(double[] array)
Wraps the given primitive array for read operations assuming native byte order.

Parameters:
  `array` - the given primitive array. It must be non-null.
Returns:
  a new Memory for read operations

### getBoolean

boolean getBoolean(long offsetBytes)
Gets the boolean value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the boolean at the given offset

### getByte

byte getByte(long offsetBytes)
Gets the byte value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the byte at the given offset

### getByteArray

void getByteArray(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int lengthBytes)
Gets the byte array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetBytes` - offset in array units
  `lengthBytes` - number of array units to transfer

### getChar

char getChar(long offsetBytes)
Gets the char value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the char at the given offset

### getCharArray

void getCharArray(long offsetBytes, char[] dstArray, int dstOffsetChars, int lengthChars)
Gets the char array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetChars` - offset in array units
  `lengthChars` - number of array units to transfer

### getDouble

double getDouble(long offsetBytes)
Gets the double value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the double at the given offset

### getDoubleArray

void getDoubleArray(long offsetBytes, double[] dstArray, int dstOffsetDoubles, int lengthDoubles)
Gets the double array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetDoubles` - offset in array units
  `lengthDoubles` - number of array units to transfer

### getFloat

float getFloat(long offsetBytes)
Gets the float value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the float at the given offset

### getFloatArray

void getFloatArray(long offsetBytes, float[] dstArray, int dstOffsetFloats, int lengthFloats)
Gets the float array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetFloats` - offset in array units
  `lengthFloats` - number of array units to transfer

### getInt

int getInt(long offsetBytes)
Gets the int value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the int at the given offset

### getIntArray

void getIntArray(long offsetBytes, int[] dstArray, int dstOffsetInts, int lengthInts)
Gets the int array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetInts` - offset in array units
  `lengthInts` - number of array units to transfer

### getLong

long getLong(long offsetBytes)
Gets the long value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the long at the given offset

### getLongArray

void getLongArray(long offsetBytes, long[] dstArray, int dstOffsetLongs, int lengthLongs)
Gets the long array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetLongs` - offset in array units
  `lengthLongs` - number of array units to transfer

### getShort

short getShort(long offsetBytes)
Gets the short value at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
Returns:
  the short at the given offset

### getShortArray

void getShortArray(long offsetBytes, short[] dstArray, int dstOffsetShorts, int lengthShorts)
Gets the short array at the given offset

Parameters:
  `offsetBytes` - offset bytes relative to this Memory start
  `dstArray` - The preallocated destination array.
  `dstOffsetShorts` - offset in array units
  `lengthShorts` - number of array units to transfer

### copyTo

void copyTo(long srcOffsetBytes, WritableMemory destination, long dstOffsetBytes, long lengthBytes)
Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method `System.arraycopy(Object, int, Object, int, int)` has. However, if the source and the destination ranges are exactly the same, this method throws `IllegalArgumentException`, because it should never be needed in real-world scenarios and therefore indicates a bug.

Parameters:
  `srcOffsetBytes` - the source offset for this Memory
  `destination` - the destination Memory, which may not be Read-Only.
  `dstOffsetBytes` - the destination offset
  `lengthBytes` - the number of bytes to copy

### writeToByteStream

void writeToByteStream(long offsetBytes, int lengthBytes, ByteArrayOutputStream out) throws IOException
Writes bytes from a source range of this Memory to the given `WritableByteChannel`.

Parameters:
  `offsetBytes` - the source offset for this Memory
  `lengthBytes` - the number of bytes to copy
  `out` - the destination ByteArrayOutputStream
Throws:
  `IOException` - may occur while writing to the ByteArrayOutputStream.