time_util.h

This section contains reference documentation for working with protocol buffer classes in C++.

#include <google/protobuf/util/time_util.h>
namespace google::protobuf::util

Defines utilities for the Timestamp and Duration well known types.

Classes in this file

Utility functions for Timestamp and Duration.

class TimeUtil

#include <google/protobuf/util/time_util.h>
namespace google::protobuf::util

Utility functions for Timestamp and Duration.

Members

const int64_t
kTimestampMinSeconds = = -62135596800LL
The min/max Timestamp/Duration values we support. more...
const int64_t
kTimestampMaxSeconds = = 253402300799LL
For "9999-12-31T23:59:59.999999999Z".
const int64_t
kDurationMinSeconds = = -315576000000LL
const int64_t
kDurationMaxSeconds = = 315576000000LL
static std::string
ToString(const Timestamp & timestamp)
Converts Timestamp to/from RFC 3339 date string format. more...
static bool
FromString(const std::string & value, Timestamp * timestamp)
static std::string
ToString(const Duration & duration)
Converts Duration to/from string format. more...
static bool
FromString(const std::string & value, Duration * timestamp)
static Timestamp
GetCurrentTime()
Gets the current UTC time.
static Timestamp
GetEpoch()
Returns the Time representing "1970-01-01 00:00:00".
static Duration
NanosecondsToDuration(int64_t nanos)
Converts between Duration and integer types. more...
static Duration
MicrosecondsToDuration(int64_t micros)
static Duration
MillisecondsToDuration(int64_t millis)
static Duration
SecondsToDuration(int64_t seconds)
static Duration
MinutesToDuration(int64_t minutes)
static Duration
HoursToDuration(int64_t hours)
static int64_t
DurationToNanoseconds(const Duration & duration)
Result will be truncated towards zero. more...
static int64_t
DurationToMicroseconds(const Duration & duration)
static int64_t
DurationToMilliseconds(const Duration & duration)
static int64_t
DurationToSeconds(const Duration & duration)
static int64_t
DurationToMinutes(const Duration & duration)
static int64_t
DurationToHours(const Duration & duration)
static Timestamp
NanosecondsToTimestamp(int64_t nanos)
Creates Timestamp from integer types. more...
static Timestamp
MicrosecondsToTimestamp(int64_t micros)
static Timestamp
MillisecondsToTimestamp(int64_t millis)
static Timestamp
SecondsToTimestamp(int64_t seconds)
static int64_t
TimestampToNanoseconds(const Timestamp & timestamp)
Result will be truncated down to the nearest integer value. more...
static int64_t
TimestampToMicroseconds(const Timestamp & timestamp)
static int64_t
TimestampToMilliseconds(const Timestamp & timestamp)
static int64_t
TimestampToSeconds(const Timestamp & timestamp)
static Timestamp
TimeTToTimestamp(time_t value)
Conversion to/from other time/date types. more...
static time_t
TimestampToTimeT(const Timestamp & value)
static Timestamp
TimevalToTimestamp(const timeval & value)
Conversion to/from timeval.
static timeval
TimestampToTimeval(const Timestamp & value)
static Duration
TimevalToDuration(const timeval & value)
static timeval
DurationToTimeval(const Duration & value)

const int64_t TimeUtil::kTimestampMinSeconds = = -62135596800LL

The min/max Timestamp/Duration values we support.

For "0001-01-01T00:00:00Z".


static std::string TimeUtil::ToString(
        const Timestamp & timestamp)

Converts Timestamp to/from RFC 3339 date string format.

Generated output will always be Z-normalized and uses 3, 6 or 9 fractional digits as required to represent the exact time. When parsing, any fractional digits (or none) and any offset are accepted as long as they fit into nano-seconds precision. Note that Timestamp can only represent time from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. Converting a Timestamp outside of this range is undefined behavior. See https://www.ietf.org/rfc/rfc3339.txt.

Example of generated format:

"1972-01-01T10:00:20.021Z"

Example of accepted format:

"1972-01-01T10:00:20.021-05:00"

static std::string TimeUtil::ToString(
        const Duration & duration)

Converts Duration to/from string format.

The string format will contains 3, 6, or 9 fractional digits depending on the precision required to represent the exact Duration value. For example:

"1s", "1.010s", "1.000000100s", "-3.100s"

The range that can be represented by Duration is from -315,576,000,000 to +315,576,000,000 inclusive (in seconds).


static Duration TimeUtil::NanosecondsToDuration(
        int64_t nanos)

Converts between Duration and integer types.

The behavior is undefined if the input value is not in the valid range of Duration.


static int64_t TimeUtil::DurationToNanoseconds(
        const Duration & duration)

Result will be truncated towards zero.

For example, "-1.5s" will be truncated to "-1s", and "1.5s" to "1s" when converting to seconds. It's undefined behavior if the input duration is not valid or the result exceeds the range of int64. A duration is not valid if it's not in the valid range of Duration, or have an invalid nanos value (i.e., larger than 999999999, less than -999999999, or have a different sign from the seconds part).


static Timestamp TimeUtil::NanosecondsToTimestamp(
        int64_t nanos)

Creates Timestamp from integer types.

The integer value indicates the time elapsed from Epoch time. The behavior is undefined if the input value is not in the valid range of Timestamp.


static int64_t TimeUtil::TimestampToNanoseconds(
        const Timestamp & timestamp)

Result will be truncated down to the nearest integer value.

For example, with "1969-12-31T23:59:59.9Z", TimestampToMilliseconds() returns -100 and TimestampToSeconds() returns -1. It's undefined behavior if the input Timestamp is not valid (i.e., its seconds part or nanos part does not fall in the valid range) or the return value doesn't fit into int64.


static Timestamp TimeUtil::TimeTToTimestamp(
        time_t value)

Conversion to/from other time/date types.

Note that these types may have a different precision and time range from Timestamp/Duration. When converting to a lower precision type, the value will be truncated to the nearest value that can be represented. If the value is out of the range of the result type, the return value is undefined.

Conversion to/from time_t