A more user-friendly version of struct tm from time.h. More...

#include <time.h>

Public Member Functions
size_t	strftime (char buffer, size_t buffer_len, const char format)
	Convert this ESPTime struct to a null-terminated c string buffer as specified by the format argument.

size_t	strftime_to (std::span< char, STRFTIME_BUFFER_SIZE > buffer, const char *format)
	Format time into a fixed-size buffer, returns length written.

std::string	strftime (const std::string &format)
	Convert this ESPTime struct to a string as specified by the format argument.

std::string	strftime (const char *format)
	Convert this ESPTime struct to a string as specified by the format argument.

bool	is_valid () const
	Check if this ESPTime is valid (all fields in range and year is greater than 2018)

bool	fields_in_range () const
	Check if all time fields of this ESPTime are in range.

void	recalc_timestamp_utc (bool use_day_of_year=true)
	Recalculate the timestamp field from the other fields of this ESPTime instance (must be UTC).

void	recalc_timestamp_local ()
	Recalculate the timestamp field from the other fields of this ESPTime instance assuming local fields.

struct tm	to_c_tm ()
	Convert this ESPTime instance back to a tm struct.

void	increment_second ()
	Increment this clock instance by one second.

void	increment_day ()
	Increment this clock instance by one day.

bool	operator< (const ESPTime &other) const

bool	operator<= (const ESPTime &other) const

bool	operator== (const ESPTime &other) const

bool	operator>= (const ESPTime &other) const

bool	operator> (const ESPTime &other) const

Static Public Member Functions
static bool	strptime (const char *time_to_parse, size_t len, ESPTime &esp_time)
	Convert a string to ESPTime struct as specified by the format argument.

static bool	strptime (const char *time_to_parse, ESPTime &esp_time)
	Convert a string to ESPTime struct as specified by the format argument.

static bool	strptime (const std::string &time_to_parse, ESPTime &esp_time)
	Convert a string to ESPTime struct as specified by the format argument.

static ESPTime	from_c_tm (struct tm *c_tm, time_t c_time)
	Convert a C tm struct instance with a C unix epoch timestamp to an ESPTime instance.

static ESPTime	from_epoch_local (time_t epoch)
	Convert an UTC epoch timestamp to a local time ESPTime instance.

static ESPTime	from_epoch_utc (time_t epoch)
	Convert an UTC epoch timestamp to a UTC time ESPTime instance.

static int32_t	timezone_offset ()

Data Fields
uint8_t	second
	seconds after the minute [0-60]

uint8_t	minute
	minutes after the hour [0-59]

uint8_t	hour
	hours since midnight [0-23]

uint8_t	day_of_week
	day of the week; sunday=1 [1-7]

uint8_t	day_of_month
	day of the month [1-31]

uint16_t	day_of_year
	day of the year [1-366]

uint8_t	month
	month; january=1 [1-12]

uint16_t	year
	year

bool	is_dst
	daylight saving time flag

time_t	timestamp
	unix epoch time (seconds since UTC Midnight January 1, 1970)

Static Public Attributes
static constexpr size_t	STRFTIME_BUFFER_SIZE = 128
	Buffer size required for strftime output.

Detailed Description

A more user-friendly version of struct tm from time.h.

Definition at line 17 of file time.h.

Member Function Documentation

◆ fields_in_range()

bool esphome::ESPTime::fields_in_range ( ) const

inline

Check if all time fields of this ESPTime are in range.

Definition at line 77 of file time.h.

◆ from_c_tm()

ESPTime esphome::ESPTime::from_c_tm	(	struct tm *	c_tm,
		time_t	c_time )

static

Convert a C tm struct instance with a C unix epoch timestamp to an ESPTime instance.

Definition at line 33 of file time.cpp.

◆ from_epoch_local()

static ESPTime esphome::ESPTime::from_epoch_local ( time_t epoch )

inlinestatic

Convert an UTC epoch timestamp to a local time ESPTime instance.

Parameters

epoch Seconds since 1st January 1970. In UTC.

Returns: The generated ESPTime

Definition at line 107 of file time.h.

◆ from_epoch_utc()

static ESPTime esphome::ESPTime::from_epoch_utc ( time_t epoch )

inlinestatic

Convert an UTC epoch timestamp to a UTC time ESPTime instance.

Parameters

epoch Seconds since 1st January 1970. In UTC.

Returns: The generated ESPTime

Definition at line 119 of file time.h.

◆ increment_day()

void esphome::ESPTime::increment_day ( )

Increment this clock instance by one day.

Definition at line 150 of file time.cpp.

◆ increment_second()

void esphome::ESPTime::increment_second ( )

Increment this clock instance by one second.

Definition at line 122 of file time.cpp.

◆ is_valid()

bool esphome::ESPTime::is_valid ( ) const

inline

Check if this ESPTime is valid (all fields in range and year is greater than 2018)

Definition at line 74 of file time.h.

◆ operator<()

bool esphome::ESPTime::operator< ( const ESPTime & other ) const

Definition at line 219 of file time.cpp.

◆ operator<=()

bool esphome::ESPTime::operator<= ( const ESPTime & other ) const

Definition at line 220 of file time.cpp.

◆ operator==()

bool esphome::ESPTime::operator== ( const ESPTime & other ) const

Definition at line 221 of file time.cpp.

◆ operator>()

bool esphome::ESPTime::operator> ( const ESPTime & other ) const

Definition at line 223 of file time.cpp.

◆ operator>=()

bool esphome::ESPTime::operator>= ( const ESPTime & other ) const

Definition at line 222 of file time.cpp.

◆ recalc_timestamp_local()

void esphome::ESPTime::recalc_timestamp_local ( )

Recalculate the timestamp field from the other fields of this ESPTime instance assuming local fields.

Definition at line 195 of file time.cpp.

◆ recalc_timestamp_utc()

void esphome::ESPTime::recalc_timestamp_utc ( bool use_day_of_year = true )

Recalculate the timestamp field from the other fields of this ESPTime instance (must be UTC).

Definition at line 168 of file time.cpp.

◆ strftime() [1/3]

size_t esphome::ESPTime::strftime	(	char *	buffer,
		size_t	buffer_len,
		const char *	format )

Convert this ESPTime struct to a null-terminated c string buffer as specified by the format argument.

Up to buffer_len bytes are written.

See also: https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#index-strftime

Definition at line 16 of file time.cpp.

◆ strftime() [2/3]

std::string esphome::ESPTime::strftime ( const char * format )

Convert this ESPTime struct to a string as specified by the format argument.

See also: https://en.cppreference.com/w/c/chrono/strftime

Warning: This method returns a dynamically allocated string which can cause heap fragmentation with some microcontrollers. Prefer strftime_to() for heap-free formatting.; This method can return "ERROR" when the underlying strftime() call fails or when the output exceeds STRFTIME_BUFFER_SIZE bytes.

Definition at line 62 of file time.cpp.

◆ strftime() [3/3]

std::string esphome::ESPTime::strftime ( const std::string & format )

Convert this ESPTime struct to a string as specified by the format argument.

See also: https://en.cppreference.com/w/c/chrono/strftime

Warning: This method returns a dynamically allocated string which can cause heap fragmentation with some microcontrollers. Prefer strftime_to() for heap-free formatting.; This method can return "ERROR" when the underlying strftime() call fails or when the output exceeds STRFTIME_BUFFER_SIZE bytes.

Definition at line 68 of file time.cpp.

◆ strftime_to()

size_t esphome::ESPTime::strftime_to	(	std::span< char, STRFTIME_BUFFER_SIZE >	buffer,
		const char *	format )

Format time into a fixed-size buffer, returns length written.

This is the preferred method for avoiding heap allocations. The buffer size is enforced at compile-time. On format error, writes "ERROR" to the buffer and returns 5.

See also: https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#index-strftime

Definition at line 21 of file time.cpp.

◆ strptime() [1/3]

static bool esphome::ESPTime::strptime	(	const char *	time_to_parse,
		ESPTime &	esp_time )

inlinestatic

Convert a string to ESPTime struct as specified by the format argument.

Parameters

time_to_parse	c string formatted like this: 2020-08-25 05:30:00.
len	length of the string (not including null terminator if present)
esp_time	an instance of a ESPTime struct

Returns: the success state of the parsing

Definition at line 91 of file time.h.

◆ strptime() [2/3]

bool esphome::ESPTime::strptime	(	const char *	time_to_parse,
		size_t	len,
		ESPTime &	esp_time )

static

Convert a string to ESPTime struct as specified by the format argument.

Parameters

time_to_parse	c string formatted like this: 2020-08-25 05:30:00.
len	length of the string (not including null terminator if present)
esp_time	an instance of a ESPTime struct

Returns: the success state of the parsing

Definition at line 70 of file time.cpp.

◆ strptime() [3/3]

static bool esphome::ESPTime::strptime	(	const std::string &	time_to_parse,
		ESPTime &	esp_time )

inlinestatic

Convert a string to ESPTime struct as specified by the format argument.

Parameters

time_to_parse	c string formatted like this: 2020-08-25 05:30:00.
len	length of the string (not including null terminator if present)
esp_time	an instance of a ESPTime struct

Returns: the success state of the parsing

Definition at line 95 of file time.h.

◆ timezone_offset()

int32_t esphome::ESPTime::timezone_offset ( )

static

Definition at line 209 of file time.cpp.

◆ to_c_tm()

struct tm esphome::ESPTime::to_c_tm ( )

Convert this ESPTime instance back to a tm struct.

Definition at line 48 of file time.cpp.

Field Documentation

◆ day_of_month

uint8_t esphome::ESPTime::day_of_month

day of the month [1-31]

Definition at line 32 of file time.h.

◆ day_of_week

uint8_t esphome::ESPTime::day_of_week

day of the week; sunday=1 [1-7]

Definition at line 30 of file time.h.

◆ day_of_year

uint16_t esphome::ESPTime::day_of_year

day of the year [1-366]

Definition at line 34 of file time.h.

◆ hour

uint8_t esphome::ESPTime::hour

hours since midnight [0-23]

Definition at line 28 of file time.h.

◆ is_dst

bool esphome::ESPTime::is_dst

daylight saving time flag

Definition at line 40 of file time.h.

◆ minute

uint8_t esphome::ESPTime::minute

minutes after the hour [0-59]

Definition at line 26 of file time.h.

◆ month

uint8_t esphome::ESPTime::month

month; january=1 [1-12]

Definition at line 36 of file time.h.

◆ second

uint8_t esphome::ESPTime::second

seconds after the minute [0-60]

Note: second is generally 0-59; the extra range is to accommodate leap seconds.

Definition at line 24 of file time.h.

◆ STRFTIME_BUFFER_SIZE

size_t esphome::ESPTime::STRFTIME_BUFFER_SIZE = 128

staticconstexpr

Buffer size required for strftime output.

Definition at line 19 of file time.h.

◆ timestamp

time_t esphome::ESPTime::timestamp

unix epoch time (seconds since UTC Midnight January 1, 1970)

Definition at line 42 of file time.h.

◆ year

uint16_t esphome::ESPTime::year

year

Definition at line 38 of file time.h.

The documentation for this struct was generated from the following files:

esphome/core/time.h
esphome/core/time.cpp

Public Member Functions

Static Public Member Functions

Data Fields

Static Public Attributes

Detailed Description

Member Function Documentation

◆ fields_in_range()

◆ from_c_tm()

◆ from_epoch_local()

◆ from_epoch_utc()

◆ increment_day()

◆ increment_second()

◆ is_valid()

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ recalc_timestamp_local()

◆ recalc_timestamp_utc()

◆ strftime() [1/3]

◆ strftime() [2/3]

◆ strftime() [3/3]

◆ strftime_to()

◆ strptime() [1/3]

◆ strptime() [2/3]

◆ strptime() [3/3]

◆ timezone_offset()

◆ to_c_tm()

Field Documentation

◆ day_of_month

◆ day_of_week

◆ day_of_year

◆ hour

◆ is_dst

◆ minute

◆ month

◆ second

◆ STRFTIME_BUFFER_SIZE

◆ timestamp

◆ year