# Distance

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/Distance.java+class:androidx.car.app.model.Distance) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
@CarProtocol
public final class Distance
```

<br />

*** ** * ** ***

Represents a distance value and how it should be displayed in the UI.

## Summary

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_FEET() = 6` Feet unit. |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS() = 2` Kilometer unit. |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1() = 3` Kilometer unit with the additional requirement that distances of this type be displayed with at least 1 digit of precision after the decimal point (for example, 2.0). |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_METERS() = 1` Meter unit. |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_MILES() = 4` Miles unit. |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_MILES_P1() = 5` Mile unit with the additional requirement that distances of this type be displayed with at least 1 digit of precision after the decimal point (for example, 2.0). |
| `static final int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_YARDS() = 7` Yards unit. |

| ### Public methods |
|---|---|
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Distance` | `https://developer.android.com/reference/androidx/car/app/model/Distance#create(double,int)(double displayDistance, int displayUnit)` Constructs a new instance of a `https://developer.android.com/reference/androidx/car/app/model/Distance`. |
| `boolean` | `https://developer.android.com/reference/androidx/car/app/model/Distance#equals(java.lang.Object)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/Object.html other)` |
| `double` | `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayDistance()()` Returns the distance measured in the unit indicated at `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayUnit()`. |
| `int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayUnit()()` Returns the unit that should be used to display the distance value, adjusted to the current user's locale and location. |
| `int` | `https://developer.android.com/reference/androidx/car/app/model/Distance#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/Distance#toString()()` |

## Constants

### UNIT_FEET

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

```
public static final int UNIT_FEET = 6
```

Feet unit.

### UNIT_KILOMETERS

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

```
public static final int UNIT_KILOMETERS = 2
```

Kilometer unit.

### UNIT_KILOMETERS_P1

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

```
public static final int UNIT_KILOMETERS_P1 = 3
```

Kilometer unit with the additional requirement that distances of this type be displayed with at least 1 digit of precision after the decimal point (for example, 2.0).

### UNIT_METERS

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

```
public static final int UNIT_METERS = 1
```

Meter unit.

### UNIT_MILES

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

```
public static final int UNIT_MILES = 4
```

Miles unit.

### UNIT_MILES_P1

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

```
public static final int UNIT_MILES_P1 = 5
```

Mile unit with the additional requirement that distances of this type be displayed with at least 1 digit of precision after the decimal point (for example, 2.0).

### UNIT_YARDS

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

```
public static final int UNIT_YARDS = 7
```

Yards unit.

## Public methods

### create

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

```
public static @NonNull Distance create(double displayDistance, int displayUnit)
```

Constructs a new instance of a `https://developer.android.com/reference/androidx/car/app/model/Distance`.

Units with precision requirements, `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1()` and `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_MILES_P1()`, will always show one decimal digit. All other units will show a decimal digit if needed but will not if the distance is a whole number.

#### Examples

A display distance of 1.0 with a display unit of `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS()` will display "1 km", whereas if the display unit is `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1()` it will display "1.0 km". Note the "km" part of the string in this example depends on the locale the host is configured with.

A display distance of 1.46 however will display "1.4 km" for both `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS()` and `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS()` display units.

`https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1()` and `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_MILES_P1()` can be used to provide consistent digit placement for a sequence of distances. For example, as the user is driving and the next turn distance changes, using `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1()` will produce: "2.5 km", "2.0 km", "1.5 km", "1.0 km", and so on.

| Parameters |
|---|---|
| `double displayDistance` | the distance to display, in the units specified in ` displayUnit`. See `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayDistance()` |
| `int displayUnit` | the unit of distance to use when displaying the value in ` displayUnit`. This should be one of the `UNIT_*` static constants defined in this class. See `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayUnit()` |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `displayDistance` is negative |

### equals

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

### getDisplayDistance

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

```
public double getDisplayDistance()
```

Returns the distance measured in the unit indicated at `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayUnit()`.

This distance is for display purposes only and it might be a rounded representation of the actual distance. For example, a distance of 1000 meters could be shown in the following ways:

- Display unit of `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_METERS()` and distance of 1000, resulting in a display of "1000 m".
- Display unit of `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS()` and distance of 1, resulting in a display of "1 km".
- Display unit of `https://developer.android.com/reference/androidx/car/app/model/Distance#UNIT_KILOMETERS_P1()` and distance of 1, resulting in a display of "1.0 km".

### getDisplayUnit

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

```
public int getDisplayUnit()
```

Returns the unit that should be used to display the distance value, adjusted to the current user's locale and location. This should match the unit used in `https://developer.android.com/reference/androidx/car/app/model/Distance#getDisplayDistance()`.

### hashCode

```
public int hashCode()
```

### toString

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