• Feature Name: structural_match
• Start Date: 2015-02-06
• RFC PR: rust-lang/rfcs#1445
• Rust Issue: rust-lang/rust#31434

Summary

The current compiler implements

• Introduce
  導入する
  a feature-gated attribute #[structural_match] which can be applied
  適用する
  to a struct
  構造、構造体
  or enum T to indicate
  指し示す
  that constants
  定数
  of type T can be used within patterns.
• Have #[derive(Eq)] automatically
  自動的に
  apply
  適用する
  this attribute to the struct
  構造、構造体
  or enum that it decorates. Automatically
  自動的に
  inserted attributes do not require use of feature-gate.
• When expanding constants
  定数
  of struct
  構造、構造体
  or enum type into equivalent
  等価
  patterns, require that the struct
  構造、構造体
  or enum type is decorated with #[structural_match]. Constants
  定数
  of builtin types are always expanded.

The practical effect of these changes will be to prevent

To be clear, this #[structural_match] attribute is never intended to be stabilized. Rather, the intention of this change is to restrict

Because the compiler currently accepts

Note: this was also discussed on an internals thread. Major points from that thread are summarized either inline or in alternatives.

Motivation

The compiler currently permits

Semantic vs structural equality

同一性、等式

Consider

#![allow(unused)]
fn main() {
struct SomeType {
    a: u32,
    b: u32,
}

const SOME_CONSTANT: SomeType = SomeType { a: 22+22, b: 44+44 };

fn test(v: SomeType) {
    match v {
        SOME_CONSTANT => println!("Yes"),
        _ => println!("No"),
    }
}
}

The question at hand is what do we expect this match

Semantic equality.

#![allow(unused)]
fn main() {
if v == SOME_CONSTANT {
    println!("Yes")
} else {
    println!("No");
}
}

Under semantic equality,

Structural equality.

#![allow(unused)]
fn main() {
if v.a == SOME_CONSTANT.a && v.b == SOME_CONSTANT.b {
    println!("Yes")
} else {
    println!("No");
}
}

Structural equality

Current semantics. The compiler's current semantics are basically structural equality,

#![allow(unused)]
fn main() {
const SOME_CONSTANT: SomeType = SomeType { a: 22+22, b: 44+44 };
}

to the value SomeType { a: 44, b: 88 }. We then expand the pattern SOME_CONSTANT as though you had typed this value in place (well, almost as though, read on for some complications around privacy). Thus

#![allow(unused)]
fn main() {
match v {
    SomeType { a: 44, b: 88 } => println!(Yes),
    _ => println!("No"),
}
}

Disadvantages of the current approach

Given

1. No abstraction boundary. The current approach does not permit
   許す
   types to define
   定義する
   what equality
   同一性、等式
   means for themselves (at least not if they can be constructed
   作る、構成体
   in a constant).
2. Scaling
   規模を変更する
   to associated constants.
   定数
   The current approach does not permit
   許す
   associated constants
   定数
   or generic integers
   整数
   to be used in a match
   一致する、マッチさせる
   statement.
   文

Disadvantage: Weakened abstraction bounary

The single

Example: Normalized durations. Consider

#![allow(unused)]
fn main() {
#[derive(Copy, Clone)]
pub struct Duration {
    pub seconds: u32,
    pub minutes: u32,
}
}

Let's say that this Duration type wishes to represent a span of time, but it also wishes to preserve whether that time was expressed in seconds or minutes. In other words, 60 seconds and 1 minute are equal

We might implement

#![allow(unused)]
fn main() {
impl PartialEq for Duration {
    fn eq(&self, other: &Duration) -> bool {
        let s1 = (self.seconds as u64) + (self.minutes as u64 * 60);
        let s2 = (other.seconds as u64) + (other.minutes as u64 * 60);
        s1 == s2
    }
}
}

Now imagine I have some constants:

#![allow(unused)]
fn main() {
const TWENTY_TWO_SECONDS: Duration = Duration { seconds: 22, minutes: 0 };
const ONE_MINUTE: Duration = Duration { seconds: 0, minutes: 1 };
}

And I write a match

#![allow(unused)]
fn main() {
fn detect_some_case_or_other(d: Duration) {
    match d {
        TWENTY_TWO_SECONDS => /* do something */,
        ONE_MINUTE => /* do something else */,
        _ => /* do something else again */,
    }
}
}

Now this code is, in all probability, buggy. Probably I meant to use the notion of equality

Example: Floating point numbers. Another example is floating point numbers. Consider

#![allow(unused)]
fn main() {
match some_computation() {
    0.0 => ...,
    x => ...,
}
}

did not intend to discriminate between zero and negative

Example: observing private fields. The current constant

#![allow(unused)]
fn main() {
mod foo {
    pub struct Foo { b: bool }
    pub const V1: Foo = Foo { b: true };
    pub const V2: Foo = Foo { b: false };
}
}

Note that there is an abstraction boundary here: b is a private field. But now if I wrote code from another module that matches

#![allow(unused)]
fn main() {
fn bar(f: x::Foo) {
    // rustc knows this is exhaustive because if expanded `V1` into
    // equivalent patterns; patterns you could not write by hand!
    match f {
        x::V1 => { /* moreover, now we know that f.b is true */ }
        x::V2 => { /* and here we know it is false */ }
    }
}
}

Note that, because Foo does not implement

More examples. There are numerous possible examples here. For example, strings that compare using case-insensitive comparisons,

Disadvantage: Scaling

規模を変更する

to associated constants

定数

and generic integers

整数

Rewriting constants

#![allow(unused)]
fn main() {
trait SomeTrait {
    const A: bool;
    const B: bool;
}

fn foo<T:SomeTrait>(x: bool) {
    match x {
        T::A => println!("A"),
        T::B => println!("B"),
    }
}

impl SomeTrait for i32 {
    const A: bool = true;
    const B: bool = true;
}

impl SomeTrait for u32 {
    const A: bool = true;
    const B: bool = false;
}
}

Is this match

Advantages of the current approach

However, structural equality

Better optimization. One of the biggest "pros" is that it can potentially enable nice optimization. For example, given

#![allow(unused)]
fn main() {
struct Value { x: u32 }
const V1: Value = Value { x: 0 };
const V2: Value = Value { x: 1 };
const V3: Value = Value { x: 2 };
const V4: Value = Value { x: 3 };
const V5: Value = Value { x: 4 };
}

and a match

#![allow(unused)]
fn main() {
match v {
    V1 => ...,
    ...,
    V5 => ...,
}
}

then, because pattern matching

Better exhautiveness and dead-code checking. Similarly,

#![allow(unused)]
fn main() {
struct Value { field: bool }
const TRUE: Value { field: true };
const FALSE: Value { field: false };
}

and a match

#![allow(unused)]
fn main() {
match v { TRUE => .., FALSE => .. }
}

then we can prove that this match

#![allow(unused)]
fn main() {
const A: Value { field: true };
match v {
    TRUE => ...,
    A => ...,
}
}

Again, some of the alternatives might not allow

Nullary variants and constants

#![allow(unused)]
fn main() {
enum Modes {
    Happy = 22,
    Shiny = 44,
    People = 66,
    Holding = 88,
    Hands = 110,
}

const C: Modes = Modes::Happy;
}

Now if I match

Detailed design

設計（する）

The goal of this RFC is not to decide between semantic and structural equality.

The structural match

一致する、マッチさせる

attribute

We will introduce

Behavior

ふるまい

of #[derive(Eq)]

When deriving the Eq trait, we will add the #[structural_match] to the type in question. Attributes added

Exhaustiveness and dead-code checking

We will treat

Similarly,

One unresolved question (described below) is what behavior

Phasing

段階

We will not make this change instantaneously. Rather, for at least one release cycle, users who are pattern matching

Drawbacks

This is a breaking change, which means some people might have to change their code. However, that is considered

Alternatives

Limit matching

Embrace current semantics (structural equality). Naturally we could opt to keep the semantics as they are. The advantages and disadvantages are discussed above.

Embrace semantic equality.

Discussion thread summary

This section

Overloaded patterns. Some languages,

Pattern synonyms. Haskell offers a feature called

Unresolved questions

What about exhaustiveness etc on builtin types? Even if we ignore

#![allow(unused)]
fn main() {
const X: u64 = 0;
const Y: u64 = 0;
fn bar(foo: u64) {
    match foo {
        X => { }
        Y => { }
        _ => { }
    }
}
}

However, we would be unable to perform such an analysis

#![allow(unused)]
fn main() {
trait Trait {
    const X: u64;
    const Y: u64;
}

fn bar<T:Trait>(foo: u64) {
    match foo {
        T::X => { }
        T::Y => { }
        _ => { }
    }
}
}

Here, although it may well be that T::X == T::Y, we can't know for sure. So, for consistency, we may wish to treat

A different argument

#![allow(unused)]
fn main() {
const fn add_to_hash(prev_hash: u64, _value: u64) -> u64 {
    prev_hash
}
}

Now I have some consumers of my library and they define

#![allow(unused)]
fn main() {
const HASH_OF_ZERO: add_to_hash(0, 0);
const HASH_OF_ONE: add_to_hash(0, 1);
}

And at some point they write a match

#![allow(unused)]
fn main() {
fn process_hash(h: u64) {
    match h {
        HASH_OF_ZERO => /* do something */,
        HASH_OF_ONE => /* do something else */,
        _ => /* do something else again */,
}
}

As before, what you get when you compile this is a dead-code error, because the compiler can see that HASH_OF_ZERO and HASH_OF_ONE are the same value.

Part of the solution here might be making "unreachable patterns" a warning and not an error. The author feels this would be a good idea regardless

On the other hand, it feels very silly for the compiler not to understand that match