1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 #![allow(non_snake_case)]
13 // Error messages for EXXXX errors.
14 // Each message should start and end with a new line, and be wrapped to 80 characters.
15 // In vim you can `:set tw=80` and use `gq` to wrap paragraphs. Use `:set tw=0` to disable.
16 register_long_diagnostics
! {
19 This error suggests that the expression arm corresponding to the noted pattern
20 will never be reached as for all possible values of the expression being
21 matched, one of the preceding patterns will match.
23 This means that perhaps some of the preceding patterns are too general, this
24 one is too specific or the ordering is incorrect.
26 For example, the following `match` block has too many arms:
30 Some(bar) => {/* ... */}
32 _ => {/* ... */} // All possible cases have already been handled
36 `match` blocks have their patterns matched in order, so, for example, putting
37 a wildcard arm above a more specific arm will make the latter arm irrelevant.
39 Ensure the ordering of the match arm is correct and remove any superfluous
44 This error indicates that an empty match expression is invalid because the type
45 it is matching on is non-empty (there exist values of this type). In safe code
46 it is impossible to create an instance of an empty type, so empty match
47 expressions are almost never desired. This error is typically fixed by adding
48 one or more cases to the match expression.
50 An example of an empty type is `enum Empty { }`. So, the following will work:
67 fn foo(x: Option<String>) {
77 Not-a-Number (NaN) values cannot be compared for equality and hence can never
78 match the input to a match expression. So, the following will not compile:
81 const NAN: f32 = 0.0 / 0.0;
91 To match against NaN values, you should instead use the `is_nan()` method in a
98 x if x.is_nan() => { /* ... */ }
106 This error indicates that the compiler cannot guarantee a matching pattern for
107 one or more possible inputs to a match expression. Guaranteed matches are
108 required in order to assign values to match expressions, or alternatively,
109 determine the flow of execution. Erroneous code example:
117 let x = Terminator::HastaLaVistaBaby;
119 match x { // error: non-exhaustive patterns: `HastaLaVistaBaby` not covered
120 Terminator::TalkToMyHand => {}
124 If you encounter this error you must alter your patterns so that every possible
125 value of the input type is matched. For types with a small number of variants
126 (like enums) you should probably cover all cases explicitly. Alternatively, the
127 underscore `_` wildcard pattern can be added after all other patterns to match
128 "anything else". Example:
136 let x = Terminator::HastaLaVistaBaby;
139 Terminator::TalkToMyHand => {}
140 Terminator::HastaLaVistaBaby => {}
146 Terminator::TalkToMyHand => {}
153 Patterns used to bind names must be irrefutable, that is, they must guarantee
154 that a name will be extracted in all cases. Erroneous code example:
159 // error: refutable pattern in local binding: `None` not covered
162 If you encounter this error you probably need to use a `match` or `if let` to
163 deal with the possibility of failure. Example:
184 This error indicates that the bindings in a match arm would require a value to
185 be moved into more than one location, thus violating unique ownership. Code
186 like the following is invalid as it requires the entire `Option<String>` to be
187 moved into a variable called `op_string` while simultaneously requiring the
188 inner `String` to be moved into a variable called `s`.
191 let x = Some("s".to_string());
194 op_string @ Some(s) => {},
199 See also the error E0303.
203 Names bound in match arms retain their type in pattern guards. As such, if a
204 name is bound by move in a pattern, it should also be moved to wherever it is
205 referenced in the pattern guard code. Doing so however would prevent the name
206 from being available in the body of the match arm. Consider the following:
209 match Some("hi".to_string()) {
210 Some(s) if s.len() == 0 => {}, // use s.
215 The variable `s` has type `String`, and its use in the guard is as a variable of
216 type `String`. The guard code effectively executes in a separate scope to the
217 body of the arm, so the value would be moved into this anonymous scope and
218 therefore become unavailable in the body of the arm. Although this example seems
219 innocuous, the problem is most clear when considering functions that take their
223 match Some("hi".to_string()) {
224 Some(s) if { drop(s); false } => (),
225 Some(s) => {}, // use s.
230 The value would be dropped in the guard then become unavailable not only in the
231 body of that arm but also in all subsequent arms! The solution is to bind by
232 reference when using guards or refactor the entire expression, perhaps by
233 putting the condition inside the body of the arm.
237 In a pattern, all values that don't implement the `Copy` trait have to be bound
238 the same way. The goal here is to avoid binding simultaneously by-move and
241 This limitation may be removed in a future version of Rust.
243 Erroneous code example:
248 let x = Some((X { x: () }, X { x: () }));
250 Some((y, ref z)) => {},
255 You have two solutions:
257 Solution #1: Bind the pattern's values the same way.
262 let x = Some((X { x: () }, X { x: () }));
264 Some((ref y, ref z)) => {},
265 // or Some((y, z)) => {}
270 Solution #2: Implement the `Copy` trait for the `X` structure.
272 However, please keep in mind that the first solution should be preferred.
275 #[derive(Clone, Copy)]
278 let x = Some((X { x: () }, X { x: () }));
280 Some((y, ref z)) => {},
287 `const` and `static` mean different things. A `const` is a compile-time
288 constant, an alias for a literal value. This property means you can match it
289 directly within a pattern.
291 The `static` keyword, on the other hand, guarantees a fixed location in memory.
292 This does not always mean that the value is constant. For example, a global
293 mutex can be declared `static` as well.
295 If you want to match against a `static`, consider using a guard instead:
298 static FORTY_TWO: i32 = 42;
301 Some(x) if x == FORTY_TWO => {}
308 An if-let pattern attempts to match the pattern, and enters the body if the
309 match was successful. If the match is irrefutable (when it cannot fail to
310 match), use a regular `let`-binding instead. For instance:
313 struct Irrefutable(i32);
314 let irr = Irrefutable(0);
316 // This fails to compile because the match is irrefutable.
317 if let Irrefutable(x) = irr {
318 // This body will always be executed.
326 struct Irrefutable(i32);
327 let irr = Irrefutable(0);
329 let Irrefutable(x) = irr;
335 A while-let pattern attempts to match the pattern, and enters the body if the
336 match was successful. If the match is irrefutable (when it cannot fail to
337 match), use a regular `let`-binding inside a `loop` instead. For instance:
340 struct Irrefutable(i32);
341 let irr = Irrefutable(0);
343 // This fails to compile because the match is irrefutable.
344 while let Irrefutable(x) = irr {
351 struct Irrefutable(i32);
352 let irr = Irrefutable(0);
355 let Irrefutable(x) = irr;
362 Enum variants are qualified by default. For example, given this type:
371 You would match it using:
387 If you don't qualify the names, the code will bind new variables named "GET" and
388 "POST" instead. This behavior is likely not what you want, so `rustc` warns when
391 Qualified names are good practice, and most code works well with them. But if
392 you prefer them unqualified, you can import the variants into scope:
396 enum Method { GET, POST }
399 If you want others to be able to import variants from your module directly, use
404 enum Method { GET, POST }
410 Patterns used to bind names must be irrefutable. That is, they must guarantee
411 that a name will be extracted in all cases. Instead of pattern matching the
412 loop variable, consider using a `match` or `if let` inside the loop body. For
416 let xs : Vec<Option<i32>> = vec!(Some(1), None);
418 // This fails because `None` is not covered.
424 Match inside the loop instead:
427 let xs : Vec<Option<i32>> = vec!(Some(1), None);
440 let xs : Vec<Option<i32>> = vec!(Some(1), None);
443 if let Some(x) = item {
451 Mutable borrows are not allowed in pattern guards, because matching cannot have
452 side effects. Side effects could alter the matched object or the environment
453 on which the match depends in such a way, that the match would not be
454 exhaustive. For instance, the following would not match any arm if mutable
455 borrows were allowed:
460 option if option.take().is_none() => {
461 /* impossible, option is `Some` */
463 Some(_) => { } // When the previous match failed, the option became `None`.
469 Assignments are not allowed in pattern guards, because matching cannot have
470 side effects. Side effects could alter the matched object or the environment
471 on which the match depends in such a way, that the match would not be
472 exhaustive. For instance, the following would not match any arm if assignments
478 option if { option = None; false } { },
479 Some(_) => { } // When the previous match failed, the option became `None`.
485 In certain cases it is possible for sub-bindings to violate memory safety.
486 Updates to the borrow checker in a future version of Rust may remove this
487 restriction, but for now patterns must be rewritten without sub-bindings.
491 match Some("hi".to_string()) {
492 ref op_string_ref @ Some(s) => {},
497 match Some("hi".to_string()) {
499 let op_string_ref = &Some(s);
506 The `op_string_ref` binding has type `&Option<&String>` in both cases.
508 See also https://github.com/rust-lang/rust/issues/14587
512 In an array literal `[x; N]`, `N` is the number of elements in the array. This
513 must be an unsigned integer. Erroneous code example:
516 let x = [0i32; true]; // error: expected positive integer for repeat count,
528 The length of an array is part of its type. For this reason, this length must
529 be a compile-time constant. Erroneous code example:
533 let x = [0i32; len]; // error: expected constant integer for repeat count,
541 register_diagnostics
! {
542 E0298
, // mismatched types between arms
543 E0299
, // mismatched types between arms
544 E0471
, // constant evaluation error: ..