@@ -69,13 +69,21 @@ buffer. For such cases we apply the "With" suffix to standard combinator names:
69* ...FromThenTo
69* ...FromThenTo
70* ...Indices
70* ...Indices
72+FromThenTo vs FromStepN:
72−We could use FromThenTo or FromStepN style for stepwise enumeration. We chose
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
73−FromThenTo style for the following reasons:
77+the following reasons:
75* It is the style used in base lists, and we are already using it in Enumerable
79* It is the style used in base lists, and we are already using it in Enumerable
76 type class.
80 type class.
77−* Both have their pros and cons. It may be non-intuitive whether To is
81+* Both have their pros and cons. In `fromThenTo`, (1) it may be
78− inclusive in one, we have to compute the correct count in the other one.
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.
80### Appending
88### Appending