Struct rustc_mir_build::build::matches::Candidate

struct Candidate<'pat, 'tcx> {
    match_pairs: Vec<MatchPairTree<'pat, 'tcx>>,
    subcandidates: Vec<Candidate<'pat, '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>,
}

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<'pat, '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::sort_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 TestCase::Irrefutable patterns have been removed by simplification.
• All or-patterns (TestCase::Or) have been sorted to the end.

subcandidates: Vec<Candidate<'pat, '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

impl<'tcx, 'pat> Candidate<'pat, 'tcx>

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

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

Incorporates an already-simplified FlatPat into a new candidate.

fn starts_with_or_pattern(&self) -> bool

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

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.

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

Visit the leaf candidates in reverse order.

Trait Implementations

impl<'pat, 'tcx> Debug for Candidate<'pat, 'tcx>

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

Formats the value using the given formatter.

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