Idiomatic Rust: Code like a Rustacean

Rust Advanced Techniques....1

brief contents....7

contents....8

preface....13

acknowledgments....14

about this book....16

How is this book different?....16

Who should read this book?....17

How this book is organized....17

How to read this book....17

About the code....18

liveBook discussion forum....19

about the author....20

about the cover illustration....21

Part 1—Building blocks....23

1 Rust-y patterns....25

1.1 What this book covers....26

1.2 What design patterns are....27

1.3 Why this book is different....30

1.4 Tools you’ll need....31

Summary....31

2 Rust’s basic building blocks....32

2.1 Generics....33

2.1.1 A Turing-complete type system....33

2.1.2 Why generics?....34

2.1.3 Basics of generics....34

2.1.4 Exploring Rust’s Option....37

2.1.5 Marker structs and phantom types....37

2.1.6 Generic parameter trait bounds....40

2.2 Traits....40

2.2.1 Why traits are not object-oriented programming....41

2.2.2 What’s in a trait?....41

2.2.3 Understanding traits by examining object-oriented code....43

2.2.4 Combining generics and traits....46

2.2.5 Deriving traits automatically....50

2.2.6 Trait objects....51

Summary....54

3 Code flow....56

3.1 A tour of pattern matching....57

3.1.1 Basics of pattern matching....57

3.1.2 Clean matches with the ? operator....62

3.2 Functional Rust....65

3.2.1 Basics of functional programming in Rust....65

3.2.2 Closure variable capture....67

3.2.3 Examining iterators....68

3.2.4 Obtaining an iterator with iter(), into_iter(), and iter_mut()....72

3.2.5 Iterator features....80

Summary....83

Part 2—Core patterns....85

4 Introductory patterns....87

4.1 Resource acquisition is initialization....88

4.1.1 Understanding RAII in C and C++....88

4.1.2 A tour of RAII in Rust....92

4.1.3 Summarizing RAII in Rust....94

4.2 Passing arguments by value vs. reference....96

4.2.1 Passing by value....96

4.2.2 Passing by reference....97

4.2.3 When to do what: Passing by value vs. reference....99

4.3 Constructors....100

4.4 Object-member visibility and access....102

4.5 Error handling....104

4.6 Global state....107

4.6.1 lazy-static.rs....109

4.6.2 once_cell....110

4.6.3 static_init....111

4.6.4 std::cell::OnceCell....111

Summary....112

5 Design patterns: Beyond the basics....113

5.1 Metaprogramming with macros....114

5.1.1 A basic declarative macro in Rust....115

5.1.2 When to use macros....116

5.1.3 Using macros to write mini-DSLs....121

5.1.4 Using macros for DRY....122

5.2 Optional function arguments....125

5.2.1 Examining optional arguments in Python....125

5.2.2 Examining optional arguments in C++....126

5.2.3 Optional arguments in Rust or the lack thereof....126

5.2.4 Emulating optional arguments with traits....126

5.3 Builder pattern....129

5.3.1 Implementing the builder pattern....129

5.3.2 Enhancing our builder with traits....131

5.3.3 Enhancing our builder with macros....132

5.4 Fluent interface pattern....135

5.4.1 A fluent builder....136

5.4.2 Test-driving our fluent builder....139

5.5 Observer pattern....139

5.5.1 Why not callbacks?....139

5.5.2 Implementing an observer....140

5.6 Command pattern....143

5.6.1 Defining the command pattern....143

5.6.2 Implementing the command pattern....143

5.7 Newtype pattern....146

Summary....149

6 Designing a library....150

6.1 Meditate on good library design....151

6.2 Do one thing, do it well, and do it correctly....151

6.3 Avoid excessive abstraction....152

6.4 Stick to basic types....152

6.5 Use the tools....153

6.6 Good artists copy; great artists steal (from the standard library)....154

6.7 Document everything, and provide examples....154

6.8 Don’t break the user’s code....154

6.9 Think of the state....155

6.10 Consider the aesthetics....156

6.11 Examining Rust library ergonomics....156

6.11.1 Revisiting linked lists....156

6.11.2 Using rustdoc to improve our API design....157

6.11.3 Improving our linked list with more tests....165

6.11.4 Making our library easier for others to debug....167

Summary....169

Part 3—Advanced patterns....171

7 Using traits, generics, and structs for specialized tasks....173

7.1 Const generics....174

7.2 Implementing traits for external crate types....176

7.2.1 Wrapper structs....176

7.2.2 Using Deref to unwrap a wrapped struct....176

7.3 Extension traits....177

7.4 Blanket traits....179

7.5 Marker traits....181

7.6 Struct tagging....183

7.7 Reference objects....185

Summary....190

8 State machines, coroutines, macros, and preludes....191

8.1 Trait state machine....192

8.2 Coroutines....195

8.3 Procedural macros....200

8.4 Preludes....204

Summary....207

Part 4—Problem avoidance....209

9 Immutability....211

9.1 The benefits of immutability....212

9.2 Why immutability is not a magic bullet....214

9.3 How to think about immutable data....214

9.4 Understanding immutability in Rust....215

9.5 Reviewing the basics of immutability in Rust....216

9.6 Using traits to make (almost) anything immutable....219

9.7 Using Cow for immutability....220

9.8 Using crates for immutable data structures....223

9.8.1 Using im....223

9.8.2 Using rpds....224

Summary....225

10 Antipatterns....227

10.1 What is an antipattern?....228

10.2 Using unsafe....229

10.2.1 What does unsafe do?....230

10.2.2 Where can you use unsafe?....231

10.2.3 When should you use unsafe?....233

10.2.4 Should you worry about unsafe?....233

10.3 Using unwrap()....234

10.4 Not using Vec....234

10.5 Too many clones....238

10.6 Using Deref to emulate polymorphism....239

10.7 Global data and singletons....243

10.8 Too many smart pointers....243

10.9 Where to go from here....245

Summary....245

appendix—Installing Rust....247

A.1 Installing tools for this book....247

A.1.1 Installing tools for macOS using Homebrew....247

A.1.2 Installing tools for Linux systems....247

A.1.3 Installing tools for Windows....248

A.2 Managing rustc and other Rust components with rustup....248

A.2.1 Installing rustc and other components....248

A.2.2 Switching default toolchains with rustup....248

A.2.3 Updating Rust components....249

index....251

Symbols....251

A....251

B....251

C....251

D....252

E....252

F....252

G....253

H....253

I....253

J....253

K....253

L....253

M....253

N....254

O....254

P....254

Q....254

R....254

S....255

T....255

U....255

V....255

W....256

Y....256

Z....256

Whether you’re a Rust beginner or a pro, Idiomatic Rust will teach you to be a better Rust programmer. It introduces essential design patterns for Rust software with detailed explanations, and code samples that encourage you to get stuck in.

In Idiomatic Rust you’ll learn how to apply important design patterns including:

• Fluent interfaces for creating delightful APIs
• The Builder pattern to encapsulate data and perform initialization
• Immutable data structures that help you avoid hard-to-debug data race conditions
• Functional programming patterns
• Anti-patterns and what not to do in Rust

Idiomatic Rust catalogs, documents, and describes both how classic design patterns work with Rust, and the new Rust-specific patterns that will help you master the language. Each pattern or best practice helps solve common programming problems and ensure your code is easy for others to understand. You’ll learn when to use each pattern—and when to break it! You’ll soon be producing higher-quality Rust code and higher-quality Rust software.

About the technology

After you’re comfortable with Rust’s syntax and its uniquely-powerful compiler, there’s a whole new dimension to explore as you put it to use in real projects. How do you apply standard design patterns in Rust applications? Where and why should you use IntoIterator? Why do Rustaceans love the PhantomData type? This book answers these questions and many, many more.

About the book

Idiomatic Rust introduces the coding and design patterns you’ll need to take advantage of Rust’s unique language design. This book’s clear explanations and reusable code examples help you explore metaprogramming, build your own libraries, create fluent interfaces, and more. Along the way, you’ll learn how to write efficient, idiomatic Rust code that’s easy to maintain and evolve as you learn how the language works under the hood.