Simplify examples

Author: jessealama

docs/cookbook.md

@@ -6,48 +6,22 @@ The Decimal proposal uses a subset of the IEEE 754-2019 Decimal128 format. This
 
 ## IEEE 754-2019 Decimal128
 
-Decimal128 is part of the IEEE 754 standard for floating-point arithmetic, added in the 2008 revision. It provides:
-
-- **128-bit representation**: Each decimal value is stored in exactly 128 bits
-- **Base-10 arithmetic**: Unlike binary floating-point, calculations are performed in base 10
-- **34 significant digits**: Up to 34 decimal digits of precision
-- **Exponent range**: -6143 to +6144 (base 10)
-
-### Why Decimal128?
+Decimal128 is part of the IEEE 754 standard for floating-point arithmetic, added in the 2008 revision. (In fact, JS's Number type is also based on IEEE 754: binary64) It provides a 128-bit representation(each decimal value is stored in exactly 128 bits) for base-10 arithmetic with up to 34 significant digits and an exponent range of -6143 to +6144.
 
 The choice of Decimal128 balances several considerations:
 
 1. **Sufficient precision**: 34 digits covers virtually all practical use cases, including:
-   - Financial calculations (even national debts)
+   - Financial calculations (even very large values that don't occur in everyday scenarios)
    - Scientific measurements
-   - Cryptocurrency (Bitcoin has 8 decimal places)
-
 2. **Fixed size**: Unlike arbitrary-precision decimals, Decimal128 has predictable memory usage and performance characteristics
-
-3. **Industry standard**: Implemented in hardware on some platforms and widely supported in other languages
-
+3. **Industry standard**: Widely supported in other languages
 4. **Reasonable range**: Can represent values from ±10^-6143 to ±10^6144
 
-## Representation Details
-
-### Encoding Format
-
-Decimal128 uses a specialized encoding that efficiently packs decimal digits into 128 bits:
-
-```
-Sign (1 bit) | Combination field (17 bits) | Trailing significand (110 bits)
-```
-
-The combination field encodes:
-- Two bits of the exponent
-- Whether the number is finite, infinite, or NaN
-- The most significant digit of the significand (for finite numbers)
-
 ### Special Values
 
 #### NaN (Not a Number)
 
-Decimal has a single, quiet NaN value:
+Decimal has a single, quiet NaN value, similar to JS's Number:
 
 ```javascript
 const nan = new Decimal("NaN");
@@ -58,8 +32,6 @@ nan.add(new Decimal("5")); // => NaN
 nan.multiply(new Decimal("0")); // => NaN
 ```
 
-Unlike IEEE 754 binary floating-point, Decimal does not distinguish between quiet and signaling NaNs.
-
 #### Infinity
 
 Positive and negative infinity are supported:
@@ -116,7 +88,7 @@ new Decimal("10").divide(new Decimal("3")).multiply(new Decimal("3")); // => 10
 
 ### Rounding
 
-When a result would exceed 34 significant digits, rounding occurs:
+When a result would exceed 34 significant digits, the calculation is exact up to 34 digits with rounding occuring after the 34th digit:
 
 ```javascript
 // Division may require rounding
@@ -128,7 +100,7 @@ const result = a.divide(b); // => 0.3333333333333333333333333333333333 (34 digit
 The default rounding mode is "half even" (banker's rounding), but other modes are available:
 
 - **halfEven**: Round to nearest, ties to even (default)
-- **halfAwayFromZero**: Round to nearest, ties away from zero
+- **halfExpand**: Round to nearest, ties away from zero
 - **ceil**: Round towards positive infinity
 - **floor**: Round towards negative infinity
 - **trunc**: Round towards zero
@@ -151,23 +123,23 @@ small.divide(new Decimal("10")); // => 0
 
 ### vs Number (binary64)
 
-| Aspect | Number (IEEE 754 binary64) | Decimal (IEEE 754 Decimal128) |
-|--------|---------------------------|-------------------------------|
-| Base | Binary (base 2) | Decimal (base 10) |
-| Precision | ~15-17 decimal digits | Exactly 34 decimal digits |
-| Exact decimal representation | No | Yes |
-| Range | ±1.8×10^308 | ±9.999...×10^6144 |
-| Size | 64 bits | 128 bits |
-| Special values | ±0, ±Infinity, NaN | ±0, ±Infinity, NaN |
+| Aspect                       | Number (IEEE 754 binary64) | Decimal (IEEE 754 Decimal128) |
+| ---------------------------- | -------------------------- | ----------------------------- |
+| Base                         | Binary (base 2)            | Decimal (base 10)             |
+| Precision                    | ~15-17 decimal digits      | Exactly 34 decimal digits     |
+| Exact decimal representation | No                         | Yes                           |
+| Range                        | ±1.8×10^308                | ±9.999...×10^6144             |
+| Size                         | 64 bits                    | 128 bits                      |
+| Special values               | ±0, ±Infinity, NaN         | ±0, ±Infinity, NaN            |
 
 ### vs BigInt
 
-| Aspect | BigInt | Decimal |
-|--------|--------|---------|
-| Precision | Arbitrary | 34 significant digits |
-| Decimal fractions | No | Yes |
-| Memory usage | Variable | Fixed 128 bits |
-| Performance | Varies with size | Consistent |
+| Aspect            | BigInt           | Decimal               |
+| ----------------- | ---------------- | --------------------- |
+| Precision         | Arbitrary        | 34 significant digits |
+| Non-integers      | No               | Yes                   |
+| Memory usage      | Variable         | Fixed 128 bits        |
+| Performance       | Varies with size | Consistent            |
 
 ## Design Decisions
 
@@ -185,10 +157,7 @@ const b = new Decimal("20");
 a.add(b); // => Decimal("30")
 ```
 
-This decision was made based on implementer feedback and concerns about:
-- Performance implications
-- Confusion with implicit conversions
-- Consistency with BigInt precedent
+This decision was made based on implementer feedback and concerns about performance implication, confusion with implicit conversions (given that Decimal is not proposed as a new primitive type).
 
 ### No Literal Syntax
 
@@ -204,60 +173,8 @@ This simplifies the implementation and avoids syntax complexity.
 
 ### Canonicalization vs Cohort Preservation
 
-IEEE 754 supports the concept of "cohorts" - different representations of the same value (e.g., 1.20 vs 1.2). The Decimal proposal canonicalizes values, not preserving cohorts:
+IEEE 754 supports the concept of "cohorts", which are different representations of the same value (e.g., 1.20 vs 1.2). The Decimal proposal canonicalizes values, not preserving cohorts:
 
 ```javascript
 new Decimal("1.20").toString(); // => "1.2" (trailing zero lost)
 ```
-
-## Implementation Considerations
-
-### Memory Layout
-
-Each Decimal value occupies 128 bits (16 bytes). Implementations may choose to:
-- Store inline for small objects
-- Use tagged pointers
-- Allocate on heap for compatibility
-
-### Performance
-
-Expected performance characteristics:
-- **Addition/Subtraction**: Similar to integer operations with normalization
-- **Multiplication**: More complex than binary, but hardware acceleration possible
-- **Division**: Most expensive operation, may require iterative algorithms
-- **Comparison**: Fast, often just integer comparison of encoded form
-
-### Platform Support
-
-Some platforms provide hardware support for Decimal128:
-- IBM POWER (Power6 and later)
-- IBM System z
-- Some Intel processors (via libraries)
-
-On platforms without hardware support, software implementations are used.
-
-## Future Considerations
-
-### Decimal256
-
-For applications requiring more than 34 digits, a future proposal might add Decimal256 (70 digits). The current API is designed to be extensible.
-
-### Arbitrary Precision
-
-Some use cases might benefit from arbitrary-precision decimals (BigDecimal). This could be a separate type that interoperates with Decimal128.
-
-### Operator Overloading
-
-If JavaScript adds general operator overloading, Decimal could be updated to support arithmetic operators while maintaining backward compatibility with the method-based API.
-
-## Summary
-
-The Decimal data model provides:
-- Exact decimal arithmetic for 34 significant digits
-- IEEE 754-2019 standard compliance
-- Predictable performance and memory usage
-- Special value handling (NaN, Infinity)
-- Multiple rounding modes
-- Clear semantics without implicit conversions
-
-This design balances the needs of financial calculations, data exchange, and general decimal arithmetic while maintaining implementation feasibility across JavaScript engines.

docs/data-model.md

@@ -213,6 +213,7 @@ All rounding methods follow IEEE 754-2019 rounding modes.
 Rounds to a given number of decimal places.
 
 **Parameters:**
+
 - `scale` (number): Number of decimal places to round to (default: 0)
 - `options.roundingMode` (string): One of "ceil", "floor", "trunc", "halfEven" (default), or "halfAwayFromZero"
 
@@ -341,4 +342,3 @@ Returns the string representation. This method is called by JavaScript when a pr
 ```js
 new Decimal("123.45").valueOf(); // => "123.45"
 ```
-

docs/decimal.md

@@ -24,8 +24,7 @@ A `Decimal` represents an exact base-10 decimal number using IEEE 754-2019 Decim
 ```js
 const price = new Decimal("19.99");
 const quantity = new Decimal("3");
-const total = price.multiply(quantity); // => Decimal("59.97")
-total.toString(); // => "59.97"
+const total = price.multiply(quantity).toString(); // "59.97"
 ```
 
 Unlike JavaScript's `Number` type, Decimal provides exact decimal arithmetic:
@@ -37,7 +36,9 @@ Unlike JavaScript's `Number` type, Decimal provides exact decimal arithmetic:
 // With Decimal
 const a = new Decimal("0.1");
 const b = new Decimal("0.2");
-a.add(b).toString(); // => "0.3"
+const c = a.add(b);
+c.toString(); // "0.3"
+c.equals(new Decimal("0.3")); // true
 ```
 
 See [Decimal Documentation](./decimal.md) for detailed documentation.
@@ -48,7 +49,7 @@ Decimal uses a subset of the IEEE 754-2019 Decimal128 specification:
 
 - **128-bit representation** allowing up to 34 significant digits
 - **Base-10 exponent** range of -6143 to +6144
-- **Special values**: NaN, positive and negative infinity
+- **Special values**: NaN, positive and negative infinity for compatibility with IEEE 754 and JS's `Number`
 - **Canonicalization**: values are normalized (e.g., "1.20" becomes "1.2")
 
 For a detailed explanation of the data model and design decisions, see [Data Model Documentation](./data-model.md).
@@ -61,7 +62,7 @@ All Decimal values can be converted to and from strings:
 // Parsing
 const d1 = new Decimal("123.456");
 const d2 = new Decimal("-0.0078");
-const d3 = new Decimal("6.022e23"); // Scientific notation
+const d3 = new Decimal("6.022e23");
 
 // Formatting
 d1.toString(); // => "123.456"
@@ -74,8 +75,9 @@ d1.toPrecision(5); // => "123.46"
 
 ### Financial Calculations
 
+#### Calculate bill with tax
+
 ```js
-// Calculate bill with tax
 function calculateTotal(subtotal, taxRate) {
   const subtotalDec = new Decimal(subtotal);
   const taxRateDec = new Decimal(taxRate);
@@ -87,7 +89,7 @@ const total = calculateTotal("99.99", "0.0825");
 console.log(total.toFixed(2)); // => "108.24"
 ```
 
-### Currency Conversion
+#### Currency Conversion
 
 ```js
 const amountUSD = new Decimal("100.00");
@@ -96,11 +98,9 @@ const amountEUR = amountUSD.multiply(exchangeRate);
 console.log(amountEUR.toFixed(2)); // => "85.00"
 ```
 
-
-
 ## Other Documentation
 
 - [Why Decimal?](./why-decimal.md) — Understanding the motivation and use cases for Decimal
 - [API Reference](./decimal.md) — Complete API documentation for Decimal
 - [Cookbook](./cookbook.md) — Common recipes and patterns for working with Decimal
-- [Data Model](./data-model.md) — Detailed explanation of the IEEE 754-2019 Decimal128 subset
+- [Data Model](./data-model.md) — Detailed explanation of the IEEE 754-2019 Decimal128 subset