Skip to content

distance.hpp

IDistance — a distance / time-of-flight sensor (pros::Distance) behind the HAL.

This header declares 1 type (8 members).

Extracted from include/shulib/hal/distance.hpp — this page is that header's documentation, reformatted, so it cannot disagree with the code. Prose about how to think about the API lives in the user guide; worked recipes live in the cookbook; this page is the complete, mechanical list of what exists.

Contents

class IDistance

class IDistance

A time-of-flight rangefinder behind the HAL, canonical at the seam: inches out of distance(), a [0, 1] confidence out of confidence(). Read confidence() FIRST — "nothing in range" arrives there as ~0 while distance() stays finite and reports a plausible- looking far wall, so a caller that trusts distance() alone acts on empty air. Consumers are the manipulation sensor-confirm and the docking distance-fallback.

class, declared at include/shulib/hal/distance.hpp:20.

IDistance::~IDistance

virtual ~IDistance() = default

Public defaulted special members on a polymorphic base: the virtual destructor makes delete through an IDistance* well-defined, and copy/move stay available so an adapter deriving from this is free to be value-like. This base carries no state of its own — hold implementations by reference or pointer, never by value.

function, declared at include/shulib/hal/distance.hpp:26.

IDistance::IDistance

IDistance() = default

Covered by the comment on ~IDistance — one comment documents this run of special members.

function, declared at include/shulib/hal/distance.hpp:27.

IDistance::IDistance (overload 2)

IDistance(const IDistance&) = default

Covered by the comment on ~IDistance — one comment documents this run of special members.

function, declared at include/shulib/hal/distance.hpp:28.

IDistance::IDistance (overload 3)

IDistance(IDistance&&) = default

Covered by the comment on ~IDistance — one comment documents this run of special members.

function, declared at include/shulib/hal/distance.hpp:29.

IDistance::operator=

IDistance& operator=(const IDistance&) = default

Covered by the comment on ~IDistance — one comment documents this run of special members.

function, declared at include/shulib/hal/distance.hpp:30.

IDistance::operator= (overload 2)

IDistance& operator=(IDistance&&) = default

Covered by the comment on ~IDistance — one comment documents this run of special members.

function, declared at include/shulib/hal/distance.hpp:31.

IDistance::distance

[[nodiscard]] virtual units::Length distance() const = 0

Measured distance to the nearest object (canonical inches). Only meaningful when confidence() is above the caller's threshold.

function, declared at include/shulib/hal/distance.hpp:35.

IDistance::confidence

[[nodiscard]] virtual double confidence() const = 0

Reading confidence in [0, 1]; ~0 means no usable return (treat as "no object").

function, declared at include/shulib/hal/distance.hpp:38.

Design commentary, from the header

The header opens with the reasoning behind these shapes. It is reproduced here in full because a reference that only lists signatures teaches nobody why.

The header’s own reasoning — 8 lines 
 IDistance — a distance / time-of-flight sensor (pros::Distance) behind the HAL.
 distance() in canonical inches; confidence() in [0, 1]. The hal/pros adapter
 converts mm→inches and normalizes the raw confidence (0–63 → 0–1) exactly once.

 Callers threshold confidence() for "object present" — never trust distance() when
 confidence() is ~0 (out of range / no return). Used for manipulation sensor-confirm
 and the docking distance-fallback (master plan §M3/§M4).

Last updated 2026-08-15 — published from the main release branch, commit fa545ff. This site tracks releases, so between them it can lag the repository — that lag is deliberate, and it is what keeps the development log off the public site. For the current state of the code, see the repository.