The problem with plain types
You are building a forum. You write a function to delete a post: fn delete_post(user_id: u32, post_id: u32). Both arguments are u32. You call it with delete_post(post_id, user_id). The compiler accepts this. It sees two u32 values. It does not care which one is the user and which one is the post. The code compiles. You delete the wrong post.
This is the unit confusion bug. It happens whenever the same primitive type represents multiple distinct concepts in your domain. IDs, currencies, distances, and permissions all suffer from this. The compiler treats u32 as just a number. It cannot distinguish between a user ID and a post ID because they share the same type.
The newtype pattern fixes this. It gives each concept its own type. The compiler then enforces that you use the right type in the right place. You cannot accidentally swap a user ID for a post ID because they are no longer the same type.
What is a newtype?
A newtype is a tuple struct with a single field. It wraps an existing type to create a distinct type. Rust treats the wrapper as completely unrelated to the inner type, even though they hold the same data.
// Wrap the inner type in a tuple struct to create a distinct type.
struct Millimeters(u32);
struct Meters(u32);
// The function signature now demands Meters, not just any number.
fn print_distance(m: Meters) {
// Access the inner value via the tuple index.
println!("Distance: {} meters", m.0);
}
fn main() {
let meters = Meters(100);
print_distance(meters);
// This fails to compile. Millimeters is not Meters.
// The compiler rejects this with E0308 (mismatched types).
// let millimeters = Millimeters(100);
// print_distance(millimeters);
}
The struct Millimeters holds a u32. The struct Meters also holds a u32. To the compiler, Millimeters and Meters are as different as String and Vec<u8>. You cannot pass a Millimeters where a Meters is expected. You must explicitly convert or construct the correct type.
Access the inner value using the tuple index .0. This is the standard way to reach inside a newtype. You can also define methods on the wrapper to provide a cleaner API.
Zero-cost abstraction
Newtypes add safety without adding overhead. The compiler optimizes the wrapper away completely. At runtime, a newtype has the same size, alignment, and layout as the inner type. There is no pointer indirection, no heap allocation, and no function call penalty.
use std::mem;
struct UserId(u32);
fn main() {
// The newtype has the exact same size as the inner type.
assert_eq!(mem::size_of::<UserId>(), mem::size_of::<u32>());
// The newtype has the exact same alignment as the inner type.
assert_eq!(mem::align_of::<UserId>(), mem::align_of::<u32>());
}
The type distinction exists only at compile time. Once the code is compiled, the newtype vanishes. This makes newtypes the preferred way to add type safety in performance-critical code. You get the safety of distinct types with the speed of raw primitives.
Convention aside: derive Copy and Clone for newtypes wrapping primitives. This allows the newtype to behave like the inner type for value semantics.
// Derive Copy and Clone so the newtype can be copied like a u32.
#[derive(Copy, Clone)]
struct UserId(u32);
Beating the orphan rule
Rust has a rule called the orphan rule. You can only implement a trait if either the trait or the type is local to your crate. You cannot implement Display for String because both Display and String are defined in std. The compiler rejects this to prevent conflicts between crates.
The newtype pattern sidesteps this rule. The wrapper type is local to your crate. You can implement any trait on the wrapper, even if the trait and the inner type are both foreign.
use std::fmt;
// Newtype wrapping a foreign type.
struct Username(String);
// Implement Display for the newtype.
// This is allowed because Username is local to this crate.
impl fmt::Display for Username {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Add a prefix to the username when displaying.
write!(f, "@{}", self.0)
}
}
fn main() {
let name = Username("alice".to_string());
println!("User: {}", name); // Prints @alice
}
This pattern is essential for adding behavior to types you do not control. You can implement Serialize, Deserialize, FromStr, or any other trait on the newtype without touching the original type.
Convention aside: derive Debug on newtypes. It provides a default implementation that delegates to the inner type. This saves boilerplate and gives you useful debugging output immediately.
// Derive Debug to get a default implementation.
#[derive(Debug)]
struct Username(String);
Enforcing invariants
Newtypes can enforce invariants at construction time. If the inner type has constraints, you can use TryFrom to validate the value before creating the newtype. This ensures that every instance of the newtype is valid.
use std::convert::TryFrom;
// Newtype representing a valid age.
struct Age(u8);
// Use TryFrom to enforce invariants during construction.
impl TryFrom<u8> for Age {
type Error = &'static str;
fn try_from(value: u8) -> Result<Self, Self::Error> {
// Validate the value before creating the newtype.
if value > 150 {
Err("Age is too high")
} else {
Ok(Age(value))
}
}
}
fn main() {
// Valid age creates the newtype successfully.
let age = Age::try_from(25).unwrap();
// Invalid age returns an error.
let invalid = Age::try_from(200);
assert!(invalid.is_err());
}
This pattern is powerful for domain logic. You can guarantee that a Percentage is between 0 and 100, or that a NonEmptyString is not empty. The type system then enforces that only valid values exist in your code. You do not need to check invariants repeatedly because the type itself represents validity.
Pitfalls and compiler errors
Newtypes are simple, but there are a few traps.
If you pass a newtype where the inner type is expected, the compiler rejects it with E0308 (mismatched types). The compiler will not automatically unwrap the newtype. You must access .0 explicitly or implement a conversion trait.
struct UserId(u32);
fn get_user(id: u32) -> String {
format!("User {}", id)
}
fn main() {
let user = UserId(42);
// This fails with E0308. UserId is not u32.
// let name = get_user(user);
// Access the inner value explicitly.
let name = get_user(user.0);
}
A common mistake is implementing Deref on the newtype to allow calling inner methods directly. This creates a leaky abstraction. If you implement Deref<Target=u32>, the newtype can be passed anywhere a u32 is expected. This erodes the type safety you built. The compiler will coerce the newtype to the inner type, and you can accidentally swap types again.
Only use Deref if you explicitly want the newtype to behave like the inner type in most contexts. Usually, you do not. Keep the newtype distinct. Access the inner value only when necessary.
Another pitfall is forgetting that newtypes are distinct types. You cannot compare a UserId with a u32 using ==. You must compare UserId with UserId, or access .0 to compare with u32. If you need equality with the inner type, implement PartialEq<u32> explicitly.
struct UserId(u32);
// Implement PartialEq<u32> to allow comparison with the inner type.
impl PartialEq<u32> for UserId {
fn eq(&self, other: &u32) -> bool {
self.0 == *other
}
}
Convention aside: use #[repr(transparent)] when you need to guarantee the layout matches the inner type. This is useful for FFI or when you need to transmute between the newtype and the inner type safely. The attribute tells the compiler to lay out the newtype exactly like the inner type.
// Guarantee the layout matches the inner type.
#[repr(transparent)]
struct UserId(u32);
When to use newtypes
Use newtypes for type safety when you have multiple values of the same primitive type that represent different concepts. Use newtypes for trait implementation when you need to implement a trait on a foreign type and the orphan rule blocks you. Use newtypes for abstraction when you want to hide the internal representation or add invariants. Reach for plain types when the distinction does not matter and you are just doing math. Reach for enums when the value can be one of several distinct variants, not just a wrapper.
Wrap the type. The compiler will thank you.