Time

Table of Contents

• Dependencies
• Features
• Status
• Description
  • SC::Time::Absolute
    • SC::Time::Absolute::parseLocal
  • SC::Time::Monotonic
    • SC::Time::Monotonic::now
  • SC::Time::Realtime
    • SC::Time::Realtime::now
  • SC::Time::Relative
  • SC::Time::HighResolutionCounter
    • SC::Time::HighResolutionCounter::snap
    • SC::Time::HighResolutionCounter::subtractApproximate
    • SC::Time::HighResolutionCounter::isLaterThanOrEqualTo
• Blog
• Roadmap
• Statistics

🟨 Time handling (relative, absolute, high resolution)

SaneCppTime.h contains classes to measure time and compute or measure time intervals.

Dependencies

• Dependencies: Foundation
• All dependencies: Foundation

Features

Class	Description
SC::Time::Absolute	Absolute time as realtime or monotonically increasing clock.
SC::Time::Monotonic	Represent monotonically increasing time (use Monotonic::now for current time)
SC::Time::Realtime	Represents a realtime clock in milliseconds since epoch (use Realtime::now for current time)
SC::Time::Relative	Interval of time represented with 64 bit double precision float.
SC::Time::HighResolutionCounter	An high resolution time counter.

Status

🟨 MVP
This library is in MVP state but it doesn't have a clear roadmap.

Description

SC::Time::Absolute

Absolute time as realtime or monotonically increasing clock.

See also

Monotonic

Realtime

SC::Time::Absolute::parseLocal

Parses local time to a Parsed structure.

Parameters

[out]

result

The Parsed structure holding current date / time

Returns

true if time has been parsed successfully
Example:

    Time::Absolute::ParseResult local;
    SC_TEST_EXPECT(Time::Realtime::now().parseLocal(local));
    SC_TEST_EXPECT(local.year > 2022);
    String result;
    (void)StringBuilder::format(result, "{} {:02}/{:02}/{} {:02}:{:02}:{:02} {}", local.getDay(), local.dayOfMonth,
                                local.getMonth(), local.year, local.hour, local.minutes, local.seconds,
                                local.isDaylightSaving ? "DAYLIGHT SAVING" : "NO DAYLIGHT SAVING");
 
    report.console.printLine(result.view());

SC::Time::Monotonic

Represent monotonically increasing time (use Monotonic::now for current time)

SC::Time::Monotonic::now

Obtain time according to monotonic clock.

SC::Time::Realtime

Represents a realtime clock in milliseconds since epoch (use Realtime::now for current time)

SC::Time::Realtime::now

Obtain time according to realtime clock.

SC::Time::Relative

Interval of time represented with 64 bit double precision float.

SC::Time::HighResolutionCounter

An high resolution time counter.

SC::Time::HighResolutionCounter::snap

Sets HighResolutionCounter to current instant
Example:

    Time::HighResolutionCounter start, end;
    start.snap();
    Thread::Sleep(100);
    end.snap();
 
    // Test all time conversion methods
    Time::Milliseconds elapsedMs = end.subtractExact(start).toMilliseconds();
    SC_TEST_EXPECT(elapsedMs < 2000_ms and elapsedMs > 0_ms);
 
    // Test nanoseconds conversion
    Time::Nanoseconds elapsedNs = end.toNanoseconds();
    SC_TEST_EXPECT(elapsedNs.ns > 800000000); // More than 800ms in ns
 
    // Test seconds conversion
    Time::Seconds elapsedSec = end.toSeconds();
    SC_TEST_EXPECT(elapsedSec.sec >= 0); // Should be roughly 1 second
 
    // Test relative time and approximate subtraction
    Time::Relative relativeTime = end.getRelative();
    SC_TEST_EXPECT(relativeTime > Time::Relative::fromSeconds(0.8));
 
    Time::Relative approxTime = end.subtractApproximate(start);
    SC_TEST_EXPECT(approxTime > Time::Relative::fromSeconds(0.05));

SC::Time::HighResolutionCounter::subtractApproximate

Subtracts another HighResolutionCounter from this one, returning an approximate Relative.

Parameters

other

The HighResolutionCounter to be subtracted

Returns

A Relative holding the time interval between the two HighResolutionCounter
Example:

    Time::HighResolutionCounter start, end;
    end = start.offsetBy(Time::Milliseconds(321));
 
    Time::Milliseconds elapsed = end.subtractExact(start).toMilliseconds();
    SC_TEST_EXPECT(elapsed == 321_ms);
 
    // Test overflow handling
    Time::Absolute maxTime(static_cast<int64_t>(INT64_MAX - 1000));
    Time::Absolute overflowed = maxTime.offsetBy(Time::Milliseconds(2000));
    SC_TEST_EXPECT(overflowed.milliseconds == INT64_MAX);
 
    // Test time normalization by adding times that cause nanosecond overflow
    Time::HighResolutionCounter counter;
    counter = counter.offsetBy(999_ms);
    // Add enough milliseconds to cause overflow from nanoseconds to seconds
    counter = counter.offsetBy(2001_ms); // This will cause nanoseconds to overflow the 1e9 limit
 
    // The total time should be 3 seconds (2001 + 999 = 3000 ms)
    Time::HighResolutionCounter base;
    Time::HighResolutionCounter normalized = counter.subtractExact(base);
    Time::Milliseconds          totalMs    = normalized.toMilliseconds();
    SC_TEST_EXPECT(totalMs == Time::Milliseconds(3000)); // Total time should be 3 seconds
    SC_TEST_EXPECT(normalized.toSeconds() == 3_sec);
 
    // Test time normalization by subtracting larger from smaller time
    Time::HighResolutionCounter smaller = base;
    smaller                             = smaller.offsetBy(100_ms); // Add 0.1 seconds
 
    Time::HighResolutionCounter larger = base;
    larger                             = larger.offsetBy(500_ms); // Add 0.5 seconds
 
    // Subtracting larger from smaller should give normalized negative time
    Time::HighResolutionCounter negDiff   = smaller.subtractExact(larger);
    Time::Milliseconds          negDiffMs = negDiff.toMilliseconds();
    SC_TEST_EXPECT(negDiffMs == Time::Milliseconds(-400)); // -0.4 seconds
 
    // While subtracting smaller from larger gives positive time
    Time::HighResolutionCounter posDiff   = larger.subtractExact(smaller);
    Time::Milliseconds          posDiffMs = posDiff.toMilliseconds();
    SC_TEST_EXPECT(posDiffMs == Time::Milliseconds(400)); // +0.4 seconds

SC::Time::HighResolutionCounter::isLaterThanOrEqualTo

Check if this HighResolutionCounter is later or equal to another HighResolutionCounter.

Parameters

other

The HighResolutionCounter to be used in the comparison

Returns

true if this HighResolutionCounter is later or equal to another HighResolutionCounter
Example:

    Time::HighResolutionCounter start;
    start.snap();
    const Time::HighResolutionCounter end = start.offsetBy(123_ms);
    SC_TEST_EXPECT(end.isLaterThanOrEqualTo(start));
    SC_TEST_EXPECT(not start.isLaterThanOrEqualTo(end));

Blog

Some relevant blog posts are:

• January 2025 Update

Roadmap

🟩 Usable

• No Plan

🟦 Complete Features:

• No Plan

💡 Unplanned Features:

• No Plan

Statistics

Type	Lines Of Code	Comments	Sum
Headers	124	136	260
Sources	219	37	256
Sum	343	173	516