Distance
@CarProtocol
class Distance
Represents a distance value and how it should be displayed in the UI.
Summary
Constants |
|
|---|---|
const Int |
UNIT_FEET = 6Feet unit. |
const Int |
UNIT_KILOMETERS = 2Kilometer unit. |
const 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). |
const Int |
UNIT_METERS = 1Meter unit. |
const Int |
UNIT_MILES = 4Miles unit. |
const 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). |
const Int |
UNIT_YARDS = 7Yards unit. |
Public functions |
|
|---|---|
java-static Distance |
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() |
String |
toString() |
Constants
UNIT_KILOMETERS_P1
const val UNIT_KILOMETERS_P1 = 3: 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).
UNIT_MILES_P1
const val UNIT_MILES_P1 = 5: Int
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 functions
create
java-static fun create(displayDistance: Double, displayUnit: Int): Distance
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 | |
|---|---|
displayDistance: Double |
the distance to display, in the units specified in |
displayUnit: Int |
the unit of distance to use when displaying the value in |
| Throws | |
|---|---|
java.lang.IllegalArgumentException |
if |
getDisplayDistance
fun getDisplayDistance(): Double
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
fun getDisplayUnit(): Int
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.