Distance

@CarProtocol
class Distance


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

Summary

Constants

const Int

Feet unit.

const Int

Kilometer 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

Meter unit.

const Int

Miles unit.

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

const Int

Yards unit.

Public functions

java-static Distance
create(displayDistance: Double, displayUnit: Int)

Constructs a new instance of a Distance.

Boolean
equals(other: Any?)
Double

Returns the distance measured in the unit indicated at getDisplayUnit.

Int

Returns the unit that should be used to display the distance value, adjusted to the current user's locale and location.

Int
String

Constants

UNIT_FEET

Added in 1.0.0
const val UNIT_FEET = 6: Int

Feet unit.

UNIT_KILOMETERS

Added in 1.0.0
const val UNIT_KILOMETERS = 2: Int

Kilometer unit.

UNIT_KILOMETERS_P1

Added in 1.0.0
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_METERS

Added in 1.0.0
const val UNIT_METERS = 1: Int

Meter unit.

UNIT_MILES

Added in 1.0.0
const val UNIT_MILES = 4: Int

Miles unit.

UNIT_MILES_P1

Added in 1.0.0
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).

UNIT_YARDS

Added in 1.0.0
const val UNIT_YARDS = 7: Int

Yards unit.

Public functions

create

Added in 1.0.0
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.

Examples A display distance of 1.0 with a display unit of 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. See getDisplayDistance

displayUnit: Int

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 getDisplayUnit

Throws
java.lang.IllegalArgumentException

if displayDistance is negative

equals

Added in 1.4.0-rc02
fun equals(other: Any?): Boolean

getDisplayDistance

Added in 1.0.0
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_METERS and distance of 1000, resulting in a display of "1000 m".
  • Display unit of UNIT_KILOMETERS and distance of 1, resulting in a display of "1 km".
  • Display unit of UNIT_KILOMETERS_P1 and distance of 1, resulting in a display of "1.0 km".

getDisplayUnit

Added in 1.0.0
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.

hashCode

Added in 1.4.0-rc02
fun hashCode(): Int

toString

Added in 1.4.0-rc02
fun toString(): String