rustc_pattern_analysis/
lib.rs

1//! Analysis of patterns, notably match exhaustiveness checking. The main entrypoint for this crate
2//! is [`usefulness::compute_match_usefulness`]. For rustc-specific types and entrypoints, see the
3//! [`rustc`] module.
4
5// tidy-alphabetical-start
6#![cfg_attr(test, allow(unused_crate_dependencies))] // Used for integration tests, not unit tests
7// tidy-alphabetical-end
8
9pub(crate) mod checks;
10pub mod constructor;
11#[cfg(feature = "rustc")]
12pub mod diagnostics;
13#[cfg(feature = "rustc")]
14pub(crate) mod lints;
15pub mod pat;
16pub mod pat_column;
17#[cfg(feature = "rustc")]
18pub mod rustc;
19pub mod usefulness;
20
21use std::fmt;
22
23pub use rustc_index::{Idx, IndexVec}; // re-exported to avoid rustc_index version issues
24
25use crate::constructor::{Constructor, ConstructorSet, IntRange};
26use crate::pat::DeconstructedPat;
27
28/// `bool` newtype that indicates whether this is a privately uninhabited field that we should skip
29/// during analysis.
30#[derive(#[automatically_derived]
impl ::core::marker::Copy for PrivateUninhabitedField { }Copy, #[automatically_derived]
#[doc(hidden)]
unsafe impl ::core::clone::TrivialClone for PrivateUninhabitedField { }
#[automatically_derived]
impl ::core::clone::Clone for PrivateUninhabitedField {
    #[inline]
    fn clone(&self) -> PrivateUninhabitedField {
        let _: ::core::clone::AssertParamIsClone<bool>;
        *self
    }
}Clone, #[automatically_derived]
impl ::core::fmt::Debug for PrivateUninhabitedField {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_tuple_field1_finish(f,
            "PrivateUninhabitedField", &&self.0)
    }
}Debug, #[automatically_derived]
impl ::core::marker::StructuralPartialEq for PrivateUninhabitedField { }
#[automatically_derived]
impl ::core::cmp::PartialEq for PrivateUninhabitedField {
    #[inline]
    fn eq(&self, other: &PrivateUninhabitedField) -> bool {
        self.0 == other.0
    }
}PartialEq, #[automatically_derived]
impl ::core::cmp::Eq for PrivateUninhabitedField {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {
        let _: ::core::cmp::AssertParamIsEq<bool>;
    }
}Eq)]
31pub struct PrivateUninhabitedField(pub bool);
32
33/// Context that provides type information about constructors.
34///
35/// Most of the crate is parameterized on a type that implements this trait.
36pub trait PatCx: Sized + fmt::Debug {
37    /// The type of a pattern.
38    type Ty: Clone + fmt::Debug;
39    /// Errors that can abort analysis.
40    type Error: fmt::Debug;
41    /// The index of an enum variant.
42    type VariantIdx: Clone + Idx + fmt::Debug;
43    /// A string literal
44    type StrLit: Clone + PartialEq + fmt::Debug;
45    /// Extra data to store in a match arm.
46    type ArmData: Copy + Clone + fmt::Debug;
47    /// Extra data to store in a pattern.
48    type PatData: Clone;
49
50    fn is_exhaustive_patterns_feature_on(&self) -> bool;
51
52    /// Whether to ensure the non-exhaustiveness witnesses we report for a complete set. This is
53    /// `false` by default to avoid some exponential blowup cases such as
54    /// <https://github.com/rust-lang/rust/issues/118437>.
55    fn exhaustive_witnesses(&self) -> bool {
56        false
57    }
58
59    /// The number of fields for this constructor.
60    fn ctor_arity(&self, ctor: &Constructor<Self>, ty: &Self::Ty) -> usize;
61
62    /// The types of the fields for this constructor. The result must contain `ctor_arity()` fields.
63    fn ctor_sub_tys(
64        &self,
65        ctor: &Constructor<Self>,
66        ty: &Self::Ty,
67    ) -> impl Iterator<Item = (Self::Ty, PrivateUninhabitedField)> + ExactSizeIterator;
68
69    /// The set of all the constructors for `ty`.
70    ///
71    /// This must follow the invariants of `ConstructorSet`
72    fn ctors_for_ty(&self, ty: &Self::Ty) -> Result<ConstructorSet<Self>, Self::Error>;
73
74    /// Write the name of the variant represented by `pat`. Used for the best-effort `Debug` impl of
75    /// `DeconstructedPat`. Only invoqued when `pat.ctor()` is `Struct | Variant(_) | UnionField`.
76    fn write_variant_name(
77        f: &mut fmt::Formatter<'_>,
78        ctor: &crate::constructor::Constructor<Self>,
79        ty: &Self::Ty,
80    ) -> fmt::Result;
81
82    /// Raise a bug.
83    fn bug(&self, fmt: fmt::Arguments<'_>) -> Self::Error;
84
85    /// Raise a delayed bug.
86    fn delayed_bug(&self, fmt: fmt::Arguments<'_>) -> Self::Error {
87        self.bug(fmt)
88    }
89
90    /// Lint that the range `pat` overlapped with all the ranges in `overlaps_with`, where the range
91    /// they overlapped over is `overlaps_on`. We only detect singleton overlaps.
92    /// The default implementation does nothing.
93    fn lint_overlapping_range_endpoints(
94        &self,
95        _pat: &DeconstructedPat<Self>,
96        _overlaps_on: IntRange,
97        _overlaps_with: &[&DeconstructedPat<Self>],
98    ) {
99    }
100
101    /// The maximum pattern complexity limit was reached.
102    fn complexity_exceeded(&self) -> Result<(), Self::Error>;
103
104    /// Lint that there is a gap `gap` between `pat` and all of `gapped_with` such that the gap is
105    /// not matched by another range. If `gapped_with` is empty, then `gap` is `T::MAX`. We only
106    /// detect singleton gaps.
107    /// The default implementation does nothing.
108    fn lint_non_contiguous_range_endpoints(
109        &self,
110        _pat: &DeconstructedPat<Self>,
111        _gap: IntRange,
112        _gapped_with: &[&DeconstructedPat<Self>],
113    ) {
114    }
115
116    /// Check if we may need to perform additional deref-pattern-specific validation.
117    fn match_may_contain_deref_pats(&self) -> bool {
118        true
119    }
120
121    /// The current implementation of deref patterns requires that they can't match on the same
122    /// place as a normal constructor. Since this isn't caught by type-checking, we check it in the
123    /// `PatCx` before running the analysis. This reports an error if the check fails.
124    fn report_mixed_deref_pat_ctors(
125        &self,
126        deref_pat: &DeconstructedPat<Self>,
127        normal_pat: &DeconstructedPat<Self>,
128    ) -> Self::Error;
129}
130
131/// The arm of a match expression.
132#[derive(#[automatically_derived]
impl<'p, Cx: ::core::fmt::Debug + PatCx> ::core::fmt::Debug for
    MatchArm<'p, Cx> where Cx::ArmData: ::core::fmt::Debug {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field3_finish(f, "MatchArm",
            "pat", &self.pat, "has_guard", &self.has_guard, "arm_data",
            &&self.arm_data)
    }
}Debug)]
133pub struct MatchArm<'p, Cx: PatCx> {
134    pub pat: &'p DeconstructedPat<Cx>,
135    pub has_guard: bool,
136    pub arm_data: Cx::ArmData,
137}
138
139impl<'p, Cx: PatCx> Clone for MatchArm<'p, Cx> {
140    fn clone(&self) -> Self {
141        *self
142    }
143}
144
145impl<'p, Cx: PatCx> Copy for MatchArm<'p, Cx> {}
rustc_pattern_analysis/lib.rs

rustc_pattern_analysis/
lib.rs
