DataBuffer (TensorFlow NdArray Library 0.2.0 API)

Type Parameters:

T - type of data stored in this buffer

All Known Subinterfaces:

BooleanDataBuffer, ByteDataBuffer, DoubleDataBuffer, FloatDataBuffer, IntDataBuffer, LongDataBuffer, ShortDataBuffer

All Known Implementing Classes:

AbstractDataBuffer
```
public interface DataBuffer<T>
```
A container of data of a specific type.
Instances of DataBuffer map native or heap memory segments to a linear view that supports:
- 64-bits indexing, allowing to work with buffer larger than 2³¹ bytes
- Storage of object of any types and not only primitives
- Generic types allows to work directly with boxed types as well, which does not require explicit buffer types as with the standard JDK buffers.
It is important to note that there is no guarantee the memory managed by a DataBuffer is linear, specially when dealing with non-primitive types or large buffers.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default <R> R`	`accept(DataStorageVisitor<R> visitor)` Visits the backing storage of this buffer.
`DataBuffer<T>`	`copyTo(DataBuffer<T> dst, long size)` Write the references of the objects in the source array into this buffer.
`boolean`	`equals(Object obj)` Checks equality between data buffers.
`T`	`getObject(long index)` Reads the value at the given index.
`boolean`	`isReadOnly()` Tells whether or not this buffer is backed by an accessible array.
`default DataBuffer<T>`	`narrow(long size)` Creates a new buffer whose content is a shared subsequence of this buffer's content, whose size is set to the given value.
`default DataBuffer<T>`	`offset(long index)` Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index.
`default DataBuffer<T>`	`read(T[] dst)` Read the references of the objects in this buffer into the destination array.
`DataBuffer<T>`	`read(T[] dst, int offset, int length)` Read the references of the objects in this buffer into the destination array.
`DataBuffer<T>`	`setObject(T value, long index)` Writes the given value into this buffer at the given index.
`long`	`size()` Size of the buffer, in elements.
`DataBuffer<T>`	`slice(long index, long size)` Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index and of the given size.
`default DataBufferWindow<? extends DataBuffer<T>>`	`window(long size)` Creates a `DataBufferWindow` that provides a partial view of this buffer.
`default DataBuffer<T>`	`write(T[] src)` Write the references of the objects in the source array into this buffer.
`DataBuffer<T>`	`write(T[] src, int offset, int length)` Bulk put method, using int arrays.

- Method Detail
  - size
```
long size()
```
    Size of the buffer, in elements.
    For exemple, in case of a byte buffer, this value is equal to the number of bytes this buffer can hold. For an integer buffer, it is equal to the number of integers, therefore the size in bytes of this buffer is size() * Integer.BYTES.
    
    Returns:
    
    the buffer size
  - isReadOnly
```
boolean isReadOnly()
```
    Tells whether or not this buffer is backed by an accessible array.
    
    Returns:
    
    true if, and only if, this buffer is read-only
  - getObject
```
T getObject(long index)
```
    Reads the value at the given index. Important: Usage of this method should be limited to buffers of non-primitive types or when the data type is not deterministically known by the caller. In any other case, prefer the usage of its primitive variant which will significantly improve performances (e.g. IntDataBuffer.getInt(idx)
    
    Parameters:
    
    index - the index from which the float will be read
    
    Returns:
    
    the value at the given index
    
    Throws:
    
    IndexOutOfBoundsException - if index is negative or not smaller than the buffer size
  - setObject
```
DataBuffer<T> setObject(T value,
                        long index)
```
    Writes the given value into this buffer at the given index. Important: Usage of this method should be limited to buffers of non-primitive types or when the data type is not deterministically known by the caller. In any other case, prefer the usage of its primitive variant which will significantly improve performances (e.g. IntDataBuffer.setInt(idx)
    
    Parameters:
    
    value - the value to be written
    
    index - the index at which the value will be written
    
    Returns:
    
    this buffer
    
    Throws:
    
    IndexOutOfBoundsException - if index is negative or not smaller than the buffer size
    
    ReadOnlyBufferException - if this buffer is read-only
  - read
```
default DataBuffer<T> read(T[] dst)
```
    Read the references of the objects in this buffer into the destination array.
    This method transfers values from this buffer into the given destination array. If there are fewer values in the buffer than are required to satisfy the request, that is, if dst.length > size(), then no values are transferred and a BufferUnderflowException is thrown.
    Otherwise, this method copies n = dst.length values from this buffer into the given array.
    
    Parameters:
    
    dst - the array into which values are to be written
    
    Returns:
    
    this buffer
    
    Throws:
    
    BufferUnderflowException - if there are not enough values to copy from this buffer
  - read
```
DataBuffer<T> read(T[] dst,
                   int offset,
                   int length)
```
    Read the references of the objects in this buffer into the destination array.
    This method transfers values from this buffer into the given destination array. If there are fewer values in the buffer than are required to satisfy the request, that is, if length > size(), then no values are transferred and a BufferUnderflowException is thrown.
    Otherwise, this method copies n = length values from this buffer into the given array starting at the given offset.
    
    Parameters:
    
    dst - the array into which values are to be written
    
    offset - the offset within the array of the first value to be written; must be non-negative and no larger than dst.length
    
    length - the maximum number of values to be written to the given array; must be non-negative and no larger than dst.length - offset
    
    Returns:
    
    this buffer
    
    Throws:
    
    BufferUnderflowException - if there are fewer than length values remaining in this buffer
    
    IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold
  - write
```
default DataBuffer<T> write(T[] src)
```
    Write the references of the objects in the source array into this buffer.
    This method transfers the values in the given source array into this buffer. If there are more values in the source array than in this buffer, that is, if src.length > size(), then no values are transferred and a BufferOverflowException is thrown.
    Otherwise, this method copies n = src.length values from the given array.
    
    Parameters:
    
    src - the source array from which values are to be read
    
    Returns:
    
    this buffer
    
    Throws:
    
    BufferOverflowException - if there is insufficient space in this buffer for the values in the source array
    
    ReadOnlyBufferException - if this buffer is read-only
  - write
```
DataBuffer<T> write(T[] src,
                    int offset,
                    int length)
```
    Bulk put method, using int arrays.
    This method transfers the values in the given source array into this buffer. If there are more values in the source array than in this buffer, that is, if length > size(), then no values are transferred and a BufferOverflowException is thrown.
    Otherwise, this method copies n = length values from the given array into this buffer, starting at the given offset.
    
    Parameters:
    
    src - the source array from which values are to be read
    
    offset - the offset within the array of the first value to be read; must be non-negative and no larger than src.length
    
    length - the number of values to be read from the given array; must be non-negative and no larger than src.length - offset
    
    Returns:
    
    this buffer
    
    Throws:
    
    BufferOverflowException - if there is insufficient space in this buffer for the values in the source array
    
    IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold
    
    ReadOnlyBufferException - if this buffer is read-only
  - copyTo
```
DataBuffer<T> copyTo(DataBuffer<T> dst,
                     long size)
```
    Write the references of the objects in the source array into this buffer.
    If there are more values to copy than the destination buffer size, i.e. size > dst.size(), then no values are transferred and a BufferOverflowException is thrown. On the other hand, if there are more values to copy that the source buffer size, i.e. > src.size(), then a BufferUnderfloatException is thrown.
    Otherwise, this method copies n = size values from this buffer into the destination buffer.
    
    Parameters:
    
    dst - the destination buffer into which values are copied; must not be this buffer
    
    size - number of values to copy to the destination buffer
    
    Returns:
    
    this buffer
    
    Throws:
    
    IllegalArgumentException - if the destination buffer is this buffer
    
    ReadOnlyBufferException - if the destination buffer is read-only
    
    BufferOverflowException - if there is not enough space in destination buffer
    
    BufferUnderflowException - if there are not enough values in the source buffer
  - offset
```
default DataBuffer<T> offset(long index)
```
    Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index.
    The index must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.
    This call is equivalent to slice(index, size() - index)
    
    Parameters:
    
    index - index of the first value of the new buffer created, must not be greater than size()
    
    Returns:
    
    the new buffer
    
    Throws:
    
    IllegalArgumentException - if index do not pass validation checks
  - narrow
```
default DataBuffer<T> narrow(long size)
```
    Creates a new buffer whose content is a shared subsequence of this buffer's content, whose size is set to the given value.
    The new size must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.
    This call is equivalent to slice(0, size)
    
    Parameters:
    
    size - size of this new buffer
    
    Returns:
    
    the new buffer
    
    Throws:
    
    IllegalArgumentException - if index and/or size values do not pass validation checks
  - slice
```
DataBuffer<T> slice(long index,
                    long size)
```
    Creates a new buffer whose content is a shared subsequence of this buffer's content, starting at the given index and of the given size.
    The index plus the new size must not be greater than this buffer size. Changes to this buffer's content will be visible in the new buffer and vice versa. The new buffer will be read-only if, and only if, this buffer is read-only.
    
    Parameters:
    
    index - index of the first value of the new buffer created
    
    size - size of this new buffer, must not be greater than size()
    
    Returns:
    
    the new buffer
    
    Throws:
    
    IllegalArgumentException - if size value do not pass validation checks
  - window
```
default DataBufferWindow<? extends DataBuffer<T>> window(long size)
```
    Creates a DataBufferWindow that provides a partial view of this buffer.
    The created window has a fixed size and can "slide" along this buffer to provide different views of the data without allocating a new buffer instance, like offset(long) does. This improves overall performance when this operation is repeated frequently. For example:
```
 IntDataBuffer bufferA = DataBuffers.ofInts(1024);
 // ... init buffer data
 IntDataBuffer bufferB = DataBuffers.ofInts(1, 2, 3, 4);

 // Return the index of the first occurrence of bufferB in bufferA using a sliding window
 DataBufferWindow<IntDataBuffer> windowA = bufferA.window(4);
 for (int i = 0; i < bufferA.size() - bufferB.size(); ++i) {
     if (windowA.slideTo(i).buffer().equals(bufferB)) {
         return i;
     }
 }
 
```
    The returned object is stateful and is not thread-safe.
    Parameters:
    
    size - size of the window
    
    Returns:
    
    a new window that starts at the index 0 of this buffer
    
    Throws:
    
    UnsupportedOperationException - if this type of buffer does not support buffer windows
  - accept
```
default <R> R accept(DataStorageVisitor<R> visitor)
```
    Visits the backing storage of this buffer.
    The buffer implementation is responsible of passing back a reference to the actual data storage to the provided visitor. The visitor does not have to handle all possible types of data storage and can override only methods for storage it is actually interested in. For any other type of storage, this call will fallback to DataStorageVisitor.fallback() so the visitor can execute some generic routine if needed.
    
    Type Parameters:
    
    R - type of value returned by the visitor
    
    Parameters:
    
    visitor - visits the data storage of this buffer
    
    Returns:
    
    the same value returned by the visitor
  - equals
```
boolean equals(Object obj)
```
    Checks equality between data buffers.
    A data buffer is equal to another object if this object is another DataBuffer of the same size, type and the elements are equal and in the same order. For example:
```
 IntDataBuffer buffer = DataBuffers.of(1, 2, 3);

 assertEquals(buffer, DataBuffers.of(1, 2, 3));  // true
 assertEquals(buffer, DataBuffers.ofObjects(1, 2, 3));  // true, as Integers are equal to ints
 assertNotEquals(buffer, DataBuffers.of(1, 2, 3, 0));  // false, different sizes
 assertNotEquals(buffer, DataBuffers.of(1, 3, 2));  // false, different order
 assertNotEquals(buffer, DataBuffers.of(1L, 2L, 3L));  // false, different types
 
```
    Note that the computation required to verify equality between two buffers can be expensive in some cases and therefore, it is recommended to not use this method in a critical path where performances matter.
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - object to compare this buffer with
    
    Returns:
    
    true if this buffer is equal to the provided object

Interface DataBuffer<T>

Method Summary

Method Detail

size

isReadOnly

getObject

setObject

read

read

write

write

copyTo

offset

narrow

slice

window

accept

equals