civil_time.h File Reference

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

#include <stdint.h>
#include <stdbool.h>

Include dependency graph for civil_time.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	civil_dst_t {   CIVIL_DST_NONE = 0 , CIVIL_DST_EU = 1 , CIVIL_DST_US = 2 , CIVIL_DST_AU = 3 ,   CIVIL_DST_NZ = 4 , CIVIL_DST__COUNT }
	Daylight-saving rules the panel clock knows, persisted in NVS as a number, so never renumber them. More...

Functions
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.
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.

Pure unit — no IDF, no lwip, no globals — so it builds and self-checks on the host (see fuzz/test_civil_time.cpp), same pattern as eth_json.cpp.

Deliberately does NOT use mktime()/timegm(): mktime() interprets its input in the current TZ, which on ESP-IDF depends on whether setenv("TZ") ran, and timegm() is not portable. Everything here is UTC by construction.

Definition in file civil_time.h.

Enumeration Type Documentation

civil_dst_t

enum civil_dst_t

Daylight-saving rules the panel clock knows, persisted in NVS as a number, so never renumber them.

ponytail: the four rule sets that cover most places with DST; a region with other rules (Chile, Israel, Egypt...) picks a fixed offset and moves it by hand. Add a rule here and to the page's region list when one is needed.

Enumerator
CIVIL_DST_NONE	Fixed offset, no DST.
CIVIL_DST_EU	Last Sun Mar 01:00 UTC to last Sun Oct 01:00 UTC.
CIVIL_DST_US	2nd Sun Mar 02:00 to 1st Sun Nov 02:00, local.
CIVIL_DST_AU	1st Sun Oct 02:00 to 1st Sun Apr 03:00, local.
CIVIL_DST_NZ	Last Sun Sep 02:00 to 1st Sun Apr 03:00, local.
CIVIL_DST__COUNT

Definition at line 99 of file civil_time.h.

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().