API — ICoreEssentials/Time

The public contract of 2 header(s) under ICoreEssentials/Time — 2 class/struct definition(s), 29 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreDateTime.h#

ICoreEssentials/Time/ICoreDateTime.h

ICoreDateTime -- a wall-clock instant.

QT-FREE (phase 3). The member is milliseconds since the Unix epoch and this header names no Qt type; <QDate> is gone from the umbrella outright and <QDateTime> survives there only until ICorePath stops needing it (see the lastModified note below).

It passed the same test ICoreElapsedTimer did: B4 gave this wrapper NO conversion OUT, so nothing ever held a reference to the QDateTime and no signature promised it existed. The implicit constructor IN was the only pin, and it had exactly one claimant -- ICorePath::lastModified() -- which now calls fromMSecsSinceEpoch() explicitly instead.

BEHAVIOUR IS UNCHANGED on every point a call site can observe. Each was

ICoreDateTime#

ICoreDateTime.h:76 · class · pImpl · 21 declaration(s)

class ICoreDateTime {
public:
    // Default-constructs INVALID, matching QDateTime. The runner's cache
    // depends on it: a default-constructed `cachedStamp` must compare unequal
    // to any real file mtime, so the first lookup always misses and populates.
    ICoreDateTime();
    ~ICoreDateTime();

    // An instant is a value and is copied as one. Written out because a
    // unique_ptr<Impl> member deletes the implicit copy.
    ICoreDateTime(const ICoreDateTime& other);
    ICoreDateTime& operator=(const ICoreDateTime& other);

    [[nodiscard]] static ICoreDateTime currentDateTime();

    // How an instant from unmigrated Qt API becomes an ICoreDateTime. This
    // replaces B4's implicit `ICoreDateTime(const QDateTime&)`; it is explicit
    // and named because the epoch count it takes is not self-describing the way
    // a QDateTime was, and because there is exactly one caller.
    [[nodiscard]] static ICoreDateTime fromMSecsSinceEpoch(std::int64_t msecs);

    // Qt's format syntax, minus the tokens listed in the header note. An
    // invalid instant yields an empty string, as QDateTime does.
    [[nodiscard]] ICoreString toString(const ICoreString& format) const;

    // True when this instant falls on today's LOCAL date. Invalid is never
    // today, matching `QDateTime().date() == QDate::currentDate()`.
    [[nodiscard]] bool isToday() const;

    [[nodiscard]] bool isValid() const noexcept;

    // Hidden friends rather than free functions: they need the epoch count,
    // and there is no call site for a public toMSecsSinceEpoch() to justify
    // adding one (Rule 3). Declared here so ADL finds them, DEFINED in the
    // .cpp.
    //
    // Equality only. The call site is a cache-invalidation check ("has this
    // file's mtime changed"), which needs no ordering; QDateTime's relational
    // operators have no call site in this project and so are not forwarded.
    friend bool operator==(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;
    friend bool operator!=(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;

    // ---- The platform SDK's completion (PS5.13, 2026-09-24) -----------------
    // Everything below is additive and non-virtual. Instants are UTC
    // milliseconds since the Unix epoch; only toString() above, isToday() and
    // localOffsetSeconds() consult the local time zone.

    [[nodiscard]] static ICoreDateTime fromSecsSinceEpoch(std::int64_t secs);

    // A UTC calendar instant. Invalid when a field is out of range (month
    // 1..12, day within the month, hour 0..23, minute 0..59, second 0..59,
    // millisecond 0..999) -- 2026-02-29 is invalid, 2028-02-29 is not.
    [[nodiscard]] static ICoreDateTime fromUtc(int year, int month, int day);
    [[nodiscard]] static ICoreDateTime fromUtc(int year, int month, int day,
                                               int hour, int minute, int second, int millisecond);

    // ISO 8601 / RFC 3339: "2026-09-24", "2026-09-24T17:05", "2026-09-24T17:05:09",
    // with an optional fraction of a second (any number of digits, truncated to
    // milliseconds) and an optional zone: "Z", "+02:00", "+0200" or "+02".
    // 'T', 't' or a space separates date and time. A string with NO zone is read
    // as UTC. Anything else gives an invalid instant.
    [[nodiscard]] static ICoreDateTime fromIso8601(std::string_view text);

    // "2026-09-24T17:05:09.120Z" -- always UTC, always milliseconds. Empty for
    // an invalid instant.
    [[nodiscard]] std::string toIso8601() const;

    // toString()'s tokens, rendered in UTC rather than local time.
    [[nodiscard]] ICoreString toUtcString(const ICoreString& format) const;

    // 0 for an invalid instant.
    [[nodiscard]] std::int64_t toMSecsSinceEpoch() const noexcept;
    [[nodiscard]] std::int64_t toSecsSinceEpoch() const noexcept;

    // Shifted copies; an invalid instant stays invalid. addDays adds exact
    // 24-hour days, so across a daylight-saving change the LOCAL clock time
    // moves by an hour.
    [[nodiscard]] ICoreDateTime addMSecs(std::int64_t msecs) const;
    [[nodiscard]] ICoreDateTime addSecs(std::int64_t secs) const;
    [[nodiscard]] ICoreDateTime addDays(std::int64_t days) const;

    // other - this, in milliseconds; 0 when either is invalid.
    [[nodiscard]] std::int64_t msecsTo(const ICoreDateTime& other) const noexcept;

    // The local zone's offset from UTC at this instant, in seconds east of
    // Greenwich (+3600 for Paris in winter). 0 for an invalid instant.
    [[nodiscard]] int localOffsetSeconds() const;

    // Chronological order. An invalid instant sorts before every valid one,
    // and two invalid instants are equal, matching == above.
    friend bool operator<(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;
    friend bool operator<=(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;
    friend bool operator>(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;
    friend bool operator>=(const ICoreDateTime& a, const ICoreDateTime& b) noexcept;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreElapsedTimer.h#

ICoreEssentials/Time/ICoreElapsedTimer.h

ICoreElapsedTimer#

ICoreElapsedTimer.h:66 · class · pImpl · 8 declaration(s)

ICoreElapsedTimer -- a monotonic stopwatch.

class ICoreElapsedTimer {
public:
    ICoreElapsedTimer();
    ~ICoreElapsedTimer();

    ICoreElapsedTimer(const ICoreElapsedTimer& other);
    ICoreElapsedTimer& operator=(const ICoreElapsedTimer& other);

    void start() noexcept;
    void restart() noexcept;

    [[nodiscard]] std::int64_t elapsed() const noexcept;
    [[nodiscard]] bool isValid() const noexcept;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};