AceTime  0.5
Date and time classes for Arduino that support timezones from the TZ Database, and a system clock that can synchronize from an NTP server or an RTC chip.
Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
ace_time::LocalDate Class Reference

The date (year, month, day) representing the date without regards to time zone. More...

#include <LocalDate.h>

Public Member Functions

 LocalDate ()
 Default constructor does nothing. More...
 
int16_t year () const
 Return the full year instead of just the last 2 digits. More...
 
void year (int16_t year)
 Set the year given the full year. More...
 
int8_t yearTiny () const
 Return the single-byte year offset from year 2000. More...
 
void yearTiny (int8_t yearTiny)
 Set the single-byte year offset from year 2000. More...
 
uint8_t month () const
 Return the month with January=1, December=12. More...
 
void month (uint8_t month)
 Set the month. More...
 
uint8_t day () const
 Return the day of the month. More...
 
void day (uint8_t day)
 Set the day of the month. More...
 
uint8_t dayOfWeek () const
 Calculate the day of week given the (year, month, day). More...
 
bool isError () const
 Return true if any component indicates an error condition. More...
 
acetime_t toEpochDays () const
 Return number of days since AceTime epoch (2000-01-01 00:00:00Z). More...
 
acetime_t toUnixDays () const
 Return the number of days since Unix epoch (1970-01-01 00:00:00). More...
 
acetime_t toEpochSeconds () const
 Return the number of seconds since AceTime epoch (2000-01-01 00:00:00). More...
 
acetime_t toUnixSeconds () const
 Return the number of seconds since Unix epoch (1970-01-01 00:00:00).
 
int8_t compareTo (const LocalDate &that) const
 Compare this LocalDate to that LocalDate, returning (<0, 0, >0) according to whether the epochSeconds is (this<that, this==this, this>that). More...
 
void printTo (Print &printer) const
 Print LocalDate to 'printer' in ISO 8601 format, along with the day of week. More...
 
 LocalDate (const LocalDate &)=default
 
LocalDateoperator= (const LocalDate &)=default
 

Static Public Member Functions

static LocalDate forComponents (int16_t year, uint8_t month, uint8_t day)
 Factory method using separated year, month and day fields. More...
 
static LocalDate forTinyComponents (int8_t yearTiny, uint8_t month, uint8_t day)
 Factory method using components with an int8_t yearTiny. More...
 
static LocalDate forEpochDays (acetime_t epochDays)
 Factory method using the number of days since AceTime epoch of 2000-01-01. More...
 
static LocalDate forUnixDays (acetime_t unixDays)
 Factory method using the number of days since Unix epoch 1970-01-1. More...
 
static LocalDate forEpochSeconds (acetime_t epochSeconds)
 Factory method using the number of seconds since AceTime epoch of 2000-01-01. More...
 
static LocalDate forUnixSeconds (acetime_t unixSeconds)
 Factory method that takes the number of seconds since Unix Epoch of 1970-01-01. More...
 
static LocalDate forDateString (const char *dateString)
 Factory method. More...
 
static LocalDate forDateStringChainable (const char *&dateString)
 Variant of forDateString() that updates the pointer to the next unprocessed character. More...
 
static LocalDate forError ()
 Factory method that returns a LocalDate which represents an error condition. More...
 
static bool isLeapYear (int16_t year)
 True if year is a leap year. More...
 
static bool isYearValid (int16_t year)
 Return true if year is within valid range of [1873, 2127]. More...
 
static uint8_t daysInMonth (int16_t year, uint8_t month)
 Return the number of days in the current month. More...
 

Static Public Attributes

static const int16_t kEpochYear = 2000
 Base year of epoch. More...
 
static const int8_t kInvalidYearTiny = INT8_MIN
 Sentinel yearTiny which indicates an error condition or sometimes a year that 'does not exist'.
 
static const acetime_t kInvalidEpochDays = INT32_MIN
 Sentinel epochDays which indicates an error. More...
 
static const acetime_t kInvalidEpochSeconds = LocalTime::kInvalidSeconds
 Sentinel epochSeconds which indicates an error. More...
 
static const acetime_t kSecondsSinceUnixEpoch = 946684800
 Number of seconds from Unix epoch (1970-01-01 00:00:00Z) to the AceTime epoch (2000-01-01 00:00:00Z).
 
static const acetime_t kDaysSinceUnixEpoch = 10957
 Number of days from Unix epoch (1970-01-01 00:00:00Z) to the AceTime epoch (2000-01-01 00:00:00Z).
 
static const uint8_t kMonday = 1
 Monday ISO 8601 number. More...
 
static const uint8_t kTuesday = 2
 Tuesday ISO 8601 number. More...
 
static const uint8_t kWednesday = 3
 Wednesday ISO 8601 number. More...
 
static const uint8_t kThursday = 4
 Thursday ISO 8601 number. More...
 
static const uint8_t kFriday = 5
 Friday ISO 8601 number. More...
 
static const uint8_t kSaturday = 6
 Saturday ISO 8601 number. More...
 
static const uint8_t kSunday = 7
 Sunday ISO 8601 number. More...
 

Friends

bool operator== (const LocalDate &a, const LocalDate &b)
 Return true if two LocalDate objects are equal in all components. More...
 

Detailed Description

The date (year, month, day) representing the date without regards to time zone.

The year field is internally represented as an int8_t offset from the year

  1. However, the value of -128 (kInvalidYearTiny) is used to indicate an error condition. So the actual range of the year is [1873, 2127] instead of [1872, 2127].

If the year is restricted to 2000-2099 (2 digit years), these fields correspond to the range supported by the DS3231 RTC chip.

The dayOfWeek (1=Monday, 7=Sunday, per ISO 8601) is calculated from the date fields.

Parts of this class were inspired by the java.time.LocalDate class of Java 11 (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/LocalDate.html).

Definition at line 36 of file LocalDate.h.

Constructor & Destructor Documentation

◆ LocalDate()

ace_time::LocalDate::LocalDate ( )
inlineexplicit

Default constructor does nothing.

Definition at line 216 of file LocalDate.h.

Member Function Documentation

◆ compareTo()

int8_t ace_time::LocalDate::compareTo ( const LocalDate that) const
inline

Compare this LocalDate to that LocalDate, returning (<0, 0, >0) according to whether the epochSeconds is (this<that, this==this, this>that).

If isError() is true, the behavior is undefined.

Definition at line 338 of file LocalDate.h.

◆ day() [1/2]

uint8_t ace_time::LocalDate::day ( ) const
inline

Return the day of the month.

Definition at line 237 of file LocalDate.h.

◆ day() [2/2]

void ace_time::LocalDate::day ( uint8_t  day)
inline

Set the day of the month.

Definition at line 240 of file LocalDate.h.

◆ dayOfWeek()

uint8_t ace_time::LocalDate::dayOfWeek ( ) const
inline

Calculate the day of week given the (year, month, day).

Idea borrowed from https://github.com/evq/utz. No validation of year, month or day is performed. If this is found to be too slow, then consider caching the results.

Definition at line 248 of file LocalDate.h.

◆ daysInMonth()

static uint8_t ace_time::LocalDate::daysInMonth ( int16_t  year,
uint8_t  month 
)
inlinestatic

Return the number of days in the current month.

Definition at line 210 of file LocalDate.h.

◆ forComponents()

static LocalDate ace_time::LocalDate::forComponents ( int16_t  year,
uint8_t  month,
uint8_t  day 
)
inlinestatic

Factory method using separated year, month and day fields.

Returns LocalDate::forError() if the parameters are out of range.

Parameters
year[1873-2127]
monthmonth with January=1, December=12
dayday of month [1-31]

Definition at line 94 of file LocalDate.h.

◆ forDateString()

LocalDate ace_time::LocalDate::forDateString ( const char *  dateString)
static

Factory method.

Create a LocalDate from the ISO 8601 date string. If the string cannot be parsed, then isError() on the constructed object returns true, but the data validation is very weak. Year should probably be between 1872 and 2127. Created for debugging purposes not for production use.

Parameters
dateStringthe date in ISO 8601 format (yyyy-mm-dd)

Definition at line 67 of file LocalDate.cpp.

◆ forDateStringChainable()

LocalDate ace_time::LocalDate::forDateStringChainable ( const char *&  dateString)
static

Variant of forDateString() that updates the pointer to the next unprocessed character.

This allows chaining to another forXxxStringChainable() method.

This method assumes that the dateString is sufficiently long.

Definition at line 74 of file LocalDate.cpp.

◆ forEpochDays()

static LocalDate ace_time::LocalDate::forEpochDays ( acetime_t  epochDays)
inlinestatic

Factory method using the number of days since AceTime epoch of 2000-01-01.

If epochDays is kInvalidEpochDays, isError() will return true.

Parameters
epochDaysnumber of days since AceTime epoch (2000-01-01)

Definition at line 113 of file LocalDate.h.

◆ forEpochSeconds()

static LocalDate ace_time::LocalDate::forEpochSeconds ( acetime_t  epochSeconds)
inlinestatic

Factory method using the number of seconds since AceTime epoch of 2000-01-01.

The number of seconds from midnight of the given day is thrown away. For negative values of epochSeconds, the method performs a floor operation when rounding to the nearest day, in other words towards negative infinity.

If epochSeconds is kInvalidEpochSeconds, isError() will return true.

Parameters
epochSecondsnumber of seconds since AceTime epoch (2000-01-01)

Definition at line 145 of file LocalDate.h.

◆ forError()

static LocalDate ace_time::LocalDate::forError ( )
inlinestatic

Factory method that returns a LocalDate which represents an error condition.

The isError() method will return true.

Definition at line 194 of file LocalDate.h.

◆ forTinyComponents()

static LocalDate ace_time::LocalDate::forTinyComponents ( int8_t  yearTiny,
uint8_t  month,
uint8_t  day 
)
inlinestatic

Factory method using components with an int8_t yearTiny.

Definition at line 101 of file LocalDate.h.

◆ forUnixDays()

static LocalDate ace_time::LocalDate::forUnixDays ( acetime_t  unixDays)
inlinestatic

Factory method using the number of days since Unix epoch 1970-01-1.

Definition at line 126 of file LocalDate.h.

◆ forUnixSeconds()

static LocalDate ace_time::LocalDate::forUnixSeconds ( acetime_t  unixSeconds)
inlinestatic

Factory method that takes the number of seconds since Unix Epoch of 1970-01-01.

Similar to forEpochSeconds(), the seconds corresponding to the partial day are truncated down towards the smallest whole day.

Definition at line 162 of file LocalDate.h.

◆ isError()

bool ace_time::LocalDate::isError ( ) const
inline

Return true if any component indicates an error condition.

Definition at line 258 of file LocalDate.h.

◆ isLeapYear()

static bool ace_time::LocalDate::isLeapYear ( int16_t  year)
inlinestatic

True if year is a leap year.

Definition at line 199 of file LocalDate.h.

◆ isYearValid()

static bool ace_time::LocalDate::isYearValid ( int16_t  year)
inlinestatic

Return true if year is within valid range of [1873, 2127].

Definition at line 204 of file LocalDate.h.

◆ month() [1/2]

uint8_t ace_time::LocalDate::month ( ) const
inline

Return the month with January=1, December=12.

Definition at line 231 of file LocalDate.h.

◆ month() [2/2]

void ace_time::LocalDate::month ( uint8_t  month)
inline

Set the month.

Definition at line 234 of file LocalDate.h.

◆ printTo()

void ace_time::LocalDate::printTo ( Print &  printer) const

Print LocalDate to 'printer' in ISO 8601 format, along with the day of week.

This class does not implement the Printable interface to avoid increasing the size of the object from the additional virtual function.

Definition at line 48 of file LocalDate.cpp.

◆ toEpochDays()

acetime_t ace_time::LocalDate::toEpochDays ( ) const
inline

Return number of days since AceTime epoch (2000-01-01 00:00:00Z).

Returns kInvalidEpochDays if isError() is true, which allows round trip conversions of forEpochDays() and toEpochDays() even when isError() is true.

In an 8-bit implementation:

  • the largest date 2127-12-31 returns 46751
  • the smallest date 1872-01-01 returns -46751

Uses Julian days which normally start at 12:00:00. But this method returns the delta number of days since 00:00:00, so we can interpret the Gregorian calendar day to start at 00:00:00.

See https://en.wikipedia.org/wiki/Julian_day

Definition at line 280 of file LocalDate.h.

◆ toEpochSeconds()

acetime_t ace_time::LocalDate::toEpochSeconds ( ) const
inline

Return the number of seconds since AceTime epoch (2000-01-01 00:00:00).

Returns kInvalidEpochSeconds if isError() is true. This is a convenience method that returns (86400 * toEpochDays()). Since acetime_t is a 32-bit signed integer, the limits are different:

  • the smallest date corresponding to INT32_MIN is 1931-12-13 20:45:52 so this method supports dates as small as 1931-12-14.
  • the largest date corresponding to INT32_MAX is 2068-01-19 03:14:07.

Definition at line 320 of file LocalDate.h.

◆ toUnixDays()

acetime_t ace_time::LocalDate::toUnixDays ( ) const
inline

Return the number of days since Unix epoch (1970-01-01 00:00:00).

Definition at line 305 of file LocalDate.h.

◆ year() [1/2]

int16_t ace_time::LocalDate::year ( ) const
inline

Return the full year instead of just the last 2 digits.

Definition at line 219 of file LocalDate.h.

◆ year() [2/2]

void ace_time::LocalDate::year ( int16_t  year)
inline

Set the year given the full year.

Definition at line 222 of file LocalDate.h.

◆ yearTiny() [1/2]

int8_t ace_time::LocalDate::yearTiny ( ) const
inline

Return the single-byte year offset from year 2000.

Definition at line 225 of file LocalDate.h.

◆ yearTiny() [2/2]

void ace_time::LocalDate::yearTiny ( int8_t  yearTiny)
inline

Set the single-byte year offset from year 2000.

Definition at line 228 of file LocalDate.h.

Friends And Related Function Documentation

◆ operator==

bool operator== ( const LocalDate a,
const LocalDate b 
)
friend

Return true if two LocalDate objects are equal in all components.

Definition at line 431 of file LocalDate.h.

Member Data Documentation

◆ kEpochYear

const int16_t ace_time::LocalDate::kEpochYear = 2000
static

Base year of epoch.

Definition at line 39 of file LocalDate.h.

◆ kFriday

const uint8_t ace_time::LocalDate::kFriday = 5
static

Friday ISO 8601 number.

Definition at line 78 of file LocalDate.h.

◆ kInvalidEpochDays

const acetime_t ace_time::LocalDate::kInvalidEpochDays = INT32_MIN
static

Sentinel epochDays which indicates an error.

Definition at line 48 of file LocalDate.h.

◆ kInvalidEpochSeconds

const acetime_t ace_time::LocalDate::kInvalidEpochSeconds = LocalTime::kInvalidSeconds
static

Sentinel epochSeconds which indicates an error.

Definition at line 51 of file LocalDate.h.

◆ kMonday

const uint8_t ace_time::LocalDate::kMonday = 1
static

Monday ISO 8601 number.

Definition at line 66 of file LocalDate.h.

◆ kSaturday

const uint8_t ace_time::LocalDate::kSaturday = 6
static

Saturday ISO 8601 number.

Definition at line 81 of file LocalDate.h.

◆ kSunday

const uint8_t ace_time::LocalDate::kSunday = 7
static

Sunday ISO 8601 number.

Definition at line 84 of file LocalDate.h.

◆ kThursday

const uint8_t ace_time::LocalDate::kThursday = 4
static

Thursday ISO 8601 number.

Definition at line 75 of file LocalDate.h.

◆ kTuesday

const uint8_t ace_time::LocalDate::kTuesday = 2
static

Tuesday ISO 8601 number.

Definition at line 69 of file LocalDate.h.

◆ kWednesday

const uint8_t ace_time::LocalDate::kWednesday = 3
static

Wednesday ISO 8601 number.

Definition at line 72 of file LocalDate.h.


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