Class Timestamps
- java.lang.Object
-
- com.google.protobuf.util.Timestamps
-
public final class Timestamps extends java.lang.Object
Utilities to help create/manipulateprotobuf/timestamp.proto
. All operations throw anIllegalArgumentException
if the input(s) are not valid.
-
-
Field Summary
Fields Modifier and Type Field Description static Timestamp
EPOCH
A constant holding theTimestamp
of epoch time,1970-01-01T00:00:00.000000000Z
.static Timestamp
MAX_VALUE
A constant holding the maximum validTimestamp
,9999-12-31T23:59:59.999999999Z
.static Timestamp
MIN_VALUE
A constant holding the minimum validTimestamp
,0001-01-01T00:00:00Z
.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static Timestamp
add(Timestamp start, Duration length)
Add a duration to a timestamp.static Duration
between(Timestamp from, Timestamp to)
Calculate the difference between two timestamps.static Timestamp
checkValid(Timestamp timestamp)
Throws anIllegalArgumentException
if the givenTimestamp
is not valid.static Timestamp
checkValid(Timestamp.Builder timestampBuilder)
Builds the given builder and throws anIllegalArgumentException
if it is not valid.static java.util.Comparator<Timestamp>
comparator()
Returns aComparator
forTimestamps
which sorts in increasing chronological order.static int
compare(Timestamp x, Timestamp y)
Compares two timestamps.static Timestamp
fromDate(java.util.Date date)
Create a Timestamp from aDate
.static Timestamp
fromMicros(long microseconds)
Create a Timestamp from the number of microseconds elapsed from the epoch.static Timestamp
fromMillis(long milliseconds)
Create a Timestamp from the number of milliseconds elapsed from the epoch.static Timestamp
fromNanos(long nanoseconds)
Create a Timestamp from the number of nanoseconds elapsed from the epoch.static Timestamp
fromSeconds(long seconds)
Create a Timestamp from the number of seconds elapsed from the epoch.static boolean
isValid(long seconds, int nanos)
Returns true if the given number of seconds and nanos is a validTimestamp
.static boolean
isValid(Timestamp timestamp)
Returns true if the givenTimestamp
is valid.static Timestamp
now()
Create a Timestamp using the best-available system clock.static Timestamp
parse(java.lang.String value)
Parse from RFC 3339 date string to Timestamp.static Timestamp
parseUnchecked(java.lang.String value)
Parses a string in RFC 3339 format into aTimestamp
.static Timestamp
subtract(Timestamp start, Duration length)
Subtract a duration from a timestamp.static long
toMicros(Timestamp timestamp)
Convert a Timestamp to the number of microseconds elapsed from the epoch.static long
toMillis(Timestamp timestamp)
Convert a Timestamp to the number of milliseconds elapsed from the epoch.static long
toNanos(Timestamp timestamp)
Convert a Timestamp to the number of nanoseconds elapsed from the epoch.static long
toSeconds(Timestamp timestamp)
Convert a Timestamp to the number of seconds elapsed from the epoch.static java.lang.String
toString(Timestamp timestamp)
Convert Timestamp to RFC 3339 date string format.
-
-
-
Method Detail
-
comparator
public static java.util.Comparator<Timestamp> comparator()
Returns aComparator
forTimestamps
which sorts in increasing chronological order. Nulls and invalidTimestamps
are not allowed (seeisValid(com.google.protobuf.Timestamp)
). The returned comparator is serializable.
-
compare
public static int compare(Timestamp x, Timestamp y)
Compares two timestamps. The value returned is identical to what would be returned by:Timestamps.comparator().compare(x, y)
.- Returns:
- the value
0
ifx == y
; a value less than0
ifx < y
; and a value greater than0
ifx > y
-
isValid
public static boolean isValid(Timestamp timestamp)
Returns true if the givenTimestamp
is valid. Theseconds
value must be in the range [-62,135,596,800, +253,402,300,799] (i.e., between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z). Thenanos
value must be in the range [0, +999,999,999].Note: Negative second values with fractional seconds must still have non-negative nanos values that count forward in time.
-
isValid
public static boolean isValid(long seconds, int nanos)
Returns true if the given number of seconds and nanos is a validTimestamp
. Theseconds
value must be in the range [-62,135,596,800, +253,402,300,799] (i.e., between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z). Thenanos
value must be in the range [0, +999,999,999].Note: Negative second values with fractional seconds must still have non-negative nanos values that count forward in time.
-
checkValid
@CanIgnoreReturnValue public static Timestamp checkValid(Timestamp timestamp)
Throws anIllegalArgumentException
if the givenTimestamp
is not valid.
-
checkValid
public static Timestamp checkValid(Timestamp.Builder timestampBuilder)
Builds the given builder and throws anIllegalArgumentException
if it is not valid. SeecheckValid(Timestamp)
.- Returns:
- A valid, built
Timestamp
.
-
toString
public static java.lang.String toString(Timestamp timestamp)
Convert Timestamp to RFC 3339 date string format. The output will always be Z-normalized and uses 3, 6 or 9 fractional digits as required to represent the exact value. Note that Timestamp can only represent time from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. See https://www.ietf.org/rfc/rfc3339.txtExample of generated format: "1972-01-01T10:00:20.021Z"
- Returns:
- The string representation of the given timestamp.
- Throws:
java.lang.IllegalArgumentException
- if the given timestamp is not in the valid range.
-
parse
public static Timestamp parse(java.lang.String value) throws java.text.ParseException
Parse from RFC 3339 date string to Timestamp. This method accepts all outputs oftoString(Timestamp)
and it also accepts any fractional digits (or none) and any offset as long as they fit into nano-seconds precision.Example of accepted format: "1972-01-01T10:00:20.021-05:00"
- Returns:
- a Timestamp parsed from the string
- Throws:
java.text.ParseException
- if parsing fails
-
parseUnchecked
public static Timestamp parseUnchecked(@CompileTimeConstant java.lang.String value)
Parses a string in RFC 3339 format into aTimestamp
.Identical to
parse(String)
, but throws anIllegalArgumentException
instead of aParseException
if parsing fails.- Returns:
- a
Timestamp
parsed from the string - Throws:
java.lang.IllegalArgumentException
- if parsing fails
-
now
public static Timestamp now()
Create a Timestamp using the best-available system clock.
-
fromSeconds
public static Timestamp fromSeconds(long seconds)
Create a Timestamp from the number of seconds elapsed from the epoch.
-
toSeconds
public static long toSeconds(Timestamp timestamp)
Convert a Timestamp to the number of seconds elapsed from the epoch.The result will be rounded down to the nearest second. E.g., if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 second.
-
fromMillis
public static Timestamp fromMillis(long milliseconds)
Create a Timestamp from the number of milliseconds elapsed from the epoch.
-
fromDate
public static Timestamp fromDate(java.util.Date date)
Create a Timestamp from aDate
. If theDate
is aTimestamp
, full nanonsecond precision is retained.- Throws:
java.lang.IllegalArgumentException
- if the year is before 1 CE or after 9999 CE
-
toMillis
public static long toMillis(Timestamp timestamp)
Convert a Timestamp to the number of milliseconds elapsed from the epoch.The result will be rounded down to the nearest millisecond. For instance, if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 millisecond.
-
fromMicros
public static Timestamp fromMicros(long microseconds)
Create a Timestamp from the number of microseconds elapsed from the epoch.
-
toMicros
public static long toMicros(Timestamp timestamp)
Convert a Timestamp to the number of microseconds elapsed from the epoch.The result will be rounded down to the nearest microsecond. E.g., if the timestamp represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 microsecond.
-
fromNanos
public static Timestamp fromNanos(long nanoseconds)
Create a Timestamp from the number of nanoseconds elapsed from the epoch.
-
toNanos
public static long toNanos(Timestamp timestamp)
Convert a Timestamp to the number of nanoseconds elapsed from the epoch.
-
between
public static Duration between(Timestamp from, Timestamp to)
Calculate the difference between two timestamps.
-
-