DEV Community: SomeB1oody

[Advanced Rust] 2.10. API Design Principles of Constrained Pt.1 - Changing Types

SomeB1oody — Wed, 12 Aug 2026 16:49:22 +0000

2.10.1. Think Carefully Before Changing an Interface

If your interface is going to change in a way that is visible to users, think twice before doing it.

You need to make sure that the changes you make:

Do not break existing user code
Should remain in place for a while

Frequently shipping backward-incompatible changes (major version bumps) will make users unhappy.

2.10.2. Backward-Incompatible Changes

Some backward-incompatible changes are obvious, such as changing the name of a public type or removing a public item from it.

Some backward-incompatible changes are more subtle and are closely tied to how Rust works. This article mainly focuses on those changes and how you, as a developer, should plan for them.

In the process, you sometimes need to make trade-offs and compromises in interface flexibility.

2.10.3. Modifying Types

If you remove or rename a public type, it will almost certainly break user code. The solution is to use visibility modifiers as much as possible. For example:

pub(crate): visible within the current crate
pub(in path): visible within the specified path

Example:

pub mod outer_mod {
    pub mod inner_mod {
        // This function is visible only to `outer_mod`
        pub(in crate::outer_mod) fn outer_mod_visible_fn() {}

        // This function is visible to the entire crate
        pub(crate) fn crate_visible_fn() {}

        // This function is visible only to `outer_mod` (using `super` to refer to the outer module)
        pub(super) fn super_mod_visible_fn() {
            // `inner_mod_visible_fn` is visible within the same module, so it can be called normally
            inner_mod_visible_fn();
        }

        // This function is visible only inside `inner_mod`, equivalent to `private`
        pub(self) fn inner_mod_visible_fn() {}
    }

    pub fn foo() {
        inner_mod::outer_mod_visible_fn();
        inner_mod::crate_visible_fn();
        inner_mod::super_mod_visible_fn();

        // This function is no longer visible because we are outside `inner_mod`
        // Error! `inner_mod_visible_fn` is private
        inner_mod::inner_mod_visible_fn();
    }
}

fn bar() {
    // This function is still visible because we are in the same crate
    outer_mod::inner_mod::crate_visible_fn();

    // This function is no longer visible outside `outer_mod`
    // Error! `super_mod_visible_fn` is private
    outer_mod::inner_mod::super_mod_visible_fn();

    // This function is also not visible outside `outer_mod`
    // Error! `outer_mod_visible_fn` is private
    outer_mod::inner_mod::outer_mod_visible_fn();

    outer_mod::foo();
}

Visibility control for the functions in the inner_mod module:

outer_mod_visible_fn(): visible only inside outer_mod, not accessible from outside
crate_visible_fn(): visible to the entire crate, so bar() can still access it
super_mod_visible_fn(): visible only inside outer_mod, so bar() cannot access it
inner_mod_visible_fn(): private, visible only inside inner_mod

The fewer public types you expose in your API, the more freedom you have to change it later (freedom here means not breaking existing code).

`#[non_exhaustive]` Attribute

User code depends on more than just the name of your type. Example:

An Example of a Breaking Change

At the beginning, I wrote a struct called Unit in lib.rs:

pub struct Unit;

Then I used Unit in main.rs:

fn main() {
    let u = constrained::Unit;
}

That works fine.

Later, I modified Unit because users needed it:

pub struct Unit {
    pub field: bool,
}

The code in main.rs would also change:

fn is_true(u: constrained::Unit) -> bool {
    matches!(u, constrained::Unit { field: true })
}

fn main() {
    let u = constrained::Unit {
        field: true,
    };
}

The is_true function uses the modified Unit field
But the original code in main would then fail to compile

The same thing happens when Unit has a private field. The compiler knows that Unit has fields, but you did not provide values for them.

Solution

For this situation, Rust provides the #[non_exhaustive] attribute to mitigate these problems. It can be applied to struct, enum, and enum variants. It indicates that the type or enum may gain more fields or variants in the future.

If you use it, then when others use your crate, the compiler will:

Forbid explicit construction, such as lib::Unit { field: true }
Forbid non-exhaustive pattern matching, that is, patterns without a trailing ..

If your interface is relatively stable, you should avoid using this attribute.

Example:

lib.rs:

#[non_exhaustive]
pub struct Config {
    pub window_width: u16,
    pub window_height: u16,
}

fn some_function() {
    let config: Config = Config {
        window_width: 640,
        window_height: 480,
    };

    // Non-exhaustive structs can be matched exhaustively within the defining crate.
    if let Config {
        window_width,
        window_height,
    } = config
    {
        // ...
    }
}

With #[non_exhaustive], lib.rs can still use explicit construction and exhaustive matching, because this code belongs to the same crate that defines the struct

What if I write this in main.rs?

use constrained::Config;

fn main() {
    let config: Config = Config {
        window_width: 640,
        window_height: 480,
    };

    if let Config {
        window_width,
        window_height,
    } = config {}
}

This will fail to compile, because this code belongs to an external crate, and the compiler will prohibit the two operations mentioned above

Output:

error[E0639]: cannot create non-exhaustive struct using struct expression
 --> src/main.rs:4:26
  |
4 |       let config: Config = Config {
  |  __________________________^
5 | |         window_width: 640,
6 | |         window_height: 480,
7 | |     };
  | |_____^

error[E0638]: `..` required with struct marked as non-exhaustive
  --> src/main.rs:9:12
   |
 9 |       if let Config {
   |  ____________^
10 | |         window_width,
11 | |         window_height,
12 | |     } = config {}
   | |_____^

We can slightly change the code so that the match in main.rs becomes a non-exhaustive pattern with ..:

if let Config {
    window_width,
    window_height,
    .. // this ignores the remaining fields or variants in a struct, tuple, or enum
} = config {
}

[Advanced Rust] 2.9. API Design Principles of Obviousness - Documentation and Type System, Semantic Types, and Zero-Sized Types

SomeB1oody — Mon, 10 Aug 2026 19:03:59 +0000

2.9.1. Documentation and the Type System

Users may not fully understand all of an API's rules and restrictions. So your API should be easy for users to understand and hard to misuse.

With Rust's documentation and type system, we can try to achieve that.

2.9.2. Documentation

The first step toward making an API transparent is to write good documentation.

Writing good documentation has several requirements:

1. Clearly Document Things

Clearly document any unexpected situations that may occur, or any behavior that depends on the user doing something beyond the type signature.

For example: when panic can happen, when an error is returned. If you use an unsafe function, you must explain the conditions under which the user can safely call it.

Example:

Here we documented the cases in which a panic may occur

2. Include End-to-End Examples

At the crate or module level, include end-to-end examples rather than examples for a specific type or method.

The benefit of doing this is that users can see how the pieces fit together and get a relatively clear understanding of the API's overall structure, which helps developers quickly understand what each method and type does and where to use them.

Once you provide an end-to-end example, users can copy and paste that code into their own project, effectively giving them a customized starting point.

For example:

Suppose we have a math_utils crate that provides some mathematical operations, including basic addition, subtraction, and a complex calculation function. I will only write the function descriptions briefly in the doc comments here, but when you write your own code, you must document each function properly.

3. Organize the Documentation Well

Use modules to group semantically related items, and then connect them with internal documentation links.

Sometimes you may want to use #[doc(hidden)] to mark interfaces that are not meant to be public but must remain for legacy reasons, so they do not clutter the documentation.

Example:

/// A simple module containing some functions and structs for internal use.
pub mod internal {
    /// A helper function used only internally.
    #[doc(hidden)]
    pub fn internal_helper() {
        // The concrete implementation of the internal calculation...
    }

    /// A struct used only internally.
    #[doc(hidden)]
    pub struct InternalStruct {
        // The struct's fields and methods...
    }
}

The internal_helper() function and the InternalStruct struct are both for internal use only
By marking them with #[doc(hidden)], their documentation comments will not appear in the generated docs

4. Enrich the Documentation as Much as Possible

Sometimes you need to explain content and concepts, and you can add links to external resources, such as RFCs, blogs, and white papers.

At the top-level documentation, you should guide users to common modules, traits, types, and methods.

Some notes about documentation features:

Use #[doc(cfg(..))] to highlight items that are available only under specific configurations, so users can quickly understand why a method shown in the docs is unavailable
Use #[doc(alias = "...")] to let users search for a type or method under alternative names

Example 1:

//! This is a library for image processing.
//!
//! This library provides some common image processing features, such as:
//! - Reading and saving image files in different formats [`Image::load`] [`Image::save`]
//! - Resizing, rotating, and cropping images [`Image::resize`] [`Image::rotate`] [`Image::crop`]
//! - Applying different filters and effects [`Filter`] [`Effect`]
//!
//! If you want to learn more about the principles and algorithms of image processing, you can refer to the following resources:
//! - [Digital Image Processing](https://book.douban.com/subject/5345798/), a classic textbook that introduces the basic concepts and methods of image processing.
//! - [Learn OpenCV](https://learnopencv.com/), a website with many tutorials and sample code for implementing image processing with OpenCV.
//! - [Awesome Computer Vision](https://github.com/jbhuang0604/awesome-computer-vision), a GitHub repository collecting many computer vision resources and projects.

/// A struct representing an image
#[derive(Debug, Clone)]
pub struct Image {
    // ...
}
// ...

Here we used external links. You can see that the link format is [text to display in the docs](https://raw.githubusercontent.com/SomeB1oody/AdvancedRust/main/en/src/Chapter-02/2.9/link), which is standard Markdown and should be familiar to anyone who has written a README before

Example 2:

impl Image {
    // ...
    // ...
    #[doc(alias = "read")]
    #[doc(alias = "open")]
    pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
        // ...
    }
    // ...
}

We used #[doc(alias = "read")] and #[doc(alias = "open")], so searching for “read” and “open” in the docs will find this function

Example 3:

/// A struct that is only available when the `foo` feature is enabled.
#[cfg(feature = "foo")]
#[doc(cfg(feature = "foo"))]
pub struct Foo;

impl Foo {
    /// A method that is only available when the `foo` feature is enabled.
    #[cfg(feature = "foo")]
    #[doc(cfg(feature = "foo"))]
    pub fn bar(&self) {
        // ...
    }
}

fn main() {
    println!("Hello, world!");
}

#[cfg(feature = "foo")]: only when the "foo" feature is enabled will the Foo struct and its bar method be included in the final build artifact
#[doc(cfg(feature = "foo"))]: marks the struct and method in the API docs as depending on the foo feature, so users know they are not available by default

2.9.3. The Type System

Using Rust's type system can ensure that APIs are:

Obvious
Self-describing
Hard to misuse

Semantic Types

Some values have meaning beyond their surface form. For example, 1 and 0 can represent male and female. In that case, we can add types to represent the meaning of the value.

Example:

fn processData(dryRun: bool, overwrite: bool, validate: bool) {
    // data processing logic
}

The three parameters of this function are all booleans, so they are easy to confuse, and users are very likely to use them incorrectly

To solve this, we can create three types and make the parameters have three different types:


enum DryRun {
    Yes,
    No,
}

enum Overwrite {
    Yes,
    No,
}

enum Validate {
    Yes,
    No,
}

fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) {
    // data processing logic
}

Turn the three booleans into three enum types

When users call the function, they will write:

processData(DryRun::Yes, Overwrite::No, Validate::Yes)

That is much clearer.

Using Zero-Sized Types to Represent Facts About a Type Instance

For example:

Suppose we have a Rocket struct with a launch method for launching it. If the rocket is not already launched, calling this method is perfectly fine. But if the rocket is already launched, you should not be able to launch it again. Likewise, after launch we can control acceleration and deceleration, but not while on the ground.

// Define different rocket states
struct Grounded;
struct Launched;

// Color enum
enum Color {
    White,
    Black,
}

// Mass type, using the newtype pattern to wrap `u32`
struct Kilograms(u32);

// Generic rocket struct with a default state of `Grounded`
struct Rocket<Stage = Grounded> {
    stage: std::marker::PhantomData<Stage>,
}

// Implement `Default` for `Rocket<Grounded>`
impl Default for Rocket<Grounded> {
    fn default() -> Self {
        Self {
            stage: Default::default(),
        }
    }
}

// Implement methods for `Rocket<Grounded>`
impl Rocket<Grounded> {
    pub fn launch(self) -> Rocket<Launched> {
        Rocket {
            stage: Default::default(),
        }
    }
}

// Implement methods for `Rocket<Launched>`
impl Rocket<Launched> {
    pub fn accelerate(&mut self) {}
    pub fn decelerate(&mut self) {}
}

// Implement common methods for rockets in all states
impl<Stage> Rocket<Stage> {
    pub fn color(&self) -> Color {
        Color::White
    }

    pub fn weight(&self) -> Kilograms {
        Kilograms(0)
    }
}

Grounded and Launched have no fields, so their size is zero, and the Rust compiler does not allocate memory for them. They are used only to mark which state Rocket is in, without extra storage cost
We define a Rocket struct with a generic parameter Stage, which defaults to Grounded. In the definition we also use std::marker::PhantomData<T>, which is a zero-sized type (ZST, Zero-Sized Type). It affects the type system at compile time but does not occupy memory at runtime
The launch method is only available on Rocket<Grounded>
After launch() is called, it returns a Rocket<Launched>, indicating that the rocket has entered the launched state. Rocket<Launched> no longer has a launch() method, ensuring that it cannot be launched twice
The accelerate method represents acceleration and decelerate represents deceleration. These methods apply only to Rocket<Launched>, preventing acceleration or deceleration while in the Grounded state
Some methods can be used in any state, and we place them in the impl<Stage> Rocket<Stage> block

`#[must_use]` Attribute

After you add the #[must_use] attribute to a type, trait, or function, if user code receives a value of that type or trait, or calls that function, and does not explicitly handle it, the compiler will emit a warning.

Example:

#[must_use]
fn process_data(data: Data) -> Result<(), Error> {
    // ...

    Ok(())
}

We use the #[must_use] attribute to mark process_data as a function whose return value must be used
If the user does not explicitly handle the returned Result after calling the function, the compiler will issue a warning
This helps remind users to be careful when dealing with potential error cases and reduces the chance of mistakes

[Advanced Rust] 2.8. API Design Principles of Flexibility Pt.4 - Problems with Explicit Destructors and Three Solutions

SomeB1oody — Mon, 10 Aug 2026 01:43:35 +0000

2.8.1. Problems with Explicit Destructors

Problems arise when you add an explicit destructor:

When a type implements Drop, you cannot move any of its fields out inside the destructor. That is because after the explicit destructor runs, drop() will still be called, and it takes &mut self, which requires all parts of self to remain in place.
Drop takes &mut self rather than self, so Drop cannot simply call the explicit destructor and ignore its result, because Drop does not own self

Based on the example from the previous article, if we add both a Drop implementation and a close method:

use std::os::fd::{FromRawFd, IntoRawFd};
use std::fs::{File as StdFile, OpenOptions, metadata};
use std::io::Error;

/// A type that represents a file handle
struct File {
    /// File name
    name: String,
    /// File descriptor
    fd: i32,
}

impl File {
    /// A constructor that opens a file and returns a `File` instance
    fn open(name: &str) -> Result<File, Error> {
        // Open the file with read and write permissions using `OpenOptions`
        let file: StdFile = OpenOptions::new()
            .read(true)
            .write(true)
            .open(name)?;

        // Obtain the file descriptor
        let fd: i32 = file.into_raw_fd();

        // Return a `File` instance
        Ok(File {
            name: name.to_string(),
            fd,
        })
    }

    /// An explicit destructor that closes the file and returns any error
    fn close(self) -> Result<(), Error> {
        // Convert the fd back into a `File` using `FromRawFd`
        let file: std::fs::File = unsafe {
            std::fs::File::from_raw_fd(self.fd)
        };

        // Flush file data to disk
        file.sync_all()?;

        // Truncate the file to 0 bytes
        file.set_len(0)?;

        // Flush the file again
        file.sync_all()?;

        // Drop the file instance; it will close the file automatically
        drop(file);

        // Return success
        Ok(())
    }
}

// Implement `Drop`
impl Drop for File {
    fn drop(&mut self) {
        let _ = self.close(); // call `close` while dropping
        println!("File dropped");
    }
}

fn main() {
    // Create a file named "test.txt" and write some content to it
    std::fs::write("test.txt", "Hello, world!").unwrap();

    // Open the file and obtain a `File` instance
    let file: File = File::open("test.txt").unwrap();

    // Print the file name and fd
    println!("File name: {}, fd: {}", file.name, file.fd);

    // Close the file and handle any error
    match file.close() {
        Ok(()) => println!("File closed successfully"),
        Err(e) => println!("Error closing file: {}", e),
    }

    // Check the file size after closing
    let metadata = metadata("test.txt").unwrap();
    println!("File size: {} bytes", metadata.len());
}

Output:

error[E0507]: cannot move out of `*self` which is behind a mutable reference
  --> src/main.rs:59:17
   |
59 |         let _ = self.close(); // call `close` while dropping
   |                 ^^^^ ------- `*self` moved due to this method call
   |                 |
   |                 move occurs because `*self` has type `File`, which does not implement the `Copy` trait
   |
note: `File::close` takes ownership of the receiver `self`, which moves `*self`
  --> src/main.rs:33:14
   |
33 |     fn close(self) -> Result<(), Error> {
   |              ^^^^
note: if `File` implemented `Clone`, you could clone the value
  --> src/main.rs:6:1
   |
 6 | struct File {
   | ^^^^^^^^^^^ consider implementing `Clone` for this type
...
59 |         let _ = self.close(); // call `close` while dropping
   |                 ---- you could clone this value

The error message shows that we cannot move a value out of *self because it sits behind &mut self.

2.8.2. Solutions

First, it is important to note that there is no perfect solution; we can only try our best to compensate.

Solution 1: Wrap the Struct in `Option<T>` and Add Another Layer of Struct

We can turn the outer layer into a new type that wraps Option<T>, so that the Option<T> internally holds a type containing all the fields.

At that point, we need two destructors, one outer and one inner. In both destructors, we use Option::take to get ownership of the data and remove the value.

Because the inner type does not implement Drop, you can take ownership of all fields.

The downside is that every method you want to provide on the outer type now has to include code to access the fields on the inner type through the Option<T> wrapper.

We modify the earlier example as follows:

Step 1: Change the `File` definition and add a wrapper layer

First, we need to move the two fields into another struct and wrap that struct in Option<T> as a field of File.

/// A type that represents a file handle
struct InnerFile {
    /// File name
    name: String,
    /// File descriptor
    fd: i32,
}

/// A wrapper around `InnerFile`
struct File {
    /// Wrap `InnerFile` in `Option<T>`
    inner: Option<InnerFile>,
}

Step 2: Update the methods on `File`

There are two methods on File, and we need to add code to access the inner fields through the Option<T> wrapper.

First, the open method:

/// A constructor that opens a file and returns a `File` instance
fn open(name: &str) -> Result<File, Error> {
    // Open the file with read and write permissions using `OpenOptions`
    let file: StdFile = OpenOptions::new()
        .read(true)
        .write(true)
        .open(name)?;

    // Obtain the file descriptor
    let fd: i32 = file.into_raw_fd();

    // Return a `File` instance
    Ok(File {
        inner: Some(InnerFile {
            name: name.to_string(),
            fd,
        }),
    })
}

Because this code only uses File in the return value, only the return value needs to change

Next, the close method:

/// An explicit destructor that closes the file and returns any error
fn close(mut self) -> Result<(), Error> { // remember to make `self` mutable, otherwise `take` will not work
    // Use pattern matching to extract the field values
    if let Some(inner) = self.inner.take() {
        let name = inner.name;
        let fd = inner.fd;
        println!("Closing file: {} with fd: {}", name, fd);

        // Convert the fd back into a `File` using `FromRawFd`
        let file: std::fs::File = unsafe {
            std::fs::File::from_raw_fd(fd)
        };

        // Flush file data to disk
        file.sync_all()?;

        // Truncate the file to 0 bytes
        file.set_len(0)?;

        // Flush the file again
        file.sync_all()?;

        // Drop the file instance; it will close the file automatically
        drop(file);

        // Return success
        Ok(())
    } else {
        // If `inner` is `None`, the file has already been closed or dropped, so return an error
        Err(Error::new(
            std::io::ErrorKind::Other,
            "File is already closed",
        ))
    }
}

After receiving the parameter, we first use pattern matching to access the field values
If the inner field is None, that is, if pattern matching fails, we need to return an error ourselves

Step 3: Update the `Drop` implementation

Drop::drop needs to be changed:

fn drop(&mut self) {
    // Use pattern matching to get the field values
    if let Some(inner) = self.inner.take() {
        let name = inner.name;
        let fd = inner.fd;
        println!("Dropping file: {} (fd: {})", name, fd);

        // Convert the fd back into a `File` using `FromRawFd`
        let file: std::fs::File = unsafe {
            std::fs::File::from_raw_fd(fd)
        };

        // Drop the `File` instance
        drop(file);
    } else {
        // If the `inner` field is `None`, the file has already been dropped or closed; do nothing
    }
}

After receiving the parameter, we first use pattern matching to get the field values
If the inner field is None, the file has already been dropped or closed, so we do nothing

Step 4: Slightly Adjust `main`

The parts of main that need to access field values must be updated:

fn main() {
    // ...unchanged above, omitted

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}",
        file.inner.as_ref().unwrap().name,
        file.inner.as_ref().unwrap().fd
    );

    // ...unchanged below, omitted
}

The original type is Option<InnerFile>. After calling .as_ref(), it becomes Option<&InnerFile>
Once it becomes Option<&InnerFile>, the value extracted by unwrap is a reference rather than an owned value
file.inner is an Option<InnerFile>. Accessing the Option value directly would require moving ownership or pattern matching (for example through take() or unwrap()), which would destroy the inner value of the Option, so as_ref() is needed

Full Code

use std::os::fd::{FromRawFd, IntoRawFd};
use std::fs::{File as StdFile, OpenOptions, metadata};
use std::io::Error;

/// A type that represents a file handle
struct InnerFile {
    /// File name
    name: String,
    /// File descriptor
    fd: i32,
}

/// A wrapper around `InnerFile`
struct File {
    /// Wrap `InnerFile` in `Option<T>`
    inner: Option<InnerFile>,
}

impl File {
    /// A constructor that opens a file and returns a `File` instance
    fn open(name: &str) -> Result<File, Error> {
        // Open the file with read and write permissions using `OpenOptions`
        let file: StdFile = OpenOptions::new()
            .read(true)
            .write(true)
            .open(name)?;

        // Obtain the file descriptor
        let fd: i32 = file.into_raw_fd();

        // Return a `File` instance
        Ok(File {
            inner: Some(InnerFile {
                name: name.to_string(),
                fd,
            }),
        })
    }

    /// An explicit destructor that closes the file and returns any error
    fn close(mut self) -> Result<(), Error> {
        // Use pattern matching and `std::mem::take` to extract the `name` field value
        if let Some(inner) = self.inner.take() {
            let name = inner.name;
            let fd = inner.fd;
            println!("Closing file: {} with fd: {}", name, fd);

            // Convert the fd back into a `File` using `FromRawFd`
            let file: std::fs::File = unsafe {
                std::fs::File::from_raw_fd(fd)
            };

            // Flush file data to disk
            file.sync_all()?;

            // Truncate the file to 0 bytes
            file.set_len(0)?;

            // Flush the file again
            file.sync_all()?;

            // Drop the file instance; it will close the file automatically
            drop(file);

            // Return success
            Ok(())
        } else {
            // If the `inner` field is `None`, the file has already been closed or dropped, so return an error
            Err(Error::new(
                std::io::ErrorKind::Other,
                "File is already closed",
            ))
        }
    }
}

// Implement `Drop` for code that runs when the value leaves scope
impl Drop for File {
    fn drop(&mut self) {
        // Use pattern matching to get the field values
        if let Some(inner) = self.inner.take() {
            let name = inner.name;
            let fd = inner.fd;
            println!("Dropping file: {} (fd: {})", name, fd);

            // Convert the fd back into a `File` using `FromRawFd`
            let file: std::fs::File = unsafe {
                std::fs::File::from_raw_fd(fd)
            };

            // Drop the file instance
            drop(file);
        } else {
            // If the `inner` field is `None`, the file has already been dropped or closed; do nothing
        }
    }
}

fn main() {
    // Create a file named "test.txt" and write some content to it
    std::fs::write("test.txt", "Hello, world!").unwrap();

    // Open the file and obtain a `File` instance
    let file: File = File::open("test.txt").unwrap();

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}",
        file.inner.as_ref().unwrap().name,
        file.inner.as_ref().unwrap().fd
    );

    // Close the file and handle any error
    match file.close() {
        Ok(()) => println!("File closed successfully"),
        Err(e) => println!("Error closing file: {}", e),
    }

    // Check the file size after closing
    let metadata = metadata("test.txt").unwrap();
    println!("File size: {} bytes", metadata.len());
}

Solution 2: Wrap Each Field in `Option<T>`

We can also keep the struct unchanged, but wrap each field in Option<T>. When ownership is needed, use Option::take; when a reference is needed, use .as_ref() and .unwrap().

This works very well if the type has a reasonable empty value.

The downside is that if you have to wrap almost every field in Option and then match and unwrap those fields on every access, the code becomes very verbose.

We modify the earlier example as follows:

Step 1: Change the `File` definition

Add one layer of Option<T> to each field:

/// A type that represents a file handle
struct File {
    /// File name
    name: Option<String>,
    /// File descriptor
    fd: Option<i32>,
}

Step 2: Update the methods on `File`

There are two methods on File, and we need to add code to access the fields through the Option<T> wrapper.

First, the open method:

/// A constructor that opens a file and returns a `File` instance
fn open(name: &str) -> Result<File, Error> {
    // Open the file with read and write permissions using `OpenOptions`
    let file: StdFile = OpenOptions::new()
        .read(true)
        .write(true)
        .open(name)?;

    // Obtain the file descriptor
    let fd: i32 = file.into_raw_fd();

    // Return a `File` instance
    Ok(File {
        name: Some(name.to_string()),
        fd: Some(fd),
    })
}

The open method's parameter does not involve the File struct, so the parameter part does not need to change
The open method's return value involves File, so each field needs to be wrapped in Some

Next, the close method:

/// An explicit destructor that closes the file and returns any error
fn close(mut self) -> Result<(), Error> {
    // Pattern-match and use `std::mem::take` to take out the `name` field value
    if let Some(name) = std::mem::take(&mut self.name) {
        // Pattern-match and use `std::mem::take` to take out the `fd` field value
        if let Some(fd) = std::mem::take(&mut self.fd) {
            // Print
            println!("Closing file: {} with fd: {}", name, fd);

            // Convert the fd back into a `File` using `FromRawFd`
            let file: std::fs::File = unsafe {
                std::fs::File::from_raw_fd(fd)
            };

            // Flush file data to disk
            file.sync_all()?;

            // Truncate the file to 0 bytes
            file.set_len(0)?;

            // Flush the file again
            file.sync_all()?;

            // Drop the file instance; it will close the file automatically
            drop(file);

            // Return success
            Ok(())
        } else {
            // If the `fd` field is `None`, the file has already been closed or dropped, so return an error
            Err(Error::new(
                std::io::ErrorKind::Other,
                "File descriptor already dropped or taken",
            ))
        }
    } else {
        // If the `name` field is `None`, the file has already been closed or dropped, so return an error
        Err(Error::new(
            std::io::ErrorKind::Other,
            "File name already dropped or taken",
        ))
    }
}

The parameter must first be pattern-matched, and we use std::mem::take to take out the value inside it
If any field is None, it means the file has already been closed or dropped, so an error is returned

Step 3: Update the `Drop` implementation

fn drop(&mut self) {
    // Use pattern matching to get the field values
    if let Some(name) = self.name.take() {
        if let Some(fd) = self.fd.take() {
            println!("Dropping file: {} (fd: {})", name, fd);

            // Convert the fd back into a `File`
            let file: std::fs::File = unsafe {
                std::fs::File::from_raw_fd(fd)
            };

            // Drop the file instance
            drop(file);
        } else {
            // If the `fd` field is `None`, the file has already been closed or dropped; do nothing
        }
    } else {
        // If the `name` field is `None`, the file has already been closed or dropped; do nothing
    }
}

The parameter must first be pattern-matched, and we use std::mem::take to take out the value inside it
If any field is None, it means the file has already been closed or dropped; do nothing

Step 4: Slightly Adjust `main`

fn main() {
    // ...unchanged above, omitted

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}",
         file.name.as_ref().unwrap(),
         file.fd.as_ref().unwrap()
    );

    // ...unchanged below, omitted
}

The original type is wrapped in Option<T>, so calling .as_ref() gives you a reference to the value inside
Once it becomes a reference, unwrap extracts a reference rather than an owned value
Accessing the Option value directly requires moving ownership or pattern matching (for example through take() or unwrap()), which destroys the inner value of the Option, so as_ref() is needed

Full Code

use std::os::fd::{FromRawFd, IntoRawFd};
use std::fs::{File as StdFile, OpenOptions, metadata};
use std::io::Error;

/// A type that represents a file handle
struct File {
    /// File name
    name: Option<String>,
    /// File descriptor
    fd: Option<i32>,
}

impl File {
    /// A constructor that opens a file and returns a `File` instance
    fn open(name: &str) -> Result<File, Error> {
        // Open the file with read and write permissions using `OpenOptions`
        let file: StdFile = OpenOptions::new()
            .read(true)
            .write(true)
            .open(name)?;

        // Obtain the file descriptor
        let fd: i32 = file.into_raw_fd();

        // Return a `File` instance
        Ok(File {
            name: Some(name.to_string()),
            fd: Some(fd),
        })
    }

    /// An explicit destructor that closes the file and returns any error
    fn close(mut self) -> Result<(), Error> {
        // Pattern-match and use `std::mem::take` to take out the value inside `name`
        if let Some(name) = std::mem::take(&mut self.name) {
            // Pattern-match and use `std::mem::take` to take out the value inside `fd`
            if let Some(fd) = std::mem::take(&mut self.fd) {
                // Print
                println!("Closing file: {} with fd: {}", name, fd);

                // Convert the fd back into a `File` using `FromRawFd`
                let file: std::fs::File = unsafe {
                    std::fs::File::from_raw_fd(fd)
                };

                // Flush file data to disk
                file.sync_all()?;

                // Truncate the file to 0 bytes
                file.set_len(0)?;

                // Flush the file again
                file.sync_all()?;

                // Drop the file instance; it will close the file automatically
                drop(file);

                // Return success
                Ok(())
            } else {
                // If the `fd` field is `None`, the file has already been closed or dropped, so return an error
                Err(Error::new(
                    std::io::ErrorKind::Other,
                    "File descriptor already dropped or taken",
                ))
            }
        } else {
            // If the `name` field is `None`, the file has already been closed or dropped, so return an error
            Err(Error::new(
                std::io::ErrorKind::Other,
                "File name already dropped or taken",
            ))
        }
    }
}

// Implement `Drop` for code that runs when the value leaves scope
impl Drop for File {
    fn drop(&mut self) {
        // Use pattern matching to get the field values
        if let Some(name) = self.name.take() {
            if let Some(fd) = self.fd.take() {
                println!("Dropping file: {} (fd: {})", name, fd);

                // Convert the fd back into a `File`
                let file: std::fs::File = unsafe {
                    std::fs::File::from_raw_fd(fd)
                };

                // Drop the file instance
                drop(file);
            } else {
                // If the `fd` field is `None`, the file has already been closed or dropped; do nothing
            }
        } else {
            // If the `name` field is `None`, the file has already been closed or dropped; do nothing
        }
    }
}

fn main() {
    // Create a file named "test.txt" and write some content to it
    std::fs::write("test.txt", "Hello, world!").unwrap();

    // Open the file and obtain a `File` instance
    let file: File = File::open("test.txt").unwrap();

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}",
         file.name.as_ref().unwrap(),
         file.fd.as_ref().unwrap()
    );

    // Close the file and handle any error
    match file.close() {
        Ok(()) => println!("File closed successfully"),
        Err(e) => println!("Error closing file: {}", e),
    }

    // Check the file size after closing
    let metadata = metadata("test.txt").unwrap();
    println!("File size: {} bytes", metadata.len());
}

Solution 3: Store Data in `ManuallyDrop`

If data is stored in ManuallyDrop, it dereferences to the inner type, so there is no need to use unwrap anymore.

When destroying values inside drop, you can use ManuallyDrop::take to gain ownership.

The downside is that ManuallyDrop::take is unsafe, so it must be placed inside an unsafe block.

We modify the earlier example as follows:

Step 1: Change the `File` definition

Add a ManuallyDrop wrapper to each field:

/// A type that represents a file handle
struct File {
    /// File name
    name: ManuallyDrop<String>,
    /// File descriptor
    fd: ManuallyDrop<i32>,
}

Step 2: Update the methods on `File`

There are two methods on File, and we need to add code to access the fields through the wrapper.

First, the open method:

/// A constructor that opens a file and returns a `File` instance
fn open(name: &str) -> Result<File, Error> {
    // Open the file with read and write permissions using `OpenOptions`
    let file: StdFile = OpenOptions::new()
        .read(true)
        .write(true)
        .open(name)?;

    // Obtain the file descriptor
    let fd: i32 = file.into_raw_fd();

    // Return a `File` instance
    Ok(File {
        name: ManuallyDrop::new(name.to_string()),
        fd: ManuallyDrop::new(fd),
    })
}

The open method's parameter does not involve the File struct, so the parameter part does not need to change
The open method's return value involves File, so each field must be passed with ManuallyDrop::new

Next, the close method:

/// An explicit destructor that closes the file and returns any error
fn close(mut self) -> Result<(), Error> {
    // Use `std::mem::replace` to replace the `name` field with an empty string, and keep the original value in `name`
    let name =
        std::mem::replace(&mut self.name, ManuallyDrop::new("".to_string()));

    // Use `std::mem::replace` to replace the `fd` field with an invalid value (-1), and keep the original value in `fd`
    let fd =
        std::mem::replace(&mut self.fd, ManuallyDrop::new(-1));

    // Print
    println!("Closing file: {:?} with fd: {:?}", name, fd);

    // Convert the fd back into a `File` using `FromRawFd`
    let file: std::fs::File = unsafe {
        std::fs::File::from_raw_fd(*fd) // `fd` must be dereferenced first
    };

    // Flush file data to disk
    file.sync_all()?;

    // Truncate the file to 0 bytes
    file.set_len(0)?;

    // Flush the file again
    file.sync_all()?;

    // Drop the file instance; it will close the file automatically
    drop(file);

    // Return success
    Ok(())
}

Use std::mem::replace to replace the name field with an empty string and store the original value in name
Use std::mem::replace to replace the fd field with an invalid value (-1) and store the original value in fd
In std::fs::File::from_raw_fd(*fd), the argument must be dereferenced first, so write *fd

Step 3: Update the `Drop` implementation

fn drop(&mut self) {
    // Use `ManuallyDrop::take` to take the `name` field value and check whether it is an empty string
    let name = unsafe { ManuallyDrop::take(&mut self.name) };

    // Use `ManuallyDrop::take` to take the `fd` field value and check whether it is an invalid value
    let fd = unsafe { ManuallyDrop::take(&mut self.fd) };

    // Print
    println!("Dropping file: {:?} (fd: {:?})", name, fd);

    // If the `fd` field is not the invalid value, the file has not been closed or dropped yet, so perform the drop operation
    if fd != -1 || !name.is_empty() {
        let file = unsafe { std::fs::File::from_raw_fd(fd) };
        // Drop it
        drop(file);
    }
}

Use ManuallyDrop::take to take the values of name and fd, and check whether they are an empty string or an invalid value
If the fd field is not the invalid value (-1), or the name field is not empty, then the file has not been closed or dropped yet, so a drop operation is needed
In fact, you do not need both conditions (fd != -1 || !name.is_empty()); one is enough, because the value changes of name and fd happen together, and if one is invalid it means the whole struct has not yet been cleaned up

Step 4: Slightly Adjust `main`

fn main() {
    // ...unchanged above, omitted

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}", *file.name, *file.fd);

    // ...unchanged below, omitted
}

Use dereferencing to print the values

Full Code

use std::os::fd::{FromRawFd, IntoRawFd};
use std::fs::{File as StdFile, OpenOptions, metadata};
use std::io::Error;
use std::mem::ManuallyDrop;

/// A type that represents a file handle
struct File {
    /// File name
    name: ManuallyDrop<String>,
    /// File descriptor
    fd: ManuallyDrop<i32>,
}

impl File {
    /// A constructor that opens a file and returns a `File` instance
    fn open(name: &str) -> Result<File, Error> {
        // Open the file with read and write permissions using `OpenOptions`
        let file: StdFile = OpenOptions::new()
            .read(true)
            .write(true)
            .open(name)?;

        // Obtain the file descriptor
        let fd: i32 = file.into_raw_fd();

        // Return a `File` instance
        Ok(File {
            name: ManuallyDrop::new(name.to_string()),
            fd: ManuallyDrop::new(fd),
        })
    }

    /// An explicit destructor that closes the file and returns any error
    fn close(mut self) -> Result<(), Error> {
        // Use `std::mem::replace` to replace the `name` field with an empty string, and keep the original value in `name`
        let name =
            std::mem::replace(&mut self.name, ManuallyDrop::new("".to_string()));

        // Use `std::mem::replace` to replace the `fd` field with an invalid value (-1), and keep the original value in `fd`
        let fd =
            std::mem::replace(&mut self.fd, ManuallyDrop::new(-1));

        // Print
        println!("Closing file: {:?} with fd: {:?}", name, fd);

        // Convert the fd back into a `File` using `FromRawFd`
        let file: std::fs::File = unsafe {
            std::fs::File::from_raw_fd(*fd) // `fd` must be dereferenced first
        };

        // Flush file data to disk
        file.sync_all()?;

        // Truncate the file to 0 bytes
        file.set_len(0)?;

        // Flush the file again
        file.sync_all()?;

        // Drop the file instance; it will close the file automatically
        drop(file);

        // Return success
        Ok(())
    }
}

// Implement `Drop` for code that runs when the value leaves scope
impl Drop for File {
    fn drop(&mut self) {
        // Use `ManuallyDrop::take` to take the `name` field value and check whether it is an empty string
        let name = unsafe { ManuallyDrop::take(&mut self.name) };

        // Use `ManuallyDrop::take` to take the `fd` field value and check whether it is an invalid value
        let fd = unsafe { ManuallyDrop::take(&mut self.fd) };

        // Print
        println!("Dropping file: {:?} (fd: {:?})", name, fd);

        // If the `fd` field is not the invalid value, the file has not been closed or dropped yet, so perform the drop operation
        if fd != -1 || !name.is_empty() {
            let file = unsafe { std::fs::File::from_raw_fd(fd) };
            // Drop it
            drop(file);
        }
    }
}

fn main() {
    // Create a file named "test.txt" and write some content to it
    std::fs::write("test.txt", "Hello, world!").unwrap();

    // Open the file and obtain a `File` instance
    let file: File = File::open("test.txt").unwrap();

    // Print the file name and fd (this needs to change)
    println!("File name: {}, fd: {}", *file.name, *file.fd);

    // Close the file and handle any error
    match file.close() {
        Ok(()) => println!("File closed successfully"),
        Err(e) => println!("Error closing file: {}", e),
    }

    // Check the file size after closing
    let metadata = metadata("test.txt").unwrap();
    println!("File size: {} bytes", metadata.len());
}

Choosing Between the Three Solutions

Which of these three solutions you choose depends on the actual situation, and usually the second one is the best. But if there are so many fields that unwrap becomes too noisy, you need to consider other options.

If the code is simple enough that you can easily verify its safety, then the third ManuallyDrop solution is also a very good choice.

[Advanced Rust] 2.7. API Design Principles of Flexibility Pt.3 - Borrowed vs Owned, Cow Type, and Fallible and Blocking Destruc…

SomeB1oody — Fri, 07 Aug 2026 16:33:48 +0000

Full title: [Advanced Rust] 2.7. API Design Principles of Flexibility Pt.3 - Borrowed vs Owned, Cow Type, and Fallible and Blocking Destructors with Solutions

2.7.1. Borrowed vs. Owned

For almost every function, trait, and type in Rust, we need to decide:

Should it own the data?
Or should it hold a reference to the data?

If your code needs ownership of the data, then it must store owned data. When your code owns the data, you must require the caller to provide owned data rather than a reference or a clone. That lets the caller control allocation and clearly see the cost of using the interface.

If the code does not need to own the data, then it should operate on references to the data. But there are exceptions: for “small types” such as i32, bool, and f64, the cost of storing and copying them directly is basically the same as storing them by reference.

Most of these small types implement Copy, but not every Copy type can be called a “small type.” For example, [u8; 114514] implements Copy, but because it has so many elements, storing and copying it is too expensive, so passing by reference is recommended.

`Cow` Type

Sometimes we cannot tell whether code owns the data, because it depends on runtime conditions. The Cow type is a perfect fit for this situation.

Cow allows you to hold either a reference or an owned value when needed. If an owned value is required while only a reference is available, Cow uses the ToOwned trait to create an owned value behind the scenes, usually by cloning. In general, we use Cow in return types to express functions that may sometimes allocate memory.

In other words:

If the data does not need to be modified, Cow can borrow the existing data and avoid extra allocation.
If the data needs to be modified, Cow will clone the data to gain ownership and then modify it.

Example:

use std::borrow::Cow;

fn process_data(data: Cow<str>) {
    if data.contains("invalid") {
        // If it contains "invalid", it needs to be modified, and modification requires ownership first
        let owned_data = data.into_owned();

        // ...some modification operations
        println!("{}", owned_data); // final output
    } else {
        // No modification here, so we only need to read it
        println!("Data: {}", data);
    }
}

fn main() {
    let input1 = "Hello, world!";
    process_data(Cow::Borrowed(input1));

    let input2 = "This is invalid data".to_string();
    process_data(Cow::Owned(input2));
}

I wrote the logic of process_data in the comments
In main, input1 does not contain "invalid" and requires no modification, so it only needs to be read. Therefore, there is no need to pass an owned value; passing a reference (Cow::Borrowed(input1)) is enough
input2 contains "invalid" and needs to be modified, so an owned value (Cow::Owned(input2)) should be passed

When Should You Consider Taking Ownership of Data?

Sometimes reference lifetimes make an interface especially complicated and hard to use. If users encounter compilation problems while using it, that is a sign that we need to own the data, even if it is not strictly necessary.

If you decide to do that, the first thing to consider is converting easy-to-clone or performance-insensitive data into owned values, instead of mechanically heap-allocating large chunks of data content. That can avoid performance problems and improve usability.

2.7.2. Fallible and Blocking Destructors

Destructors, that is, the Drop trait, are special methods that are called automatically when an object reaches the end of its lifetime, and are used to release resources.

Destructors are generally not allowed to fail and are expected to be non-blocking, but there are exceptions:

Releasing resources may require closing a network connection or writing to a log file, and these operations may fail
The drop method may need to perform blocking work, such as waiting for a thread to finish or waiting for an async task to complete

Problems with I/O Operations and Destructors

In I/O-related types such as files and network connections, resource management is very important, and the Drop mechanism (destructors) can ensure that cleanup operations are performed correctly when the object is dropped, avoiding resource leaks.

More specifically:

File operations: when a file object is dropped, Drop needs to ensure that all data has been written to disk to prevent data loss
Network connections: when a TcpStream or UdpSocket is dropped, Drop needs to close the connection properly to prevent resource leaks
Database connections: when a database connection object goes out of scope, Drop needs to disconnect and free server-side resources

The problem is that in Rust's Drop mechanism, if an error occurs while performing cleanup, there is no direct way to return a Result for the caller to handle. The only thing you can do is trigger panic! and crash the program.

Problems with Async Code and Destructors

Async code has a similar problem. In Rust's async programming (async/await), we often want to perform cleanup operations in Drop, such as:

Closing a database connection
Flushing and closing a file
Closing a WebSocket or TCP connection
Releasing a lock or resource

However, async code may be running while other tasks are still pending, for example:

A network I/O operation has not finished
Other async tasks are still waiting for a signal
The current task needs await, but Drop cannot await

The problem is that Rust's Drop trait cannot await, because drop() is not async:

trait Drop {
    fn drop(&mut self);
}

drop() cannot await, which means it cannot perform async cleanup tasks such as closing a database connection asynchronously
But async cleanup usually needs await, for example:

async fn close_connection() {
    // Simulate closing a database connection
    println!("Closing database connection...");
}

This code cannot be called directly from Drop, because Drop cannot await.

A common approach is to start another async executor inside drop() to run the cleanup code, for example:

impl Drop for MyAsyncResource {
    fn drop(&mut self) {
        tokio::spawn(async {
            self.close().await;
        });
    }
}

This allows you to run async tasks inside drop()
But there is a problem: if drop() happens when main() is ending or after other async tasks finish, the task spawned inside drop() may not finish before the program exits

For These Two Problems

For these two problems, there is no perfect solution. The best we can do is use Drop to clean up as much as possible. If cleanup produces an error, at least we tried, and we can only ignore the error and continue.

If an executor is still available, we can try to create a Future to perform cleanup, but if the Future will never be allowed to run, there is nothing we can do.

A Small Extension: About `Future`

In Rust's async model, a Future represents a value that will be produced by an asynchronous computation:

async fn cleanup() {
    println!("Cleaning up...");
}

This cleanup() function returns a Future; it does not run immediately and instead must be polled by an executor

struct MyResource;

impl Drop for MyResource {
    fn drop(&mut self) {
        let fut = async {
            println!("Cleaning up...");
        };

        // A `Future` is created here, but nobody executes it!
    }
}

A Future is created inside drop(), but it will not run by itself; an executor must drive it
If no executor is available, the Future will never run, and the cleanup task cannot complete

The Solution — Explicit Destructors

Now that we have covered Future, let us return to solving these two problems.

If users do not want to leave behind “dangling threads,” we can provide an explicit destructor. Such a destructor is usually a method that takes ownership of self and exposes any errors (using Result<T, E>) or asynchrony (using async fn), both of which are related to destruction.

“Dangling threads” refers to the following:

Resources such as threads, database connections, or file handles are not cleaned up properly, so they are still occupied when the process exits

For example, some background tasks may not terminate normally and may continue running, leak resources, or prevent the process from exiting

“Explicit destructor” means:

Because Rust's Drop cannot return Result<T, E> and also cannot be async (since drop() cannot await), it cannot handle async cleanup or errors

Therefore, we can provide an explicit close() or shutdown() method that users call manually to ensure resources are released correctly and to support Result or async error handling

Example:

use std::os::fd::{FromRawFd, IntoRawFd};
use std::fs::{File as StdFile, OpenOptions, metadata};
use std::io::Error;

/// A type that represents a file handle
struct File {
    /// File name
    name: String,
    /// File descriptor
    fd: i32,
}

impl File {
    /// A constructor that opens a file and returns a `File` instance
    fn open(name: &str) -> Result<File, Error> {
        // Open the file with read and write permissions
        let file: StdFile = OpenOptions::new()
            .read(true)
            .write(true)
            .open(name)?;

        // Take ownership of the file descriptor (do not use as_raw_fd:
        // dropping StdFile would close the fd while we still hold a copy)
        let fd: i32 = file.into_raw_fd();

        // Return a `File` instance
        Ok(File {
            name: name.to_string(),
            fd,
        })
    }

    /// An explicit destructor that closes the file and returns any error
    fn close(self) -> Result<(), Error> {
        // Convert the fd back into a `File` using `FromRawFd`
        let file: std::fs::File = unsafe {
            std::fs::File::from_raw_fd(self.fd)
        };

        // Flush file data to disk
        file.sync_all()?;

        // Truncate the file to 0 bytes
        file.set_len(0)?;

        // Flush the file again
        file.sync_all()?;

        // Drop the file instance, which will close the file automatically
        drop(file);

        // Return success
        Ok(())
    }
}

fn main() {
    // Create a file named "test.txt" and write some content into it
    std::fs::write("test.txt", "Hello, world!").unwrap();

    // Open the file and obtain a `File` instance
    let file: File = File::open("test.txt").unwrap();

    // Print the file name and fd
    println!("File name: {}, fd: {}", file.name, file.fd);

    // Close the file and handle any error
    match file.close() {
        Ok(()) => println!("File closed successfully"),
        Err(e) => println!("Error closing file: {}", e),
    }

    // Check the file size after closing
    let metadata = metadata("test.txt").unwrap();
    println!("File size: {} bytes", metadata.len());
}

I wrote the important details in the code comments
close is an explicit destructor: it closes the file and returns any error, takes self as its parameter, and returns a Result
In main, we explicitly call the destructor and use match for pattern matching

A Small Note

Explicit destructors need to be highlighted in the documentation.

[Advanced Rust] 2.6. API Design Principles of Flexibility Pt.2 - Object Safety, API Design, and Generic Trait Methods

SomeB1oody — Fri, 07 Aug 2026 00:19:39 +0000

2.6.1. Object Safety

When defining a trait, whether it is object-safe is also part of the unstated contract.

Object safety is a concept in Rust related to trait objects. It determines whether a trait can be dynamically dispatched, that is, whether it can be used in the form of dyn Trait.

Traits That Are Object-Safe Must Satisfy the Following Conditions (Based on RFC 255)

All supertraits must also be object-safe

If a trait inherits from other traits, then those supertraits must also be object-safe.
It must not require Sized

A trait cannot use Sized as a supertrait, meaning it cannot contain a Self: Sized bound, because the size of a trait object is unknown at compile time.
It cannot have associated constants.
It cannot have associated types with type parameters.
All associated functions (methods) must satisfy one of the following rules:
- Dispatchable functions:
 - They cannot have any type parameters, though lifetime parameters are allowed.
 - They must be methods, and Self may only appear in receiver positions such as:
 - &self
 - &mut self
 - Box<Self>
 - Rc<Self>
 - Arc<Self>
 - Pin (where P is one of the types above)
 - They cannot require Self: Sized, otherwise the trait would only be usable for types with known size and object safety would be broken.

Explicitly non-dispatchable functions:
- They may return Self, but such functions must require Self: Sized, so they cannot be called on trait objects and can only be used with concrete types.

If you cannot remember all of the above, just remember object safety describes whether a trait can be safely turned into a trait object.

What Object Safety Does

If a trait is object-safe, meaning it satisfies all of the conditions above, then we can use dyn Trait to treat different types that implement the trait as a single generic type.

If it is not object-safe, the compiler will prevent you from using dyn Trait.

Object Safety and API Design

When designing APIs, it is recommended to make traits object-safe, even if that slightly reduces convenience, because it provides new ways to use the trait and increases flexibility.

Let's look at an example:

Suppose we have an Animal trait with two methods: name and speak. The name method returns &str and represents the animal's name. The speak method prints an onomatopoeic sound for the animal and returns nothing. We have two structs, Dog and Cat, and both implement this trait.

trait Animal {
    fn name(&self) -> &str;
    fn speak(&self);
}

struct Dog {
    name: String,
}

impl Animal for Dog {
    fn name(&self) -> &str {
        &self.name
    }

    fn speak(&self) {
        println!("Woof!");
    }
}

struct Cat {
    name: String,
}

impl Animal for Cat {
    fn name(&self) -> &str {
        &self.name
    }

    fn speak(&self) {
        println!("Meow!");
    }
}

fn main() {
    let dog = Dog { name: String::from("George") };
    let cat = Cat { name: String::from("Hamilton") };

    let animals: Vec<&dyn Animal> = vec![&dog, &cat];

    for animal in animals {
        println!("The name of this animal is {}", animal.name());
        animal.speak();
    }
}

The Animal trait is object-safe because it does not return Self or use generic parameters
So we can use it to create a trait object: let animals: Vec<&dyn Animal> = vec![&dog, &cat];, and this Vec effectively becomes a trait-object collection

Output:

The name of this animal is George
Woof!
The name of this animal is Hamilton
Meow!

Next, let's make a small change to the previous example:

We add a new clone method to the Animal trait, and it returns a Self value

trait Animal {
    fn name(&self) -> &str;
    fn speak(&self);
    fn clone(&self) -> Self;
}

struct Dog {
    name: String,
}

impl Animal for Dog {
    fn name(&self) -> &str {
        &self.name
    }

    fn speak(&self) {
        println!("Woof!");
    }

    fn clone(&self) -> Self {
        todo!()
    }
}

struct Cat {
    name: String,
}

impl Animal for Cat {
    fn name(&self) -> &str {
        &self.name
    }

    fn speak(&self) {
        println!("Meow!");
    }

    fn clone(&self) -> Self {
        todo!()
    }
}

fn main() {
    let dog = Dog { name: String::from("George") };
    let cat = Cat { name: String::from("Hamilton") };

    let animals: Vec<&dyn Animal> = vec![&dog, &cat];

    for animal in animals {
        println!("The name of this animal is {}", animal.name());
        animal.speak();
    }
}

Output:

error[E0038]: the trait `Animal` is not dyn compatible
  --> src/main.rs:47:27
   |
47 |     let animals: Vec<&dyn Animal> = vec![&dog, &cat];
   |                           ^^^^^^ `Animal` is not dyn compatible
   |
note: for a trait to be dyn compatible it needs to allow building a vtable
      for more information, visit <https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility>
  --> src/main.rs:4:24
   |
 1 | trait Animal {
   |       ------ this trait is not dyn compatible...
...
 4 |     fn clone(&self) -> Self;
   |                        ^^^^ ...because method `clone` references the `Self` type in its return type
   = help: consider moving `clone` to another trait
   = help: the following types implement `Animal`:
             Dog
             Cat
           consider defining an enum where each variant holds one of these types,
           implementing `Animal` for this new enum and using it instead

After adding clone, Animal is no longer object-safe because clone violates the rule that the return type cannot be Self. A dyn Trait is called through a pointer, while Self refers to the concrete implementation type, whose size is unknown at compile time.

For example:

fn main() {
    let dog = Dog { name: "Ver".to_string() };
    let dog2 = dog.clone(); // this is fine because Self = Dog

    let animal: Box<dyn Animal> = Box::new(Dog { name: "Ver".to_string() });
    let animal2 = animal.clone(); // compile error: the concrete size is unknown at compile time
}

If I want to keep Animal object-safe while also keeping the clone method, what should I do?

Going back to the first section of this article, look at explicitly non-dispatchable functions: they may return Self, but such functions must require Self: Sized, so they cannot be called on trait objects and can only be used with concrete types.

According to that requirement, we can change the code like this:

trait Animal {
    fn name(&self) -> &str;
    fn speak(&self);
    fn clone(&self) -> Self
    where
        Self: Sized;
}

// ...the rest of the code stays the same

Output:

The name of this animal is George
Woof!
The name of this animal is Hamilton
Meow!

That way, there is no error.

Note that clone can now only be called on concrete types; otherwise it will fail:

fn main() {
    let dog = Dog { name: String::from("George") };
    let cat = Cat { name: String::from("Hamilton") };

    let animals: Vec<&dyn Animal> = vec![&dog, &cat];

    for animal in animals {
        println!("The name of this animal is {}", animal.name());
        animal.speak();
        animal.clone();  // this will fail because `animal` is `&dyn Animal`, not a concrete type
    }
}

Output:

error: the `clone` method cannot be invoked on a trait object
  --> src/main.rs:54:16
   |
 6 |         Self: Sized;
   |               ----- this has a `Sized` requirement
...
54 |         animal.clone();  // this will fail because `animal` is `&dyn Animal`, not a concrete type
   |                ^^^^^

Because the trait method declares a Self: Sized requirement on the clone return value, and &dyn Animal does not have a known concrete size, the method cannot be called.

Of course, it definitely works on a concrete type:

fn main() {
    let dog = Dog { name: String::from("George") };
    let dog_clone = dog.clone(); // compiles successfully
}

Generic Trait Methods and API Design

Put Generic Parameters on the Trait

If a trait must have a generic method, consider putting the generic parameter on the trait itself.

Example:

use std::collections::HashSet;
use std::hash::Hash;

trait Container<T> {
    fn contains(&self, item: &T) -> bool;
}

impl<T> Container<T> for Vec<T>
where
    T: PartialEq,
{
    fn contains(&self, item: &T) -> bool {
        self.iter().any(|x| x == item)
    }
}

impl<T> Container<T> for HashSet<T>
where
    T: Eq + Hash,
{
    fn contains(&self, item: &T) -> bool {
        HashSet::contains(self, item)
    }
}

fn main() {
    // Create `Vec<T>` and `HashSet<T>` instances
    let vec_container: Box<dyn Container<i32>> = Box::new(vec![1, 2, 3]);
    let hashset_container: Box<dyn Container<i32>> =
        Box::new(vec![4, 5, 6].into_iter().collect::<HashSet<_>>());

    // Call the contains method
    println!("Vector contains 2: {}", vec_container.contains(&2));
    println!("HashSet contains 4: {}", hashset_container.contains(&4));
}

There is a trait called Container, and it has a method called contains. The implementation of contains will definitely need a generic parameter. But to preserve object safety, we cannot add type parameters to the method itself.
So we move the generic parameter to the trait rather than to the trait method, namely Container<T>, where T is the generic parameter
In this way, we can implement the Container trait for different container types, and each implementation has its own specific element type
For example, in the code above we implemented Container for Vec<T> and HashSet<T>

Output:

Vector contains 2: true
HashSet contains 4: true

Use Dynamic Dispatch

Another option is to consider whether the generic parameter can be expressed with dynamic dispatch in order to keep the trait object-safe.

Example:

Suppose we have a Foo trait with a generic method bar that takes a generic parameter T:

trait Foo {
    fn bar<T>(&self, x: T);
}

This trait is not object-safe, because object safety requires trait methods to have no generic parameters. The reason is that generic methods rely on monomorphization: Rust needs to determine the concrete type of T at compile time and generate different code for different Ts, while dyn Foo uses runtime dynamic dispatch, so the compiler cannot pre-generate code for every possible T.

But there is a workaround: replace the generic parameter with a dynamically dispatched form, like this:

trait Foo {
    fn bar(&self, x: &dyn Debug);
}

Then the bar method can call x's Debug behavior through dynamic dispatch (via the vtable) without needing the concrete type at compile time, which keeps Foo object-safe.

Example:

trait Foo {
    fn bar<T>(&self, x: T); // generic method, so the trait is not object-safe
}

struct MyStruct;

impl Foo for MyStruct {
    fn bar<T>(&self, x: T) {
        println!("Received a value!");
    }
}

fn main() {
    let obj = MyStruct;

    let obj_ref: &dyn Foo = &obj; // compile error: the trait `Foo` is not dyn compatible
    obj_ref.bar(42);  // cannot call this because `T` must be known at compile time
}

This will not work, so we need to switch to a dynamic-dispatch version:

use std::fmt::Debug;

trait Foo {
    fn bar(&self, x: &dyn Debug); // use a trait object instead of a generic parameter to keep it object-safe
}

struct MyStruct;

impl Foo for MyStruct {
    fn bar(&self, x: &dyn Debug) {
        println!("Received a value: {:?}", x);
    }
}

fn main() {
    let obj = MyStruct;

    let obj_ref: &dyn Foo = &obj; // now it can be used as a trait object
    obj_ref.bar(&42);  // output: Received a value: 42
    obj_ref.bar(&"Hello"); // output: Received a value: "Hello"
}

The Cost of Object Safety

How much do we have to give up in order to achieve object safety?

Think about how users will use your trait; if they are likely to treat it as a trait object, then do your best to make it object-safe

[Advanced Rust] 2.5. API Design Principles of Flexibility Pt.1 - Contracts and More Flexible Interfaces with Generic Parameters

SomeB1oody — Thu, 06 Aug 2026 06:53:13 +0000

2.5.1. Code Contracts

Your code, whether explicitly or implicitly, contains a contract.

A contract has two sides:

A contract is a requirement, which is a restriction on how the code is used
A contract is a promise, which is a guarantee about how the code behaves

When designing APIs, there is a useful rule of thumb: avoid imposing unnecessary restrictions, and only make promises you can keep.

Why?

Adding restrictions or removing promises requires a major semantic version change and may break other code
When you first design an API, loosening restrictions and later adding extra promises is usually backward-compatible

2.5.2. Restrictions and Promises

Common forms of restrictions in Rust are:

Trait bounds
Argument types

Common forms of promises are:

Trait implementations
Return types

Some Examples

Let's look at an API evolving through three versions:

fn frobnicate(s: String) -> String

The first version takes a String and returns a String
Its contract is that the caller performs allocation (because both the parameter and return value are owned, allocation is inevitable), and its promise is that it returns an owned String
The problem with this function is that, without changing the signature, it cannot later be turned into a “no-allocation” function, because both the argument and return value are owned

fn frobnicate(s: &str) -> Cow<'_, str>

The second version relaxes the contract a bit
Its contract is that it accepts only a string reference, and its promise is that it returns either a string reference or an owned String, namely the Cow type
This version is still somewhat rigid. For example, the argument is &str; if I pass in a String, I still have to convert it first. Also, because the return value is Cow, it cannot return string-owning types other than String and &str (for example, OsString)

fn frobnicate<T: AsRef<str>>(s: T) -> T

The third version relaxes the contract further
Now both the parameter and the return value only require a type that implements AsRef<str>, that is, a type that can produce a string reference

These three functions all take a string and return a string; the only difference is the contract. None of them is better or worse than the others, only stricter or looser. When designing an API, carefully plan the contract, because changing it will cause breaking changes.

Let's look at the full example:

use std::borrow::Cow;

fn frobnicate<T: AsRef<str>>(s: T) -> T {
    s
}

fn main() {
    let string: String = String::from("example");
    let borrowed: &str = "hello";
    let cow: Cow<str> = Cow::Borrowed("world");

    let result1: &str = frobnicate::<&str>(string.as_ref());
    let result2: &str = frobnicate::<&str>(borrowed);
    let result3: Cow<str> = frobnicate(cow);

    println!("Result1: {:?}", result1);
    println!("Result2: {:?}", result2);
    println!("Result3: {:?}", result3);
}

Whether it is String, &str, or Cow<str> (which is essentially also &str), this function can accept it (String needs to be converted to &str first with as_ref) and return a value (the return value can also be a different type)

Output:

Result1: "example"
Result2: "hello"
Result3: "world"

2.5.3. Use Generic Parameters to Make Interfaces More Flexible

We can loosen function requirements by using generics. In most cases, it is worthwhile to use generics instead of concrete types.

Example of Using Generic Parameters

Example:

fn print_as_str<T: AsRef<str>>(s: T) {
    println!("{}", s.as_ref());
}

fn main() {
    let s: String = String::from("hello");
    let r: &str = "world";

    print_as_str(s);  // calls `print_as_str::<String>`
    print_as_str(r);  // calls `print_as_str::<&str>`
}

The print_as_str function accepts a parameter that implements AsRef<str>
This function is generic, which means it is monomorphized for every type that implements AsRef<str> that you use with it. For example, if you call it with a String and a &str, you will have two copies of the function in your binary, print_as_str::<String> and print_as_str::<&str>, and each call will invoke the corresponding function

Note: the advantage of monomorphization is that it avoids runtime overhead, while the drawback is that the compiler generates one function for each input type, increasing binary size.

If you do not want multiple copies of a function in the binary, you can use dynamic dispatch:

fn print_as_str(s: &dyn AsRef<str>) {
    println!("{}", s.as_ref());
}

fn main() {
    let s: String = String::from("hello");
    let r: &str = "world";

    print_as_str(&s);  // pass a trait object of type `&dyn AsRef<str>`
    print_as_str(&r);  // pass a trait object of type `&dyn AsRef<str>`
}

This function is no longer generic; it accepts a trait object that can be any type implementing AsRef<str>
This means it uses dynamic dispatch at runtime to call as_ref, and you will only have one copy of the function in your binary

See 1.15.4. Dynamic Dispatch for more details. Note that dynamic dispatch has some runtime overhead compared with monomorphization, but it is very small.

Do Not Take Generic Parameters to the Extreme

Do not overuse generic parameters; it depends on the specific situation.

Whether to use generics (or trait objects) or concrete types depends on whether users will reasonably and frequently want to substitute other types for the concrete type you initially chose. If so, making the parameter generic is more appropriate.

The Trade-Off Between Monomorphization and Dynamic Dispatch

The advantage of monomorphization is that it avoids runtime overhead; the drawback is that the compiler generates one function for each input type, increasing binary size.

If you are worried that the generated binary will be too large, you can use dynamic dispatch. Although dynamic dispatch has some runtime overhead compared with monomorphization, it is very small.

In high-performance applications, using dynamic dispatch inside frequently executed hot loops can become a fatal issue!

Dynamic dispatch can only be used with simple trait bounds (a single trait bound), such as T: AsRef<str> or impl AsRef<str>. Because Rust cannot create a vtable for complex trait bounds (for example, two or more trait bounds; see 1.15.5. vtable), dynamic dispatch cannot be used there.

For parameters taken by reference (dyn Trait is not Sized, so a wide pointer is needed to use them), dynamic dispatch can be used instead of generic parameters.

Let's look at an example:

// Generic function, static dispatch
fn process<T>(value: T) {
    println!("processing T");
}

This is the generic function form

// Dynamic dispatch
trait Processable {
    fn process(&self);
}

struct TypeA;
impl Processable for TypeA {
    fn process(&self) {
        println!("processing TypeA");
    }
}

fn process_trait_object(value: &dyn Processable) {
    value.process();
}

This is the dynamic-dispatch form

What if we put both together—how can we tell which one uses static dispatch and which one uses dynamic dispatch?

// Generic function, static dispatch
fn process<T>(value: T) {
    println!("processing T");
}

// Dynamic dispatch
trait Processable {
    fn process(&self);
}

struct TypeA;
impl Processable for TypeA {
    fn process(&self) {
        println!("processing TypeA");
    }
}

struct TypeB;
impl Processable for TypeB {
    fn process(&self) {
        println!("processing TypeB");
    }
}

fn process_trait_object(value: &dyn Processable) {
    value.process();
}

fn main() {
    let a = TypeA;
    let b = TypeB;

    process_trait_object(&a); // dynamic dispatch
    process_trait_object(&b); // dynamic dispatch

    process(&a);  // static dispatch
    process(&b);  // static dispatch

    process(&a as &dyn Processable); // static dispatch
    process(&b as &dyn Processable); // static dispatch
}

Calls to process_trait_object use dynamic dispatch
Calls to process use static dispatch

The last two process calls are a little special. The argument passed in is &dyn Processable rather than a concrete type (because as &dyn Processable is used). The compiler will treat it as a type and monomorphize it, that is, it will monomorphize the code into:

fn process(value: &dyn Processable) {
    println!("processing T");
}

This part is still static dispatch because T = &dyn Processable is determined at compile time.

At runtime, because &dyn Processable does not have a concrete static type behind the fat pointer, any method call through that trait object would look up the implementation via the vtable. In this particular process example, however, the function body never calls a method on value, so no vtable dispatch occurs; monomorphization still produces a single process::<&dyn Processable> specialization at compile time.

But overall, we still consider the call to the generic process function itself to be static dispatch.

Output:

processing TypeA
processing TypeB
processing T
processing T
processing T
processing T

When using generic parameters, the caller can always choose dynamic dispatch by passing a trait object (process(&a as &dyn Processable);).

The reverse is not true: if you accept a trait object as a parameter, then the caller must provide a trait object and cannot use static dispatch.

How Should APIs Consider Generic Parameters?

We can start by writing interfaces with concrete types and then gradually convert them to generics. That approach works, but it is not necessarily backward-compatible.

Example:

fn foo(v: &Vec<usize>) {
    // ...
}

fn main() {
    let iter = vec![1, 2, 3].into_iter();
    foo(&iter.collect());
}

In main, the into_iter method converts the Vec into an IntoIter<usize>
iter.collect() then converts iter from IntoIter<usize> back into Vec<usize>, and adding & in front of it makes it fully match the parameter type required by foo Here, collect knows to collect iter into a Vec<usize> because the compiler knows that foo accepts &Vec<usize>

Now let's rewrite foo using a trait bound:

fn foo(v: impl AsRef<[usize]>) {
    // ...
}

fn main() {
    let iter = vec![1, 2, 3].into_iter();
    foo(&iter.collect());
}

This program does not compile because the compiler does not know what type collect should collect iter into. The compiler only knows that foo's parameter is AsRef<[usize]>, but many types satisfy that, such as Vec<usize> and &[usize]

Output:

error[E0283]: type annotations needed
  --> src/main.rs:7:15
   |
 7 |     foo(&iter.collect());
   |               ^^^^^^^ cannot infer type of the type parameter `B` declared on the method `collect`
   |
   = note: the type must implement `FromIterator<i32>`
help: consider specifying the generic argument
   |
 7 |     foo(&iter.collect::<Vec<_>>());
   |                      ++++++++++

To solve this, the caller must explicitly tell collect what type to collect into:

fn foo(v: impl AsRef<[usize]>) {
    // ...
}

fn main() {
    let iter = vec![1, 2, 3].into_iter();
    foo(&iter.collect::<Vec<usize>>());
}

[Advanced Rust] 2.4. API Design Principles of Unsurprising Pt.4 - Ergonomic Trait Implementations, Wrapper Types, and Borrow Tr…

SomeB1oody — Tue, 04 Aug 2026 22:26:38 +0000

Full title: [Advanced Rust] 2.4. API Design Principles of Unsurprising Pt.4 - Ergonomic Trait Implementations, Wrapper Types, and Borrow Trait

2.4.1. Ergonomic Trait Implementations

Rust does not automatically provide implementations for references to a type that implements a given trait.

For example, if Bar implements Trait, you still cannot pass &Bar to fn foo<T: Trait>(t: T). That is because implementing Trait for Bar does not automatically implement Trait for &Bar.

Example:

trait Trait {
    fn name(&self) -> &'static str;
}

struct Bar;

impl Trait for Bar {
    fn name(&self) -> &'static str {
        "Bar"
    }
}

fn foo<T: Trait>(t: T) {
    println!("{}", t.name());
}

fn main() {
    let bar = Bar;
    foo(bar); // OK

    let bar_ref = &Bar;
    foo(bar_ref); // error[E0277]: the trait bound `&Bar: Trait` is not satisfied
}

If a user sees that a trait method only accepts &self (and not self or &mut self), they may still be surprised that &Bar does not satisfy T: Trait. That does not satisfy the unsurprising principle.

To solve this, when defining a new trait, we usually provide corresponding blanket implementations for the following (when the trait methods allow it—typically methods that take &self or &mut self):

&T where T: Trait + ?Sized
&mut T where T: Trait + ?Sized
Box<T> where T: Trait + ?Sized

Continuing the example above, to prevent foo(bar_ref); from failing, we need to manually provide a Trait implementation for &T:

impl<T: Trait + ?Sized> Trait for &T {
    fn name(&self) -> &'static str {
        (**self).name()
    }
}

Note: if a trait method takes `self` by value (consuming ownership), you generally cannot provide a blanket `impl Trait for &T` that forwards to `T`, because a shared reference cannot move out of `T`.

For iterators, if a type can be iterated, then its references should also provide the corresponding trait implementations. In other words: for any iterable type, consider implementing IntoIterator for &MyType and &mut MyType. That way, we can use borrowed values directly in loops, which matches user expectations.

Example:

struct MyCollection {
    items: Vec<i32>,
}

// Implement IntoIterator for MyCollection
impl IntoIterator for MyCollection {
    type Item = i32;
    type IntoIter = std::vec::IntoIter<Self::Item>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.into_iter()
    }
}

// Implement IntoIterator for &MyCollection
impl<'a> IntoIterator for &'a MyCollection {
    type Item = &'a i32;
    type IntoIter = std::slice::Iter<'a, i32>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.iter()
    }
}

// Implement IntoIterator for &mut MyCollection
impl<'a> IntoIterator for &'a mut MyCollection {
    type Item = &'a mut i32;
    type IntoIter = std::slice::IterMut<'a, i32>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.iter_mut()
    }
}

fn main() {
    let mut collection = MyCollection { items: vec![1, 2, 3] };

    // Iterate by taking ownership
    for item in collection {
        println!("Owned: {}", item);
    }

    let collection = MyCollection { items: vec![4, 5, 6] };

    // Iterate by immutable borrow
    for item in &collection {
        println!("Borrowed: {}", item);
    }

    let mut collection = MyCollection { items: vec![7, 8, 9] };

    // Iterate by mutable borrow
    for item in &mut collection {
        *item *= 2;
    }

    // Make sure the modification took effect
    for item in &collection {
        println!("Modified: {}", item);
    }
}

2.4.2. Wrapper Types

Rust does not have inheritance in the traditional object-oriented sense, but Deref and AsRef provide something similar.

For example, if you have a value of type T and it satisfies Deref<Target = U>, then you can directly call methods from U on a value of type T.

Example:

use std::ops::Deref;

// Define a wrapper type Wrapper that stores a String internally
struct Wrapper(String);

// Implement Deref so that Wrapper dereferences to String
impl Deref for Wrapper {
    type Target = String;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

fn main() {
    let my_wrapper = Wrapper(String::from("Hello, Rust!"));

    // Because Wrapper implements Deref<Target = String>,
    // we can call String methods directly without manual dereferencing
    let len = my_wrapper.len();
    let uppercased = my_wrapper.to_uppercase();

    println!("Length: {}", len);
    println!("Uppercased: {}", uppercased);
}

Output:

Length: 12
Uppercased: HELLO, RUST!

If you provide a relatively transparent type such as Arc<T>, then implementing Deref lets your wrapper type automatically dereference to the inner type at the point of use, so its methods can be called directly.

If accessing the inner type does not require any complicated or potentially inefficient logic, you should consider implementing AsRef, so users can easily use &WrapperType as &InnerType.

For most wrapper types, you should also implement From<InnerType> for the wrapper and From<Wrapper> for the inner type where possible (which also gives you Into for free), so users can easily add or remove the wrapper.

Example:

use std::ops::Deref;
use std::sync::Arc;

// Define a wrapper type
struct Wrapper(Arc<String>);

// Implement Deref to allow transparent access to the inner String
impl Deref for Wrapper {
    type Target = String;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

// Implement AsRef<String> so users can obtain a `&String`
impl AsRef<String> for Wrapper {
    fn as_ref(&self) -> &String {
        &self.0
    }
}

// Implement From<String> so users can easily create a Wrapper
impl From<String> for Wrapper {
    fn from(s: String) -> Self {
        Wrapper(Arc::new(s))
    }
}

// Implement From<Wrapper> for String so users can convert the Wrapper back into a String (by cloning)
impl From<Wrapper> for String {
    fn from(w: Wrapper) -> Self {
        (*w).clone() // Deref allows Wrapper to be used as if it were a String
    }
}

fn main() {
    let wrapped = Wrapper::from("Hello, Rust!".to_string());

    // Because Deref is implemented, we can call String methods directly
    println!("Length: {}", wrapped.len());
    println!("Uppercased: {}", wrapped.to_uppercase());

    // Use AsRef to obtain a &String reference
    let str_ref: &String = wrapped.as_ref();
    println!("AsRef: {}", str_ref);

    // Convert back to String through Into (cloning the string)
    let original: String = wrapped.into();
    println!("Converted back: {}", original);
}

Output:

Length: 12
Uppercased: HELLO, RUST!
AsRef: Hello, Rust!
Converted back: Hello, Rust!

2.4.3. `Borrow` Trait

The Borrow trait is somewhat similar to Deref and AsRef, but it is aimed at a narrower use case and is more specialized.

The Borrow trait allows callers to provide any of several essentially identical variants of a unified type. These variants are called equivalents.

Note: The Borrow trait should only be used when your type is essentially equivalent to another type. In other words, Borrow is for “equivalent” cases, while AsRef and Deref are for “acts as” cases.

For example, for a HashSet<String>, Borrow allows callers to provide &str or &String.

Example:

use std::collections::HashSet;

fn main() {
    let mut set: HashSet<String> = HashSet::new();
    set.insert("hello".to_string());
    set.insert("world".to_string());

    // Query directly with &str without creating a String.
    // This works because the standard library already provides `impl Borrow<str> for String`.
    let exists = set.contains("hello");
    let not_exists = set.contains("rust");

    println!("Contains 'hello': {}", exists);
    println!("Contains 'rust': {}", not_exists);
}

Output:

Contains 'hello': true
Contains 'rust': false

Comparison with `AsRef`

Of course, the same effect as above can also be achieved with AsRef:

use std::collections::HashSet;

// Generic function that accepts any type implementing `AsRef<str>`, such as `&str` and `&String`
fn contains<S: AsRef<str>>(set: &HashSet<String>, value: S) -> bool {
    set.contains(value.as_ref()) // `AsRef<str>` converts `value` to `&str`
}

fn main() {
    let mut set: HashSet<String> = HashSet::new();
    set.insert("hello".to_string());
    set.insert("world".to_string());

    // Query directly with &str
    let exists = contains(&set, "hello");

    // You can also query with &String
    let string_value = "world".to_string();
    let exists_string = contains(&set, &string_value);

    println!("Contains 'hello': {}", exists);
    println!("Contains 'world': {}", exists_string);
}

Using AsRef can achieve the same result, but without the extra requirements of Borrow, this implementation is unsafe for hash-table lookup, because Borrow requires the Hash, Eq, and Ord implementations of the borrowed form to match those of the owned type.

The potential problem is that AsRef does not require (even as documentation) consistency of Hash, Eq, and Ord between the source type and U.

For example:

use std::collections::HashSet;

#[derive(Hash, Eq, PartialEq)]
struct CustomType {
    value: String,
}

// Implement AsRef<str>, but that alone does not make HashSet lookup with &str legal
impl AsRef<str> for CustomType {
    fn as_ref(&self) -> &str {
        &self.value
    }
}

fn main() {
    let mut set: HashSet<CustomType> = HashSet::new();
    set.insert(CustomType { value: "hello".to_string() });

    // This will not compile (error[E0308]): `contains` is keyed on `Borrow`, not `AsRef`,
    // so `&str` does not match without `CustomType: Borrow<str>`
    let exists = set.contains("hello");
    println!("Exists: {}", exists);
}

contains is typed in terms of Borrow, so AsRef<str> does not participate
Even if you wrote a helper that converted via AsRef and then looked up somehow, nothing in the type system would force CustomType's Hash/Eq to match str's

By contrast, Borrow is the trait HashMap/HashSet use for lookup, and its documentation requires Hash, Eq, and Ord to remain consistent between the type and the borrowed form (the compiler does not prove this; implementors must uphold it):

use std::borrow::Borrow;
use std::collections::HashSet;

#[derive(Hash, Eq, PartialEq)]
struct CustomType {
    value: String,
}

// `Borrow<str>` is what enables `contains("hello")`, and you must keep Hash/Eq aligned with `str`
impl Borrow<str> for CustomType {
    fn borrow(&self) -> &str {
        &self.value
    }
}

fn main() {
    let mut set: HashSet<CustomType> = HashSet::new();
    set.insert(CustomType { value: "hello".to_string() });

    let exists = set.contains("hello"); // safe lookup if Hash/Eq match str
    println!("Exists: {}", exists);
}

Other Traits

Borrow also has blanket implementations for Borrow<T>, &T, and &mut T. This makes it convenient to use in trait bounds when you want to accept owned values or references of a given type.

The Rust standard library provides the following blanket implementations of Borrow<T> for all T, which means:

The type T itself can Borrow<T>, so T can be used directly as an argument to Borrow<T>
&T can also Borrow<T>, which lets an immutable reference satisfy a Borrow<T> bound
&mut T can also Borrow<T>, which lets a mutable reference satisfy a Borrow<T> bound

Suppose we have a find_item function that looks up a key in a HashMap<K, V>:

use std::borrow::Borrow;
use std::collections::HashMap;
use std::hash::Hash;

fn find_item<'a, K, V, Q>(map: &'a HashMap<K, V>, key: &Q) -> Option<&'a V>
where
    K: Eq + Hash + Borrow<Q>,
    Q: ?Sized + Eq + Hash,
{
    map.get(key)
}

fn main() {
    let mut map: HashMap<String, i32> = HashMap::new();
    map.insert("hello".to_string(), 42);

    // Because `String: Borrow<str>`, we can use `&str` directly to query `HashMap<String, i32>`
    let value = find_item(&map, "hello");

    println!("Value: {:?}", value); // Output: Value: Some(42)
}

The convenience provided by Borrow<T> is as follows:

String can be used as str's Borrow<T> implementation, so HashMap<String, i32> can be queried using &str as the key
find_item(&map, "hello") passes &str directly without converting it to String
find_item(&map, &"hello".to_string()) also works because &String also satisfies Borrow<str>

[Advanced Rust] 2.3. API Design Principles of Unsurprising Pt.3 - Implementing serde Serialize and Deserialize Traits, and Why…

SomeB1oody — Sun, 02 Aug 2026 18:42:24 +0000

Full title: [Advanced Rust] 2.3. API Design Principles of Unsurprising Pt.3 - Implementing serde Serialize and Deserialize Traits, and Why Copy Is Not Recommended

2.3.1. It Is Recommended to Implement `Serialize` and `Deserialize` in serde

Serde is the core Rust library for serialization and deserialization:

Serialization: converts a Rust struct or enum into a string or binary representation such as JSON or YAML
Deserialization: parses a string or binary representation such as JSON or YAML back into a Rust struct or enum

Serialize and Deserialize are both traits from the serde crate.

`Serialize` Trait

The Serialize trait allows a type to be converted into a serializable data format such as JSON, YAML, or TOML.

Its main methods include:

serialize_bool
serialize_i32
serialize_str
serialize_struct

These are methods on the Serializer (and related) traits that a Serialize implementation calls; the Serialize trait itself only requires serialize.

Its definition is:

pub trait Serialize {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer;
}

Here is an example showing how to implement Serialize manually:

use serde::ser::{Serialize, SerializeStruct, Serializer};

struct Point {
    x: i32,
    y: i32,
}

impl Serialize for Point {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let mut state = serializer.serialize_struct("Point", 2)?;
        state.serialize_field("x", &self.x)?;
        state.serialize_field("y", &self.y)?;
        state.end()
    }
}

serializer.serialize_struct("Point", 2)? creates a struct serializer state, and 2 is the number of fields
state.serialize_field("x", &self.x)? serializes the struct fields one by one
state.end() finishes serialization

`Deserialize` Trait

The Deserialize trait allows Rust types to be parsed from various data formats.

Its main methods include:

deserialize_bool
deserialize_i32
deserialize_string
deserialize_struct

These are methods on the Deserializer (and related) traits that a Deserialize implementation drives via a Visitor; the Deserialize trait itself only requires deserialize.

Its definition is:

pub trait Deserialize<'de>: Sized {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>;
}

The purpose of deserialize is to use deserializer to parse a Rust type from some data format

Here is an example showing how to implement Deserialize manually:

use serde::de::{self, Deserialize, Deserializer, Visitor, MapAccess};
use std::fmt;

struct Point {
    x: i32,
    y: i32,
}

impl<'de> Deserialize<'de> for Point {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        struct PointVisitor;

        impl<'de> Visitor<'de> for PointVisitor {
            type Value = Point;

            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
                formatter.write_str("a struct Point with fields x and y")
            }

            fn visit_map<M>(self, mut map: M) -> Result<Point, M::Error>
            where
                M: MapAccess<'de>,
            {
                let mut x = None;
                let mut y = None;

                while let Some(key) = map.next_key::<String>()? {
                    match key.as_str() {
                        "x" => x = Some(map.next_value()?),
                        "y" => y = Some(map.next_value()?),
                        _ => {}
                    }
                }

                let x = x.ok_or_else(|| de::Error::missing_field("x"))?;
                let y = y.ok_or_else(|| de::Error::missing_field("y"))?;

                Ok(Point { x, y })
            }
        }

        deserializer.deserialize_struct("Point", &["x", "y"], PointVisitor)
    }
}

PointVisitor is used to parse JSON fields
visit_map parses the values of x and y and ensures the fields exist

Automatically Implementing `Serialize` and `Deserialize` with `#[derive(Serialize, Deserialize)]`

Manually implementing Serialize and Deserialize is very tedious, so we usually use the serde_derive macro:

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p = Point { x: 10, y: 20 };

    let serialized = serde_json::to_string(&p).unwrap();
    println!("Serialized: {}", serialized); // {"x":10,"y":20}

    let deserialized: Point = serde_json::from_str(&serialized).unwrap();
    println!("Deserialized: {:?}", deserialized); // Point { x: 10, y: 20 }
}

Example Using `Serialize` and `Deserialize`

use serde::{Serialize, Deserialize};
use serde_json;

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    age: u32,
}

fn main() {
    let user = User {
        name: "Alice".to_string(),
        age: 30,
    };

    // Serialize
    let json_str = serde_json::to_string(&user).unwrap();
    println!("Serialized JSON: {}", json_str);

    // Deserialize
    let deserialized: User = serde_json::from_str(&json_str).unwrap();
    println!("Deserialized: {:?}", deserialized);
}

Output:

Serialized JSON: {"name":"Alice","age":30}
Deserialized: User { name: "Alice", age: 30 }

Other Notes

serde's serde_derive crate provides a mechanism for overriding the serialization of individual fields or enum variants. Because serde is a third-party library, you may not want to force it as a dependency.

Most libraries choose to provide a serde feature, and only add serde support when the user enables that feature.

That means you can write this in your crate:

[dependencies]
serde = { version = "1.0", optional = true }

[features]
serde = ["dep:serde"]

In the [dependencies] section, serde is introduced as a semver dependency with optional = true, which means it is an optional dependency. This means serde is not included by default unless it is explicitly enabled
In the [features] section, serde = ["dep:serde"] means that when the user enables the serde feature, the serde dependency will also be enabled
"dep:serde" indicates that this feature depends on the serde dependency (dep: is the dependency prefix that tells Cargo this feature depends on serde)

Someone else can enable serde when using your crate (assuming the crate is named my_crate) like this:

[dependencies]
my_crate = { version = "0.1", features = ["serde"] }

2.3.2. It Is Not Recommended to Implement the `Copy` Trait

Users usually do not expect a type to implement Copy. If they want a duplicate, they usually call clone.

The Copy trait changes the semantics of moving a value of a given type. Example:

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point1 = Point { x: 10, y: 10 };
    let point2 = point1;

    println!("{:?}", point1);
    println!("{:?}", point2);
}

The value of point1 is assigned to point2. Normally, point1 would be invalid after that, but because the Point struct implements Copy, the assignment copies the value instead of moving it, and point1 remains valid. That can surprise users, so implementing Copy is not recommended.

In addition, types that implement Copy have many restrictions. A type that starts out simple can easily stop meeting the requirements for Copy. For example, once it contains a String or any other type that does not support Copy, you must remove Copy.

[Advanced Rust] 2.2. API Design Principles of Unsurprising Pt.2 - Implementing Clone, Default, PartialEq, PartialOrd, Hash, Eq…

SomeB1oody — Sun, 02 Aug 2026 18:42:07 +0000

Full title: [Advanced Rust] 2.2. API Design Principles of Unsurprising Pt.2 - Implementing Clone, Default, PartialEq, PartialOrd, Hash, Eq, and Ord

2.2.1. It Is Recommended to Implement the `Clone` Trait and the `Default` Trait

`Clone` Trait

The Clone trait in Rust allows an implementer to explicitly create a deep copy of itself through the clone method, as opposed to the by-value copy provided by the Copy trait.

Example:

#[derive(Debug, Clone)]
struct Person {
    name: String,
    age: u32,
}

impl Person {
    fn new(name: String, age: u32) -> Self {
        Self { name, age }
    }
}

fn main() {
    let person1 = Person::new("John".to_owned(), 25);
    let person2 = person1.clone();

    println!("{:?}", person1);
    println!("{:?}", person2);
}

The Person struct implements the Clone trait
In main, person2 clones the data from person1 because it implements Clone

Output:

Person { name: "John", age: 25 }
Person { name: "John", age: 25 }

`Default` Trait

The Default trait in Rust allows a type to define a default value and return that default instance through the default() method.

Example:

#[derive(Default)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p = Point::default();

    println!("Point is at ({}, {})", p.x, p.y);
}

Output:

Point is at (0, 0)

2.2.2. It Is Recommended to Implement the `PartialEq`, `PartialOrd`, `Hash`, `Eq`, and `Ord` Traits

`PartialEq` Trait

PartialEq provides support for the == and != operators, allowing custom types to participate in partial equality comparisons.

Example:

#[derive(Debug, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point1: Point = Point { x: 1, y: 2 };
    let point2: Point = Point { x: 1, y: 2 };
    let point3: Point = Point { x: 3, y: 4 };

    println!("point1 == point2: {}", point1 == point2);
    println!("point1 == point3: {}", point1 == point3);
}

By implementing PartialEq, we can compare whether two structs are equal

Output:

point1 == point2: true
point1 == point3: false

`PartialOrd`, `Eq`, and `Ord` Traits

PartialOrd provides support for the <, <=, >, and >= operators, allowing custom types to participate in partial ordering comparisons, where some values may not be comparable.

Eq is a stricter version of PartialEq that requires equality to be reflexive (a == a is always true). You must implement PartialEq before implementing Eq.

Ord is a stricter version of PartialOrd that requires a total ordering, enabling complete sorting logic for types such as BTreeMap and BTreeSet. You must implement PartialOrd before implementing Ord.

Example:

use std::collections::BTreeMap;

#[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone)]
struct Person {
    name: String,
    age: u32,
}

fn main() {
    let mut ages = BTreeMap::new();

    let person1 = Person {
        name: String::from("Alice"),
        age: 25,
    };

    let person2 = Person {
        name: String::from("Bob"),
        age: 30,
    };

    let person3 = Person {
        name: String::from("Charlie"),
        age: 20,
    };

    ages.insert(person1.clone(), "Alice's Age");
    ages.insert(person2.clone(), "Bob's Age");
    ages.insert(person3.clone(), "Charlie's Age");

    for (person, description) in &ages {
        println!("{}: {} - {:?}", person.name, person.age, description);
    }
}

BTreeMap stores entries in sorted order. Because it sorts by the key's value, the key type must implement Ord for total ordering and Eq for equality comparison.
- Implementing Ord requires PartialOrd first
- Implementing Eq requires PartialEq first

`Hash` Trait

Hash allows a type to implement the hash() method, which supports hash-based collections such as HashMap and HashSet. The Hash trait itself does not require Eq as a supertrait, but hash collections require K: Eq + Hash, and equal values must produce the same hash. So in practice, you should implement PartialEq and Eq together with Hash whenever the type will be used as a hash-map/set key.

Example:

use std::collections::HashSet;
use std::hash::{Hash, Hasher};

#[derive(Debug, PartialEq, Eq, Clone)]
struct Person {
    name: String,
    age: u32,
}

impl Hash for Person {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.name.hash(state);
        self.age.hash(state);
    }
}

fn main() {
    let mut persons = HashSet::new();

    let person1 = Person {
        name: "Alice".to_string(),
        age: 25,
    };

    let person2 = Person {
        name: "Bob".to_string(),
        age: 30,
    };

    let person3 = Person {
        name: "Charlie".to_string(),
        age: 20,
    };

    persons.insert(person1.clone());
    persons.insert(person2.clone());
    persons.insert(person3.clone());

    println!("Persons: {:#?}", persons);
}

HashSet is used to store a set of unique elements, while HashMap is used to store key-value pairs.

Output:

Persons: {
    Person {
        name: "Bob",
        age: 30,
    },
    Person {
        name: "Charlie",
        age: 20,
    },
    Person {
        name: "Alice",
        age: 25,
    },
}

`Eq` and `PartialEq`, `Ord` and `PartialOrd`

Eq has additional semantic requirements compared with PartialEq, and Ord has additional semantic requirements compared with PartialOrd. You should only implement them when those semantics apply to your type.

The additional semantics of Eq compared with PartialEq are:

Reflexivity: for all a, a == a must always hold

(PartialEq already expects symmetry and transitivity; Eq is the marker that equality is also reflexive, so there are no “partial” equalities such as f32::NAN != f32::NAN.)

The additional semantics of Ord compared with PartialOrd are:

Totality / comparability: for all a and b, exactly one of a < b, a == b, or a > b holds (equivalently, partial_cmp never returns None)
Reflexivity: for all a, a <= a and a >= a must always hold
Antisymmetry: if a <= b and b <= a, then a == b must hold
Transitivity: if a <= b and b <= c, then a <= c must hold

[Advanced Rust] 2.1. API Design Principles of Unsurprising - Naming Tips, Implementing Common Traits

SomeB1oody — Sat, 01 Aug 2026 17:01:22 +0000

Full title: [Advanced Rust] 2.1. API Design Principles of Unsurprising - Naming Tips, Implementing Common Traits (Debug, Send, Sync, and Unpin)

2.1.1. What Is the Unsurprising Principle?

The unsurprising principle is also called the least-surprise principle. It means that the APIs you write should be as intuitive as possible.

Users should be able to guess what an interface does just by looking at it. At the very least, your interface should not surprise them. Its core idea is to stay close to what users already know, so they do not need to relearn concepts. For example, if an interface name contains error, users will probably guess that it is used for error handling.

In other words, we need our interfaces to be predictable, which requires attention to the following:

Naming
Implementing common traits
Ergonomic traits
Wrapper types

2.1.2. Naming Tips

Interface names should follow conventions so their behavior is easy to infer. Here, conventions means the conventions commonly used in the Rust standard library and Rust community.

Examples:

A method named iter (or ending with iter) will most likely take &self as an argument and return an iterator
A method named into_inner will most likely take self as an argument and return the wrapped type
A type named SomethingError should implement std::error::Error and appear in various Result types

Using the same common names for the same purposes helps users understand the API. This leads to another conclusion: things with the same name should behave in the same way, otherwise users will probably write incorrect code.

2.1.3. Implementing Common Traits

Users usually assume that everything in an interface works “as expected,” for example:

You can print any type with {:?}
You can send anything to another thread
Every type is Clone

So when writing code, actively implement most standard traits, even if you do not need them immediately.

From another angle, users cannot implement foreign traits for foreign types themselves because that would violate the orphan rule. That makes it hard for them to add the traits they want to your types. So you should actively implement most standard traits, so your types can satisfy the traits most users expect.

2.1.4. It Is Recommended to Implement the `Debug` Trait

Almost all types can and should implement the Debug trait.

The simplest and best way is to use #[derive(Debug)]. Note that a derived trait will add the same bound to any generic parameter.

An example makes this clear:

use std::fmt::Debug;

#[derive(Debug)]
struct Pair<T> {
    a: T,
    b: T,
}

fn main() {
    let pair = Pair { a: 5, b: 10 };
    println!("{:?}", pair);
}

The Pair struct implements the Debug trait through derive, so it automatically adds the bound T: Debug to the generic parameter T
The type of the Pair fields in main is i32, which implements Debug, so it can be printed

Output:

Pair { a: 5, b: 10 }

What if I change the field type to something that does not implement Debug?

use std::fmt::Debug;

struct Person {
    name: String,
}

#[derive(Debug)]
struct Pair<T> {
    a: T,
    b: T,
}

fn main() {
    let pair = Pair {
        a: Person { name: "Dave".to_string() },
        b: Person { name: "Nick".to_string() },
    };
    println!("{:?}", pair);
}

Output:

error[E0277]: `Person` doesn't implement `Debug`
  --> src/main.rs:18:22
   |
18 |     println!("{:?}", pair);
   |               ----   ^^^^ `Person` cannot be formatted using `{:?}` because it doesn't implement `Debug`
   |               |
   |               required by this formatting parameter
   |
   = help: the trait `Debug` is not implemented for `Person`
   = note: add `#[derive(Debug)]` to `Person` or manually `impl Debug for Person`
help: the trait `Debug` is implemented for `Pair<T>`
  --> src/main.rs:7:10
   |
 7 | #[derive(Debug)]
   |          ^^^^^
note: required for `Pair<Person>` to implement `Debug`
  --> src/main.rs:8:8
   |
 7 | #[derive(Debug)]
   |          ----- in this derive macro expansion
 8 | struct Pair<T> {
   |        ^^^^ - type parameter would need to implement `Debug`
   = help: consider manually implementing `Debug` to avoid undesired bounds
help: consider annotating `Person` with `#[derive(Debug)]`
   |
 3 + #[derive(Debug)]
 4 | struct Person {
   |

We can also manually implement Debug by using the various debug_xxx helper methods provided by fmt::Formatter in the standard library:

debug_struct
debug_tuple
debug_list
debug_set
debug_map

Example:

use std::fmt;

struct Pair<T> {
    a: T,
    b: T,
}

impl<T: fmt::Debug> fmt::Debug for Pair<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Pair")
            .field("a", &self.a)
            .field("b", &self.b)
            .finish()
    }
}

fn main() {
    let pair = Pair { a: 1, b: 2 };
    println!("{:?}", pair);
}

We manually implement the Debug trait instead of using #[derive(Debug)]
fmt is the method that must be defined when implementing fmt::Debug
f: &mut fmt::Formatter<'_> provides the formatting context and tools
f.debug_struct("Pair") declares that the value should be formatted as a debug struct with fields, and sets the struct name to "Pair"
.field("a", &self.a) and .field("b", &self.b) add the a and b fields to Pair and associate each field with its value
.finish() completes the formatting builder and returns the result to be printed

Output:

Pair { a: 1, b: 2 }

2.1.5. It Is Recommended to Implement the `Send`, `Unpin`, and `Sync` Traits

If your type does not implement Send, it cannot be moved to another thread (for example, thread::spawn requires T: Send). Wrapping a !Send value in Mutex<T> does not help either: Mutex<T> is only Send/Sync when T: Send, so it still cannot be shared across threads.

Example:

use std::rc::Rc;

fn main() {
    let x = Rc::new(42);

    std::thread::spawn(move || {
        println!("{:?}", x);
    });
}

Rc<T> does not implement Send, so it cannot be used across threads

We can write a simple tuple struct ourselves to implement it manually (of course, it will not have Rc<T>'s reference counting feature):

#[derive(Debug)]
struct MyBox(*mut u8);

unsafe impl Send for MyBox {}

fn main() {
    let mb = MyBox(Box::into_raw(Box::new(42)));

    std::thread::spawn(move || {
        println!("{:?}", mb);
    });
}

MyBox implements Send, so it can be used across threads
Traits such as Send that act only as markers and do not provide concrete behavior are called marker traits. Marker traits provide compile-time information but do not add behavior. So implementing Send for MyBox does not require any method body
Manually implementing Send is unsafe, so we must add the unsafe marker before the impl block. Rust's type system normally infers Send automatically to ensure thread safety, while a manual Send implementation may bypass Rust's safety checks

Types that do not implement Sync cannot be shared across threads through Arc<T> (the atomic reference-counted pointer, the multithreaded version of Rc<T>), and they also cannot be stored in static items that require Sync.

Example:

use std::cell::RefCell;
use std::sync::Arc;

fn main() {
    let x = Arc::new(RefCell::new(42));
    std::thread::spawn(move || {
        let mut x = x.borrow_mut();
        *x += 1;
    });
}

RefCell<T> does not implement Sync, so it cannot be shared across threads with Arc<T>

Unpin means “can be unpinned.” It is a marker trait used to indicate whether a type can be safely moved out of a Pin, that is, whether it can bypass the restrictions of Pin.

Most types are Unpin by default. Self-referential types are usually made !Unpin by embedding a marker such as std::marker::PhantomPinned (or another !Unpin field). Rust does not automatically treat “has a self-reference” as !Unpin; without such a marker, the type would still be Unpin, and moving it could invalidate internal pointers.

If your type does not implement any of the above traits, it is recommended that you state that in the documentation.

[Advanced Rust] 1.17. Orphan Rules, Coherence, and Consistency - Blanket and Covered Implementations

SomeB1oody — Sat, 01 Aug 2026 05:25:42 +0000

1.17.1. Coherence

Coherence means that for a given type and method, there is only one correct choice for the implementation of that method on that type.

The orphan rule means that as long as either the trait or the type is in the local crate, you can implement that trait for that type. For example:

A type you define locally can implement the Debug trait
You can implement a trait you define locally for bool
You cannot implement Debug for bool, because neither side is local

There are exceptions to the orphan rule, which we will discuss below.

1.17.2. Blanket Implementation

A blanket implementation, also called a general implementation, means that Rust allows a default implementation for every type that satisfies a trait bound.

Its template is:

impl<T> MyTrait for T where T: ...

This means implementing MyTrait for all types that implement some trait.

For example:

impl<T: Display> ToString for T {}

This means implementing ToString for all types that implement Display.

This example is not yet written in template form. In template form, it would be:

impl<T> ToString for T where T: Display {}

Note that only the crate that defines the trait is allowed to use blanket implementations. Adding a blanket implementation to an existing trait is a breaking change.

1.17.3. Fundamental Types

Some types are so fundamental that we need to allow anyone to implement traits for them, even if that would violate the orphan rule. These types are marked #[fundamental], and currently include &T, &mut T, Box<T>, and Pin.

One extra note: the main purpose of Pin is to ensure that a value cannot be moved, that is, to prevent operations such as std::mem::replace, std::mem::swap, or std::mem::take from changing the value’s physical address
For the purpose of the orphan rule, these types are actually erased before orphan-rule checking takes place

Note: using blanket implementations on fundamental types is also considered a breaking change.

1.17.4. Covered Implementation

Sometimes you need to implement an external trait for an external type, which is called a covered implementation. This uses one narrow exemption established by the orphan rule: it allows an external trait to be implemented for an external type in very specific cases.

Note: covered implementation can refer either to Covered Implementation or Override Implementation. Here it refers to Covered Implementation. Override implementation means that when a struct implements a trait and provides its own methods, it can override the default implementation.

The template for this form is:

impl<P1..=Pn> ForeignTrait<T1..=Tn> for T0

P1..=Pn and T1..=T0 refer to a number of parameters

This form is allowed only if all of the following conditions are met:

At least one of T1..=Tn is a local type
No T (where T is one of the generic types in P1..=Pn) may appear before the first such local type
A generic type parameter P may appear in T0..Ti as long as it is wrapped by some intermediate type
- If T appears as a type parameter of another type, such as Vec<T>, then T is considered wrapped
- If T appears only by itself, or behind a fundamental type such as &T, then it is not wrapped

For a simple example:

impl From<MyType> for Vec<i32>

This implements the external From<MyType> trait for the external Vec<i32> type.

Here are some more complex examples. You can use the rules above to understand them:

Implementation	Valid?
`impl<T> From<T> for MyType`	OK
`impl<T> From<T> for MyType<T>`	OK
`impl<T> From<MyType> for Vec<T>`	OK
`impl<T> ForeignTrait<MyType, T> for Vec<T>`	OK
`--------------------------------------------`	------------
`impl<T> ForeignTrait for T`	Not OK
`impl<T> From<T> for T`	Not OK
`impl<T> From<Vec<T>> for T`	Not OK
`impl<T> From<MyType<T>> for T`	Not OK
`impl<T> From<T> for Vec<T>`	Not OK
`impl<T> ForeignTrait<T, MyType> for Vec<T>`	Not OK

Whether a covered implementation is a breaking change depends on the specific situation:

Adding a new implementation to an existing trait, with at least one new local type that satisfies the conditions above, is a non-breaking change
Adding an implementation for an existing trait that does not meet the conditions above is a breaking change

Note:

impl<T> ForeignTrait<MyType, T> for Vec<T> is valid
impl<T> ForeignTrait<T, MyType> for Vec<T> is invalid

[Advanced Rust] 1.16. Generic Traits - Generic (Type-Parameter) Traits and Associated-Type Traits

SomeB1oody — Sat, 01 Aug 2026 05:11:39 +0000

1.16.1. Two Ways to Make a Trait Generic

Traits can be generic in two ways:

Generic type parameters. Example: trait Foo<T>
Associated types. Example: trait Foo { type Bar; }

The difference between the two is:

With associated types, a given trait for a specific type has only one implementation
With generic parameters, there can be multiple implementations

A simple suggestion: if possible, prefer associated types.

1.16.2. Generic (Type-Parameter) Traits

Generic traits require you to specify all generic type parameters and repeat their bounds.

This is somewhat harder to maintain. For example, if you add a generic type parameter to a trait, all implementers of that trait must update their code.

This form can also lead to the problem that a trait may have multiple implementations for a given type. Then the compiler has a harder time inferring which instance of the trait you actually want. Sometimes you must call an ambiguity-resolving function such as FromIterator::<u32>::from_iter.

In some cases this feature is also an advantage, for example:

impl PartialEq<BookFormat> for Book, where BookFormat can be different types
You can implement both FromIterator<T> and FromIterator<&T> where T: Clone

1.16.3. Associated-Type Traits

Let’s use a piece of code as an example:

trait Contains {
    type A;
    type B;

    // Updates syntax to refer to these new types generically
    fn contains(&self, _: &Self::A, _: &Self::B) -> bool;
}

With associated types:

The compiler only needs to know the type that implements the trait
The bound can live entirely on the trait itself and does not need to be repeated
Adding another associated type in the future does not affect users
The concrete type determines the associated types inside the trait, so there is no need to use ambiguity-resolving functions. Look at this example:

impl Contains for Container {
    // Specify what types `A` and `B` are. If the `input` type
    // is `Container(i32, i32)`, the `output` types are determined
    // as `i32` and `i32`.
    type A = i32;
    type B = i32;

    // `&Self::A` and `&Self::B` are also valid here.
    fn contains(&self, number_1: &i32, number_2: &i32) -> bool {
        (&self.0 == number_1) && (&self.1 == number_2)
    }

    // Grab the first number.
    fn first(&self) -> i32 { self.0 }

    // Grab the last number.
    fn last(&self) -> i32 { self.1 }
}

This example implements the Contains trait for the Container type
The associated types in Container’s Contains implementation are determined by type A = i32; and type B = i32;

You Cannot Implement `Deref` for Multiple Target Types

Look at the source code of the Deref trait:

pub trait Deref {
    type Target: ?Sized;

    fn deref(&self) -> &Self::Target;
}

Target in type Target: ?Sized; is the target type we are talking about

Let’s write a Deref implementation to illustrate:

use std::ops::Deref;

struct Wrapper {
    value: String,
}

impl Deref for Wrapper {
    type Target = String;

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

In the code above, Wrapper can only be dereferenced as String. But if you want Wrapper to be dereferenced as both String and str at the same time, Rust does not allow you to implement Deref again, because Target can only have one concrete type.

In other words, this is illegal:

use std::ops::Deref;

struct Wrapper {
    value: String,
}

// First Deref implementation, Target = String
impl Deref for Wrapper {
    type Target = String;

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

// This is illegal: Rust does not allow a second `Deref` implementation
// for the same `Wrapper` type.
impl Deref for Wrapper {
    type Target = str;  // Conflict: Rust cannot infer which `Target` applies

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

You Cannot Use Multiple `Item`s to Implement the `Iterator` Trait

The reason is the same as the reason you cannot implement Deref for multiple target types: it mainly involves the uniqueness of associated types and the inference rules of the Rust compiler.

DEV Community: SomeB1oody

[Advanced Rust] 2.10. API Design Principles of Constrained Pt.1 - Changing Types

2.10.1. Think Carefully Before Changing an Interface

2.10.2. Backward-Incompatible Changes

2.10.3. Modifying Types

#[non_exhaustive] Attribute

An Example of a Breaking Change

Solution

[Advanced Rust] 2.9. API Design Principles of Obviousness - Documentation and Type System, Semantic Types, and Zero-Sized Types

2.9.1. Documentation and the Type System

2.9.2. Documentation

1. Clearly Document Things

2. Include End-to-End Examples

3. Organize the Documentation Well

4. Enrich the Documentation as Much as Possible

2.9.3. The Type System

Semantic Types

Using Zero-Sized Types to Represent Facts About a Type Instance

#[must_use] Attribute

[Advanced Rust] 2.8. API Design Principles of Flexibility Pt.4 - Problems with Explicit Destructors and Three Solutions

2.8.1. Problems with Explicit Destructors

2.8.2. Solutions

Solution 1: Wrap the Struct in Option<T> and Add Another Layer of Struct

Step 1: Change the File definition and add a wrapper layer

Step 2: Update the methods on File

Step 3: Update the Drop implementation

Step 4: Slightly Adjust main

Full Code

Solution 2: Wrap Each Field in Option<T>

Step 1: Change the File definition

Step 2: Update the methods on File

Step 3: Update the Drop implementation

Step 4: Slightly Adjust main

Full Code

Solution 3: Store Data in ManuallyDrop

Step 1: Change the File definition

Step 2: Update the methods on File

Step 3: Update the Drop implementation

Step 4: Slightly Adjust main

Full Code

Choosing Between the Three Solutions

[Advanced Rust] 2.7. API Design Principles of Flexibility Pt.3 - Borrowed vs Owned, Cow Type, and Fallible and Blocking Destruc…

2.7.1. Borrowed vs. Owned

Cow Type

When Should You Consider Taking Ownership of Data?

2.7.2. Fallible and Blocking Destructors

Problems with I/O Operations and Destructors

Problems with Async Code and Destructors

For These Two Problems

A Small Extension: About Future

The Solution — Explicit Destructors

A Small Note

[Advanced Rust] 2.6. API Design Principles of Flexibility Pt.2 - Object Safety, API Design, and Generic Trait Methods

2.6.1. Object Safety

Traits That Are Object-Safe Must Satisfy the Following Conditions (Based on RFC 255)

What Object Safety Does

Object Safety and API Design

Generic Trait Methods and API Design

Put Generic Parameters on the Trait

Use Dynamic Dispatch

The Cost of Object Safety

[Advanced Rust] 2.5. API Design Principles of Flexibility Pt.1 - Contracts and More Flexible Interfaces with Generic Parameters

2.5.1. Code Contracts

2.5.2. Restrictions and Promises

Some Examples

2.5.3. Use Generic Parameters to Make Interfaces More Flexible

Example of Using Generic Parameters

Do Not Take Generic Parameters to the Extreme

The Trade-Off Between Monomorphization and Dynamic Dispatch

How Should APIs Consider Generic Parameters?

[Advanced Rust] 2.4. API Design Principles of Unsurprising Pt.4 - Ergonomic Trait Implementations, Wrapper Types, and Borrow Tr…

2.4.1. Ergonomic Trait Implementations

Note: if a trait method takes self by value (consuming ownership), you generally cannot provide a blanket impl Trait for &T that forwards to T, because a shared reference cannot move out of T.

2.4.2. Wrapper Types

2.4.3. Borrow Trait

Comparison with AsRef

Other Traits

[Advanced Rust] 2.3. API Design Principles of Unsurprising Pt.3 - Implementing serde Serialize and Deserialize Traits, and Why…

2.3.1. It Is Recommended to Implement Serialize and Deserialize in serde

Serialize Trait

`#[non_exhaustive]` Attribute

`#[must_use]` Attribute

Solution 1: Wrap the Struct in `Option<T>` and Add Another Layer of Struct

Step 1: Change the `File` definition and add a wrapper layer

Step 2: Update the methods on `File`

Step 3: Update the `Drop` implementation

Step 4: Slightly Adjust `main`

Solution 2: Wrap Each Field in `Option<T>`

Step 1: Change the `File` definition

Step 2: Update the methods on `File`

Step 3: Update the `Drop` implementation

Step 4: Slightly Adjust `main`

Solution 3: Store Data in `ManuallyDrop`

Step 1: Change the `File` definition

Step 2: Update the methods on `File`

Step 3: Update the `Drop` implementation

Step 4: Slightly Adjust `main`

`Cow` Type

A Small Extension: About `Future`

Note: if a trait method takes `self` by value (consuming ownership), you generally cannot provide a blanket `impl Trait for &T` that forwards to `T`, because a shared reference cannot move out of `T`.

2.4.3. `Borrow` Trait

Comparison with `AsRef`

2.3.1. It Is Recommended to Implement `Serialize` and `Deserialize` in serde

`Serialize` Trait

`Deserialize` Trait

Automatically Implementing `Serialize` and `Deserialize` with `#[derive(Serialize, Deserialize)]`

Example Using `Serialize` and `Deserialize`

2.3.2. It Is Not Recommended to Implement the `Copy` Trait

2.2.1. It Is Recommended to Implement the `Clone` Trait and the `Default` Trait

`Clone` Trait

`Default` Trait

2.2.2. It Is Recommended to Implement the `PartialEq`, `PartialOrd`, `Hash`, `Eq`, and `Ord` Traits

`PartialEq` Trait

`PartialOrd`, `Eq`, and `Ord` Traits

`Hash` Trait

`Eq` and `PartialEq`, `Ord` and `PartialOrd`

2.1.4. It Is Recommended to Implement the `Debug` Trait

2.1.5. It Is Recommended to Implement the `Send`, `Unpin`, and `Sync` Traits

You Cannot Implement `Deref` for Multiple Target Types

You Cannot Use Multiple `Item`s to Implement the `Iterator` Trait