Detailed Description

Date and time utilities.

Classes
class	Date
	Date in format YYYY-MM-DD, std::chrono::year_month_day like type. More...

class	DateParseError
	Date/time parsing error. More...

class	SteadyClock

struct	SteadyCoarseClock
	Steady clock with up to a few millisecond resolution that is slightly faster than the std::chrono::steady_clock. More...

class	TimeOfDay
	A simple implementation of a "time since midnight" datatype. More...

class	TimeOfDay< std::chrono::duration< Rep, Period > >

class	TimezoneLookupError
	Timezone information lookup error. More...

struct	WallCoarseClock
	System clock with up to a few millisecond resolution that is slightly faster than the std::chrono::system_clock. More...

Typedefs
using	timepair_t = std::pair<uint8_t, uint8_t>

Functions
std::chrono::system_clock::time_point	Now () noexcept
	std::chrono::system_clock::now() that could be mocked

std::chrono::system_clock::time_point	Epoch () noexcept
	Returns std::chrono::system_clock::time_point from the start of the epoch.

std::chrono::steady_clock::time_point	SteadyNow () noexcept
	std::chrono::steady_clock::now() that could be mocked

bool	IsTimeBetween (int hour, int min, int hour_from, int min_from, int hour_to, int min_to, bool include_time_to=false) noexcept
	Returns true if the time is in range; works over midnight too.

std::string	Timestring (std::time_t timestamp, const std::string &timezone=kDefaultTimezone, const std::string &format=kDefaultFormat)
	Returns time in a string of specified format.

std::string	LocalTimezoneTimestring (std::time_t timestamp, const std::string &format=kDefaultFormat)
	Returns time in a string of specified format.

std::string	Timestring (std::chrono::system_clock::time_point tp, const std::string &timezone=kDefaultTimezone, const std::string &format=kDefaultFormat)
	Returns time in a string of specified format.

std::string	LocalTimezoneTimestring (std::chrono::system_clock::time_point tp, const std::string &format=kDefaultFormat)
	Returns time in a string of specified format.

std::chrono::system_clock::time_point	Stringtime (const std::string &timestring, const std::string &timezone=kDefaultTimezone, const std::string &format=kDefaultFormat)
	Extracts time point from a string of a specified format.

std::chrono::system_clock::time_point	LocalTimezoneStringtime (const std::string &timestring, const std::string &format=kDefaultFormat)
	Extracts time point from a string of a specified format.

std::chrono::system_clock::time_point	GuessStringtime (const std::string &timestamp, const std::string &timezone)
	Extracts time point from a string, guessing the format.

std::chrono::system_clock::time_point	GuessLocalTimezoneStringtime (const std::string &timestamp)
	Extracts time point from a string, guessing the format.

std::optional< std::chrono::system_clock::time_point >	OptionalStringtime (const std::string &timestring, const std::string &timezone=kDefaultTimezone, const std::string &format=kDefaultFormat)
	Returns optional time in a string of specified format Example:

std::time_t	Timestamp (std::chrono::system_clock::time_point tp) noexcept
	Converts time point to std::time_t Example:

std::time_t	Timestamp () noexcept
	Returned current time as std::time_t; could be mocked.

std::uint32_t	ParseDayTime (const std::string &str)
	Parse day time in hh:mm[:ss] format.

cctz::civil_second	Localize (const std::chrono::system_clock::time_point &tp, const std::string &timezone)
	Converts absolute time in std::chrono::system_clock::time_point to a civil time of a particular timezone.

cctz::civil_second	LocalTimezoneLocalize (const std::chrono::system_clock::time_point &tp)
	Converts absolute time in std::chrono::system_clock::time_point to a civil time of a local timezone.

std::time_t	Unlocalize (const cctz::civil_second &local_tp, const std::string &timezone)
	Converts a civil time in a specified timezone into an absolute time.

std::time_t	LocalTimezoneUnlocalize (const cctz::civil_second &local_tp)
	Converts a civil time in a local timezone into an absolute time.

std::string	TimestampToString (std::time_t timestamp)
	Returns string with time in ISO8601 format "YYYY-MM-DDTHH:MM:SS+0000".

int64_t	TimePointToTicks (const std::chrono::system_clock::time_point &tp) noexcept
	Convert time_point to DotNet ticks.

std::chrono::system_clock::time_point	TicksToTimePoint (int64_t ticks) noexcept
	Convert DotNet ticks to a time point.

template<class Duration , class Clock >
double	CalcTimeDiff (const std::chrono::time_point< Clock > &a, const std::chrono::time_point< Clock > &b)
	Compute (a - b) with a specified duration.

Date	DateFromRFC3339String (const std::string &date_string)
	Validates date_string and constructs date from YYYY-MM-DD string and.

std::string	ToString (Date date)
	Outputs date as a YYYY-MM-DD string.

template<typename Value >
std::enable_if_t< formats::common::kIsFormatValue< Value >, Date >	Parse (const Value &value, formats::parse::To< Date >)

template<typename Value >
std::enable_if_t< formats::common::kIsFormatValue< Value >, Value >	Serialize (Date date, formats::serialize::To< Value >)

template<typename StringBuilder >
void	WriteToStream (Date value, StringBuilder &sw)

template<typename LogHelper = ::logging::LogHelper>
::logging::LogHelper &	operator<< (::logging::LogHelper &lh, const Date &date)

std::ostream &	operator<< (std::ostream &os, Date date)

std::chrono::system_clock::time_point	FromRfc3339StringSaturating (const std::string &timestring)
	Converts strings like "2012-12-12T00:00:00" to std::chrono::system_clock::time_point in UTC timezone and saturates on overflow Example:

std::chrono::system_clock::time_point	FromStringSaturating (const std::string &timestring, const std::string &format)
	Converts strings of the specified format starting with "%Y" to std::chrono::system_clock::time_point in UTC timezone and saturates on overflow.

void	MockNowSet (std::chrono::system_clock::time_point new_mocked_now)

void	MockSleep (std::chrono::milliseconds duration)

void	MockNowUnset () noexcept

bool	IsMockNow () noexcept

Duration arithmetic
template<typename LDuration , typename RDuration >
auto	operator- (TimeOfDay< LDuration > lhs, TimeOfDay< RDuration > rhs)

template<typename Duration , typename Rep , typename Period >
TimeOfDay< Duration >	operator+ (TimeOfDay< Duration > lhs, std::chrono::duration< Rep, Period > rhs)

template<typename Duration , typename Rep , typename Period >
TimeOfDay< Duration >	operator- (TimeOfDay< Duration > lhs, std::chrono::duration< Rep, Period > rhs)

template<typename Duration >
logging::LogHelper &	operator<< (logging::LogHelper &lh, TimeOfDay< Duration > value)

Variables
const std::string	kRfc3339Format = "%Y-%m-%dT%H:%M:%E*S%Ez"

const std::string	kTaximeterFormat = "%Y-%m-%dT%H:%M:%E6SZ"

constexpr std::time_t	kStartOfTheEpoch = 0

const std::string	kDefaultDriverTimezone = "Europe/Moscow"

const std::string	kDefaultTimezone = "UTC"

const std::string	kDefaultFormat = "%Y-%m-%dT%H:%M:%E*S%z"

const std::string	kIsoFormat = "%Y-%m-%dT%H:%M:%SZ"

Typedef Documentation

◆ timepair_t

using utils::datetime::timepair_t = std::pair<uint8_t, uint8_t>

Definition at line 31 of file datetime.hpp.

Function Documentation

◆ CalcTimeDiff()

template<class Duration , class Clock >

double utils::datetime::CalcTimeDiff	(	const std::chrono::time_point< Clock > &	a,
		const std::chrono::time_point< Clock > &	b )

Compute (a - b) with a specified duration.

Definition at line 205 of file datetime.hpp.

◆ FromRfc3339StringSaturating()

std::chrono::system_clock::time_point utils::datetime::FromRfc3339StringSaturating ( const std::string & timestring )

Converts strings like "2012-12-12T00:00:00" to std::chrono::system_clock::time_point in UTC timezone and saturates on overflow Example:

◆ GuessLocalTimezoneStringtime()

std::chrono::system_clock::time_point utils::datetime::GuessLocalTimezoneStringtime ( const std::string & timestamp )

Extracts time point from a string, guessing the format.

Exceptions

utils::datetime::DateParseError

◆ GuessStringtime()

std::chrono::system_clock::time_point utils::datetime::GuessStringtime	(	const std::string &	timestamp,
		const std::string &	timezone )

Extracts time point from a string, guessing the format.

Exceptions

utils::datetime::DateParseError
utils::datetime::TimezoneLookupError	Example: const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000"); EXPECT_EQ(utils::datetime::GuessStringtime("2014-03-17T02:47:07+0000", "UTC"), tp);

◆ IsMockNow()

bool utils::datetime::IsMockNow ( )

noexcept

Returns true if time point is mocked for utils::datetime::Now() and utils::datetime::SteadyNow().

◆ Localize()

cctz::civil_second utils::datetime::Localize	(	const std::chrono::system_clock::time_point &	tp,
		const std::string &	timezone )

Converts absolute time in std::chrono::system_clock::time_point to a civil time of a particular timezone.

Exceptions

utils::datetime::TimezoneLookupError

Example:

◆ LocalTimezoneStringtime()

std::chrono::system_clock::time_point utils::datetime::LocalTimezoneStringtime	(	const std::string &	timestring,
		const std::string &	format = kDefaultFormat )

Extracts time point from a string of a specified format.

Exceptions

utils::datetime::DateParseError

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

◆ LocalTimezoneTimestring() [1/2]

std::string utils::datetime::LocalTimezoneTimestring	(	std::chrono::system_clock::time_point	tp,
		const std::string &	format = kDefaultFormat )

Returns time in a string of specified format.

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

◆ LocalTimezoneTimestring() [2/2]

std::string utils::datetime::LocalTimezoneTimestring	(	std::time_t	timestamp,
		const std::string &	format = kDefaultFormat )

Returns time in a string of specified format.

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

◆ MockNowSet()

void utils::datetime::MockNowSet ( std::chrono::system_clock::time_point new_mocked_now )

Sets the mocked value for utils::datetime::Now() and utils::datetime::SteadyNow().

Thread safe.

◆ MockNowUnset()

void utils::datetime::MockNowUnset ( )

noexcept

Removes time point mocking for utils::datetime::Now() and utils::datetime::SteadyNow().

◆ MockSleep()

void utils::datetime::MockSleep ( std::chrono::milliseconds duration )

Adds duration to current mocked time point value

Thread safe.

Exceptions

utils::InvariantError if IsMockNow() returns false.

◆ Now()

std::chrono::system_clock::time_point utils::datetime::Now ( )

noexcept

std::chrono::system_clock::now() that could be mocked

Returns last time point passed to utils::datetime::MockNowSet(), or std::chrono::system_clock::now() if the timepoint is not mocked.

Examples: samples/config_service/config_service.cpp, samples/digest_auth_service/auth_digest.cpp, and samples/testsuite-support/src/now.cpp.

◆ operator+()

template<typename Duration , typename Rep , typename Period >

TimeOfDay< Duration > utils::datetime::operator+	(	TimeOfDay< Duration >	lhs,
		std::chrono::duration< Rep, Period >	rhs )

Definition at line 129 of file time_of_day.hpp.

◆ operator-() [1/2]

template<typename Duration , typename Rep , typename Period >

TimeOfDay< Duration > utils::datetime::operator-	(	TimeOfDay< Duration >	lhs,
		std::chrono::duration< Rep, Period >	rhs )

Definition at line 135 of file time_of_day.hpp.

◆ operator-() [2/2]

template<typename LDuration , typename RDuration >

auto utils::datetime::operator-	(	TimeOfDay< LDuration >	lhs,
		TimeOfDay< RDuration >	rhs )

Definition at line 124 of file time_of_day.hpp.

◆ operator<<() [1/2]

template<typename LogHelper = ::logging::LogHelper>

::logging::LogHelper & utils::datetime::operator<<	(	::logging::LogHelper &	lh,
		const Date &	date )

Definition at line 97 of file date.hpp.

◆ operator<<() [2/2]

template<typename Duration >

logging::LogHelper & utils::datetime::operator<<	(	logging::LogHelper &	lh,
		TimeOfDay< Duration >	value )

Definition at line 142 of file time_of_day.hpp.

◆ OptionalStringtime()

std::optional< std::chrono::system_clock::time_point > utils::datetime::OptionalStringtime	(	const std::string &	timestring,
		const std::string &	timezone = kDefaultTimezone,
		const std::string &	format = kDefaultFormat )

Returns optional time in a string of specified format Example:

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

◆ Parse()

template<typename Value >

std::enable_if_t< formats::common::kIsFormatValue< Value >, Date > utils::datetime::Parse	(	const Value &	value,
		formats::parse::To< Date >	)

Definition at line 68 of file date.hpp.

◆ ParseDayTime()

std::uint32_t utils::datetime::ParseDayTime ( const std::string & str )

Parse day time in hh:mm[:ss] format.

Parameters

str	day time in format hh:mm[:ss]

Returns: number of second since start of day

◆ Serialize()

template<typename Value >

std::enable_if_t< formats::common::kIsFormatValue< Value >, Value > utils::datetime::Serialize	(	Date	date,
		formats::serialize::To< Value >	)

Definition at line 87 of file date.hpp.

◆ SteadyNow()

std::chrono::steady_clock::time_point utils::datetime::SteadyNow ( )

noexcept

std::chrono::steady_clock::now() that could be mocked

Returns last time point passed to utils::datetime::MockNowSet(), or std::chrono::steady_clock::now() if the timepoint is not mocked.

It is only intended for period-based structures/algorithms testing.

Warning: You MUST NOT pass time points received from this function outside of your own code. Otherwise this will break your service in production.

◆ Stringtime()

std::chrono::system_clock::time_point utils::datetime::Stringtime	(	const std::string &	timestring,
		const std::string &	timezone = kDefaultTimezone,
		const std::string &	format = kDefaultFormat )

Extracts time point from a string of a specified format.

Exceptions

utils::datetime::DateParseError
utils::datetime::TimezoneLookupError	Example: const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000"); EXPECT_EQ(utils::datetime::Stringtime("2014-03-17T02:47:07+0000"), tp);

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

Examples: samples/config_service/config_service.cpp, and samples/mongo_service/mongo_service.cpp.

◆ TimePointToTicks()

int64_t utils::datetime::TimePointToTicks ( const std::chrono::system_clock::time_point & tp )

noexcept

Convert time_point to DotNet ticks.

Parameters

time	point day time

Returns: number of 100nanosec intervals between current date and 01/01/0001 Example:
const auto tp = utils::datetime::FromStringSaturating(

"2014-03-17 02:47:07.333304", "%Y-%m-%d %H:%M:%E*S");

const auto ticks = utils::datetime::TimePointToTicks(tp);

EXPECT_EQ((int64_t)635306212273333040, ticks);

EXPECT_EQ(utils::datetime::TicksToTimePoint(ticks), tp);

◆ Timestamp()

std::time_t utils::datetime::Timestamp ( std::chrono::system_clock::time_point tp )

noexcept

Converts time point to std::time_t Example:

  const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000");
  const auto c_time = utils::datetime::Timestamp(tp);
  EXPECT_EQ(utils::datetime::Timestring(c_time), "2014-03-17T02:47:07+0000");
  EXPECT_EQ(utils::datetime::TimestampToString(c_time),
            "2014-03-17T02:47:07+0000");

◆ TimestampToString()

std::string utils::datetime::TimestampToString ( std::time_t timestamp )

Returns string with time in ISO8601 format "YYYY-MM-DDTHH:MM:SS+0000".

Parameters

timestamp unix timestamp

◆ Timestring() [1/2]

std::string utils::datetime::Timestring	(	std::chrono::system_clock::time_point	tp,
		const std::string &	timezone = kDefaultTimezone,
		const std::string &	format = kDefaultFormat )

Returns time in a string of specified format.

Exceptions

utils::datetime::TimezoneLookupError

Example:

const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000");

EXPECT_EQ(utils::datetime::Timestring(tp), "2014-03-17T02:47:07+0000");

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

◆ Timestring() [2/2]

std::string utils::datetime::Timestring	(	std::time_t	timestamp,
		const std::string &	timezone = kDefaultTimezone,
		const std::string &	format = kDefaultFormat )

Returns time in a string of specified format.

Exceptions

utils::datetime::TimezoneLookupError

Example:

  const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000");
  const auto c_time = utils::datetime::Timestamp(tp);
  EXPECT_EQ(utils::datetime::Timestring(c_time), "2014-03-17T02:47:07+0000");
  EXPECT_EQ(utils::datetime::TimestampToString(c_time),
            "2014-03-17T02:47:07+0000");

See also: kRfc3339Format, kTaximeterFormat, kStartOfTheEpoch, kDefaultDriverTimezone, kDefaultTimezone, kDefaultFormat, kIsoFormat

Examples: samples/config_service/config_service.cpp, and samples/mongo_service/mongo_service.cpp.

◆ Unlocalize()

std::time_t utils::datetime::Unlocalize	(	const cctz::civil_second &	local_tp,
		const std::string &	timezone )

Converts a civil time in a specified timezone into an absolute time.

Exceptions

utils::datetime::TimezoneLookupError

Example:

◆ WriteToStream()

template<typename StringBuilder >

void utils::datetime::WriteToStream	(	Date	value,
		StringBuilder &	sw )

Definition at line 93 of file date.hpp.

Variable Documentation

◆ kDefaultDriverTimezone

const std::string utils::datetime::kDefaultDriverTimezone = "Europe/Moscow"

inline

  const auto tp = utils::datetime::Stringtime(
      "2014-03-17T02:47:07+00:00", utils::datetime::kDefaultDriverTimezone,
      utils::datetime::kRfc3339Format);
  EXPECT_EQ(utils::datetime::Stringtime("2014-03-17T02:47:07+0000"), tp);

Definition at line 23 of file datetime.hpp.

◆ kDefaultFormat

const std::string utils::datetime::kDefaultFormat = "%Y-%m-%dT%H:%M:%E*S%z"

inline

  const auto exp = utils::datetime::FromStringSaturating(
      "2014-03-17 02:47:07.000000", "%Y-%m-%d %H:%M:%E*S");
  const auto tp = utils::datetime::FromStringSaturating(
      "2014-03-17T02:47:07.000000+0000", utils::datetime::kDefaultFormat);
  EXPECT_EQ(tp, exp);

Definition at line 27 of file datetime.hpp.

◆ kDefaultTimezone

const std::string utils::datetime::kDefaultTimezone = "UTC"

inline

  const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+00:00",
                                              utils::datetime::kDefaultTimezone,
                                              utils::datetime::kRfc3339Format);
  EXPECT_EQ(utils::datetime::Stringtime("2014-03-17T02:47:07+0000"), tp);

Definition at line 25 of file datetime.hpp.

◆ kIsoFormat

const std::string utils::datetime::kIsoFormat = "%Y-%m-%dT%H:%M:%SZ"

inline

  const auto exp = utils::datetime::FromStringSaturating(
      "2014-03-17 02:47:07.000000", "%Y-%m-%d %H:%M:%E*S");
  const auto tp = utils::datetime::FromStringSaturating(
      "2014-03-17T02:47:07Z", utils::datetime::kIsoFormat);
  EXPECT_EQ(tp, exp);

Definition at line 29 of file datetime.hpp.

◆ kRfc3339Format

const std::string utils::datetime::kRfc3339Format = "%Y-%m-%dT%H:%M:%E*S%Ez"

inline

  const auto exp = utils::datetime::FromStringSaturating(
      "2014-03-17 02:47:07.000000", "%Y-%m-%d %H:%M:%E*S");
  const auto tp = utils::datetime::FromStringSaturating(
      "2014-03-17T02:47:07+00:00", utils::datetime::kRfc3339Format);
  EXPECT_EQ(tp, exp);

Definition at line 18 of file datetime.hpp.

◆ kStartOfTheEpoch

constexpr std::time_t utils::datetime::kStartOfTheEpoch = 0

inlineconstexpr

Definition at line 21 of file datetime.hpp.

◆ kTaximeterFormat

const std::string utils::datetime::kTaximeterFormat = "%Y-%m-%dT%H:%M:%E6SZ"

inline

Definition at line 20 of file datetime.hpp.

Detailed Description

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ timepair_t

Function Documentation

◆ CalcTimeDiff()

◆ FromRfc3339StringSaturating()

◆ GuessLocalTimezoneStringtime()

◆ GuessStringtime()

◆ IsMockNow()

◆ Localize()

◆ LocalTimezoneStringtime()

◆ LocalTimezoneTimestring() [1/2]

◆ LocalTimezoneTimestring() [2/2]

◆ MockNowSet()

◆ MockNowUnset()

◆ MockSleep()

◆ Now()

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator<<() [1/2]

◆ operator<<() [2/2]

◆ OptionalStringtime()

◆ Parse()

◆ ParseDayTime()

◆ Serialize()

◆ SteadyNow()

◆ Stringtime()

◆ TimePointToTicks()

◆ Timestamp()

◆ TimestampToString()

◆ Timestring() [1/2]

◆ Timestring() [2/2]

◆ Unlocalize()

◆ WriteToStream()

Variable Documentation

◆ kDefaultDriverTimezone

◆ kDefaultFormat

◆ kDefaultTimezone

◆ kIsoFormat

◆ kRfc3339Format

◆ kStartOfTheEpoch

◆ kTaximeterFormat