logistics.route-distance

pub fn route_distance(stops: &[GeoPoint], return_to_start: bool) -> RouteDistance

/// The whole route and each leg, in metres to the millimetre.
#[derive(Debug, Clone, PartialEq)]
pub struct RouteDistance {
    /// the sum of the legs, summed exactly in millimetres
    pub total_metres: f64,
    /// one per leg: stops[0] to stops[1], stops[1] to stops[2], ...
    pub leg_metres: Vec<f64>,
}

fune!(logistics.route-distance@^1);  // then call route_distance(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::geo_distance::distance;  ← from geo.distance ^1.0.0 · built alongside by fune
use super::geo_point_in_polygon::{geo_point_from_value, GeoPoint};  ← from geo.point-in-polygon ^1.0.0 · built alongside by fune

/// Great-circle length of a route through the stops in order, leg by leg,
/// optionally closing back to the first stop.
///
/// # Panics
/// Panics on an empty list or a coordinate out of range.
pub fn route_distance(stops: &[GeoPoint], return_to_start: bool) -> RouteDistance {
    if stops.is_empty() {
        panic!("stops must not be empty");
    }
    let mut leg_metres: Vec<f64> = Vec::new();
    // 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 mut total_millimetres: i64 = 0;
    let mut add_leg = |a: &GeoPoint, b: &GeoPoint| {
        let metres = distance(a.lat, a.lng, b.lat, b.lng);
        leg_metres.push(metres);
        total_millimetres += (metres * 1000.0 + 0.5).floor() as i64;
    };
    for i in 1..stops.len() {
        add_leg(&stops[i - 1], &stops[i]);
    }
    if return_to_start && stops.len() > 1 {
        add_leg(&stops[stops.len() - 1], &stops[0]);
    }
    RouteDistance {
        total_metres: total_millimetres as f64 / 1000.0,
        leg_metres,
    }
}

pub fn route_distance_to_value(r: &RouteDistance) -> Value {
    Value::obj(vec![
        ("totalMetres", Value::Float(r.total_metres)),
        ("legMetres", Value::Arr(r.leg_metres.iter().map(|m| Value::Float(*m)).collect())),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    let stops: Vec<GeoPoint> = args[0].as_arr().iter().map(geo_point_from_value).collect();
    route_distance_to_value(&route_distance(&stops, args[1].as_bool()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. 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 Rust implementation. Install it without the registry with fune add ./logistics.route-distance-1.0.0-rust.fune, or fetch it from a terminal with fune pull logistics.route-distance@1.0.0:rust.

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