TZ-independent calendar arithmetic and date-string parsing. More...

#include "civil_time.h"
#include <stdio.h>
#include <string.h>

Include dependency graph for civil_time.cpp:

Functions
static int64_t	days_from_civil (int y, int m, int d)
	Days from 1970-01-01 to the given proleptic-Gregorian civil date.
static bool	fields_sane (int year, int mon, int day, int hour, int min, int sec)
	Range-check a parsed civil date/time.
int64_t	civil_to_epoch (int year, int mon, int day, int hour, int min, int sec)
	Convert a UTC civil date/time to seconds since the Unix epoch.
int	civil_month_from_abbrev (const char *mmm)
	Map a three-letter English month abbreviation to 1–12.
bool	civil_parse_build_stamp (const char date, const char time_str, int64_t *out)
	Parse the compiler's DATE / TIME pair into an epoch value.
bool	civil_parse_http_date (const char hdr, int64_t out)
	Parse an HTTP-date in IMF-fixdate form into an epoch value.
static int64_t	weekday (int64_t days)
	Day of week of a day count from days_from_civil(), 0 = Sunday.
static int64_t	nth_sunday (int y, int m, int n)
	Day count of the `n` th Sunday of a month (n >= 1).
static int64_t	last_sunday (int y, int m)
	Day count of the last Sunday of a month (m <= 11).
int	civil_local_offset_min (int64_t utc, int std_off_min, int rule)
	Offset from UTC in force at `utc`, DST included.

Detailed Description

TZ-independent calendar arithmetic and date-string parsing.

Definition in file civil_time.cpp.

Function Documentation

◆ civil_local_offset_min()

int civil_local_offset_min	(	int64_t	utc,
		int	std_off_min,
		int	rule )

Offset from UTC in force at utc, DST included.

Parameters

[in]	utc	Seconds since the Unix epoch.
[in]	std_off_min	Standard (winter) offset, minutes east of UTC.
[in]	rule	A civil_dst_t; anything else is treated as none.

Returns: std_off_min, plus 60 while DST is in force.

Definition at line 194 of file civil_time.cpp.

References CIVIL_DST_AU, CIVIL_DST_EU, CIVIL_DST_NZ, CIVIL_DST_US, days_from_civil(), last_sunday(), and nth_sunday().

Referenced by clock_refresh().

◆ civil_month_from_abbrev()

int civil_month_from_abbrev ( const char * mmm )

Map a three-letter English month abbreviation to 1–12.

Parameters

[in] mmm Three characters, case-sensitive ("Jan" … "Dec"); need not be NUL-terminated beyond the third character.

Returns: 1–12, or 0 if mmm is not a valid abbreviation.

Definition at line 88 of file civil_time.cpp.

Referenced by civil_parse_build_stamp(), and civil_parse_http_date().

◆ civil_parse_build_stamp()

bool civil_parse_build_stamp	(	const char *	date,
		const char *	time_str,
		int64_t *	out )

Parse the compiler's DATE / TIME pair into an epoch value.

Accepts the exact forms the C standard mandates: "Mmm dd yyyy" where dd is space-padded for single-digit days ("Jul 9 2026"), and "hh:mm:ss".

Parameters

[in]	date	DATE-style string, e.g. "Jul 29 2026".
[in]	time_str	TIME-style string, e.g. "15:14:09".
[out]	out	Epoch seconds on success; untouched on failure.

Returns: true on success, false if either string is malformed.

Definition at line 105 of file civil_time.cpp.

References civil_month_from_abbrev(), civil_to_epoch(), and fields_sane().

Referenced by build_time_floor().

◆ civil_parse_http_date()

bool civil_parse_http_date	(	const char *	hdr,
		int64_t *	out )

Parse an HTTP-date in IMF-fixdate form into an epoch value.

Example: "Wed, 29 Jul 2026 15:14:09 GMT". RFC 9110 §5.6.7 requires senders to emit exactly this form; the two obsolete forms (RFC 850, asctime) are rejected rather than guessed at. The day-of-week field is not cross-checked against the date — it carries no information the date does not.

Parameters

[in]	hdr	HTTP Date header value (NUL-terminated).
[out]	out	Epoch seconds on success; untouched on failure.

Returns: true on success, false if hdr is NULL or malformed.

Definition at line 138 of file civil_time.cpp.

References civil_month_from_abbrev(), civil_to_epoch(), and fields_sane().

Referenced by clock_corroborated().

◆ civil_to_epoch()

int64_t civil_to_epoch	(	int	year,
		int	mon,
		int	day,
		int	hour,
		int	min,
		int	sec )

Convert a UTC civil date/time to seconds since the Unix epoch.

Proleptic Gregorian, valid far beyond any range this firmware cares about. No range validation — callers that parse untrusted text must validate first (both parsers below do).

Parameters

[in]	year	Full year (e.g. 2026).
[in]	mon	Month, 1–12.
[in]	day	Day of month, 1–31.
[in]	hour	Hour, 0–23.
[in]	min	Minute, 0–59.
[in]	sec	Second, 0–60 (60 tolerated for leap seconds).

Returns: Seconds since 1970-01-01T00:00:00Z (negative before the epoch).

Definition at line 80 of file civil_time.cpp.

References days_from_civil().

Referenced by civil_parse_build_stamp(), and civil_parse_http_date().

◆ days_from_civil()

int64_t days_from_civil	(	int	y,
		int	m,
		int	d )

static

Days from 1970-01-01 to the given proleptic-Gregorian civil date.

Howard Hinnant's days_from_civil (public domain, chrono-Compatible-Date paper). Shifts the year so that March starts the year, which makes the leap day the last day and removes every special case from the arithmetic.

Parameters

[in]	y	Full year.
[in]	m	Month, 1–12.
[in]	d	Day of month, 1–31.

Returns: Signed day count relative to the Unix epoch.

Definition at line 36 of file civil_time.cpp.

Referenced by civil_local_offset_min(), civil_to_epoch(), last_sunday(), and nth_sunday().

◆ fields_sane()

bool fields_sane	(	int	year,
		int	mon,
		int	day,
		int	hour,
		int	min,
		int	sec )

static

Range-check a parsed civil date/time.

Month-length and leap-year rules are deliberately not enforced: a bogus "Feb 31" simply rolls into March, which cannot help an attacker (the back-dating this guards against needs an error of weeks, not one day). ponytail: no per-month day table, add one if a caller ever needs to reject impossible dates rather than normalise them.

Parameters

[in]	mon	Month, 1–12.
[in]	day	Day of month, 1–31.
[in]	hour	Hour, 0–23.
[in]	min	Minute, 0–59.
[in]	sec	Second, 0–60.
[in]	year	Full year; bounded to a sane span.