ROSE  0.11.109.0
Public Member Functions | Static Public Member Functions | List of all members
Sawyer::Time Class Reference

Description

Represents an ISO 8601 time point.

Definition at line 20 of file Time.h.

#include <util/Sawyer/Time.h>

Public Member Functions

 Time ()
 Construct an empty time point. More...
 
bool isEmpty () const
 Test whether this object is empty. More...
 
bool hasDate () const
 Test whether date is present. More...
 
bool hasTime () const
 Test whether time is present. More...
 
bool hasZone () const
 Test whether a timezone is present. More...
 
bool hasSpecificDate () const
 Test whether a date is fully specified. More...
 
bool hasSpecificTime () const
 Test whether a time is fully specified. More...
 
Time resolve (const Time &) const
 Fill in missing fields. More...
 
Time lowerBound () const
 Returns the lower bound for the time. More...
 
Result< Time, std::string > upperBound () const
 Returns an upper bound for the time. More...
 
Time noDate () const
 Removes the date portion of a time point. More...
 
Time noTime () const
 Removes the time portion of a time point. More...
 
Time noZone () const
 Removes the timezone portion of a time point. More...
 
const Optional< unsigned > & year () const
 Returns the year, if any. More...
 
const Optional< unsigned > & month () const
 Returns the month, if any. More...
 
const Optional< unsigned > & day () const
 Returns the day of the month, if any. More...
 
const Optional< unsigned > & hour () const
 Returns the hour, if any. More...
 
const Optional< unsigned > & minute () const
 Returns the minute, if any. More...
 
const Optional< unsigned > & second () const
 Returns the second, if any. More...
 
const Optional< int > & timeZoneHour () const
 Returns a timezone hour, if any. More...
 
const Optional< int > & timeZoneMinute () const
 Returns a timezone minute, if any. More...
 
Result< Time, std::string > toZulu () const
 Convert to timezone +0000. More...
 
std::string toString () const
 Convert a time point to ISO 8601 format. More...
 
Result< time_t, std::string > toUnix () const
 Convert the time point to a Unix system time. More...
 
bool operator< (const Time &) const
 Compare two times for less-than. More...
 
bool operator== (const Time &) const
 Compare two times for equality or inequality. More...
 
bool operator!= (const Time &) const
 Compare two times for equality or inequality. More...
 

Static Public Member Functions

static Result< Time, std::string > parse (const std::string &)
 Parse an ISO 8601 time string. More...
 
static Time now ()
 Current time. More...
 

Constructor & Destructor Documentation

Sawyer::Time::Time ( )

Construct an empty time point.

The constructed object has no date, no time, and no timezone.

Member Function Documentation

static Result<Time, std::string> Sawyer::Time::parse ( const std::string &  )
static

Parse an ISO 8601 time string.

Returns either a time or an error description.

static Time Sawyer::Time::now ( )
static

Current time.

Returns the current time.

bool Sawyer::Time::isEmpty ( ) const

Test whether this object is empty.

Returns true if this time point has no date or time. It does not matter if a timezone is present.

bool Sawyer::Time::hasDate ( ) const

Test whether date is present.

Returns true if a date (year, month, or day) is present.

bool Sawyer::Time::hasTime ( ) const

Test whether time is present.

Returns true if a time (hour, minute, second) is present.

bool Sawyer::Time::hasZone ( ) const

Test whether a timezone is present.

Returns true if a timezone is present.

bool Sawyer::Time::hasSpecificDate ( ) const

Test whether a date is fully specified.

Returns true if a year, month, and day are all present.

bool Sawyer::Time::hasSpecificTime ( ) const

Test whether a time is fully specified.

Returns true if a time is fully specified. I.e., if a year, month, day, hour, minute, and second are all present.

Time Sawyer::Time::resolve ( const Time ) const

Fill in missing fields.

Returns a new time whose fields are individually initialized to be from this object or another object. If this object has a value for a field then it's used, otherwise the value comes from the other object.

Time Sawyer::Time::lowerBound ( ) const

Returns the lower bound for the time.

Returns a time point that has a fully specified time (year, month, day, hour, minute, and second) such that it is the latest time not past the time specified by this time point. For instance, if this time point is "2022-06-30 11:30" (no seconds specified) then the lower bound is created by adding "00" as the seconds to give "2022-06-30 11:30:00".

If this time point has only a time but no date, then the returned time will also not have a date portion. For instance, if this time point is "11:30" then the return value is "11:30:00". If this time has only a timezone, then the result also has only a timezone.

The returned timezone is identical to the time zone from the input time point.

Result<Time, std::string> Sawyer::Time::upperBound ( ) const

Returns an upper bound for the time.

Returns a time point that has a fully specified time (year, month, day, hour, minute, and second) such that it is the earliest time that is past the time specified by this time point. For instance, if this time point is fully specified as "2022-06-30 11:30:00" then the return value is the next second, namely "2022-06-30 11:30:01". If this time point is partially specified as "2022-06-30 11:30" then the return value is the next minute, namely "2022-06-30 11:31:00".

If this time point has no date, then the return value also has no date, in which case it's possible for the return value to be earlier than the input value. For instance, if this time point is the last second of the day "23:59:59", then the return value will be the first second of the (next) day: "00:00:00". Similarly, a partially specified last minute of a day gets converted to the first minute of the next day, "23:59" to "00:00:00".

If the return value would have a year that's larger 9999, then an error is returned. For instance, the upper bound for "9999-12-31" is "10000-01-01 00:00:00", which exceeds what can be represented by ISO 8601.

The returned timezone is identical to the time zone from the input time point.

Time Sawyer::Time::noDate ( ) const

Removes the date portion of a time point.

Returns a copy of this time but without a year, month, and day.

Time Sawyer::Time::noTime ( ) const

Removes the time portion of a time point.

Returns a copy of this time but without an hour, minute, or second.

Time Sawyer::Time::noZone ( ) const

Removes the timezone portion of a time point.

Returns a copy of this time but without a timezone.

const Optional<unsigned>& Sawyer::Time::year ( ) const

Returns the year, if any.

A year can be anything between 1583 and 9999, inclusive.

const Optional<unsigned>& Sawyer::Time::month ( ) const

Returns the month, if any.

A month can be in the range 1 through 12, inclusive. If a month is present, then a year is also present.

const Optional<unsigned>& Sawyer::Time::day ( ) const

Returns the day of the month, if any.

The day of the month can be in the range 1 through 28, 29, 30, or 31 depending on the year and month. If a day of month is present, then the year and month are also present.

const Optional<unsigned>& Sawyer::Time::hour ( ) const

Returns the hour, if any.

An hour is in the range 0 through 23, inclusive.

const Optional<unsigned>& Sawyer::Time::minute ( ) const

Returns the minute, if any.

A minute is in the range 0 through 59, inclusive. If a minute is present, then an hour is also present.

const Optional<unsigned>& Sawyer::Time::second ( ) const

Returns the second, if any.

A second is in the range 0 through 60, inclusive. A value of 60 represents a leap second. If a second is present, then an hour and minute are also present.

const Optional<int>& Sawyer::Time::timeZoneHour ( ) const

Returns a timezone hour, if any.

The timezone hour is a signed integer between -23 and 23, inclusive and represents the distance east of the prime meridian. Positive values are east; negative values are west.

const Optional<int>& Sawyer::Time::timeZoneMinute ( ) const

Returns a timezone minute, if any.

The timezone minute is a value between -59 and 59, inclusive and has the same sign as the timezone hour. If a timezone minute is present then a timezone hour is also present.

Result<Time, std::string> Sawyer::Time::toZulu ( ) const

Convert to timezone +0000.

The hours and minutes of this time's timezone is subtracted from this time in order to create a new time whose time zone is +0000. If the input time has no timezone or has no time, then the output is the same as the input. The seconds field is always unchanged. If the time zone minute field is unspecified, then it is assumed to be zero for the purpose of subtraction. If the time minute field is unspecified, then it is assumed to be zero for the purpose of the subtraction and will remain unspecified in the result. If the input has a time but no date, then the time will be adjusted but the return value will also not have a date.

It's possible that the normalized time does not fall within the range of times representable by this type. If that happens, then an error string is returned instead of a valid time.

std::string Sawyer::Time::toString ( ) const

Convert a time point to ISO 8601 format.

Returns this time point as an ISO 8601 string that can be parsed by this same class. This function generates the string using the extended format for ISO 8601. That is, the parts of a date are separated by a hyphen, the parts of the time and timezone are separated by colons, and the time is separated from the date by a space. Only the parts that are present are output. An empty time point without a timezone will result in an empty string being returned.

Result<time_t, std::string> Sawyer::Time::toUnix ( ) const

Convert the time point to a Unix system time.

Returns the number of seconds since "1970-01-01 00:00:00Z". Returns an error string if this time point does not have a specific time. If no timezone is present, then the return value is local time.

bool Sawyer::Time::operator== ( const Time ) const

Compare two times for equality or inequality.

Two times are equal if, after converting them both to the same timezone, they have the same year, month, day, hour, minute, and second for all such fields where either or both times have a value. Fields are considered equal if neither time has a value for that field.

If either or both times fail to convert to Zulu due to overflows, then they are neither equal nor unequal.

bool Sawyer::Time::operator!= ( const Time ) const

Compare two times for equality or inequality.

Two times are equal if, after converting them both to the same timezone, they have the same year, month, day, hour, minute, and second for all such fields where either or both times have a value. Fields are considered equal if neither time has a value for that field.

If either or both times fail to convert to Zulu due to overflows, then they are neither equal nor unequal.

bool Sawyer::Time::operator< ( const Time ) const

Compare two times for less-than.

Time a is less than time b if a occurs earlier than b after normalizing both to Zulu. If the conversion to Zulu fails for both times, then the result is the comparison of the error strings. If only one of the times fails to convert, then that one is less than the other. If a field is missing from both times, then that field is considered to be equal (e.g., if both times are missing the month). If the field is missing from a but not b, then a is less than b. The fields are compared in order from year to second, followed by the timezone hour and then timezone minute (although the timezone comparisons are only based on their presence or absense since they've both been converted to Zulu).


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