Add scoped API for FPU rounding mode control

Introduces safer closure-based APIs for rounding mode and exception state
management in CIEEE754, eliminating the need for manual defer blocks.

New APIs:
- withRoundingMode(_:_:) - Executes closure with specific rounding mode
- withClearedExceptions(_:) - Executes closure with cleared exceptions
- withRoundingModeAndClearedExceptions(_:_:) - Combines both

Benefits:
- Guarantees cleanup through structured programming
- Prevents FPU state pollution between tests
- More ergonomic than manual defer blocks
- Automatically handles errors and early returns

Implementation:
- Created Sources/IEEE 754/CIEEE754+Extensions.swift
- Internal visibility (C types aren't public)
- Uses defer for guaranteed cleanup
- Fully documented with usage examples

Test Updates:
- Refactored CIEEE754 Integration Tests to use scoped API
- Cleaner test code without repetitive defer blocks
- Better isolation guarantees

All 707 tests passing.

Author: coenttb

Sources/IEEE 754/CIEEE754+Extensions.swift

@@ -0,0 +1,119 @@
+// CIEEE754+Extensions.swift
+// swift-ieee-754
+//
+// Swift convenience wrappers for CIEEE754 C APIs
+//
+// Provides scoped APIs that guarantee cleanup and prevent test pollution
+
+#if canImport(CIEEE754)
+import CIEEE754
+
+/// Scoped rounding mode execution
+///
+/// Executes a closure with a specific FPU rounding mode, then automatically
+/// restores the original mode - even if the closure throws.
+///
+/// ## Usage
+///
+/// ```swift
+/// let result = withRoundingMode(.towardZero) {
+///     return 10.0 / 3.0  // Rounded toward zero
+/// }
+/// // Original rounding mode automatically restored
+/// ```
+///
+/// ## Safety
+///
+/// This is the preferred way to change rounding modes in tests and application
+/// code. It guarantees the rounding mode is restored, preventing pollution of
+/// global FPU state.
+///
+/// - Parameters:
+///   - mode: The rounding mode to use during execution
+///   - body: The closure to execute with the specified rounding mode
+/// - Returns: The value returned by the closure
+/// - Throws: Rethrows any error thrown by the closure
+func withRoundingMode<T>(
+    _ mode: IEEE754RoundingMode,
+    _ body: () throws -> T
+) rethrows -> T {
+    let originalMode = ieee754_get_rounding_mode()
+    defer { ieee754_set_rounding_mode(originalMode) }
+
+    ieee754_set_rounding_mode(mode)
+    return try body()
+}
+
+/// Scoped exception state execution
+///
+/// Executes a closure with cleared exception state, then automatically
+/// restores the original exception flags - even if the closure throws.
+///
+/// ## Usage
+///
+/// ```swift
+/// withClearedExceptions {
+///     let result = 1.0 / 0.0  // Raises divByZero
+///     // Exception state is isolated to this scope
+/// }
+/// // Original exception state automatically restored
+/// ```
+///
+/// - Parameter body: The closure to execute with cleared exceptions
+/// - Returns: The value returned by the closure
+/// - Throws: Rethrows any error thrown by the closure
+func withClearedExceptions<T>(_ body: () throws -> T) rethrows -> T {
+    let originalExceptions = ieee754_get_exceptions()
+    defer {
+        // Restore original exception state
+        ieee754_clear_all_exceptions()
+        if originalExceptions.invalid != 0 {
+            ieee754_raise_exception(IEEE754_EXCEPTION_INVALID)
+        }
+        if originalExceptions.divByZero != 0 {
+            ieee754_raise_exception(IEEE754_EXCEPTION_DIVBYZERO)
+        }
+        if originalExceptions.overflow != 0 {
+            ieee754_raise_exception(IEEE754_EXCEPTION_OVERFLOW)
+        }
+        if originalExceptions.underflow != 0 {
+            ieee754_raise_exception(IEEE754_EXCEPTION_UNDERFLOW)
+        }
+        if originalExceptions.inexact != 0 {
+            ieee754_raise_exception(IEEE754_EXCEPTION_INEXACT)
+        }
+    }
+
+    ieee754_clear_all_exceptions()
+    return try body()
+}
+
+/// Scoped rounding mode and exception state execution
+///
+/// Executes a closure with a specific rounding mode and cleared exceptions,
+/// then automatically restores both - even if the closure throws.
+///
+/// ## Usage
+///
+/// ```swift
+/// let result = withRoundingModeAndClearedExceptions(.upward) {
+///     return 1.0 / 3.0
+/// }
+/// // Both rounding mode and exceptions automatically restored
+/// ```
+///
+/// - Parameters:
+///   - mode: The rounding mode to use during execution
+///   - body: The closure to execute
+/// - Returns: The value returned by the closure
+/// - Throws: Rethrows any error thrown by the closure
+func withRoundingModeAndClearedExceptions<T>(
+    _ mode: IEEE754RoundingMode,
+    _ body: () throws -> T
+) rethrows -> T {
+    try withRoundingMode(mode) {
+        try withClearedExceptions(body)
+    }
+}
+
+#endif

Tests/IEEE 754 Tests/CIEEE754 Integration Tests.swift

@@ -20,62 +20,54 @@ struct CIEEERoundingModeTests {
     }
 
     @Test func setRoundingModeToNearest() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
+        withRoundingMode(IEEE754_ROUND_TONEAREST) {
+            let result = ieee754_set_rounding_mode(IEEE754_ROUND_TONEAREST)
+            #expect(result == 0, "Setting rounding mode should succeed")
 
-        let result = ieee754_set_rounding_mode(IEEE754_ROUND_TONEAREST)
-        #expect(result == 0, "Setting rounding mode should succeed")
-
-        let mode = ieee754_get_rounding_mode()
-        #expect(mode == IEEE754_ROUND_TONEAREST)
+            let mode = ieee754_get_rounding_mode()
+            #expect(mode == IEEE754_ROUND_TONEAREST)
+        }
     }
 
     @Test func setRoundingModeDownward() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
-
-        let result = ieee754_set_rounding_mode(IEEE754_ROUND_DOWNWARD)
-        #expect(result == 0)
+        withRoundingMode(IEEE754_ROUND_DOWNWARD) {
+            let result = ieee754_set_rounding_mode(IEEE754_ROUND_DOWNWARD)
+            #expect(result == 0)
 
-        let mode = ieee754_get_rounding_mode()
-        #expect(mode == IEEE754_ROUND_DOWNWARD)
+            let mode = ieee754_get_rounding_mode()
+            #expect(mode == IEEE754_ROUND_DOWNWARD)
+        }
     }
 
     @Test func setRoundingModeUpward() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
-
-        let result = ieee754_set_rounding_mode(IEEE754_ROUND_UPWARD)
-        #expect(result == 0)
+        withRoundingMode(IEEE754_ROUND_UPWARD) {
+            let result = ieee754_set_rounding_mode(IEEE754_ROUND_UPWARD)
+            #expect(result == 0)
 
-        let mode = ieee754_get_rounding_mode()
-        #expect(mode == IEEE754_ROUND_UPWARD)
+            let mode = ieee754_get_rounding_mode()
+            #expect(mode == IEEE754_ROUND_UPWARD)
+        }
     }
 
     @Test func setRoundingModeTowardZero() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
+        withRoundingMode(IEEE754_ROUND_TOWARDZERO) {
+            let result = ieee754_set_rounding_mode(IEEE754_ROUND_TOWARDZERO)
+            #expect(result == 0)
 
-        let result = ieee754_set_rounding_mode(IEEE754_ROUND_TOWARDZERO)
-        #expect(result == 0)
-
-        let mode = ieee754_get_rounding_mode()
-        #expect(mode == IEEE754_ROUND_TOWARDZERO)
+            let mode = ieee754_get_rounding_mode()
+            #expect(mode == IEEE754_ROUND_TOWARDZERO)
+        }
     }
 
     @Test func roundingModeAffectsOperations() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
-
-        // Set to round toward zero
-        ieee754_set_rounding_mode(IEEE754_ROUND_TOWARDZERO)
+        // Test that rounding mode actually affects operations
+        let result1 = withRoundingMode(IEEE754_ROUND_TOWARDZERO) {
+            1.0 / 3.0  // Should round toward zero
+        }
 
-        // 1.0 / 3.0 should round toward zero
-        let result1 = 1.0 / 3.0
-
-        // Set to round upward
-        ieee754_set_rounding_mode(IEEE754_ROUND_UPWARD)
-        let result2 = 1.0 / 3.0
+        let result2 = withRoundingMode(IEEE754_ROUND_UPWARD) {
+            1.0 / 3.0  // Should round upward
+        }
 
         // Results should differ (though exact values depend on rounding)
         // At minimum, verify operations complete
@@ -353,17 +345,15 @@ struct CIEEESignalingCompareFloatTests {
 @Suite("CIEEE754 - Integration Scenarios")
 struct CIEEEIntegrationTests {
     @Test func roundingModeAndExceptions() {
-        let originalMode = ieee754_get_rounding_mode()
-        defer { ieee754_set_rounding_mode(originalMode) }
-
-        // Set rounding mode and perform operation
-        ieee754_set_rounding_mode(IEEE754_ROUND_TOWARDZERO)
-        ieee754_clear_all_exceptions()
+        // Use the combined scoped API for both rounding mode and exceptions
+        let result = withRoundingModeAndClearedExceptions(IEEE754_ROUND_TOWARDZERO) {
+            let result = 10.0 / 3.0
 
-        let result = 10.0 / 3.0
+            // Verify rounding mode is set within scope
+            #expect(ieee754_get_rounding_mode() == IEEE754_ROUND_TOWARDZERO)
 
-        // Verify rounding mode is still set
-        #expect(ieee754_get_rounding_mode() == IEEE754_ROUND_TOWARDZERO)
+            return result
+        }
 
         // Verify result is reasonable
         #expect(result > 3.0 && result < 4.0)