Time is an immutable time class representing a time without a time zone in the ISO-8601 calendar system, such as "09:55:02". More...

#include <time.hpp>

Public Types
Durations
using	Nanoseconds = std::chrono::nanoseconds
	Nanosecond duration.

using	Microseconds = std::chrono::microseconds
	Microsecond duration.

using	Milliseconds = std::chrono::milliseconds
	Millisecond duration.

using	Seconds = std::chrono::seconds
	Second duration.

using	Minutes = std::chrono::minutes
	Minute duration.

using	Hours = std::chrono::hours
	Hour duration.

Public Member Functions
Constructors and Destructors
	Time ()
	Constructs an invalid Time object with every field is set to zero. More...

	Time (const Time &other)=default
	Copy-constructs a Time object from `other`.

	Time (Time &&other)=default
	Move-constructs a Time object from `other`.

	Time (std::time_t scalarStdTime)
	Constructs a Time object from the standard library std::time_t object `scalarStdTime`.

	Time (const std::tm &brokenStdTime)
	Constructs a Time object from the standard library std::tm object `brokenStdTime`.

	Time (const Duration &duration)
	Constructs a Time object from time `duration` elapsed since midnight ("00:00:00"). More...

	Time (const std::chrono::system_clock::time_point &timePoint)
	Constructs a Time object from the given system time point `timePoint`.

	Time (int hours, int minutes, int seconds)
	Constructs a Time object from the given `hours`, `minutes` and `seconds`.

	Time (int hours, int minutes, int seconds, int milliseconds)
	Constructs a Time object from the given `hours`, `minutes`, `seconds` and `milliseconds`.

	Time (int hours, int minutes, int seconds, const Duration &subseconds)
	Constructs a Time object from the given `hours`, `minutes`, `seconds`, and `subseconds`. More...

	Time (Hours hours, Minutes minutes, Seconds seconds, const Duration &subseconds)
	Constructs a Time object from the given `hours`, `minutes`, `seconds`, and `subseconds`. More...

	~Time ()=default
	Default destructor.

Assignment Operators
Time &	operator= (const Time &other)=default
	Copy assignment operator.

Time &	operator= (Time &&other)=default
	Move assignment operator.

Comparison Operators
The following operators compare this time to `other`. For example, if this time is smaller than `other`, it means that it is earlier than `other`.
bool	operator< (const Time &other) const
	Returns whether this time is earlier than `other`.

bool	operator<= (const Time &other) const
	Returns whether this time is earlier than `other` or equal to it.

bool	operator> (const Time &other) const
	Returns whether this time is later than `other`.

bool	operator>= (const Time &other) const
	Returns whether this time is later than `other` or equal to it.

bool	operator== (const Time &other) const
	Returns whether this time is equal to `other`.

bool	operator!= (const Time &other) const
	Returns whether this time is different from `other`.

Addition/Subtraction Operators
Time	operator+ (const Duration &duration) const
	Returns the result of adding `duration` to this time as a new Time object.

Time	operator- (const Duration &duration) const
	Returns the result of subtracting `duration` from this time as a new Time object.

Nanoseconds	operator- (const Time &other) const
	Returns the result of subtracting `other` from this time as a Time::Nanoseconds duration.

Querying Methods
bool	isValid () const
	Returns whether this time object represents a valid time. More...

long	nanosecond () const
	Returns the nanosecond of second (0, 999999999).

long	microsecond () const
	Returns the microsecond of second (0, 999999).

int	millisecond () const
	Returns the millisecond of second (0, 999).

int	second () const
	Returns the second of minute (0, 59).

int	minute () const
	Returns the minute of hour (0, 59).

int	hour () const
	Returns the hour of day (0, 23).

Addition/Subtraction Methods
Time	addNanoseconds (int nanoseconds) const
	Returns the result of adding `nanoseconds` to this time as a new Time object.

Time	subtractNanoseconds (int nanoseconds) const
	Returns the result of subtracting `nanoseconds` from this time as a new Time object.

Time	addMicroseconds (int microseconds) const
	Returns the result of adding `microseconds` to this time as a new Time object.

Time	subtractMicroseconds (int microseconds) const
	Returns the result of subtracting `microseconds` from this time as a new Time object.

Time	addMilliseconds (int milliseconds) const
	Returns the result of adding `milliseconds` to this time as a new Time object.

Time	subtractMilliseconds (int milliseconds) const
	Returns the result of subtracting `milliseconds` from this time as a new Time object.

Time	addSeconds (int seconds) const
	Returns the result of adding `seconds` to this time as a new Time object.

Time	subtractSeconds (int seconds) const
	Returns the result of subtracting `seconds` from this time as a new Time object.

Time	addMinutes (int minutes) const
	Returns the result of adding `minutes` to this time as a new Time object.

Time	subtractMinutes (int minutes) const
	Returns the result of subtracting `minutes` from this time as a new Time object.

Time	addHours (int hours) const
	Returns the result of adding `hours` to this time as a new Time object.

Time	subtractHours (int hours) const
	Returns the result of subtracting `hours` from this time as a new Time object.

Time	addDuration (const Duration &duration) const
	Returns the result of adding `duration` to this time as a new Time object.

Time	subtractDuration (const Duration &duration) const
	Returns the result of subtracting `duration` from this time as a new Time object.

Conversion Methods
long long	toNanosecondsSinceMidnight () const
	Returns the elapsed nanoseconds since midnight.

long long	toMicrosecondsSinceMidnight () const
	Returns the elapsed microseconds since midnight.

long	toMillisecondsSinceMidnight () const
	Returns the elapsed milliseconds since midnight.

long	toSecondsSinceMidnight () const
	Returns the elapsed seconds since midnight.

int	toMinutesSinceMidnight () const
	Returns the elapsed minutes since midnight.

int	toHoursSinceMidnight () const
	Returns the elapsed hours since midnight. If this time is invalid, the returned value may exceed 23. More...

Nanoseconds	toStdDurationSinceMidnight () const
	Returns the elapsed time since midnight as a Nanoseconds duration.

std::tm	toBrokenStdTime () const
	Returns a std::tm representation of this time.

std::time_t	toScalarStdTime () const
	Returns a std::time_t representation of this time.

std::string	toString (const std::string &format) const
	Returns the time as a string formatted according to the format string `format`. More...

Static Public Member Functions
static Time	current ()
	Returns a Time object set to the current time obtained from the system clock. More...

static Time	midnight ()
	Returns a Time object set to midnight (i.e., "00:00:00").

static Time	fromString (const std::string &time, const std::string &format)
	Returns a Time object from the string `time` according to the format string `format`. More...

Calculation Methods
The following methods return the time difference between two times: `from` and `to`. If `from` is smaller than (earlier than) `to`, then the difference is negative.
static long long	nanosecondsBetween (const Time &from, const Time &to)
	Returns the number of nanoseconds between `from` and `to`.

static long long	microsecondsBetween (const Time &from, const Time &to)
	Returns the number of microseconds between `from` and `to`.

static long	millisecondsBetween (const Time &from, const Time &to)
	Returns the number of milliseconds between `from` and `to`.

static long	secondsBetween (const Time &from, const Time &to)
	Returns the number of seconds between `from` and `to`.

static int	minutesBetween (const Time &from, const Time &to)
	Returns the number of minutes between `from` and `to`.

static int	hoursBetween (const Time &from, const Time &to)
	Returns the number of hours between `from` and `to`.

Related Functions
(Note that these are not member functions.)
Input/Output Operators
std::ostream &	operator<< (std::ostream &os, const Time &t)
	Writes time `t` to stream `os` in ISO-8601 time format "hh:mm:ss.fff". See toString() for information about the format patterns.

std::istream &	operator>> (std::istream &is, Time &t)
	Reads a time in ISO-8601 time format "hh:mm:ss.fff" from stream `is` and stores it in time `t`. See toString() for information about the format patterns.

Detailed Description

Time is an immutable time class representing a time without a time zone in the ISO-8601 calendar system, such as "09:55:02".

Time is represented by nanosecond precision. For example, the value "09:55:02.123456789" can be stored in a Time object. Time uses the 24-hour clock format. Internally, it describes the time as the number of nanoseconds since midnight. Time provides methods for comparing times, manipulating a time by adding or subtracting durations, and converting the whole time into minutes, seconds, or any finer duration.

A Time object can be created by giving the number of hours, minutes, seconds, milliseconds, etc. explicitly. Also, it can be created from std::time_t, std::tm, or std::chrono::system_clock::time_point objects.

A default-constructed time object is invalid (calling isValid() on it returns false). The static method current() can be used to get the current time from the system's clock. Note that the accuracy depends on the accuracy of the underlying operating system; not all systems provide 1-millisecond accuracy.

The methods hour(), minute(), second(), millisecond(), microsecond(), and nanosecond() provide access to the number of hours, minutes, seconds, milliseconds, microseconds, and nanoseconds of the time, respectively.

Time supports the C++11 chrono library's way of manipulating time, i.e., time constructors and methods can take duration parameters such as std::chrono::hours(1), std::chrono::minutes(1), etc. For convenience, Time defines aliases for these durations, which may be used instead of chrono's ones. Time durations are Hours, Minutes, Seconds, Milliseconds, Microseconds, and Nanoseconds, which correspond to std:chrono::hours, std:chrono::minutes, std:chrono::seconds, std:chrono::milliseconds, std:chrono::microseconds, and std:chrono::nanoseconds, respectively.

The methods toHours(), toMinutes(), toSeconds(), toMilliseconds(), toMicroseconds(), and toNanoseconds() return the whole time passed since midnight as a number of hours, minutes, seconds, milliseconds, microseconds, or nanoseconds, respectively.

The toString() method can be used to get a textual representation of the time formatted according to a given format string.

Time provides the comparison operators to compare two Time objects. Time A is considered earlier than Time B if A is smaller than B, and so on. Time also provides methods to compute the difference between two times in hours, minutes, etc.

See also: The unit tests in time.h for further details.

Constructor & Destructor Documentation

◆ Time() [1/4]

xclox::Time::Time ( )

inline

Constructs an invalid Time object with every field is set to zero.

See also: isValid()

◆ Time() [2/4]

xclox::Time::Time ( const Duration & duration )

inlineexplicit

Constructs a Time object from time duration elapsed since midnight ("00:00:00").

For example:

Time myTime(Time::Hours(2) + Time::Minutes(55));

xclox::Time::Time

Time()

Constructs an invalid Time object with every field is set to zero.

Definition: time.hpp:71

xclox::Time::Minutes

std::chrono::minutes Minutes

Minute duration.

Definition: time.hpp:60

xclox::Time::Hours

std::chrono::hours Hours

Hour duration.

Definition: time.hpp:61

Parameters

duration can be Time::Duration or std::chrono::duration.

◆ Time() [3/4]

xclox::Time::Time	(	int	hours,
		int	minutes,
		int	seconds,
		const Duration &	subseconds
	)

inlineexplicit

Constructs a Time object from the given hours, minutes, seconds, and subseconds.

The subseconds parameter can be any fine duration of Time such as Time::Microseconds(54), or any fine duration of chrono, such as std::chrono::nanoseconds(435223543).

◆ Time() [4/4]

xclox::Time::Time	(	Hours	hours,
		Minutes	minutes,
		Seconds	seconds,
		const Duration &	subseconds
	)

inlineexplicit

Constructs a Time object from the given hours, minutes, seconds, and subseconds.

All parameters can be Time::Duration or std::chrono::duration. For example:

Time myTime(Time::Hours(2), Time::Minutes(55), Time::Seconds(10), Time::Nanoseconds(435223543));

Time sameTime(std::chrono::hours(2), std::chrono::::minutes(55), std::chrono::::seconds(10), std::chrono::::nanoseconds(435223543));

xclox::Time::Nanoseconds

std::chrono::nanoseconds Nanoseconds

Nanosecond duration.

Definition: time.hpp:56

xclox::Time::Seconds

std::chrono::seconds Seconds

Second duration.

Definition: time.hpp:59

Member Function Documentation

◆ current()

static Time xclox::Time::current ( )

inlinestatic

Returns a Time object set to the current time obtained from the system clock.

Note that the returned time is not the current local time, but rather the current system time, i.e., the current time in Coordinated Universal Time (UTC).

◆ fromString()

static Time xclox::Time::fromString	(	const std::string &	time,
		const std::string &	format
	)

inlinestatic

Returns a Time object from the string time according to the format string format.

The format patterns are the same patterns used in the method toString().

See also: toString()

◆ isValid()

bool xclox::Time::isValid ( ) const

inline

Returns whether this time object represents a valid time.

A valid time is a fraction of a day; the time to be valid must be between 00:00:00 and 23:59:59. Thus, negative times or times containing 24 hours or more are considered invalid.

Time t1; // t1.isValid(); returns false.
Time t2(0, 0, 0); // t2.isValid(); returns true.
Time t3(22, 1, 55); // t3.isValid(); returns true.
Time t4(-1, 0, 0); // t4.isValid(); returns false.
Time t5(Time::Hours(24)); // t5.isValid(); returns false.
Time t6(Time::Hours(-1)); // t6.isValid(); returns false.
Time t7(Time::Seconds(1)); // t7.isValid(); returns true.
Time t8(std::chrono::system_clock::now()); // t8.isValid(); returns true.

◆ toHoursSinceMidnight()

int xclox::Time::toHoursSinceMidnight ( ) const

inline

Returns the elapsed hours since midnight. If this time is invalid, the returned value may exceed 23.

See also: isValid().

◆ toString()

std::string xclox::Time::toString ( const std::string & format ) const

inline

Returns the time as a string formatted according to the format string format.

The formatting string may contain the following patterns:

Pattern	Meaning
h	one-digit hour (0, 23)
hh	two-digit hour (00, 23)
H	one-digit hour (1, 12)
HH	two-digit hour (01, 12)
m	one-digit minute (0, 59)
mm	two-digit minute (00, 59)
s	one-digit second (0, 59)
ss	two-digit second (00, 59)
f	one-digit subsecond (0, 9)
ff	two-digit subsecond (00, 99)
fff	three-digit subsecond (000, 999)
ffff	four-digit subsecond (0000, 9999)
fffff	five-digit subsecond (00000, 99999)
ffffff	six-digit subsecond (000000, 999999)
fffffff	seven-digit subsecond (0000000, 9999999)
ffffffff	eight-digit subsecond (00000000, 99999999)
fffffffff	nine-digit subsecond (000000000, 999999999)
a	before/after noon indicator(i.e. am or pm)
A	before/after noon indicator(i.e. AM or PM)

Any character in the format string not listed above will be inserted as-is into the output string. If this time is invalid, an empty string will be returned.

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

include/xclox/time.hpp

Public Types

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Time() [1/4]

◆ Time() [2/4]

◆ Time() [3/4]

◆ Time() [4/4]

Member Function Documentation

◆ current()

◆ fromString()

◆ isValid()

◆ toHoursSinceMidnight()

◆ toString()