# Interface Positional

All Known Subinterfaces:
  `PositionalSegment`

public interface Positional
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". Mark is 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

Modifier and Type
Method
Description
`long`
`getEnd()`
Gets the end position
`static Positional`
`getInstance(long capacity)`
Gets an instance of this Positional.
`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.

## Method Details

### getInstance

static Positional getInstance(long capacity)
Gets an instance of this Positional.

Parameters:
  `capacity` - the upper limit of positional range.
Returns:
  an instance of Positional.

### incrementPosition

Positional incrementPosition(long increment)
Increments the current position by the given increment.

Parameters:
  `increment` - the given increment
Returns:
  this Positional

### 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:
  `PositionInvariantsException` - 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:
  `PositionInvariantsException` - if positional invariants have been violated.