#include <evo/time.h>

Detailed Description

Full calendar date and time of day with timezone offset.

This combines Date, TimeOfDay, and TimeZoneOffset as members to form a full calendar date and time
You can access the fields directly, or use methods as needed
Format with format(), parse with parse()
Validate with validate()
Set to current time with: set_utc(), set_local(), set_local_notz()

Example

#include <evo/time.h>
#include <evo/io.h>
using namespace evo;
int main() {
    DateTime dt;
    dt.parse("1999-12-31-23:59:59");
    dt.add_seconds(1);
    dt.format(con().out, ' ') << NL;
    return 0;
}

Output:

2000-01-01 00:00:00

Public Member Functions
	DateTime ()
	Constructor. More...

	DateTime (int year, int month, int day, int hour=0, int minute=0, int second=0, int msecond=0, int tz_offset=OFFSET_NULL)
	Constructor. More...

	DateTime (const DateTime &src)
	Copy constructor. More...

	DateTime (const Date &date)
	Date constructor. More...

	DateTime (const Date &date, const TimeOfDay &time)
	Date and TimeOfDay constructor. More...

	DateTime (const Date &date, const TimeOfDay &time, const TimeZoneOffset &tz)
	Date and TimeOfDay constructor. More...

	DateTime (const TimeZoneOffset &tz)
	Timezone offset constructor. More...

bool	add_days (int days)
	Add days to current date, subtract if negative. More...

bool	add_hours (int hours)
	Add hours to current date and time, subtract if negative. More...

bool	add_milliseconds (int msec)
	Add milliseconds to current date and time, subtract if negative. More...

bool	add_minutes (int minutes)
	Add minutes to current date and time, subtract if negative. More...

bool	add_months (int months)
	Add months to current date, subtract if negative. More...

bool	add_seconds (int seconds)
	Add seconds to current date and time, subtract if negative. More...

bool	add_years (int years)
	Add years to current date, subtract if negative. More...

int	compare (const DateTime &oth) const
	Compare to another date and time. More...

template<class T >
T &	format (T &out, char dt_delim='T', char d_delim='-', char t_delim=':', char msec_delim=0, char tz_delim=':') const
	Format date and time to String or Stream using given delimiters. More...

template<class T >
T &	format_nodelim (T &out, char dt_delim='T', char msec_delim=0) const
	Format date and time to String or Stream using standard delimiters. More...

template<class T >
T &	format_std (T &out, char dt_delim='T', char msec_delim=0) const
	Format date and time to String or Stream using standard delimiters. More...

double	get_jdn_dt () const
	Get Julian Day Number with time fraction. More...

bool	operator!= (const DateTime &oth) const
	Compare for inequality with another date and time. More...

bool	operator< (const DateTime &oth) const
	Compare whether less than another date and time. More...

bool	operator<= (const DateTime &oth) const
	Compare whether less than or equal to another date and time. More...

DateTime &	operator= (const DateTime &src)
	Assignment operator. More...

bool	operator== (const DateTime &oth) const
	Compare for equality with another date and time. More...

bool	operator> (const DateTime &oth) const
	Compare whether greater than another date and time. More...

bool	operator>= (const DateTime &oth) const
	Compare whether greater than or equal to another date and time. More...

bool	parse (const SubString &str)
	Set date/time from parsing standard ISO 8601 based string. More...

bool	parse_std_impl (const char &inp, const char end)
	Set date/time from parsing standard ISO 8601 based string. More...

DateTime &	set ()
	Set all fields to 0, which is not a validate but is a valid time (midnight) and timezone offset (UTC). More...

bool	set (int year, int month, int day, int hour=0, int minute=0, int second=0, int msecond=0)
	Set new new fields. More...

bool	set_jdn_dt (double tm, int msec=0)
	Set new fields from Julian Day Number. More...

DateTime &	set_local ()
	Set to current local date and time with time zone offset. More...

DateTime &	set_local_notz ()
	Set to current local date and time without time zone offset. More...

DateTime &	set_utc ()
	Set to current UTC date and time. More...

bool	validate () const
	Validate current date, time, and timezone offset. More...

Public Attributes
Date	date
	Date fields. More...

TimeOfDay	time
	TimeOfDay fields. More...

TimeZoneOffset	tz
	TimeZoneOffset fields. More...

Static Public Attributes
static const ulong	JDN_MIN = Date::JDN_MIN
	Minimum Julian Day Number for Jan 1, 1000. More...

static const int	OFFSET_NULL = TimeZoneOffset::OFFSET_NULL
	Null time zone offset. More...

Constructor & Destructor Documentation

◆ DateTime() [1/7]

DateTime ( )

inline

Constructor.

◆ DateTime() [2/7]

DateTime	(	int	year,
		int	month,
		int	day,
		int	hour = `0`,
		int	minute = `0`,
		int	second = `0`,
		int	msecond = `0`,
		int	tz_offset = `OFFSET_NULL`
	)

inline

Constructor.

Parameters

year	4 digit year
month	Month of year
day	Day of month
hour	Hour of day
minute	Minute of hour
second	Second of minute
msecond	Millisecond of second
tz_offset	Time zone offset from UTC in minutes, 0 for UTC, negative for the Western Hemisphere (America), positive for the remaining time zones, OFFSET_NULL for null (no time zone)

◆ DateTime() [3/7]

DateTime ( const DateTime & src )

inline

Copy constructor.

Parameters

src	Source to copy

◆ DateTime() [4/7]

DateTime ( const Date & date )

inline

Date constructor.

Parameters

date	Date to copy from

◆ DateTime() [5/7]

DateTime	(	const Date &	date,
		const TimeOfDay &	time
	)

inline

Date and TimeOfDay constructor.

Parameters

date	Date to copy from
time	Time to copy from

◆ DateTime() [6/7]

DateTime	(	const Date &	date,
		const TimeOfDay &	time,
		const TimeZoneOffset &	tz
	)

inline

Date and TimeOfDay constructor.

Parameters

date	Date to copy from
time	Time to copy from
tz	Timezone offset to copy from

◆ DateTime() [7/7]

DateTime ( const TimeZoneOffset & tz )

inline

Timezone offset constructor.

Parameters

tz	Timezone offset to copy from

Member Function Documentation

◆ add_days()

bool add_days ( int days )

inline

Add days to current date, subtract if negative.

This adds the given days and adjusts months and years accordingly

Parameters

days	Number of days to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_hours()

bool add_hours ( int hours )

inline

Add hours to current date and time, subtract if negative.

This adds the given hours and adjusts the date accordingly

Parameters

hours Number of hours to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_milliseconds()

bool add_milliseconds ( int msec )

inline

Add milliseconds to current date and time, subtract if negative.

This adds the given milliseconds and adjusts the second, minute, hour, and date accordingly

Parameters

msec	Number of milliseconds to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_minutes()

bool add_minutes ( int minutes )

inline

Add minutes to current date and time, subtract if negative.

This adds the given minutes and adjusts the hour and date accordingly

Parameters

minutes Number of minutes to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_months()

bool add_months ( int months )

inline

Add months to current date, subtract if negative.

This adds the given months and adjusts day of month to last day of month if not valid for the new year and month

Parameters

months Number of months to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_seconds()

bool add_seconds ( int seconds )

inline

Add seconds to current date and time, subtract if negative.

This adds the given seconds and adjusts the minute, hour, and date accordingly

Parameters

seconds Number of seconds to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ add_years()

bool add_years ( int years )

inline

Add years to current date, subtract if negative.

This adds the given years and adjusts day of month to last day of month if not valid for the new year and month

Parameters

years Number of years to add, negative to subtract

Returns: Whether successful, false if current date is invalid before or after modification

◆ compare()

int compare ( const DateTime & oth ) const

inline

Compare to another date and time.

If this and oth have different time zone offsets, the differnce is taken into account, as if both are converted to UTC for comparison
If either time zone offset is null, then time zones are ignored here

Parameters

oth	Other date and time to compare to

Returns: Result (<0 if this is less, 0 if equal, >0 if this is greater)

◆ format()

T& format	(	T &	out,
		char	dt_delim = `'T'`,
		char	d_delim = `'-'`,
		char	t_delim = `':'`,
		char	msec_delim = `0`,
		char	tz_delim = `':'`
	)		const

inline

Format date and time to String or Stream using given delimiters.

See also: format_std(), format_nodelim()
Example outputs using default delimiters:
- 1999-12-31T23:59:59Z
- 1999-12-31T23:59:59+07:30
- 1999-12-31T23:59:59-08:00

Template Parameters

T	String/Stream type, inferred from argument

Parameters

out	Output String/Stream to format to
dt_delim	Delimiter between date and time, ISO 8601 uses `T`, Evo also supports space and underscore
d_delim	Date field delimiter, usually `-`, 0 for none – see Date::format()
t_delim	TimeOfDay field delimiter, usually `:`, 0 for none – see TimeOfDay::format()
msec_delim	Milliseconds delimiter, can be `.` or `,`, 0 for none – see TimeOfDay::format()
tz_delim	TimeZoneOffset field delimiter, usually `:`, 0 for none – see TimeZoneOffset::format()

Returns: Reference to out

◆ format_nodelim()

T& format_nodelim	(	T &	out,
		char	dt_delim = `'T'`,
		char	msec_delim = `0`
	)		const

inline

Format date and time to String or Stream using standard delimiters.

See also: format_nodelim(), format()
Example outputs using default delimiters:
- 19991231T235959Z
- 19991231T235959+07:30
- 19991231T235959-08:00

Template Parameters

T	String/Stream type, inferred from argument

Parameters

out	Output String/Stream to format to
dt_delim	Delimiter between date and time, ISO 8601 uses `T`, Evo also supports space and underscore
msec_delim	Milliseconds delimiter, can be `.` or `,`, 0 for none – see TimeOfDay::format()

Returns: Reference to out

◆ format_std()

T& format_std	(	T &	out,
		char	dt_delim = `'T'`,
		char	msec_delim = `0`
	)		const

inline

Format date and time to String or Stream using standard delimiters.

See also: format_nodelim(), format()
Example outputs using _ and . delimiters:
- 1999-12-31_23:59:59.999Z
- 1999-12-31_23:59:59.999+07:30
- 1999-12-31_23:59:59.999-08:00

Template Parameters

T	String/Stream type, inferred from argument

Parameters

out	Output String/Stream to format to
dt_delim	Delimiter between date and time, ISO 8601 uses `T`, Evo also supports space and underscore
msec_delim	Milliseconds delimiter, can be `.` or `,`, 0 for none – see TimeOfDay::format()

Returns: Reference to out

◆ get_jdn_dt()

double get_jdn_dt ( ) const

inline

Get Julian Day Number with time fraction.

This is useful for turning a date and time into a single floating-point number in day units that is easy to add/subtract and convert back
Call set_jdn_dt() to convert a JDN back into date and time fields
For a Modified JDN: subtract JDN_MOD from a valid (non-zero) result, then add it back again
Notes:
- Julian Days normally begin at noon, but this pretends they begin at midnight (12 hours earlier) since this is easier to manage
- Not related to the Julian calendar
Caution: Milliseconds aren't stored in the fraction (not enough precision) and are ignored here
See: set_jdn_dt()

Returns: Julian Day Number with whole number as date and fraction for time since midight – never negative

◆ operator!=()

bool operator!= ( const DateTime & oth ) const

inline

Compare for inequality with another date and time.

Parameters

oth	Other date and time to compare to

Returns: Whether inequal

◆ operator<()

bool operator< ( const DateTime & oth ) const

inline

Compare whether less than another date and time.

If this and oth have different time zone offsets, the differnce is taken into account, as if both are converted to UTC for comparison
If either time zone offset is null, then time zones are ignored here

Parameters

oth	Other date and time to compare to

Returns: Whether less than

◆ operator<=()

bool operator<= ( const DateTime & oth ) const

inline

Compare whether less than or equal to another date and time.

If this and oth have different time zone offsets, the differnce is taken into account, as if both are converted to UTC for comparison
If either time zone offset is null, then time zones are ignored here

Parameters

oth	Other date and time to compare to

Returns: Whether less than or equal

◆ operator=()

DateTime& operator= ( const DateTime & src )

inline

Assignment operator.

Parameters

src	Source to copy

Returns: This

◆ operator==()

bool operator== ( const DateTime & oth ) const

inline

Compare for equality with another date and time.

Parameters

oth	Other date and time to compare to

Returns: Whether equal

◆ operator>()

bool operator> ( const DateTime & oth ) const

inline

Compare whether greater than another date and time.

If this and oth have different time zone offsets, the differnce is taken into account, as if both are converted to UTC for comparison
If either time zone offset is null, then time zones are ignored here

Parameters

oth	Other date and time to compare to

Returns: Whether greater than

◆ operator>=()

bool operator>= ( const DateTime & oth ) const

inline

Compare whether greater than or equal to another date and time.

If this and oth have different time zone offsets, the differnce is taken into account, as if both are converted to UTC for comparison
If either time zone offset is null, then time zones are ignored here

Parameters

oth	Other date and time to compare to

Returns: Whether greater than or equal

◆ parse()

bool parse ( const SubString & str )

inline

Set date/time from parsing standard ISO 8601 based string.

Supported date/time syntax is based on ISO 8601:
- High level syntax: DATE "T" TIME TZ (without quotes or spaces)
- DATE: YYYY-MM-DD – see Date::parse() for more variations and detail
- TIME: HH:MM:SS or HH:MM:SS.fff – see TimeOfDay::parse() for more variations and detail
- TZ: Z or +HH:MM or -HH:MM – see TimeZoneOffset::parse() for more variations and detail

Parameters

str	String to parse

Returns: Whether successful, false on bad input or unrecognized format

◆ parse_std_impl()

bool parse_std_impl	(	const char *&	inp,
		const char *	end
	)

inline

Set date/time from parsing standard ISO 8601 based string.

Supported date/time syntax is based on ISO 8601:
- High level syntax: DATE "T" TIME TZ (without quotes or spaces)
- DATE: YYYY-MM-DD – see Date::parse() for more variations and detail
- TIME: HH:MM:SS or HH:MM:SS.fff – see TimeOfDay::parse() for more variations and detail
- TZ: Z or +HH:MM or -HH:MM – see TimeZoneOffset::parse() for more variations and detail

Parameters

inp	Start parsing pointer (must be `<= end`), set to stop position [in/out]
end	End of string pointer, must not be NULL

Returns: Whether successful, false on bad input or unrecognized format

◆ set() [1/2]

DateTime& set ( )

inline

Set all fields to 0, which is not a validate but is a valid time (midnight) and timezone offset (UTC).

◆ set() [2/2]

bool set	(	int	year,
		int	month,
		int	day,
		int	hour = `0`,
		int	minute = `0`,
		int	second = `0`,
		int	msecond = `0`
	)

inline

Set new new fields.

Caution: This does not modify the time zone offset (tz)

Parameters

year	4 digit year
month	Month of year
day	Day of month
hour	Hour of day
minute	Minute of hour
second	Second of minute
msecond	Millisecond of second

Returns: Whether successful, false if one of the fields is invalid

◆ set_jdn_dt()

bool set_jdn_dt	(	double	tm,
		int	msec = `0`
	)

inline

Set new fields from Julian Day Number.

Caution: This does not modify the time zone offset (tz)
Caution: Milliseconds aren't stored in the fraction (not enough precision) so time.msecond is set from msec

Parameters

tm	Julian Day Number with whole number as date and fraction for time since midight – must not be negative
msec	Milliseconds to set (0 - 999), defaults to `0`

Returns: Whether successful, false if tm is invalid (0 or less than JDN_MIN)

◆ set_local()

DateTime& set_local ( )

inline

Set to current local date and time with time zone offset.

Getting the time zone has some overhead so this can be slightly slower than set_local_notz()

Returns: This

◆ set_local_notz()

DateTime& set_local_notz ( )

inline

Set to current local date and time without time zone offset.

Getting the time zone has some overhead so this can be slightly faster than set_local()

Returns: This

◆ set_utc()

DateTime& set_utc ( )

inline

Set to current UTC date and time.

Returns: This

◆ validate()

bool validate ( ) const

inline

Validate current date, time, and timezone offset.

Returns: Whether valid, false if any date/time/tz field is invalid (out of range)

Member Data Documentation

◆ date

Date date

Date fields.

◆ JDN_MIN

const ulong JDN_MIN = Date::JDN_MIN

static

Minimum Julian Day Number for Jan 1, 1000.

◆ OFFSET_NULL

const int OFFSET_NULL = TimeZoneOffset::OFFSET_NULL

static

Null time zone offset.

◆ time

TimeOfDay time

TimeOfDay fields.

◆ tz

TimeZoneOffset tz

TimeZoneOffset fields.

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

evo/time.h

Detailed Description

Public Member Functions

Public Attributes

Static Public Attributes

Constructor & Destructor Documentation

◆ DateTime() [1/7]

◆ DateTime() [2/7]

◆ DateTime() [3/7]

◆ DateTime() [4/7]

◆ DateTime() [5/7]

◆ DateTime() [6/7]

◆ DateTime() [7/7]

Member Function Documentation

◆ add_days()

◆ add_hours()

◆ add_milliseconds()

◆ add_minutes()

◆ add_months()

◆ add_seconds()

◆ add_years()

◆ compare()

◆ format()

◆ format_nodelim()

◆ format_std()

◆ get_jdn_dt()

◆ operator!=()

◆ operator<()

◆ operator<=()

◆ operator=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ parse()

◆ parse_std_impl()

◆ set() [1/2]

◆ set() [2/2]

◆ set_jdn_dt()

◆ set_local()

◆ set_local_notz()

◆ set_utc()

◆ validate()

Member Data Documentation

◆ date

◆ JDN_MIN

◆ OFFSET_NULL

◆ time

◆ tz