@@ -69,13 +69,21 @@ buffer. For such cases we apply the "With" suffix to standard combinator names:
6969* ...FromThenTo
7070* ...Indices
7171
72−We could use FromThenTo or FromStepN style for stepwise enumeration. We chose
73−FromThenTo style for the following reasons:
72+FromThenTo vs FromStepN:
73+
74+We could use `fromThenTo` or `fromStepN` style APIs for stepwise
75+enumeration. The first one uses absolute numbers whereas the second one
76+uses relative positioning. We prefer FromThenTo style where possible for
77+the following reasons:
7478
7579* It is the style used in base lists, and we are already using it in Enumerable
7680 type class.
77−* Both have their pros and cons. It may be non-intuitive whether To is
78− inclusive in one, we have to compute the correct count in the other one.
81+* Both have their pros and cons. In `fromThenTo`, (1) it may be
82+ non-intuitive whether `To` is inclusive, (2) specifying an empty range
83+ is a bit awkward (e.g. fromThenTo 1 1 0). In `fromStepN`, if we know
84+ the first and the last element then we will have to compute the offset
85+ correctly. Ideally, when we know the elements then former is more
86+ suitable while if we know the count then the latter is more suitable.
7987
8088### Appending
8189