# DateTimeWithZone

Artifact: [androidx.car.app:app](https://developer.android.com/jetpack/androidx/releases/car-app) [View Source](https://cs.android.com/search?q=file:androidx/car/app/model/DateTimeWithZone.java+class:androidx.car.app.model.DateTimeWithZone) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
@CarProtocol
public final class DateTimeWithZone
```

<br />

*** ** * ** ***

A time with an associated time zone information.

In order to avoid time zone databases being out of sync between the app and the host, this model avoids using [IANA database](https://www.iana.org/time-zones) time zone IDs and instead relies on the app passing the time zone offset and its abbreviated name. Apps can use their time library of choice to retrieve the time zone information.

`https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(long,java.util.TimeZone)` and `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(java.time.ZonedDateTime)` are provided for convenience if using `java.util` and `java.time` respectively. If using another library such as Joda time, `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(long,int,java.lang.String)` can be used.

## Summary

| ### Public methods |
|---|---|
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 26) https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(java.time.ZonedDateTime)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/time/ZonedDateTime.html zonedDateTime)` Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`. |
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(long,java.util.TimeZone)(long timeSinceEpochMillis, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/TimeZone.html timeZone)` Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`. |
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#create(long,int,java.lang.String)( long timeSinceEpochMillis, @https://developer.android.com/reference/androidx/annotation/IntRange(from = "-64800", to = 64800) int zoneOffsetSeconds, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html zoneShortName )` Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`. |
| `boolean` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#equals(java.lang.Object)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/Object.html other)` |
| `long` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#getTimeSinceEpochMillis()()` Returns the number of milliseconds from the epoch of 1970-01-01T00:00:00Z. |
| `int` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#getZoneOffsetSeconds()()` Returns the offset of the time zone from UTC. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#getZoneShortName()()` Returns the abbreviated name of the time zone, for example "PST" for Pacific Standard Time. |
| `int` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#hashCode()()` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone#toString()()` |

## Public methods

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
@RequiresApi(value = 26)
public static @NonNull DateTimeWithZone create(@NonNull ZonedDateTime zonedDateTime)
```

Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/time/ZonedDateTime.html zonedDateTime` | The time with a time zone. The abbreviated name of this time zone, formatted using the default locale, may be displayed to the user when needed, for example, if this time zone is different than the current system time zone |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `zonedDateTime` is `null` |

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public static @NonNull DateTimeWithZone create(long timeSinceEpochMillis, @NonNull TimeZone timeZone)
```

Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`.

| Parameters |
|---|---|
| `long timeSinceEpochMillis` | The number of milliseconds from the epoch of 1970-01-01T00:00:00Z |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/TimeZone.html timeZone` | The time zone at the date specified by `timeInUtcMillis`. The abbreviated name of this time zone, formatted using the default locale, may be displayed to the user when needed, for example, if this time zone is different than the current system time zone |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `timeSinceEpochMillis` is a negative value |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `timeZone` is `null` |

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public static @NonNull DateTimeWithZone create(
    long timeSinceEpochMillis,
    @IntRange(from = "-64800", to = 64800) int zoneOffsetSeconds,
    @NonNull String zoneShortName
)
```

Returns an instance of a `https://developer.android.com/reference/androidx/car/app/model/DateTimeWithZone`.

| Parameters |
|---|---|
| `long timeSinceEpochMillis` | The number of milliseconds from the epoch of 1970-01-01T00:00:00Z |
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = "-64800", to = 64800) int zoneOffsetSeconds` | The offset of the time zone from UTC at the date specified by `timeInUtcMillis`. This offset must be in the range `-18:00` to `+18:00`, which corresponds to -64800 to +64800 |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html zoneShortName` | The abbreviated name of the time zone, for example, "PST" for Pacific Standard Time. This string may be used to display to the user along with the date when needed, for example, if this time zone is different than the current system time zone |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `timeSinceEpochMillis` is a negative value, if `zoneOffsetSeconds` is not within the required range, or if `zoneShortName` is empty |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `zoneShortName` is `null` |

### equals

```
public boolean equals(@Nullable Object other)
```

### getTimeSinceEpochMillis

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public long getTimeSinceEpochMillis()
```

Returns the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.

### getZoneOffsetSeconds

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public int getZoneOffsetSeconds()
```

Returns the offset of the time zone from UTC.

### getZoneShortName

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @Nullable String getZoneShortName()
```

Returns the abbreviated name of the time zone, for example "PST" for Pacific Standard Time.

### hashCode

```
public int hashCode()
```

### toString

```
public @NonNull String toString()
```