package com.facebook.presto.block;

import com.facebook.presto.Range;
import com.facebook.presto.Tuple;
import com.facebook.presto.TupleInfo;
import com.facebook.presto.slice.Slice;

/**
 * Iterate as:
 * <p/>
 * <pre>{@code
 *  Cursor cursor = ...;
 * <p/>
 *  while (cursor.hasNextValue()) {
 *     cursor.advanceNextValue();
 *     long value = cursor.getLong(...);
 *     ...
 *  }
 * }</pre>
 */
public interface Cursor
{
    /**
     * Gets the type of all tuples in this cursor
     */
    TupleInfo getTupleInfo();

    /**
     * Gets the upper bound on the range of this cursor
     */
    Range getRange();

    /**
     * Is there any more data in the cursor.  When a cursor is finished, the cursor does not have a current value.
     */
    boolean isFinished();

    /**
     * Attempts to advance to the first position of the next value
     *
     * @returns true if the stream had a next value; false if the stream contains no more data
     */
    boolean advanceNextValue();

    /**
     * Attempts to advance to the next position in this stream and possibly to the next value if the current position if the last one for the current value
     *
     * @returns true if the stream had a next position; false if the stream contains no more data
     */
    boolean advanceNextPosition();

    /**
     * Attempts to advance to the requested position or the next immediately available if that position does not exist in this stream (e.g., there's a gap in the sequence)
     *
     * @returns true if the stream advanced to the position; false if the stream contains no more data
     */
    boolean advanceToPosition(long position);

    /**
     * Gets the current tuple.
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    Tuple getTuple();

    /**
     * Gets a field from the current tuple.
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    long getLong(int field);

    /**
     * Gets a field from the current tuple.
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    double getDouble(int field);

    /**
     * Gets a field from the current tuple.
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     *
     */
    Slice getSlice(int field);

    /**
     * Returns the current position of this cursor
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    long getPosition();

    /**
     * Returns the last position of the current value
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    long getCurrentValueEndPosition();

    /**
     * True if the next tuple equals the specified tuple.
     *
     * @throws java.util.NoSuchElementException if this cursor has not been advanced yet
     */
    boolean currentTupleEquals(Tuple value);
}

@@ -266,40 +266,8 @@
 le (
-cursor.hasNextValue()) %7B%0A *     
 curs
@@ -287,17 +287,19 @@
 tValue()
-;
+) %7B
 %0A *     
@@ -601,115 +601,281 @@
   * 
-Is there any more data in the cursor.  When a cursor is f
+Returns true if the cursor has advanced beyond its last position.%0A     * INVARIANT 1: isF
 inished
-, the cursor does not have a current value.
+ will only return true once advance* has returned false.%0A     * INVARIANT 2: all get* and data access methods will throw java.util.NoSuchElementException once isFinished is true
 %0A   
@@ -1820,32 +1820,110 @@
 t tuple.%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -1973,37 +1973,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */
@@ -2087,32 +2087,110 @@
 t tuple.%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -2240,37 +2240,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */
@@ -2361,32 +2361,110 @@
 t tuple.%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -2514,37 +2514,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */
@@ -2639,32 +2639,110 @@
 t tuple.%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -2792,37 +2792,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     *%0A
@@ -2929,32 +2929,110 @@
 s cursor%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -3082,37 +3082,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */
@@ -3208,32 +3208,110 @@
 nt value%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -3361,37 +3361,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */
@@ -3506,32 +3506,110 @@
 d tuple.%0A     *%0A
+     * @throws IllegalStateException if this cursor has not been advanced yet%0A
      * @throws j
@@ -3659,37 +3659,47 @@
 sor has 
-not been advanced yet
+advanced past its last position
 %0A     */

Update Cursor comments