mod: bump version

The usefulness of this feature is questionable, and its correct implementation
is difficult due to the use of generics. The implementation worked incorrectly
in cases where the iterator step is not equal to one and is not a multiple of
the end element. For example, for `range(0, 7, 4)`, the result is `[0]`
instead of `[0, 4]`. After this commit range end value is always included.

To check for multiples, a user-defined type must also implement an overload of
the remainder operator (`%`), even if the exclusivity function is not needed.

Another correct implementation requires subtracting one from the end element
for integers and the minimum fractional part supported by the type for floats.
This cannot be done correctly for generics, as it requires casting the literal
to a specific type, and we cannot cast number to any type.

README.md

@@ -3,7 +3,7 @@
 The `ranges` module provides tools for creating ranges of numbers.
 
 Ranges are represented by the generic `Range` iterator, which has start and
-end points, a step size, and an inclusive/exclusive flag.
+end points and a step size.
 
 ```v
 import ranges

ranges.v

@@ -4,16 +4,17 @@ import strconv
 import math.big
 
 struct Range[T] {
-	limit  T
+	start  T
+	end    T
 	step   T
-	is_neg bool
+	is_neg bool // Is set to true if range end value is lesser than start value.
 mut:
 	cur T
 }
 
 // next returns the new element from range or none if range end is reached.
 pub fn (mut r Range[T]) next() ?T {
-	if (r.is_neg && r.cur < r.limit) || (!r.is_neg && r.cur > r.limit) {
+	if (r.is_neg && r.cur < r.end) || (!r.is_neg && r.cur > r.end) {
 		return none
 	}
 	defer {
@@ -22,11 +23,24 @@ pub fn (mut r Range[T]) next() ?T {
 	return r.cur
 }
 
-@[params]
+// reset resets the internal iterator state to its initial value, after which the iterator can be reused.
-pub struct RangeConfig {
+// Note: `for i in iter {` does not modify the internal iterator state, but direct `next()` call does.
-pub:
+pub fn (mut r Range[T]) reset() {
-	// If true exclude the end value from range.
+	r.cur = r.start
-	exclusive bool
+}
+
+// bounds returns the start, end and step values of range.
+pub fn (r Range[T]) bounds() (T, T, T) {
+	return r.start, r.end, r.step
+}
+
+// with_step returns copy of the range with new step value.
+pub fn (r Range[T]) with_step[T](step T) Range[T] {
+	return Range[T]{
+		...r
+		step: step
+		cur:  r.start
+	}
 }
 
 // range creates new Range iterator with given start, end and step values.
@@ -35,17 +49,13 @@ pub:
 // must be overloaded to perform comparisons and arithmetics: `+`, `-`, `<`, `==`.
 // See https://docs.vlang.io/limited-operator-overloading.html for details.
 //
-// By default, the range includes the end value. This behavior can be changed
+// The range includes the end value.
-// by enabling the 'exclusive' option.
 //
 // Note: Zero step value will cause an infitite loop!
-pub fn range[T](start T, end T, step T, config RangeConfig) Range[T] {
+pub fn range[T](start T, end T, step T) Range[T] {
-	mut limit := end
-	if config.exclusive {
-		limit -= step
-	}
 	return Range[T]{
-		limit:  limit
+		start:  start
+		end:    end
 		step:   step
 		cur:    start
 		is_neg: start > end
@@ -54,7 +64,6 @@ pub fn range[T](start T, end T, step T, config RangeConfig) Range[T] {
 
 @[params]
 pub struct RangeFromStringConfig {
-	RangeConfig
 pub:
 	sep       string = '-'
 	group_sep string = ','
@@ -65,34 +74,34 @@ pub:
 // Use from_string_custom if you want to use custom type with special string
 // convertion rules.
 //
-// Supported string formats are `start-end`, `start[:step]end`. start and end
+// Supported string formats are `start-end[/step]` and `start[:step]:end`. start
-// values are sepatared by 'sep' which is hypen (`-`) by default. Single number
+// and end values are sepatared by 'sep' which is hypen (`-`) by default. Single
-// will be interpreted as range of one element. Several ranges can be specified
+// number will be interpreted as range of one element. Several ranges can be
-// in a line, separated by 'group_sep' (comma by default). 'sep' and 'group_sep'
+// specified in a line, separated by 'group_sep' (comma by default). 'sep' and
-// can be overrided by user.
+// 'group_sep' can be overrided by user.
 //
 // Some example input strings:
 //
 // * `5` - range from 5 to 5 (single element).
 // * `0-10` - range from 0 to 10.
+// * `0-100/5` - range in Cron-style syntax from 0 to 100 with step 5.
 // * `15:-1:0` - range in MathLab-style syntax from 15 to 0 with negative step -1.
 // * `1..8` - range from 1 to 8 with '..' sep.
 // * `0-7,64-71` - multiple ranges: from 0 to 7 and from 64 to 71.
 //
-// Only MathLab-style syntax allows you to specify a step directly in the string.
+// If the step value is not specified, it will be set to one.
-// For all other cases, the step is equal to one.
 //
 // Example: assert ranges.from_string[int]('1-7')! == [ranges.range(1, 7, 1)]
 pub fn from_string[T](s string, config RangeFromStringConfig) ![]Range[T] {
 	mut result := []Range[T]{}
 	for i in s.split(config.group_sep) {
-		range_str := parse_string(i, config.sep)!
+		range_str := split_string(i, config.sep)!
 		// vfmt off
 		result << range[T](
 			convert_string[T](range_str[0])!,
 			convert_string[T](range_str[1])!,
 			convert_string[T](range_str[2])!,
-			config.RangeConfig)
+		)
 		// vfmt on
 	}
 	return result
@@ -129,16 +138,16 @@ pub type StringConvertFn[T] = fn (s string) !T
 pub fn from_string_custom[T](s string, conv StringConvertFn[T], config RangeFromStringConfig) ![]Range[T] {
 	mut result := []Range[T]{}
 	for i in s.split(config.group_sep) {
-		range_str := parse_string(i, config.sep)!
+		range_str := split_string(i, config.sep)!
 		start := conv[T](range_str[0])!
 		end := conv[T](range_str[1])!
 		step := conv[T](range_str[2])!
-		result << range(start, end, step, config.RangeConfig)
+		result << range(start, end, step)
 	}
 	return result
 }
 
-fn parse_string(s string, sep string) ![]string {
+fn split_string(s string, sep string) ![]string {
 	parts := s.split(sep)
 	if parts.any(|x| x.is_blank()) || parts.len !in [1, 2, 3] {
 		return error('`start${sep}end` or `start[:step]:end`' +
@@ -146,12 +155,19 @@ fn parse_string(s string, sep string) ![]string {
 	}
 	if parts.len == 1 {
 		return [parts[0], parts[0], '1']
-	} else if parts.len == 2 {
+	}
+	if parts.len == 2 {
+		if parts[1].contains('/') {
+			end, step := parts[1].split_once('/') or { '', '' }
+			return [parts[0], end, step]
+		}
 		return [parts[0], parts[1], '1']
-	} else if sep == ':' && parts.len == 3 {
+	}
+	if sep == ':' && parts.len == 3 {
 		return [parts[0], parts[2], parts[1]]
 	}
-	return error('invalid range string: ${s}')
+	return error('invalid range string: expected `start[${sep}step]${sep}end` ' +
+		'or `start${sep}end[/step]` format, got `${s}`')
 }
 
 fn convert_string[T](s string) !T {

ranges_test.v

@@ -9,14 +9,6 @@ fn test_range() {
 	assert result == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 }
 
-fn test_range_exclusive() {
-	mut result := []int{}
-	for i in ranges.range[int](0, 10, 1, exclusive: true) {
-		result << i
-	}
-	assert result == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-}
-
 fn test_range_negative() {
 	mut result := []int{}
 	for i in ranges.range[int](10, 0, -1) {
@@ -25,14 +17,6 @@ fn test_range_negative() {
 	assert result == [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
 }
 
-fn test_range_negative_exclusive() {
-	mut result := []int{}
-	for i in ranges.range[int](10, 0, -1, exclusive: true) {
-		result << i
-	}
-	assert result == [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
-}
-
 fn test_range_with_step() {
 	mut result := []int{}
 	for i in ranges.range[int](0, 10, 2) {
@@ -65,14 +49,6 @@ fn test_range_single_item() {
 	assert result == [0]
 }
 
-fn test_range_single_item_exclusive() {
-	mut result := []int{}
-	for i in ranges.range(0, 1, 1, exclusive: true) {
-		result << i
-	}
-	assert result == [0]
-}
-
 fn test_range_bigint() {
 	start := big.zero_int
 	end := big.integer_from_int(5)
@@ -111,6 +87,7 @@ fn test_range_from_string() {
 	assert ranges.from_string[f32]('0.0..99.99', sep: '..')! == [
 		ranges.range[f32](0.0, 99.99, 1),
 	]
+	assert ranges.from_string[int]('0-100/5')! == [ranges.range(0, 100, 5)]
 }
 
 struct Int {
@@ -169,3 +146,44 @@ fn test_range_from_string_custom_type() {
 		sep: '..'
 	)! == [ranges.range[Int](Int{0}, Int{10}, Int{1})]
 }
+
+fn test_range_reset() {
+	mut result := []int{}
+	mut iter := ranges.range(0, 5, 1)
+
+	for {
+		if elem := iter.next() {
+			result << elem
+		} else {
+			break
+		}
+	}
+	assert result == [0, 1, 2, 3, 4, 5]
+
+	iter.reset()
+
+	result = []int{}
+
+	for i in iter {
+		result << i
+	}
+	assert result == [0, 1, 2, 3, 4, 5]
+}
+
+fn test_range_new_with_step() {
+	mut result := []int{}
+	mut iter := ranges.range(0, 5, 1)
+
+	for i in iter.with_step(2) {
+		result << i
+	}
+	assert result == [0, 2, 4]
+}
+
+fn test_range_bounds() {
+	r := ranges.range(0, 10, 2)
+	a, b, c := r.bounds()
+	assert a == 0
+	assert b == 10
+	assert c == 2
+}

v.mod

@@ -1,7 +1,7 @@
 Module {
 	name: 'ranges'
 	description: 'Operating with ranges of numbers'
-	version: '0.1.0'
+	version: '0.5.0'
 	license: 'Unlicense'
 	dependencies: []
 }