Package org.apache.datasketches.memory

Interface Positional

All Known Subinterfaces:
Buffer, WritableBuffer
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". 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
    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

    • 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.