IEEE-754 binary64 text-conversion prerequisite for Phase 4 of #863

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 `main`, the release pipeline automatically replaces `[current]` with the next
 version number before tagging the release.
 
+## [current]
+
+### Added
+
+- **Lossless binary64 text-conversion prerequisite** (#863 Phase 3.5). Implemented `string.from_double(value: float) -> string` in `std.string`. This function converts every finite IEEE-754 binary64 value to a lossless decimal representation (using `"%.17g"` format), ensuring exact bit equality after parsing back with `string.to_double()`. It handles positive/negative normal and subnormal values, signed zeros, NaN, and positive/negative infinity cleanly and locale-independently.
+
+### Fixed
+
+- **`string.to_float` / `string.to_double` rejected subnormal values.** `strtof` and `strtod` may set `ERANGE` for a representable underflow result, but the wrappers treated every `ERANGE` as failure. They now reject range overflow while accepting correctly rounded subnormal and zero results.
+
 ## [0.491.0]
 
 ### Fixed

docs/stdlib-api.md

@@ -140,6 +140,7 @@ typedef struct AetherString {
 - `string.to_cstr(str)` - Get C string pointer
 - `string.from_int(value)` - Convert int to string
 - `string.from_float(value)` - Convert float to string
+- `string.from_double(value)` - Convert float (binary64) to lossless decimal string (round-trip safe)
 
 #### Parsing (Go-style)
 

docs/stdlib-reference.md

@@ -618,6 +618,7 @@ For a `split_once`-style operation (find the first `sep` in `s`, return the halv
 - `string.to_cstr(str)` - Get raw C string pointer
 - `string.from_int(value)` - Create string from integer
 - `string.from_float(value)` - Create string from float
+- `string.from_double(value)` - Create lossless, round-trip-safe decimal string from float (binary64)
 
 **Parsing (Go-style):**
 - `string.to_int(s)` → `(int, string)` - Parse base-10 integer

std/string/aether_string.h

@@ -196,6 +196,10 @@ AetherString* string_from_long(long long value);
 // ABI-mismatch hazard caused `from_float(1.0)` to serialise as `"0"`
 // — see the .c-side comment for the full diagnosis.
 AetherString* string_from_float(double value);
+// Lossless, deterministic double-to-decimal text conversion pairing with
+// `string.to_double`. Round-trips every finite IEEE-754 binary64 value,
+// and normalizes special values.
+AetherString* string_from_double(double value);
 
 // Inverse of string_to_int_radix: render `value` in base `radix`
 // (2..36). Empty string on out-of-range radix; '-' prefix for

std/string/module.ae

@@ -31,6 +31,7 @@ exports(
     string_seq_each, string_seq_map, string_seq_filter, string_seq_reduce,
     string_seq_zip_each,
     string_to_cstr, string_from_int, string_from_long, string_from_float,
+    string_from_double,
     string_from_int_radix, string_pad_start, string_pad_end,
     string_to_int_raw, string_to_long_raw, string_to_float_raw, string_to_double_raw,
     string_try_int, string_get_int, string_try_long, string_get_long,
@@ -323,6 +324,7 @@ extern string_to_cstr(str: string) -> string
 extern string_from_int(value: int) -> ptr
 extern string_from_long(value: long) -> ptr
 extern string_from_float(value: float) -> ptr
+extern string_from_double(value: float) -> string
 
 // Inverse of to_int_radix. Render `value` in base `radix` (2..36).
 // Returns an empty string for radix outside [2, 36]; otherwise the

tests/regression/test_string_double_roundtrip.ae

@@ -0,0 +1,114 @@
+import std.mem
+import std.string
+
+check_roundtrip(bits: long) -> int {
+    value = mem.float_from_bits(bits)
+    text = string.from_double(value)
+    parsed, err = string.to_double(text)
+    parsed_bits = mem.bits_of_float(parsed)
+
+    ok = 1
+    if err != "" || bits != parsed_bits {
+        ok = 0
+    }
+
+    if ok == 0 {
+        orig_hex = string.from_int_radix(bits, 16)
+        parsed_hex = string.from_int_radix(parsed_bits, 16)
+        println("  FAIL: bit mismatch!")
+        println("    Original bits: ${orig_hex}")
+        println("    Emitted text:  ${text}")
+        println("    Parse error:   ${err}")
+        println("    Parsed bits:   ${parsed_hex}")
+        string.free(orig_hex)
+        string.free(parsed_hex)
+    }
+
+    string.free(text)
+    string.free(err)
+
+    if ok == 1 {
+        return 0
+    }
+    return 1
+}
+
+check_text(value: float, expected: string, label: string) -> int {
+    text = string.from_double(value)
+    ok = 1
+    if string.equals(text, expected) != 1 {
+        ok = 0
+        println("  FAIL ${label}: got \"${text}\", expected \"${expected}\"")
+    } else {
+        println("  PASS ${label}: ${expected}")
+    }
+    string.free(text)
+    if ok == 1 {
+        return 0
+    }
+    return 1
+}
+
+main() {
+    println("=== Running IEEE-754 binary64 round-trip tests ===")
+    fails = 0
+
+    // Required raw bit patterns
+    fails = fails + check_roundtrip(0x0000000000000000)
+    fails = fails + check_roundtrip(0x8000000000000000)
+    fails = fails + check_roundtrip(0x0000000000000001)
+    fails = fails + check_roundtrip(0x000fffffffffffff)
+    fails = fails + check_roundtrip(0x0010000000000000)
+    fails = fails + check_roundtrip(0x3ff0000000000000)
+    fails = fails + check_roundtrip(0x3ff0000000000001)
+    fails = fails + check_roundtrip(0x3fefffffffffffff)
+    fails = fails + check_roundtrip(0x3fb999999999999a)
+    fails = fails + check_roundtrip(0x400921fb54442d18)
+    fails = fails + check_roundtrip(0x7fefffffffffffff)
+
+    // Negative counterparts
+    fails = fails + check_roundtrip(0x8000000000000001)
+    fails = fails + check_roundtrip(0x800fffffffffffff)
+    fails = fails + check_roundtrip(0x8010000000000000)
+    fails = fails + check_roundtrip(0xbff0000000000000)
+    fails = fails + check_roundtrip(0xffefffffffffffff)
+
+    // Ordinary expected text tests
+    fails = fails + check_text(0.0, "0", "zero text")
+    fails = fails + check_text(mem.float_from_bits(0x8000000000000000), "-0", "neg zero text")
+    fails = fails + check_text(1.0, "1", "1.0 text")
+    fails = fails + check_text(-2.5, "-2.5", "-2.5 text")
+
+    // Special values: Infinity, -Infinity, NaN
+    inf_val = mem.float_from_bits(0x7ff0000000000000)
+    neginf_val = mem.float_from_bits(0xfff0000000000000)
+    nan_val = mem.float_from_bits(0x7ff8000000000000)
+
+    fails = fails + check_text(inf_val, "Infinity", "Infinity text")
+    fails = fails + check_text(neginf_val, "-Infinity", "-Infinity text")
+    fails = fails + check_text(nan_val, "NaN", "NaN text")
+
+    // Deterministic loop over several thousand generated finite bit patterns.
+    var state = 1234567890123456789
+    var count = 0
+    var loop_fails = 0
+    while count < 5000 {
+        state = (state *6364136223846793005) + 1442695040888963407
+        if (state &0x7ff0000000000000) != 0x7ff0000000000000 {
+            loop_fails = loop_fails + check_roundtrip(state)
+            count = count + 1
+        }
+    }
+    if loop_fails > 0 {
+        println("  FAIL: ${loop_fails} loop patterns failed.")
+        fails = fails + loop_fails
+    } else {
+        println("  PASS: 5000 deterministic pseudo-random finite bit patterns round-tripped perfectly.")
+    }
+
+    if fails > 0 {
+        println("FAIL: Some tests failed.")
+        exit(1)
+    }
+    println("All PASS")
+}