rainlanguage · thedavidmeister · Aug 14, 2025 · Aug 14, 2025 · coderabbitai · Aug 14, 2025
diff --git a/README.md b/README.md
@@ -1 +1,20 @@
 # rain.math.float
+
+Decimal floating point math implemented in Solidity/Yul.
+
+## Context
+
+IEEE 754 Floating point math such as is used by JavaScript is usually bad in finance for a few reasons.
+
+- The decimal representations of amounts and prices of things don't have exact representations in the underlying binary
+- Mathematical nonsense like dividing by 0 gives "special" values like `Infinity` and `NaN` which then propagate throughout business logic rather than erroring
+
+This lib provides decimal floats that do error upon nonsense.
+
+Everything you can type into a webform, or Rainlang, etc. that fits into 224 bit coefficient with 32 bit exponent (huge values for both) will be exactly represented.
+
+This doesn't mean the floating point math is perfect, for example 1/3 will still be some imprecise rounded 0.3333... value as we don't have infinite precision.
+
+It does mean that `0.2+0.7` is `0.9` rather than `0.8999999999999999` because the fractional values use decimal exponents rather than binary exponents.
+
+e.g. `0.2` internally is something like `2e-1` and `0.7` is `7e-1` so internally the result is `2+7` which is `9` with an exponent of `-1`.
-Decimal floating point math implemented in Solidity/Yul.
-
-## Context
-
-IEEE 754 Floating point math such as is used by JavaScript is usually bad in finance for a few reasons.
-
- The decimal representations of amounts and prices of things don't have exact representations in the underlying binary
- Mathematical nonsense like dividing by 0 gives "special" values like `Infinity` and `NaN` which then propagate throughout business logic rather than erroring
-
-This lib provides decimal floats that do error upon nonsense.
-
-Everything you can type into a webform, or Rainlang, etc. that fits into 224 bit coefficient with 32 bit exponent (huge values for both) will be exactly represented.
-
-This doesn't mean the floating point math is perfect, for example 1/3 will still be some imprecise rounded 0.3333... value as we don't have infinite precision.
-
-It does mean that `0.2+0.7` is `0.9` rather than `0.8999999999999999` because the fractional values use decimal exponents rather than binary exponents.
-
-e.g. `0.2` internally is something like `2e-1` and `0.7` is `7e-1` so internally the result is `2+7` which is `9` with an exponent of `-1`.
+Decimal floating-point math implemented in Solidity/Yul.
+
+## Context
+
+IEEE 754 binary floating-point (as used by JavaScript) is a poor fit for many financial use cases:
+
+- Many decimal fractions cannot be represented exactly in binary floating-point formats.
+- Operations such as division by zero produce special values (`Infinity`, `NaN`) that can propagate through computations instead of reverting.
+
+This library provides decimal floats that revert on invalid operations rather than producing `NaN`/`Infinity`.
+
+Any finite decimal literal whose coefficient fits within 224 bits with a 32-bit decimal exponent range is exactly representable in this format. Internally, the `Float` type packs a 224-bit signed coefficient and a 32-bit signed exponent into 32 bytes.
+
+Not all values have exact decimal expansions; for example, 1/3 will be rounded (0.3333…), as precision is finite.
+
+It does mean that `0.2 + 0.7` evaluates to `0.9`, because fractional values use base-10 exponents rather than base-2 exponents.
+
+For example, `0.2` is represented approximately as `2e-1` and `0.7` as `7e-1`; adding them yields `9e-1` (i.e., `0.9`).
-Decimal floating point math implemented in Solidity/Yul.
-
-## Context
-
-IEEE 754 Floating point math such as is used by JavaScript is usually bad in finance for a few reasons.
-
- The decimal representations of amounts and prices of things don't have exact representations in the underlying binary
- Mathematical nonsense like dividing by 0 gives "special" values like `Infinity` and `NaN` which then propagate throughout business logic rather than erroring
-
-This lib provides decimal floats that do error upon nonsense.
-
-Everything you can type into a webform, or Rainlang, etc. that fits into 224 bit coefficient with 32 bit exponent (huge values for both) will be exactly represented.
-
-This doesn't mean the floating point math is perfect, for example 1/3 will still be some imprecise rounded 0.3333... value as we don't have infinite precision.
-
-It does mean that `0.2+0.7` is `0.9` rather than `0.8999999999999999` because the fractional values use decimal exponents rather than binary exponents.
-
-e.g. `0.2` internally is something like `2e-1` and `0.7` is `7e-1` so internally the result is `2+7` which is `9` with an exponent of `-1`.
+Decimal floating-point math implemented in Solidity/Yul.
+
+## Context
+
+IEEE 754 binary floating-point (as used by JavaScript) is a poor fit for many financial use cases:
+
+- Many decimal fractions cannot be represented exactly in binary floating-point formats.
+- Operations such as division by zero produce special values (`Infinity`, `NaN`) that can propagate through computations instead of reverting.
+
+This library provides decimal floats that revert on invalid operations rather than producing `NaN`/`Infinity`.
+
+Any finite decimal literal whose coefficient fits within 224 bits with a 32-bit decimal exponent range is exactly representable in this format. Internally, the `Float` type packs a 224-bit signed coefficient and a 32-bit signed exponent into 32 bytes.
+
+Not all values have exact decimal expansions; for example, 1/3 will be rounded (0.3333…), as precision is finite.
+
+It does mean that `0.2 + 0.7` evaluates to `0.9`, because fractional values use base-10 exponents rather than base-2 exponents.
+
+For example, `0.2` is represented approximately as `2e-1` and `0.7` as `7e-1`; adding them yields `9e-1` (i.e., `0.9`).