Respell the subframe count domain as Int64 for 32-bit platforms

Alternative to the saturating fix in #88, per review feedback: use Int64 where
the value genuinely needs 64 bits, rather than clamping.

At `.max100Days` a subframe count exceeds Int32.max for every frame rate at the
80- and 100-subframe bases (smallest: 23.976fps@80 = 16_588_800_000), so on a
32-bit platform — wasm32, watchOS armv7k/arm64_32 — the `Int` form trapped on
overflow. Because the bound is recomputed inside every wrapping add, that took
ALL arithmetic on a `.max100Days` timecode with it, however small the operands.

Widened, with no platform-conditional logic:
- internal: `FrameCount.subFrameCount`, `framesToSubFrames`, `subFramesToFrames`,
  `FrameCount.init(subFrameCount:base:)`, and the `sfcNew` locals (which infer).
- public: `TimecodeFrameRate.maxTotalSubFrames(in:base:)`,
  `maxSubFrameCountExpressible(in:base:)`, `Timecode.maxSubFrameCountExpressible`.

Deliberately NOT widened: `maxTotalFrames`, which peaks at 1_036_800_000
(120fps @ 100 days) and fits a 32-bit Int; and the frames/subFrames components,
which are bounded by it. Only the COUNT needs 64 bits.

One narrowing remains, at `Timecode.rationalValue`: `Fraction` is Int-based, so
a timecode beyond ~Int32.max subframes has no representable rational value on a
32-bit platform. That is a pre-existing limit of `Fraction`, not of the count,
and is commented at the site.

Unlike the saturating approach this makes `.max100Days` genuinely usable on
32-bit rather than merely non-trapping.

Full suite passes: 506 tests in 55 suites.

Author: mansbernhardt

Sources/SwiftTimecodeCore/Timecode/FrameCount/FrameCount.swift

@@ -105,7 +105,7 @@ extension Timecode {
 
 extension Timecode.FrameCount {
     init(
-        subFrameCount: Int,
+        subFrameCount: Int64,
         base: Timecode.SubFramesBase
     ) {
         let converted = Timecode.subFramesToFrames(
@@ -225,7 +225,7 @@ extension Timecode.FrameCount {
     public func multiplying(by factor: Double) -> Self {
         let lhsTotalSubFrames = subFrameCount
 
-        let resultSubFrameCount = Int(Double(lhsTotalSubFrames) * factor)
+        let resultSubFrameCount = Int64(Double(lhsTotalSubFrames) * factor)
 
         let newFrames = Timecode.subFramesToFrames(
             resultSubFrameCount,
@@ -241,7 +241,7 @@ extension Timecode.FrameCount {
     public func dividing(by divisor: Double) -> Self {
         let lhsTotalSubFrames = subFrameCount
 
-        let resultSubFrameCount = Int(Double(lhsTotalSubFrames) / divisor)
+        let resultSubFrameCount = Int64(Double(lhsTotalSubFrames) / divisor)
 
         let newFrames = Timecode.subFramesToFrames(
             resultSubFrameCount,
@@ -268,7 +268,7 @@ extension Timecode.FrameCount {
 }
 
 extension Timecode.FrameCount {
-    var subFrameCount: Int {
+    var subFrameCount: Int64 {
         Timecode.framesToSubFrames(
             frames: wholeFrames,
             subFrames: subFrames,
@@ -285,15 +285,19 @@ extension Timecode {
         frames: Int,
         subFrames: Int,
         base: SubFramesBase
-    ) -> Int {
-        (frames * base.rawValue) + subFrames
+    ) -> Int64 {
+        // Int64 because a 100-day timecode's subframe count exceeds Int32.max
+        // for every frame rate, and `Int` is 32-bit on wasm32 / watchOS armv7k.
+        (Int64(frames) * Int64(base.rawValue)) + Int64(subFrames)
     }
 
     /// Internal utility
-    static func subFramesToFrames(_ subFrames: Int, base: SubFramesBase) -> (frames: Int, subFrames: Int) {
-        let outSubFrames = subFrames % base.rawValue
-        let outFrames = (subFrames - outSubFrames) / base.rawValue
+    static func subFramesToFrames(_ subFrames: Int64, base: SubFramesBase) -> (frames: Int, subFrames: Int) {
+        // The COUNT needs 64 bits; the resulting frames/subFrames do not —
+        // max total frames is ~1.04e9 even at 120 fps over 100 days.
+        let outSubFrames = subFrames % Int64(base.rawValue)
+        let outFrames = (subFrames - outSubFrames) / Int64(base.rawValue)
 
-        return (frames: outFrames, subFrames: outSubFrames)
+        return (frames: Int(outFrames), subFrames: Int(outSubFrames))
     }
 }

Sources/SwiftTimecodeCore/Timecode/Math/Timecode Math Internal.swift

@@ -311,7 +311,7 @@ extension Timecode {
         if sfcNew > Double(maxSubFrameCountExpressible) { return nil }
 
         let fcNew = FrameCount(
-            subFrameCount: Int(sfcNew),
+            subFrameCount: Int64(sfcNew),
             base: subFramesBase
         )
 
@@ -333,7 +333,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        var sfcNew = Int(Double(fcOrigin.subFrameCount) * factor)
+        var sfcNew = Int64(Double(fcOrigin.subFrameCount) * factor)
 
         sfcNew = sfcNew.clamped(to: 0 ... maxSubFrameCountExpressible)
 
@@ -360,7 +360,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        var sfcNew = Int(Double(fcOrigin.subFrameCount) * factor)
+        var sfcNew = Int64(Double(fcOrigin.subFrameCount) * factor)
 
         let maxTotalSubFrames = frameRate.maxTotalSubFrames(
             in: upperLimit,
@@ -401,7 +401,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        let sfcNew = Int(Double(fcOrigin.subFrameCount) * factor)
+        let sfcNew = Int64(Double(fcOrigin.subFrameCount) * factor)
 
         let fcNew = FrameCount(
             subFrameCount: sfcNew,
@@ -434,7 +434,7 @@ extension Timecode {
         if sfcNew > Double(maxSubFrameCountExpressible) { return nil }
 
         let fcNew = FrameCount(
-            subFrameCount: Int(sfcNew),
+            subFrameCount: Int64(sfcNew),
             base: subFramesBase
         )
 
@@ -456,7 +456,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        var sfcNew = Int(Double(fcOrigin.subFrameCount) / divisor)
+        var sfcNew = Int64(Double(fcOrigin.subFrameCount) / divisor)
 
         sfcNew = sfcNew.clamped(to: 0 ... maxSubFrameCountExpressible)
 
@@ -483,7 +483,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        var sfcNew = Int(Double(fcOrigin.subFrameCount) / divisor)
+        var sfcNew = Int64(Double(fcOrigin.subFrameCount) / divisor)
 
         let maxTotalSubFrames = frameRate.maxTotalSubFrames(
             in: upperLimit,
@@ -524,7 +524,7 @@ extension Timecode {
             base: subFramesBase
         )
 
-        let sfcNew = Int(Double(fcOrigin.subFrameCount) / divisor)
+        let sfcNew = Int64(Double(fcOrigin.subFrameCount) / divisor)
 
         let fcNew = FrameCount(
             subFrameCount: sfcNew,

Sources/SwiftTimecodeCore/Timecode/Source/Timecode Rational.swift

@@ -50,7 +50,11 @@ extension Timecode {
     /// fractions.)
     public var rationalValue: Fraction {
         let frFrac = frameRate.frameDuration
-        let n = frFrac.numerator * frameCount.subFrameCount
+        // `Fraction` is `Int`-based, so the 64-bit subframe count is narrowed
+        // here. On a 32-bit platform a timecode beyond ~Int32.max subframes has
+        // no representable rational value — a pre-existing limit of `Fraction`,
+        // not of the count.
+        let n = frFrac.numerator * Int(frameCount.subFrameCount)
         let d = frFrac.denominator * subFramesBase.rawValue
 
         return Fraction(n, d).reduced()

Sources/SwiftTimecodeCore/Timecode/Timecode Validation.swift

@@ -197,7 +197,7 @@ extension Timecode {
     }
 
     /// Returns the `upperLimit` minus 1 subframe expressed as total subframes.
-    public var maxSubFrameCountExpressible: Int {
+    public var maxSubFrameCountExpressible: Int64 {
         frameRate.maxSubFrameCountExpressible(
             in: upperLimit,
             base: subFramesBase

Sources/SwiftTimecodeCore/TimecodeFrameRate/TimecodeFrameRate Properties.swift

@@ -303,16 +303,21 @@ extension TimecodeFrameRate {
     public func maxTotalSubFrames(
         in extent: Timecode.UpperLimit,
         base: Timecode.SubFramesBase
-    ) -> Int {
-        maxTotalFrames(in: extent) * base.rawValue
+    ) -> Int64 {
+        // Int64, not Int: at `.max100Days` this product exceeds Int32.max for
+        // EVERY frame rate (smallest case 23.976fps@80 = 16_588_800_000), so on
+        // a 32-bit platform — wasm32, watchOS armv7k/arm64_32 — the `Int` form
+        // trapped on overflow. `maxTotalFrames` stays `Int`: it peaks at
+        // 1_036_800_000 (120fps @ 100 days), which fits.
+        Int64(maxTotalFrames(in: extent)) * Int64(base.rawValue)
     }
 
     /// Returns max elapsed subframes possible before rolling over to 0.
     /// (Number of subframes from 0 to `extent` minus one subframe).
     public func maxSubFrameCountExpressible(
         in extent: Timecode.UpperLimit,
         base: Timecode.SubFramesBase
-    ) -> Int {
+    ) -> Int64 {
         maxTotalSubFrames(in: extent, base: base) - 1
     }
 }

Tests/SwiftTimecodeCoreTests/TimecodeFrameRate/TimecodeFrameRate Properties Tests.swift

@@ -89,6 +89,44 @@ struct TimecodeFrameRate_Properties_Tests {
         #expect(frameRate.framesDroppedPerMinute == 0.0)
     }
 
+    /// `.max100Days` subframe counts must not overflow on a 32-bit platform.
+    ///
+    /// These counts are `Int64` rather than `Int` because at `.max100Days` the
+    /// product exceeds `Int32.max` for every frame rate at the 80- and
+    /// 100-subframe bases — the smallest such case, 23.976 fps at 80 subframes,
+    /// is already `2_073_600 * 100 * 80 = 16_588_800_000`. (At the
+    /// `.quarterFrames` base the lower rates do still fit, which is exactly why
+    /// this is asserted across every rate/base pair rather than spot-checked.) As plain `Int` this trapped on wasm32 and on watchOS
+    /// armv7k/arm64_32, and because the bound is recomputed inside every
+    /// wrapping add it took ALL arithmetic on a `.max100Days` timecode with it,
+    /// however small the operands.
+    @Test
+    func maxTotalSubFramesFitsOn32Bit() {
+        for frameRate in TimecodeFrameRate.allCases {
+            for base in Timecode.SubFramesBase.allCases {
+                let total = frameRate.maxTotalSubFrames(in: .max100Days, base: base)
+                #expect(total == Int64(frameRate.maxTotalFrames(in: .max100Days)) * Int64(base.rawValue))
+                #expect(frameRate.maxSubFrameCountExpressible(in: .max100Days, base: base) == total - 1)
+            }
+        }
+    }
+
+    /// Arithmetic on a `.max100Days` timecode must work on every platform.
+    ///
+    /// The regression this guards is not about large values — these operands are
+    /// tiny. It is the upper BOUND, recomputed on each wrapping add.
+    @Test
+    func max100DaysArithmeticDoesNotTrap() throws {
+        var lhs = try Timecode(.realTime(seconds: 1.0), at: .fps59_94)
+        var rhs = try Timecode(.realTime(seconds: 192.0), at: .fps59_94)
+        lhs.properties.upperLimit = .max100Days
+        rhs.properties.upperLimit = .max100Days
+
+        let sum = try lhs.adding(rhs, by: .wrapping)
+        #expect(sum.components.minutes == 3)
+        #expect(sum.components.seconds == 12)
+    }
+
     @Test
     func initStringValue() {
         #expect(TimecodeFrameRate(stringValue: "23.976") == .fps23_976)