Package net.algart.arrays

Interface DataByteBuffer

All Superinterfaces:

DataBuffer

public interface DataByteBuffer
extends DataBuffer

Data buffer for byte elements.

Author:

Daniel Alievsky

Nested Class Summary

Nested classes/interfaces inherited from interface net.algart.arrays.DataBuffer

DataBuffer.AccessMode

Method Summary

Modifier and Type	Method	Description
byte[]	data()	Returns the Java array which contains the mapped region of the data.
DataByteBuffer	force()	Writes all elements in the actual region of the DataBuffer.data() Java array (from DataBuffer.fromIndex(), inclusive, to DataBuffer.toIndex(), exclusive) back to the underlying data storage (usually AlgART array).
DataByteBuffer	map(long position)	Maps this data buffer to the specified position of the underlying data storage (usually AlgART array) for accessing first DataBuffer.capacity() elements starting from this position.
DataByteBuffer	map(long position, boolean readData)	An analog of DataBuffer.map(long) with the only exception, that when readData=false, reading data from the data storage is not guaranteed.
DataByteBuffer	map(long position, long maxCount)	Equivalent to map(position, maxCount, true).
DataByteBuffer	map(long position, long maxCount, boolean readData)	Maps this data buffer to the specified position of the underlying data storage (usually AlgART array) for accessing first min(maxCount,DataBuffer.capacity()) elements starting from this position.
DataByteBuffer	mapNext()	Maps the next region in the underlying data storage (usually AlgART array).
DataByteBuffer	mapNext(boolean readData)	An analog of DataBuffer.mapNext() with the only exception, that when readData=false, reading data from the data storage is not guaranteed.

Methods inherited from interface net.algart.arrays.DataBuffer

capacity, cnt, count, force, from, fromIndex, hasData, isDirect, mode, position, to, toIndex

Method Details

map

DataByteBuffer map(long position)

Description copied from interface: DataBuffer

Maps this data buffer to the specified position of the underlying data storage (usually AlgART array) for accessing first DataBuffer.capacity() elements starting from this position. The fragment of the data storage will be loaded and accessible in the DataBuffer.data() Java array at the positions DataBuffer.fromIndex()..DataBuffer.toIndex()-1. Equivalent to map(DataBuffer.position(),DataBuffer.capacity(),true).

The passed argument must be in range 0..length, where length is the total number of elements in the underlying data storage (for an AlgART array, its Array.length()). The number of actually mapped elements (DataBuffer.count()) will be equal to min(DataBuffer.capacity(),length-position).

Specified by:

map in interface DataBuffer

Parameters:

position - new mapping position.

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.mapNext()
• DataBuffer.map(long, long)
• DataBuffer.map(long, boolean)

map

DataByteBuffer map(long position,
 boolean readData)

Description copied from interface: DataBuffer

An analog of DataBuffer.map(long) with the only exception, that when readData=false, reading data from the data storage is not guaranteed. (When readData=true, there is no difference with DataBuffer.map(long) method.) Equivalent to map(DataBuffer.position(),DataBuffer.capacity(),readData). The mode readData=false can be useful for optimization in DataBuffer.AccessMode.READ_WRITE mode, if you are sure that you will fully rewrite all mapped elements and, so, want to save time by avoiding useless reading them.

Specified by:

map in interface DataBuffer

Parameters:

position - new mapping position.

readData - if true, all mapped elements will be really loaded from the data storage; if false, there is no such a guarantee.

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.mapNext(boolean)
• DataBuffer.map(long, long, boolean)

mapNext

DataByteBuffer mapNext()

Description copied from interface: DataBuffer

Maps the next region in the underlying data storage (usually AlgART array). Equivalent to map(DataBuffer.position() + DataBuffer.count()). In particular, if the buffer is newly created and DataBuffer.map(long) and mapNext() were never called yet, this method is equivalent to map(0).

The following loop allows to sequentially map all elements of the underlying data storage:

 for (buf.map(0); buf.DataBuffer.hasData(); buf.mapNext()) {
     // ... (processing elements of buf.DataBuffer.data())
 }
 

Specified by:

mapNext in interface DataBuffer

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.map(long)
• DataBuffer.mapNext(boolean)

mapNext

DataByteBuffer mapNext(boolean readData)

Description copied from interface: DataBuffer

An analog of DataBuffer.mapNext() with the only exception, that when readData=false, reading data from the data storage is not guaranteed. (When readData=true, there is no difference with DataBuffer.mapNext() method.) Equivalent to map(DataBuffer.position() + DataBuffer.count(), readData). The mode readData=false can be useful for optimization in DataBuffer.AccessMode.READ_WRITE mode, if you are sure that you will fully rewrite all mapped elements and, so, want to save time by avoiding useless reading them.

Specified by:

mapNext in interface DataBuffer

Parameters:

readData - if true, all mapped elements will be really loaded from the data storage; if false, there is no such a guarantee.

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.map(long, boolean)

map

DataByteBuffer map(long position,
 long maxCount)

Description copied from interface: DataBuffer

Equivalent to map(position, maxCount, true).

Specified by:

map in interface DataBuffer

Parameters:

position - new mapping position.

maxCount - this method does not guarantee that the elements after #position+maxCount-1 will be loaded into the buffer.

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.map(long)

map

DataByteBuffer map(long position,
 long maxCount,
 boolean readData)

Description copied from interface: DataBuffer

Maps this data buffer to the specified position of the underlying data storage (usually AlgART array) for accessing first min(maxCount,DataBuffer.capacity()) elements starting from this position. If readData=true, the fragment of the data storage will be loaded and accessible in the DataBuffer.data() Java array at the positions DataBuffer.fromIndex()..DataBuffer.toIndex()-1. If readData=false, the behaviour is the same with the exception of reading data from the data storage is not guaranteed. This mode can be useful for optimization in DataBuffer.AccessMode.READ_WRITE mode, if you are sure that you will fully rewrite all mapped elements and, so, want to save time by avoiding useless reading them.

The passed position must be in range 0..length, where length is the total number of elements in the underlying data storage (for an AlgART array, its Array.length()). The number of actually mapped elements (DataBuffer.count()) will be equal to min(maxCount,DataBuffer.capacity(),length-position).

This method should be used instead of the full map(position) version, if you need to access a less number of elements than the full buffer capacity or if you are going to fully rewrite all mapped elements.

Specified by:

map in interface DataBuffer

Parameters:

position - new mapping position.

maxCount - this method does not guarantee that the elements after #position+maxCount-1 will be loaded into the buffer.

readData - if true, all mapped elements will be really loaded from the data storage; if false, there is no such a guarantee.

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.map(long)
• DataBuffer.map(long, long)

force

DataByteBuffer force()

Description copied from interface: DataBuffer

Writes all elements in the actual region of the DataBuffer.data() Java array (from DataBuffer.fromIndex(), inclusive, to DataBuffer.toIndex(), exclusive) back to the underlying data storage (usually AlgART array). May do nothing if the changes in this Java array reflect in the storage immediately (for example, for direct buffers).

This method must be called to ensure that all changes, performed in the mapped data elements, will be reflected in the original data storage.

This method must not be called in the READ access mode. This method does nothing in the PRIVATE access mode.

Specified by:

force in interface DataBuffer

Returns:

a reference to this data buffer.

See Also:

• DataBuffer.force(long, long)

data

byte[] data()

Description copied from interface: DataBuffer

Returns the Java array which contains the mapped region of the data. The actual data elements are placed at the positions DataBuffer.fromIndex()..DataBuffer.toIndex()-1. For bit elements, returned Java array is a packed long[] array, and the positions in this array should be considered in terms of PackedBitArrays class.

The length of the returned array is always enough to fit the DataBuffer.fromIndex()..DataBuffer.toIndex()-1 positions range in it.

Note: this method returns null if map / mapNext methods were never called for this buffer yet, that is, if it is newly created.

Warning: the reference, returned by this method, may change after any call of map or mapNext methods.

Specified by:

data in interface DataBuffer

Returns:

the Java array which contains the mapped region of the data.