Distance
@CarProtocol
public final class Distance
Represents a distance value and how it should be displayed in the UI.
Summary
Constants |
|
|---|---|
static final int |
UNIT_FEET = 6Feet unit. |
static final int |
UNIT_KILOMETERS = 2Kilometer unit. |
static final int |
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 |
UNIT_METERS = 1Meter unit. |
static final int |
UNIT_MILES = 4Miles unit. |
static final int |
UNIT_MILES_P1 = 5Mile 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 |
UNIT_YARDS = 7Yards unit. |
Public methods |
|
|---|---|
static @NonNull Distance |
create(double displayDistance, int displayUnit)Constructs a new instance of a |
boolean |
|
double |
Returns the distance measured in the unit indicated at |
int |
Returns the unit that should be used to display the distance value, adjusted to the current user's locale and location. |
int |
hashCode() |
@NonNull String |
toString() |
Constants
UNIT_KILOMETERS_P1
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_MILES_P1
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).
Public methods
create
public static @NonNull Distance create(double displayDistance, int displayUnit)
Constructs a new instance of a Distance.
Units with precision requirements, UNIT_KILOMETERS_P1 and 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.
UNIT_KILOMETERS will display "1 km", whereas if the display unit is 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 UNIT_KILOMETERS and UNIT_KILOMETERS display units.
UNIT_KILOMETERS_P1 and 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 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 |
int displayUnit |
the unit of distance to use when displaying the value in |
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
if |
getDisplayDistance
public double getDisplayDistance()
Returns the distance measured in the unit indicated at 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
UNIT_METERSand distance of 1000, resulting in a display of "1000 m". - Display unit of
UNIT_KILOMETERSand distance of 1, resulting in a display of "1 km". - Display unit of
UNIT_KILOMETERS_P1and distance of 1, resulting in a display of "1.0 km".
getDisplayUnit
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 getDisplayDistance.