Struct Choice 

#[non_exhaustive]
pub struct Choice<'a> {
    pub value: &'a str,
    pub label: &'a str,
    pub unavailable: Option<&'a str>,
}

One option offered by a field FieldKind::offers_options accepts.

Two strings, because the submitted value and the read label are different facts and every renderer that has tried to collapse them has had to un-collapse them later. makeover-webview invented this shape writing its form emitter and it is taken here unchanged; moving it down rather than re-deriving it is the point, since the second and third renderers were each going to arrive at a near-miss of it. #[non_exhaustive] as of 0.28.0, which every other type here that a renderer matches or builds has carried for releases. It was the omission that made unavailable a breaking change across 40 literal sites in six repos, and it arrives with that member so the price is paid once and never again.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

value: &'a str

What is submitted.

label: &'a str

What is read.

unavailable: Option<&'a str>

Why it cannot be picked right now, when it cannot.

One member rather than an available: bool beside a reason, and the conflation is the point: an option greyed out with no explanation is a dead end the user cannot act on, and it is exactly the state the app that found this gap had to patch by hand with a line of prose under the control. Making the reason mandatory means the description cannot say the useless half.

The option stays in the list. Dropping it is what an app does today, and it costs the user the knowledge that the thing exists at all — audiofiles’ multi-sample mode appears on its own once a second sample is dropped, so a user who never sees it never learns what to drop.

Not Field::error, and not Field::hint. An error is about the answer and a hint is standing help for the whole question; this is about one option among several, which is the level neither of those reaches.

Not disabled-the-state. State::Disabled is about a whole field refusing to answer. This says the field is live and one of its answers is not available yet, which is a different sentence and the reason the tone rule matters here: the other options are still usable.

Added 0.28.0, from audiofiles’ instrument mode selector (e761833e).

Implementations

impl<'a> Choice<'a>

pub const fn plain(value: &'a str) -> Self

An option whose submitted value is also its label.

pub const fn new(value: &'a str, label: &'a str) -> Self

An option that submits one string and reads as another.

A constructor rather than a literal, which is what #[non_exhaustive] costs and buys: outside this crate the struct cannot be built by naming its members, so every call site goes through here and the next member added breaks none of them.

pub const fn unless(self, reason: &'a str) -> Self

The same option, not pickable yet, and why.

Builder-shaped because the reason is the rare case: 39 of the 40 option sites measured across the tree do not have one.

pub const fn available(&self) -> bool

Whether the option can be picked right now.

The predicate a renderer branches on, so that “unavailable” is read as one condition in one place rather than as unavailable.is_some() at three renderers, one of which will invert it.

Trait Implementations

impl<'a> Clone for Choice<'a>

fn clone(&self) -> Choice<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for Choice<'a>

impl<'a> Debug for Choice<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Eq for Choice<'a>

impl<'a> Hash for Choice<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for Choice<'a>

fn eq(&self, other: &Choice<'a>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for Choice<'a>