Stores a target local-time context backed by a named zone or fixed UTC offset. More...

#include <ZonedClock.hpp>

Public Member Functions
	ZonedClock () noexcept
	Construct UTC fixed-offset clock without NTP.

	ZonedClock (TimeZone zone, bool use_ntp=false) noexcept
	Construct clock for a named zone.

	ZonedClock (tz_t utc_offset, bool use_ntp=false)
	Construct clock for a fixed UTC offset.

void	set_zone (TimeZone zone) noexcept
	Set the stored named zone.

bool	try_set_offset (tz_t utc_offset) noexcept
	Set the stored fixed UTC offset.

bool	try_set_zone (const std::string &zone_spec) noexcept
	Parse and set a named zone or numeric offset from string.

void	set_use_ntp (bool use_ntp) noexcept
	Set preferred UTC source.

bool	has_named_zone () const noexcept
	Return true when the instance stores a named zone.

TimeZone	zone () const noexcept
	Return stored named zone or `UNKNOWN` for fixed-offset mode.

bool	use_ntp () const noexcept
	Return the preferred UTC source flag.

bool	ntp_active () const noexcept
	Return true when the global NTP service is active for this clock.

tz_t	offset_now () const noexcept
	Return effective UTC offset in seconds for the current UTC instant.

tz_t	offset_at_utc_ms (ts_ms_t utc_ms) const noexcept
	Return effective UTC offset in seconds for a specific UTC instant.

bool	try_offset_at_utc_ms (ts_ms_t utc_ms, tz_t &out) const noexcept
	Try to resolve effective UTC offset for a UTC instant.

LocalTimeResolution	resolve_local_time_ms (ts_ms_t local_ms) const noexcept
	Resolve a local timestamp in this clock's zone.

ts_ms_t	to_utc_ms (ts_ms_t local_ms, AmbiguousTimePolicy ambiguous_policy=AmbiguousTimePolicy::error, NonexistentTimePolicy nonexistent_policy=NonexistentTimePolicy::error) const noexcept
	Convert a local timestamp in this clock's zone to UTC.

ts_t	utc_time_sec () const noexcept
	Return current UTC time in seconds.

ts_ms_t	utc_time_ms () const noexcept
	Return current UTC time in milliseconds.

ts_us_t	utc_time_us () const noexcept
	Return current UTC time in microseconds.

ts_t	local_time_sec () const noexcept
	Return current local timestamp in seconds.

ts_ms_t	local_time_ms () const noexcept
	Return current local timestamp in milliseconds.

ts_us_t	local_time_us () const noexcept
	Return current local timestamp in microseconds.

DateTime	now () const noexcept
	Return current time snapshot with resolved fixed offset.

DateTime	from_utc_ms (ts_ms_t utc_ms) const noexcept
	Return a snapshot for a specific UTC instant in milliseconds.

DateTime	from_utc_s (ts_t utc_s) const noexcept
	Return a snapshot for a specific UTC instant in seconds.

std::string	zone_name () const
	Return short name of the stored named zone.

std::string	zone_full_name () const
	Return human-readable zone label.

std::string	offset_string () const
	Return effective numeric UTC offset as `+HH:MM` or `-HH:MM`.

std::string	to_iso8601 () const
	Return current local time formatted as ISO8601 with offset.

std::string	to_iso8601_utc () const
	Return current UTC time formatted as ISO8601 with `Z`.

std::string	format (const std::string &fmt) const
	Format current local time using the custom formatter grammar.

Static Public Member Functions
static bool	try_from_offset (tz_t utc_offset, ZonedClock &out) noexcept
	Try to build fixed-offset clock without throwing.

Private Member Functions
ts_ms_t	current_utc_ms () const noexcept

ts_us_t	current_utc_us () const noexcept

Static Private Member Functions
static std::string	trim_ascii (const std::string &value)

static bool	is_ascii_space (char ch) noexcept

static std::string	offset_string_for_offset (tz_t utc_offset)

Private Attributes
TimeZone	m_zone

tz_t	m_offset

bool	m_is_named_zone

bool	m_use_ntp

Detailed Description

Stores a target local-time context backed by a named zone or fixed UTC offset.

Class resolves the effective offset on demand. Named zones are recalculated for the requested UTC instant, while numeric offsets remain fixed. Current UTC time can come from the local realtime clock or from the global NTP service.

Definition at line 30 of file ZonedClock.hpp.

Constructor & Destructor Documentation

◆ ZonedClock() [1/3]

time_shield::ZonedClock::ZonedClock ( )

inlinenoexcept

Construct UTC fixed-offset clock without NTP.

Definition at line 33 of file ZonedClock.hpp.

◆ ZonedClock() [2/3]

time_shield::ZonedClock::ZonedClock	(	TimeZone	zone,
		bool	use_ntp = false )

inlineexplicitnoexcept

Construct clock for a named zone.

Parameters

zone	Supported named zone.
use_ntp	Use NTP-backed UTC time when true.

Definition at line 42 of file ZonedClock.hpp.

◆ ZonedClock() [3/3]

time_shield::ZonedClock::ZonedClock	(	tz_t	utc_offset,
		bool	use_ntp = false )

inlineexplicit

Construct clock for a fixed UTC offset.

Parameters

utc_offset	Fixed UTC offset in seconds.
use_ntp	Use NTP-backed UTC time when true.

Exceptions

std::invalid_argument if utc_offset is outside the supported range.

Definition at line 54 of file ZonedClock.hpp.

Member Function Documentation

◆ current_utc_ms()

ts_ms_t time_shield::ZonedClock::current_utc_ms ( ) const

inlineprivatenoexcept

Definition at line 344 of file ZonedClock.hpp.

◆ current_utc_us()

ts_us_t time_shield::ZonedClock::current_utc_us ( ) const

inlineprivatenoexcept

Definition at line 348 of file ZonedClock.hpp.

◆ format()

std::string time_shield::ZonedClock::format ( const std::string & fmt ) const

inline

Format current local time using the custom formatter grammar.

Parameters

fmt	Formatting pattern.

Returns: Formatted string.

Definition at line 319 of file ZonedClock.hpp.

◆ from_utc_ms()

DateTime time_shield::ZonedClock::from_utc_ms ( ts_ms_t utc_ms ) const

inlinenoexcept

Return a snapshot for a specific UTC instant in milliseconds.

Parameters

utc_ms UTC timestamp in milliseconds.

Returns: DateTime snapshot with resolved fixed offset.

Definition at line 275 of file ZonedClock.hpp.

◆ from_utc_s()

DateTime time_shield::ZonedClock::from_utc_s ( ts_t utc_s ) const

inlinenoexcept

Return a snapshot for a specific UTC instant in seconds.

Parameters

utc_s UTC timestamp in seconds.

Returns: DateTime snapshot with resolved fixed offset.

Definition at line 282 of file ZonedClock.hpp.

◆ has_named_zone()

bool time_shield::ZonedClock::has_named_zone ( ) const

inlinenoexcept

Return true when the instance stores a named zone.

Definition at line 136 of file ZonedClock.hpp.

◆ is_ascii_space()

static bool time_shield::ZonedClock::is_ascii_space ( char ch )

inlinestaticprivatenoexcept

Definition at line 336 of file ZonedClock.hpp.

◆ local_time_ms()

ts_ms_t time_shield::ZonedClock::local_time_ms ( ) const

inlinenoexcept

Return current local timestamp in milliseconds.

Definition at line 256 of file ZonedClock.hpp.

◆ local_time_sec()

ts_t time_shield::ZonedClock::local_time_sec ( ) const

inlinenoexcept

Return current local timestamp in seconds.

Definition at line 250 of file ZonedClock.hpp.

◆ local_time_us()

ts_us_t time_shield::ZonedClock::local_time_us ( ) const

inlinenoexcept

Return current local timestamp in microseconds.

Definition at line 262 of file ZonedClock.hpp.

◆ now()

DateTime time_shield::ZonedClock::now ( ) const

inlinenoexcept

Return current time snapshot with resolved fixed offset.

Definition at line 268 of file ZonedClock.hpp.

◆ ntp_active()

bool time_shield::ZonedClock::ntp_active ( ) const

inlinenoexcept

Return true when the global NTP service is active for this clock.

Definition at line 151 of file ZonedClock.hpp.

◆ offset_at_utc_ms()

tz_t time_shield::ZonedClock::offset_at_utc_ms ( ts_ms_t utc_ms ) const

inlinenoexcept

Return effective UTC offset in seconds for a specific UTC instant.

Parameters

utc_ms UTC timestamp in milliseconds.

Returns: Effective UTC offset in seconds.

Definition at line 167 of file ZonedClock.hpp.

◆ offset_now()

tz_t time_shield::ZonedClock::offset_now ( ) const

inlinenoexcept

Return effective UTC offset in seconds for the current UTC instant.

Definition at line 160 of file ZonedClock.hpp.

◆ offset_string()

std::string time_shield::ZonedClock::offset_string ( ) const

inline

Return effective numeric UTC offset as +HH:MM or -HH:MM.

Definition at line 302 of file ZonedClock.hpp.

◆ offset_string_for_offset()

static std::string time_shield::ZonedClock::offset_string_for_offset ( tz_t utc_offset )

inlinestaticprivate

Definition at line 340 of file ZonedClock.hpp.

◆ resolve_local_time_ms()

LocalTimeResolution time_shield::ZonedClock::resolve_local_time_ms ( ts_ms_t local_ms ) const

inlinenoexcept

Resolve a local timestamp in this clock's zone.

Parameters

local_ms Local civil timestamp in milliseconds.

Returns: Local-time resolution with zero, one, or two UTC candidates.

Definition at line 192 of file ZonedClock.hpp.

◆ set_use_ntp()

void time_shield::ZonedClock::set_use_ntp ( bool use_ntp )

inlinenoexcept

Set preferred UTC source.

Parameters

use_ntp Use NTP-backed UTC time when true.

Definition at line 131 of file ZonedClock.hpp.

◆ set_zone()

void time_shield::ZonedClock::set_zone ( TimeZone zone )

inlinenoexcept

Set the stored named zone.

Parameters

zone	Supported named zone. `UNKNOWN` resets the instance to fixed UTC offset `+00:00`.

Definition at line 79 of file ZonedClock.hpp.

◆ to_iso8601()

std::string time_shield::ZonedClock::to_iso8601 ( ) const

inline

Return current local time formatted as ISO8601 with offset.

Definition at line 307 of file ZonedClock.hpp.

◆ to_iso8601_utc()

std::string time_shield::ZonedClock::to_iso8601_utc ( ) const

inline

Return current UTC time formatted as ISO8601 with Z.

Definition at line 312 of file ZonedClock.hpp.

◆ to_utc_ms()

ts_ms_t time_shield::ZonedClock::to_utc_ms	(	ts_ms_t	local_ms,
		AmbiguousTimePolicy	ambiguous_policy = AmbiguousTimePolicy::error,
		NonexistentTimePolicy	nonexistent_policy = NonexistentTimePolicy::error ) const

inlinenoexcept

Convert a local timestamp in this clock's zone to UTC.

Parameters

local_ms	Local civil timestamp in milliseconds.
ambiguous_policy	Policy for DST-fold local times.
nonexistent_policy	Policy for DST-gap local times.

Returns: UTC timestamp in milliseconds, or ERROR_TIMESTAMP.

Definition at line 219 of file ZonedClock.hpp.

◆ trim_ascii()

static std::string time_shield::ZonedClock::trim_ascii ( const std::string & value )

inlinestaticprivate

Definition at line 324 of file ZonedClock.hpp.

◆ try_from_offset()

static bool time_shield::ZonedClock::try_from_offset	(	tz_t	utc_offset,
		ZonedClock &	out )

inlinestaticnoexcept

Try to build fixed-offset clock without throwing.

Parameters

utc_offset	Fixed UTC offset in seconds.
out	Output clock on success.

Returns: True when the offset is valid and out is updated.

Definition at line 68 of file ZonedClock.hpp.

◆ try_offset_at_utc_ms()

bool time_shield::ZonedClock::try_offset_at_utc_ms	(	ts_ms_t	utc_ms,
		tz_t &	out ) const

inlinenoexcept

Try to resolve effective UTC offset for a UTC instant.

Parameters

utc_ms	UTC timestamp in milliseconds.
out	Receives offset in seconds on success.

Returns: True when the offset can be resolved.

Definition at line 176 of file ZonedClock.hpp.

◆ try_set_offset()

bool time_shield::ZonedClock::try_set_offset ( tz_t utc_offset )

inlinenoexcept

Set the stored fixed UTC offset.

Parameters

utc_offset Fixed UTC offset in seconds.

Returns: True when the offset is valid.

Definition at line 95 of file ZonedClock.hpp.

◆ try_set_zone()

bool time_shield::ZonedClock::try_set_zone ( const std::string & zone_spec )

inlinenoexcept

Parse and set a named zone or numeric offset from string.

Parameters

zone_spec Input string with ASCII trimming applied before parsing.

Returns: True when parsing succeeds.

Definition at line 109 of file ZonedClock.hpp.

◆ use_ntp()

bool time_shield::ZonedClock::use_ntp ( ) const

inlinenoexcept

Return the preferred UTC source flag.

Definition at line 146 of file ZonedClock.hpp.

◆ utc_time_ms()

ts_ms_t time_shield::ZonedClock::utc_time_ms ( ) const

inlinenoexcept

Return current UTC time in milliseconds.

Definition at line 240 of file ZonedClock.hpp.

◆ utc_time_sec()

ts_t time_shield::ZonedClock::utc_time_sec ( ) const

inlinenoexcept

Return current UTC time in seconds.

Definition at line 235 of file ZonedClock.hpp.

◆ utc_time_us()

ts_us_t time_shield::ZonedClock::utc_time_us ( ) const

inlinenoexcept

Return current UTC time in microseconds.

Definition at line 245 of file ZonedClock.hpp.

◆ zone()

TimeZone time_shield::ZonedClock::zone ( ) const

inlinenoexcept

Return stored named zone or UNKNOWN for fixed-offset mode.

Definition at line 141 of file ZonedClock.hpp.

◆ zone_full_name()

std::string time_shield::ZonedClock::zone_full_name ( ) const

inline

Return human-readable zone label.

Returns: Full zone name for named zones or UTC+/-HH:MM for fixed offsets.

Definition at line 294 of file ZonedClock.hpp.

◆ zone_name()

std::string time_shield::ZonedClock::zone_name ( ) const

inline

Return short name of the stored named zone.

Returns: Zone abbreviation or an empty string in fixed-offset mode.

Definition at line 288 of file ZonedClock.hpp.

Member Data Documentation

◆ m_is_named_zone

bool time_shield::ZonedClock::m_is_named_zone

private

Definition at line 363 of file ZonedClock.hpp.

◆ m_offset

tz_t time_shield::ZonedClock::m_offset

private

Definition at line 362 of file ZonedClock.hpp.

◆ m_use_ntp

bool time_shield::ZonedClock::m_use_ntp

private

Definition at line 364 of file ZonedClock.hpp.

◆ m_zone

TimeZone time_shield::ZonedClock::m_zone

private

Definition at line 361 of file ZonedClock.hpp.

The documentation for this class was generated from the following file:

include/time_shield/timezone/ZonedClock.hpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ZonedClock() [1/3]

◆ ZonedClock() [2/3]

◆ ZonedClock() [3/3]

Member Function Documentation

◆ current_utc_ms()

◆ current_utc_us()

◆ format()

◆ from_utc_ms()

◆ from_utc_s()

◆ has_named_zone()

◆ is_ascii_space()

◆ local_time_ms()

◆ local_time_sec()

◆ local_time_us()

◆ now()

◆ ntp_active()

◆ offset_at_utc_ms()

◆ offset_now()

◆ offset_string()

◆ offset_string_for_offset()

◆ resolve_local_time_ms()

◆ set_use_ntp()

◆ set_zone()

◆ to_iso8601()

◆ to_iso8601_utc()

◆ to_utc_ms()

◆ trim_ascii()

◆ try_from_offset()

◆ try_offset_at_utc_ms()

◆ try_set_offset()

◆ try_set_zone()

◆ use_ntp()

◆ utc_time_ms()

◆ utc_time_sec()

◆ utc_time_us()

◆ zone()

◆ zone_full_name()

◆ zone_name()

Member Data Documentation

◆ m_is_named_zone

◆ m_offset

◆ m_use_ntp

◆ m_zone