org.apache.datasketches.memory

## Interface Positional

All Superinterfaces:
  AutoCloseable, Resource

All Known Subinterfaces:
  Buffer, WritableBuffer

    public interface Positional
    extends Resource

Defines the relative positional API. This is different from and simpler than Java ByteBuffer positional API.

- 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

### Field Summary

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

`defaultMemReqSvr`

### Method Summary

All Methods Instance Methods Abstract Methods
`long` `getEnd()` Gets the end position
`long` `getPosition()` Gets the current position
`long` `getRemaining()` The number of elements remaining between the current position and the end position
`long` `getStart()` Gets start position
`boolean` `hasRemaining()` Returns true if there are elements remaining between the current position and the end position
`Positional` `incrementPosition(long increment)` Increments the current position by the given increment.
`Positional` `resetPosition()` Resets the current position to the start position, This does not modify any data.
`Positional` `setPosition(long position)` Sets the current position.
`Positional` `setStartPositionEnd(long start, long position, long end)` Sets start position, current position, and end position.

### 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

#### incrementPosition

    Positional incrementPosition(long increment)

Increments the current position by the given increment. Checks that the resource is alive and that the positional invariants are not violated

Parameters:
  `increment` - the given increment
Returns:
  this Positional
Throws:
  `BufferPositionInvariantsException` - if positional invariants have been violated.

#### getEnd

    long getEnd()

Gets the end position

Returns:
  the end position

#### getPosition

    long getPosition()

Gets the current position

Returns:
  the current position

#### getStart

    long getStart()

Gets start position

Returns:
  start position

#### getRemaining

    long getRemaining()

The number of elements remaining between the current position and the end position

Returns:
  `(end - position)`

#### hasRemaining

    boolean hasRemaining()

Returns true if there are elements remaining between the current position and the end position

Returns:
  `(end - position) > 0`

#### resetPosition

    Positional resetPosition()

Resets the current position to the start position, This does not modify any data.

Returns:
  this Positional

#### setPosition

    Positional setPosition(long position)

Sets the current position. Checks that the positional invariants are not violated.

Parameters:
  `position` - the given current position.
Returns:
  this Positional
Throws:
  `BufferPositionInvariantsException` - if positional invariants have been violated.

#### setStartPositionEnd

    Positional setStartPositionEnd(long start,
                                   long position,
                                   long end)

Sets start position, current position, and end position. Checks that the positional invariants are not violated.

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:
  this Positional
Throws:
  `BufferPositionInvariantsException` - if positional invariants have been violated.