tsa::date_time Class Reference

Class representing a gregorian-date and time-of-day combination. The time component has microsecond resolution. More...

#include <TSATime.h>

Inheritance diagram for tsa::date_time:

Public Member Functions
	date_time (uint32_t yyyymmdd=date_time::undefined)
	Constructor. By default, self will be in an 'undefined' state. Passing date_time::now_local or date_time::now_utc as constructor argument initializes self to the current system time. Otherwise ny other number in yyyymmdd format is acceptable as constructor argument. More...
	date_time (const date_time &other)
	Copy constructor.
	date_time (const std::chrono::time_point< std::chrono::system_clock > &time_point)
	Constructor. Translates given time_point as local-time.
	date_time (const char *date_time_str)
	Constructor. Initializes self with given date_time_str by automatically interpreting its format. More...
	date_time (const date &date)
	Constructs self from date. Time-of-day is set to midnight / start of day.
	date_time (uint32_t year, uint32_t month, uint32_t day)
	Constructor. Time-of-day is set to midnight.
	date_time (const date &date, uint32_t hour, uint32_t minute, uint32_t second=0)
	Constructor.
	date_time (uint32_t year, uint32_t month, uint32_t day, uint32_t hour, uint32_t minute, uint32_t second=0, uint32_t microseconds=0)
	Constructor. Hour: 0-23, minute:0-59, second: 0-59, microseconds: 0-999999.
	date_time (const date &date, uint32_t hour, uint32_t minute, uint32_t second, uint32_t microseconds)
	Constructor. Hour: 0-23, minute:0-59, second: 0-59, microseconds: 0-999999.
	date_time (const variant &variant)
	Constructs self from given variant. More...
time_t	as_system_time (local_or_utc_time_select local_or_utc=tsa::local_time) const
	Returns the time_t equivalent of self. More...
std::chrono::system_clock::time_point	as_time_point (local_or_utc_time_select local_or_utc)
	Returns self as a std::chrono time_point. The given flag determines wheter self is interpreted as 'local' or 'UTC' time. More...
void	assign (const tsa::date_time &other, bool error_on_nil=true)
	Assignment. More...
void	clear (void)
	Resets the object to an 'undefined' state (see defined()).
date_time	convert_to_utc (void) const
	Converts into 'universal time coordinate' time (ZULU time).
void	decr_microsec (int64_t n=1)
	Decrements self by n microseconds. If the start of day is reached, the date is decremented.
bool	defined (void) const
	Returns true if self has been initialized with a valid date-time. The default constructor does not initialize the object. More...
bool	has_time_zone_offset (void) const
	Returns true if a timezone offset was defined.
uint32_t	hhmm (void) const
	Returns the time-of-day as an hhmm integer.
uint32_t	hhmmss (void) const
	Returns the time-of-day as an hhmmss integer.
uint32_t	hhmmssmmm (void) const
	Returns the time-of-day as an hhmmssmmm integer.
uint64_t	hhmmssmmmmmm (void) const
	Returns the time-of-day as an hhmmssmmmmmm integer.
uint32_t	hour (void) const
	Returns the hour (0-23).
void	incr_date (int num_days=1)
	Increments the date by num_days.
void	incr_microsec (int64_t n=1)
	Increments self by n microseconds. If the end of day is reached, the date is incremented.
bool	is_midnight (void) const
	Returns true if the time component (number of microseconds since midnight as returned by microsec_of_day() ) is zero.
uint32_t	microsec (void) const
	Returns the microsecond (0-999999).
int64_t	microsec_since_midnight (void) const
	Gets the time-of-day as the number of microseconds since midnight.
void	microsec_since_midnight (int64_t)
	Sets the time-of-day in the form of the number of microseconds since midnight.
uint32_t	minute (void) const
	Returns the minute (0-59).
bool	operator!= (const date_time &other) const
	Returns true if self and other are not equal.
void	operator+= (const duration &duration)
	Adds duration to self.
void	operator-= (const duration &duration)
	Subtracts duration from self.
bool	operator< (const date_time &other) const
	Returns true if self is smaller (earlier) than other.
bool	operator<= (const date_time &other) const
	Returns true if self is smaller (earlier) or equal than other.
date_time &	operator= (const tsa::date_time &)
	Assignment operator.
bool	operator== (const date_time &other) const
	Returns true if self and other are equal.
bool	operator> (const date_time &other) const
	Returns true if self is larger (later) than other.
bool	operator>= (const date_time &other) const
	Returns true if self is larger (later) or equal than other.
uint32_t	second (void) const
	Returns the second (0-59).
void	set (const std::chrono::system_clock::time_point &time_pt, local_or_utc_time_select local_or_utc=tsa::local_time)
	Sets self to std::chrono::system_clock::time_point. More...
void	set_date (uint32_t year, uint32_t month, uint32_t day)
	Sets the date. Time-of-day remains unchanged.
void	set_date (const date &)
	Sets the date. Time-of-day remains unchanged.
void	set_date_from_string (const std::string &date_string, const char *date_format)
	Sets the date from given date_string and format. See date::set_from_string() for valid format strings. This member is the equivalent of date::set_from_string(). More...
void	set_from_iso_string (const std::string &date_time_string)
	Sets the date-time from a string in ISO format (yyyy-mm-ddThh:mm:ss:f). This member is very fast. More...
void	set_from_string (const std::string &date_time_string, const char *date_format=nullptr, char sep= 'T')
	Sets self from given date_time_string. The given date-time separator character must be either 'T' and ' '. If date_format is given as a nullptr then the function will try to automatically recognize the date format. This process is much slower than when passing the correct date format. See date::from_string(). More...
void	set_hhmm (uint32_t hhmm)
	Sets the time - of - day from an integer.
void	set_hhmmss (uint32_t hhmmss)
	Sets the time-of-day from an integer.
void	set_time (uint32_t hour, uint32_t minute, uint32_t second, uint32_t microsecond)
	Sets the time-of-day to given hour, minute, second, and microsecond.
void	set_time (uint32_t hour, uint32_t minute, uint32_t second)
	Sets the time-of-day to given hour, minute, second.
void	set_time (uint32_t hour, uint32_t minute)
	Sets the time-of-day to the given hour, minute.
void	set_time_from_string (const std::string &time_string)
	Sets the time-of-day from given time_string. More...
void	set_time_t (time_t system_time, local_or_utc_time_select local_or_utc, set_timezone_offset_select tz=no_timezone_offset)
	Sets self to given system_time. More...
void	set_to_now (local_or_utc_time_select local_or_utc_flag, set_timezone_offset_select set_tz_offset_flag=no_timezone_offset)
	Sets self to the operating system's current date-time. More...
int	timezone_half_hour_offset (void) const
	Returns the timezone offset as a number of 30 minute intervals.
void	timezone_half_hour_offset (int)
	Sets the timezone offset as a number of 30 minute intervals.
double	timezone_offset (void) const
	Returns the timezone offset in hours (which can be a fraction).
void	timezone_offset (double hours)
	Sets the timezone offset as a number of hours (which can be a fraction)
std::string	to_string (const char *date_format, const char *time_format, char sep) const
	Returns date and time as a formated string. More...
std::string	to_string (char sep= 'T') const
	Returns a ISO date-time string (yyyy-mm-ddThh:mm:ss:f) with given separator ('T' by default). This member function is much faster than the more flexible function taking format string arguments. More...
std::string	to_time_string (const char *format="hh:mm:ss.f") const
	Returns time-of-day as a formated string. More...
uint32_t	usec (void) const
	Returns the microsecond (0-999999).
void	verify_defined (void) const
	Throws an exceptio if self is not defined. See defined() member.
Public Member Functions inherited from tsa::date
	date (const date &other)
	Copy constructor.
	date (const char *date_str)
	Constructor. Requires unambiguous date string (e.g. yyyy-mm-dd, yyyy/mm/dd, yyyy.mm.dd)
	date (const variant &variant)
	Constructor. May throw exception if variant cannot be converted to a date.
	date (uint32_t yyyymmdd=date::undefined)
	Constructor. By default, self is not initialized; defined() will return false. Use the date::now argument to initialize to the current system date. Otherwise initialize to any other date by submitting a valid yyyymmdd argument. More...
	date (int year, int month, int day)
	Constructor taking year, month, and day arguments.
void	assign (const date &, bool _error_on_undefined=true)
	Assigns a given date to self. Throws an exception if given date is not defined (see defined()) and _error_on_undefined flag is true.
void	clear (void)
	Sets self to an 'undefined' state, where defined() will return false.
int	day_of_month (void) const
	Returns the day of the month (1-31).
week_day	day_of_week (void) const
	Returns the day of the week (Sunday = 0, Saturday = 6).
int	day_of_year (void) const
	Returns the day of the year (1-366).
void	decr (int num_days)
	Decrements self by num_days.
void	decr_to_prev_weekday (void)
	Decrements self to previous weekday, skipping sundays or saturdays.
bool	defined (void) const
	Returns true if self is not 'null'; in other words, the date was defined.
bool	in_leap_year (void) const
	Returns true if the date's year is a leap year.
void	incr (int num_days)
	Increments self by num_days.
void	incr_to_next_weekday (void)
	Increments self to next weekday, skipping sundays and saturdays.
bool	is_weekend (void) const
	Returns true if current day of week is either Saturday or Sunday.
void	julian_day (int julian_day)
	Resets the internal julian-day value.
int	julian_day (void) const
	Returns the julian-day.
int	month (void) const
	Returns the month (1-12).
bool	operator!= (const date &other) const
	Returns true if self is not equal to other.
void	operator+= (const duration &num_days)
	Adds a given number of days to self. The given duration must not have an intraday component.
void	operator-= (const duration &num_days)
	Subtracts a given number of days from self. The given duration must not have an intraday component.
bool	operator< (const date &other) const
	Returns true if self is smaller than other.
bool	operator<= (const date &other) const
	Returns true if self is smaller or equal to other.
date &	operator= (const date &other)
	Assignment operator.
bool	operator== (const date &other) const
	Returns true if self is equal to other.
bool	operator> (const date &other) const
	Returns true if self is larger than other.
bool	operator>= (const date &other) const
	Returns true if self is larger or equal to other.
void	set (uint32_t year, uint32_t month, uint32_t day)
	Sets self to given year, month, day combination.
void	set_from_iso_string (const std::string &iso_date_string)
	Sets the date from the given ISO date string with format: "yyyy-mm-dd". This member function is much faster then the one declaring a format parameter. More...
void	set_from_string (const std::string &date_string, const char *format_string="")
	Sets the date from the given date_string interpreted according to given format_string. More...
void	set_to_now (tsa::local_or_utc_time_select lu)
	Sets self to the operating system's current date.
std::string	to_string (const char *format) const
	Returns the date as a string formated according to given format. More...
std::string	to_string (void) const
	Returns the date as an ISO date string (yyyy-mm-dd).
int	year (void) const
	Returns the year.
void	yyyymmdd (uint32_t yyyymmdd)
	Sets the date from an integer in yyyymmdd format such as 19990403 (representing April 3 1999).
uint32_t	yyyymmdd (void) const
	Returns the current date as a number.

Static Public Member Functions
static date_time	local_time (void)
	Returns the current system date-time. Same as now();.
static date_time	now (void)
	Returns the current system date-time.
static date_time	utc_time (set_timezone_offset_select set_tz_offset_flag=no_timezone_offset)
	Returns the current system date-time as 'universal time coordinate' time.
Static Public Member Functions inherited from tsa::date
static bool	is_leap_year (int year)
	Returns true if the given year is a leap year, otherwise returns false.
static bool	is_valid (int year, int month, int day)
	Returns true if arguments form a valid date. More...

Static Public Attributes
static const int64_t	last_microsecond_in_day = (date_time::microseconds_in_day - 1)
	Constant representing the number of microseconds in a day.
static const date_time	max = date_time(99999, 12, 31, 23, 59, 59, 999999)
	Constant representing the largest allowed date_time.
static const int64_t	microseconds_in_day = 86400000000
	Constant representing the number of microseconds in a day.
static const int64_t	microseconds_in_hour = 3600000000
	Constant representing the number of microseconds in an hour.
static const int64_t	microseconds_in_minute = 60000000
	Constant representing the number of microseconds in a minute.
static const int64_t	microseconds_in_second = 1000000
	Constant representing the number of microseconds in a second.
static const date_time	min = date_time(100, 1, 1, 0, 0, 0, 0)
	Constant representing the smallest allowed date_time.
static const uint32_t	now_local = ((std::numeric_limits<uint32_t>::max)() - 1)
	Constructor flag to initialize self to the current system's 'local time'.
static const uint32_t	now_utc = ((std::numeric_limits<uint32_t>::max)() - 2)
	Constructor flag to initialize self to the current system's 'UTC time'.
static const uint32_t	undefined = (std::numeric_limits<uint32_t>::max)()
	Constructor flag to initilize self to a not-initialized state.
Static Public Attributes inherited from tsa::date
static const date	gregorian_start = date(1753, 01, 01)
	Gregorian calendar start date (of this implementation - Jan 1 1753).
static const date	max = date(99999, 12, 31)
	Largest valid date (dec 31 99999AD).
static const int	max_julian_day = 38245309
	Largest valid julian day.
static const int	max_yyyymmdd = 999991231
	Largest valid yyyymmdd.
static const date	min = date(100, 01, 01)
	Smallest valid date ( jan 1 100AD).
static const int	min_julian_day = 1757585
	Smallest valid julian day.
static const int	min_yyyymmdd = 1000101
	Smallest valid yyyymmdd.
static const uint32_t	undefined = (std::numeric_limits<uint32_t>::max)()
	Constructor flag to instruct self to stay undefined (see defined()).

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &stream, const date_time &datetime)
	Writes datetime to stream as a string, formated as 'yyyy-mm-ddThh:mm:ss.f'. More...
Related Functions inherited from tsa::date
std::ostream &	operator<< (std::ostream &stream, const date &date)
	Writes date to stream in "yyyy-mm-dd" format. If the date is undefined, output is "[undefined-date]". More...

Additional Inherited Members

Public Types inherited from tsa::date

Detailed Description

Class representing a gregorian-date and time-of-day combination. The time component has microsecond resolution.

Constructor & Destructor Documentation

tsa::date_time::date_time ( uint32_t  yyyymmdd = date_time::undefined )

explicit

Constructor. By default, self will be in an 'undefined' state. Passing date_time::now_local or date_time::now_utc as constructor argument initializes self to the current system time. Otherwise ny other number in yyyymmdd format is acceptable as constructor argument.

Parameters

yyyymmdd

The date as yyyymmdd number.

tsa::date_time::date_time

(

const char *

date_time_str

)

Constructor. Initializes self with given date_time_str by automatically interpreting its format.

This constructor can throw an exception if it fails to understand the string argument. This member is not to be used in situations where high performance is required.

Only use unambiguous date formats such as: 2010-10-30 23:10:54 (for Oct 30 2010) The object will try its best to understand and interpret the given date_time string. Only use 4 digit years! Non y2k compliant dates are not supported. Date and time can either be separated by a 'T' or ' ' character.

Parameters

date_time_str

The date time string.

tsa::date_time::date_time

(

const variant &

variant

)

Constructs self from given variant.

If variant cannot be converted, to a valid date_time, an exception is thrown!

Parameters

variant

The variant.

Member Function Documentation

time_t tsa::date_time::as_system_time

(

tsa::local_or_utc_time_select

_lu = tsa::local_time

)

const

Returns the time_t equivalent of self.

Parameters

local_or_utc

Local time or UTC time.

Returns

A time_t.

std::chrono::system_clock::time_point tsa::date_time::as_time_point

(

tsa::local_or_utc_time_select

_lu

)

Returns self as a std::chrono time_point. The given flag determines wheter self is interpreted as 'local' or 'UTC' time.

Parameters

local_or_utc

Local time or UTC time.

Returns

A std::chrono::system_clock::time_point.

void tsa::date_time::assign	(	const tsa::date_time &	other,
		bool	error_on_nil = true
	)

Assignment.

This member throws an exception if error_on_nil is true and other is undefined. This can prevent assigment of undefined date_time objects in situations where this is not desirable.

Parameters

other	The other date_time instance.
error_on_nil	If true will prevent assignment of undefined date_time instance.

bool tsa::date_time::defined

(

void

)

const

Returns true if self has been initialized with a valid date-time. The default constructor does not initialize the object.

Returns

bool.

void tsa::date_time::set	(	const std::chrono::system_clock::time_point &	time_pt,
		local_or_utc_time_select	local_or_utc = tsa::local_time
	)

Sets self to std::chrono::system_clock::time_point.

The local_or_utc flag determines whether.

Parameters

time_pt	The time point.
local_or_utc	Local time or UTC time.

void tsa::date_time::set_date_from_string	(	const std::string &	date_string,
		const char *	date_format
	)

Sets the date from given date_string and format. See date::set_from_string() for valid format strings. This member is the equivalent of date::set_from_string().

Parameters

date_string	The date string.
date_format	The date format.

void tsa::date_time::set_from_iso_string

(

const std::string &

date_time_string

)

Sets the date-time from a string in ISO format (yyyy-mm-ddThh:mm:ss:f). This member is very fast.

The given date_time_string must be exactly in ISO format. The only change allowed is that the sparator can be either 'T' or ' '.

Parameters

date_time_string

The date time string.

void tsa::date_time::set_from_string	(	const std::string &	date_time_string,
		const char *	date_format = nullptr,
		char	sep = 'T'
	)

Sets self from given date_time_string. The given date-time separator character must be either 'T' and ' '. If date_format is given as a nullptr then the function will try to automatically recognize the date format. This process is much slower than when passing the correct date format. See date::from_string().

The format string essentially provides the YMD sequence, as well as the field separator. Valid field separators are '.', '-', '/'.

If the month format is set to 'mmm', then the function will required the month to be a 3 letter short month name, such as 'Jan'.

Examples for valid date formats are:

• yyyy-mm-dd
• yyyy.mmm.dd
• dd/mmm/yyyy
• d/m/y
• y-m-d.

A time format string is not required. The given time-string can be any of:

• hh:mm:ss:f
• hh:mm:ss.f
• hhmmssmmm
• hh:mm:ss
• hhmmss
• hh:mm
• hhmm.

  Parameters

  date_time_string	The date-time string.
  date_format	The date format.
  sep	The date and time separator. 'T' by default. Only 'T' and ' ' are valid.

void tsa::date_time::set_time_from_string

(

const std::string &

time_string

)

Sets the time-of-day from given time_string.

Recognized time formats are:

• hh:mm:ss:f
• hh:mm:ss.f
• hhmmssmmm
• hh:mm:ss
• hhmmss
• hh:mm
• hhmm.

  Parameters

  time_string

  The time string.

void tsa::date_time::set_time_t	(	time_t	system_time,
		local_or_utc_time_select	local_or_utc,
		set_timezone_offset_select	tz = no_timezone_offset
	)

Sets self to given system_time.

Parameters

system_time	The system time.
local_or_utc	Local time or UTC time selector.
tz	The timezone.

void tsa::date_time::set_to_now	(	tsa::local_or_utc_time_select	_lu,
		set_timezone_offset_select	set_tz_offset_flag = no_timezone_offset
	)

Sets self to the operating system's current date-time.

Parameters

local_or_utc_flag	The local or UTC flag.
set_tz_offset_flag	Set as true to set the object's timezone offset.

std::string tsa::date_time::to_string	(	const char *	date_format,
		const char *	time_format,
		char	sep
	)		const

Returns date and time as a formated string.

Please see the documentation for date::to_string() for details on date_format and time_format.

Parameters

date_format	The date format.
time_format	The time format.
sep	The date and time string separator.

Returns

The given data converted to a std::string.

std::string tsa::date_time::to_string

(

char

sep = 'T'

)

const

Returns a ISO date-time string (yyyy-mm-ddThh:mm:ss:f) with given separator ('T' by default). This member function is much faster than the more flexible function taking format string arguments.

Parameters

sep	The separator.

Returns

std::string.

std::string tsa::date_time::to_time_string

(

const char *

format = "hh:mm:ss.f"

)

const

Returns time-of-day as a formated string.

Valid formats are:

• hh:mm:ss:f
• hh:mm:ss.f
• hhmmssmmm
• hh:mm:ss
• hhmmss
• hh:mm
• hhmm.

  Parameters

  format

  Describes the format to use.

  Returns

  std::string.