round

npx toopo add number/round

type Round = (value: number, places: number) => number | null

What it does

Rounds a number to a fixed number of decimal places in JavaScript and TypeScript, answering the decimal the caller wrote rather than the double the machine stored. The two spellings a caller reaches for first are wrong, silently: Number((1.005).toFixed(2)) answers 1 and Math.round(1.005 * 100) / 100 answers 1, because the double nearest 1.005 sits below it. Neither ever returns NaN, so nothing announces the loss - a half-cent goes missing and the total is short. Math.round carries a second, unrelated fault: it breaks a tie towards positive infinity, so Math.round(-0.5) is -0 and Math.round(-2.5) is -2, which makes a refund round the opposite way from the charge it reverses. The one spelling in the language that answers correctly is Intl.NumberFormat with a rounding mode, and it hands back a locale-formatted string: converting it back with Number is the third trap, because "1,000.01" is NaN. This contract answers a number, breaks every tie away from zero, and refuses rather than guesses.

The language ships toFixed, which answers a string and rounds the stored double rather than the decimal the caller wrote, and Math.round, which breaks a tie towards positive infinity rather than away from zero. Intl.NumberFormat with roundingMode: "halfExpand" agrees with this contract and answers locale-formatted text.

What it is for, and what it is not

Finite doubles carrying an amount somebody wrote down: prices, totals, tax lines, measurements, percentages, chart axes. It is not a formatter - the answer is a number and never text - not a decimal arithmetic library, not a currency type, not banker's rounding, and not a way to round to tens or hundreds, which is why a negative place count is refused rather than answered.

Try it on your own input

This calls round on whatever you type. What you type into a field is the value, character for character, and the form opens on the-half-cent-to-fixed-loses so there is a call that works to edit. What comes back is what the function answered, under the call it was made from — invisible characters are named there, so two inputs that look alike on screen do not print alike. The settled answer is on the case's own line below, and is deliberately not repeated here. When it answers nothing, describeRoundFailure is called on the same input and its reason is printed underneath: the two exports are one surface, and every input this contract turns down answers round alike.

The JavaScript this runs is number/round's own reference.ts with its types stripped. That is neither the file the registry serves nor the file its digest covers: both are TypeScript, and no browser runs TypeScript. It is also the only part of this page that needs JavaScript at all.

Reference

Everything above answers whether this function does what you need. Everything below is what it is bound to do, in full. It is long on purpose, and none of it is folded away: a case a reader cannot find with their browser's own search is a case this catalogue did not really publish.

Signature

You get round and describeRoundFailure.

type Round = (value: number, places: number) => number | null

type DescribeRoundFailure = (value: number, places: number) => RoundFailureReason | null

A call fails for one of 3 reasons, and the set is frozen with the major version: "value-not-finite", "places-not-whole", "places-negative".

round(v, p) === null if and only if describeRoundFailure(v, p) !== null, for every v and p.

31 settled cases

Every one of them is named, frozen with the major version, and linkable. This is what the contract decides, one input at a time.

the calls this contract settles, every answer computed in integer arithmetic beforehand.

• The decimal a double cannot hold 5
• Which way a tie goes 5
• The sign of zero 3
• A carry that runs 3
• A magnitude no fixed notation holds 4
• The place count at its edges 4
• What is refused 7

#The decimal a double cannot hold

The reason this contract exists. Each value below is one a caller typed and the machine stored as something slightly smaller, so a built-in that rounds what was stored answers a penny short.

#Which way a tie goes

#The sign of zero

A refund that rounds away to nothing keeps the mark saying which way the money went. It is why the contract compares answers with Object.is rather than with ===.

#A carry that runs

#A magnitude no fixed notation holds

Values whose shortest decimal is written in exponent notation, at both ends of the double range. toFixed refuses some of these outright.

#The place count at its edges

#What is refused

Properties

2 of these 4 are checked on 1 000 generated cases per run, re-seeded each time. The other 2 are not applicable to this contract, and each says why below.

• never mutates its arguments — not applicable

  The signature takes two number arguments, primitives immutable by construction in JavaScript. No implementation, correct or broken, can violate this, so a test asserting it would be structurally incapable of failing.

• deterministic — checked

  Violable in practice, and witnessed by an implementation that hoists the carry out of the increment loop - the shape a variable reaches when it is made "reusable" - so that a carry left by an earlier call decides this one and two identical consecutive calls answer differently. Two caches keyed on one of the two arguments were measured as candidates and both were rejected: the probe primes them itself, so the pair of calls agrees and the defect surfaces on the specific properties instead. A third was rejected for a reason worth carrying past this contract - an accumulator that appends rather than replaces drives the digit string past what a double holds, both calls answer Infinity, and outputsAreEqual is Object.is, which judges two infinities equal. On a numeric contract an overflow can absorb a determinism signal. This property is ordered under no ambient input rather than independent of it: every mutant measured to redden it reddens that one too, and the memoise-last mutant reddens that one and not this.

• no ambient input — checked

  Violable in practice: this contract reads two numbers and answers a third, so the call history is the only ambient input it can plausibly acquire. Witnessed by an implementation holding the last call answered and serving it whenever the value matches, which answers the previous place count - the shape a caller rounding one amount to two places and then to none would meet. The property interleaves a probe with an arbitrary history and requires the probe to answer identically either way. Measured: a memo keyed on the value alone stays invisible to it, because the probe primes the memo before the history runs, which is the same limit number/parse@1 records of its own caches.

• no ambient output — not applicable

  Not reachable by a property - a test cannot observe a write that happened before it ran, and a correct memoising cache is indistinguishable from a defect by behaviour alone.

Benchmark profiles

The shapes of input an implementation is timed on. No figures yet: there is no reference machine, and a number produced on a developer laptop would be a number with nothing behind it.

• money-to-the-cent — shortened

  Amounts with a third decimal rounded to two places, the dominant shape in pricing, tax and invoicing code.

• half-cents — at-a-tie

  Values sitting exactly on the half-cent, where the rounding rule is the whole answer and every built-in spelling parts from this contract.

• nothing-to-drop — already-exact

  Values already carrying no more decimals than the caller asked for. Timed apart because an implementation reading the shortest decimal answers these without rounding anything, and a caller normalising a column of amounts hits this path on most rows.

• seventeen-significant-digits — shortened

  Values whose shortest decimal is as long as a double gets, to expose an implementation whose cost grows with the digit string rather than with the places asked for. The last one carries every digit through the increment, since rounding it grows the string.

• refused-calls — refused

  Calls that must answer null. Measured separately because an implementation may take a very different path when it refuses, and a caller validating user input hits that path most.

How this contract measured

2 batteries break this implementation on purpose, 36 times, and require the contract's own suite to notice each time. 33 of those defects were caught.

3 cells survived, and what did is here rather than on a page of its own, because what a suite did not catch is a fact about this function. Each carries the battery's own account of why, in the instrument's words and not this page's.

3 — equivalent

the edit cannot change an answer, so no test could catch it. Measured rather than assumed: each one carries what was compared against what.

What you can check yourself

This definition is frozen. Its canonical text hashes to 7418dfc5de093b77643d5be7852083c24fbf7fb3ab0f89056b6a0983ad97bc12, and the 8 files of its test harness are listed inside it with their own hashes — so a copy of the harness can be checked against this definition before it is trusted, then run against any implementation, without taking our word for any of it.

Written for node, browser, bun.