Merge pull request #17 from orchetect/dev

New features and fixes

Author: orchetect

README.md

@@ -80,7 +80,7 @@ Note: This documentation does not cover every property and initializer available
 
 ### Initialization
 
-Using `(_ exaclty:, ...)` by default:
+Using `(_ exactly:, ...)` by default:
 
 ```swift
 // from Int timecode component values
@@ -91,9 +91,9 @@ TCC(h: 01, m: 00, s: 00, f: 00).toTimecode(at: ._23_976) // alternate method
 Timecode("01:00:00:00", at: ._23_976)
 "01:00:00:00".toTimecode(at: ._23_976) // alternate method
 
-// from real time (wall clock) elapsed
-Timecode(TimeValue(seconds: 4723.241579), at: ._23_976)
-TimeValue(seconds: 4723.241579).toTimecode(at: ._23_976) // alternate method
+// from real time (wall clock) elapsed in seconds
+Timecode(realTimeValue: 4723.241579, at: ._23_976)
+(4723.241579).toTimecode(at: ._23_976) // alternate method on TimeInterval
 
 // from elapsed number of audio samples at a given sample rate
 Timecode(samples: 123456789, sampleRate: 48000, at: ._23_976)
@@ -181,7 +181,7 @@ TCC(h: 01, m: 00, s: 00, f: 00)
 
 ### Math
 
-Using operators:
+Using operators (which use `wrapping:` internally if the result underflows or overflows timecode bounds):
 
 ```swift
 guard let tc1 = "01:00:00:00".toTimecode(at: ._23_976) else { return }
@@ -201,13 +201,15 @@ Mutating methods:
 - `.subtract()`
 - `.multiply()`
 - `.divide()`
+- `.offset()`
 
 Non-mutating methods that produce a new `Timecode` instance:
 
 - `.adding()`
 - `.subtracting()`
 - `.multiplying()`
 - `.dividing()`
+- `.offsetting()`
 
 ### Conversions
 
@@ -227,13 +229,13 @@ Non-mutating methods that produce a new `Timecode` instance:
 // timecode to real-world time
 let tc = "01:00:00:00"
     .toTimecode(at: ._23_976)?
-    .realTimeValue // == TimeValue()
+    .realTimeValue // == TimeInterval (aka Double)
 
 tc?.seconds // == 3603.6
 tc?.ms      // == 3603600.0
 
 // real-world time to timecode
-TimeValue(seconds: 3603.6)
+(3603.6) // TimeInterval, aka Double
     .toTimecode(at: ._23_976)?
     .stringValue // == "01:00:00:00"
 ```

Sources/TimecodeKit/Data Interchange/Timecode Real Time.swift

@@ -6,46 +6,48 @@
 //  Copyright © 2018 Steffan Andrews. All rights reserved.
 //
 
+import Foundation
+
 extension Timecode {
 
-	/// (Lossy) Returns the current timecode converted to a duration in real-time milliseconds (wall-clock time), based on the frame rate. Value is returned as a Double so a high level of precision can be maintained.
+	/// (Lossy) Returns the current timecode converted to a duration in real-time (wall-clock time), based on the frame rate.
 	///
-	/// Generally, `.realTimeValue` -> `.setTimecode(from: TimeValue)` will produce equivalent results where 'from timecode' == 'out timecode'.
+	/// Generally, `.realTimeValue` -> `.setTimecode(fromRealTimeValue:)` will produce equivalent results where 'from timecode' == 'out timecode'.
 	/// When setting, invalid values will cause the setter to fail silently. (Validation is based on the frame rate and `upperLimit` property.)
-	public var realTimeValue: TimeValue {
+	public var realTimeValue: TimeInterval {
 
 		get {
-			var calc = Double(totalElapsedFrames) * (1000.0 / frameRate.frameRateForRealTimeCalculation)
+			var calc = Double(totalElapsedFrames) * (1.0 / frameRate.frameRateForRealTimeCalculation)
 
 			// over-estimate so real time is just past the equivalent timecode
 			// so calculations of real time back into timecode work reliably
 			// otherwise, this math produces a real time value that can be a hair under the actual elapsed real time that would trigger the equivalent timecode
 
-			calc += 0.00001
+			calc += 0.00000001
 
-			return TimeValue(ms: calc)
+			return calc
 		}
 
 		set {
 			// set, suppressing failure silently
-			_ = setTimecode(from: newValue)
+			_ = setTimecode(fromRealTimeValue: newValue)
 		}
 
 	}
 
-	/// Sets the timecode to the nearest frame at the current frame rate from real-time milliseconds.
+	/// Sets the timecode to the nearest frame at the current frame rate from real-time (wall-clock time).
 	/// Returns false if it underflows or overflows valid timecode range.
 	@discardableResult
-	public mutating func setTimecode(from realTimeValue: TimeValue) -> Bool {
+	public mutating func setTimecode(fromRealTimeValue: TimeInterval) -> Bool {
 
 		// the basic calculation
-		var calc = realTimeValue.ms / (1000.0 / frameRate.frameRateForRealTimeCalculation)
+		var calc = fromRealTimeValue / (1.0 / frameRate.frameRateForRealTimeCalculation)
 
 		// over-estimate so real time is just past the equivalent timecode
 		// so calculations of real time back into timecode work reliably
 		// otherwise, this math produces a real time value that can be a hair under the actual elapsed real time that would trigger the equivalent timecode
 
-		calc += 0.0006
+		calc += 0.0000006
 
 		// final calculation
 
@@ -60,7 +62,8 @@ extension Timecode {
 
 }
 
-extension TimeValue {
+// a.k.a: extension Double
+extension TimeInterval {
 
 	/// Convenience method to create an `Timecode` struct using the default `(_ exactly:)` initializer.
 	public func toTimecode(at frameRate: Timecode.FrameRate,
@@ -69,14 +72,14 @@ extension TimeValue {
 
 		if let sfd = subFramesDivisor {
 
-			return Timecode(self,
+			return Timecode(realTimeValue: self,
 							at: frameRate,
 							limit: limit,
 							subFramesDivisor: sfd)
 
 		} else {
 
-			return Timecode(self,
+			return Timecode(realTimeValue: self,
 							at: frameRate,
 							limit: limit)
 

Sources/TimecodeKit/Data Interchange/Timecode String.swift

@@ -72,24 +72,23 @@ extension Timecode {
 	/// Forms `.stringValue` using filename-compatible characters.
 	public var stringValueFileNameCompatible: String {
 
-		let result = stringValue
+		stringValue
 			.replacingOccurrences(of: ":", with: "-")
 			.replacingOccurrences(of: ";", with: "-")
 			.replacingOccurrences(of: " ", with: "-")
 
-		return result
-		
 	}
 
 	// MARK: stringValueValidated
 
 	/// Returns `stringValue` as `NSAttributedString`, highlighting invalid values.
 	///
 	/// `invalidAttributes` are the `NSAttributedString` attributes applied to invalid values.
-	/// If `invalidAttributes` are not passed, the default of red forground color is used.
-	public func stringValueValidated(invalidAttributes: [NSAttributedString.Key : Any]? = nil,
-									 withDefaultAttributes attrs: [NSAttributedString.Key : Any]? = nil) -> NSAttributedString
-	{
+	/// If `invalidAttributes` are not passed, the default of red foreground color is used.
+	public func stringValueValidated(
+		invalidAttributes: [NSAttributedString.Key : Any]? = nil,
+		withDefaultAttributes attrs: [NSAttributedString.Key : Any]? = nil
+	) -> NSAttributedString{
 
 		let sepDays = NSAttributedString(string: " ", attributes: attrs)
 		let sepMain = NSAttributedString(string: ":", attributes: attrs)

Sources/TimecodeKit/Delta/Delta.swift

@@ -0,0 +1,115 @@
+//
+//  Delta.swift
+//  TimecodeKit
+//
+//  Created by Steffan Andrews on 2021-04-23.
+//  Copyright © 2021 Steffan Andrews. All rights reserved.
+//
+
+import Foundation
+
+extension Timecode {
+	
+	/// Represents an abstract delta between two `Timecode` structs.
+	public struct Delta {
+		
+		@usableFromInline let delta: Timecode
+		@usableFromInline let sign: Sign
+		
+		@inlinable public init(_ delta: Timecode,
+					_ sign: Sign = .positive) {
+			
+			self.delta = delta
+			self.sign = sign
+			
+		}
+		
+		/// Returns true if sign is negative.
+		@inlinable public var isNegative: Bool {
+			
+			sign == .negative
+			
+		}
+		
+		/// Returns the delta value expressed as a concrete `Timecode` value by wrapping around lower/upper timecode limit bounds if necessary.
+		@inlinable public var timecode: Timecode {
+			
+			switch sign {
+			case .positive:
+				return delta.adding(wrapping: TCC())
+				
+			case .negative:
+				return
+					Timecode(
+						TCC(f: 0),
+						at: delta.frameRate,
+						limit: delta.upperLimit,
+						subFramesDivisor: delta.subFramesDivisor
+					)!
+					.subtracting(wrapping: delta.components)
+			}
+			
+		}
+		
+		/// Returns a `Timecode` value offsetting it by the delta value, wrapping around lower/upper timecode limit bounds if necessary.
+		@inlinable public func timecode(offsetting base: Timecode) -> Timecode {
+			
+			base + timecode
+			
+		}
+		
+		/// Returns real-time (wall-clock time) equivalent of the delta time.
+		@inline(__always) public var realTimeValue: TimeInterval {
+			
+			switch sign {
+			case .positive:
+				return delta.realTimeValue
+				
+			case .negative:
+				return -delta.realTimeValue
+			}
+			
+		}
+		
+	}
+	
+}
+
+extension Timecode.Delta: CustomStringConvertible, CustomDebugStringConvertible {
+	
+	public var description: String {
+		
+		switch sign {
+		case .positive: return delta.description
+		case .negative: return "-\(delta.description)"
+		}
+		
+	}
+	
+	public var debugDescription: String {
+		
+		switch sign {
+		case .positive: return "Timecode.Delta(\(delta.description))"
+		case .negative: return "Timecode.Delta(-\(delta.description))"
+		}
+		
+	}
+	
+	public var verboseDescription: String {
+		
+		"Timecode Delta \(description) @ \(delta.frameRate.stringValue)"
+		
+	}
+	
+}
+
+extension Timecode.Delta {
+	
+	public enum Sign {
+		
+		case positive
+		case negative
+		
+	}
+	
+}

Sources/TimecodeKit/Math/Timecode Math Internal.swift

@@ -288,5 +288,56 @@ extension Timecode {
 							   subFramesDivisor: subFramesDivisor)
 
 	}
+	
+	
+	// MARK: - Offset / Delta
+	
+	/// Utility function to return a Delta duration.
+	@usableFromInline
+	internal func __offset(to other: Components) -> Delta {
+		
+		if self.components == other {
+			return .init(TCC().toTimecode(rawValuesAt: frameRate,
+										  limit: upperLimit,
+										  subFramesDivisor: subFramesDivisor),
+						 .positive)
+		}
+		
+		let otherTimecode = Timecode(rawValues: other,
+									 at: frameRate,
+									 limit: ._100days,
+									 subFramesDivisor: subFramesDivisor)
+		
+		if otherTimecode > self {
+			
+			let diff = otherTimecode
+				.__subtract(wrapping: components,
+							from: otherTimecode.components)
+			
+			let deltaTC = diff.toTimecode(rawValuesAt: frameRate,
+										  limit: upperLimit,
+										  subFramesDivisor: subFramesDivisor)
+			
+			let delta = Delta(deltaTC, .positive)
+			
+			return delta
+			
+		} else /* other < self */ {
+			
+			let diff = otherTimecode
+				.__subtract(wrapping: other,
+							from: components)
+			
+			let deltaTC = diff.toTimecode(rawValuesAt: frameRate,
+										  limit: upperLimit,
+										  subFramesDivisor: subFramesDivisor)
+			
+			let delta = Delta(deltaTC, .negative)
+			
+			return delta
+			
+		}
+		
+	}
 
 }