time.h
Dates, and lengths of time, as text.
#include <sonore/time.h>- 1type
- 8other declarations
On this page
Design notes
Why this exists now
files.h reports a modification time and nothing could show it. A preset browser with a Date column, a sampler saying a file is 3:24 long, a "last used" ordering -- all of them need the same two conversions and neither was here.
Not std::chrono's formatting
std::format and <chrono>'s calendar types are C++20, and this SDK is C++17 so a generated plugin builds with whatever toolchain its author already has. What is here is the handful of formats a plugin actually shows, done once.
Thread safety, which localtime does not have
std::localtime returns a pointer to a STATIC struct. Two threads formatting a date at the same time -- a background scan filling a browser while the UI draws it -- get each other's answers, and the bug looks like a date that is occasionally somebody else's. localtime_s and localtime_r are the reentrant forms and this uses whichever the platform has.
Types 1
A moment, split up. Fields are what a human would say: month 1..12, not 0..11, because every off-by-one month bug starts with tm_mon.
Functions 8
- fn
inline int64_t currentUnixTime()Seconds since the Unix epoch, now.time.h:48 - fn
inline DateTime dateTimeFromUnix(int64_t unixSeconds, bool utc = false)time.h:69unixSecondssplit up in the user's local time zone, or in UTC withutc. A time the system cannot convert gives the default DateTime, 1970-01-01 00:00:00. Safe from any thread. - fn
inline std::string formatDate(const DateTime& when)"2026-08-23", which sorts as text in the same order it does as a date.time.h:91 - fn
inline std::string formatClockTime(const DateTime& when, bool withSeconds = false)"14:07". Seconds left off: a preset's minute is as much as anybody reads.time.h:104 - fn
inline std::string formatDateTime(const DateTime& when, bool withSeconds = false)"2026-08-23 14:07".time.h:115 - fn
inline std::string formatDuration(double seconds)A LENGTH, as a musician reads it: "3:24", or "1:02:03" past an hour.time.h:128 - fn
inline std::string formatShortDuration(double seconds)A short length, for anything under a minute: "0.35 s", "12 ms".time.h:156 - fn
inline std::string describeAge(int64_t then, int64_t now)How long ago, roughly: "just now", "12 minutes ago", "3 days ago".time.h:175