Introduce a `Timecode.Delta` object to allow abstract timecode math about timecodekit

[orchetect]

But for the meantime, short answer is keep using this:

let numeric = incoming.realTimeValue.seconds - start.realTimeValue.seconds
Log.debug(numeric) // -3.199999999999818 -- this is right

The real time domain will achieve what you want to do here. (At least until a TimecodeDelta object or some other solution can be introduced).

It's also possible to test if the float is a negative and then wrap it in fabs() to invert it to a positive float, then feed it back into a Timecode constructor to get a "negative duration" as expressed by positive timecode.

[orchetect]

Basically everything in your code snippet is behavior by design (or at least, not incorrect).

Timecode by nature is linear, and is never expressed as a negative (think of consecutive repeating 24 hour clocks). The library tries to adhere to that principle.

When determining the behaviors when using math operations around boundaries (underflowing 00:00:00:00, or overflowing 23:59:59:FF where FF is max frames) I picked sensible defaults, but they will not always make sense in every scenario.

The - operator currently uses lhs.subtracting(clamping: rhs) under the hood which clamps to lower and upper timecode bounds. Which explains why this results in 00:00:00:00:

let subtracting = incoming - start
Log.debug(subtracting) // == 00:00:00:00

The alternatives are:

• subtracting(_ exactly: ) -> Timecode?

  • This would produce nil since a negative timecode is not possible (and should not be possible)

• subtracting(wrapping: ) -> Timecode

  • This would wrap around the 24 hour timecode upper bound

    let subtracting = incoming.subtracting(wrapping: start.components)
    Log.debug(subtracting) // == 23:59:56:20
    

I could have originally made subtracting(wrapping: ) the default behavior for the - operator but that won't directly resolve your use case.

All of that said, this opens a discussion regarding delta values when it comes to timecode differentials (ie: distance between two timecodes, not producing an absolute timecode). Because of how the Timecode object is designed to be representative of real timecode, it may make sense to introduce another struct called TimecodeDelta that can be returned as the result of math operations that the consumer can then manipulate in the abstract before converting back to Timecode or real time values.

[orchetect]

Introduced Timecode.Delta in release 1.1.0: https://github.com/orchetect/TimecodeKit/releases/tag/1.1.0

[orchetect]

New usage would be as follows:

func testNegativeTimecode() {
    guard let incoming = Timecode("00:59:56:20", at: ._25),
          let start = Timecode("01:00:00:00", at: ._25) else {
        XCTFail()
        return
    }

    let delta = start.delta(to: incoming)
    Log.debug(delta.timecode)   // 23:59:56:20
    Log.debug(delta.delta)      // 00:00:03:05
    Log.debug(delta.isNegative) // true
    
    let numeric = delta.realTimeValue
    Log.debug(numeric)          // -3.20000001
}

[orchetect]

Bumped to 1.1.1 with minor fix: https://github.com/orchetect/TimecodeKit/releases/tag/1.1.1