Fixed adding()/subtracting(). Removed time value category methods: timecode(at:base:limit:) and timecode(using:)

Author: orchetect

Sources/TimecodeKit/API Evolution/API-2.0.0.swift

@@ -423,28 +423,6 @@ extension Timecode {
 }
 
 extension Timecode.Components {
-    @available(*, deprecated, renamed: "timecode(at:base:limit:)")
-    public func toTimecode(
-        at rate: TimecodeFrameRate,
-        limit: Timecode.UpperLimit = .max24Hours,
-        base: Timecode.SubFramesBase = .default(),
-        format: Timecode.StringFormat = .default()
-    ) throws -> Timecode {
-        let properties = Timecode.Properties(rate: rate, base: base, limit: limit)
-        return try timecode(using: properties)
-    }
-    
-    @available(*, deprecated, message: "Renamed to timecode(at:base:limit: by: .allowingInvalid)")
-    public func toTimecode(
-        rawValuesAt rate: TimecodeFrameRate,
-        limit: Timecode.UpperLimit = .max24Hours,
-        base: Timecode.SubFramesBase = .default(),
-        format: Timecode.StringFormat = .default()
-    ) -> Timecode {
-        let properties = Timecode.Properties(rate: rate, base: base, limit: limit)
-        return timecode(using: properties, by: .allowingInvalid)
-    }
-    
     @available(*, deprecated, renamed: "invalidComponents(at:base:limit:)")
     public func invalidComponents(
         at rate: TimecodeFrameRate,

Sources/TimecodeKit/Documentation.docc/TimecodeKit-2-Migration-Guide.md

@@ -150,17 +150,18 @@ For value type reference, see the [Time Value Types](#Time-Value-Types) section
 
 For timecode validation rules reference, see the [Timecode Validation](#Timecode-Validation) section above.
 
-## Functional Shorthand
+## Removal Functional Shorthand
 
-The time value category method `toTimecode(...)` has been renamed to `timecode(...)`.
+For technical reasons and to avoid ambiguity for time value types that are common types (such as TimeInterval aka Double),
+the `toTimecode(...)` category methods have been removed.
 
 For example:
 
 ```swift
 // 1.x API
 try "01:00:00:00".toTimecode(at: ._24)
 // 2.x API
-try "01:00:00:00".timecode(at: .fps24)
+// (removed)
 ```
 
 ## Enum Case Respellings

Sources/TimecodeKit/Timecode/Math/Timecode Math Internal.swift

@@ -571,11 +571,11 @@ extension Timecode {
     func _offset(to other: Components) -> TimecodeInterval {
         if components == other {
             return TimecodeInterval(
-                Timecode.Components.zero.timecode(
+                Timecode(
+                    .zero,
                     at: frameRate,
                     base: subFramesBase,
-                    limit: upperLimit,
-                    by: .allowingInvalid
+                    limit: upperLimit
                 ),
                 .plus
             )
@@ -595,7 +595,8 @@ extension Timecode {
                 from: otherTimecode.components
             )
 
-            let deltaTC = diff.timecode(
+            let deltaTC = Timecode(
+                .components(diff),
                 using: properties,
                 by: .allowingInvalid
             )
@@ -610,7 +611,8 @@ extension Timecode {
                 from: components
             )
 
-            let deltaTC = diff.timecode(
+            let deltaTC = Timecode(
+                .components(diff),
                 using: properties,
                 by: .allowingInvalid
             )

Sources/TimecodeKit/Timecode/Math/Timecode Math Public.swift

@@ -174,79 +174,79 @@ extension Timecode {
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: TimecodeSourceValue) throws -> Timecode {
+    public func adding(_ other: TimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try adding(otherTC)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: FormattedTimecodeSourceValue) throws -> Timecode {
+    public func adding(_ other: FormattedTimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try adding(otherTC)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: RichTimecodeSourceValue) throws -> Timecode {
+    public func adding(_ other: RichTimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other)
         return try adding(otherTC)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: GuaranteedTimecodeSourceValue) throws -> Timecode {
+    public func adding(_ other: GuaranteedTimecodeSourceValue) throws -> Timecode {
         let otherTC = Timecode(other, using: properties)
         return try adding(otherTC)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: GuaranteedRichTimecodeSourceValue) throws -> Timecode {
+    public func adding(_ other: GuaranteedRichTimecodeSourceValue) throws -> Timecode {
         let otherTC = Timecode(other)
         return try adding(otherTC)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: TimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func adding(_ other: TimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try adding(otherTC, by: validation)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: FormattedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func adding(_ other: FormattedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try adding(otherTC, by: validation)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: RichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func adding(_ other: RichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other)
         return try adding(otherTC, by: validation)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: GuaranteedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func adding(_ other: GuaranteedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = Timecode(other, using: properties)
         return try adding(otherTC, by: validation)
     }
 
     /// Add a duration to the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func adding(_ other: GuaranteedRichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func adding(_ other: GuaranteedRichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = Timecode(other)
         return try adding(otherTC, by: validation)
     }
@@ -440,79 +440,79 @@ extension Timecode {
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: TimecodeSourceValue) throws -> Timecode {
+    public func subtracting(_ other: TimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try subtracting(otherTC)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: FormattedTimecodeSourceValue) throws -> Timecode {
+    public func subtracting(_ other: FormattedTimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try subtracting(otherTC)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: RichTimecodeSourceValue) throws -> Timecode {
+    public func subtracting(_ other: RichTimecodeSourceValue) throws -> Timecode {
         let otherTC = try Timecode(other)
         return try subtracting(otherTC)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: GuaranteedTimecodeSourceValue) throws -> Timecode {
+    public func subtracting(_ other: GuaranteedTimecodeSourceValue) throws -> Timecode {
         let otherTC = Timecode(other, using: properties)
         return try subtracting(otherTC)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: GuaranteedRichTimecodeSourceValue) throws -> Timecode {
+    public func subtracting(_ other: GuaranteedRichTimecodeSourceValue) throws -> Timecode {
         let otherTC = Timecode(other)
         return try subtracting(otherTC)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: TimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func subtracting(_ other: TimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try subtracting(otherTC, by: validation)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: FormattedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func subtracting(_ other: FormattedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other, using: properties)
         return try subtracting(otherTC, by: validation)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: RichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func subtracting(_ other: RichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = try Timecode(other)
         return try subtracting(otherTC, by: validation)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: GuaranteedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func subtracting(_ other: GuaranteedTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = Timecode(other, using: properties)
         return try subtracting(otherTC, by: validation)
     }
 
     /// Subtract a duration from the current timecode and return a new instance.
     ///
     /// - Throws: ``ValidationError``
-    public mutating func subtracting(_ other: GuaranteedRichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
+    public func subtracting(_ other: GuaranteedRichTimecodeSourceValue, by validation: ValidationRule) throws -> Timecode {
         let otherTC = Timecode(other)
         return try subtracting(otherTC, by: validation)
     }
@@ -664,13 +664,13 @@ extension Timecode {
     // MARK: - Offset / TimecodeInterval
 
     /// Offsets the current timecode by a delta amount.
-    /// Wraps around the clock if needed, as set by the `upperLimit` property.
+    /// Wraps around the clock if needed, as set by the ``upperLimit`` property.
     public mutating func offset(by interval: TimecodeInterval) {
         self = interval.timecode(offsetting: self)
     }
 
     /// Returns the timecode offset by a delta amount.
-    /// Wraps around the clock if needed, as set by the `upperLimit` property.
+    /// Wraps around the clock if needed, as set by the ``upperLimit`` property.
     public func offsetting(by interval: TimecodeInterval) -> Timecode {
         interval.timecode(offsetting: self)
     }
@@ -682,24 +682,21 @@ extension Timecode {
         } else {
             guard let otherConverted = try? other.converted(to: frameRate) else {
                 assertionFailure("Could not convert other Timecode to self Timecode frameRate.")
-                return .init(
-                    Timecode.Components.zero
-                        .timecode(using: properties, by: .allowingInvalid)
-                )
+                return .init(Timecode(.zero, using: properties))
             }
 
             return _offset(to: otherConverted.components)
         }
     }
 
-    /// Constructs a new `TimecodeInterval` instance from `self`.
+    /// Constructs a new ``TimecodeInterval`` instance from `self`.
     public func asInterval(_ sign: FloatingPointSign = .plus) -> TimecodeInterval {
         TimecodeInterval(self, sign)
     }
 
     // MARK: - Convenience Attributes
 
-    /// Returns `true` if timecode including subframes is zero (00:00:00:00.00).
+    /// Returns `true` if timecode (including subframes) is zero (00:00:00:00.00).
     public var isZero: Bool {
         frameCount.isZero
     }