From: Jean Privat <jean@pryen.org>
Date: Fri, 15 May 2015 01:14:05 +0000 (-0400)
Subject: standard/collection: add `Iterator::next_by` as a safe multiple `next`
X-Git-Tag: v0.7.5~40^2~3
X-Git-Url: http://nitlanguage.org

standard/collection: add `Iterator::next_by` as a safe multiple `next`

Signed-off-by: Jean Privat <jean@pryen.org>
---

diff --git a/lib/standard/collection/abstract_collection.nit b/lib/standard/collection/abstract_collection.nit
index 2f7e454..c33416f 100644
--- a/lib/standard/collection/abstract_collection.nit
+++ b/lib/standard/collection/abstract_collection.nit
@@ -191,6 +191,37 @@ interface Iterator[E]
 	# Require `is_ok`.
 	fun next is abstract
 
+	# Jump to the next item `step` times.
+	#
+	# ~~~
+	# var i = [11, 22, 33, 44].iterator
+	# assert i.item == 11
+	# i.next_by 2
+	# assert i.item == 33
+	# ~~~
+	#
+	# `next_by` should be used instead of looping on `next` because is takes care
+	# of stopping if the end of iteration is reached prematurely whereas a loop of
+	# `next` will abort because of the precondition on `is_ok`.
+	#
+	# ~~~
+	# i.next_by 100
+	# assert not i.is_ok
+	# ~~~
+	#
+	# If `step` is negative, this method aborts.
+	# But specific subclasses can change this and do something more meaningful instead.
+	#
+	# Require `is_ok`
+	fun next_by(step: Int)
+	do
+		assert step >= 0
+		while is_ok and step > 0 do
+			next
+			step -= 1
+		end
+	end
+
 	# Is there a current item ?
 	fun is_ok: Bool is abstract