ESPHome  2024.5.2
Public Member Functions | Static Public Member Functions | Data Fields
esphome::ESPTime Struct Reference

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. More...
 
std::string strftime (const std::string &format)
 Convert this ESPTime struct to a string as specified by the format argument. More...
 
bool is_valid () const
 Check if this ESPTime is valid (all fields in range and year is greater than 2018) More...
 
bool fields_in_range () const
 Check if all time fields of this ESPTime are in range. More...
 
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). More...
 
void recalc_timestamp_local (bool use_day_of_year=true)
 Recalculate the timestamp field from the other fields of this ESPTime instance assuming local fields. More...
 
struct tm to_c_tm ()
 Convert this ESPTime instance back to a tm struct. More...
 
void increment_second ()
 Increment this clock instance by one second. More...
 
void increment_day ()
 Increment this clock instance by one day. More...
 
bool operator< (ESPTime other)
 
bool operator<= (ESPTime other)
 
bool operator== (ESPTime other)
 
bool operator>= (ESPTime other)
 
bool operator> (ESPTime other)
 

Static Public Member Functions

static bool strptime (const std::string &time_to_parse, ESPTime &esp_time)
 Convert a string to ESPTime struct as specified by the format argument. More...
 
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. More...
 
static ESPTime from_epoch_local (time_t epoch)
 Convert an UTC epoch timestamp to a local time ESPTime instance. More...
 
static ESPTime from_epoch_utc (time_t epoch)
 Convert an UTC epoch timestamp to a UTC time ESPTime instance. More...
 
static int32_t timezone_offset ()
 

Data Fields

uint8_t second
 seconds after the minute [0-60] More...
 
uint8_t minute
 minutes after the hour [0-59] More...
 
uint8_t hour
 hours since midnight [0-23] More...
 
uint8_t day_of_week
 day of the week; sunday=1 [1-7] More...
 
uint8_t day_of_month
 day of the month [1-31] More...
 
uint16_t day_of_year
 day of the year [1-366] More...
 
uint8_t month
 month; january=1 [1-12] More...
 
uint16_t year
 year More...
 
bool is_dst
 daylight saving time flag More...
 
time_t timestamp
 unix epoch time (seconds since UTC Midnight January 1, 1970) More...
 

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 64 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 22 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
epochSeconds since 1st January 1970. In UTC.
Returns
The generated ESPTime

Definition at line 85 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
epochSeconds since 1st January 1970. In UTC.
Returns
The generated ESPTime

Definition at line 94 of file time.h.

◆ increment_day()

void esphome::ESPTime::increment_day ( )

Increment this clock instance by one day.

Definition at line 135 of file time.cpp.

◆ increment_second()

void esphome::ESPTime::increment_second ( )

Increment this clock instance by one second.

Definition at line 108 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 61 of file time.h.

◆ operator<()

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

Definition at line 214 of file time.cpp.

◆ operator<=()

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

Definition at line 215 of file time.cpp.

◆ operator==()

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

Definition at line 216 of file time.cpp.

◆ operator>()

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

Definition at line 218 of file time.cpp.

◆ operator>=()

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

Definition at line 217 of file time.cpp.

◆ recalc_timestamp_local()

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

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

Definition at line 181 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 152 of file time.cpp.

◆ strftime() [1/2]

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 18 of file time.cpp.

◆ strftime() [2/2]

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://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#index-strftime
Warning
This method uses dynamically allocated strings which can cause heap fragmentation with some microcontrollers.
This method can return "ERROR" when the underlying strftime() call fails, e.g. when the format string contains unsupported specifiers or when the format string doesn't produce any output.

Definition at line 49 of file time.cpp.

◆ strptime()

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

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

Parameters
time_to_parsenull-terminated c string formatet like this: 2020-08-25 05:30:00.
esp_timean instance of a ESPTime struct
Returns
the success sate of the parsing

Definition at line 67 of file time.cpp.

◆ timezone_offset()

int32_t esphome::ESPTime::timezone_offset ( )
static

Definition at line 190 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 36 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 29 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 27 of file time.h.

◆ day_of_year

uint16_t esphome::ESPTime::day_of_year

day of the year [1-366]

Definition at line 31 of file time.h.

◆ hour

uint8_t esphome::ESPTime::hour

hours since midnight [0-23]

Definition at line 25 of file time.h.

◆ is_dst

bool esphome::ESPTime::is_dst

daylight saving time flag

Definition at line 37 of file time.h.

◆ minute

uint8_t esphome::ESPTime::minute

minutes after the hour [0-59]

Definition at line 23 of file time.h.

◆ month

uint8_t esphome::ESPTime::month

month; january=1 [1-12]

Definition at line 33 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 21 of file time.h.

◆ timestamp

time_t esphome::ESPTime::timestamp

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

Definition at line 39 of file time.h.

◆ year

uint16_t esphome::ESPTime::year

year

Definition at line 35 of file time.h.


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