The Rust Programming Language

335 Pages·2016·0.94 MB·English

by  The Rust Team

The Rust Programming Language
The Rust Team
2016-10-01
2
Contents
1 Introduction 11
Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2 Getting Started 13
Installing Rust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Hello, world! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Hello, Cargo! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Closing Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3 Tutorial: Guessing Game 25
Set up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Processing a Guess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Generating a secret number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Comparing guesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Looping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Complete! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4 Syntax and Semantics 43
Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Type annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Mutability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Initializing bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Scope and shadowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Primitive Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Booleans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4 CONTENTS
char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Numeric types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Slices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Move semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
More than ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
References and Borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
&mut references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
The Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Lifetimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Lifetimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
In structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Mutability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Interior vs. Exterior Mutability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Update syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Tuple structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Unit-like structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Constructors as functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
CONTENTS 5
Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Matching on enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Multiple patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Destructuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Ignoring bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
ref and ref mut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Guards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Mix and Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Method Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Chaining method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Associated functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Builder Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Generics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Traits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Rules for implementing traits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Multiple trait bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Where clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Default methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Deriving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
if let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Trait Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Closures and their environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Closure implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Taking closures as arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6 CONTENTS
Function pointers and closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Returning closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Universal Function Call Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Angle-bracket Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Crates and Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Basic terminology: Crates and Modules . . . . . . . . . . . . . . . . . . . . . . . 142
Defning Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Multiple File Crates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Importing External Crates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Exporting a Public Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Importing Modules with use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
const and static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Initializing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Which construct should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
type aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Casting between types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Coercion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
as . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
transmute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Associated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Unsized Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
?Sized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Operators and Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Using operator traits in generic structs . . . . . . . . . . . . . . . . . . . . . . . . 164
Deref coercions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Defning a macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Hygiene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Recursive macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Debugging macro code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Syntactic requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
CONTENTS 7
Scoping and macro import/export . . . . . . . . . . . . . . . . . . . . . . . . . . 176
The variable $crate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
The deep end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Common macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Procedural macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Raw Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
References and raw pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
unsafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
What does ‘safe’ mean? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Unsafe Superpowers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
5 Efective Rust 187
The Stack and the Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
The Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
The Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Arguments and borrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
A complex example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
What do other languages do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Which to use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
The test attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
The ignore attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
The tests module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
The tests directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Documentation tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
cfg_attr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
cfg! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8 CONTENTS
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
The Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Working with multiple error types . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Standard library traits used for error handling . . . . . . . . . . . . . . . . . . . . 252
Case study: A program to read population data . . . . . . . . . . . . . . . . . . . 259
The Short Story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Choosing your Guarantees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Basic pointer types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Cell types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Synchronous types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
FFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Creating a safe interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Destructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Callbacks from C code to Rust functions . . . . . . . . . . . . . . . . . . . . . . . 283
Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Unsafe blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Accessing foreign globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Foreign calling conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Interoperability with foreign code . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
The “nullable pointer optimization” . . . . . . . . . . . . . . . . . . . . . . . . . 288
Calling Rust code from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
FFI and panics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Representing opaque structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Borrow and AsRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Borrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
AsRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Which should I use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Release Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Choosing a version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Helping the ecosystem through CI . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Using Rust without the standard library . . . . . . . . . . . . . . . . . . . . . . . . . . 294
CONTENTS 9
6 Nightly Rust 297
Compiler Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Syntax extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Lint plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Inline Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
No stdlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Intrinsics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Lang items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Advanced linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Link args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Static linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Benchmark Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Box Syntax and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Returning Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Slice Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Associated Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Custom Allocators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Default Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Switching Allocators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Writing a custom allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Custom allocator limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
7 Glossary 325
8 Syntax Index 327
9 Bibliography 333
10 CONTENTS