Giters

tc39 / proposal-iterator.range

A proposal for ECMAScript to add a built-in Iterator.range()

Home Page:https://tc39.es/proposal-iterator.range/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

parameter names

Andrew-Cottrell opened this issue · comments

commented

The parameter names mentioned in the spec might be unimportant, but potentially they would eventually be copied to MDN, online examples, and other training materials.

The spec currently names the parameters from and to.

  • The name from is also used for static methods that build an instance of one type from an instance of another type; for example Array.from(iterable) and String.fromCharCode(number).
  • The name to may confuse as the range does not yield the to value.

So, I want to think about alternative names that might be a better fit for ECMAScript.

  • The name start seems a better conceptual match with String#padStart and String#startsWith. It is the point at which something starts, it is not converting from something.
  • The name done might be obvious for those familiar with ECMAScript iterators, and indicates the threshold at which the range will be done and therefore not yield any more values.

This leads to my opening suggestion

  • Number.range(start, done, option)
  • BigInt.range(start, done, option)
commented

The name to may confuse as the range does not yield the to value.

Hmm, it's (from, to] (exclusive from, inclusive to)

IMO start and done doesn't become a pair, start / end might be better name.

commented

Hmm, it's (from, to] (exclusive from, inclusive to)

That is contrary to what I conclude while reading the spec.

On the first iteration at 5.1.22.a the currentCount should be zero, so lastValue === from, and lastValue is not modified before being yielded at 5.1.22.g.

In an increasing range, when lastValue becomes >= to, the range is done at 5.1.22.c.
In a decreasing range, when lastValue becomes <= to, the range is done at 5.1.22.d.

Is the spec out of date with current thinking, or am I reading it wrong?

commented

Ah! I'm very sorry, my mind doesn't clear today... Yes, you're right, the design is [from, to) currently. And I'm going to refine the spec to make it easier to read (with no spec change).

On the other hand, https://tc39.es/proposal-Number.range/playground.html you can try it on the playground. The playground is one-to-one implemented the spec so it will be easier to track spec variables to verify your thought.

commented

IMO start and done doesn't become a pair, start / end might be better name.

The pair start/end looks good to me. My implementation previously used begin/end, which is basically the same thing; but has just now changed to use start/end.

Notably, the specification of Array.prototype.copyWithin, Array.prototype.fill, and Array.prototype.slice each use start/end with inclusive start and exclusive end.

Any future documentation will need to be clear the iterator is done once the end value is hit, or passed, and will not yield the end value; similar to the MDN document for those Array.prototype methods.