Tuple Struct

A tuple struct is a nominal data type in Rust that combines the named identity of a standard struct with the anonymous, position-based fields of a tuple. Unlike standard structs, which use named fields, tuple structs rely entirely on the order of their elements for data organization.

Syntax and Instantiation

Tuple structs are defined using the struct keyword followed by an identifier and a parenthesized list of types. They are instantiated using function-call syntax.

// Definition
struct Color(u8, u8, u8);
struct Point3D(f32, f32, f32);

// Instantiation
let pure_red = Color(255, 0, 0);
let origin = Point3D(0.0, 0.0, 0.0);

Implicit Constructor Function

Defining a tuple struct implicitly generates a constructor function of the same name. This function accepts arguments corresponding to the tuple’s field types and returns an instance of the struct. Because it is a standard function item, it implements the closure traits (Fn, FnMut, FnOnce) and can be passed directly to higher-order functions that expect a callable.

struct Distance(f64);

// `Distance` acts as a function item `fn(f64) -> Distance`
let distances: Vec<Distance> = vec![1.0, 2.5, 3.0]
    .into_iter()
    .map(Distance) 
    .collect();

The Newtype Pattern

A tuple struct containing exactly one field is known as a “newtype”. This pattern is a fundamental Rust idiom used to enforce strict compile-time type safety and to bypass the orphan rule, allowing the implementation of external traits on external types by wrapping them in a local newtype.

struct UserId(u64);
struct Milliseconds(u64);

// The compiler treats `UserId` and `Milliseconds` as distinct types
// despite both wrapping a `u64`.

Nominal Typing

Tuple structs enforce strict nominal typing. Even if two tuple structs possess identical internal type signatures, the Rust compiler treats them as distinct, incompatible types.

struct Distance(f64);
struct Weight(f64);

let d = Distance(10.0);
// let w: Weight = d; // Compilation error: expected `Weight`, found `Distance`

Field Access

Because the fields lack identifiers, they are accessed using zero-indexed dot notation, identical to standard tuples.

# struct Color(u8, u8, u8);

# let pure_red = Color(255, 0, 0);
let red_value = pure_red.0;
let green_value = pure_red.1;
let blue_value = pure_red.2;

Destructuring

Tuple structs can be destructured into their constituent parts using pattern matching via let bindings, match arms, or function parameters. During destructuring, ownership semantics depend entirely on whether the individual matched fields implement the Copy trait. If a matched field implements Copy, its value is copied out. If a matched field does not implement Copy, its value is moved, resulting in a partial move of the tuple struct.

struct Color(u8, u8, u8);
struct UserData(String, u32);

let pure_red = Color(255, 0, 0);
let user = UserData(String::from("Alice"), 30);

// Destructuring fields that implement `Copy` (`u8`)
// The values are copied; `pure_red` is not moved and remains fully valid.
let Color(r, g, b) = pure_red;

// `pure_red` can be destructured again because the previous step only copied the fields.
// The `..` syntax ignores the remaining fields.
let Color(r_only, ..) = pure_red;

// Destructuring a field that does not implement `Copy` (`String`)
// This moves the `String` out of `user.0`, causing a partial move of `user`.
let UserData(name, age) = user;

// `user.0` is no longer valid, but `user.1` (or the copied `age`) remains valid.

Visibility

Visibility modifiers (pub, pub(crate), pub(super)) can be applied to the tuple struct itself, as well as individually to its anonymous fields. If a field is not marked pub, it remains private to the module in which the tuple struct is defined. If any field is private, external modules cannot instantiate the tuple struct using the function-call syntax or destructure the private fields.

pub struct EncryptedPayload(pub Vec<u8>, u64); 
// Field 0 is public, Field 1 is private

Memory Layout

At the ABI level, a tuple struct is indistinguishable from a standard struct containing the same types. The Rust compiler (rustc) applies the default repr(Rust) memory layout rules. This means the compiler may reorder the anonymous fields in memory to minimize padding and optimize alignment. To enforce a strict, predictable layout that matches the declaration order, the #[repr(C)] attribute must be applied.

#[repr(C)]
struct AlignedTuple(u8, u32, u16);

Master Rust with Deep Grasping Methodology!

Learn More