Introduced jump inside iterator

This is a memory optimization for the case when a user required to
modify iterator by moving it to a desire position. This works the same
way as `iteraotr(fromElement)` but doesn't create a new iterator that
decreases memory footprint at an algorithms which makes a lot of jumps.

Author: catap

drv/AVLTreeSet.drv

@@ -1127,6 +1127,17 @@ public class AVL_TREE_SET KEY_GENERIC extends ABSTRACT_SORTED_SET KEY_GENERIC im
 			AVL_TREE_SET.this.remove(curr.key);
 			curr = null;
 		}
+
+		@Override
+		public void jump(final KEY_GENERIC_TYPE fromElement) {
+			if ((next = locateKey(fromElement)) != null) {
+				if (compare(next.key, fromElement) <= 0) {
+					prev = next;
+					next = next.next();
+				}
+				else prev = next.prev();
+			}
+		}
 	}
 
 	@Override

drv/Iterator.drv

@@ -153,4 +153,27 @@ public interface KEY_ITERATOR KEY_GENERIC extends Iterator<KEY_GENERIC_CLASS> {
 		while(i-- != 0 && hasNext()) NEXT_KEY();
 		return n - i - 1;
 	}
+
+	/** Moves back or forward to the elements in this set,
+	 * starting from a given element of the domain.
+	 *
+	 * <p>This method moves an iterator to the specified starting point.
+	 * The starting point is any element comparable to the elements of this set
+	 * (even if it does not actually belong to the set).
+	 * The next element of the returned iterator is the least element of
+	 * the set that is greater than the starting point (if there are no
+	 * elements greater than the starting point, {@link
+	 * it.unimi.dsi.fastutil.BidirectionalIterator#hasNext() hasNext()} will return
+	 * {@code false}). The previous element of the returned iterator is
+	 * the greatest element of the set that is smaller than or equal to the
+	 * starting point (if there are no elements smaller than or equal to the
+	 * starting point, {@link it.unimi.dsi.fastutil.BidirectionalIterator#hasPrevious()
+	 * hasPrevious()} will return {@code false}).
+	 *
+	 * @param fromElement an element to start from.
+	 * @throws UnsupportedOperationException if this set does not support jump at iterator.
+	 */
+	default void jump(final KEY_GENERIC_TYPE fromElement) {
+		throw new UnsupportedOperationException();
+	}
 }

drv/RBTreeSet.drv

@@ -1055,6 +1055,17 @@ public class RB_TREE_SET KEY_GENERIC extends ABSTRACT_SORTED_SET KEY_GENERIC imp
 			RB_TREE_SET.this.remove(curr.key);
 			curr = null;
 		}
+
+		@Override
+		public void jump(final KEY_GENERIC_TYPE fromElement) {
+			if ((next = locateKey(fromElement)) != null) {
+				if (compare(next.key, fromElement) <= 0) {
+					prev = next;
+					next = next.next();
+				}
+				else prev = next.prev();
+			}
+		}
 	}
 
 	@Override

test/it/unimi/dsi/fastutil/ints/IntAVLTreeSetTest.java

@@ -41,4 +41,31 @@ public void testGet() {
 	public void testLegacyMainMethodTests() throws Exception {
 		MainRunner.callMainIfExists(IntAVLTreeSet.class, "test", /*num=*/"20", /*seed=*/"423429");
 	}
+
+	@Test
+	public void testIteratorJump() {
+		final IntRBTreeSet s = new IntRBTreeSet();
+		for (int i = 0; i < 100; i += 3) {
+			s.add(i);
+		}
+
+		final IntBidirectionalIterator it = s.iterator(50);
+
+		assertTrue(it.hasNext());
+		assertEquals(51, it.nextInt());
+
+		it.jump(50);
+		assertTrue(it.hasPrevious());
+		assertEquals(48, it.previousInt());
+
+		it.jump(-1);
+		assertTrue(it.hasNext());
+		assertFalse(it.hasPrevious());
+		assertEquals(0, it.nextInt());
+
+		it.jump(100);
+		assertFalse(it.hasNext());
+		assertTrue(it.hasPrevious());
+		assertEquals(99, it.previousInt());
+	}
 }

test/it/unimi/dsi/fastutil/ints/IntRBTreeSetTest.java

@@ -42,4 +42,31 @@ public void testAddAndGet() {
 	public void testLegacyMainMethodTests() throws Exception {
 		MainRunner.callMainIfExists(IntRBTreeSet.class, "test", /*num=*/"20", /*seed=*/"423429");
 	}
+
+	@Test
+	public void testIteratorJump() {
+		final IntRBTreeSet s = new IntRBTreeSet();
+		for (int i = 0; i < 100; i += 3) {
+			s.add(i);
+		}
+
+		final IntBidirectionalIterator it = s.iterator(50);
+
+		assertTrue(it.hasNext());
+		assertEquals(51, it.nextInt());
+
+		it.jump(50);
+		assertTrue(it.hasPrevious());
+		assertEquals(48, it.previousInt());
+
+		it.jump(-1);
+		assertTrue(it.hasNext());
+		assertFalse(it.hasPrevious());
+		assertEquals(0, it.nextInt());
+
+		it.jump(100);
+		assertFalse(it.hasNext());
+		assertTrue(it.hasPrevious());
+		assertEquals(99, it.previousInt());
+	}
 }