From f49b01506507e1a12a21d7698f47ced043d3a335 Mon Sep 17 00:00:00 2001 From: Chirodip Lodh Choudhury Date: Tue, 7 Jul 2026 11:06:08 +0530 Subject: [PATCH] Fix : Corrected unit.md files --- docs/datatypes/units.md | 26 ++++++++++++++++++++++++++ docs/reference/classes/unit.md | 13 +++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/datatypes/units.md b/docs/datatypes/units.md index 31c928440d..d1028fa696 100644 --- a/docs/datatypes/units.md +++ b/docs/datatypes/units.md @@ -242,11 +242,37 @@ Get a string representation of the unit. The function will determine the best fitting prefix for the unit. See the [Format](../reference/functions/format.md) page for available options. +When math.js determines a best prefix automatically, it uses the same heuristic as +`unit.toBest()`: + +- The heuristic is applied only for single units with an integer power, and only + when `fixPrefix` is `false`. +- First, math.js has a bias toward the current prefix: if the current prefix is in + a "good enough" range, it is kept. +- Otherwise, it evaluates candidate prefixes and chooses the one minimizing + `abs(log10(abs(value) / (prefixValue * unitValue)^power) - offset)`. +- In a tie, the shorter prefix name is chosen. +- By default, only prefixes marked as scientific are considered during this search + (for example, `m`, `k`, `M`, but not `c`, `d`, `da`, `h`). + +The default `offset` is `1.2`. This means the heuristic prefers values around +$10^{1.2} \approx 15.8$ rather than values around `1`. In practice this leads to +results like preferring `0.6 m` over `600 mm`, and can also prefer tenths over +hundreds depending on nearby prefix choices. + ### unit.toBest(unitList, options) Converts a unit to the most appropriate display unit by choosing from the list of passed units (unitList) or doing it automatically if no list is passed. It also accepts options. At the moment, the only available one is offset which is used for a better prefix calculation +Without a `unitList`, `unit.toBest()` uses the same prefix heuristic described above +for `unit.format([options])`, including: + +- a bias toward keeping the current prefix; +- the default `offset: 1.2`, which favors values around $10^{1.2}$; +- and candidate scoring in log space, which can prefer values in tenths over values + in the hundreds. + ### unit.fromJSON(json) Revive a unit from a JSON object. Accepts An object `{mathjs: 'Unit', value: number, unit: string, fixPrefix: boolean}`, diff --git a/docs/reference/classes/unit.md b/docs/reference/classes/unit.md index c3f88fed6a..3c74e86134 100644 --- a/docs/reference/classes/unit.md +++ b/docs/reference/classes/unit.md @@ -208,6 +208,19 @@ Get a string representation of the Unit, with optional formatting options. ### unit.toBest(unitList, options) ⇒ Unit Converts a unit to the most appropriate display unit with optional unitList and options. +When `unitList` is omitted, this method picks a prefix using a heuristic: + +- It only applies to single units with integer powers and when `fixPrefix` is `false`. +- It first biases toward the current prefix. If the current prefix is in a + "good enough" range, it is kept. +- Otherwise, it evaluates candidate prefixes by minimizing + `abs(log10(abs(value) / (prefixValue * unitValue)^power) - offset)`. +- The default `offset` is `1.2`, so values around $10^{1.2} \approx 15.8$ are + preferred over values around `1`. +- This can produce outcomes like preferring `0.6 m` over `600 mm`, and in general + can favor values in tenths over values in the hundreds. +- In a tie, the shorter prefix name is chosen. + **Kind**: instance method of Unit **Returns**: Unit