BaseBuffer (com.yahoo.datasketches:memory 0.12.2 API)

java.lang.Object
- com.yahoo.memory.BaseBuffer

Direct Known Subclasses:

Buffer
```
public abstract class BaseBuffer
extends Object
```
A new positional API. This is different from and simpler than Java Buffer positional approach.
- All based on longs instead of ints.
- Eliminated "mark". Rarely used and confusing with its silent side effects.
- The invariants are 0 <= start <= position <= end <= capacity.
- It always starts up as (0, 0, capacity, capacity).
- You set (start, position, end) in one call with setStartPositionEnd(long, long, long)
- Position can be set directly or indirectly when using the positional get/put methods.
- Added incrementPosition(long), which is much easier when you know the increment.
- This approach eliminated a number of methods and checks, and has no unseen side effects, e.g., mark being invalidated.
- Clearer method naming (IMHO).
Author:

Lee Rhodes

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`checkValidAndBounds(long offsetBytes, long lengthBytes)` Checks that the specified range of bytes is within bounds of this object, throws `IllegalArgumentException` if it's not: i.
`boolean`	`equals(Object that)` Returns true if the given object is an instance of this class and has equal data contents.
`boolean`	`equalTo(long thisOffsetBytes, Object that, long thatOffsetBytes, long lengthBytes)` Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes.
`ByteBuffer`	`getByteBuffer()` Gets the backing ByteBuffer if it exists, otherwise returns null.
`ByteOrder`	`getByteOrder()` Gets the current ByteOrder.
`long`	`getCapacity()` Gets the capacity of this object in bytes
`long`	`getCumulativeOffset()` Gets the cumulative offset in bytes of this object from the backing resource.
`long`	`getCumulativeOffset(long offsetBytes)` Gets the cumulative offset in bytes of this object from the backing resource including the given offsetBytes.
`static long`	`getCurrentDirectMemoryAllocated()` Gets the current size of active direct memory allocated.
`static long`	`getCurrentDirectMemoryAllocations()` Gets the current number of active direct memory allocations.
`static long`	`getCurrentDirectMemoryMapAllocated()` Gets the current size of active direct memory map allocated.
`static long`	`getCurrentDirectMemoryMapAllocations()` Gets the current number of active direct memory map allocations.
`long`	`getEnd()` Gets the end position
`long`	`getPosition()` Gets the current position
`long`	`getRegionOffset()` Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
`long`	`getRegionOffset(long offsetBytes)` Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
`long`	`getRemaining()` The number of elements remaining between the current position and the end position
`long`	`getStart()` Gets start position
`boolean`	`hasArray()` Returns true if this object is backed by an on-heap primitive array
`boolean`	`hasByteBuffer()` Returns true if this Memory is backed by a ByteBuffer.
`int`	`hashCode()` Returns the hashCode of this object.
`boolean`	`hasRemaining()` Returns true if there are elements remaining between the current position and the end position
`BaseBuffer`	`incrementAndCheckPosition(long increment)` Increments the current position by the given increment.
`BaseBuffer`	`incrementPosition(long increment)` Increments the current position by the given increment.
`boolean`	`isDirect()` Returns true if the backing resource is direct (off-heap) memory.
`boolean`	`isNativeOrder()` Returns true if the current byte order is native order.
`boolean`	`isReadOnly()` Returns true if this object or the backing resource is read-only.
`boolean`	`isSameResource(Object that)` Returns true if the backing resource of this is identical with the backing resource of that.
`boolean`	`isValid()` Returns true if this object is valid and has not been closed.
`BaseBuffer`	`resetPosition()` Resets the current position to the start position, This does not modify any data.
`BaseBuffer`	`setAndCheckPosition(long position)` Sets the current position.
`BaseBuffer`	`setAndCheckStartPositionEnd(long start, long position, long end)` Sets start position, current position, and end position.
`BaseBuffer`	`setPosition(long position)` Sets the current position.
`BaseBuffer`	`setStartPositionEnd(long start, long position, long end)` Sets start position, current position, and end position.
`String`	`toHexString(String header, long offsetBytes, int lengthBytes)` Returns a formatted hex string of a range of this object.
`long`	`xxHash64(long offsetBytes, long lengthBytes, long seed)` Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - incrementPosition
```
public final BaseBuffer incrementPosition(long increment)
```
    Increments the current position by the given increment. Asserts that the resource is valid and that the positional invariants are not violated, otherwise, if asserts are enabled throws an AssertionError.
    
    Parameters:
    
    increment - the given increment
    
    Returns:
    
    BaseBuffer
  - incrementAndCheckPosition
```
public final BaseBuffer incrementAndCheckPosition(long increment)
```
    Increments the current position by the given increment. Checks that the resource is valid and that the positional invariants are not violated, otherwise throws an IllegalArgumentException.
    
    Parameters:
    
    increment - the given increment
    
    Returns:
    
    BaseBuffer
  - getEnd
```
public final long getEnd()
```
    Gets the end position
    
    Returns:
    
    the end position
  - getPosition
```
public final long getPosition()
```
    Gets the current position
    
    Returns:
    
    the current position
  - getStart
```
public final long getStart()
```
    Gets start position
    
    Returns:
    
    start position
  - getRemaining
```
public final long getRemaining()
```
    The number of elements remaining between the current position and the end position
    
    Returns:
    
    (end - position)
  - hasRemaining
```
public final boolean hasRemaining()
```
    Returns true if there are elements remaining between the current position and the end position
    
    Returns:
    
    (end - position) > 0
  - resetPosition
```
public final BaseBuffer resetPosition()
```
    Resets the current position to the start position, This does not modify any data.
    
    Returns:
    
    BaseBuffer
  - setPosition
```
public final BaseBuffer setPosition(long position)
```
    Sets the current position. Asserts that the positional invariants are not violated, otherwise, if asserts are enabled throws an AssertionError.
    
    Parameters:
    
    position - the given current position.
    
    Returns:
    
    BaseBuffer
  - setAndCheckPosition
```
public final BaseBuffer setAndCheckPosition(long position)
```
    Sets the current position. Checks that the positional invariants are not violated, otherwise, throws an IllegalArgumentException.
    
    Parameters:
    
    position - the given current position.
    
    Returns:
    
    BaseBuffer
  - setStartPositionEnd
```
public final BaseBuffer setStartPositionEnd(long start,
                                            long position,
                                            long end)
```
    Sets start position, current position, and end position. Asserts that the positional invariants are not violated, otherwise, if asserts are enabled throws an AssertionError.
    
    Parameters:
    
    start - the start position in the buffer
    
    position - the current position between the start and end
    
    end - the end position in the buffer
    
    Returns:
    
    BaseBuffer
  - setAndCheckStartPositionEnd
```
public final BaseBuffer setAndCheckStartPositionEnd(long start,
                                                    long position,
                                                    long end)
```
    Sets start position, current position, and end position. Checks that the positional invariants are not violated, otherwise, throws an IllegalArgumentException.
    
    Parameters:
    
    start - the start position in the buffer
    
    position - the current position between the start and end
    
    end - the end position in the buffer
    
    Returns:
    
    BaseBuffer
  - equals
```
public final boolean equals(Object that)
```
    Returns true if the given object is an instance of this class and has equal data contents.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    that - the given object
    
    Returns:
    
    true if the given Object is an instance of this class and has equal data contents.
  - equalTo
```
public final boolean equalTo(long thisOffsetBytes,
                             Object that,
                             long thatOffsetBytes,
                             long lengthBytes)
```
    Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes. This will also check two distinct ranges within the same object for eauals.
    
    Parameters:
    
    thisOffsetBytes - the starting offset in bytes for this object.
    
    that - the given object
    
    thatOffsetBytes - the starting offset in bytes for the given object
    
    lengthBytes - the size of the range in bytes
    
    Returns:
    
    true if the given object has equal contents to this object in the given range of bytes.
  - getByteBuffer
```
public ByteBuffer getByteBuffer()
```
    Gets the backing ByteBuffer if it exists, otherwise returns null.
    
    Returns:
    
    the backing ByteBuffer if it exists, otherwise returns null.
  - getByteOrder
```
public final ByteOrder getByteOrder()
```
    Gets the current ByteOrder. This may be different from the ByteOrder of the backing resource.
    
    Returns:
    
    the current ByteOrder.
  - getCapacity
```
public final long getCapacity()
```
    Gets the capacity of this object in bytes
    
    Returns:
    
    the capacity of this object in bytes
  - getCumulativeOffset
```
public final long getCumulativeOffset()
```
    Gets the cumulative offset in bytes of this object from the backing resource. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.
    
    Returns:
    
    the cumulative offset in bytes of this object from the backing resource.
  - getCumulativeOffset
```
public final long getCumulativeOffset(long offsetBytes)
```
    Gets the cumulative offset in bytes of this object from the backing resource including the given offsetBytes. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.
    
    Parameters:
    
    offsetBytes - offset to be added to the cumulative offset.
    
    Returns:
    
    the cumulative offset in bytes of this object from the backing resource including the given offsetBytes.
  - getRegionOffset
```
public final long getRegionOffset()
```
    Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
    
    Returns:
    
    the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
  - getRegionOffset
```
public final long getRegionOffset(long offsetBytes)
```
    Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
    
    Parameters:
    
    offsetBytes - the given offsetBytes
    
    Returns:
    
    the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
  - hasArray
```
public final boolean hasArray()
```
    Returns true if this object is backed by an on-heap primitive array
    
    Returns:
    
    true if this object is backed by an on-heap primitive array
  - hashCode
```
public final int hashCode()
```
    Returns the hashCode of this object.
    The hash code of this object depends upon all of its contents. Because of this, it is inadvisable to use these objects as keys in hash maps or similar data structures unless it is known that their contents will not change.
    
    If it is desirable to use these objects in a hash map depending only on object identity, than the IdentityHashMap can be used.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hashCode of this object.
  - xxHash64
```
public final long xxHash64(long offsetBytes,
                           long lengthBytes,
                           long seed)
```
    Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed. Note that the sequence of bytes is always processed in the same order independent of endianness.
    
    Parameters:
    
    offsetBytes - the given offset in bytes to the first byte of the byte sequence.
    
    lengthBytes - the given length in bytes of the byte sequence.
    
    seed - the given long seed.
    
    Returns:
    
    the 64-bit hash of the sequence of bytes in this object specified by offsetBytes and lengthBytes.
  - hasByteBuffer
```
public final boolean hasByteBuffer()
```
    Returns true if this Memory is backed by a ByteBuffer.
    
    Returns:
    
    true if this Memory is backed by a ByteBuffer.
  - isDirect
```
public final boolean isDirect()
```
    Returns true if the backing resource is direct (off-heap) memory. This is the case for allocated direct memory, memory mapped files,
    
    Returns:
    
    true if the backing resource is direct (off-heap) memory.
  - isNativeOrder
```
public final boolean isNativeOrder()
```
    Returns true if the current byte order is native order.
    
    Returns:
    
    true if the current byte order is native order.
  - isReadOnly
```
public final boolean isReadOnly()
```
    Returns true if this object or the backing resource is read-only.
    
    Returns:
    
    true if this object or the backing resource is read-only.
  - isSameResource
```
public final boolean isSameResource(Object that)
```
    Returns true if the backing resource of this is identical with the backing resource of that. The capacities must be the same. If this is a region, the region offset must also be the same.
    
    Parameters:
    
    that - A different non-null object
    
    Returns:
    
    true if the backing resource of this is the same as the backing resource of that.
  - isValid
```
public boolean isValid()
```
    Returns true if this object is valid and has not been closed. This is relevant only for direct (off-heap) memory and Mapped Files.
    
    Returns:
    
    true if this object is valid and has not been closed.
  - checkValidAndBounds
```
public final void checkValidAndBounds(long offsetBytes,
                                      long lengthBytes)
```
    Checks that the specified range of bytes is within bounds of this object, throws IllegalArgumentException if it's not: i. e. if offsetBytes < 0, or length < 0, or offsetBytes + length > getCapacity().
    
    Parameters:
    
    offsetBytes - the given offset in bytes of this object
    
    lengthBytes - the given length in bytes of this object
  - getCurrentDirectMemoryAllocations
```
public static final long getCurrentDirectMemoryAllocations()
```
    Gets the current number of active direct memory allocations.
    
    Returns:
    
    the current number of active direct memory allocations.
  - getCurrentDirectMemoryAllocated
```
public static final long getCurrentDirectMemoryAllocated()
```
    Gets the current size of active direct memory allocated.
    
    Returns:
    
    the current size of active direct memory allocated.
  - getCurrentDirectMemoryMapAllocations
```
public static final long getCurrentDirectMemoryMapAllocations()
```
    Gets the current number of active direct memory map allocations.
    
    Returns:
    
    the current number of active direct memory map allocations.
  - getCurrentDirectMemoryMapAllocated
```
public static final long getCurrentDirectMemoryMapAllocated()
```
    Gets the current size of active direct memory map allocated.
    
    Returns:
    
    the current size of active direct memory map allocated.
  - toHexString
```
public final String toHexString(String header,
                                long offsetBytes,
                                int lengthBytes)
```
    Returns a formatted hex string of a range of this object. Used primarily for testing.
    
    Parameters:
    
    header - a descriptive header
    
    offsetBytes - offset bytes relative to this object start
    
    lengthBytes - number of bytes to convert to a hex string
    
    Returns:
    
    a formatted hex string in a human readable array

Class BaseBuffer

Method Summary

Methods inherited from class java.lang.Object

Method Detail

incrementPosition

incrementAndCheckPosition

getEnd

getPosition

getStart

getRemaining

hasRemaining

resetPosition

setPosition

setAndCheckPosition

setStartPositionEnd

setAndCheckStartPositionEnd

equals

equalTo

getByteBuffer

getByteOrder

getCapacity

getCumulativeOffset

getCumulativeOffset

getRegionOffset

getRegionOffset

hasArray

hashCode

xxHash64

hasByteBuffer

isDirect

isNativeOrder

isReadOnly

isSameResource

isValid

checkValidAndBounds

getCurrentDirectMemoryAllocations

getCurrentDirectMemoryAllocated

getCurrentDirectMemoryMapAllocations

getCurrentDirectMemoryMapAllocated

toHexString