Add comprehensive Floating-Point Math documentation with 40+ examples

[Copilot]

Creates a detailed technical document explaining floating-point arithmetic in Java, covering IEEE 754 representation, common pitfalls, precision issues, and best practices.

Content Overview

• IEEE 754 Fundamentals: Binary representation, precision limits for float (32-bit) and double (64-bit), special values (NaN, Infinity, signed zero)
• Common Pitfalls: The classic 0.1 + 0.2 problem, equality comparison failures, error accumulation, loss of significance, associativity failures
• Comparison Strategies: Epsilon-based, relative epsilon, and ULP-based approaches
• BigDecimal: Proper usage with String constructor, rounding modes, division with scale
• Advanced Topics: Kahan summation, subnormal numbers, Math.fma, strictfp, binary representation inspection
• Practical Guidance: HashMap keys, loop counters, type mixing, performance trade-offs

Example

void main() {
    double a = 0.1;
    double b = 0.2;
    double sum = a + b;

    IO.println("0.1 + 0.2 = " + sum);           // 0.30000000000000004
    IO.println("Equal to 0.3? " + (sum == 0.3)); // false

    // Solution: epsilon comparison
    double epsilon = 1e-10;
    boolean equal = Math.abs(sum - 0.3) < epsilon;
    IO.println("Within epsilon: " + equal);      // true
}

43 code examples following Java 25 conventions (compact source files, instance main methods, implicit imports).

Original prompt

On floating-point.md, Create a detailed technical document explaining Floating-Point Math in Java. Create 40 examples.
The document should include:

1. Introduction

   • Define floating-point numbers in Java (float and double).
   • Explain why floating-point arithmetic is widely used (performance, scientific computing, graphics, etc.).

2. Representation of Floating-Point Numbers

   • Describe IEEE 754 standard and how Java implements it.
   • Explain precision limits of float (32-bit) and double (64-bit).
   • Discuss special values: NaN, Infinity, -Infinity, and signed zero.

3. Common Issues with Floating-Point Math

   • Precision Errors: Explain why 0.1 + 0.2 != 0.3.
   • Rounding Problems: Show examples of unexpected rounding.
   • Accumulation of Errors: Demonstrate how repeated calculations amplify inaccuracies.
   • Comparison Pitfalls: Explain why direct equality checks (==) often fail.
   • Overflow and Underflow: Describe how extremely large or small values behave.

4. Examples of Issues

   • Provide code snippets showing problematic cases.
   • Illustrate real-world consequences (e.g., financial calculations, scientific simulations).

5. Solutions and Best Practices

   • Use BigDecimal for precise decimal arithmetic (especially in finance).
   • Tolerance-based Comparisons: Use an epsilon value for equality checks.
   • Rounding Modes: Explain Math.round, DecimalFormat, and BigDecimal rounding options.
   • Avoid Mixing Types: Be cautious when mixing float, double, and integer arithmetic.
   • Use Libraries: Mention libraries or tools that handle high-precision math.

6. Performance Considerations

   • Compare performance trade-offs between double and BigDecimal.
   • Discuss when precision is more important than speed.

7. Best Practices Summary

   • Guidelines for choosing between float, double, and BigDecimal.
   • Tips for writing robust numerical code in Java.

8. Conclusion

   • Summarize the importance of understanding floating-point math.
   • Emphasize balancing precision, performance, and correctness in Java applications.

Formatting Requirements:

• Include code examples and tables where appropriate.
• Write in a professional, educational tone suitable for intermediate to advanced Java developers.
• Ensure the document is cohesive, well-organized, and easy to follow.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.