logistics.route-distance

export function routeDistance(stops: readonly GeoPoint[], returnToStart: boolean): RouteDistance

/** The whole route and each leg, in metres to the millimetre. */
export interface RouteDistance {
  /** the sum of the legs, summed exactly in millimetres */
  readonly totalMetres: number;
  /** one per leg: stops[0] to stops[1], stops[1] to stops[2], ... */
  readonly legMetres: readonly number[];
}

import { routeDistance } from "#fune/logistics.route-distance@^1";

import { distance } from "./geo_distance.ts";  ← from geo.distance ^1.0.0 · built alongside by fune
import { type GeoPoint } from "./geo_point_in_polygon.ts";  ← from geo.point-in-polygon ^1.0.0 · built alongside by fune
import { type RouteDistance } from "./logistics_route_distance_types.ts";

/**
 * Great-circle length of a route through the stops in order, leg by leg,
 * optionally closing back to the first stop.
 */
export function routeDistance(stops: readonly GeoPoint[], returnToStart: boolean): RouteDistance {
  if (stops.length === 0) throw new RangeError("stops must not be empty");
  const legMetres: number[] = [];
  // Each leg is a whole number of millimetres; adding them as integers and
  // dividing once avoids floating-point drift (and is the same double everywhere).
  let totalMillimetres = 0;
  const addLeg = (a: GeoPoint, b: GeoPoint): void => {
    const metres = distance(a.lat, a.lng, b.lat, b.lng);
    legMetres.push(metres);
    totalMillimetres += Math.floor(metres * 1000 + 0.5);
  };
  for (let i = 1; i < stops.length; i++) addLeg(stops[i - 1], stops[i]);
  if (returnToStart && stops.length > 1) addLeg(stops[stops.length - 1], stops[0]);
  return { totalMetres: totalMillimetres / 1000, legMetres };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add logistics.route-distance

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./logistics.route-distance-1.0.0-typescript.fune, or fetch it from a terminal with fune pull logistics.route-distance@1.0.0:typescript.

The whole function, every language, is one file too: logistics.route-distance-1.0.0.fune, 10,910 bytes, sha256 466edb4c820220ce3afbcc8bdacd67502202c89f2f192576ce8b885c7f53a9a8. It installs into a project of any language.

// fune: before logistics.route-distance

// fune: after logistics.route-distance

// fune: replace geo.distance in logistics.route-distance
// fune: replace geo.point-in-polygon in logistics.route-distance

// fune: step logistics.route-distance after <n|label>

More from the author

## 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.

Files