nish/json-number
JSON number text compared and divided exactly, the arithmetic JSON Schema's minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, const and enum ask for.
import {
JSON_NUMBER_ERR_DIVISOR,
JSON_NUMBER_ERR_EXPONENT,
JSON_NUMBER_ERR_GAP,
JSON_NUMBER_ERR_SYNTAX,
JSON_NUMBER_MAX_EXPONENT,
JSON_NUMBER_MAX_STEPS,
jsonNumberCanonical,
jsonNumberCompare,
jsonNumberMultipleOf,
} from "nish/json-number";
import { jsonNumberCompare, jsonNumberMultipleOf } from "nish/json-number"
jsonNumberCompare("1.0", "1e0") // 0: the same value
jsonNumberCompare("0.1", "0.10000000000000001") // -1, which f64 calls equal
jsonNumberMultipleOf("0.3", "0.1") // 1, which f64 calls 0
jsonNumberMultipleOf("1e1000000000", "2") // JSON_NUMBER_ERR_GAP
jsonNumberCanonical
The one text every spelling of a number's value has: 0 for zero (-0 too), else an optional -, the significant digits, e and the exponent of the last digit, so 1.50, 15e-1 and 0.015e2 are all 15e-1, and 100 is 1e2.
jsonNumberCompare
-1, 0 or 1 as the value of the JSON number text a is below, equal to or above that of b, exactly: 1, 1.0, 1e0 and 10e-1 are equal, and -0 equals 0.
jsonNumberMultipleOf
1 when the value of the JSON number text value is a whole multiple of that of divisor, exactly, else 0: 0.3 is a multiple of 0.1 and 0.0075 of 0.0001, 4.5 is not one of 2, and zero is one of anything.
Never through `f64`
A number is read from its text as a sign, its
significant digits (leading and trailing zeros dropped) and the decimal
exponent of its last digit, and every answer is computed on those, so
9007199254740993 is not 9007199254740992, 0.1 * 3 is not involved in
whether 0.3 is a multiple of 0.1, and 1e400 is a number like any
other rather than an infinity. The text is a JSON number, RFC 8259's
grammar exactly (what JsonDocument.numberText answers); anything else is
JSON_NUMBER_ERR_SYNTAX.
What a call costs
jsonNumberCompare reads each text once and allocates
two records of a few fields, nothing in proportion to the text: time is
linear in the texts' lengths. jsonNumberCanonical allocates the string it
answers, at most the text's length plus an exponent.
jsonNumberMultipleOf divides the value's digits, followed by as many zeros
as its exponent is above the divisor's (the gap), by the divisor's digits:
one step per digit of that dividend when the divisor has at most 18
significant digits, and one per digit of the dividend per digit of the
divisor otherwise, which then also allocates the remainder, one byte per
divisor digit. A step of that long division is a shift, up to ten comparisons
and up to nine subtractions of a byte each, so about twenty byte operations.
The bounds are stated
An exponent is at most JSON_NUMBER_MAX_EXPONENT
in size, which keeps every exponent sum far inside i64, and past
it a text is JSON_NUMBER_ERR_EXPONENT, unless every digit is zero:
0e9999999999999999 is zero. A division that would take more
than JSON_NUMBER_MAX_STEPS steps is JSON_NUMBER_ERR_GAP before it
starts: 1e1000000000 is 12 bytes, and whether it is a multiple of 3
would otherwise be a billion steps, the cheap input and expensive answer an
attacker sends to a validator. A JSON Schema validator reports a refused
comparison as the instance failing, and says why.
Every answer is an i32, so a program reads them the same under
--number-mode f64; a refusal is a JSON_NUMBER_ERR_* code, each below
-1, so that it is never one of jsonNumberCompare's answers.
Functions
jsonNumberCanonical
The one text every spelling of a number's value has: 0 for zero (-0
too), else an optional -, the significant digits, e and the exponent of
the last digit, so 1.50, 15e-1 and 0.015e2 are all 15e-1, and 100
is 1e2. Two texts have the same canonical text exactly when
jsonNumberCompare calls them equal, which makes it a key for a set or a
hash. "" for a text that is not a number or whose exponent is past
JSON_NUMBER_MAX_EXPONENT. Allocates the answer.
const jsonNumberCanonical: (text: string) => string
textstringrequireda JSON number text.
returnsstringthe canonical text of its value, or "" when text is refused.
jsonNumberCompare
-1, 0 or 1 as the value of the JSON number text a is below, equal
to or above that of b, exactly: 1, 1.0, 1e0 and 10e-1 are equal,
and -0 equals 0. A text that is not a number, or whose exponent is past
JSON_NUMBER_MAX_EXPONENT, is that JSON_NUMBER_ERR_* code, a's first.
Linear in the two lengths; allocates two small records.
const jsonNumberCompare: (a: string, b: string) => i32
astringrequiredthe first JSON number text.
bstringrequiredthe second JSON number text.
returnsi32
-1, 0 or 1 as a is below, equal to or above b, or a
negative JSON_NUMBER_ERR_* code.
jsonNumberMultipleOf
1 when the value of the JSON number text value is a whole multiple of
that of divisor, exactly, else 0: 0.3 is a multiple of 0.1 and
0.0075 of 0.0001, 4.5 is not one of 2, and zero is one of anything.
Signs are ignored. JSON Schema's multipleOf is 1 here.
Refused, each with its JSON_NUMBER_ERR_* code: a text that is not a
number or whose exponent is past JSON_NUMBER_MAX_EXPONENT (value's
first), a divisor of zero, and a division of more than
JSON_NUMBER_MAX_STEPS steps, which is JSON_NUMBER_ERR_GAP: the value's
digits plus the gap between the two last digits' exponents, times the
divisor's digits when it has more than 18.
const jsonNumberMultipleOf: (
value: string,
divisor: string,
) => i32
valuestringrequiredthe JSON number text to test.
divisorstringrequiredthe JSON number text it should be a multiple of.
returnsi32
1 for a multiple, 0 for not one, or a negative
JSON_NUMBER_ERR_* code when the question is refused.
Limits
1,000,000,000,000,000
JSON_NUMBER_MAX_EXPONENT: i64
The largest exponent, in size, a text may write: 10^15, so a sum of two stays far inside i64.
1,048,576
JSON_NUMBER_MAX_STEPS: i64
The most digit steps one jsonNumberMultipleOf may take, 2^20 (the module header says what a step costs).
Constants
-12
JSON_NUMBER_ERR_DIVISOR: i32
jsonNumberMultipleOf was asked about a divisor of zero.
-11
JSON_NUMBER_ERR_EXPONENT: i32
The text's exponent is larger in size than JSON_NUMBER_MAX_EXPONENT.
-13
JSON_NUMBER_ERR_GAP: i32
jsonNumberMultipleOf would take more than JSON_NUMBER_MAX_STEPS steps.
-10
JSON_NUMBER_ERR_SYNTAX: i32
The text is not a JSON number.

