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.

drv/AVLTreeMap.drv

@@ -1185,6 +1185,16 @@ public class AVL_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP  KEY_VAL
 			while(i-- != 0 && hasPrevious()) previousEntry();
 			return n - i - 1;
 		}
+
+		public void jumpKey(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();
+			}
+		}
 	}
 
 
@@ -1211,6 +1221,8 @@ public class AVL_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP  KEY_VAL
 
 		@Override
 		public void add(MAP.Entry KEY_VALUE_GENERIC ok) { throw new UnsupportedOperationException(); }
+
+		public void jump(final MAP.Entry KEY_VALUE_GENERIC fromElement) { jumpKey(fromElement.ENTRY_GET_KEY()); }
 	}
 
 
@@ -1304,6 +1316,9 @@ public class AVL_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP  KEY_VAL
 		public KEY_GENERIC_TYPE NEXT_KEY() { return nextEntry().key; }
 		@Override
 		public KEY_GENERIC_TYPE PREV_KEY() { return previousEntry().key; }
+
+		@Override
+		public void jump(final KEY_GENERIC_TYPE fromElement) { jumpKey(fromElement); }
 	}
 
 	/** A keyset implementation using a more direct implementation for iterators. */

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
@@ -1360,6 +1371,25 @@ public class AVL_TREE_SET KEY_GENERIC extends ABSTRACT_SORTED_SET KEY_GENERIC im
 				next = next.next();
 				if (! top && next != null && AVL_TREE_SET.this.compare(next.key, to) >= 0) next = null;
 			}
+
+			@Override
+			public void jump(final KEY_GENERIC_TYPE fromElement) {
+				next = firstEntry();
+
+				if (next != null) {
+					if (! bottom && compare(fromElement, next.key) < 0) prev = null;
+					else if (! top && compare(fromElement, (prev = lastEntry()).key) >= 0) next = null;
+					else {
+						next = locateKey(fromElement);
+
+						if (compare(next.key, fromElement) <= 0) {
+							prev = next;
+							next = next.next();
+						}
+						else prev = next.prev();
+					}
+				}
+			}
 		}
 	}
 

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/RBTreeMap.drv

@@ -1116,6 +1116,16 @@ public class RB_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP KEY_VALUE
 			while(i-- != 0 && hasPrevious()) previousEntry();
 			return n - i - 1;
 		}
+
+		public void jumpKey(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();
+			}
+		}
 	}
 
 
@@ -1135,6 +1145,9 @@ public class RB_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP KEY_VALUE
 		public MAP.Entry KEY_VALUE_GENERIC next() { return nextEntry(); }
 		@Override
 		public MAP.Entry KEY_VALUE_GENERIC previous() { return previousEntry(); }
+
+		@Override
+		public void jump(final MAP.Entry KEY_VALUE_GENERIC fromElement) { jumpKey(fromElement.ENTRY_GET_KEY()); }
 	}
 
 
@@ -1231,6 +1244,9 @@ public class RB_TREE_MAP KEY_VALUE_GENERIC extends ABSTRACT_SORTED_MAP KEY_VALUE
 
 		@Override
 		public KEY_GENERIC_TYPE PREV_KEY() { return previousEntry().key; }
+
+		@Override
+		public void jump(final KEY_GENERIC_TYPE fromElement) { jumpKey(fromElement); }
 	};
 
 

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
@@ -1299,6 +1310,25 @@ public class RB_TREE_SET KEY_GENERIC extends ABSTRACT_SORTED_SET KEY_GENERIC imp
 				next = next.next();
 				if (! top && next != null && RB_TREE_SET.this.compare(next.key, to) >= 0) next = null;
 			}
+
+			@Override
+			public void jump(final KEY_GENERIC_TYPE fromElement) {
+				next = firstEntry();
+
+				if (next != null) {
+					if (! bottom && compare(fromElement, next.key) < 0) prev = null;
+					else if (! top && compare(fromElement, (prev = lastEntry()).key) >= 0) next = null;
+					else {
+						next = locateKey(fromElement);
+
+						if (compare(next.key, fromElement) <= 0) {
+							prev = next;
+							next = next.next();
+						}
+						else prev = next.prev();
+					}
+				}
+			}
 		}
 	}
 

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

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2017-2022 Sebastiano Vigna
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package it.unimi.dsi.fastutil.ints;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+
+import it.unimi.dsi.fastutil.objects.ObjectBidirectionalIterator;
+
+public class Int2IntAVLTreeMapTest {
+
+	@Test
+	public void testIteratorJump() {
+		final Int2IntSortedMap m = new Int2IntAVLTreeMap();
+		for (int i = 0; i < 100; i += 3) {
+			m.put(i, i);
+		}
+
+		final IntBidirectionalIterator mapIt = m.keySet().iterator(50);
+
+		assertTrue(mapIt.hasNext());
+		assertEquals(51, mapIt.nextInt());
+
+		mapIt.jump(50);
+		assertTrue(mapIt.hasPrevious());
+		assertEquals(48, mapIt.previousInt());
+
+		mapIt.jump(-1);
+		assertTrue(mapIt.hasNext());
+		assertFalse(mapIt.hasPrevious());
+		assertEquals(0, mapIt.nextInt());
+
+		mapIt.jump(100);
+		assertFalse(mapIt.hasNext());
+		assertTrue(mapIt.hasPrevious());
+		assertEquals(99, mapIt.previousInt());
+
+		final ObjectBidirectionalIterator<Int2IntMap.Entry> mapEntryIt = m.int2IntEntrySet().iterator(new AbstractInt2IntMap.BasicEntry(50, 0));
+
+		assertTrue(mapEntryIt.hasNext());
+		assertEquals(51, mapEntryIt.next().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(50, 0));
+		assertTrue(mapEntryIt.hasPrevious());
+		assertEquals(48, mapEntryIt.previous().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(-1, 0));
+		assertTrue(mapEntryIt.hasNext());
+		assertFalse(mapEntryIt.hasPrevious());
+		assertEquals(0, mapEntryIt.next().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(100, 0));
+		assertFalse(mapEntryIt.hasNext());
+		assertTrue(mapEntryIt.hasPrevious());
+		assertEquals(99, mapEntryIt.previous().getIntKey());
+	}
+}

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

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2017-2022 Sebastiano Vigna
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package it.unimi.dsi.fastutil.ints;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+
+import it.unimi.dsi.fastutil.objects.ObjectBidirectionalIterator;
+
+public class Int2IntRBTreeMapTest {
+
+	@Test
+	public void testIteratorJump() {
+		final Int2IntSortedMap m = new Int2IntRBTreeMap();
+		for (int i = 0; i < 100; i += 3) {
+			m.put(i, i);
+		}
+
+		final IntBidirectionalIterator mapKeyIt = m.keySet().iterator(50);
+
+		assertTrue(mapKeyIt.hasNext());
+		assertEquals(51, mapKeyIt.nextInt());
+
+		mapKeyIt.jump(50);
+		assertTrue(mapKeyIt.hasPrevious());
+		assertEquals(48, mapKeyIt.previousInt());
+
+		mapKeyIt.jump(-1);
+		assertTrue(mapKeyIt.hasNext());
+		assertFalse(mapKeyIt.hasPrevious());
+		assertEquals(0, mapKeyIt.nextInt());
+
+		mapKeyIt.jump(100);
+		assertFalse(mapKeyIt.hasNext());
+		assertTrue(mapKeyIt.hasPrevious());
+		assertEquals(99, mapKeyIt.previousInt());
+
+		final ObjectBidirectionalIterator<Int2IntMap.Entry> mapEntryIt = m.int2IntEntrySet().iterator(new AbstractInt2IntMap.BasicEntry(50, 0));
+
+		assertTrue(mapEntryIt.hasNext());
+		assertEquals(51, mapEntryIt.next().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(50, 0));
+		assertTrue(mapEntryIt.hasPrevious());
+		assertEquals(48, mapEntryIt.previous().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(-1, 0));
+		assertTrue(mapEntryIt.hasNext());
+		assertFalse(mapEntryIt.hasPrevious());
+		assertEquals(0, mapEntryIt.next().getIntKey());
+
+		mapEntryIt.jump(new AbstractInt2IntMap.BasicEntry(100, 0));
+		assertFalse(mapEntryIt.hasNext());
+		assertTrue(mapEntryIt.hasPrevious());
+		assertEquals(99, mapEntryIt.previous().getIntKey());
+	}
+}

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

@@ -41,4 +41,50 @@ public void testGet() {
 	public void testLegacyMainMethodTests() throws Exception {
 		MainRunner.callMainIfExists(IntAVLTreeSet.class, "test", /*num=*/"20", /*seed=*/"423429");
 	}
+
+	@Test
+	public void testIteratorJump() {
+		final IntSortedSet s = new IntAVLTreeSet();
+		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());
+
+		final IntBidirectionalIterator subIt = s.subSet(10, 90).iterator(50);
+
+		assertTrue(subIt.hasNext());
+		assertEquals(51, subIt.nextInt());
+
+		subIt.jump(50);
+		assertTrue(subIt.hasPrevious());
+		assertEquals(48, subIt.previousInt());
+
+		subIt.jump(-1);
+		assertTrue(subIt.hasNext());
+		assertFalse(subIt.hasPrevious());
+		assertEquals(12, subIt.nextInt());
+
+		subIt.jump(90);
+		assertFalse(subIt.hasNext());
+		assertTrue(subIt.hasPrevious());
+		assertEquals(87, subIt.previousInt());
+	}
 }