AceTime 3.0.0 Date and time classes for Arduino that support timezones from the TZ Database.

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
| Default constructor does nothing.
int16_t | year () const
| Return the year.
void | year (int16_t year)
| Set the year.
uint8_t | month () const
| Return the month with January=1, December=12.
void | month (uint8_t month)
| Set the month.
uint8_t | day () const
| Return the day of the month.
void | day (uint8_t day)
| Set the day of the month.
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.
int32_t | toEpochDays () const
| Return number of days since the current epoch year `sCurrentEpochYear`. More...
int32_t | toUnixDays () const
| Return the number of days since Unix epoch (1970-01-01 00:00:00).
acetime_t | toEpochSeconds () const
| Return the number of seconds since the currentEpochYear(). More...
int64_t | toUnixSeconds64 () const
| Return the number of seconds since Unix epoch (1970-01-01 00:00:00).
int16_t | daysUntil (uint8_t month, uint8_t day) const
| Calculate number of days from current LocalDate to the next target (month, day). More...
int8_t | compareTo (const LocalDate &that) const
| Compare 'this' LocalDate to 'that' LocalDate, returning (<0, 0, >0) according to whether 'this' occurs (before, same as, after) '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
LocalDate & | operator= (const LocalDate &)=default

## Static Public Member Functions
static bool | isLeapYear (int16_t year)
| True if year is a leap year.
static uint8_t | daysInMonth (int16_t year, uint8_t month)
| Return the number of days in the given (year, month).
static bool | isYearValid (int16_t year)
| Return true if year is within the range of `[0,10000]`
static LocalDate | forComponents (int16_t year, uint8_t month, uint8_t day)
| Factory method using separated year, month and day fields. More...
static LocalDate | forEpochDays (int32_t epochDays)
| Factory method using the number of days since the current epoch (usually 2000-01-01). More...
static LocalDate | forUnixDays (int32_t unixDays)
| Factory method using the number of days since Unix epoch 1970-01-01.
static LocalDate | forEpochSeconds (acetime_t epochSeconds)
| Factory method using the number of seconds since the current epoch year given by `currentEpochYear()`. More...
static LocalDate | forUnixSeconds64 (int64_t unixSeconds)
| Factory method that takes the 64-bit 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 Public Attributes
static const int16_t | kInvalidYear = INT16_MIN
| Sentinel year which indicates one or more of the following conditions: More...
static const int16_t | kMinYear = 0
| The smallest year that is expected to be handled by LocalDate. More...
static const int16_t | kMaxYear = 10000
| The largest year that is expected to be handled by LocalDate. More...
static const int32_t | kInvalidEpochDays = INT32_MIN
| Sentinel epochDays which indicates an error.
static const int32_t | kInvalidEpochSeconds = INT32_MIN
| Sentinel epochSeconds which indicates an error.
static const int64_t | kInvalidUnixSeconds64 = INT64_MIN
| Sentinel unixSeconds64 which indicates an error.
static const acetime_t | kMinEpochSeconds = INT32_MIN + 1
| Minimum valid epochSeconds. More...
static const acetime_t | kMaxEpochSeconds = INT32_MAX
| Maximum valid epochSeconds. More...
static const uint8_t | kMonday = 1
| Monday ISO 8601 number.
static const uint8_t | kTuesday = 2
| Tuesday ISO 8601 number.
static const uint8_t | kWednesday = 3
| Wednesday ISO 8601 number.
static const uint8_t | kThursday = 4
| Thursday ISO 8601 number.
static const uint8_t | kFriday = 5
| Friday ISO 8601 number.
static const uint8_t | kSaturday = 6
| Saturday ISO 8601 number.
static const uint8_t | kSunday = 7
| Sunday ISO 8601 number.

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

## Detailed Description

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

Normally, the range of the year field is [1,9999]. Occasionally, the year 0 is used to indicate -Infinity, with the month and day fields ignored. And the year 10000 is used to indicate +Infinity, with the month and day fields ignored. The value of INT16_MIN (-32768) is used to indicate an error condition.

The `toEpochDays()` and `fromEpochDays()` provides conversions of the (year, month, day) tuple to the number of days since the "epoch". The default epoch year is 2000, which makes the epoch date-time be 2000-01-01T00:00:00.

The epoch year can be changed using the static `currentEpochYear()` method. This is useful for dates larger than 2068-01-19T03:14:07, which is the largest date-time that can be represented using an `int32_t` type to hold the number of seconds since the epoch. For example, calling `currentEpochYear(2100)` will set the epoch to be 2100-01-01T00:00:00, so that dates from 2031-12-13 20:45:52Z to 2168-01-20T03:14:07 can be captured.

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 46 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 'this' occurs (before, same as, after) 'that'.

If either this->isError() or that.isError() is true, the behavior is undefined.

Definition at line 406 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 324 of file LocalDate.h.

## ◆ daysUntil()

int16_t ace_time::LocalDate::daysUntil | ( | uint8_t | month,
|  | uint8_t | day
| ) |  | const
| inline

Calculate number of days from current LocalDate to the next target (month, day).

For example, setting (month, day) of (12, 25) returns number of days until the next Christmas. This function should always return an integer in the interval [0, 365]. In a normal year, the maximum is 364. During a leap year, the maximum is 365.

Definition at line 391 of file LocalDate.h.

## ◆ forComponents()

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

Factory method using separated year, month and day fields.

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

Parameters

  year | [0,10000]
  month | month with January=1, December=12
  day | day of month [1-31]

Definition at line 153 of file LocalDate.h.

## ◆ forDateString()

static LocalDate ace_time::LocalDate::forDateString | ( | const char * | dateString | ) |
| inline 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 be between 0001 and 9999. Created for mostly for debugging purposes not for production use.

Parameters

  dateString | the date in ISO 8601 format (yyyy-mm-dd)

Definition at line 246 of file LocalDate.h.

## ◆ forDateStringChainable()

static LocalDate ace_time::LocalDate::forDateStringChainable | ( | const char *& | dateString | ) |
| inline 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 260 of file LocalDate.h.

## ◆ forEpochDays()

static LocalDate ace_time::LocalDate::forEpochDays | ( | int32_t | epochDays | ) |
| inline static

Factory method using the number of days since the current epoch (usually 2000-01-01).

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

Parameters

  epochDays | number of days since the current epoch

Definition at line 166 of file LocalDate.h.

## ◆ forEpochSeconds()

static LocalDate ace_time::LocalDate::forEpochSeconds | ( | acetime_t | epochSeconds | ) |
| inline static

Factory method using the number of seconds since the current epoch year given by `currentEpochYear()`.

The default is 2000-01-01, but can be changed using `currentEpochYear(epochYear)`.

The number of seconds from midnight of the given day is thrown away. For negative values of epochSeconds, the method to rounds down to the nearest day.

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

Parameters

  epochSeconds | number of seconds since the current epoch

Definition at line 205 of file LocalDate.h.

## ◆ forError()

static LocalDate ace_time::LocalDate::forError | ( |  | ) |
| inline static

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

The isError() method will return true.

Definition at line 291 of file LocalDate.h.

## ◆ forUnixSeconds64()

static LocalDate ace_time::LocalDate::forUnixSeconds64 | ( | int64_t | unixSeconds | ) |
| inline static

Factory method that takes the 64-bit 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. Valid over the entire range of year `[0,10000]` due to the use of `int64_t` operations.

Definition at line 224 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 58 of file LocalDate.cpp.

## ◆ toEpochDays()

int32_t ace_time::LocalDate::toEpochDays | ( |  | ) | const
| inline

Return number of days since the current epoch year `sCurrentEpochYear`.

By default, the current epoch year is 2000 so the epoch is 2000-01-01 00:00:00 UTC).

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

Definition at line 352 of file LocalDate.h.

## ◆ toEpochSeconds()

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

Return the number of seconds since the currentEpochYear().

Returns kInvalidEpochSeconds if isError() is true or if epochSeconds is out of range.

Definition at line 371 of file LocalDate.h.

## Member Data Documentation

## ◆ kInvalidYear

const int16_t ace_time::LocalDate::kInvalidYear = INT16_MIN
| static

Sentinel year which indicates one or more of the following conditions:

- an error condition, or
- a year that 'does not exist', or
- a year smaller than any valid year.

Some algorithms in ExtendedZoneProcessor assume that this value is smaller than any valid year, i.e. smaller than kMinYear.

Definition at line 58 of file LocalDate.h.

## ◆ kMaxEpochSeconds

const acetime_t ace_time::LocalDate::kMaxEpochSeconds = INT32_MAX
| static

Maximum valid epochSeconds.

Use LocalDate::forEpochSeconds() or LocalDateTime::forEpochSeconds() to obtain the maximum instance of those classes.

Definition at line 102 of file LocalDate.h.

## ◆ kMaxYear

const int16_t ace_time::LocalDate::kMaxYear = 10000
| static

The largest year that is expected to be handled by LocalDate.

The ZoneRule instances in the zoneinfo databases (zonedb, zonedbx) have a maximum `untilYear` value of 32767, so we have to make sure that we stay below that limit.

Definition at line 78 of file LocalDate.h.

## ◆ kMinEpochSeconds

const acetime_t ace_time::LocalDate::kMinEpochSeconds = INT32_MIN + 1
| static

Minimum valid epochSeconds.

The smallest int32, `INT32_MIN`, is used to indicate an invalid epochSeconds. Use LocalDate::forEpochSeconds() or LocalDateTime::forEpochSeconds() to obtain the minimum instance of those classes.

Definition at line 95 of file LocalDate.h.

## ◆ kMinYear

const int16_t ace_time::LocalDate::kMinYear = 0
| static

The smallest year that is expected to be handled by LocalDate.

The algorithms in the EpochConverterHinnant works for the propletic Gregorian calendar down to year 1. However, time zone offsets and shifting the year to start in March (to make computations involving leap days easier) may shift the year to 0. So this class is allowed to handle the year 0.

Definition at line 69 of file LocalDate.h.

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

- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/LocalDate.h
- /home/brian/src/AceTimeSuite/libraries/AceTimeLib/src/ace_time/LocalDate.cpp