2 n C d o v E e rs di R ti u s o Programming t 1. n 5 0 R ust Fast, Safe Systems Development Jim Blandy, Jason Orendorff & Leonora F. S. Tindall SECOND EDITION Programming Rust Fast, Safe Systems Development Jim Blandy, Jason Orendorff, and Leonora F.S. Tindall BBeeiijjiinngg BBoossttoonn FFaarrnnhhaamm SSeebbaassttooppooll TTookkyyoo Programming Rust by Jim Blandy, Jason Orendorff, and Leonora F.S. Tindall Copyright © 2021 Jim Blandy, Leonora F.S. Tindall, Jason Orendorff. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or [email protected]. Acquisitions Editor: Suzanne McQuade Indexer: Potomac Indexing, LLC Developmental Editor: Jeff Bleiel Interior Designer: David Futato Production Editor: Beth Kelly Cover Designer: Karen Montgomery Copyeditor: Charles Roumeliotis Illustrator: Kate Dullea Proofreader: Kim Wimpsett June 2021: Second Edition Revision History for the Second Edition 2021-06-11: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781492052593 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Programming Rust, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors, and do not represent the publisher’s views. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights. 978-1-492-05259-3 [LSI] Table of Contents Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv 1. Systems Programmers Can Have Nice Things. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Rust Shoulders the Load for You 2 Parallel Programming Is Tamed 3 And Yet Rust Is Still Fast 4 Rust Makes Collaboration Easier 4 2. A Tour of Rust. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 rustup and Cargo 6 Rust Functions 8 Writing and Running Unit Tests 10 Handling Command-Line Arguments 11 Serving Pages to the Web 15 Concurrency 22 What the Mandelbrot Set Actually Is 23 Parsing Pair Command-Line Arguments 28 Mapping from Pixels to Complex Numbers 30 Plotting the Set 32 Writing Image Files 33 A Concurrent Mandelbrot Program 35 Running the Mandelbrot Plotter 40 Safety Is Invisible 41 Filesystems and Command-Line Tools 42 The Command-Line Interface 43 Reading and Writing Files 45 Find and Replace 46 iii 3. Fundamental Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Fixed-Width Numeric Types 52 Integer Types 53 Checked, Wrapping, Saturating, and Overflowing Arithmetic 56 Floating-Point Types 58 The bool Type 61 Characters 61 Tuples 63 Pointer Types 65 References 65 Boxes 66 Raw Pointers 66 Arrays, Vectors, and Slices 67 Arrays 67 Vectors 68 Slices 71 String Types 73 String Literals 73 Byte Strings 74 Strings in Memory 74 String 76 Using Strings 77 Other String-Like Types 77 Type Aliases 78 Beyond the Basics 78 4. Ownership and Moves. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Ownership 81 Moves 85 More Operations That Move 90 Moves and Control Flow 91 Moves and Indexed Content 92 Copy Types: The Exception to Moves 94 Rc and Arc: Shared Ownership 98 5. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 References to Values 102 Working with References 105 Rust References Versus C++ References 105 Assigning References 107 References to References 107 Comparing References 108 iv | Table of Contents References Are Never Null 109 Borrowing References to Arbitrary Expressions 109 References to Slices and Trait Objects 110 Reference Safety 110 Borrowing a Local Variable 110 Receiving References as Function Arguments 113 Passing References to Functions 115 Returning References 116 Structs Containing References 117 Distinct Lifetime Parameters 120 Omitting Lifetime Parameters 121 Sharing Versus Mutation 123 Taking Arms Against a Sea of Objects 130 6. Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 An Expression Language 133 Precedence and Associativity 134 Blocks and Semicolons 137 Declarations 138 if and match 140 if let 142 Loops 142 Control Flow in Loops 144 return Expressions 145 Why Rust Has loop 146 Function and Method Calls 148 Fields and Elements 149 Reference Operators 151 Arithmetic, Bitwise, Comparison, and Logical Operators 151 Assignment 152 Type Casts 153 Closures 154 Onward 154 7. Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Panic 157 Unwinding 158 Aborting 159 Result 160 Catching Errors 160 Result Type Aliases 162 Printing Errors 163 Table of Contents | v Propagating Errors 164 Working with Multiple Error Types 166 Dealing with Errors That “Can’t Happen” 168 Ignoring Errors 169 Handling Errors in main() 169 Declaring a Custom Error Type 171 Why Results? 172 8. Crates and Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Crates 173 Editions 176 Build Profiles 177 Modules 178 Nested Modules 179 Modules in Separate Files 180 Paths and Imports 183 The Standard Prelude 186 Making use Declarations pub 186 Making Struct Fields pub 186 Statics and Constants 187 Turning a Program into a Library 188 The src/bin Directory 189 Attributes 191 Tests and Documentation 193 Integration Tests 196 Documentation 197 Doc-Tests 199 Specifying Dependencies 202 Versions 202 Cargo.lock 204 Publishing Crates to crates.io 205 Workspaces 207 More Nice Things 208 9. Structs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Named-Field Structs 209 Tuple-Like Structs 212 Unit-Like Structs 213 Struct Layout 213 Defining Methods with impl 214 Passing Self as a Box, Rc, or Arc 217 Type-Associated Functions 219 vi | Table of Contents Associated Consts 220 Generic Structs 221 Structs with Lifetime Parameters 223 Deriving Common Traits for Struct Types 224 Interior Mutability 225 10. Enums and Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Enums 230 Enums with Data 232 Enums in Memory 233 Rich Data Structures Using Enums 234 Generic Enums 236 Patterns 239 Literals, Variables, and Wildcards in Patterns 242 Tuple and Struct Patterns 243 Array and Slice Patterns 244 Reference Patterns 245 Match Guards 247 Matching Multiple Possibilities 248 Binding with @ Patterns 248 Where Patterns Are Allowed 249 Populating a Binary Tree 250 The Big Picture 252 11. Traits and Generics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Using Traits 255 Trait Objects 256 Generic Functions and Type Parameters 258 Which to Use 261 Defining and Implementing Traits 264 Default Methods 265 Traits and Other People’s Types 266 Self in Traits 268 Subtraits 269 Type-Associated Functions 270 Fully Qualified Method Calls 271 Traits That Define Relationships Between Types 273 Associated Types (or How Iterators Work) 273 Generic Traits (or How Operator Overloading Works) 277 impl Trait 278 Associated Consts 280 Reverse-Engineering Bounds 281 Table of Contents | vii Traits as a Foundation 284 12. Operator Overloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Arithmetic and Bitwise Operators 286 Unary Operators 289 Binary Operators 290 Compound Assignment Operators 291 Equivalence Comparisons 292 Ordered Comparisons 295 Index and IndexMut 298 Other Operators 300 13. Utility Traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Drop 302 Sized 305 Clone 308 Copy 309 Deref and DerefMut 310 Default 313 AsRef and AsMut 315 Borrow and BorrowMut 316 From and Into 318 TryFrom and TryInto 321 ToOwned 322 Borrow and ToOwned at Work: The Humble Cow 323 14. Closures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Capturing Variables 327 Closures That Borrow 328 Closures That Steal 328 Function and Closure Types 330 Closure Performance 332 Closures and Safety 333 Closures That Kill 334 FnOnce 334 FnMut 336 Copy and Clone for Closures 338 Callbacks 339 Using Closures Effectively 343 15. Iterators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 The Iterator and IntoIterator Traits 347 viii | Table of Contents