mirror of
https://github.com/esphome/esphome.git
synced 2026-02-18 15:35:59 -07:00
129 lines
5.1 KiB
C++
129 lines
5.1 KiB
C++
#pragma once
|
|
|
|
#include <cstdint>
|
|
#include <ctime>
|
|
#include <cstring>
|
|
|
|
namespace esphome {
|
|
|
|
/// Type of DST transition rule
|
|
enum class DSTRuleType : uint8_t {
|
|
MONTH_WEEK_DAY, ///< M format: Mm.w.d (e.g., M3.2.0 = 2nd Sunday of March)
|
|
JULIAN_NO_LEAP, ///< J format: Jn (day 1-365, Feb 29 not counted)
|
|
DAY_OF_YEAR, ///< Plain number: n (day 0-365, Feb 29 counted in leap years)
|
|
};
|
|
|
|
/// Rule for DST transition
|
|
struct DSTRule {
|
|
DSTRuleType type; ///< Type of rule
|
|
uint8_t month; ///< Month 1-12 (for MONTH_WEEK_DAY)
|
|
uint8_t week; ///< Week 1-5, 5 = last (for MONTH_WEEK_DAY)
|
|
uint8_t day_of_week; ///< Day 0-6, 0 = Sunday (for MONTH_WEEK_DAY)
|
|
uint16_t day; ///< Day of year (for JULIAN_NO_LEAP and DAY_OF_YEAR)
|
|
int32_t time_seconds; ///< Seconds after midnight (default 7200 = 2:00 AM)
|
|
};
|
|
|
|
/// Parsed POSIX timezone information
|
|
struct ParsedTimezone {
|
|
int32_t std_offset_seconds; ///< Standard time offset from UTC in seconds (positive = west)
|
|
int32_t dst_offset_seconds; ///< DST offset from UTC in seconds
|
|
DSTRule dst_start; ///< When DST starts
|
|
DSTRule dst_end; ///< When DST ends
|
|
bool has_dst; ///< Whether this timezone has DST
|
|
};
|
|
|
|
/// Parse a POSIX TZ string into a ParsedTimezone struct.
|
|
/// Supports formats like:
|
|
/// - "EST5" (simple offset, no DST)
|
|
/// - "EST5EDT,M3.2.0,M11.1.0" (with DST, M-format rules)
|
|
/// - "CST6CDT,M3.2.0/2,M11.1.0/2" (with transition times)
|
|
/// - "<+07>-7" (angle-bracket notation for special names)
|
|
/// - "IST-5:30" (half-hour offsets)
|
|
/// - "EST5EDT,J60,J300" (J-format: Julian day without leap day)
|
|
/// - "EST5EDT,60,300" (plain day number: day of year with leap day)
|
|
/// @param tz_string The POSIX TZ string to parse
|
|
/// @param result Output: the parsed timezone data
|
|
/// @return true if parsing succeeded, false on error
|
|
bool parse_posix_tz(const char *tz_string, ParsedTimezone &result);
|
|
|
|
/// Calculate the epoch timestamp for a DST transition in a given year.
|
|
/// @param year The year (e.g., 2026)
|
|
/// @param rule The DST rule (month, week, day_of_week, time)
|
|
/// @param base_offset_seconds The timezone offset to apply (std or dst depending on context)
|
|
/// @return Unix epoch timestamp of the transition
|
|
time_t calculate_dst_transition(int year, const DSTRule &rule, int32_t base_offset_seconds);
|
|
|
|
/// Check if a given UTC epoch falls within DST for the parsed timezone.
|
|
/// @param utc_epoch Unix timestamp in UTC
|
|
/// @param tz The parsed timezone
|
|
/// @return true if DST is in effect at the given time
|
|
bool is_in_dst(time_t utc_epoch, const ParsedTimezone &tz);
|
|
|
|
/// Convert a UTC epoch to local time using the parsed timezone.
|
|
/// This replaces libc's localtime() to avoid scanf dependency.
|
|
/// @param utc_epoch Unix timestamp in UTC
|
|
/// @param tz The parsed timezone
|
|
/// @param[out] out_tm Output tm struct with local time
|
|
/// @return true on success
|
|
bool epoch_to_local_tm(time_t utc_epoch, const ParsedTimezone &tz, struct tm *out_tm);
|
|
|
|
/// Get the current offset from UTC in seconds for a given epoch.
|
|
/// @param utc_epoch Unix timestamp in UTC
|
|
/// @param tz The parsed timezone
|
|
/// @return Offset in seconds (positive = behind UTC, negative = ahead)
|
|
int32_t get_utc_offset(time_t utc_epoch, const ParsedTimezone &tz);
|
|
|
|
// Internal helper functions exposed for testing
|
|
|
|
namespace internal {
|
|
|
|
/// Skip a timezone name (letters or <...> quoted format)
|
|
/// @param p Pointer to current position, updated on return
|
|
/// @return true if a valid name was found
|
|
bool skip_tz_name(const char *&p);
|
|
|
|
/// Parse an offset in format [-]hh[:mm[:ss]]
|
|
/// @param p Pointer to current position, updated on return
|
|
/// @return Offset in seconds
|
|
int32_t parse_offset(const char *&p);
|
|
|
|
/// Parse a DST rule in format Mm.w.d[/time], Jn[/time], or n[/time]
|
|
/// @param p Pointer to current position, updated on return
|
|
/// @param rule Output: the parsed rule
|
|
/// @return true if parsing succeeded
|
|
bool parse_dst_rule(const char *&p, DSTRule &rule);
|
|
|
|
/// Convert Julian day (J format, 1-365 not counting Feb 29) to month/day
|
|
/// @param julian_day Day number 1-365
|
|
/// @param year The year (for leap year calculation)
|
|
/// @param[out] month Output: month 1-12
|
|
/// @param[out] day Output: day of month
|
|
void julian_to_month_day(int julian_day, int year, int &month, int &day);
|
|
|
|
/// Convert day of year (plain format, 0-365 counting Feb 29) to month/day
|
|
/// @param day_of_year Day number 0-365
|
|
/// @param year The year (for leap year calculation)
|
|
/// @param[out] month Output: month 1-12
|
|
/// @param[out] day Output: day of month
|
|
void day_of_year_to_month_day(int day_of_year, int year, int &month, int &day);
|
|
|
|
/// Calculate day of week for any date (0 = Sunday)
|
|
/// Uses a simplified algorithm that works for years 1970-2099
|
|
int day_of_week(int year, int month, int day);
|
|
|
|
/// Get the number of days in a month
|
|
int days_in_month(int year, int month);
|
|
|
|
/// Check if a year is a leap year
|
|
bool is_leap_year(int year);
|
|
|
|
/// Convert epoch to year/month/day/hour/min/sec (UTC)
|
|
void epoch_to_tm_utc(time_t epoch, struct tm *out_tm);
|
|
|
|
/// Convert tm struct to epoch (UTC)
|
|
time_t tm_to_epoch_utc(const struct tm *tm);
|
|
|
|
} // namespace internal
|
|
|
|
} // namespace esphome
|