Represents a point of time in wallclock, tracking the timestamps accuracy/precision. More...

#include <time.hpp>

Public Types
enum	accuracy : char { days , hours , minutes , seconds , milliseconds }
	The datetime's accuracy.

enum	zone { utc , local }
	When importing or exporting a timestamp, zone is used to explicitly specify whether the conversion is to/from localtime or UTC.

Public Member Functions
	datetime () noexcept=default
	A default-constructed timestamp is empty()

	datetime (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)

	datetime (time_t, accuracy a)

	datetime (std::string_view const &s, zone z)
	Construct from string, looks for `YYYYmmDD`[[[[HH]MM]SS]sss]. More...

	datetime (std::wstring_view const &s, zone z)

	datetime (FILETIME const &ft, accuracy a)
	Windows-only: Construct from FILETIME.

	datetime (datetime const &op)=default

	datetime (datetime &&op) noexcept=default

datetime &	operator= (datetime const &op)=default

datetime &	operator= (datetime &&op) noexcept=default

bool	empty () const

	operator bool () const

void	clear ()
	Resulting timestamp is empty()

accuracy	get_accuracy () const

int	compare (datetime const &op) const
	Accuracy-aware comparison against another timestamp. More...

bool	earlier_than (datetime const &op) const
	Equivalent to compare(op) < 0.

bool	later_than (datetime const &op) const
	Equivalent to compare(op) > 0.

bool	set (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)
	Sets the timestamp. More...

bool	set (std::string_view const &str, zone z)
	Set from string, looks for `YYYYmmDD`[[[[HH]MM]SS]sss]. More...

bool	set (std::wstring_view const &str, zone z)

bool	set (FILETIME const &ft, accuracy a)
	Windows-only: Set timestamp from FILETIME.

bool	set (SYSTEMTIME const &ft, accuracy a, zone z)
	Windows-only: Set timestamp from SYSTEMTIME.

bool	set (tm &t, accuracy a, zone z)

bool	imbue_time (int hour, int minute, int second=-1, int millisecond=-1)
	Adds time to timestamps that only have a day-accuracy. More...

std::string	format (std::string const &format, zone z) const

std::wstring	format (std::wstring const &format, zone z) const

int	get_milliseconds () const
	Get millisecond part of timestamp.

time_t	get_time_t () const
	Get timestamp as time_t, seconds since 1970-01-01 00:00:00.

tm	get_tm (zone z) const
	Get timestamp as struct tm. More...

FILETIME	get_filetime () const
	Windows-only: Get timestamp as FILETIME.

std::string	get_rfc822 () const

bool	set_rfc822 (std::string_view const &str)

bool	set_rfc822 (std::wstring_view const &str)

bool	set_rfc3339 (std::string_view const &str)

bool	set_rfc3339 (std::wstring_view const &str)

Naive comparison operators
Naive operators compare the timestamp's internal representation first, with accuracy as secondary criterion. See also compare
bool	operator== (datetime const &op) const

bool	operator!= (datetime const &op) const

bool	operator< (datetime const &op) const

bool	operator<= (datetime const &op) const

bool	operator> (datetime const &op) const

bool	operator>= (datetime const &op) const

Adding/subtracting duration intervals
Adding or subtracting a duration interval is accuracy-aware, e.g. adding a single second to a datetime with minute-accuracy does not change the timestamp.
datetime &	operator+= (duration const &op)

datetime	operator+ (duration const &op) const

datetime &	operator-= (duration const &op)

datetime	operator- (duration const &op) const

Static Public Member Functions
static datetime	now ()
	Returns the current date/time.

static bool	verify_format (std::string const &fmt)

static bool	verify_format (std::wstring const &fmt)

Friends
duration	operator- (datetime const &a, datetime const &b)
	Gets the difference between two timestamps as duration. More...

Detailed Description

Represents a point of time in wallclock, tracking the timestamps accuracy/precision.

As time may come from different sources that have different accuracy/precision, this class keeps track of accuracy information.

For example, your local filesystem might store timestamps with milliseconds, whereas a given network protocol might only offer seconds. You can use compare to easily check whether the timestamp of a local file is equivalent to a timestamp received via the protocol.

The internal representation of datetime is in milliseconds since 1970-01-01 00:00:00.000 UTC and can handle a range of several million years. While datetime supports negative times (i.e. earlier than 1970-01-01 00:00:00.000 UTC), the underlying platform may not support it.

Remarks: Some *nix systems base their time on TAI instead of UTC, though we pretend there is no difference, as the latter is the default on every modern distribution.

Examples: list.cpp.

Constructor & Destructor Documentation

◆ datetime()

datetime	(	std::string_view const &	s,
		zone	z
	)

explicit

Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

See also: bool set(std::string_view const& str, zone z)

Member Function Documentation

◆ compare()

int compare ( datetime const & op ) const

Accuracy-aware comparison against another timestamp.

Conceptually it works as if naively comparing both timestamps after truncating/clamping them to the least common accuracy.

Returns: 0 if timestamps are equivalent,
<0 if own timestamp is earlier than the argument,
>0 if own timestamp is late than the argument.

◆ empty()

bool empty ( ) const

Returns: true if no timestamp has been set

Examples: list.cpp.

◆ format()

std::string format	(	std::string const &	format,
		zone	z
	)		const

Format time as string

Parameters

format is a format string as understood by ::strftime

Note that some format specifiers are locale-dependent.

Examples: list.cpp.

◆ get_rfc822()

std::string get_rfc822 ( ) const

Returns date in the format specified in RFC 822, updated by RFC 1123.

Example:

Sun, 06 Nov 1994 08:49:37 GMT

◆ get_tm()

tm get_tm ( zone z ) const

Get timestamp as struct tm.

Undefined if datetime is empty.

Note: On Windows the tm_yday and tm_isdst fields are undefined.

◆ imbue_time()

bool imbue_time	(	int	hour,
		int	minute,
		int	second = `-1`,
		int	millisecond = `-1`
	)

Adds time to timestamps that only have a day-accuracy.

Changes accuracy based on given parameters. Use -1 in parameters that aren't used.

Returns: Whether the function succeeded. On failure object remains unchanged.

◆ set() [1/3]

bool set	(	std::string_view const &	str,
		zone	z
	)

Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

Ignores all non-digit characters between fields. For example 20140720T165432 is the same as 2014-07-20 16:54:32

accuracy is set according to the fields present in the string.

Returns: whether setting the timestamp succeeded. On failure object gets cleared

◆ set() [2/3]

bool set	(	tm &	t,
		accuracy	a,
		zone	z
	)

Sets timestamp from struct tm.

Note: Not available on Windows.

Warning: modifies passed structure

Returns: true on success, false on failure. The object is empty after failure.

◆ set() [3/3]

bool set	(	zone	z,
		int	year,
		int	month,
		int	day,
		int	hour = `-1`,
		int	minute = `-1`,
		int	second = `-1`,
		int	millisecond = `-1`
	)

Sets the timestamp.

Parameters

month	1-indexed as on a calender, e.g. February is 2
day	1-indexed as on a calender
hour	0-indexed as on a 24h clock

Returns: whether setting the timestamp succeeded. On failure object gets cleared

◆ set_rfc3339()

bool set_rfc3339 ( std::string_view const & str )

Parses a date in the format specified in RFC 3339

On errors, object gets clears

Returns: whether setting the timestamp succeeded. On failure object gets cleared.

Examples:: 1985-04-12T23:20:50.52Z 1996-12-19T16:39:57-08:00

◆ set_rfc822()

bool set_rfc822 ( std::string_view const & str )

Parses a date in the format specified in RFC 822, either original or updated by RFC 1123. Also supports RFC 850 and ANSI C asctime formats.

Used timezone is always UTC.

On errors, object gets clears

Returns: whether setting the timestamp succeeded. On failure object gets cleared.

Examples:: Sun, 06 Nov 1994 08:49:37 GMT // RFC 822, updated by RFC 1123
Sun, 06-Nov-94 08:49:37 GMT // obsolete RFC 850
Sun Nov 6 08:49:37 1994 // ANSI C asctime

◆ verify_format()

static bool verify_format ( std::string const & fmt )

static

Verify format strings

Parameters

fmt	the string that is to be tested

Returns: whether the passed string is a format string understood by ::strftime

Friends And Related Function Documentation

◆ operator-

duration operator-	(	datetime const &	a,
		datetime const &	b
	)

friend

Gets the difference between two timestamps as duration.

This function ignores accuracy, it treats both timestamps as if they had millisecond-accuracy.

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

time.hpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ datetime()

Member Function Documentation

◆ compare()

◆ empty()

◆ format()

◆ get_rfc822()

◆ get_tm()

◆ imbue_time()

◆ set() [1/3]

◆ set() [2/3]

◆ set() [3/3]

◆ set_rfc3339()

◆ set_rfc822()

◆ verify_format()

Friends And Related Function Documentation

◆ operator-