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`
	)

inlineexplicit

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 )

inlineexplicit

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 )

inlinestatic

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ TimePeriod() [1/2]

◆ TimePeriod() [2/2]

Member Function Documentation

◆ compareTo()

◆ forError()

◆ hour()

◆ isError()

◆ minute()

◆ printTo()

◆ second()

◆ sign()

◆ toSeconds()

Friends And Related Function Documentation

◆ operator==

Member Data Documentation

◆ kMaxPeriodSeconds