Newtype idiom
The newtype idiom defines a distinct type by wrapping an existing type, typically preserving its representation while enabling type-specific distinctions or behavior.
Write Powerful Rust Macros
A newtype is a distinct wrapper type around an existing value that gives the value stronger type-level meaning and can enforce construction invariants.
- How it is used
- Prevents swapped same-typed arguments and gives public APIs domain-specific meanings.
- How deep it goes
- Works through wrapper structs, private fields, validating constructors, accessors, and macro-generated repeated methods; defers conversion implementations to exercises.
- Examples
- Uses a pay-raise call with swapped strings and integers, then FirstName, LastName, Age, and Pay wrappers.
- What you can do after
- Build it from scratch by defining validated wrapper structs and reducing repeated accessor or conversion code with declarative macros.
Read how Write Powerful Rust Macros explains newtype idiom →
Functional Design and Architecture: Examples in Haskell
A newtype is a distinct type wrapper around an existing representation that preserves its runtime representation while enforcing compile-time type distinctions.
- How it is used
- Prevents wrong arguments when domain identifiers share a representation, especially inside embedded domain-specific languages.
- How deep it goes
- Defines the wrapper pattern and its compiler-visible distinction, but does not detail construction, unwrapping, or runtime mechanics.
- Examples
- Uses ControllerName and ComponentIndex as distinct wrappers around String.
- What you can do after
- Apply it by wrapping bare domain types so the compiler rejects interchangeable identifiers.
Read how Functional Design and Architecture: Examples in Haskell explains newtype idiom →
Idiomatic Rust
The newtype pattern defines a distinct type, typically as a tuple struct containing an existing type, to add type information or behavior with minimal encapsulation.
- How it is used
- Adds semantic type information or safe conversions around data already represented by a primitive.
- How deep it goes
- Defines tuple-struct wrappers and demonstrates conversion methods, stopping at simple examples.
- Examples
- Uses BitCount and ByteCount around u32 values, converting between them by factors of eight.
- What you can do after
- Build it from scratch by wrapping a primitive in tuple structs and adding conversion methods.
Learn Haskell by Example
newtype is Haskell syntax for defining a distinct type with exactly one constructor containing exactly one field.
- How it is used
- Uses newtype to separate an associative-map representation from its operations and protect map invariants.
- How deep it goes
- Defines syntax, constructor hiding, and implementation patterns, but defers technical differences between newtype and data to an appendix.
- Examples
- Uses AssocMap over key-value lists, with member, alter, empty, delete, and insert operations.
- What you can do after
- Apply newtype and constructor hiding to build a representation-backed type whose invariants callers cannot bypass directly.
Related concepts
- orphan ruleaddresses · Rust's orphan rule restricts trait implementations so that either the trait or the implementing type must be local to the defining crate.
- type systemuses · A type system is a programming language’s set of rules and mechanisms for classifying values and expressions and constraining their valid uses and combinations.
- type aliascontrasts with · A type alias is a declaration that gives an existing type an alternative name without creating a distinct type or representation.
- tuple structuses · A tuple struct is a Rust struct whose unnamed fields are accessed by positional indices.
- tupleuses · A tuple is a finite, ordered collection of elements treated as a single composite value or record.
- structimplements · A struct is a composite data type or structure that groups related fields or values into a single unit.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.