Length, a standard type

A length or distance: 5km, 45cm, 3inch or 2metre.

Use it for any distance, in any unit. It keeps your sums correct across units, so 1metre + 3cm just works. For a box's three sides, use Dimensions.

Shape

One value, with no fields to fill in. As text it reads 1000 metre.

Example

example

Length(5km)

text.parse(raw, as: Length) reads one from text that comes from outside. Text that isn't one at all fails malformed, such as 5, 1.2.3 or five.

These operations give one: geo.distance, geo.length, units.of and units.sum.

Good to know

m is minutes, so a metre is metre. Inches are inch.
A Length times a Length gives an Area.
units.of(5, LengthUnit.mile) builds one from a number, and units.in reads a number back.
It is held in metres to 6 places.
== tells you whether two are the same, and < and list.sort_by compare and sort them.

In JSON

An object of its parts, in a request, a response or json.write:

json

{"value":"-1.5","unit":"metre"}{"value":"0.0254","unit":"metre"}{"value":"1000","unit":"metre"}

Details

Text form, storage, how it is shown, and operations

Length is in the group Physical quantities, and has been in Jadpo since 0.1.0.

Text form

text.from writes one standard text form, the same form text.parse reads back: -1.5 metre, 0.0254 metre and 1000 metre.

How it is stored

It is stored in one column named for the field, of type numeric(38, 6), holding the length in metres (m). 0.0254 metre is stored as 0.0254.

How it is shown to people

text.format(value, locale:) shows it to people in their locale. A call may also give unit:.

With locale: Locale.en_gb:

Value	Shown
`-1.5 metre`	`-1.5 m`
`0.0254 metre`	`0.0254 m`
`1000 metre`	`1,000 m`

Operations

geo.distance(from: Point, to: Point) -> Length: The geodesic distance between two points on the ellipsoid, rounded half to even to the micrometre.
geo.length(line: T) -> Length: A LineString's or MultiLineString's length: each edge measured as distance measures it, and summed.
geo.within(a: T, b: U, distance: Length?) -> Bool: geo.contains(b, a); or, with distance:, whether two points are at most that far apart, as geo.distance measures them.
units.in(value: Quantity, unit: QuantityUnit, scale: Int, rounding: Rounding) -> Decimal: value in unit, a unit of its kind, as a Decimal of scale places rounded by rounding: units.in(5km, LengthUnit.mile, scale: 2, rounding: Rounding.half_even) is 3.11.
units.of(value: Number, unit: QuantityUnit) -> Quantity: value of unit, an Int or a Decimal, as the quantity of unit's kind, converted exactly to the base unit and rounded half to even to the kind's scale: units.of(5, LengthUnit.mile).
units.sum(items: List<Quantity>) -> Quantity: The items added up, all of one kind; nothing for no items. A Temperature or a SoundLevel doesn't add to itself, so neither is summed.

It also takes text.parse, text.from, text.format, json.read, json.write and ==. How every standard type behaves says how they work.