diff --git a/src/main/java/gr/james/sampling/SkipFunction.java b/src/main/java/gr/james/sampling/SkipFunction.java index 2c7e06f..bc4d7f0 100644 --- a/src/main/java/gr/james/sampling/SkipFunction.java +++ b/src/main/java/gr/james/sampling/SkipFunction.java @@ -2,7 +2,8 @@ /** * A skip function returns how many elements a reservoir algorithm must skip before accepting an element in the - * reservoir. + * reservoir. The {@code SkipFunction} works similarly to an iterator: it's {@link #skip()} method returns the skip + * counts in temporal order as the stream increases. */ @Deprecated @FunctionalInterface @@ -10,10 +11,26 @@ interface SkipFunction { /** * Returns a {@code long} indicating how many elements the algorithm must skip. *

- * This method is called right after an element was accepted in the reservoir. + * The first call to this method return the skip when the stream size equals the sample size. Subsequent calls + * return the skip count between two consecutive acceptances. + *

+ * Visual example for a sample size of 2: + * 


+     * A - A + A - S - A - A - S - S - S - A - S - A
+     *
+ * In this example, the {@code skip} method returns the numbers 0, 1, 0, 3, 1. + *

+ * Same example for a sample size of 3: + * 


+     * A - A - A + S - A - A - S - S - A - A - S - A
+     *
+ * In this example, the {@code skip} method returns the numbers 1, 0, 2, 0, 1. + *

+ * The {@code skip} method may throw {@link StreamOverflowException} if the internal state has overflown and it + * can't process any more skips, which automatically signals the termination of the algorithm. * - * @param streamSize the stream size * @return how many elements the algorithm must skip + * @throws StreamOverflowException if the internal state has overflown and it can't process any more skips */ - long skip(long streamSize); + long skip() throws StreamOverflowException; }