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

Represents a period of time relative to some known point in time, potentially represented by a DateTime. More...

`#include <TimePeriod.h>`

## Public Member Functions
| TimePeriod (uint8_t hour, uint8_t minute, uint8_t second, int8_t sign=1)
| Constructor. More...
| TimePeriod (int32_t seconds=0)
| Constructor from number of seconds. More...
uint8_t | hour () const
| Return the hour.
void | hour (uint8_t hour)
| Set the hour. More...
uint8_t | minute () const
| Return the minute.
void | minute (uint8_t minute)
| Set the minute. More...
uint8_t | second () const
| Return the second.
void | second (uint8_t second)
| Set the second. More...
int8_t | sign () const
| Return the sign bit.
void | sign (int8_t sign)
| Set the sign bit. More...
int32_t | toSeconds () const
| Convert to number of seconds. More...
bool | isError () const
| Return true if this represents an error. More...
int8_t | compareTo (const TimePeriod &that) const
| Compare 'this' TimePeriod with 'that' TimePeriod and return (<0, 0, >0) according to (this<that, this==that, this>that). More...
void | printTo (Print &printer) const
| Print to given printer. More...
| TimePeriod (const TimePeriod &)=default
TimePeriod & | operator= (const TimePeriod &)=default

## Static Public Member Functions
static TimePeriod | forError (int8_t sign=0)
| Factory method that creates a TimePeriod representing a generic error so that isError() returns true. More...

## Static Public Attributes
static const int32_t | kInvalidPeriodSeconds = INT32_MIN
| An invalid time period seconds.
static const int32_t | kMaxPeriodSeconds = 921599
| The largest period that can be represented by this class, in seconds, corresponding to +/- 255h59m59s. More...

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

## Detailed Description

Represents a period of time relative to some known point in time, potentially represented by a DateTime.

Each component (hour, minute, second) is stored as an unsigned byte (uint8_t). The sign bit allows forward and backward time periods to be represented.

There are 3 conditions which return isError() true:

- generic error: sign == 0
- overflow: sign == 1
- underflow: sign == -1

Definition at line 27 of file TimePeriod.h.

## Constructor & Destructor Documentation

## ◆ TimePeriod() [1/2]

ace_time::TimePeriod::TimePeriod | ( | uint8_t | hour,
|  | uint8_t | minute,
|  | uint8_t | second,
|  | int8_t | sign = `1`
| ) |  |
| inline explicit

Constructor.

No input validation or normalization is performed by this constructor.

Parameters

  hour | hour (0-255)
  minute | minute (0-59)
  second | second (0-59)
  sign | The sign bit. Should be either +1 or -1. Any other value may cause the isError() method to return true.

Definition at line 60 of file TimePeriod.h.

## ◆ TimePeriod() [2/2]

ace_time::TimePeriod::TimePeriod | ( | int32_t | seconds = `0` | ) |
| inline explicit

Constructor from number of seconds.

The largest valid 'seconds' is +/- 921599 corresponding to (hour=255, minute=59, second=59). For larger number or smaller values, an error object will be returned whose isError() returns true.

Parameters

  seconds | number of seconds (default 0)

Definition at line 75 of file TimePeriod.h.

## Member Function Documentation

## ◆ compareTo()

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

Compare 'this' TimePeriod with 'that' TimePeriod and return (<0, 0, >0) according to (this<that, this==that, this>that).

If either 'this' or 'that' returns true for isError(), then the result is undefined.

Definition at line 162 of file TimePeriod.h.

## ◆ forError()

static TimePeriod ace_time::TimePeriod::forError | ( | int8_t | sign = `0` | ) |
| inline static

Factory method that creates a TimePeriod representing a generic error so that isError() returns true.

Parameters

  sign | optional sign value which indicates generic error (0, default), overflow (1), or underflow (-1).

Definition at line 46 of file TimePeriod.h.

## ◆ hour()

void ace_time::TimePeriod::hour | ( | uint8_t | hour | ) |
| inline

Set the hour.

Should be between [0, 255]. No error checking is done.

Definition at line 107 of file TimePeriod.h.

## ◆ isError()

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

Return true if this represents an error.

Check the sign() value to descriminate the 3 different error conditions:

- sign==0: generic error
- sign==1: overflow
- sign==-1: underflow

Definition at line 153 of file TimePeriod.h.

## ◆ minute()

void ace_time::TimePeriod::minute | ( | uint8_t | minute | ) |
| inline

Set the minute.

Should be between [0, 59]. No error checking is done.

Definition at line 113 of file TimePeriod.h.

## ◆ printTo()

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

Print to given printer.

If the time period is negative, a minus sign is prepended. If the TimePeriod is an error, prints the following:

- sign == 0, generic error: <Error>
- sign == 1, overflow: <+Inf>
- sign == -1, underflow: <-Inf>

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 TimePeriod.cpp.

## ◆ second()

void ace_time::TimePeriod::second | ( | uint8_t | second | ) |
| inline

Set the second.

Should be between [0, 59]. No error checking is done.

Definition at line 119 of file TimePeriod.h.

## ◆ sign()

void ace_time::TimePeriod::sign | ( | int8_t | sign | ) |
| inline

Set the sign bit.

Should be either +1 or -1. Setting it to 0 causes isError() to return true, to indicate a generic error condition. Any other value caused undefined behavior.

Definition at line 129 of file TimePeriod.h.

## ◆ toSeconds()

int32_t ace_time::TimePeriod::toSeconds | ( |  | ) | const
| inline

Convert to number of seconds.

For a normal TimePeriod, the maximum and minimum values are +kMaxPeriodSeconds or -kMaxPeriodSeconds. If isError() is true, this returns kInvalidPeriodSeconds.

Definition at line 136 of file TimePeriod.h.

## Friends And Related Function Documentation

## ◆ operator==

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

Return true if two TimePeriod objects are equal.

Optimized for small changes in the less signficant fields.

Definition at line 211 of file TimePeriod.h.

## Member Data Documentation

## ◆ kMaxPeriodSeconds

const int32_t ace_time::TimePeriod::kMaxPeriodSeconds = 921599
| static

The largest period that can be represented by this class, in seconds, corresponding to +/- 255h59m59s.

The same limit applies in the positive and negative direction.

Definition at line 37 of file TimePeriod.h.

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

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