lintel::datetime Namespace Reference

Typedefs
using	SystemTime = std::chrono::sys_time< std::chrono::microseconds >

Functions
std::time_t	timegmPortable (std::tm *tm) noexcept
long	localOffsetSeconds (std::time_t time, const std::tm &local) noexcept
bool	isEastOfUtc (long offsetSeconds) noexcept
std::string	formatOffset (long offsetSeconds)
std::string	formatSystemTime (const SystemTime &value, char dateSeparator='-')
SystemTime	parseSystemTime (const std::string &value)
std::string	formatUtcIsoSeconds (const std::chrono::sys_seconds &value)

Detailed Description

Portable, locale-independent timestamp formatting/parsing.

The library used to rely on the C++20 chrono integrations of <format> (std::format("{:%Y-%m-%d %H:%M:%S%Ez}", sys_time<microseconds>)) and of the stream extraction operator (std::chrono::parse(...)). Both landed in libc++ only recently (chrono formatting in LLVM 21) and are still incomplete in AppleClang's libc++, so they are not portable to macOS. libstdc++ and MSVC support them, but with platform-specific corner cases (e.g. the decimal separator of the active locale). These helpers replace both with a small, self-contained implementation that produces the same wire format on every platform and target:

"2021-09-08 17:04:49.580723+02:00"

i.e. local time with microsecond resolution and a "+HH:MM" UTC offset. The offset variants "±HH", "±HHMM" and "±HH:MM" are all accepted when parsing, matching what PostgreSQL/SQLite store in the seed data.

Typedef Documentation

SystemTime

using lintel::datetime::SystemTime = typedef std::chrono::sys_time<std::chrono::microseconds>

Timestamp type used across the persistence layer.

Function Documentation

formatOffset()

std::string lintel::datetime::formatOffset ( long  offsetSeconds )

inline

Parameters

offsetSeconds

offset from UTC in seconds

Returns

offset formatted as "+HH:MM"/"-HH:MM"

formatSystemTime()

std::string lintel::datetime::formatSystemTime ( const SystemTime &  value, char  dateSeparator = '-'  )

inline

Format a timestamp the way the persistence layer stores it: local time, microsecond resolution, "+HH:MM" offset.

Parameters

value	the timestamp (microsecond resolution)
dateSeparator	separator used between the date components ('-' in the database, '.' in the human-readable user dump)

Returns

the formatted timestamp, or an empty string when the time cannot be converted

formatUtcIsoSeconds()

std::string lintel::datetime::formatUtcIsoSeconds ( const std::chrono::sys_seconds &  value )

inline

Format a UTC timestamp as ISO-8601 with a second resolution and a "Z" suffix (the "{:%FT%TZ}" form used by the CLI prompt).

Parameters

value

the timestamp

Returns

e.g. "2026-10-16T07:49:08Z", or an empty string on failure

isEastOfUtc()

bool lintel::datetime::isEastOfUtc ( long  offsetSeconds )

inlinenoexcept

Parameters

offsetSeconds

offset from UTC in seconds

Returns

true when east of UTC

localOffsetSeconds()

long lintel::datetime::localOffsetSeconds ( std::time_t  time, const std::tm &  local  )

inlinenoexcept

Parameters

time	a point in time
local	its local-time representation (from lintel::localTime)

Returns

the local offset from UTC in seconds (east positive)

parseSystemTime()

SystemTime lintel::datetime::parseSystemTime ( const std::string &  value )

inline

Parse a timestamp produced by formatSystemTime (or by PostgreSQL/SQLite). Accepts "YYYY-MM-DD HH:MM:SS[.ffffff]" followed by a required UTC offset in one of the forms "Z", "+HH", "-HH", "+HHMM", "+HH:MM".

Parameters

value

the string to parse

Returns

the parsed timestamp, or a default-constructed (epoch) value when the string cannot be parsed - mirroring std::chrono::parse's behaviour

timegmPortable()

std::time_t lintel::datetime::timegmPortable ( std::tm *  tm )

inlinenoexcept

timegm() is POSIX, _mkgmtime() is MSVC; both interpret a std::tm as UTC.

Parameters

tm	broken-down UTC time (modified in place)

Returns

the corresponding time_t