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::LocalTime Class Reference

The time (hour, minute, second) fields representing the time without regards to the day or the time zone. More...

`#include <LocalTime.h>`

## Public Member Functions
| LocalTime ()
| Default constructor does nothing.
bool | isError () const
| Return true if any component is outside the normal time range of 00:00:00 to 23:59:59. More...
uint8_t | hour () const
| Return the hour.
void | hour (uint8_t hour)
| Set the hour.
uint8_t | minute () const
| Return the minute.
void | minute (uint8_t minute)
| Set the minute.
uint8_t | second () const
| Return the second.
void | second (uint8_t second)
| Set the second.
uint8_t | fold () const
| Return the fold.
void | fold (uint8_t fold)
| Set the fold.
acetime_t | toSeconds () const
| Return the number of seconds since midnight. More...
int8_t | compareTo (const LocalTime &that) const
| Compare 'this' LocalTime with 'that' LocalTime, and return (<0, 0, >0) according to whether 'this' occurs (before, same as, after) 'that'. More...
void | printTo (Print &printer) const
| Print LocalTime to 'printer' in ISO 8601 format. More...
| LocalTime (const LocalTime &)=default
LocalTime & | operator= (const LocalTime &)=default

## Static Public Member Functions
static LocalTime | forComponents (uint8_t hour, uint8_t minute, uint8_t second, uint8_t fold=0)
| Factory method using separated date, time, and time zone fields. More...
static LocalTime | forSeconds (acetime_t seconds, uint8_t fold=0)
| Factory method. More...
static LocalTime | forTimeString (const char *timeString)
| Factory method. More...
static LocalTime | forTimeStringChainable (const char *&timeString)
| Variant of forTimeString() that updates the pointer to the next unprocessed character. More...
static LocalTime | forError ()
| Factory method that returns an instance which indicates an error condition. More...

## Static Public Attributes
static const int32_t | kInvalidSeconds = INT32_MIN
| An invalid seconds marker that indicates isError() true.

## Friends
bool | operator== (const LocalTime &a, const LocalTime &b)
| Return true if two LocalTime objects are equal. More...

## Detailed Description

The time (hour, minute, second) fields representing the time without regards to the day or the time zone.

The valid range is 00:00:00 to 23:59:59. Trying to create an instance outside of this range causes the isError() method to return true, and toSeconds() returns kInvalidSeconds.

Parts of this class were inspired by the java.time.LocalTime class of Java 11 (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/LocalTime.html). The 'fold' parameter was inspired by the datetime package in Python 3.6.

Definition at line 27 of file LocalTime.h.

## Member Function Documentation

## ◆ compareTo()

int8_t ace_time::LocalTime::compareTo | ( | const LocalTime & | that | ) | const
| inline

Compare 'this' LocalTime with 'that' LocalTime, and return (<0, 0, >0) according to whether 'this' occurs (before, same as, after) 'that'.

The 'fold' parameter is ignored.

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

Definition at line 162 of file LocalTime.h.

## ◆ forComponents()

static LocalTime ace_time::LocalTime::forComponents | ( | uint8_t | hour,
|  | uint8_t | minute,
|  | uint8_t | second,
|  | uint8_t | fold = `0`
| ) |  |
| inline static

Factory method using separated date, time, and time zone fields.

The dayOfWeek will be lazily evaluated. No data validation is performed on the fields on construction, but if any field is out of range, then isError() will return true.

Parameters

  hour | hour (0-23)
  minute | minute (0-59)
  second | second (0-59), does not support leap seconds
  fold | optional disambiguation of multiple occurrences [0, 1]

Definition at line 43 of file LocalTime.h.

## ◆ forError()

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

Factory method that returns an instance which indicates an error condition.

The isError() method will return true.

Definition at line 95 of file LocalTime.h.

## ◆ forSeconds()

static LocalTime ace_time::LocalTime::forSeconds | ( | acetime_t | seconds,
|  | uint8_t | fold = `0`
| ) |  |
| inline static

Factory method.

Create the various components of the LocalTime from the number of seconds from midnight. If kInvalidSeconds is given, the isError() condition is set to be true. The behavior is undefined if seconds is greater than 86399.

Parameters

  seconds | number of seconds from midnight, (0-86399)

Definition at line 56 of file LocalTime.h.

## ◆ forTimeString()

LocalTime ace_time::LocalTime::forTimeString | ( | const char * | timeString | ) |
| static

Factory method.

Create a LocalTime from the ISO 8601 time string. If the string cannot be parsed, then returns LocalTime::forError(). However, the data validation on parsing is very weak and the behavior is undefined for most invalid time strings.

Parameters

Definition at line 28 of file LocalTime.cpp.

## ◆ forTimeStringChainable()

LocalTime ace_time::LocalTime::forTimeStringChainable | ( | const char *& | timeString | ) |
| static

Variant of forTimeString() 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 36 of file LocalTime.cpp.

## ◆ isError()

bool ace_time::LocalTime::isError | ( |  | ) | const
| inline

Return true if any component is outside the normal time range of 00:00:00 to 23:59:59.

We add the exception that 24:00:00 is also considered valid to allow ExtendedZoneProcessor (and maybe BasicZoneProcessor) to support midnight transitions from the TZ Database.

Definition at line 108 of file LocalTime.h.

## ◆ printTo()

void ace_time::LocalTime::printTo | ( | Print & | printer | ) | const

Print LocalTime to 'printer' in ISO 8601 format.

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

Definition at line 14 of file LocalTime.cpp.

## ◆ toSeconds()

acetime_t ace_time::LocalTime::toSeconds | ( |  | ) | const
| inline

Return the number of seconds since midnight.

Return kInvalidSeconds if isError() is true.

Definition at line 145 of file LocalTime.h.

## Friends And Related Function Documentation

## ◆ operator==

bool operator== | ( | const LocalTime & | a,
|  | const LocalTime & | b
| ) |  |
| friend

Return true if two LocalTime objects are equal.

The fold is ignored.

Definition at line 220 of file LocalTime.h.

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

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