userver: utils::datetime Namespace Reference
Loading...
Searching...
No Matches
utils::datetime Namespace Reference

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  TimePointTz
 Timepoint with timezone parsed in kRfc3339Format. More...
 
class  TimePointTzBase
 
class  TimePointTzIsoBasic
 Timepoint with timezone parsed in kDefaultFormat. More...
 
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<std::uint8_t, std::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.
 
std::time_t Timestamp (std::chrono::system_clock::time_point tp) noexcept
 Converts time point to std::time_t.
 
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".
 
std::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 (std::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 >, DateParse (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::LogHelperoperator<< (::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.
 
bool operator< (const TimePointTzBase::TimePoint &lhs, const TimePointTzBase &rhs)
 
bool operator> (const TimePointTzBase::TimePoint &lhs, const TimePointTzBase &rhs)
 
bool operator<= (const TimePointTzBase::TimePoint &lhs, const TimePointTzBase &rhs)
 
bool operator>= (const TimePointTzBase::TimePoint &lhs, const TimePointTzBase &rhs)
 
logging::LogHelperoperator<< (logging::LogHelper &os, const TimePointTz &v)
 
logging::LogHelperoperator<< (logging::LogHelper &os, const TimePointTzIsoBasic &v)
 
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::LogHelperoperator<< (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<std::uint8_t, std::uint8_t>

Definition at line 32 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 227 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:

EXPECT_EQ(
utils::datetime::FromRfc3339StringSaturating("10000-01-01T00:00:00+0000"),
std::chrono::system_clock::time_point::max());

◆ 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:

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

◆ 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::InvariantErrorif 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]

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:

const auto tp = utils::datetime::Stringtime("2014-03-17T02:47:07+0000");
EXPECT_EQ(
utils::datetime::OptionalStringtime("2014-03-17T02:47:07+0000").value(),
tp);
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
strday 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()

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

Convert time_point to DotNet ticks.

Parameters
timepoint day time
Returns
number of 100nanosec intervals between current date and 01/01/0001

Example:

"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");
"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
timestampunix 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");
"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:

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

◆ 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,
EXPECT_EQ(utils::datetime::Stringtime("2014-03-17T02:47:07+0000"), tp);

Definition at line 24 of file datetime.hpp.

◆ kDefaultFormat

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

Definition at line 28 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",
EXPECT_EQ(utils::datetime::Stringtime("2014-03-17T02:47:07+0000"), tp);

Definition at line 26 of file datetime.hpp.

◆ kIsoFormat

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

Definition at line 30 of file datetime.hpp.

◆ kRfc3339Format

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

Definition at line 19 of file datetime.hpp.

◆ kStartOfTheEpoch

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

Definition at line 22 of file datetime.hpp.

◆ kTaximeterFormat

const std::string utils::datetime::kTaximeterFormat = "%Y-%m-%dT%H:%M:%E6SZ"
inline
"2014-03-17 02:47:07.000000", "%Y-%m-%d %H:%M:%E*S");
"2014-03-17T02:47:07.000000Z", utils::datetime::kTaximeterFormat);
EXPECT_EQ(tp, exp);

Definition at line 21 of file datetime.hpp.