@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/AVFoundation/CMTime.swift

@@ -0,0 +1,303 @@
+// Core Media's time types, which `import AVFoundation` brings along on Apple
+// platforms (no app the shim has met imports CoreMedia by name, so they live
+// here). A `CMTime` is a rational number of seconds, `value / timescale`, with
+// flags for the values that are not numbers (invalid, indefinite, the two
+// infinities), as in Core Media: times compare and hash by the number they
+// stand for (1/2 == 2/4), sums of different timescales use their least common
+// multiple (or the larger timescale, rounded, when that overflows), and an
+// invalid operand gives an invalid result.
+
+import Foundation
+
+public typealias CMTimeValue = Int64
+public typealias CMTimeScale = Int32
+public typealias CMTimeEpoch = Int64
+
+public struct CMTimeFlags: OptionSet, Hashable, Sendable, Codable {
+    public let rawValue: UInt32
+    public init(rawValue: UInt32) { self.rawValue = rawValue }
+    public static let valid = CMTimeFlags(rawValue: 1)
+    public static let hasBeenRounded = CMTimeFlags(rawValue: 2)
+    public static let positiveInfinity = CMTimeFlags(rawValue: 4)
+    public static let negativeInfinity = CMTimeFlags(rawValue: 8)
+    public static let indefinite = CMTimeFlags(rawValue: 16)
+    public static let impliedValueFlagsMask: CMTimeFlags = [.positiveInfinity, .negativeInfinity, .indefinite]
+}
+
+/// How a conversion to another timescale rounds.
+public enum CMTimeRoundingMethod: UInt32, Sendable {
+    case roundHalfAwayFromZero = 1, roundTowardZero, roundAwayFromZero, quickTime, roundTowardPositiveInfinity, roundTowardNegativeInfinity
+    public static let `default` = CMTimeRoundingMethod.roundHalfAwayFromZero
+}
+
+public struct CMTime: Sendable, Codable, CustomStringConvertible {
+    public var value: CMTimeValue
+    public var timescale: CMTimeScale
+    public var flags: CMTimeFlags
+    public var epoch: CMTimeEpoch
+
+    public init(value: CMTimeValue, timescale: CMTimeScale, flags: CMTimeFlags, epoch: CMTimeEpoch) {
+        self.value = value
+        self.timescale = timescale
+        self.flags = flags
+        self.epoch = epoch
+    }
+
+    /// `value / timescale` seconds; a timescale of 0 or less is invalid.
+    public init(value: CMTimeValue, timescale: CMTimeScale) {
+        self.init(value: value, timescale: timescale, flags: timescale > 0 ? .valid : [], epoch: 0)
+    }
+
+    /// `seconds` rounded to the nearest `1 / preferredTimescale`; a NaN is
+    /// invalid and an infinity is that infinity.
+    public init(seconds: Double, preferredTimescale: CMTimeScale) {
+        if seconds.isNaN || preferredTimescale <= 0 {
+            self = .invalid
+        } else if seconds.isInfinite {
+            self = seconds > 0 ? .positiveInfinity : .negativeInfinity
+        } else {
+            let scaled = seconds * Double(preferredTimescale)
+            let rounded = scaled.rounded(.toNearestOrAwayFromZero)
+            guard abs(rounded) < 9.2e18 else {
+                self = seconds > 0 ? .positiveInfinity : .negativeInfinity
+                return
+            }
+            var flags: CMTimeFlags = .valid
+            if rounded != scaled { flags.insert(.hasBeenRounded) }
+            self.init(value: CMTimeValue(rounded), timescale: preferredTimescale, flags: flags, epoch: 0)
+        }
+    }
+
+    public static let zero = CMTime(value: 0, timescale: 1)
+    public static let invalid = CMTime(value: 0, timescale: 0, flags: [], epoch: 0)
+    public static let indefinite = CMTime(value: 0, timescale: 0, flags: [.valid, .indefinite], epoch: 0)
+    public static let positiveInfinity = CMTime(value: 0, timescale: 0, flags: [.valid, .positiveInfinity], epoch: 0)
+    public static let negativeInfinity = CMTime(value: 0, timescale: 0, flags: [.valid, .negativeInfinity], epoch: 0)
+
+    public var isValid: Bool { flags.contains(.valid) }
+    public var isIndefinite: Bool { isValid && flags.contains(.indefinite) }
+    public var isPositiveInfinity: Bool { isValid && flags.contains(.positiveInfinity) }
+    public var isNegativeInfinity: Bool { isValid && flags.contains(.negativeInfinity) }
+    /// A finite number of seconds: valid, and neither indefinite nor infinite.
+    public var isNumeric: Bool { isValid && flags.isDisjoint(with: .impliedValueFlagsMask) }
+    public var hasBeenRounded: Bool { isNumeric && flags.contains(.hasBeenRounded) }
+
+    /// The time in seconds: NaN when invalid or indefinite, ±infinity for the infinities.
+    public var seconds: Double {
+        if isPositiveInfinity { return .infinity }
+        if isNegativeInfinity { return -.infinity }
+        guard isNumeric else { return .nan }
+        return Double(value) / Double(timescale)
+    }
+
+    /// The same time in another timescale, rounded by `method`.
+    public func convertScale(_ newTimescale: Int32, method: CMTimeRoundingMethod) -> CMTime {
+        guard isNumeric, newTimescale > 0 else { return newTimescale > 0 ? self : .invalid }
+        if newTimescale == timescale { return self }
+        let exact = Double(value) * Double(newTimescale) / Double(timescale)
+        let rounded: Double
+        switch method {
+        case .roundHalfAwayFromZero, .quickTime: rounded = exact.rounded(.toNearestOrAwayFromZero)
+        case .roundTowardZero: rounded = exact.rounded(.towardZero)
+        case .roundAwayFromZero: rounded = exact.rounded(.awayFromZero)
+        case .roundTowardPositiveInfinity: rounded = exact.rounded(.up)
+        case .roundTowardNegativeInfinity: rounded = exact.rounded(.down)
+        }
+        var flags = flags
+        if rounded != exact { flags.insert(.hasBeenRounded) }
+        return CMTime(value: CMTimeValue(rounded), timescale: newTimescale, flags: flags, epoch: epoch)
+    }
+
+    public var description: String {
+        if !isValid { return "CMTime(invalid)" }
+        if isIndefinite { return "CMTime(indefinite)" }
+        if isPositiveInfinity { return "CMTime(+infinity)" }
+        if isNegativeInfinity { return "CMTime(-infinity)" }
+        return "CMTime(\(value)/\(timescale) = \(seconds)s)"
+    }
+}
+
+// MARK: - Comparing
+
+extension CMTime: Comparable, Hashable {
+    /// Core Media's order: invalid times are equal to each other and greater
+    /// than everything else; then −∞ < numbers < +∞ < indefinite.
+    private var rank: Int {
+        if !isValid { return 4 }
+        if isIndefinite { return 3 }
+        if isPositiveInfinity { return 2 }
+        if isNegativeInfinity { return 0 }
+        return 1
+    }
+
+    public static func == (lhs: CMTime, rhs: CMTime) -> Bool { CMTimeCompare(lhs, rhs) == 0 }
+    public static func < (lhs: CMTime, rhs: CMTime) -> Bool { CMTimeCompare(lhs, rhs) < 0 }
+
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(rank)
+        guard rank == 1 else { return }
+        // Equal rationals hash alike: reduce the fraction.
+        let divisor = gcd(abs(value), CMTimeValue(timescale))
+        hasher.combine(value / max(divisor, 1))
+        hasher.combine(CMTimeValue(timescale) / max(divisor, 1))
+    }
+}
+
+/// −1, 0 or 1 as `time1` is less than, equal to or greater than `time2`.
+public func CMTimeCompare(_ time1: CMTime, _ time2: CMTime) -> Int32 {
+    let (a, b) = (time1, time2)
+    let rankA = rankOf(a), rankB = rankOf(b)
+    if rankA != rankB { return rankA < rankB ? -1 : 1 }
+    guard rankA == 1 else { return 0 }
+    // value1 / scale1 vs value2 / scale2, exactly where the products fit.
+    let (left, leftOverflow) = a.value.multipliedReportingOverflow(by: CMTimeValue(b.timescale))
+    let (right, rightOverflow) = b.value.multipliedReportingOverflow(by: CMTimeValue(a.timescale))
+    if !leftOverflow, !rightOverflow { return left < right ? -1 : (left > right ? 1 : 0) }
+    let x = a.seconds, y = b.seconds
+    return x < y ? -1 : (x > y ? 1 : 0)
+}
+
+private func rankOf(_ time: CMTime) -> Int {
+    if !time.isValid { return 4 }
+    if time.isIndefinite { return 3 }
+    if time.isPositiveInfinity { return 2 }
+    if time.isNegativeInfinity { return 0 }
+    return 1
+}
+
+private func gcd(_ a: CMTimeValue, _ b: CMTimeValue) -> CMTimeValue {
+    var (x, y) = (a, b)
+    while y != 0 { (x, y) = (y, x % y) }
+    return x
+}
+
+// MARK: - Arithmetic
+
+extension CMTime {
+    public static func + (lhs: CMTime, rhs: CMTime) -> CMTime { CMTimeAdd(lhs, rhs) }
+    public static func - (lhs: CMTime, rhs: CMTime) -> CMTime { CMTimeSubtract(lhs, rhs) }
+    public static func += (lhs: inout CMTime, rhs: CMTime) { lhs = lhs + rhs }
+    public static func -= (lhs: inout CMTime, rhs: CMTime) { lhs = lhs - rhs }
+    public static func * (time: CMTime, multiplier: Int32) -> CMTime { CMTimeMultiply(time, multiplier: multiplier) }
+    public static func * (multiplier: Int32, time: CMTime) -> CMTime { CMTimeMultiply(time, multiplier: multiplier) }
+    public static func * (time: CMTime, multiplier: Float64) -> CMTime { CMTimeMultiplyByFloat64(time, multiplier: multiplier) }
+    public static func * (multiplier: Float64, time: CMTime) -> CMTime { CMTimeMultiplyByFloat64(time, multiplier: multiplier) }
+    public static func *= (time: inout CMTime, multiplier: Int32) { time = time * multiplier }
+    public static func *= (time: inout CMTime, multiplier: Float64) { time = time * multiplier }
+    public static prefix func - (time: CMTime) -> CMTime {
+        if time.isPositiveInfinity { return .negativeInfinity }
+        if time.isNegativeInfinity { return .positiveInfinity }
+        guard time.isNumeric else { return time }
+        var negated = time
+        negated.value = -time.value
+        return negated
+    }
+}
+
+public func CMTimeMake(value: Int64, timescale: Int32) -> CMTime {
+    CMTime(value: value, timescale: timescale)
+}
+
+public func CMTimeMakeWithSeconds(_ seconds: Float64, preferredTimescale: Int32) -> CMTime {
+    CMTime(seconds: seconds, preferredTimescale: preferredTimescale)
+}
+
+public func CMTimeMakeWithEpoch(value: Int64, timescale: Int32, epoch: Int64) -> CMTime {
+    CMTime(value: value, timescale: timescale, flags: timescale > 0 ? .valid : [], epoch: epoch)
+}
+
+public func CMTimeGetSeconds(_ time: CMTime) -> Float64 { time.seconds }
+
+public func CMTimeConvertScale(_ time: CMTime, timescale newTimescale: Int32, method: CMTimeRoundingMethod) -> CMTime {
+    time.convertScale(newTimescale, method: method)
+}
+
+/// The sum or difference of two numeric times, in a timescale both fit
+/// (their least common multiple, or the larger one, rounded); the special
+/// values combine as Core Media's do.
+private func combine(_ lhs: CMTime, _ rhs: CMTime, subtract: Bool) -> CMTime {
+    guard lhs.isValid, rhs.isValid else { return .invalid }
+    let right = subtract ? -rhs : rhs
+    if lhs.isIndefinite || right.isIndefinite { return .indefinite }
+    if lhs.isPositiveInfinity || lhs.isNegativeInfinity || right.isPositiveInfinity || right.isNegativeInfinity {
+        let plus = lhs.isPositiveInfinity || right.isPositiveInfinity
+        let minus = lhs.isNegativeInfinity || right.isNegativeInfinity
+        if plus, minus { return .invalid }
+        return plus ? .positiveInfinity : .negativeInfinity
+    }
+    var timescale = lhs.timescale
+    if lhs.timescale != right.timescale {
+        let common = CMTimeValue(lhs.timescale) / gcd(CMTimeValue(lhs.timescale), CMTimeValue(right.timescale)) * CMTimeValue(right.timescale)
+        timescale = common <= CMTimeValue(Int32.max) ? Int32(common) : max(lhs.timescale, right.timescale)
+    }
+    let a = lhs.convertScale(timescale, method: .default)
+    let b = right.convertScale(timescale, method: .default)
+    let (sum, overflow) = a.value.addingReportingOverflow(b.value)
+    if overflow { return sum < 0 ? .positiveInfinity : .negativeInfinity }
+    var flags: CMTimeFlags = .valid
+    if a.flags.contains(.hasBeenRounded) || b.flags.contains(.hasBeenRounded) { flags.insert(.hasBeenRounded) }
+    return CMTime(value: sum, timescale: timescale, flags: flags, epoch: lhs.epoch)
+}
+
+public func CMTimeAdd(_ lhs: CMTime, _ rhs: CMTime) -> CMTime { combine(lhs, rhs, subtract: false) }
+public func CMTimeSubtract(_ lhs: CMTime, _ rhs: CMTime) -> CMTime { combine(lhs, rhs, subtract: true) }
+
+public func CMTimeMultiply(_ time: CMTime, multiplier: Int32) -> CMTime {
+    guard time.isNumeric else {
+        if multiplier < 0 { return -time }
+        return multiplier == 0 && (time.isPositiveInfinity || time.isNegativeInfinity) ? .invalid : time
+    }
+    let (product, overflow) = time.value.multipliedReportingOverflow(by: CMTimeValue(multiplier))
+    if overflow { return (time.value < 0) != (multiplier < 0) ? .negativeInfinity : .positiveInfinity }
+    var result = time
+    result.value = product
+    return result
+}
+
+public func CMTimeMultiplyByFloat64(_ time: CMTime, multiplier: Float64) -> CMTime {
+    guard time.isNumeric else { return multiplier < 0 ? -time : time }
+    return CMTime(seconds: time.seconds * multiplier, preferredTimescale: time.timescale)
+}
+
+public func CMTimeMultiplyByRatio(_ time: CMTime, multiplier: Int32, divisor: Int32) -> CMTime {
+    guard divisor != 0 else { return .invalid }
+    guard time.isNumeric else { return time }
+    return CMTime(seconds: time.seconds * Double(multiplier) / Double(divisor), preferredTimescale: time.timescale)
+}
+
+public func CMTimeMinimum(_ time1: CMTime, _ time2: CMTime) -> CMTime { time2 < time1 ? time2 : time1 }
+public func CMTimeMaximum(_ time1: CMTime, _ time2: CMTime) -> CMTime { time2 > time1 ? time2 : time1 }
+public func CMTimeAbsoluteValue(_ time: CMTime) -> CMTime { time < .zero ? -time : time }
+
+// MARK: - Ranges
+
+public struct CMTimeRange: Hashable, Sendable, Codable {
+    public var start: CMTime
+    public var duration: CMTime
+
+    public init(start: CMTime, duration: CMTime) {
+        self.start = start
+        self.duration = duration
+    }
+
+    public init(start: CMTime, end: CMTime) {
+        self.init(start: start, duration: end - start)
+    }
+
+    public static let zero = CMTimeRange(start: .zero, duration: .zero)
+    public static let invalid = CMTimeRange(start: .invalid, duration: .invalid)
+
+    public var end: CMTime { start + duration }
+    public var isValid: Bool { start.isValid && duration.isValid && !(duration < .zero) && !duration.isIndefinite }
+    public var isEmpty: Bool { isValid && duration == .zero }
+    public var isIndefinite: Bool { start.isIndefinite || duration.isIndefinite }
+
+    public func containsTime(_ time: CMTime) -> Bool { time >= start && time < end }
+    public func containsTimeRange(_ range: CMTimeRange) -> Bool { range.start >= start && range.end <= end }
+}
+
+public func CMTimeRangeMake(start: CMTime, duration: CMTime) -> CMTimeRange {
+    CMTimeRange(start: start, duration: duration)
+}
+
+public func CMTimeRangeGetEnd(_ range: CMTimeRange) -> CMTime { range.end }