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
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
textstringrequired

a JSON number text.

returnsstring

the 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
astringrequired

the first JSON number text.

bstringrequired

the 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
valuestringrequired

the JSON number text to test.

divisorstringrequired

the 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.