Agoric / nat

Ensures that a number is within the natural numbers (0, 1, 2...) or throws a RangeError
Apache License 2.0
5 stars 4 forks source link

example in README fails: not a BigInt #115

Closed warner closed 4 years ago

warner commented 4 years ago

The const a = [2,4,6] example in the README no longer works, because 2/4/6 are not BigInts.

I think the non-acceptance of normal (integer) Numbers is going to surprise some folks (although I appreciate the safety values), so we need to emphasize the new conventions we're trying to encourage. I think it might be enough to change the example to say [2n, 4n, 6n], but we also need to explain what exactly that numeric literal syntax is, how widely supported it is, and add a link to where people can learn more (maybe https://caniuse.com/#feat=bigint , which says that it's not yet supported in Safari).

I'd also suggest changing the first sentence of the README. The old version needed to talk about being "accurately representable", alluding to the fact that infinitely many integers would not survive a roundtrip through the JavaScript Number type, which is not an issue with BigInts. Maybe something like:

 `Nat(value)` returns its argument if it is a non-negative
 BigInt instance. If the argument is negative, an ordinary
 `Number`, or some other non-`BigInt` type, an exception
 is thrown. This makes it easy to use `Nat()` on incoming
 arguments, or as an assertion on generated values.

 BigInts (link) can accurately represent arbitrarily large
 integers without concern of rounding or loss of
 precision. Two Nats added together will always produce
 another Nat.

And then the later example could be like:

const myOldBal = 12n; // BigInt numeric literal
const amount = 3n;
Nat(myOldBal + amount);

const withdrawalAmount = 2n;
const newBal = Nat(myOldBal - withdrawalAmount);
katelynsills commented 4 years ago

Closed by #116