Void
The uninhabited end marker of the sum list: an empty enum that can never be constructed, which lets a complete variant match end without a runtime branch.
Overview
In Context-Generic Programming (CGP), Void marks the end of a sum. Unlike the Nil that ends the other lists, it is uninhabited: a
value of Void cannot exist. A record, a string, or a path can each be empty and still exist, but an
empty choice cannot, so the natural terminator for the sum list is a type without values.
The sum list depends on this uninhabitedness. An Either chain ends in Void, so a
value that passed every real branch would have type Void, and such a value cannot exist. So the
chain is closed at its end by its definition, and a match that has handled every real variant has
nothing left to handle.
Definition
Void is an empty enum:
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum Void {}
Its variant list is empty, so it is uninhabited, like Rust's never type ! or
Infallible. CGP defines its own so
that the terminator of a sum is named for that job. It derives the standard traits so that a sum
ending in Void can inherit them. But code never builds a value of Void, so those impls never run
on one. It is not in the prelude, so import it from cgp::core::field::types.
Behavior
Void is the base case of a recursion over a sum, and it differs from the product list's base case
in a way that matters. A walk over an Either chain handles each Left as a branch
and defers each Right to the tail, until the tail is Void. At that point nothing is left to
handle, so the base-case impl for Void ends the recursion, handing back what it was given or
discharging a value that cannot exist.
Variant extraction uses the same uninhabitedness in a second place. An extractor from
#[derive(ExtractField)] is a companion enum with one marker
per variant, and extract_field marks each variant it has
ruled out as IsVoid, whose payload type is Void. Once every variant is IsVoid, every variant
of the companion holds a Void, so the companion itself is uninhabited. The derive gives that
configuration a FinalizeExtract impl whose body is an
empty match self {}, so a fully handled extraction ends without an unreachable runtime branch. The
trait's impl for Void itself has the same body:
pub trait FinalizeExtract {
fn finalize_extract<T>(self) -> T;
}
impl FinalizeExtract for Void {
fn finalize_extract<T>(self) -> T {
match self {}
}
}
A constructible type could not be discharged this way, because the compiler would demand an arm for
its values. This is why a ruled-out variant holds Void rather than the () a missing record field
holds, and why the sum list terminates in Void while the product list terminates in Nil.
Examples
Void ends every sum chain, closes a match over one, and fills the error position of a Result
that cannot fail:
use cgp::core::field::traits::FinalizeExtractResult;
use cgp::core::field::types::{Either, Void};
use cgp::prelude::*;
pub type Token = Sum![u32, bool];
// Behind a reference, the `Void` arm is required.
pub fn describe(token: &Token) -> String {
match token {
Either::Left(number) => format!("number {number}"),
Either::Right(Either::Left(flag)) => format!("flag {flag}"),
Either::Right(Either::Right(void)) => match *void {},
}
}
// By value, it may be left out.
pub fn is_number(token: Token) -> bool {
match token {
Either::Left(_) => true,
Either::Right(Either::Left(_)) => false,
}
}
pub fn demo() {
// The annotations are the check: the chain ends in `Void`, and the empty sum is `Void`.
let _: PhantomData<Either<u32, Either<bool, Void>>> = PhantomData::<Token>;
let _: PhantomData<Void> = PhantomData::<Sum![]>;
assert_eq!(describe(&Either::Right(Either::Left(true))), "flag true");
assert!(is_number(Either::Left(3)));
// A `Result` that cannot fail unwraps without an `unwrap`.
let result: Result<u32, Void> = Ok(5);
assert_eq!(result.finalize_extract_result(), 5);
}
You do not construct a Void. You only eliminate one, with an empty match, and
FinalizeExtractResult does that for the error side
of a Result<T, Void>.
When to use it
You read Void at the end of a sum and in an extractor's type, and you write it only to close a
match.
- Read
Voidas "the choice ends here, and this point is unreachable." In an expandedEitherchain, theVoidmarks the end, and a value can never sit at it. - Write
match void {}for the last arm of a match on a sum behind a reference, where Rust requires the arm. - Expect
Void, notNil, at the end of a variant. A record, a string, and a path end inNil, and a variant ends inVoid. The wrong terminator in an error usually means the product and sum families have been mixed up. - Recognize
Voidin aFinalizeExtracterror as the payload of a variant already ruled out. An extraction that stops short leaves some variantIsPresent, and the missingFinalizeExtractimpl is for that partly ruled-out companion.
Common Mistakes
Void is uninhabited, and Nil is not. Nil is the real value of the empty product, while
Void is a type without values. Records use Nil, and variants use Void. An error that names the wrong
one usually means the two families have been mixed up.
A match behind a reference needs the Void arm. A match on a sum by value may leave the last
arm out, since Rust treats an uninhabited payload as unreachable there. Through a reference it does
not:
pub type Token = Sum![u32, bool];
pub fn describe(token: &Token) -> String {
match token {
Either::Left(number) => format!("number {number}"),
Either::Right(Either::Left(flag)) => format!("flag {flag}"),
}
}
This fails with
error[E0004]: non-exhaustive patterns: `&Either::Right(Either::Right(_))` not covered,
and the compiler says why:
= note: `Void` is uninhabited but is not being matched by value, so a wildcard `_` is required
Add Either::Right(Either::Right(void)) => match *void {} to close it.
You cannot build a Void. It has neither a constructor nor a literal, by design. Code that appears to
"return a Void" is really an empty match that never returns.
Related constructs
Either: the head-or-rest cell this marker terminates.Nil: the product, string, and path lists' constructible end marker, the counterpart to this one.Sum!: the macro whose empty form isVoid.FinalizeExtract: discharges an extractor whose every variant holdsVoid, with an empty match.FinalizeExtractResult: the result-carrying form built on the same idea.MapType: whoseIsVoidmarker maps a ruled-out variant's payload toVoid.
The ideas behind it:
- Extensible variants: where the uninhabited terminator closes a total variant match.
Source
Voidis insum.rs, alongsideEitherFinalizeExtractand its impl forVoid:extract_field.rs- The
IsVoidmarker:map_type.rs
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.