From f4286d0a9d8525bda61be486df964bf2527c8789 Mon Sep 17 00:00:00 2001 From: Kevin Gibbons Date: Tue, 9 Apr 2024 12:17:00 -0700 Subject: [PATCH] update to stage 2.7 (#13) --- README.md | 26 ++++++++------------------ spec.html | 8 ++++---- 2 files changed, 12 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 13e535f..d30d5b2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Math.sumExact +# Math.sumPrecise A proposal to add a method to sum multiple values to JavaScript. @@ -8,7 +8,7 @@ Authors: Kevin Gibbons Champions: Kevin Gibbons -This proposal is at stage 2 of [the TC39 process](https://tc39.es/process-document/): the proposal has been accepted as a draft. +This proposal is at stage 2.7 of [the TC39 process](https://tc39.es/process-document/): the proposal is approved in principle and now requires tests. ## Motivation @@ -18,14 +18,14 @@ Also, summing a list of floating point numbers can be done more precisely than t ## Proposal -Add an iterable-taking `Math.sumExact` method which returns the sum of the values in the iterable using a more precise algorithm than naive summation. +Add an iterable-taking `Math.sumPrecise` method which returns the sum of the values in the iterable using a more precise algorithm than naive summation. ```js let values = [1e20, 0.1, -1e20]; values.reduce((a, b) => a + b, 0); // 0 -Math.sumExact(values); // 0.1 +Math.sumPrecise(values); // 0.1 ```` ## Questions @@ -46,29 +46,19 @@ So this proposal includes only an iterable-taking form. ### Naming -`Math.sum` is the obvious name, but it's not obvious that this going to be a different (slower) algorithm than naive summation. This is tentatively called `Math.sumExact` to call attention to that difference. - -Since it differs from `Math.max` in taking an iterable, we might want a name which calls attention to that as well, such as `sumExactFrom`. See [issue #3](https://github.com/tc39/proposal-math-sum/issues/3) for discussion. +`Math.sum` is the obvious name, but it's not obvious that this going to be a different (slower) algorithm than naive summation. This is called `Math.sumPrecise` to call attention to that difference. ### Should this coerce things to number, or throw if given something which is not a number? -I want to [stop coercing things](https://github.com/tc39/how-we-work/pull/136), but `Math.max` is pretty strong precedent that we do coercion. - -As currently specified it will reject non-number values, breaking with precedent. +It will reject non-number values, breaking with precedent from `Math.max`. ### Is the sum of an empty list 0 or -0? -In some sense -0 is the right answer: that's the additive identity on floats. - -But in another sense the point is stick as close to real-number arithmetic as possible, and in the reals there is no -0. - -Python's `fsum` returns 0 when given an empty list. - -As currently specified this will return -0. This question remains open. See [issue #5](https://github.com/tc39/proposal-math-sum/issues/5) for discussion. +It is -0. This is the floating point additive identity. This choice ensures that `Math.sumPrecise([]) + Math.sumPrecise(foo)` always gives the same answer as `Math.sumPrecise(foo)`. ### Should this work with BigInts? -[No](https://github.com/tc39/proposal-bigint-math/issues/23) - it's important that `Math.sumExact()` returns the Number `-0` (or `0`), which means that `5n + Math.sumExact(bigints)` would throw when `bigints` is empty, which would be bad. +[No](https://github.com/tc39/proposal-bigint-math/issues/23) - it's important that `Math.sumPrecise()` returns the Number `-0` (or `0`), which means that `5n + Math.sumPrecise(bigints)` would throw when `bigints` is empty, which would be bad. We could have seperate methods for summing BigInts. I'd vote for `BigInt.sum` or `BigInt.sumFrom`, depending on the outcome of the naming discussion above. But such a method will not be part of this proposal. diff --git a/spec.html b/spec.html index 2257749..e0c535c 100644 --- a/spec.html +++ b/spec.html @@ -1,9 +1,9 @@ 
-title: Math.sumExact
+title: Math.sumPrecise
 status: proposal
-stage: 2
+stage: 2.7
 copyright: false
 contributors: Kevin Gibbons
@@ -18,8 +18,8 @@

Introduction

This proposal adds a method for summing multiple numbers.

- -

Math.sumExact ( _items_ )

+ +

Math.sumPrecise ( _items_ )

Given an iterable of Numbers, this function sums each value in the iterable and returns their sum. If any value is not a Number it throws a *TypeError* exception.

It performs the following steps when called: