Document JS number semantics

[kwalrath]

See dart-lang/sdk#42924 for details.

[kwalrath]

@eernstg has given me the following text as a possible starting point. It could replace the text in the int subsection of https://dart.dev/guides/language/language-tour#numbers. We might want to have some additional example code, as well, and to update the 'Bitwise and shift operators' section.

---

Integer values no larger than 64 bits, depending on the platform. Overflows do not cause errors, but will produce results that are imprecise.

On the Dart VM, values can be from -2⁶³ to 2⁶³ - 1, and all operations work on a signed 64-bit two's complement representation. Overflows wrap around. For instance, adding two large positive numbers may yield a negative result.

When Dart is compiled to JavaScript it uses [JavaScript numbers,][js numbers] and the corresponding JavaScript operations, except for bit operations. This allows values in the range -2⁵³ + 1 to 2⁵³ - 1 to be represented precisely. Numbers with larger absolute values are considered to have zero in the lowest bits. A number is an int if it has no fractional part, so 1.0 is an int, but 1.1 is not. Overflow causes a loss of precision, because the lowest bits are considered to be zero. For instance, adding two large positive numbers may yield an even result even though the precise result is odd.

Bit operations on integers (and, or, xor, negation, and shifts) mask the operands to 32-bit, perform 32-bit operations on them, and interpret the result as a 32-bit unsigned integer (for example, -1 << 1 evaluates to 4294967294).

---

[eernstg]

Small correction: '\code{-1 <{}< 1}' should be '-1 << 1'.

[kwalrath]

Small correction: '\code{-1 <{}< 1}' should be '-1 << 1'.

I wondered about that... figured I'd clarify later, but thanks for clarifying now.

[kwalrath]

@vsmenon has written a more extensive treatment of numbers. We plan to turn that into a page soon, which I'll link to from the language tour.

[kwalrath]

I'm starting on this now.