The Rust Programming Language

264 Pages·2015·0.7 MB·English

by  The Rust Team

The Rust Programming Language
The Rust Team
2015-05-13
2
Contents
1 Introduction 11
1.1 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.2 A brief introduction to Rust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 Getting Started 15
2.1 Installing Rust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Hello, world! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3 Hello, Cargo! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3 Learn Rust 23
3.1 Guessing Game . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1.1 Set up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1.2 Processing a Guess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.1.3 Generating a secret number . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.4 Comparing guesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.1.5 Looping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1.6 Complete! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.2 Dining Philosophers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.3 Rust inside other languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.3.1 The problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.3.2 A Rust library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.3.3 Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.3.4 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3.3.5 Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3.3.6 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3
4 CONTENTS
4 Efective Rust 59
4.1 The Stack and the Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.1.1 Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.1.2 The Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.1.3 The Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.1.4 Arguments and borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
4.1.5 A complex example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
4.1.6 What do other languages do? . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.1.7 Which to use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.2 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.2.1 The test attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.2.2 The tests module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.2.3 The tests directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.2.4 Documentation tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.3 Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.3.1 cfg_attr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.3.2 cfg! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.4 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.5 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.6 Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.7 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.7.1 Failure vs. Panic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.7.2 Handling errors with Option and Result . . . . . . . . . . . . . . . . . . . 102
4.7.3 Non-recoverable errors with panic! . . . . . . . . . . . . . . . . . . . . . . 103
4.7.4 Upgrading failures to panics . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.7.5 Using try! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.8 FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.8.2 Creating a safe interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.8.3 Destructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.8.4 Callbacks from C code to Rust functions . . . . . . . . . . . . . . . . . . . 109
4.8.5 Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.8.6 Unsafe blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
CONTENTS 5
4.8.7 Accessing foreign globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.8.8 Foreign calling conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.8.9 Interoperability with foreign code . . . . . . . . . . . . . . . . . . . . . . . 114
4.8.10 The “nullable pointer optimization” . . . . . . . . . . . . . . . . . . . . . 115
4.8.11 Calling Rust code from C . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.9 Borrow and AsRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.9.1 Borrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
4.9.2 AsRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.9.3 Which should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.10 Release Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.10.2 Choosing a version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.10.3 Helping the ecosystem through CI . . . . . . . . . . . . . . . . . . . . . . 118
5 Syntax and Semantics 119
5.1 Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.3 Primitive Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.3.1 Booleans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.3.2 char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.3.3 Numeric types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.3.4 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.3.5 Slices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.3.6 str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.3.7 Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.3.8 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.4 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.5 if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
5.6 for loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.7 while loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
5.8 Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
5.8.1 Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
5.8.2 Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
5.8.3 Move semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6 CONTENTS
5.8.4 More than ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.9 References and Borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.9.1 Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.9.2 Borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.9.3 &mut references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
5.9.4 The Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5.10 Lifetimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.10.1 Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.10.2 Lifetimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.11 Mutability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.11.1 Interior vs. Exterior Mutability . . . . . . . . . . . . . . . . . . . . . . . . 151
5.12 Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.12.1 Update syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
5.12.2 Tuple structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.12.3 Unit-like structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5.13 Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5.14 Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.14.1 Matching on enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.15 Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.15.1 Multiple patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.15.2 Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.15.3 Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
5.15.4 Ignoring variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.15.5 Guards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.15.6 ref and ref mut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.15.7 Destructuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
5.15.8 Mix and Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.16 Method Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.16.1 Method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.16.2 Chaining method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.16.3 Associated functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.16.4 Builder Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
5.17 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
CONTENTS 7
5.18 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
5.19 Generics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
5.20 Traits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
5.20.1 Multiple trait bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.20.2 Where clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.20.3 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
5.21 Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
5.22 if let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
5.23 Trait Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
5.24 Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.24.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.24.2 Closures and their environment . . . . . . . . . . . . . . . . . . . . . . . . 189
5.24.3 Closure implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.24.4 Taking closures as arguments . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.24.5 Returning closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
5.25 Universal Function Call Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
5.25.1 Angle-bracket Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
5.26 Crates and Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
5.26.1 Basic terminology: Crates and Modules . . . . . . . . . . . . . . . . . . . 198
5.26.2 Defning Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.26.3 Multiple fle crates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
5.26.4 Importing External Crates . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.26.5 Exporting a Public Interface . . . . . . . . . . . . . . . . . . . . . . . . . 203
5.26.6 Importing Modules with use . . . . . . . . . . . . . . . . . . . . . . . . . . 204
5.27 const and static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
5.27.1 static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
5.27.2 Initializing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
5.27.3 Which construct should I use? . . . . . . . . . . . . . . . . . . . . . . . . 208
5.28 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
5.29 type aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
5.30 Casting between types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.30.1 as . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.30.2 transmute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
8 CONTENTS
5.31 Associated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
5.32 Unsized Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
5.32.1 ?Sized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
5.33 Operators and Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
5.34 Deref coercions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
5.35 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
5.35.1 Defning a macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
5.35.2 Hygiene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
5.35.3 Recursive macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
5.35.4 Debugging macro code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
5.35.5 Syntactic requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
5.35.6 Scoping and macro import/export . . . . . . . . . . . . . . . . . . . . . . 228
5.35.7 The variable $crate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
5.35.8 The deep end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
5.35.9 Common macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
5.35.10 Procedural macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.36 Raw Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.36.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.36.2 FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
5.36.3 References and raw pointers . . . . . . . . . . . . . . . . . . . . . . . . . . 234
5.37 unsafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
5.37.1 What does ‘safe’ mean? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
5.37.2 Unsafe Superpowers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
6 Nightly Rust 239
6.1 Compiler Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
6.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
6.1.2 Syntax extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
6.1.3 Lint plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
6.2 Inline Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
6.3 No stdlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
6.4 Intrinsics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
6.5 Lang items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
6.6 Link args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
CONTENTS 9
6.7 Benchmark Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
6.8 Box Syntax and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
6.8.1 Returning Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
6.9 Slice Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
6.10 Associated Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
7 Glossary 261
8 Academic Research 263
10 CONTENTS