feat: add Decoder.UseNumber and the Number type

Assisted-by: GLM 5.3 Flash

number.go

@@ -10,6 +10,50 @@ import (
 	"strings"
 )
 
+// A Number holds a TOML number as the literal the document wrote it with:
+// 0x1f, 1_000, +1.0, inf. Decoder.UseNumber decodes integers and floats into
+// it, so a round trip through the value tree keeps the spelling instead of a
+// normalised one, and Marshal writes the literal back as it is.
+//
+// Number is a string type, the shape encoding/json.Number has: the literal is
+// carried, not evaluated. Float64 and Int64 evaluate it on demand, and a
+// destination of another numeric kind takes the evaluated value through the
+// ordinary conversion rules.
+type Number string
+
+// Float64 returns the value as a float64. An integer or radix literal
+// converts; a literal that is not a valid TOML number is an error.
+func (n Number) Float64() (float64, error) {
+	v, err := decodeNumber(string(n))
+	if err != nil {
+		return 0, fmt.Errorf("interpres: %w", err)
+	}
+	switch v := v.(type) {
+	case float64:
+		return v, nil
+	case int64:
+		return float64(v), nil
+	}
+	return 0, fmt.Errorf("interpres: %q is not a number", n)
+}
+
+// Int64 returns the value as an int64. A float literal is an error, however
+// whole its value, and so is a literal that is not a valid TOML number.
+func (n Number) Int64() (int64, error) {
+	v, err := decodeNumber(string(n))
+	if err != nil {
+		return 0, fmt.Errorf("interpres: %w", err)
+	}
+	i, ok := v.(int64)
+	if !ok {
+		return 0, fmt.Errorf("interpres: %q is not an integer", n)
+	}
+	return i, nil
+}
+
+// String returns the literal itself.
+func (n Number) String() string { return string(n) }
+
 // decodeNumber parses a bare numeric token under strict TOML rules: no leading
 // zeros, underscores only between digits, prefixed radixes without a sign, and
 // floats with explicit fraction/exponent digits.