Using #[non_exhaustive] for Non-exhaustive Rust Structs

Non-exhaustive Rust structs will future-proof our codes by preventing client codes from using Struct expressions. We use Struct expressions to instantiate structs, and they’re JSON-like expressions in appearance with all fields present. When we update a struct with a new field, all expressions must be updated to include that field.

The non_exhaustive attribute indicates that a type or variant may have more fields or variants added in the future. It can be applied to structs, enums, and enum variants.

For example, we have a struct Pet with two initial fields – name and age.

struct Pet {
    name: String,
    age: i32
}

struct Pet {

name: String,

age: i32

}

We can instantiate it using a struct expression as follows.

let my_pet = Pet { 
                 name: "Jake".to_string(), 
                 age: 2
             };

let my_pet = Pet {

name: "Jake".to_string(),

age: 2

};

The codes work until we add a new field owner to the Struct.

Wouldn’t it be better if we could disallow struct expressions? We could use #[non_exhaustive]!

Non-exhaustive Struts are Crate-Level Only

One important thing to note about #[non_exhaustive]; it only works at the crate level.

Using #[non_exhaustive] for Non-exhaustive Structs

How, then, do we instantiate structs? Through factory functions provided by the crate with non-exhaustive structs.

Non-exhaustive Structs In Crate mycrate lib.rs

This crate has non-exhaustive structs. These are just structs marked with #[non_exhaustive]. The following codes have a struct with two public factory functions to instantiate it in the client codes. They are using #[non_exhaustive] on a struct, which in this case, is just Person.

#[non_exhaustive]
#[derive(Debug)]
pub struct Person {
    pub first_name: String,
    pub last_name: String
}

impl Person {
    pub fn new() -> Person {
        Person {
            first_name: "John".to_string(),
            last_name: "Doe".to_string()
        }
    }

    pub fn new_with_fname_lname(fname: String, lname: String) -> Person {
        Person {
            first_name: fname,
            last_name: lname
        }
    }
}

#[non_exhaustive]

#[derive(Debug)]

pub struct Person {

pub first_name: String,

pub last_name: String

}

impl Person {

pub fn new() -> Person {

Person {

first_name: "John".to_string(),

last_name: "Doe".to_string()

}

pub fn new_with_fname_lname(fname: String, lname: String) -> Person {

Person {

first_name: fname,

last_name: lname

}

When our Struct is non-exhaustive, we restrict the client codes to use the factory functions we defined for the Struct. Therefore, the only way the client codes can instantiate our Struct is via those functions.

Crate myapp that Uses Non-Exhaustive Rust Strut

This crate uses mycrate that has those non-exhaustive structs. Any attempts to use struct expressions to instantiate those structs will fail the building process.

Cargo.toml

[package]
name = "rust1_40features"
version = "0.1.0"
authors = ["Karl San Gabriel"]
edition = "2018"

[dependencies]
# Change path accordingly
mycrate={version="0.1.0", path = "..\\rust\\mycrate" }

[package]

name = "rust1_40features"

version = "0.1.0"

authors = ["Karl San Gabriel"]

edition = "2018"

[dependencies]

# Change path accordingly

mycrate={version="0.1.0", path = "..\\rust\\mycrate" }

main.rs

With our Struct, the following codes show the only way we can instantiate our Person struct. The Rust codes use factory functions we defined in the crate mycrate.

extern crate mycrate;
use mycrate::Person;

fn main() {

    // Instantiate Person using new 
    let p = Person::new();
    println!("{:?}", p);

    // Instantate Person using factory
    let another_p = Person::new_with_fname_lname("Karl".to_string(),
                                                 "San Gabriel".to_string());
    println!("{:?}", another_p);
}

extern crate mycrate;

use mycrate::Person;

fn main() {

// Instantiate Person using new

let p = Person::new();

println!("{:?}", p);

// Instantate Person using factory

let another_p = Person::new_with_fname_lname("Karl".to_string(),

"San Gabriel".to_string());

println!("{:?}", another_p);

}

Output:

Person { first_name: "John", last_name: "Doe" }
Person { first_name: "Karl", last_name: "San Gabriel" }

1 2	Person { first_name: "John", last_name: "Doe" } Person { first_name: "Karl", last_name: "San Gabriel" }

Tested with Rust 1.64.0.

The non-exhaustive attribute can also make Rust enum non-exhaustive. However, it has slightly different semantics than the Non-exhaustive rust Structs.