julia-script / julia-script/silk

stdlib: render floats as text with a shortest round-trip guarantee

Open
#137 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

new feature P2 spec-change stdlib
Dominant language
TypeScript
Stars
48
Forks
0
Avg merge
4h 49m
Merged PRs (30d)
213

Description

Context

The follow-up #40 split off. PR #127 shipped integer→text for every fixed-width type at radix 10, plus the formatting API shape — the half self-hosting needs, since diagnostics and artifact output are integer-and-text.

Float formatting was deliberately deferred, because it carries a decision the integer half does not.

The decision this needs

#40's requirement 9 asks for a shortest round-trip guarantee: f64 → text → f64 returns the identical value, and the text is the shortest decimal that does so. That is a real algorithm — Ryu, Grisu3, or Schubfach — not a formatting detail. It is comparable in weight to the Transcendental plan work, and like that work it must produce identical digits on all three engines, which rules out leaning on any host's float printer.

Answer before implementing:

  1. Which algorithm, and adopted from a citable source or derived here?
  2. Shortest round-trip, or a fixed significant-digit count? Fixed precision is far smaller and still deterministic across engines, but f64 → text → f64 will not round-trip exactly — a sharp edge for a compiler's own artifact output, which is the motivating consumer.
  3. The invalid and special cases: infinity, negative zero, and NaN. Note f64.INFINITY exists (PR #106) but f64.NAN does not — it is tracked in #109 and is not blocking, because a NaN is obtainable at runtime (zero / zero, verified). Decide the rendered text for each.

Requirements

  1. f32 and f64 render to text with the guarantee chosen above.
  2. Identical digits on the evaluator, LLVM and Wasm for every input — no host float printer anywhere in the path.
  3. Infinity, negative zero and NaN render as decided in the question above.
  4. If shortest round-trip is chosen: parse(render(x)) == x for every finite x, and the text is the shortest decimal with that property.
  5. Amend the relevant spec through the openspec process.

Acceptance criteria

  • The three questions above are answered and recorded here before implementation.
  • A three-engine test compares rendered digits for a pinned table including subnormals, the largest finite, negative zero, and powers of two.
  • If shortest round-trip: a round-trip property test over a wide input sweep, in the shape of PR #124's squareRoot fuzz (1,099,998 inputs, zero mismatches).
  • Special cases render as decided.

Dependencies

  • PR #127 (#40's integer half) landed and supplies the formatting API shape this extends.
  • Not blocked on #109. f64.NAN would be convenient for tests but a runtime NaN works.

Filed by orchestrator run run-r7x1 from the #40 split.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read PR #127 for the existing formatting API shape and PR #124 for the wide-input fuzz-test pattern. Resolve and record the algorithm, precision, and special-case decisions through the openspec process, then verify identical digits across the evaluator, LLVM, and Wasm with the pinned cases and round-trip property test described here.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, wasm
Domain
compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.