Package 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

Modifier and Type	Method	Description
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.