DateTime represents a particular date and time down to the nanosecond level along with timezone information. More...

#include "datetime.h"

Classes
class	Range
	A class to contain a beginning and ending DateTime. More...

Public Types
enum	DateTimeField { kYear = 0, kMonth = 1, kDay = 2, kHour = 3, kMinute = 4, kSecond = 5, kNanosecond = 6, kNumFields }
	Enumeration of the time-value fields of DateTime (used for iteration and numerical access). More...

enum	DateStringEnum { kRenderDayMonthYear = 1, kRenderMonthYear, kRenderYearOnly }
	ComputeDateString() and ComputeTimeString() render the DateTime object to a std::string. More...

enum	TimeStringEnum { kRenderHoursMinutesSeconds = 1, kRenderHoursMinutes, kRenderHoursOnly }

Public Member Functions
	DateTime ()

	DateTime (const DateTime &rhs)

	DateTime (int64 year, uint8 month, uint8 day, uint8 hour, uint8 minute, uint8 second, uint32 nanosec=0, int8 zone_hours=0, int8 zone_minutes=0)

	DateTime (std::chrono::system_clock::time_point time, int8 zone_hours=0, int8 zone_minutes=0)

virtual	~DateTime ()

int64	GetYear () const
	Accessors for all fields. More...

uint8	GetMonth () const

uint8	GetDay () const

uint8	GetHour () const

uint8	GetMinute () const

uint8	GetSecond () const

uint32	GetNanosecond () const

int8	GetZoneHours () const

int8	GetZoneMinutes () const

void	SetYear (int64 year)
	Mutators for individual fields. More...

void	SetMonth (uint8 month)

void	SetDay (uint8 day)

void	SetHour (uint8 hour)

void	SetMinute (uint8 minute)

void	SetSecond (uint8 second)

void	SetNanosecond (uint32 nanosecond)

void	SetZoneHours (int8 zone_hours)

void	SetZoneMinutes (int8 zone_minutes)

void	Reset ()
	Set the DateTime to default values (<year>/1/1T00:00:00.0Z00:00, where <year> is set as `kUndefinedYear`. More...

void	Set (int64 years, uint8 months, uint8 days, uint8 hours, uint8 minutes, uint8 seconds, int8 zone_hours, int8 zone_minutes)

void	Set (int64 years, uint8 months, uint8 days, uint8 hours, uint8 minutes, uint8 seconds, uint32 nanoseconds, int8 zone_hours, int8 zone_minutes)

void	Set (const DateTime &other)

void	Normalize ()
	Converts this DateTime to UTC time (+0:00 time zone). More...

bool	IsEqualByComponent (const DateTime &dtime) const
	Checks each component of the time object, including time zone. More...

bool	operator== (const DateTime &dtime) const
	This operator converts the date times to absolute and compares the absolute times for equality (hence time zone comparison is omitted). More...

bool	operator> (const DateTime &dtime) const

bool	operator< (const DateTime &dtime) const

bool	operator>= (const DateTime &dtime) const

bool	operator<= (const DateTime &dtime) const

bool	operator!= (const DateTime &dtime) const

DateTime &	operator= (const DateTime &rhs)

std::chrono::system_clock::time_point	GetTimePoint () const
	Return a std::chrono::system_clock::time_point. More...

template<typename Rep = double>
Rep	GetPosixSeconds () const
	Return the number of seconds offset from the POSIX epoch, as a given type `Rep`. More...

void	Lerp (const DateTime &origin, const DateTime &target, double t)
	Set the current time to the interpolation of the two given times according to the interpolant, normalized on [0-1]. More...

void	AdjustTimeZone (int newHours, int newMins)
	Converts time to another time zone. More...

std::string	ToString () const
	Converts time to user-readable string. More...

bool	FromString (const std::string &str)
	Parses `str` into this DateTime object. More...

void	ComputeDateString (const DateStringEnum output_date_format, std::string *out_string) const

void	ComputeTimeString (const TimeStringEnum output_time_format, std::string *out_string) const

std::string	ComputeDurationString (double fractional_seconds) const
	Returns string for 'this', e.g., "2y3m18d", interpreted as a duration. More...

double	GetJulianDate () const
	The Julian Day is the integer number of days that have elapsed since noon on Monday, January 1, 4713 BC. More...

double	GetTimeAsDecimal () const
	Convert "Standard" time to decimal time (or "French Revolutionary" time). More...

double	GetJ2000Date () const
	Returns a day decimal value relative to J2000, the epoch relative to 2000 Jan 1.5 (12h on January 1) or JD 2451545.0. More...

bool	IsUndefined () const
	Checks if the date is unset or marked undefined. More...

void	MakeUndefined ()
	Changes this DateTime to mark it as undefined. More...

void	operator+= (int64 secs)

void	operator-= (int64 secs)

void	operator+= (int secs)
	Regular int operators provided for compiler convenience so that you don't have to static cast. More...

void	operator+= (double secs)

void	operator-= (int secs)

void	operator-= (double secs)

int64	GetDateTimeField (DateTimeField field) const
	Returns a specific field value in the DateTime object as defined by DateTimeField `field` (kYear, kMonth, etc.). More...

int64	GetDateTimeField (uint8 field) const
	A convenience function to iterate through DateTime fields. More...

Static Public Member Functions
template<typename Rep >
static DateTime	CreateFromPosixSeconds (Rep secs, int8 zone_hours=0, int8 zone_minutes=0)
	Create a DateTime as an offset (in seconds) from the POSIX epoch, i.e., 00:00:00 01 January 1970. More...

static DateTime	Interpolate (const DateTime &begin, const DateTime &end, double t)
	Returns a linearly-interpolated DateTime between `begin` and `end` as defined by parameter `t`. More...

static double	GetDurationSecs (const DateTime &begin, const DateTime &end)
	Compute the duration from the first datetime to the second datetime in seconds, down to nanosecond resolution. More...

static double	GetInterpValue (const DateTime &now, const DateTime &time_a, const DateTime &time_b)
	Returns a double value representing the interpolation of `now` with respect to `time_a` and `time_b`, where time_a is 0.0, and time_b is 1.0. More...

static bool	ParseYMString (const std::string &date, DateTime *date_out)
	Checks if given string is in YYYY-MM formatr. More...

Protected Member Functions
virtual bool	Use24HourTime () const
	Determines whether to render 24-hour time strings based on a value set by translators. More...

Detailed Description

DateTime represents a particular date and time down to the nanosecond level along with timezone information.

This class also provides functions for parsing string representations of date and time, and computing a number of output formats (std::chrono::system_clock::time_point, seconds since the POSIX epoch, and string representations). The calendar used for DateTime is the proleptic Gregorian calendar as defined in ISO 8601. In particular, year 0 exists in this calendar, and is a leap year.

See: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar

Definition at line 45 of file datetime.h.

Member Enumeration Documentation

enum ion::base::DateTime::DateStringEnum

ComputeDateString() and ComputeTimeString() render the DateTime object to a std::string.

DateStringEnum and TimeStringEnum specify how much of the date or time to render.

Enumerator
kRenderDayMonthYear
kRenderMonthYear
kRenderYearOnly

Definition at line 238 of file datetime.h.

enum ion::base::DateTime::DateTimeField

Enumeration of the time-value fields of DateTime (used for iteration and numerical access).

Note: Localization code could rearrange these based on locale to properly order the date fields.

Enumerator
kYear
kMonth
kDay
kHour
kMinute
kSecond
kNanosecond
kNumFields

Definition at line 51 of file datetime.h.

enum ion::base::DateTime::TimeStringEnum

Enumerator
kRenderHoursMinutesSeconds
kRenderHoursMinutes
kRenderHoursOnly

Definition at line 243 of file datetime.h.

Constructor & Destructor Documentation

ion::base::DateTime::DateTime ( )

Definition at line 167 of file datetime.cc.

References Reset().

ion::base::DateTime::DateTime ( const DateTime & rhs )

Definition at line 173 of file datetime.cc.

References Set().

ion::base::DateTime::DateTime	(	int64	year,
		uint8	month,
		uint8	day,
		uint8	hour,
		uint8	minute,
		uint8	second,
		uint32	nanosec = `0`,
		int8	zone_hours = `0`,
		int8	zone_minutes = `0`
	)

Note: requested_zone_hours and requested_zone_minutes describe the resultant DateTime, not the input secs.

Definition at line 177 of file datetime.cc.

References Reset(), and Set().

ion::base::DateTime::DateTime	(	std::chrono::system_clock::time_point	time,
		int8	zone_hours = `0`,
		int8	zone_minutes = `0`
	)

explicit

Definition at line 185 of file datetime.cc.

References Reset().

virtual ion::base::DateTime::~DateTime ( )

inlinevirtual

Definition at line 138 of file datetime.h.

Member Function Documentation

void ion::base::DateTime::AdjustTimeZone	(	int	newHours,
		int	newMins
	)

Converts time to another time zone.

Definition at line 801 of file datetime.cc.

Referenced by Normalize().

void ion::base::DateTime::ComputeDateString	(	const DateStringEnum	output_date_format,
		std::string *	out_string
	)		const

Definition at line 529 of file datetime.cc.

References DCHECK, DCHECK_GE, DCHECK_LE, DCHECK_NE, kRenderDayMonthYear, kRenderMonthYear, and kRenderYearOnly.

std::string ion::base::DateTime::ComputeDurationString ( double fractional_seconds ) const

Returns string for 'this', e.g., "2y3m18d", interpreted as a duration.

fractional_seconds supplied as arg since DateTime only supports integer seconds.

Definition at line 654 of file datetime.cc.

References GetDateTimeField(), kNanosecond, kSecond, ion::base::TrimStartAndEndWhitespace(), and value.

void ion::base::DateTime::ComputeTimeString	(	const TimeStringEnum	output_time_format,
		std::string *	out_string
	)		const

Definition at line 598 of file datetime.cc.

References DCHECK, kRenderHoursMinutes, kRenderHoursMinutesSeconds, kRenderHoursOnly, and Use24HourTime().

template<typename Rep >

static DateTime ion::base::DateTime::CreateFromPosixSeconds	(	Rep	secs,
		int8	zone_hours = `0`,
		int8	zone_minutes = `0`
	)

inlinestatic

Create a DateTime as an offset (in seconds) from the POSIX epoch, i.e., 00:00:00 01 January 1970.

Note: requested_zone_hours and requested_zone_minutes describe the resultant DateTime, not the input secs.

Definition at line 118 of file datetime.h.

References Reset(), and value.

bool ion::base::DateTime::FromString ( const std::string & str )

Parses str into this DateTime object.

The parsing code accepts the union of xml:date, and xml:dateTime. See unit-test for examples of valid strings that this regular expression parses.

Definition at line 366 of file datetime.cc.

References DCHECK_GE, DCHECK_LE, GetNanosecond(), LOG, Reset(), Set(), SetDay(), SetHour(), SetMinute(), SetMonth(), SetNanosecond(), SetSecond(), SetYear(), SetZoneHours(), SetZoneMinutes(), and ion::port::WARNING.

Referenced by ion::base::operator>>().

int64 ion::base::DateTime::GetDateTimeField ( DateTimeField field ) const

Returns a specific field value in the DateTime object as defined by DateTimeField field (kYear, kMonth, etc.).

Definition at line 920 of file datetime.cc.

References ion::port::ERROR, kDay, kHour, kMinute, kMonth, kNanosecond, kSecond, kYear, and LOG.

Referenced by ComputeDurationString(), and GetDateTimeField().

int64 ion::base::DateTime::GetDateTimeField ( uint8 field ) const

inline

A convenience function to iterate through DateTime fields.

Definition at line 337 of file datetime.h.

References DCHECK, GetDateTimeField(), and kNumFields.

uint8 ion::base::DateTime::GetDay ( ) const

inline

Definition at line 143 of file datetime.h.

double ion::base::DateTime::GetDurationSecs	(	const DateTime &	begin,
		const DateTime &	end
	)

static

Compute the duration from the first datetime to the second datetime in seconds, down to nanosecond resolution.

Use this method instead of subtracting GetPosixSeconds() values for maximum precision.

Definition at line 830 of file datetime.cc.

Referenced by Interpolate().

uint8 ion::base::DateTime::GetHour ( ) const

inline

Definition at line 144 of file datetime.h.

double ion::base::DateTime::GetInterpValue	(	const DateTime &	now,
		const DateTime &	time_a,
		const DateTime &	time_b
	)

static

Returns a double value representing the interpolation of now with respect to time_a and time_b, where time_a is 0.0, and time_b is 1.0.

Definition at line 848 of file datetime.cc.

double ion::base::DateTime::GetJ2000Date ( ) const

inline

Returns a day decimal value relative to J2000, the epoch relative to 2000 Jan 1.5 (12h on January 1) or JD 2451545.0.

Definition at line 279 of file datetime.h.

References GetJulianDate().

double ion::base::DateTime::GetJulianDate ( ) const

The Julian Day is the integer number of days that have elapsed since noon on Monday, January 1, 4713 BC.

The fractional component represents time of day (starting at noon). Confusingly, the Julian Day bears little relation to the Julian Calendar.

Why is this important? Astronomers base most of their calculations on Julian Days rather than UTC. This code was converted from equations presented in "Astronomical Algorithms" by Jean Mesus.

Definition at line 768 of file datetime.cc.

References GetTimeAsDecimal().

Referenced by GetJ2000Date().

uint8 ion::base::DateTime::GetMinute ( ) const

inline

Definition at line 145 of file datetime.h.

uint8 ion::base::DateTime::GetMonth ( ) const

inline

Definition at line 142 of file datetime.h.

uint32 ion::base::DateTime::GetNanosecond ( ) const

inline

Definition at line 147 of file datetime.h.

Referenced by FromString().

template<typename Rep = double>

Rep ion::base::DateTime::GetPosixSeconds ( ) const

inline

Return the number of seconds offset from the POSIX epoch, as a given type Rep.

Definition at line 210 of file datetime.h.

uint8 ion::base::DateTime::GetSecond ( ) const

inline

Definition at line 146 of file datetime.h.

double ion::base::DateTime::GetTimeAsDecimal ( ) const

Convert "Standard" time to decimal time (or "French Revolutionary" time).

This represents time as a fraction of a day, and ignores year, month, and day. Interestingly, representing time as a decimal actually preceeded representing length, volume, etc as decimal (the metric system). However, it never caught on and lasted only two years (1793-1795). The same law which repealed decimal time introduced the metric system.

Definition at line 792 of file datetime.cc.

Referenced by GetJulianDate().

std::chrono::system_clock::time_point ion::base::DateTime::GetTimePoint ( ) const

Return a std::chrono::system_clock::time_point.

Definition at line 758 of file datetime.cc.

int64 ion::base::DateTime::GetYear ( ) const

inline

Accessors for all fields.

Definition at line 141 of file datetime.h.

int8 ion::base::DateTime::GetZoneHours ( ) const

inline

Definition at line 148 of file datetime.h.

int8 ion::base::DateTime::GetZoneMinutes ( ) const

inline

Definition at line 149 of file datetime.h.

DateTime ion::base::DateTime::Interpolate	(	const DateTime &	begin,
		const DateTime &	end,
		double	t
	)

static

Returns a linearly-interpolated DateTime between begin and end as defined by parameter t.

At t=0, this returns begin and at t=1 this returns end.

Definition at line 819 of file datetime.cc.

References GetDurationSecs().

Referenced by Lerp(), and ion::base::DateTime::Range::SetInterpolation().

bool ion::base::DateTime::IsEqualByComponent ( const DateTime & dtime ) const

Checks each component of the time object, including time zone.

Definition at line 750 of file datetime.cc.

bool ion::base::DateTime::IsUndefined ( ) const

inline

Checks if the date is unset or marked undefined.

Definition at line 286 of file datetime.h.

void ion::base::DateTime::Lerp	(	const DateTime &	origin,
		const DateTime &	target,
		double	t
	)

Set the current time to the interpolation of the two given times according to the interpolant, normalized on [0-1].

The result is in whatever zone this DateTime was in before calling lerp.

Definition at line 916 of file datetime.cc.

References Interpolate().

void ion::base::DateTime::MakeUndefined ( )

inline

Changes this DateTime to mark it as undefined.

Definition at line 289 of file datetime.h.

void ion::base::DateTime::Normalize ( )

inline

Converts this DateTime to UTC time (+0:00 time zone).

Definition at line 188 of file datetime.h.

References AdjustTimeZone().

Referenced by operator==(), and operator>().

bool ion::base::DateTime::operator!= ( const DateTime & dtime ) const

inline

Definition at line 201 of file datetime.h.

void ion::base::DateTime::operator+= ( int64 secs )

inline

Definition at line 291 of file datetime.h.

void ion::base::DateTime::operator+= ( int secs )

inline

Regular int operators provided for compiler convenience so that you don't have to static cast.

Definition at line 301 of file datetime.h.

void ion::base::DateTime::operator+= ( double secs )

Definition at line 872 of file datetime.cc.

References DCHECK_LT.

void ion::base::DateTime::operator-= ( int64 secs )

inline

Definition at line 297 of file datetime.h.

void ion::base::DateTime::operator-= ( int secs )

inline

Definition at line 303 of file datetime.h.

void ion::base::DateTime::operator-= ( double secs )

inline

Definition at line 304 of file datetime.h.

bool ion::base::DateTime::operator< ( const DateTime & dtime ) const

inline

Definition at line 198 of file datetime.h.

bool ion::base::DateTime::operator<= ( const DateTime & dtime ) const

inline

Definition at line 200 of file datetime.h.

DateTime & ion::base::DateTime::operator= ( const DateTime & rhs )

Definition at line 812 of file datetime.cc.

References Set().

bool ion::base::DateTime::operator== ( const DateTime & dtime ) const

This operator converts the date times to absolute and compares the absolute times for equality (hence time zone comparison is omitted).

Definition at line 734 of file datetime.cc.

References Normalize().

bool ion::base::DateTime::operator> ( const DateTime & dtime ) const

Definition at line 697 of file datetime.cc.

References Normalize().

bool ion::base::DateTime::operator>= ( const DateTime & dtime ) const

inline

Definition at line 199 of file datetime.h.

bool ion::base::DateTime::ParseYMString	(	const std::string &	date,
		DateTime *	date_out
	)

static

Checks if given string is in YYYY-MM formatr.

If date is properly formatted, this sets date_out to the time date specified and returns true, otherwise it leaves date_out untouched and returns false.

Definition at line 896 of file datetime.cc.

References Set(), and ion::base::StringToInt32().

void ion::base::DateTime::Reset ( )

Set the DateTime to default values (<year>/1/1T00:00:00.0Z00:00, where <year> is set as kUndefinedYear.

Definition at line 169 of file datetime.cc.

References Set().

Referenced by CreateFromPosixSeconds(), DateTime(), and FromString().

void ion::base::DateTime::Set	(	int64	years,
		uint8	months,
		uint8	days,
		uint8	hours,
		uint8	minutes,
		uint8	seconds,
		int8	zone_hours,
		int8	zone_minutes
	)

Definition at line 273 of file datetime.cc.

References SetDay(), SetHour(), SetMinute(), SetMonth(), SetNanosecond(), SetSecond(), SetYear(), SetZoneHours(), and SetZoneMinutes().

Referenced by DateTime(), FromString(), operator=(), ParseYMString(), Reset(), and Set().

void ion::base::DateTime::Set	(	int64	years,
		uint8	months,
		uint8	days,
		uint8	hours,
		uint8	minutes,
		uint8	seconds,
		uint32	nanoseconds,
		int8	zone_hours,
		int8	zone_minutes
	)