Candidate in rustc_mir_build::builder::matches - Rust
Description: Candidates are a generalization of (a) top-level match arms, and (b) sub-branches of or-patterns, allowing the match-lowering process to handle them both in a mostly-uniform way. For example, the list of candidates passed to `Builder::match_candidates` will often contain a mixture of top-level candidates and or-pattern subcandidates.

Skip to main content

## Candidate

# Struct Candidate

Source

    struct Candidate<'tcx> {
        match_pairs: Vec<MatchPairTree<'tcx>>,
        subcandidates: Vec<Candidate<'tcx>>,
        has_guard: bool,
        extra_data: PatternExtraData<'tcx>,
        or_span: Option<Span>,
        pre_binding_block: Option<BasicBlock>,
        otherwise_block: Option<BasicBlock>,
        false_edge_start_block: Option<BasicBlock>,
    }

Expand description

Candidates are a generalization of (a) top-level match arms, and (b) sub-branches of or-patterns, allowing the match-lowering process to handle them both in a mostly-uniform way. For example, the list of candidates passed to `Builder::match_candidates` will often contain a mixture of top-level candidates and or-pattern subcandidates.

At the start of match lowering, there is one candidate for each match arm. During match lowering, arms with or-patterns will be expanded into a tree of candidates, where each “leaf” candidate represents one of the ways for the arm pattern to successfully match.

## Fields§

§`match_pairs: Vec<MatchPairTree<'tcx>>`

For the candidate to match, all of these must be satisfied…

Initially contains a list of match pairs created by `FlatPat`, but is subsequently mutated (in a queue-like way) while lowering the match tree. When this list becomes empty, the candidate is fully matched and becomes a leaf (see `Builder::select_matched_candidate`).

Key mutations include:

- When a match pair is fully satisfied by a test, it is removed from the list, and its subpairs are added instead (see `Builder::choose_bucket_for_candidate`).
- During or-pattern expansion, any leading or-pattern is removed, and is converted into subcandidates (see `Builder::expand_and_match_or_candidates`).
- After a candidate’s subcandidates have been lowered, a copy of any remaining or-patterns is added to each leaf subcandidate (see `Builder::test_remaining_match_pairs_after_or`).

Invariants:

- All or-patterns (`TestableCase::Or`) have been sorted to the end.

§`subcandidates: Vec<Candidate<'tcx>>`

…and if this is non-empty, one of these subcandidates also has to match…

Initially a candidate has no subcandidates; they are added (and then immediately lowered) during or-pattern expansion. Their main function is to serve as output of match tree lowering, allowing later steps to see the leaf candidates that represent a match of the entire match arm.

A candidate no subcandidates is either incomplete (if it has match pairs left), or is a leaf in the match tree. A candidate with one or more subcandidates is an internal node in the match tree.

Invariant: at the end of match tree lowering, this must not contain an `is_never` candidate, because that would break binding consistency.

- See `Builder::remove_never_subcandidates`.

§`has_guard: bool`

…and if there is a guard it must be evaluated; if it’s `false` then branch to `otherwise_block`.

For subcandidates, this is copied from the parent candidate, so it indicates whether the enclosing match arm has a guard.

§`extra_data: PatternExtraData<'tcx>`

Holds extra pattern data that was prepared by `FlatPat`, including bindings and ascriptions that must be established if this candidate succeeds.

§`or_span: Option<Span>`

When setting `self.subcandidates`, we store here the span of the or-pattern they came from.

Invariant: it is `None` iff `subcandidates.is_empty()`.

- FIXME: We sometimes don’t unset this when clearing `subcandidates`.

§`pre_binding_block: Option<BasicBlock>`

The block before the `bindings` have been established.

After the match tree has been lowered, `Builder::lower_match_arms` will use this as the start point for lowering bindings and guards, and then jump to a shared block containing the arm body.

§`otherwise_block: Option<BasicBlock>`

The block to branch to if the guard or a nested candidate fails to match.

§`false_edge_start_block: Option<BasicBlock>`

The earliest block that has only candidates >= this one as descendents. Used for false edges, see the doc for `Builder::match_expr`.

## Implementations§

Source§

### impl<'tcx> Candidate<'tcx>

Source

#### fn new( place: PlaceBuilder<'tcx>, pattern: &Pat<'tcx>, has_guard: HasMatchGuard, cx: &mut Builder<'_, 'tcx>, ) -> Self

Source

#### fn from_flat_pat(flat_pat: FlatPat<'tcx>, has_guard: bool) -> Self

Incorporates an already-simplified `FlatPat` into a new candidate.

Source

#### fn sort_match_pairs(&mut self)

Restores the invariant that or-patterns must be sorted to the end.

Source

#### fn starts_with_or_pattern(&self) -> bool

Returns whether the first match pair of this candidate is an or-pattern.

Source

#### fn visit_leaves<'a>(&'a mut self, visit_leaf: impl FnMut(&'a mut Self))

Visit the leaf candidates (those with no subcandidates) contained in this candidate.

Source

#### fn visit_leaves_rev<'a>(&'a mut self, visit_leaf: impl FnMut(&'a mut Self))

Visit the leaf candidates in reverse order.

## Trait Implementations§

Source§

### impl<'tcx> Debug for Candidate<'tcx>

Source§

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl<'tcx> DynSend for Candidate<'tcx>

§

### impl<'tcx> DynSync for Candidate<'tcx>

§

### impl<'tcx> Freeze for Candidate<'tcx>

§

### impl<'tcx> !RefUnwindSafe for Candidate<'tcx>

§

### impl<'tcx> Send for Candidate<'tcx>

§

### impl<'tcx> Sync for Candidate<'tcx>

§

### impl<'tcx> Unpin for Candidate<'tcx>

§

### impl<'tcx> UnsafeUnpin for Candidate<'tcx>

§

### impl<'tcx> !UnwindSafe for Candidate<'tcx>

## Blanket Implementations§

Source§

### impl<T> Aligned for T

Source§

#### const ALIGN: Alignment

Alignment of `Self`.
Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T, R> CollectAndApply<T, R> for T

Source§

#### fn collect_and_apply<I, F>(iter: I, f: F) -> R
where I: Iterator<Item = T>, F: FnOnce(&[T]) -> R,

Equivalent to `f(&iter.collect::<Vec<_>>())`.

Source§

#### type Output = R

Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T> Instrument for T

Source§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided `Span`, returning an `Instrumented` wrapper. Read more
Source§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> IntoEither for T

Source§

#### fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left` is `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

#### fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left(&self)` returns `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

### impl<K> IntoQueryKey<K> for K

Source§

#### fn into_query_key(self) -> K

Argument conversion from `Self` to `K`. This should always be a very cheap conversion, e.g. `LocalDefId::to_def_id`.
Source§

### impl<T> MaybeResult<T> for T

Source§

#### type Error = !

Source§

#### fn from(_: Result<T, <T as MaybeResult<T>>::Error>) -> T

Source§

#### fn to_result(self) -> Result<T, <T as MaybeResult<T>>::Error>

Source§

### impl<T> Pointable for T

Source§

#### const ALIGN: usize

The alignment of pointer.
Source§

#### type Init = T

The type for initializers.
Source§

#### unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

#### unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

#### unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

#### unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

### impl<T> Same for T

Source§

#### type Output = T

Should always be `Self`
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

### impl<I, T, U> Upcast<I, U> for T
where U: UpcastFrom<I, T>,

Source§

#### fn upcast(self, interner: I) -> U

Source§

### impl<I, T> UpcastFrom<I, T> for T

Source§

#### fn upcast_from(from: T, _tcx: I) -> T

Source§

### impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

#### fn vzip(self) -> V

Source§

### impl<T> WithSubscriber for T

Source§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a `WithDispatch` wrapper. Read more
Source§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a `WithDispatch` wrapper. Read more
Source§

### impl<T> ErasedDestructor for T
where T: 'static,

## Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain `repr(...)` attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 144 bytes