# Class Timestamps (3.19.4)

    public final class Timestamps

Utilities to help create/manipulate `protobuf/timestamp.proto`. All operations throw an
IllegalArgumentException if the input(s) are not [valid](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.util.Timestamps#com_google_protobuf_util_Timestamps_isValid_com_google_protobuf_Timestamp_).

## Inheritance

[java.lang.Object](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html) \> Timestamps

## Inherited Members

[Object.clone()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--) [Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-) [Object.finalize()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--) [Object.getClass()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--) [Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--) [Object.notify()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--) [Object.notifyAll()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--) [Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--) [Object.wait()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--) [Object.wait(long)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-) [Object.wait(long,int)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-)

## Static Fields

### EPOCH

    public static final Timestamp EPOCH

A constant holding the [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) of epoch time, `1970-01-01T00:00:00.000000000Z`.

| **Field Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### MAX_VALUE

    public static final Timestamp MAX_VALUE

A constant holding the maximum valid [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp), `9999-12-31T23:59:59.999999999Z`.

| **Field Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### MIN_VALUE

    public static final Timestamp MIN_VALUE

A constant holding the minimum valid [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp), `0001-01-01T00:00:00Z`.

| **Field Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

## Static Methods

### add(Timestamp start, Duration length)

    public static Timestamp add(Timestamp start, Duration length)

Add a duration to a timestamp.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `start` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |
| `length` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Duration` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### between(Timestamp from, Timestamp to)

    public static Duration between(Timestamp from, Timestamp to)

Calculate the difference between two timestamps.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `from` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |
| `to` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Duration` |   |

### checkValid(Timestamp timestamp)

    public static Timestamp checkValid(Timestamp timestamp)

Throws an IllegalArgumentException if the given [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) is not valid.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### checkValid(Timestamp.Builder timestampBuilder)

    public static Timestamp checkValid(Timestamp.Builder timestampBuilder)

Builds the given builder and throws an IllegalArgumentException if it is not valid. See
[#checkValid(Timestamp)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.util.Timestamps#com_google_protobuf_util_Timestamps_checkValid_com_google_protobuf_Timestamp_).

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestampBuilder` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp.Builder` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` | A valid, built [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp). |

### comparator()

    public static Comparator<Timestamp> comparator()

Returns a [Comparator](https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html) for [Timestamps](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) which sorts in increasing
chronological order. Nulls and invalid [Timestamps](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) are not allowed (see
[#isValid](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.util.Timestamps#com_google_protobuf_util_Timestamps_isValid_)). The returned comparator is serializable.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html<https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp>` |   |

### compare(Timestamp x, Timestamp y)

    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)`.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `x` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |
| `y` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` | the value `0` if `x == y`; a value less than `0` if `x < y`; and a value greater than `0` if `x > y` |

### fromDate(Date date)

    public static Timestamp fromDate(Date date)

Create a Timestamp from a java.util.Date. If the java.util.Date is a java.sql.Timestamp,
full nanonsecond precision is retained.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `date` | `https://docs.oracle.com/javase/8/docs/api/java/util/Date.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### fromMicros(long microseconds)

    public static Timestamp fromMicros(long microseconds)

Create a Timestamp from the number of microseconds elapsed from the epoch.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `microseconds` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### fromMillis(long milliseconds)

    public static Timestamp fromMillis(long milliseconds)

Create a Timestamp from the number of milliseconds elapsed from the epoch.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `milliseconds` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### fromNanos(long nanoseconds)

    public static Timestamp fromNanos(long nanoseconds)

Create a Timestamp from the number of nanoseconds elapsed from the epoch.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `nanoseconds` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### fromSeconds(long seconds)

    public static Timestamp fromSeconds(long seconds)

Create a Timestamp from the number of seconds elapsed from the epoch.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `seconds` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### isValid(Timestamp timestamp)

    public static boolean isValid(Timestamp timestamp)

Returns true if the given [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) is valid. The `seconds` 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). The `nanos` 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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### isValid(long seconds, int nanos)

    public static boolean isValid(long seconds, int nanos)

Returns true if the given number of seconds and nanos is a valid [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp). The `
seconds` 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). The `nanos` 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.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `seconds` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |
| `nanos` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### parse(String value)

    public static Timestamp parse(String value)

Parse from RFC 3339 date string to Timestamp. This method accepts all outputs of [#toString(Timestamp)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.util.Timestamps#com_google_protobuf_util_Timestamps_toString_com_google_protobuf_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"

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `value` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` | A Timestamp parsed from the string. |

| **Exceptions** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/text/ParseException.html` | if parsing fails. |

### parseUnchecked(String value)

    public static Timestamp parseUnchecked(String value)

Parses a string in RFC 3339 format into a [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp).

Identical to [#parse(String)](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.util.Timestamps#com_google_protobuf_util_Timestamps_parse_java_lang_String_), but throws an IllegalArgumentException instead
of a [ParseException](https://docs.oracle.com/javase/8/docs/api/java/text/ParseException.html) if parsing fails.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `value` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` | a [Timestamp](https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp) parsed from the string |

### subtract(Timestamp start, Duration length)

    public static Timestamp subtract(Timestamp start, Duration length)

Subtract a duration from a timestamp.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `start` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |
| `length` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Duration` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |   |

### toMicros(Timestamp timestamp)

    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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### toMillis(Timestamp timestamp)

    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. E.g., if the timestamp
represents "1969-12-31T23:59:59.999999999Z", it will be rounded to -1 millisecond.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### toNanos(Timestamp timestamp)

    public static long toNanos(Timestamp timestamp)

Convert a Timestamp to the number of nanoseconds elapsed from the epoch.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### toSeconds(Timestamp timestamp)

    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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` |   |

### toString(Timestamp timestamp)

    public static 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.txt>

Example of generated format: "1972-01-01T10:00:20.021Z"

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `timestamp` | `https://docs.cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.Timestamp` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | The string representation of the given timestamp. |