Effective Rust: 35 Specific Ways to Improve Your Rust Code

Preface....5 Who This Book Is For....5 Rust Version....7 Navigating This Book....7 Conventions Used in This Book....8 O’Reilly Online Learning....9 How to Contact Us....10 Acknowledgments....11 1. Types....12 Item 1: Use the type system to express your data structures....12 Fundamental Types....12 Aggregate Types....14 enums....15 enums with Fields....16 Ubiquitous enum Types....17 Item 2: Use the type system to express common behavior....18 Functions and Methods....19 Function Pointers....20 Closures....21 Traits....24 Item 3: Prefer Option and Result transforms over explicit match expressions....26 Things to Remember....31 Item 4: Prefer idiomatic Error types....31 The Error Trait....31 Minimal Errors....32 Nested Errors....33 Trait Objects....35 Libraries Versus Applications....36 Things to Remember....37 Item 5: Understand type conversions....37 User-Defined Type Conversions....38 Casts....41 Coercion....41 Item 6: Embrace the newtype pattern....42 Bypassing the Orphan Rule for Traits....44 Newtype Limitations....45 Item 7: Use builders for complex types....46 Item 8: Familiarize yourself with reference and pointer types....51 Rust References....52 Pointer Traits....54 Fat Pointer Types....55 More Pointer Traits....59 Smart Pointer Types....60 Item 9: Consider using iterator transforms instead of explicit loops....63 Iterator Traits....65 Iterator Transforms....67 Iterator Consumers....68 Building Collections from Result Values....71 Loop Transformation....72 When Explicit Is Better....74 2. Traits....76 Item 10: Familiarize yourself with standard traits....76 Common Standard Traits....76 Standard Traits Covered Elsewhere....82 Operator Overloads....83 Summary....84 Item 11: Implement the Drop trait for RAII patterns....87 Item 12: Understand the trade-offs between generics and trait objects....90 Generics....91 Trait Objects....92 Basic Comparisons....93 More Trait Bounds....94 Trait Object Safety....96 Trade-Offs....97 Item 13: Use default implementations to minimize required trait methods....98 3. Concepts....100 Item 14: Understand lifetimes....100 Introduction to the Stack....100 Evolution of Lifetimes....102 Scope of a Lifetime....104 Algebra of Lifetimes....106 Lifetime Elision Rules....108 The 'static Lifetime....109 Lifetimes and the Heap....111 Lifetimes in Data Structures....111 Anonymous Lifetimes....113 Things to Remember....114 Item 15: Understand the borrow checker....114 Access Control....115 Borrow Rules....116 Owner Operations....118 Winning Fights Against the Borrow Checker....120 Things to Remember....129 Item 16: Avoid writing unsafe code....129 Item 17: Be wary of shared-state parallelism....131 Data Races....132 Deadlocks....139 Advice....142 Item 18: Don’t panic....143 Item 19: Avoid reflection....145 Upcasting in Future Versions of Rust....151 Item 20: Avoid the temptation to over-optimize....151 Data Structures and Allocation....151 Who’s Afraid of the Big Bad Copy?....154 References and Smart Pointers....155 4. Dependencies....157 Item 21: Understand what semantic versioning promises....157 Semver Essentials....158 Semver for Crate Authors....159 Semver for Crate Users....161 Discussion....161 Item 22: Minimize visibility....162 Visibility Syntax....162 Visibility Semantics....164 Item 23: Avoid wildcard imports....165 Item 24: Re-export dependencies whose types appear in your API....167 Item 25: Manage your dependency graph....169 Version Specification....171 Solving Problems with Tooling....171 What to Depend On....173 Things to Remember....173 Item 26: Be wary of feature creep....174 Conditional Compilation....174 Features....174 Things to Remember....177 5. Tooling....179 Item 27: Document public interfaces....179 Tooling....180 Additional Documentation Locations....180 Published Crate Documentation....181 What Not to Document....181 Things to Remember....183 Item 28: Use macros judiciously....183 Declarative Macros....184 Procedural Macros....188 When to Use Macros....191 Disadvantages of Macros....193 Advice....194 Item 29: Listen to Clippy....195 Item 30: Write more than unit tests....198 Unit Tests....198 Integration Tests....199 Doc Tests....199 Examples....200 Benchmarks....200 Fuzz Testing....201 Testing Advice....203 Things to Remember....204 Item 31: Take advantage of the tooling ecosystem....204 Tools to Remember....205 Item 32: Set up a continuous integration (CI) system....206 CI Steps....206 CI Principles....208 Public CI Systems....209 6. Beyond Standard Rust....211 Item 33: Consider making library code no_std compatible....211 core....211 alloc....212 Writing Code for no_std....213 Fallible Allocation....214 Things to Remember....215 Item 34: Control what crosses FFI boundaries....215 Invoking C Functions from Rust....216 Accessing C Data from Rust....219 Lifetimes....220 Invoking Rust from C....222 Things to Remember....225 Item 35: Prefer bindgen to manual FFI mappings....225 Beyond C....227 Afterword....228 Index....230 About the Author....311