# logistics.route-distance

The length of a route that visits the given stops in the given order: the
great-circle distance of each leg from `geo.distance`, and their total. With
`returnToStart` a closing leg from the last stop back to the first is added,
for a van that comes back to the depot.

It does not choose the order (that is route optimisation, a much bigger
problem) and it measures as the crow flies. Road distance is typically 20-40%
longer; callers that quote it multiply by their own circuity factor, and
callers that need the real figure need a routing engine.

## Exact totals

Each leg is `geo.distance`'s answer, a whole number of millimetres expressed in
metres. Adding those as floating-point numbers drifts: three legs of
2,886,448.43 m add up to 8,659,345.290000001 m. So each leg is turned back into
integer millimetres, the millimetres are added as integers, and the total is
divided by 1000 once, which gives the same double in every language
(8,659,345.29). The manifest says `floats exact` and the vectors hold the
three implementations to it.

## Edge cases

- One stop is a route of no legs: total 0, `legMetres` empty, with or
  without `returnToStart` (there is nowhere to return from).
- Two identical stops in a row are a leg of 0.
- An empty list is an error, not 0: it usually means the stops were never
  loaded.
- Coordinates are checked by `geo.distance`: out of range is an error, not
  wrapped, because it usually means latitude and longitude were swapped.

## Types

A stop is `GeoPoint` from `geo.point-in-polygon`, the registry's one
latitude/longitude record, so a polygon's vertices and a route's stops are the
same type. That capability is required for its type only.