Rust idiom for exposing public fields while restricting direct struct construction

Question

I know of the visibility rules in Rust and the typical 'constructor' patterns in Rust, e.g. via associated functions, commonly named as new or if all fields of the struct are public, via 'direct' construction, e.g. Struct {value: 0}.

Just wish to get a sense of what is the appropriate idiom to achieve the following:

Exposing a public struct with all public fields but restricting direct construction.

e.g.

pub struct MyStruct {
    pub val: u8,
}

impl MyStruct {
    pub fn new(val: u8) {
        MyStruct {val}
    }
}

Ok for external crate to do this:

use your_crate::MyStruct;

let your_struct = MyStruct::new(8);
println!("{}", your_struct.val);
//8

But not Ok for external crate (call it 'your_crate' vs. 'my_crate' in which MyStruct is defined) to do this:

use my_crate::MyStruct;

let your_struct = MyStruct {val: 8};
// above should return compile error

I am aware that there are two methods to achieve this.

1. Using getter and setter methods and make fields private.

pub struct MyStruct {
    val: u8,
}

impl MyStruct {
    pub fn new(val: u8) {
        MyStruct {val}
    }

    pub fn get_val(&self) -> &u8 {
        self.val
    }
    
    pub fn set_val(&mut self, new_val: u8) {
        *self.val = new_val;
    }
}

This provides access to the fields indirectly via method calls instead of attribute access.

2. Add a 'private' inconsequential field.

pub struct MyStruct {
    pub val: u8,
    _private: (),
}

This prevents direct construction but allows for direct attribute access and removes the need for implementing superfluous 'get' and 'set' methods.

My question is:

Which is the more appropriate idiom accepted by many in the community? Or what considerations should a library writer think through before deciding which idiom is more appropriate?

Answer 1

You can use a private field trick, but the normal way to do this would probably be the #[non_exhaustive] annotation, which works with structs as well as enums.

Non-exhaustive types cannot be constructed outside of the defining crate:

• Non-exhaustive variants (struct or enum variant) cannot be constructed with a StructExpression (including with functional update syntax).

Answer 2

Using getters is the most common. However, they're usually field and field_mut:

fn val(&self) -> &u8 {
    &self.val
}

fn val_mut(&mut self) -> &mut u8 {
    &mut self.val
}

A setter method is useful if you want to (leave open the option to) process incoming values.

Your second method isn't used much since it's functionally a downgrade from a fully public struct. If someone wanted to make one with arbitrary values, they could just construct one via a constructor and then reassign all the fields.

There is one common case where this is useful: reserving the ability to add fields without breaking your API. There is a built-in attribute for that: #[non_exhaustive].

#[non_exhaustive]
pub struct MyStruct {
    pub val: u8,
}

This is used more on enums, but on structs it prevents code outside the module from constructing the struct with the braces syntax, like MyStruct { val: 0 }.