datetime Class Reference

Utilities for date and time operations. More...

#include <datetime.hpp>

Collaboration diagram for datetime:

Static Public Member Functions
static std::string	to_iso8601_utc (const std::chrono::system_clock::time_point &tp)
	Serialises a time point to ISO 8601 UTC string with 'Z' suffix.
static std::chrono::system_clock::time_point	from_iso8601_utc (const std::string &str)
	Parses an ISO 8601 UTC string to a time point.
static std::string	to_db_string (const std::chrono::system_clock::time_point &tp)
	Formats a time point as a UTC database timestamp string.
static std::string	to_local_display_string (const std::chrono::system_clock::time_point &tp, const std::string &format=k_timestamp_format)
	Formats a time point as a human-readable local-time string.

Detailed Description

Utilities for date and time operations.

Policy: all timestamps are stored and transmitted in UTC. Local time is used only for display. The canonical wire/storage format is ISO 8601 with a 'Z' suffix: "YYYY-MM-DD HH:MM:SSZ".

Member Function Documentation

to_iso8601_utc()

std::string to_iso8601_utc ( const std::chrono::system_clock::time_point &  tp )

static

Serialises a time point to ISO 8601 UTC string with 'Z' suffix.

Output format: "YYYY-MM-DD HH:MM:SSZ" Use this for all wire protocol and database writes.

Parameters

tp	Time point to format (treated as UTC per C++20 definition).

Returns

ISO 8601 UTC string, always ending with 'Z'.

Examples

/home/runner/work/OreStudio/OreStudio/projects/ores.database/include/ores.database/repository/mapper_helpers.hpp.

Here is the caller graph for this function:

from_iso8601_utc()

std::chrono::system_clock::time_point from_iso8601_utc ( const std::string &  str )

static

Parses an ISO 8601 UTC string to a time point.

Accepted UTC designators: 'Z', '+00', '+00:00'. Throws std::invalid_argument if the designator is absent or the offset is non-zero — callers must not pass ambiguous local-time strings.

Parameters

str	String to parse. Must include a UTC designator.

Returns

Parsed time point.

Exceptions

std::invalid_argument

if the string cannot be parsed or has no UTC designator.

Examples

/home/runner/work/OreStudio/OreStudio/projects/ores.database/include/ores.database/repository/mapper_helpers.hpp.

Here is the caller graph for this function:

to_db_string()

std::string to_db_string ( const std::chrono::system_clock::time_point &  tp )

static

Formats a time point as a UTC database timestamp string.

Output format: "YYYY-MM-DD HH:MM:SS" (no timezone suffix). Use this for embedding timestamps directly in raw SQL statements. Produces the same format as PostgreSQL returns for TIMESTAMPTZ columns when the session timezone is UTC.

Parameters

tp	Time point to format (treated as UTC per C++20 definition).

Returns

UTC timestamp string without timezone designator.

Here is the caller graph for this function:

to_local_display_string()

std::string to_local_display_string ( const std::chrono::system_clock::time_point &  tp, const std::string &  format = k_timestamp_format  )

static

Formats a time point as a human-readable local-time string.

Intended for display only (UI, CLI output). Do NOT use for wire protocol or database writes — use to_iso8601_utc() instead.

Parameters

tp	Time point to format.
format	strftime format string (default: k_timestamp_format).

Returns

Local-time string without timezone designator.