Consider some suggestions for modifications and additions on 'Numbers in Dart' page

[dtonhofer]

Page URL

https://dart.dev/guides/language/numbers/

Page source

https://github.com/dart-lang/site-www/tree/main/src/content/guides/language/numbers.md

Describe the problem

At https://dart.dev/guides/language/numbers, "Numbers in Dart", we read:

Dart has always allowed platform-specific representations and semantics for numbers, for reasons of performance, code size, and platform interoperability.

I'm not sure this is really right. It seems rather that

Dart proposes a very restricted set of numeric types (or "number types"). These can be reasonably mapped to representations proper to the actual platform that a Dart program or the Dart VM runs on, thus ensuring performance and portability at the cost of flexibility.

We continue:

Similarly, in C/C++ the commonly used int type for integer values is platform-specific to best map to the native machine architecture (16-, 32-, or 64-bit). In Java, the float and double types for fractional values were originally designed to strictly follow IEEE 754 on all platforms, but this constraint was loosened almost immediately for efficiency reasons (strictfp is required for exact coherence).

Suggesting the following, but it may be too complicated. (also, is "fractional values" really a correct term?):

In C/C++, the machine representation underlying short, int, long and long long (all either signed and unsigned) is left for the compiler designer to choose. This makes it possible to map numeric types of the language to the underlying architecture in an efficient way (for example, one would choose a 32-bit two-complement for signed int on Intel 32-bit CPUs).

In Java, Sun Microsystems demanded that float and double floating-point implementations use strict IEEE 754 semantics in a conformant Java VM. This was abandoned in the 2nd edition of the Java language specification (2000) because, although not all hardware implementations were fully IEEE 754 conformant [IIRC in particular regarding trap facilites], and not using the hardware for floating-point calculations was excessively onerous. The option of falling back to a strict IEEE 754 semantics implemented in software if this is deemed necessary has been left open (with the strictfp flag). This is similar to Dart int (platform-dependent integer) and the use of the Dart fixnum package (strict behaviour for 32-bit and 64-bit integers on all platforms)

Additional numeric types

At the very end of the page the BigInt class and fixnum package are mentioned:

For other cases where precision matters, consider other numeric types. The BigInt type provides arbitrary-precision integers on both native and web. The fixnum package provides strict 64-bit signed numbers, even on the web. Use these types with care, though: they often result in significantly bigger and slower code.

However, it might be of use to refer the reader to other libraries and packages providing numeric types of interest. I have found the following:

BigDecimal

There is no BigDecimal in Dart proper, but there is an add-on package for it:

"A bugless implementation of BigDecimal in Dart based on Java's BigDecimal."

• https://pub.dev/packages/big_decimal
• https://pub.dev/documentation/big_decimal/latest/big_decimal/BigDecimal-class.html

Rational

There is no Rational in Dart proper, but there is an add-on package for it:

"This project enable to make computations on rational numbers."

• https://pub.dev/packages/rational
• https://pub.dev/documentation/rational/latest/rational/Rational-class.html

Complex

There is no Complex in Dart proper, but there is an add-on package for it:

"A representation of a complex number, i.e. a number which has both a real and an imaginary part."

Translated from The Apache Commons Mathematics Library into Dart.

• https://pub.dev/packages/complex
• https://pub.dev/documentation/complex/latest/complex/Complex-class.html

Quaternion

An implementation can be found in three_dart, the "Dart 3D library. an easy to use, lightweight, cross-platform, general purpose 3D library."

• https://pub.dev/documentation/three_dart/latest/three3d_math_quaternion/Quaternion-class.html

There is another implementation of quaternions in Flutter:

• https://api.flutter.dev/flutter/vector_math/Quaternion-class.html

SIMD numeric types

Additionally, there is:

Typed Data

Dart provides the declaration for a library that is meant to provide efficient implementations for certain common datastructures of the form "List" (called "SIMD numeric types")

• import 'dart:typed_data';
• https://api.dart.dev/stable/dart-typed_data/dart-typed_data-library.html

Expected fix

No response

Additional context

No response

I would like to fix this problem.

• I will try and fix this problem on dart.dev.

[atsansone]

@munificent , @lrhn or @leafpetersen : Do these changes appear consistent with what we should express in the docs? If so, I'll make these changes.

[leafpetersen]

What changes are being proposed? This seems more like some kind of general commentary, I'm not sure what is actionable here.

[lrhn]

At https://dart.dev/guides/language/numbers, "Numbers in Dart", we read:

Dart has always allowed platform-specific representations and semantics for numbers, for reasons of performance, code size, and platform interoperability.

I'm not sure this is really right. It seems rather that

Dart proposes a very restricted set of numeric types (or "number types"). These can be reasonably mapped to representations proper to the actual platform that a Dart program or the Dart VM runs on, thus ensuring performance and portability at the cost of flexibility.

The change tries to be more precise, but it's probably too cumbersome and detailed to be a good lead-in sentence.
(We can argue content too, but I think this fails on form alone. The goal here isn't to be absolutely precise.)

We continue:

Similarly, in C/C++ the commonly used int type for integer values is platform-specific to best map to the native machine architecture (16-, 32-, or 64-bit). In Java, the float and double types for fractional values were originally designed to strictly follow IEEE 754 on all platforms, but this constraint was loosened almost immediately for efficiency reasons (strictfp is required for exact coherence).

Suggesting the following, but it may be too complicated. (also, is "fractional values" really a correct term?):

In C/C++, the machine representation underlying short, int, long and long long (all either signed and unsigned) is left for the compiler designer to choose. This makes it possible to map numeric types of the language to the underlying architecture in an efficient way (for example, one would choose a 32-bit two-complement for signed int on Intel 32-bit CPUs).

In Java, Sun Microsystems demanded that float and double floating-point implementations use strict IEEE 754 semantics in a conformant Java VM. This was abandoned in the 2nd edition of the Java language specification (2000) because, although not all hardware implementations were fully IEEE 754 conformant [IIRC in particular regarding trap facilites], and not using the hardware for floating-point calculations was excessively onerous. The option of falling back to a strict IEEE 754 semantics implemented in software if this is deemed necessary has been left open (with the strictfp flag). This is similar to Dart int (platform-dependent integer) and the use of the Dart fixnum package (strict behaviour for 32-bit and 64-bit integers on all platforms)

I honestly don't get the point of the original either.

Dart has two built-in number types, int and double. The concrete implementations of these may depend on the target platform, although currently there are only two different behaviors among the supported platforms. The concrete differences are chosen both to ensure as much consistency as possible, and to still allow efficient operations.

I'd stop at that.
Mentioning Java and C++ is just confusing. Especially Java, because C++ precisely has the int-is-platform-dependent rule, which is sometimes too vague, but is in the same ballpark. Java only has platform specific behavior for doubles, but the text so far hasn't talked about operations, just values.

Additional numeric types

At the very end of the page the BigInt class and fixnum package are mentioned:

For other cases where precision matters, consider other numeric types. The BigInt type provides arbitrary-precision integers on both native and web. The fixnum package provides strict 64-bit signed numbers, even on the web. Use these types with care, though: they often result in significantly bigger and slower code.

However, it might be of use to refer the reader to other libraries and packages providing numeric types of interest. I have found the following:

I'd be vary about pointing to specific third-party packages as if they are specially endorsed by the Dart team.

SIMD numeric types

Additionally, there is:

Typed Data

Dart provides the declaration for a library that is meant to provide efficient implementations for certain common datastructures of the form "List" (called "SIMD numeric types")

• import 'dart:typed_data';
• https://api.dart.dev/stable/dart-typed_data/dart-typed_data-library.html

These are Dart-team provided. Not sure they fit in here, depending on what the goal of the page is.
(Shouldn't try to solve too many problems on the same page.)