Skip to content

Commit

Permalink
Timecode: Added base parameter to converted(to:) instance method
Browse files Browse the repository at this point in the history
  • Loading branch information
orchetect committed Jan 6, 2024
1 parent 06d243d commit 342092f
Showing 1 changed file with 25 additions and 9 deletions.
34 changes: 25 additions & 9 deletions Sources/TimecodeKit/Timecode/Timecode Conversion.swift
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,45 @@ extension Timecode {

/// Return a new `Timecode` object converted to a new frame rate.
///
/// - If `preservingValues` is `false` (default): entire timecode is converted based on the equivalent real time value.
/// - Warning: This conversion process may be lossy.
///
/// - If `preservingValues` is `true`: Return a new `Timecode` instance at the new frame rate preserving literal timecode values if
/// possible.
/// If any value is not expressible at the new frame rate, the entire timecode will be converted.
/// - Parameters:
/// - newFrameRate: New frame rate.
/// If the new rate is identical to the current rate, the timecode will be returned unchanged.
///
/// - Note: this process may be lossy.
/// - newSubFramesBase: New sub-frames base (optional).
///
/// If not specified, the current sub-frames base will be preserved.
///
/// - preservingValues: Preserve literal timecode component values. (Default: `false`)
///
/// When `true`, a new `Timecode` instance at the new frame rate is returned, preserving literal timecode values
/// if possible. If any values are invalid at the new frame rate, an error is thrown.
/// If any value is not expressible at the new frame rate, the entire timecode will be converted.
/// When `false`, the timecode is converted to the new frame rate based on the equivalent real time value.
///
/// - Throws: ``ValidationError``
///
/// - Returns: A new `Timecode` instance converted to the new frame rate and sub-frames base.
public func converted(
to newFrameRate: TimecodeFrameRate,
base newSubFramesBase: Timecode.SubFramesBase? = nil,
preservingValues: Bool = false
) throws -> Timecode {
// just return self if frameRate is equal
guard frameRate != newFrameRate else {
let newSubFramesBase = newSubFramesBase ?? subFramesBase

// just return self if new parameters are equal to current parameters
guard frameRate != newFrameRate ||
subFramesBase != newSubFramesBase
else {
return self
}

if preservingValues,
let newTC = try? Timecode(
.components(components),
at: newFrameRate,
base: subFramesBase,
base: newSubFramesBase,
limit: upperLimit
)
{
Expand All @@ -43,7 +59,7 @@ extension Timecode {
return try Timecode(
.realTime(seconds: realTimeValue),
at: newFrameRate,
base: subFramesBase,
base: newSubFramesBase,
limit: upperLimit
)
}
Expand Down

0 comments on commit 342092f

Please sign in to comment.