Rust Programming Language

Rust Programming language
A comprehensive beginner's guide to Rust
3nd edition
2021
By Claudia Alves
"Programming isn't about what you know; it's about what you can
figure out.” - Chris Pine
.
Memlnc.com
WHY LEARN A NEW PROGRAMMING LANGUAGE?..............................................................12

WHERE RUST SHINES............................................................................................................13
SETTING UP...........................................................................................................................15
CHAPTER I________________________________________________________________22
FIRST STEPS............................................................................................................................22
HELLO WORLD! .....................................................................................................................23
HELLO, CARGO! .....................................................................................................................27
MIGRATING IN CHARGE.........................................................................................................28
A NEW PROJECT.....................................................................................................................32
CHAPTER II________________________________________________________________35
LEARN RUST............................................................................................................................35
INITIAL SETUP..........................................................................................................................35
PROCESSING A RIDDLE ATTEMPT............................................................................................37
GENERATING A SECRET NUMBER...........................................................................................45
COMPARING RIDDLES.............................................................................................................51
ITERATION...............................................................................................................................58
COMPLETED! ..........................................................................................................................68
RUST WITHIN OTHER LANGUAGES..........................................................................................90
THE PROBLEM.........................................................................................................................91
A RUST LIBRARY......................................................................................................................93
RUBY........................................................................................................................................97
PYTHON...................................................................................................................................99
NODE.JS.................................................................................................................................100
$ NPM INSTALL FFI................................................................................................................100
CHAPTER III______________________________________________________________102
RUST CASH..........................................................................................................................,102
THE STACK AND THE MOUND..............................................................................................103
MEMORY MANAGEMENT.....................................................................................................103
THE BATTERY........................................................................................................................103
THE MOUND.........................................................................................................................108
ARGUMENTS AND BORROWING...........................................................................................111
A COMPLEX EXAMPLE...........................................................................................................112
WHAT DO OTHER LANGUAGES DO? ....................................................................................118
WHICH TO USE......................................................................................................................119
EXECUTION TIME EFFICIENCY. .............................................................................................119
SEMANTIC IMPACT...............................................................................................................119
TESTS...........................................................................................................,………………………120
THE TEST ATTRIBUTE.............................................................................................................120
THE TESTS MODULE..............................................................................................................127
THE TESTS DIRECTORY...........................................................................................................129
DOCUMENTATION TESTS......................................................................................................131
[CFG (TEST)] ..........................................................................................................................131
CONDITIONAL COMPILATION................................................................................................133
CFG_ATTR..............................................................................................................................135
CFG! ......................................................................................................................................135
DOCUMENTATION................................................................................................................135
ABOUT RUSTDOC..................................................................................................................135
DOCUMENTING SOURCE CODE.............................................................................................136
WRITING DOCUMENTATION COMMENTS............................................................................137
SPECIAL SECTIONS.................................................................................................................138
FN FOO () {}...........................................................................................................139
FN FOO () {}...........................................................................................................139
FN FOO () {}...........................................................................................................140
FN FOO () {}...........................................................................................................140
FN FOO () {}...........................................................................................................141
FN FOO () {}...........................................................................................................141
DOCUMENTING MACROS......................................................................................144
[MACRO_EXPORT] ................................................................................................144
FN MAIN () {}...........................................................................................................145
FN FOO () {}...........................................................................................................145
FN FOO () {}...........................................................................................................146
FN FOO () {}...........................................................................................................146
DOCUMENTATION FEEDBACK
STYLE…………………………………………………………………148
OTHER DOCUMENTATION.....................................................................................148
FN FOO () {}...........................................................................................................149
DOC ATTRIBUTES...................................................................................................149
RE-EXPORTS...........................................................................................................150
CONTROLLING HTML..............................................................................................150
GENERATION OPTIONS...........................................................................................151
SAFETY NOTE...........................................................................................................151
CONSUMERS...........................................................................................................154
ITERATORS...............................................................................................................157
ITERATOR ADAPTERS................................................................................................158
CONCURRENCE..........................................................................................................159
THREADS...................................................................................................................160
MUTABLE STATE SHARED SAFE.................................................................................161
CHANNELS................................................................................................................166
PANICS......................................................................................................................168
ERROR HANDLING.....................................................................................................169
FAIL VS. PANIC...........................................................................................................169
HANDLING ERRORS WITH OPTION AND
RESULT…………………………………………………….173
UNRECOVERABLE ERRORS WITH PANIC! ..................................................................175
PROMOTING PANIC FAILURES....................................................................................175
USING TRY! .................................................................................................................176
FOREIGN / EXTERNAL FUNCTION INTERFACE.............................................................179
INTRODUCTION...........................................................................................................180
CREATING A SECURE INTERFACE.................................................................................182
DESTROYERS................................................................................................................186
CALLBACKS FROM C CODE TO RUST
FUNCTIONS……………………………………………………..187
AIMING CALLBACKS AT RUST
OBJECTS…………………………………………………………………….188
ASYNCHRONOUS CALLBACKS.......................................................................................191
LINK...........................................................................................................,,……………….191
UNSAFE BLOCKS...........................................................................................................193
ACCESSING EXTERNAL GLOBALS...................................................................................193
FOREIGN CALLING CONVENTIONS................................................................................195
INTEROPERABILITY WITH EXTERNAL
CODE……………………………………………………………….196
THE "NULL POINTER OPTIMIZATION"............................................................................197
CALLING CODING RUST FROM C.....................................................................................197

FFI AND PANICS..............................................................................................................198
BORROW........................................................................................................................199
ASREF.............................................................................................................................200
WHICH ONE SHOULD YOU USE? ....................................................................................201
OVERVIEW..........................................................................................................................201
CHOOSING A VERSION.......................................................................................................202
HELPING THE ECOSYSTEM THROUGH CI............................................................................202
CHAPTER IV_____________________________________________________________202
SYNTAX AND SEMANTICS...................................................................................................202
VARIABLE LINKS..................................................................................................................203
FEATURES............................................................................................................................207
EXPRESSIONS VS. SENTENCES.............................................................................................210
EARLY RETURNS...................................................................................................................211
DIVERGENT FUNCTIONS.......................................................................................................212
FUNCTION POINTERS...........................................................................................................213
PRIMITIVE TYPES..................................................................................................................214
BOOLEAN.............................................................................................................................214
CHAR....................................................................................................................................214
NUMERICAL TYPES...............................................................................................................215
SIGNED AND UNSIGNED.......................................................................................................216
FIXED SIZE TYPES..................................................................................................................216
VARIABLE SIZE TYPES...........................................................................................................216
FLOATING POINT TYPES.......................................................................................................216
ARRANGEMENTS.................................................................................................................216
SLICES..................................................................................................................................217
TUPLES.................................................................................................................................218
INDEXED IN TUPLES.............................................................................................................220
FEATURES.............................................................................................................................220
COMMENTS..........................................................................................................................221
IF...........................................................................................................................................222
CYCLES...........................................................................................................................224
LOOP..............................................................................................................................224
WHILE.............................................................................................................................225
FOR.................................................................................................................................226
ENDING THE ITERATION EARLY.......................................................................................228
LOOP TAGS......................................................................................................................229
BELONGING.....................................................................................................................230
GOAL...............................................................................................................................230
BELONGING.....................................................................................................................231
MOTION SEMANTICS.......................................................................................................232
THE DETAILS....................................................................................................................233
COPY TYPES.....................................................................................................................234
MORE THAN BELONGING................................................................................................236
REFERENCES AND LOAN..................................................................................................237
GOAL................................................................................................................................237
LOAN................................................................................................................................238
REFERENCES & MUT.........................................................................................................240
THE RULES..........................................................................................................................242
THINKING ABOUT SCOPES.................................................................................................242
PROBLEMS THAT THE LOAN PREVENTS.............................................................................244
ITERATOR INVALIDATION...................................................................................................244
USE AFTER RELEASE...........................................................................................................246
LIFE TIMES..........................................................................................................................249
GOAL..................................................................................................................................250
LIFE TIMES..........................................................................................................................250
IN STRUCT S.......................................................................................................................252
IMPL BLOCKS......................................................................................................................253
MULTIPLE LIFE TIME...........................................................................................................254
THINKING ABOUT SCOPES...................................................................................................255
'STATIC.................................................................................................................................257
LIFE TIMES ELISION..............................................................................................................257
EXAMPLES...........................................................................................................................258
MUTABILITY.........................................................................................................................261
INTERNAL MUTABILITY VS. EXTERIOR
MUTABILITY…………………………………………………………262
FIELD LEVEL MUTABILITY.....................................................................................................264
STRUCTURES........................................................................................................................265
UPDATE SYNTAX...................................................................................................................268
TUPLE STRUCTURES (TUPLE STRUCTS) ................................................................................269
UNIT-LIKE STRUCTS...............................................................................................................271
ENUMERATIONS...................................................................................................................271
CONSTRUCTORS AS FUNCTIONS...........................................................................................273
MATCH..................................................................................................................................274
MAKING MATCH IN ENUMS..................................................................................................276
VECTOR.................................................................................................................................277
ACCESSING ELEMENTS..........................................................................................................278
ITERATING.............................................................................................................................278
CHARACTER STRINGS............................................................................................................279
INDEXED................................................................................................................................281
SLICING..................................................................................................................................282
CONCATENATION..................................................................................................................283
GENERIC................................................................................................................................283
GENERIC FUNCTIONS............................................................................................................285
GENERIC STRUCTURES.......................................................................................................286
TRAITS................................................................................................................................287
TRAIT LIMITS FOR GENERIC FUNCTIONS............................................................................289

TRAIT LIMITS FOR GENERIC STRUCTURES...........................................................................292
RULES FOR THE IMPLEMENTATION OF TRAITS...................................................................294
MULTIPLE TRAIT LIMITS.......................................................................................................296
THE WHERE CLAUSE.............................................................................................................297
DEFAULT METHODS..............................................................................................................300
HERITAGE..............................................................................................................................302
DROP.....................................................................................................................................303
IF LET.....................................................................................................................................305
WHILE LET.............................................................................................................................307
TRAIT OBJECTS......................................................................................................................308
BASES....................................................................................................................................308
STATIC DISPATCH..................................................................................................................309
DYNAMIC DISPATCH.............................................................................................................311
WHY POINTERS? ...................................................................................................................313
REPRESENTATION..................................................................................................................313
OBJECT SECURITY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . …………...318
CLOSURES..............................................................................................................................319
SYNTAX..................................................................................................................................319
CLOSURES AND ITS SURROUNDINGS....................................................................................320
CLOSURES MOVE...................................................................................................................323
IMPLEMENTATION OF CLOSURES.........................................................................................324
RECEIVING CLOSURES AS ARGUMENTS................................................................................326
FUNCTION POINTERS AND CLOSURES. . . . . . . . . . . . . . . . . . ... . . .. . . . . . . . . . . . . …………..
.328
RETURNING CLOSURES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Why learn a new Programming Language?

As Einstein might have said, "As gentle as possible, but no gentler.". There is
a lot of new stuff to learn here, and it's different enough to require some
rearrangement of your mental furniture. By 'gentle' I mean that the features
are presented practically with examples; as we encounter difficulties, I hope
to show how Rust solves these problems. It is important to understand the
problems before the solutions make sense. To put it in flowery language, we
are going for a hike in hilly country and I will point out some interesting rock
formations on the way, with only a few geology lectures. There will be some
uphill but the view will be inspiring; the community is unusually pleasant and
happy to help. There is the Rust Users Forum and an active subreddit which
is unusually well-moderated. The FAQ is a good resource if you have
specific questions.
First, why learn a new programming language? It is an investment of time

and energy and that needs some justification. Even if you do not immediately
land a cool job using that language, it stretches the mental muscles and makes
you a better programmer. That seems a poor kind of return-on-investment but
if you're not learning something genuinely new all the time then you will
stagnate and be like the person who has ten years of experience in doing the
same thing over and over.
Where Rust Shines
Rust is a statically and strongly typed systems programming language.

statically means that all types are known at compile-time, strongly means that
these types are designed to make it harder to write incorrect programs. A
successful compilation means you have a much better guarantee of
correctness than with a cowboy language like C. systems means generating
the best possible machine code with full control of memory use. So the uses
are pretty hardcore: operating systems, device drivers and embedded systems
that might not even have an operating system. However, it's actually a very
pleasant language to write normal application code in as well.
The big difference from C and C++ is that Rust is safe by default; all
memory accesses are checked. It is not possible to corrupt memory by
accident.
The unifying principles behind Rust are:
- strictly enforcing safe borrowing of data

- functions, methods and closures to operate on data
- tuples, structs and enums to aggregate data
- pattern matching to select and destructure data
- traits to define behaviour on data
There is a fast-growing ecosystem of available libraries through Cargo but

here we will concentrate on the core principles of the language by learning to
use the standard library. My advice is to write lots of small programs, so
learning to use rustc directly is a core skill. When doing the examples in this
tutorial I defined a little script called rrun which does a compilation and runs
the result:
rustc $1.rs && ./$1

Setting Up
This tutorial assumes that you have Rust installed locally. Fortunately this is
very straightforward.
$ curl https://sh.rustup.rs -sSf | sh

$ rustup component add rust-docs
I would recommend getting the default stable version; it's easy to download
unstable versions later and to switch between.
This gets the compiler, the Cargo package manager, the API documentation,
and the Rust Book. The journey of a thousand miles starts with one step, and
this first step is painless.
rustup is the command you use to manage your Rust installation. When a new
stable release appears, you just have to say rustup update to upgrade. rustup
doc will open the offline documentation in your browser.
You will probably already have an editor you like, and basic Rust support is
good. I'd suggest you start out with basic syntax highlighting at first, and
work up as your programs get larger.
Personally I'm a fan of Geany which is one of the few editors with Rust
support out-of-the-box; it's particularly easy on Linux since it's available
through the package manager, but it works fine on other platforms.
The main thing is knowing how to edit, compile and run Rust programs. You
learn to program with your fingers; type in the code yourself, and learn to
rearrange things efficiently with your editor.
Is Rust a language that you would be interested in? Let's examine a few small
code examples that demonstrate some of its strengths.
The main concept that makes Rust unique is called 'ownership'. Consider this
little example:
fn main ( ) {
let mut x = vec! [ "Hello" , "world" ];
}
This program creates a variable called x . The value of this variable is Vec
<T> , a 'vector', which we create through a macro defined in the standard
library. This macro is called vec , macros are invoked with a ! . All this
following a general principle in Rust: make things explicit. Macros can do
significantly more complex things than function calls, which is why they are
visually different. The ! It also helps parsing, making writing tools easier,
which is also important.
We have used mut to make x mutable: In Rust the variables are immutable
by default. Later in this example we will be mutating this vector.
It's important to mention that we don't need a type annotation here: while
Rust is statically typed, we don't need to explicitly annotate the type. Rust has
type inference to balance the power of static typing with the verbosity of type
annotations.
Rust prefers memory allocation from the stack than from the mound: x is put
directly on the stack. However, the Vec <T> type allocates space for the vector
elements on the mound. If you are not familiar with this distinction you can
ignore it for now or take a look at 'The Stack and the Mound' . Rust as a
system programming language gives you the ability to control how memory
is allocated, but how we are getting started is not that relevant.
Earlier we mentioned that 'membership' is a new key concept in Rust. In Rust

terminology, x is the 'owner' of the vector. This means that when x goes out
of scope, the memory allocated to the vector will be freed. This is done
deterministically by the Rust compiler , without the need for a mechanism
like a garbage collector. In other words, in Rust, you don't make calls to
functions like malloc and free explicitly: the compiler statically determines
when memory needs to be allocated or freed, and inserts those calls for you.
To err is human, but compilers never forget.
Let's add another line to our example:
fn main ( ) {
let y = & x [ 0 ];
}
We have introduced another variable, and . In this case, y is a 'reference' to

the first element of the vector. References in Rust are similar to pointers in
other languages, but with additional security checks at compile time.
References interact with the membership system through 'borrowing' , they
borrow what they are targeting, rather than owning it. The difference is that
when the reference goes out of scope, the underlying memory will not be
freed. If that is the case we would be releasing the same memory twice,
which is bad.
Let's add a third line. This line looks innocent but causes a compilation error:
fn main ( ) {
let mut x = vec! [ "Hello", "world"];
let y = & x [ 0];
x.push ("foo");
}
is a method in vectors that adds an element to the end of the vector.

push
When we try to compile the program we get an error:
error: cannot borrow `x` as mutable because it is also borrowed as
immutable
x.push ("foo");
^
note: previous borrow of `x` occurs here; the immutable borrow
prevents
subsequent moves or mutable borrows of `x` until the borrow ends
let y = & x [ 0];
^
note: previous borrow ends here
fn main ( ) {
}
^
Whoa! The Rust compiler can sometimes provide well-detailed errors and
this time one of them. As the error explains, while we make the variable
mutable we cannot call push . This is because we already have a reference to
an element of the vector, y . Mutating something while there is a reference to
it is dangerous, because we can invalidate the reference. In this specific case,
when we create the vector, we have only allocated space for two elements.
Adding a third party would mean allocating a new memory segment for all
items, copying all previous values, and updating the internal pointer to that
memory. All of that is fine. The problem is that and would not be updated,
generating a 'hanging pointer'. Which is wrong. Any use of y would be a
mistake in this case, and the compiler has warned us against it.
So how do we solve this problem? There are two approaches that we could
take. The first is to make a copy instead of a reference:
fn main ( ) {
let y = x [ 0 ] .clone ();

x.push ( "foo" );
}
Rust has motion semantics by default , so if we want to make a copy of some
data, we call the clone () method . In this example, y is no longer a reference
to the vector stored in x , but a copy of its first element, "Hello" . Because we
don't have a reference, our push ( ) works perfectly.
If we really want a reference, we need another option: make sure our

reference goes out of scope before we try to do the mutation. In this way:
fn main ( ) {
{
let y = & x [ 0 ];
}
x.push ( "foo" );
}
With the additional pair of keys we have created an internal scope. and it will
go out of scope before we call push ( ) , so no problem.
This membership concept is not only good at preventing dangling pointers,

but an entire set of issues, such as iterator invalidation, concurrency, and
more.
Chapter I
First steps
This first section of the book will walk you through Rust and his tools. First,
we will install Rust. Then the classic program 'Hello World'. Finally, we'll
talk about Cargo, Rust's package manager and build system.
Hello World!
Now that you have installed Rust, let's write your first program. It is tradition
that your first program in any language is one that prints the text "Hello,
world!" to the screen. The good thing about starting with such a simple
program is that you verify not only that the compiler is installed, but that it is
working. Printing information to the screen is a very common thing.
The first thing we must do is create a file where we can put our code. I like to
create a projects directory in my user directory and keep all my projects there.
Rust doesn't care where the code resides.
This leads to another issue to be clarified: this guide will assume that you
have a basic familiarity with the command line. Rust does not demand
anything regarding your editing tools or where your code lives. If you prefer
an IDE to the command line interface, you should probably take a look at
SolidOak , or wherever the plugins are for your favorite IDE. There are a
number of extensions of varying quality under development by the
community. The team behind Rust also publishes plugins for various
publishers . Setting up your editor or IDE is beyond the objectives of this
tutorial, check the documentation for your specific configuration.
With that said, let's create a directory in our project directory.

$ mkdir ~ / projects
$ cd ~ / projects
$ mkdir hello_world
$ cd hello_world
If you're on Windows and you're not using PowerShell, the ~ might not
work. Consult the specific documentation for your terminal for more details.
Let's create a new source code file. We will call our file main.rs. Rust files end
with the extension .rs . If you are using more than one word in your file
name, use a sub-hyphen: hello_world.rs instead of helloworld.rs .
Now that you have your file open write this in:
fn main ( ) {
println! ( "Hello, world!" );
}
Save the changes to the file, and write the following in your terminal
window:
$ rustc main.rs
$. / main # or main.exe in Windows
Hello World!
Success! Now let's see what has happened in detail.
fn main ( ) {
}
These lines define a function in Rust. The main function is special: it is the
beginning of every Rust program. The first line says: "I am declaring a
function called main which receives no arguments and returns nothing." If
there were arguments, they would be enclosed in parentheses ( ( and ) ), and
since we are not returning anything from this function, we can omit the return
type entirely. We will come to this later.
You will also notice that the function is wrapped in curly braces ( { and } ).
Rust requires these keys delimiting all function bodies. It is also considered a
good style to place the opening brace on the same line as the function
declaration, with an intermediate space.
The following is this line:

This line does all the work in our little program. There are a number of details
that are important here. The first is that it is indented with four spaces, not
tabs. Please configure your editor to insert four spaces with the tab key. We
provide some sample configurations for various editors .
The second point is the println! ( ) Part . This is calling a Rust macro , which is
how metaprogramming is done in Rust. If this were a function instead, it
would look like this: println ( ) . For our purposes, we need not worry about
this difference. Just know that sometimes you will see ! , and that this means
that you are calling a macro instead of a normal function. Rust implements
println! as a macro instead of a function for good reason, but that's an advanced
topic. One last thing to mention: Rust macros are different from C macros, if
you've used them. Don't be scared of using macros. We'll get to the details
eventually, for now you just have to trust us.
Then "Hello world!" it is a character string. Character strings are a surprisingly

complex topic in system programming languages, and this specifically is a
'statically assigned' character string. If you'd like to read about memory
allocation, take a look at the stack and the mound , but for now you don't
need to if you don't want to. We pass this string as an argument to println!
who in turn prints the character string to the screen. Easy!
Finally, the line ends with a semicolon ( ; ). Rust is an expression-oriented

language, which means that most things are expressions, rather than
statements. The ; it is used to indicate that the expression has ended, and that
the next one is ready to start. Most lines of code in Rust end with a ; .
Finally, compile and run our program. We can compile with our rustc
compiler by passing it the name of our source file:
$ rustc main.rs
This is similar to gcc or clang , if you come from C or C . Rust will output an
executable binary. You can see it with ls :
$ ls
main main.rs
Or in Windows:
$ dir
main.exe main.rs
There are two files: our source code, with the extension .rs , and the
executable ( main.exe in Windows, main in others)
$. / main # or main.exe in Windows

The above prints our text Hello world! to our terminal.
If you're coming from a dynamic language like Ruby, Python, or Javascript,

you're probably not used to seeing these two steps as separate. Rust is a
compiled language, which means you can compile your program, give it to
someone else, and they don't need to have Rust installed. If you give someone
a .rb or .py or .js file , they need to have a Ruby / Python / JavaScript
implementation, but you only need one command for both of them, compile
and run your program. It's all about balancing advantages / disadvantages in
language design, and Rust has chosen.
Congratulations, you have officially written a Rust program. That makes you
a Rust programmer! Welcome. ��
Next I would like to introduce you to another tool, Cargo, which is used to
write Rust programs for the real world. Just using rustc is fine for simple
things, but as your project grows, you will need something to help you
manage all the options it has, as well as making it easy to share the code with
other people and projects.
Hello, Cargo!
Cargo is a tool that Rusteros use to help them manage their Rust projects.
Cargo is currently in pre-1.0 status, and as a result is still a work in progress.
However it is already good enough for many Rust projects, and it is assumed
that Rust projects will use Cargo from the beginning.
Cargo manages three things: compiling your code, downloading the

dependencies your code needs, and compiling those dependencies. In the first
instance, your code will not have any dependency, that is why we will be
using only the first part of the Cargo functionality. Eventually we will add
more. Because we started using Cargo from the beginning it will be easy to
add later.
If you have installed Rust through the official installers then you should have
Cargo. If you have installed Rust in any other way, you could take a look at
Cargo's README for specific instructions on how to install it.
Migrating in Charge
Let's convert Hello World in Charge.
To load our project, we need two things: Create a Cargo.toml configuration file
, and put our source file in the right place. Let's do that part first:
$ mkdir src
$ mv main.rs src / main.rs
Note that because we are creating an executable, use main.rs . If we wanted to
create a library, you should use lib.rs . Customized locations for the entry
point can be specified with a [ [[lib]] or [[bin]] ] crates-custom key in the
TOML file described below.
Cargo expects your source code files to reside in the src directory . This
leaves the root level for other things, like READMEs, licensing information,
and anything unrelated to your code. Cargo helps us keep our projects nice
and orderly. A place for everything, and everything in its place.
Here is our configuration file:
$ editor Cargo.toml
Make sure you have this correct name: you need the capital C !
Put this inside:
[package]
name = "hello_world"
version = "0.0.1"
authors = [ "Your name <your@example.com> " ]
This file is in TOML format . Let us explain the same:
TOML's goal is to be a minimal configuration format that is easy to read due

to obvious semantics. TOML is designed to unambiguously map to a hash
table. TOML should be easy to convert to data structures in a wide variety of
languages.
TOML is very similar to INI, but with some extra niceties.
Once you have this file in its place, we should be ready to compile! Try this:
$ build charge
Compiling hello_world v0. 0.1 (file: /// home / yourname / projects /
hello_world)
$. / target / debug / hello_world
Hello World!
Bam! We build our project with build charge , and run it with . / target / debug /
hello_world . We can do the two steps in one with run charge :
$ charge run
Running `target / debug / hello_world`
Hello World!
Note that we did not rebuild the project this time. Cargo determined that we
hadn't changed the source file, so I just run the binary. If we had made a
modification, we should have seen it doing the two steps:
$ charge run
Compiling hello_world v0. 0.1 (file: /// home / yourname / projects /
hello_world)
Running `target / debug / hello_world`
Hello World!
This has not contributed much to us beyond our simple use of rustc , but think
about the future: when our projects get more complicated, we will need to do
more to get all the parts to compile correctly. With Cargo, as our project
grows, we simply run cargo build , and everything will work correctly.
When our project is finally ready for release, you can use cargo build --release to
compile it with optimizations.
You may also have noticed that Cargo has created a new file: Cargo.lock .
[root]
version = "0.0.1"
This file is used by Cargo to keep track of the dependencies used in your
application. For now, we don't have any, and it's a little scattered. You should
never need to touch this file on your own, just let Cargo handle it.
That's it! We have successfully built hello_world with Cargo. Although our
program is simple, it is using much of the real tools that you will use for the
rest of your career with Rust. You can assume that to start virtually any Rust
project you will do the following:
$ git clone someturl.com/foo
$ cd foo
$ build charge
A New Project
You don't have to go through that entire process every time you want to start
a new project! Cargo has the ability to create a template directory in which
you can start developing immediately.
To start a new project with Cargo, we use cargo new :
$ cargo new hello_world –bin
We are passing --bin because we are creating a binary program: if we were

creating a library, we would skip it.
Let's take a look at what Cargo has generated for us:
$ cd hello_world
$ tree.
.
├── Cargo.toml
└── src
└── main.rs
1 directory, 2 files
If you don't have the tree command installed, you could probably get it using
your distribution's package handler. It is not necessary, but it is certainly
useful.
This is all you need to get started. Let's first look at our Cargo.toml :
[package]
version = "0.0.1"
authors = [ "Your Name <your@example.com>" ]
I loaded this file with default values based on the arguments you provided
and your global git settings . You might also notice that Cargo has initialized
the hello_world directory as a git repository .
Here is the content of src / main.rs :
fn main ( ) {
}
Cargo has generated a "Hello world!" for us, you're ready to start rubbing
elbows. Cargo has its own guide which covers all its features in much more
depth.
Now that we have learned the tools, let's actually start learning more about
Rust as a language. This is the base that will serve you well for the rest of
your time with Rust.
You have two options: Immerse yourself in a project with ' Learn Rust ', or
start from the bottom and work upwards with ' Syntax and Semantics '. More
experienced system programmers will probably prefer 'Learn Rust', while
those from dynamic languages might also enjoy it. Different people learn
differently! Choose what works best for you.
Chapter I
Learn Rust
Welcome! This section has a few tutorials that will teach you Rust through
project building. You'll get an overview, but we'll also take a look at the
details.
If you prefer a more bottom-up experience, check out Syntax and Semantics .
Guessing Game
For our first project, we will implement a classic programming problem for
beginners: a guessing game. How the game works: Our program will
generate a random integer between one and one hundred. It will ask us to
introduce a hunch. After having provided our number, it will tell us if we
were far below and far above. Once we guess the correct number, you will
congratulate us. Sounds good?
Initial setup
Let's create a new project. Go to your project directory. Remember how we
created our directory structure and a Cargo.toml for hello_world ? I have a
command that does that for us. Let's try it:
$ cd ~ / projects
$ charge new riddles --bin
$ cd riddles
We pass the name of our project in charge new , along with the flag --bin ,
because we are creating a binary, instead of a library.
Take a look at the generated Cargo.toml :
[package]
name = "riddles"
version = "0.1.0"
authors = [ "Your Name <your@example.com>" ]
Cargo obtains this information from your environment. If it is not correct,
correct it.
Finally, Cargo has generated a 'Hello, world!' for us. Take a look at src / main.rs
:
fn main () {
}
Let's try to compile what Cargo has provided us:
$ build charge
Compiling riddles v0.1.0 (file: /// home / you / projects / riddles)
Excellent! Open your src / main.rs again. We will be writing all our code in this
file.
Before continuing, let me show you one more command from Cargo: run .
cargo run is a kind of cargo build , but with the difference that it also executes the
binary produced. Let's try it:
$ charge run
Compiling riddles v0. 1.0 (file: /// home / you / projects / riddles)
Running `target / debug / riddles`
Hello World!
Great! The run command is very useful when you need to quickly iterate
through a project. Our game is one of those projects, we will need to quickly
test each iteration before moving on to the next.
Processing a Riddle Attempt

Let's try it! The first thing we need to do for our guessing game is allow our
player to enter a guess attempt. Put this in your src / main.rs :
use std :: io;
fn main () {
println! ("Guess the number!");
println! ("Please enter your hunch.");
let mut hunch = String :: new ();
io :: stdin (). read_line (& mut hunch)

.okay()
.expect ("Failed to read line");
println! ("Your hunch was: {}", hunch);

}
There is a lot here! Let's try to go through it, piece by piece.
use std :: io;

We will need to receive input from the user, and then print the result as
output. Because of this we need the io library from the standard library. Rust
only matters a few things for all programs, this set of things is called a
'prelude' . If it is not in the prelude you will have to call it directly through use
.
fn main () {
As you have seen previously, the main () function is the entry point to your
program. The fn syntax declares a new function, the () s indicate that there
are no arguments, and { the body of the function begins. Because we don't
include a return type, it is assumed to be () an empty tuple .

We previously learned that println! () Is a macro that prints a string of
characters to the screen.

Now we are getting interesting! There are a lot of things going on in this little
line. The first things to note is that it is a let statement , used to create
variables. It has the form:
let foo = bar;

This will create a new variable called foo , and bind it to the value bar . In
many languages this is called a 'variable' but Rust variables have a few tricks
up their sleeve.
For example, they are immutable by default. This is why our example uses
mut : this does a mutable binding, rather than immutable. let doesn't just take
a name from the left side, let accepts a ' pattern '. We will use the patterns a
little later. It is sufficient for now to use:
let foo = 5 ; // immutable.

let mut bar = 5 ; // mutable
Ah, // start a comment, until the end of the line. Rust ignores everything in
comments
So we know that let mut hunch will introduce a mutable binding called hunch ,
but we have to look on the other side of = to know what it is being associated
with: String :: new () .
is a type of character string, provided by the standard library. A String is

String
a segment of text encoded in UTF-8 capable of growing.
The :: new () syntax uses :: because it is an 'associated function' of a particular

type. In other words, it is associated with String itself, rather than with a
particular instance of String . Some languages call this a 'static method'.
This function is called new () , because it creates a new empty String . You
will find a new () function on many types, because it is a common name for
creating a new value of some type.
Let's continue:

.okay()
.expect ("Line reading failure");
Another pile! Let's go piece by piece. The first line has two parts. Here is the
first one:
io :: stdin ()
Remember how we use use in std :: io in the first line of our program? We are
now calling an associated function in std :: io . If you had not used use std :: io ,
we could have written this line as std :: io :: stdin () .
This particular function returns a handle to the standard input of your

terminal. More specifically, a std :: io :: Stdin .
The next part will use that handle to get user input:
.read_line (& mut hunch)

Here, we call the read_line () method on our handle. The methods are similar to
the associated functions, but are only available in a particular instance of a
type, rather than the type itself. We're also passing an argument to read_line () :
& mut hunch .
Remember when we created hunch ? We said it was mutable. However

read_line does not accept a String as argument: it accepts a & mut String . Rust
has a feature called ' references ', which allows having multiple references to
a piece of data, thus reducing the need for copying. References are a complex
feature, because one of Rust's strongest selling points is about how easy and
safe it is to use references. For now we don't need to know much about those
details to finish our program. All we need to know at the moment is that just
like let bindings, references are immutable by default. As a consequence we
need to write & mut hunch instead of & hunch .
Because read_line () accepts a mutable reference to a character string. Your job

is to take what the user enters in the standard input, and put it in a string.
Because of this, it takes this string as an argument, and because it must add
user input, it needs to be mutable.
We are not done with this line yet. While it is a single line of text, it is just
the first part of a complete logical line of code:
.okay()
.expect ("Line reading failure");
When you call a method with the .foo () syntax you can enter a line break and
another space. This helps you divide long lines. We could have written:
io :: stdin (). read_line (& mut hunched) .ok (). expect ("Line reading
failed");
But that is more difficult to read. So we have divided it into three lines for
three method calls. We've already talked about read_line () , but what about ok
() and expect () ? Well, we already mentioned that read_line () places the user's
input in the & mut String that we provide. But it also returns a value: in this
case an io :: Result . Rust has a number of types called Result in its standard
library: a generic Result , and specific versions for sub-libraries, such as io ::
Result .
The purpose of those Result is to encode error handling information. Values

of type Result have methods defined in them. In this case io :: Result has an ok
() method , which translates to 'we want to assume that this value is a
successful value. If not, discard the information about the error. ' Why discard
the information about the error? For a basic program, we simply want to print
a generic error, any problem that means we cannot continue. The ok ()
method returns a value that has another method defined in: expect () . The
expect () method takes the value at which it is called and if it is not a successful
value, it panics ! with a message that we have provided. A panic! like this it
will cause the program to have an abrupt exit (crash), showing this message.
If we remove the calls to those two methods, our program will compile, but
we will get a warning:
$ build charge
src / main.rs: 10 : 5 : 10 : 44 warning: unused result which must be used,
# [warn (unused_must_use)] on by default
src / main.rs: 10 io :: stdin (). read_line (& mut hunch);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Rust advises us that we have not used the Result value . This warning comes
from a special annotation that io :: Result has . Rust is trying to tell you that you
have not handled a possible error. The correct way to suppress the error is to
actually write the code for handling errors. Luckily, if we only want to end
the program execution if there is a problem, we can use these two small
methods. If we could somehow recover from the error, we would do
something different, but leave that for a future project.
We only have one line left from this first example:

}
This line prints the character string in which we save our entry. The {} s are
placeholders, that's why we pass riddle as an argument. If there had been
multiple {} s, we should have passed multiple arguments:
let x = 5 ;
let y = 10 ;
println! ( "xyy: {} y {}" , x, y);

Easy.
Either way, that's the tour. We can run it with run charge :
$ charge run
Compiling guessing_game v0. 1.0 (file: /// home / you / projects /
riddles)
Guess the number!
Please enter your hunch.
6
Your hunch was: 6
Congratulations! Our first part is over: we can get keyboard input and print it
back.
Generating a secret number

Next we need to generate a secret number. Rust does not yet include a
random number functionality in the standard library. However, Rust's team
provides a crate rand . A 'crate' is a package of Rust code. We have been
building a 'crate binaro', which is an executable. rand is a 'crate library', which
contains code to be used by other programs.
Using external crates is where Cargo really shines. Before we can write code
that uses rand , we must modify our Cargo.toml file . Open it, and add these
lines at the end:
[dependencies]
rand = "0.3.0"
The [dependencies] section of Cargo.toml is like the [package] section : everything

that follows is part of it, until the next section begins. Cargo uses the
dependencies section to know which external crates we depend on, as well as
the required versions. In this case we have used version 0.3.0 . Cargo
understands Semantic Versioning , which is a standard for writing version
numbers. If we wanted to use the latest version we could have used * or a
range of versions. The documentation Cargo contains more details.
Now, without changing anything in our code, let's build our project:
$ build charge
Updating registry `https: // github.com / rust-lang / crates.io-index`
Downloading rand v0. 3.8
Downloading libc v0. 1.6
Compiling libc v0. 1.6
Compiling rand v0. 3.8
(You could see different versions, of course.)
Lots of more output! Now that we have an external dependency, Cargo

downloads the latest versions of everything from the registry, which can copy
data from Crates.io . Crates.io is where people in the Rust ecosystem post
their open source projects for others to use.
After updating the registry, Cargo checks our dependencies (in [dependencies] )
and downloads them if they do not have them yet. In this case we just said we
wanted to rely on rand , and we also got a copy of libc . This is because rand
itself depends on libc to function. After downloading the dependencies, Cargo
compiles them, to later compile our code.
If we run cargo build , we will get a different output:
$ build charge
That's right, there is no way out! Cargo knows that our project has been built,
as well as all its dependencies, so there is no reason to do the whole process
again. With nothing to do, just run. If we open src / main.rs again, we make a
trivial change, save the changes, we would only see one line:
$ build charge
So, we have told Cargo that we wanted any version 0.3.x of rand , and he
downloaded the latest version at the time of writing this tutorial, v0.3.8 . But
what happens when the next version v0.3.9 is released with a major bugfix?
While receiving bugfixes is important, what happens if 0.3.9 contains a
regression that breaks our code?
The answer to this problem is the Cargo.lock file, which you will find in your
project directory. When you build your project the first time, cargo
determines all versions that match your criteria and writes them to the
Cargo.lock file . When you build your project in the future, Cargo will notice
that a Cargo.lock file exists, and will use the versions specified in it, instead of
doing all the work of determining the versions again. This allows you to have
an automatically reproducible construction. In other words, we will stay at
0.3.8 until we explicitly upload the version, in the same way the people with
whom we have shared our code will do so, thanks to the Cargo.lock file .
But what happens when we want to use v0.3.9 ? Cargo has another command,
update , which translates to 'ignore the lock and determine all the latest
versions that match what we have specified. If this works, write those
versions to the Cargo.lock ' lock file . But, by default, Cargo will only search
for versions greater than 0.3.0 and less than 0.4.0 . If we want to move to 0.4.x
, we would need to update the Cargo.toml file directly. When we do that, the
next time we run cargo build , Cargo will update the index and re-evaluate our
rand requirements .
There is much more to say about Cargo and its ecosystem , but for now, that's
all we need to know. Cargo makes it really easy to reuse libraries, and
Russetters tend to write small projects which are built by a smaller set of
packages.
Let us now use rand . Here is our next step:
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {
let secret_number = rand :: thread_rng (). gen_range (1, 101);
println! ("The secret number is: {}", secret_number);

.okay()

}
The first thing we have done is change the first line. Now it says extern crate
rand . Because we declare rand in our [dependencies] section , we can use extern
crate to let Rust know that we will be using rand . This is equivalent to a use
rand; , so that we can make use of whatever is inside the crate rand through the
prefix rand :: .
Then we have added another use line : use rand :: Rng . In a few moments we
will be using a method, and this requires that Rng is available for it to work.
The basic idea is this: the methods are inside something called 'traits', and for
the method to work you need the trait to be available. For more details go to
the Traits section .
There are two more lines in the middle:

We use the rand :: thread_rng () function to obtain a copy of the random number
generator, which is local to the thread of execution in which we are. Because
we have made rand :: Rng available through the use rand :: Rng , it has a gen_range ()
method available. This method accepts two arguments, and generates a
random number between them. It is inclusive at the lower limit, but it is
exclusive at the upper limit, so we need 1 and 101 to get a number between
one and one hundred.
The second line only prints the secret number. This is useful as we develop
our program so that we can test it. We will be removing this line for the final
version. It's not a game if you print the answer right when you start it!
Try to run the program a few times:
$ charge run
Guess the number!
The secret number is: 7
4
Your hunch was: 4
$ charge run
Guess the number!
5
Your hunch was: 5
Gradious! Next: let's compare our riddle with the secret number.
Comparing riddles
Now that we have user input, let's compare the riddle with our secret number.
Here is our next step, although it still doesn't work completely:
extern crate rand;
use std :: io;

use std :: cmp :: Ordering;
use rand :: Rng;
fn main () {

.okay()
match hunch.cmp (& secret_number) {

Ordering :: Less => println! ("Very small!"),
Ordering :: Greater => println! ("Very big!"),
Ordering :: Equal => println! ("You won!"),
}
}
Some pieces here. The first is another use . We have made available a type
called std :: cmp :: Ordering . Then, five new bottom lines that use it:

}
The cmp () method can be called to anything that can be compared, it takes a
reference to the thing you want to compare with. Returns the Ordering type
that we made available previously. We have used a match statement to
determine exactly what type of Ordering it is. Ordering is an enum , short for
'enumeration', which looks like this:
enum foo {
Pub,
Baz,
}
With this definition, anything of the Foo type can be either a Foo :: Bar or a
Foo :: Baz . We use the :: to indicate the namespace for a particular enum
variant .
The Ordering enum has three possible variants: Less , Equal , and Greater
(minor, equal and major respectively). The match statement takes a value of a
type, and allows you to create an 'arm' for each possible value. Because we
have three possible types of Ordering , we have three arms:
match guess.cmp (& secret_number) {

}
If it is Less , we print Too small! , if it's Greater , Too big! , and if it's Equal ,
you've won! . match is really useful, and is often used in Rust.
Earlier I mentioned that it still doesn't work. Let's put it to the test:
$ build charge
src / main.rs: 28 : 21 : 28 : 35 error: mismatched types:
expected `& collections :: string :: String`,
found `& _`
(expected struct `collections :: string :: String`,
found integral variable) [E0308]
src / main.rs: 28 match hunch.cmp (& secret_number) {
^ ~~~~~~~~~~~~~
error: aborting due to previous error
Could not compile `riddles`.
Oops! A big mistake. The main thing in it is that we have 'mismatched types'.
Rust has a strong, static rate system. However, it also has type inference.
When we typed let hunch = String :: new () , Rust was able to infer that hunch must
be a String , and so did not make us write the type. With our secret_number ,
there are a number of types that can have a value between one and one
hundred: i32 , a thirty-two-bit number, u32 , an unsigned thirty-two-bit
number, or i64 a sixty-four-bit number or others. So far, that hasn't mattered,
since Rust by default uses i32 . However, in this case, Rust doesn't know how
to compare hunch to secret_number . Both need to be of the same type. In the
end, we want to convert the String that we read as input into a real type of
number, for comparison purposes. We can do that with three more lines. Here
is our new program:
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {

.okay()
let hunch: u32 = hunch.trim (). parse ()

.okay()
.expect ("Please enter a number!");

}
}
The three new lines:

.okay()
Wait a minute, I thought we already had a hunch ? We do, but Rust allows us
to overwrite the previous hunch with a new one. This is frequently used in this
same situation, where hunch is a String , but we want to convert it to a u32 .
This shadowing allows us to reuse the name hunch instead of forcing us to
come up with two unique names like hunch_str and hunch , or others.
We are associating a hunch with an expression that looks like something we

wrote earlier:
guess.trim (). parse ()

Followed by an invocation to ok (). Expect () . Here hunch refers to the old
version, which was a String that contained our user input in it. The trim ()
method on String s removes any whitespace at the beginning and end of our
character strings. This is important, because we had to press the 'return' key to
satisfy read_line () . This means if we type 5 and hit 'return' hunch it looks like
this: 5 \ n . The \ n represents 'new line', the enter key. trim () gets rid of this,
leaving our string only at 5 . The parse () method on character strings parses a
string of characters into some type of number. Because it can parse a variety
of numbers, we must give Rust a hint of the exact type of number we want.
Hence the hunch part let: u32 . The colon ( : ) after Hunch tell Rust we will
note the type. u32 is a thirty-two-bit unsigned integer. Rust has a variety of
built-in number types , but we have chosen u32 . It is a good default option
for a small positive number.
Like read_line () , our call to parse () could cause an error. What if our character
string contains A ߑ ? There would be no way to convert that to a number.
This is why we will do the same as we did with read_line () : use the ok () and
expect () methods to end abruptly if there are any errors.
Let's try our program!
$ charge run
Running `target / riddles`
Guess the number!
76
Your hunch was: 76
Very big!
Excellent! You can see that I have even added spaces before my attempt, and
still the program determined that I try 76. Run the program a few times, and
verify that guessing the number works, as well as trying a very small number.
Now we have most of the game working, but we can only try to guess once.
Let's try to change that by adding cycles!
Iteration
The loop keyword provides an infinite loop. Let's add it:
Guess the number! The secret number is: 58 Please enter your riddle. 76
Your hunch was: 76 Very big!
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {
loop {

.okay()

.okay()
println! ("Hunch: {}", hunch);

}
}
}
Test it. But wait, didn't we just add an infinite loop? Yep. Remember our
discussion about parse () ? If we give a non - numerical answer, we will return
( return ) and will finish execution. Observe:
$ charge run
Guess the number!
Four. Five
Your hunch was: 45
Very small!
60
Your hunch was: 60
Very big!
59
Your hunch was: 59
You won!
quit
thread '<main>' panicked at 'Please type a number!'
Ha! quit in effect ends the execution. As well as any other entry that is not a
number. Well this is suboptimal to say the least. Let's get out first when we
win:
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {
loop {

.okay()

.okay()

Ordering :: Equal => {
println! ("You won!");
break;
}
}
}
}
By adding the break line after "You won!", We will break the cycle when we
win. Exiting the loop also means exiting the program, since it is the last thing
in main () . We only have one improvement left to make: when someone
enters a non-numeric value, we don't want to end the run, we just want to
ignore it. We can do it in the following way:
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {
loop {

.okay()
let hunch: u32 = match hunch.trim (). parse () {

Ok (num) => num,
Err (_) => continue,
};

break;
}
}
}
}
These are the lines that have changed:

Ok (num) => num,
};
This is how we went from 'abruptly ending an error' to 'effectively handling
the error', through changing ok (). Expect () to a match statement . The Result
returned by parse () is an enum just like Ordering , but in this case each variant
has associated data: Ok is successful, and Err is a failure. Each contains more
information: the parsed integer in the successful case , or a type of error. In
this case we match on Ok (num) , which assigns the internal value of the Ok to
name num , and then returns on the right side. In the case of Err , we don't
care what kind of error it is, that's why we use _ instead of a name. This
ignores the error and continue moves us to the next iteration of the loop .
Now we should be fine! Let's try:

$ charge run
Guess the number!
10
Your hunch was: 10
Very small!
99
Your hunch was: 99
Very small!
foo
61
Your hunch was: 61
You won!
Great! With one last upgrade, we finish the puzzle game. Can you imagine
what it is? It is correct, we do not want to print the secret number. It was
good for testing, but it ruins our game. Here is our final source code:
extern crate rand;
use std :: io;

use rand :: Rng;
fn main () {
loop {

.okay()

Ok (num) => num,
};

break;
}
}
}
}
Completed!
At this point, you have successfully finished the guessing game!
Congratulations!
This first project taught you a lot: let , match , methods, associated functions,
using external crates, and more. Our next project will demonstrate even more.
The Dinner of the Philosophers
For our second project, let's take a look at a classic concurrency problem. It's
called 'The Dinner of the Philosophers'. It was originally conceived by
Dijkstra in 1965, but we will use a slightly adapted version of this paper by
Tony Hoare in 1985.
In ancient times, a wealthy philanthropist set up a university to house five

eminent philosophers. Each philosopher had a room in which he could carry
out his professional activity of thought: there was also a common dining
room, furnished with a circular table, surrounded by five chairs, each
identified with the name of the philosopher who sat in it. Philosophers sat
counterclockwise around the table. To the left of each philosopher lay a
golden fork, and in the center a bowl of spaghetti, which was constantly
refilled. A philosopher was expected to spend most of his time thinking; but
when they were hungry, go to the dining room and take the fork to your left
and dip it in the spaghetti. But such was the tangled nature of spaghetti that a
second fork was required to bring it to the mouth. The philosopher therefore
also had to take the fork to his right. When they finished they had to lower
both forks, get up from the chair and continue thinking. Of course, a fork can
be used by only one philosopher at a time. If another philosopher wants it, he
has to wait until the fork is available again.
This classic problem exhibits some elements of concurrency. The reason for
this is that it is an effectively difficult solution to implement: a simple
implementation can generate a deadlock. For example, consider a simple
algorithm that could solve this problem:
1. A philosopher takes the fork to his left.

2. Then take the fork to your right.
3. Eat.
4. Lower the forks.
Now, let's imagine this sequence of events:
1. Philosopher 1 begins the algorithm, taking the fork to his left.

6. ...? All forks have been taken, but no one can eat!
There are different ways to solve this problem. We will guide you through
the solution of this tutorial. For now, let's start by modeling the problem.
Let's start with the philosophers:
struct Philosopher {
name: String ,
}
impl Filosofo {
fn new (name: & str ) -> Philosopher {
Philosopher {
name: name.to_string (),
}
}
}
fn main () {
let f1 = Philosopher :: new ( "Judith Butler" );
let f2 = Philosopher :: new ( "Gilles Deleuze" );
let f3 = Philosopher :: new ( "Karl Marx" );
let f4 = Philosopher :: new ( "Emma Goldman" );
let f5 = Philosopher :: new ( "Michel Foucault" );
}
Here, we create a structure (struct) to represent a philosopher. For now the
name is all we need. We choose the String type for the name, instead of & str .
Generally speaking, working with the type that owns (owns) your data is
easier than working with one that uses references.
Let's continue:
# struct Philosopher {
# name: String ,
#}
impl Filosofo {
Philosopher {
}
}
}
This impl block allows us to define things in Philosopher structures . In this
case we are defining an 'associated function' called new . The first line looks
like this:
# name: String ,
#}
# impl Philosopher {
# Philosopher {
# name: name.to_string (),
#}
#}
#}
We get an argument, name , of type & str . A reference to another character
string. This returns an instance of our Philosopher structure .
# name: String ,
#}
# fn new (name: & str ) -> Philosopher {
Philosopher {
}
#}
#}
The above creates a new Philosopher , and assigns our name argument to the
name field . Not the argument itself, because we call .to_string () on it. Which
creates a copy of the string pointed to our & str , and gives us a new String ,
which is the type of the field name of Filosofo .
Why not accept a String directly? It is easier to call. If we received a String but
the caller had a & str they would be forced to call .to_string () on their side. The
downside to this flexibility is that we always make a copy. For this little
program, this is not particularly important, and we know that we will be using
short strings anyway.
One last thing you may have noticed: we only define a Philosopher , and we
don't seem to do anything with it. Rust is an 'expression-based' language,
which means that almost anything in Rust is an expression that returns a
value. This is true for functions too, the last expression is automatically
returned. Because we create a new Philosopher as the last expression of this
function, we end up returning it.
The name new () is nothing special to Rust, but it is a convention for functions
that create new instances of structures. Before we talk about why, we take a
look at main () again:
# name: String ,
#}
#
# fn new (name: & str ) -> Philosopher {
# Philosopher {
# name: name.to_string (),
#}
#}
#}
#
fn main () {
let f1 = Philosopher :: new ( "Judith Butler" );
let f2 = Philosopher :: new ( "Gilles Deleuze" );
let f3 = Philosopher :: new ( "Karl Marx" );
let f4 = Philosopher :: new ( "Emma Goldman" );
let f5 = Philosopher :: new ( "Michel Foucault" );
}
Here, we create five variables with five new philosophers. These are my five
favorites, but you can replace them with whomever you prefer. If you had not
defined the new () function , main () would look like this:
# name: String ,
#}
fn main () {
let f1 = Philosopher {name: "Judith Butler" .to_string ()};
let f2 = Philosopher {name: "Gilles Deleuze" .to_string ()};
let f3 = Philosopher {name: "Karl Marx" .to_string ()};
let f4 = Philosopher {name: "Emma Goldman" .to_string ()};
let f5 = Philosopher {name: "Michel Foucault" .to_string ()};
}
A little louder. Using new also has other advantages, but even in this simple
case it ends up being of better use.
Now that we have the basics in place, there are a number of ways in which
we can attack the larger problem. I like to start at the end: let's create a way
for each philosopher to finish eating. As a small step, let's make a method,
and then iterate through all the philosophers calling it:
name: String ,
}
impl Filosofo {
Philosopher {
}
}
fn eat (& self ) {

println! ( "{} has finished eating." , self .name);
}
}
fn main () {
let philosophers = vec! [
Philosopher :: new ( "Judith Butler" ),
Philosopher :: new ( "Gilles Deleuze" ),
Philosopher :: new ( "Karl Marx" ),
Philosopher :: new ( "Emma Goldman" ),
Philosopher :: new ( "Michel Foucault" ),
];
for f in & philosophers {

f.comer ();
}
}
Let's look at main () first . Instead of having five individual variables for our
philosophers, we create a Vec <T> . Vec <T> is also called a 'vector', and is an
array capable of growth. Then we use a [ for ] [for] loop to iterate through the
vector, getting a reference to each philosopher at once.
In the body of the loop, we call f.comer (); , which is defined as:
fn eat (& self) {

println! ("{} has finished eating.", self.name);
}
In Rust, methods receive an explicit parameter self . This is why eating () is a
method and new is an associated function: new () has no self . For our first
version of eating () , we only printed the name of the philosopher, and we
mention that he has finished eating. Running this program should generate
the following output:
Judith Butler has finished eating.
Gilles Deleuze has finished eating.
Karl Marx has finished eating.
Emma Goldman has finished eating.
Michel Foucault has finished eating.
Very easy, everyone has finished eating! But we haven't implemented the real
problem yet, so we're not done yet!
Next, we not only want to just finish eating, but actually eat. Here is the next
version:
use std :: thread;
name: String ,
}
impl Filosofo {
Philosopher {
}
}
fn eat (& self ) {

println! ( "{} is eating." , self .name);
thread :: sleep_ms ( 1000 );

}
}
fn main () {
];
for f in & philosophers {

f.comer ();
}
}
Only a few changes. Let us analyze them part by part.
use std :: thread;

use makes names available in our scope. We will start using the thread module
of the standard library, and that is why we need to use it .
fn eat (& self) {

println! ("{} is eating.", self.name);
thread :: sleep_ms (1000);

}
We are now printing two messages, with a sleep_ms () in the middle. Which
simulates the time it takes for a philosopher to eat.
If you run this program, you should see each philosopher eat at once:
Judith Butler is eating.
Gilles Deleuze is eating.
Karl Marx is eating.
Emma Goldman is eating.
Michel Foucault is eating.
Excellent! We're moving forward. There is only one detail: we are not
operating concurrently, which is central to our problem!
To make our philosophers eat concurrently, we need to make a small change.
Here is the next iteration:

use std :: thread;
name: String ,
}
impl Filosofo {
Philosopher {
}
}
fn eat (& self ) {


}
}
fn main () {
];
let handles: Vec <_> = philosophers.into_iter (). map (| f | {

thread :: spawn (move || {
f.comer ();
})
}). collect ();
for h in handles {
h.join (). unwrap ();
}
}
All we have done is change the loop in main () , and added a second! This is
the first change:

f.comer ();
})
}). collect ();
Even so they are only five lines, they are five dense lines. Let's analyze by
parts.
let handles: Vec <_> =

We introduce a new variable, called handles . We have given this name
because we will create some new threads, which will result in some handles
(handles, handles) to these threads which will allow us to control their
operation. We need to explicitly annotate the type, due to something we'll
reference later. The _ is a placeholder for a type. We're saying " handles is a
vector of something, but you, Rust, can determine what that something is."
philosophers.into_iter (). map (| f | {

We take our list of philosophers and call into_iter () on it. This creates an
iterator that takes over (belongs to) each philosopher. We need to do this in
order to pass the philosophers to our threads. Then we take that iterator and
call map on it, a method that takes a closure as an argument and calls that
closure on each of the elements at once.

f.comer ();
})
This is where concurrency occurs. The thread :: spawn function takes a closure
as an argument and executes that closure on a new thread. The closure needs
an extra annotation, move , to indicate that the closure is going to take over
the values it is capturing. Mainly, the variable f of the map function .
Inside the thread, all we do is call eat (); in f .
}). collect ();

Finally, we take the result of all those calls to map and collect them. collect ()
will convert them into a collection of some type, which is why we note the
return type: we want a Vec <T> . The elements are the returned values of the
calls to thread :: spawn , which are handles to those threads. Whew!
for h in handles {
}
At the end of main () , we iterate through the handles by calling join () on
them, which blocks execution until the thread has completed execution. This
ensures that the thread completes its execution before the program ends.
If you run this program, you will see that philosophers eat without order! We
have multi-threads!
But that about the forks we have not fully modeled them yet.
To do so, let's create a new struct :

use std :: sync :: Mutex;
struct Table {
forks: Vec <Mutex <() >>,
}
This table contains a Mutex vector . A mutex is a way to control concurrency,
only one thread can access content at a time. This is exactly the property we
need for our holders. We use an empty pair, () , inside the mutex, because we
are not going to use the value, we will just hold on to it.
Let's modify the program to use Mesa :

use std :: thread;
use std :: sync :: {Mutex, Arc};
name: String ,
left: usize,
right: usize,
}
impl Filosofo {
fn new (name: & str , left: usize, right: usize) -> Philosopher {
Philosopher {
left: left,
right: right,
}
}
fn eat (& self , table: & table) {

let _left = table.forks [ self. left] .lock (). unwrap ();
let _right = table.forks [ self. right] .lock (). unwrap ();

}
}
struct Table {
forks: Vec <Mutex <() >>,
}
fn main () {
let table = Arc :: new (Table {forks: vec! [
Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
]});

Philosopher :: new ( "Judith Butler" , 0 , 1 ),
Philosopher :: new ( "Gilles Deleuze" , 1 , 2 ),
Philosopher :: new ( "Karl Marx" , 2 , 3 ),
Philosopher :: new ( "Emma Goldman" , 3 , 4 ),
Philosopher :: new ( "Michel Foucault" , 0 , 4 ),
];

let table = table.clone ();
f.comer (& table);
})
}). collect ();
for h in handles {
}
}
Many changes! However, with this iteration, we have obtained a functional
program. Let's see the details:
use std :: sync :: {Mutex, Arc};

We will use another std :: sync package structure : Arc <T> .
We will talk more about it when we use it.
name: String,
left: usize,
right: usize,
}
We are going to need to add two more fields to our Philosopher structure . Each
philosopher will have two forks: the one on the left and the one on the right.
We will use the type usize to indicate them, because this is the type with
which the vectors are indexed. These two values will be indexes in the holders
that our Table owns.
fn new (name: & str, left: usize, right: usize) -> Philosopher {
Philosopher {
left: left,
right: right,
}
}
Now we need to build those values left and right , so that we can add them to
new () .
fn eat (& self, table: & table) {
let _left = table.forks [self.left] .lock (). unwrap ();
let _right = table.forks [self.right] .lock (). unwrap ();
println! ("{} is eating.", self.name);

}
We have two new lines, we have also added an argument, table . Access the
list of holders of the table , and then use self.izquierda and self.derecha to access
the fork in a particular index. That gives us access to the Mutex at that index,
where we call lock () . If the mutex is currently being accessed by someone
else, we will block it until it is available.
The call to lock () may fail, and if it does, we want to end it abruptly. In this
case the error that can occur is that the mutex this 'poisoning' ( 'poisoned'),
which is what happens when the thread does panic while holding the lock.
Because this shouldn't happen, we simply use unwrap () .
Another strange thing about these lines: we have named the results _ left and
_ right . What about that sub-script? Well, we don't actually plan to use the
value inside the lock. We just want to acquire it. As a consequence, Rust will
warn us that we never use value. Through the use of the sub-script we tell
Rust what we wanted, that way he would not generate the warning.
What about releasing the lock ?, Well, this will happen when _left and _right
go out of scope, automatically.
let table = Arc :: new (Table {forks: vec! [

Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
Mutex :: new (()),
]});
Then in main () , we create a new Table and wrap it in an Arc <T> . 'arc' comes
from 'atomic reference count', we need to share our Table between multiple
threads. As we share it, the reference count will go up, and when each thread
ends, it will go down.
Philosopher :: new ("Judith Butler", 0, 1),
Philosopher :: new ("Gilles Deleuze", 1, 2),
Philosopher :: new ("Karl Marx", 2, 3),
Philosopher :: new ("Emma Goldman", 3, 4),
Philosopher :: new ("Michel Foucault", 0, 4),
];
We need to pass our values left and right to the constructors of our Philosophers
. But there is one more detail here, and it is very important. If you look at the
pattern, it is consistent to the end, Monsieur Foucault must have 4, 0 as
arguments, but instead it has 0, 4 . This is what prevents deadlocks, indeed:
one of the philosophers is left-handed! That is one way to solve the problem,
and in my opinion, it is the simplest.
let table = table.clone ();

f.comer (& table);
})
}). collect ();
Finally, inside our map () / collect () loop , we call mesa.clone () . The clone ()
method on Arc <T> is what increments the reference count, and when it goes
out of scope, decrements it. You will notice that we can introduce a new table
variable , and this will overwrite the old one. This is often used so that you
don't have to make up two unique names.
With all this, our program works! Only two philosophers can eat at any given
time and consequently you will have an exit that will look like this:
Congratulations! You have implemented a classic concurrency problem in
Rust.
Rust Within Other Languages

For our third project, we will choose something that demonstrates one of
Rust's greatest strengths: the absence of an execution environment.
As organizations grow, they progressively make use of a multitude of

programming languages. Different programming languages have different
strengths and weaknesses, and a polyglot architecture allows a particular
language to be used where its strengths make sense and another language is
weak.
A very common area where many programming languages are weak is

performance at runtime. Often, using language that is slow, but offers
increased productivity for the programmer, is a worthwhile balance. To help
mitigate this, these languages provide a way to write a part of your system in
C and then call that code as if it had been written in a higher-level language.
This facility is called the 'foreign function interface', commonly shortened to
'FFI'.
Rust has support for FFI in both directions: it can easily call C code, but
crucially it can be called as easily as C. Combined with the absence of a
garbage collector and low runtime requirements, Rust is a candidate for be
embedded within other languages when you need those extra ooKmh.
The problem
There are many problems that we could have chosen, but we will choose an
example in which Rust has a clear advantage over other languages: numerical
computing and threads.
Many languages, in honor of consistency, place numbers on the mound,

rather than on the pile. Especially in languages focused on object-oriented
programming and the use of a garbage collector, memory allocation from the
mound is the default behavior. Sometimes optimizations can put certain
numbers on the stack, but instead of relying on an optimizer to do this job, we
might want to make sure that we are always using primitive numbers instead
of some kind of object.
Second, many languages have a 'global interpreter lock' (GIL), which limits
concurrency in many situations. This is done in the name of security, which is
a positive effect, but limits the amount of work that can be done concurrently,
which is a huge negative.
To emphasize these 2 aspects, we will create a small project that uses these
two aspects to a great extent. Because the focus of the example is to embed
Rust in other languages, instead of the problem itself, we will use a toy
example:
Start ten threads. Within each thread, it counts from one to five million. After
all threads have finished, print "completed!".
I have chosen five million based on my particular computer. Here's an

example of this Ruby code:
threads = []
10 .times do
threads << Thread .new do
count = 0
5_000_000 .times do
count = 1
end
end
end
threads.each {| t | t.join}
puts "completed!"
Try running this example, and pick a number that runs for a few seconds.
Depending on the hardware of your computer, you will have to increase or
decrease the number.
On my system, running this program takes 2,156 . If I use some kind of

process monitoring tool, like top , I can see that it only uses one kernel on my
machine. The GIL present doing its job.
While it is true that you are in a synthetic program, one could imagine many
problems similar to this in the real world. For our purposes, picking up a few
threads and occupying them represents a kind of parallel and expensive
computing.
A Rust library
Let's write this problem in Rust. First, let's create a new project with Cargo:
$ charge new embed
$ cd embed
This program is easy to write in Rust:
use std :: thread;
fn process () {
let handles: Vec <_> = ( 0 .. 10 ) .map (| _ | {
thread :: spawn (|| {
let mut _x = 0 ;
for _ in ( 0 .. 5_000_000 ) {
_x =1
}
})
}). collect ();
for h in handles {
h.join (). ok (). expect ( "A thread could not be joined!" );
}
}
Some of this should look familiar to previous examples. We start ten threads,
collecting them in a vector handles . Within each thread, we iterate five
million times, adding one to _x on each iteration. Why the sub-script? Well,
if we remove it and then compile:
$ build charge
Compiling embed v0. 1.0 (file: /// Users / goyox86 / Code / rust / embed)
src / lib.rs: 3 : 1 : 16 : 2 warning: function is never used: ` process` , #
[warn (dead_code)] on by default
src / lib.rs: 3 fn process () {
src / lib.rs: 4 let handles: Vec <_> = ( 0 .. 10 ) .map (| _ | {
src / lib.rs: 5 thread :: spawn (|| {
src / lib.rs: 6 let mut x = 0 ;
src / lib.rs: 7 for _ in ( 0 .. 5 _000_000) {
src / lib.rs: 8 x =1
...
src / lib.rs: 6 : 17 : 6 : 22 warning: variable `x` is assigned to, but never
used, # [warn (unused_variables)] on by default
src / lib.rs: 6 let mut x = 0 ;
^ ~~~~
The first warning is due is due to building a library. If we had a test for this
function, the warning would disappear. But for now it is never called.
The second is related to x versus _x . As a product of actually doing nothing

with x we get a warning. That, in our case, is perfectly fine, since we want to
waste CPU cycles. Using a prefix sub-hyphen we remove the warning.
Finally, we join each of the threads.
So far, however, it is a Rust library, and it doesn't expose anything that can be
called from C. If we wanted to connect it to another language, in its current
state, it wouldn't work. We just need to make a few small changes to fix it.
The first thing is to modify the principle of our code:
# [no_mangle]
pub extern fn process () {
We must add a new attribute, no_mangle . When we create a Rust library, it
changes the name of the function in the compiled output. The reasons for this
are beyond the scope of this tutorial, but in order for other languages to know
how to call the function, we must prevent the compiler from changing the
name in the compiled output. This attribute disables that behavior.
The other change is the pub extern . The pub means that this function can be
called from outside this module, and the extern says that it can be called from
C. That's it! Not many changes.
The second thing we need to do is change a setting in our Cargo.toml . Add this
at the end:
[lib]
name = "embed"
crate-type = [ "dylib" ]
These lines inform Rust that we want to compile our library into a standard
dynamic library. Rust compiles an 'rlib', a specific format from Rust.
Now let's build the project:
$ charge build --release

Compiling embed v0. 1.0 (file: /// Users / goyox86 / Code / rust /
embed)
We have chosen charge build --release , which builds the project with
optimizations. We want it to be as fast as possible! You can find the library
output in target / release :
$ ls target / release /
build deps examples libembeber.dylib native
That libembeber.dylib is our 'shared objects' library. We can use this library like
any shared object library written in C! As a note, this could be libembeber.so or
libembeber.dll , depending on the platform.
Now that we have our Rust library, let's use it from Ruby.
Ruby
Create an embeber.rb file inside our project, and put this inside:
require 'ffi'
Hello module
extend FFI :: Library
ffi_lib 'target / release / libembeber.dylib'
attach_function : process , [] ,: void
end
Hello .process
puts 'completed!'
Before we can run it, we need to install the ffi gem :
$ gem install ffi # this may need sudo
Fetching: ffi- 1.9 . 8 .gem ( 100 %)
Building native extensions. This could take a while ...
Successfully installed ffi- 1.9 . 8
Parsing documentation for ffi- 1.9 . 8
Installing ri documentation for ffi- 1.9 . 8
Done installing documentation for ffi after 0 seconds
1 gem installed
Finally, let's try running it:
$ ruby embeber.rb
completed!
$
Whoa, that was fast! On my system, it takes 0.086 seconds, as opposed to two
seconds than the pure Ruby version. Let's analyze this Ruby code:
require 'ffi'
First we need to require the ffi gem . It allows us to interact with a Rust
library like a C library.
Hello module
extend FFI :: Library
ffi_lib 'target / release / libembeber.dylib'
The Hello module is used to attach the native functions of the shared library.
Inside, we extend the FFI :: Library module and then call the ffi_lib method to
load our shared object library. We simply pass the path in which our library is
stored, which, as we saw earlier, is target / release / libembeber.dylib .
attach_function : process , [] ,: void

The attach_functionmethod is provided by the FFI gem. It is what connects our
process () function in Rust to a method in Ruby with the same name. Because
process () receives no arguments, the second parameter is an empty array, and
since it returns nothing, we pass : void as the final argument.
Hello .process
This is the call to Rust. The combination of our module and the call to
attach_function have configured everything. It looks like a Ruby method but it is
actually Rust code!
puts 'completed!'
Finally, and as a requirement of our project, we print completed! .
That's it! As we have seen, bridging the two languages is really easy, and it
buys us a lot of performance.
Next, let's try Python!
Python
Create an embeber.py file in this directory, and put this in:
from ctypes import cdll
lib = cdll.LoadLibrary ( "target / release / libembeber.dylib" )
lib.process ()
print ( "completed!" )
Even easier! We use cdll from the ctypes module . A quick call to LoadLibrary
later, and then we can call process () .
On my system, it takes 0.017 seconds. Quickly!
Node.js
Node is not a language, but it is currently the dominant server-side Javascript
implementation.
To make FFI with Node, we first need to install the library:
$ npm install ffi

After it is installed, we can use it:
var ffi = require ( 'ffi' );
var lib = ffi.Library ( 'target / release / libembeber' , {

'process' : [ 'void' , []]
});
lib.process ();
console .log ( "completed!" );
It looks more like the Ruby example than the Python example. We use the ffi
module to access ffi.Library () , which allows us to load our shared object
library. We need to note the return type and the types of the function's
arguments, which are void for the return and an empty array to represent no
arguments. From there we simply call the process () function and print the
result.
On my system, this example takes a quick 0.092 seconds.

Chapter III
Rust Cash
So, you've learned how to write some Rust code. But there is a difference
between writing any Rust code and writing good Rust code.
This section consists of relatively independent tutorials that show you how to
take your Rust to the next level. Common patterns and characteristics of the
standard library will be presented. You can read these sections in the order
you prefer.
The Stack and the Mound

Like a systems language, Rust operates at a low level. If you come from a
high-level language, there are some aspects of system programming
languages that you may not be familiar with. The most important is the
functioning of the memory, with the battery and the mound. If you are
familiar with how languages like C use mapping from the stack, this chapter
will be a review. If you are not, you will learn about this general concept, but
with a Rustero approach.
Memory management
These two terms refer to memory management. The stack and the mound are
abstractions that help determine when to allocate and free memory.
Here's a high-level comparison:
The stack is very fast, and that is where the memory is allocated by default in
Rust. But the assignment is local to a function call, and it is limited in size.
The mound on the other hand, is slower, and is assigned by your program.
But it is effectively unlimited in size, and globally accessible.
The battery
Let's talk about this Rust program:
fn main () {
let x = 42 ;
}
This program has a variable (variable binding), x . Memory has to be
allocated from somewhere. Rust allocates from the default stack, which
means that the basic values 'go on the stack'. But what does this mean?
Let's see, when a function is called, some memory is allocated for its local
variables and other extra information. This memory is called 'activation
register' ('stack frame'), for the purpose of this tutorial, we will ignore the
extra information and only consider the local variables to which we are
allocating memory. So in this case, when main () is executed, we assign a 32-
bit integer to our activation register. All of this is handled automatically, as
you can see, we didn't have to write any special Rust code or anything else.
When the function ends, your activation record is released or deallocated.
This happens automatically, we didn't have to do anything special here.
That's it for this simple program. The key thing to understand here is that
memory allocation from the stack is very, very fast. Because we know all the
local variables in advance, we can get all the memory at once. And because
we'll throw it all away, we can get rid of it real quick, too.
The disadvantage is that we cannot keep values hanging around if we need
them for a period longer than the lifetime of a function. We also haven't
talked about what that name means, 'stack'. To do this we need a slightly
more complex example:
fn foo () {
let y = 5 ;
let z = 100 ;
}
fn main () {
let x = 42 ;
foo ();
}
This program has three variables in total: two in foo () , one in main () . Just
like before, when main () is called, a single integer is assigned for its
activation record. But before we demonstrate what happens when foo () is
called, we need to visualize what is happening in memory. Your operating
system presents your program with a very simple vision: an immense list of
addresses, from 0 to a very large number, which represents how much RAM
the machine has. For example if you have a gigabyte of RAM, your addresses
will go from 0 to 1,073,741,824 , a number that comes from 2 , the number of
30
bytes in a gigabyte.
This memory is a kind of giant arrangement: addresses start at zero and
increase to the final number. So here's a diagram of our first activation
record:
AddressNameValue
0 x 42
We have placed x in address 0 , with the value 42
When foo () is called a new activation record is assigned:
AddressNameValue
two z 100
one and 5
0 x 42
Since 0 was reserved for the first frame, 1 and 2 are used for the activation
record of foo () . The stack grows upwards, as we call more functions.
There are some important things to note here. The numbers 0, 1, and 2 exist
for illustrative purposes only, and have no relation to the numbers that a
computer would actually use. In particular, the series of addresses are
separated by a number of bytes, and that separation may even exceed the size
of the value being stored.
After foo () ends, your activation record is released:
AddressNameValue
0 x 42
And then after main () ends, this last value goes away. Easy!
It is called a stack because it works like a stack of plates: the first plate you
place is the last plate you will remove. Stacks are sometimes called 'last in,
first out queues' queues, for these reasons the last value you put in the stack
will be the first you will get from it.
Let's try an example of three levels:
fn bar () {
let i = 6 ;
}
fn foo () {
let a = 5 ;
let b = 100 ;
let c = 1 ;
Pub();
}
fn main () {
let x = 42 ;
foo ();
}
Well, in the first instance, we call main () :
AddressNameValue
0 x 42
Then main () calls foo () :
AddressNameValue
3 c one
two b 100
one to 5
0 x 42
Then foo () calls bar () :
AddressNameValue
4 i 6
3 c one
two b 100
one to 5
0 x 42
Uff! Our stack is growing.
After bar () ends, its activation record is released, leaving only foo () and main
() :
AddressNameValue
3 c one
two b 100
one to 5
0 x 42
Then foo () ends, leaving only main ()
AddressNameValue
0 x 42
We are done then. It is understood? It is like stacking plates: you add to the
top and remove from it.
The Mound
Now, all of this works fine, but not everything works that way. Sometimes,
you need to pass memory between different functions, or keep memory alive
for a longer time than executing a function. For this we use the mound.
In Rust, you can allocate memory from the mound with the type Box <T> .
Here is an example:
fn main () {
let x = Box :: new ( 5 );
let y = 42 ;
}
Here, what happens when main () is called:
AddressName Value
one and 42
0 x ??????
We allocate space for two variables on the stack. y is 42 , as we know so far,
but what about x ? Well, x is a Box <i32> , and the boxes allocate memory
from the mound. The value of the box in question is a structure that has a
pointer to 'the mound'. When function execution begins, and Box :: new () is
called, it allocates some memory for the mound and places 5 there. Memory
now looks like this:
AddressNameValue
2 30 5
... ... ...
one and 42
0 x 2 30
We have 2 on our hypothetical computer with 1GB of RAM. And because
30
our stack grows from scratch, the easiest way to allocate memory is from the
other end. So our first value is in the highest place in memory. And the value
of the structure in x has a flat pointer (raw pointer) to the place we have
assigned on the mound, then the value of x EN 2 , the memory address we
30
have requested.
We haven't talked much about what allocating and releasing memory actually
means in these contexts. Going into the deep detail of it is beyond the scope
of this tutorial, the important thing to note is that the mound is not a simple
pile growing from the opposite side. We will have an example of this later in
the book, but because the mound can be assigned and released in any order, it
can end with 'gaps'. Here is a diagram of the memory distribution of a
program that has been running for some time:
AddressName Value
2 30 5
(2 30 ) - 1
(2 30 ) - 2
(2 30 ) - 3 42
... ... ...
3 and (2 30 ) - 3
two and 42
one and 42
0 x 2 30
In this case, we have assigned four things on the mound, but we have
released two of them. There is a gap between 2 and (2 ) - 3 that is not
30 30
currently being used. The specific detail about how and why this happens
depends on the strategy used to manage the mound. Different programs can
use different 'memory allocators', which are libraries that handle memory
allocation for you. Programs in Rust use jemalloc for that purpose.
Anyway, and back to our example. Because this memory is on the mound, it
can stay alive longer than the function that creates the box. However, in this
case, this does not happen. when the function ends, we need to release the
moving
activation record from main () . Box <T> , however, does have a trick up its
sleeve: Drop . The Drop for Box implementation frees up the memory that has
been allocated when the box is created. Great! So when x leaves (leaves
context), it first frees allocated memory from the mound:
AddressName Value
one and 42
0 x ??????
moving
. We can make memory stay alive longer by transferring ownership, sometimes called 'moving out
of the box'. More complex examples will be covered later. ↩
Then the activation record goes away, freeing up all of our memory.
Arguments and borrowing
We have done some basic examples with the stack and the mound, but what
about function arguments and borrowing? Here's a little Rust program:
fn foo (i: & i32 ) {
let z = 42 ;
}
fn main () {
let x = 5 ;
let y = & x;
foo (y);
}
When we enter main () , the memory looks like this:
Address Name Value
one and 0
0 x 5
x is a simple 5 , and y is a reference to x . So the value of y is the memory

address where x lives, which in this case is 0 .
What happens when we call foo () passing to y as an argument?
Address Name Value
3 z 42
two i 0
one and 0
0 x 5
Activation records are not just for local variables, they are also for arguments.
In this case, we need to have both i , our argument, and z our local variable.
i is a copy of the argument, and . Because the value of y is 0 then that is the
value of i .
This is one reason why borrowing a variable doesn't free up any memory: the
reference value is just a pointer to a memory address. If we got rid of the
underlying memory, things would not go quite right.
A complex example
Okay, let's go through this complex step-by-step program:
fn foo (x: & i32 ) {
let y = 10 ;
let z = & y;
baz (z);
bar (x, z);
}
fn bar (a: & i32 , b: & i32 ) {
let c = 5 ;
let d = Box :: new ( 5 );
let e = & d;
baz (e);
}
fn baz (f: & i32 ) {
let g = 100 ;
}
fn main () {
let h = 3 ;
let i = Box :: new ( 20 );
let j = & h;
foo (j);
}
First, we call main () :
AddressName Value
2 30 twenty
... ... ...
two j 0
one i 2 30
0 h 3
We allocate memory for j , i , and h . i is on the mound, that is why its
value points towards it.
Then at the end of main () , foo () is called:
AddressName Value
2 30 twenty
... ... ...
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
Space is allocated for x , y , and z . The argument x has the same value as j
, because that is what we provided to the function. It is a pointer to address 0
, since j points to h .
Then foo () calls baz () , passing it z :
AddressName Value
2 30 twenty
... ... ...
7 g 100
6 F 4
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
We have allocated memory for f and g . baz () is very short, so when it ends,
we get rid of your activation record:
AddressName Value
2 30 twenty
... ... ...
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
Then foo () calls bar () with x and z :
AddressName Value
2 30 twenty
(2 30 ) - 1 5
... ... ...
10 and 9
9 d (2 30 ) - 1
8 c 5
7 b 4
6 to 0
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
We end up assigning another value on the mound, so we have to subtract one
from 2 . It is easier to write that than 1,073,741,823 . In any case, we set the
30
variables as usual.
At the end of bar () , this calls baz () :
AddressName Value
2 30 twenty
(2 30 ) - 1 5
... ... ...
12 g 100
eleven F 9
10 and 9
9 d (2 30 ) - 1
8 c 5
7 b 4
6 to 0
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
With this, we are at our deepest point! Wow! Congratulations on having
followed all this and having come so far.
Then baz () ends, we get rid of f and g :
Address Name Value
2 30 twenty
(2 30 ) - 1 5
... ...
...
10 and 9
9 d (2 30 ) - 1
8 c 5
7 b 4
6 to 0
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
Next, we return from bar () . d in this case is a Box <T> , so it also releases
what it points to: (2 ) - 1. 30
Address Name Value

2 30 twenty
... ... ...
5 z 4
4 and 10
3 x 0
two j 0
one i 2 30
0 h 3
Then foo () returns:

Address Name Value
2 30 twenty
... ... ...
two j 0
one i 2 30
0 h 3
Then finally main () returns, which cleans up the rest. When i is released (via
Drop ) it will also clean the rest on the mound.
What do other languages do?

Most languages with a garbage collector map from the mound by default.
This means that all the values are inside boxes (boxed). There are a number
of reasons why this is done this way, but they are beyond the scope of this
tutorial. Also, there are some optimizations that make this not 100% true all
the time. Instead of relying on the stack and Drop to clean the memory, the
garbage collector is in charge of managing the mound.
Which to use
If the pile is faster and easier to use, why do we need the mound? A great
reason is that allocation from the stack means you only have LIFO semantics
to reclaim storage. Allocation from the mound is strictly more general,
allowing storage to be taken and returned to the pool in arbitrary order, but at
a cost of complexity.
Generally, you should prefer allocation from the stack, which is why Rust
assigns from the default stack. The LIFO model of the stack is simpler, on a
fundamental level. This has two major impacts: runtime efficiency and
semantic impact.
Execution time efficiency.
Managing memory for the stack is trivial: The machine simply increments a
single value, the so-called "stack pointer". Memory management for the
mound is not: Memory allocated from the mound is released at arbitrary
points, and each block of memory allocated from the mound can be arbitrary
in size, memory manager generally must work much harder to identify
memory that can be reused.
If you would like to dive deeper into this topic in greater detail, this paper is a
very good introduction.
Semantic impact
Stack-allocation impacts the Rust language itself, and thus the developer's
mental model. The LIFO semantics is what drives how the Rust language
handles automatic memory management. Even the deallocation of a uniquely-
owned heap-allocated box can be driven by the stack-based LIFO semantics,
as discussed throughout this chapter. The flexibility (ie expressiveness) of
non LIFO-semantics means that in general the compiler cannot automatically
infer at compile-time where memory should be freed; it has to rely on
dynamic protocols, potentially from outside the language itself, to drive
deallocation (reference counting, as used by Rc and Arc, is one example of
this).
Mapping from the stack impacts Rust as a language, and with it the
developer's mental model. LIFO semantics is what drives how the Rust
language handles automatic memory handling. Even releasing an assigned
box from the mound with a single owner can be handled by LIFO semantics,
as discussed in this chapter. The flexibility (eg expressiveness) of non-LIFO
semantics means that in general the compiler cannot infer automatically and
at compile time where memory should be freed; it has to rely on dynamic
protocols, potentially external to the language, to perform memory release
(reference counting, like the one used in Rc <T> and Arc <T> , is an example).
When taken to the extreme, the greater expressive power of allocation from
the mound comes at the cost of either significant runtime support (eg in the
form of a garbage collector) or significant effort by the programmer (in the
form of explicit manual calls that require verification not provided by the
Rust compiler).
Tests
Testing programs can be an effective way to show the presence of bugs, but it
is hopelessly inadequate to show their absence. Edsger W. Dijkstra, "The
Humble Programmer" (1972)
We will talk about how to test Rust code. What we will not be talking about
is the correct way to test Rust code. There are many schools of thought
regarding the correct and incorrect way of writing tests. All these approaches
use the same basic tools, in this section we will show you the syntax to make
use of them.
The test attribute

In essence, a test in Rust is a function that is annotated with the test attribute .
We are going to create a new project called adder with Cargo:
$ new adder charge
$ cd adder
Cargo will automatically generate a simple test when you create a new
project. Here is the content of src / lib.rs :
#[test]
fn it_works () {
}
Note the # [test] . This attribute indicates that this is a test function. It
currently has no body. But that is enough to happen! We can run the tests
with test charge :
$ test charge
Compiling adder v0. 1.0 (file: /// Users / goyox86 / Code / rust / adder)
Running target / debug / adder-ba17f4f6708ca3b9
running 1 test
test it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
Doc-tests adder
running 0 tests

Charge I compile and run our tests. There are two sets of output here: one for
the tests we write, and one for the documentation tests. We will talk about
these later. For now let's see this line:
Note the it_works . It comes from the name of our function:
fn it_works () {
#}
We also get a summary line:
So why do our empty tests pass? Any test that doesn't panic! passes, and any
tests that panic! failure. Let's fail our test:
#[test]
fn it_works () {
assert! ( false );
}
assert!it is a macro provided by Rust which takes an argument: if the
argument is true , nothing happens. If the argument is false , assert! ago panic!
. Let's run our tests again:
$ test charge
running 1 test
test it_works ... FAILED
failures:
---- it_works stdout ----

thread 'it_works' panicked at 'assertion failed: false' , src / lib.rs: 3
failures:
it_works
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured
thread '<main>' panicked at 'Some tests failed' ,

/Users/rustbuild/src/rust-buildbot/slave/stable-dist-rustc-
mac/build/src/libtest/lib.rs: 259
Rust tells us that our test has failed:
test it_works ... FAILED
And it is reflected in the summary line:
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured
We also get a non-zero return value:
$ echo $?
101
This is very useful to integrate cargo test with other tools.
We can reverse our test failure with another attribute: should_panic :
#[test]
# [should_panic]
fn it_works () {
assert! ( false );
}
These tests will be successful if we panic! and will fail if completed. Let's try:
$ test charge
running 1 test
Doc-tests adder
running 0 tests

Rust provides another macro, assert_eq! , which compares two arguments to
verify equality:
#[test]
# [should_panic]
fn it_works () {
assert_eq! ( "Hello" , "world" );
}
Does this test pass or fail? Due to the presence of the should_panic attribute , it
passes:
$ test charge
running 1 test
Doc-tests adder
running 0 tests

Should_panic tests can be fragile, it is difficult to guarantee that the test did not
fail for an unexpected reason. To aid in this, an optional parameter expected
can be added to the should_panic attribute . The test will ensure that the error
message contains the provided message. A safer version of the test would be:
#[test]
# [should_panic (expected = "assertion failed")]
fn it_works () {
assert_eq! ( "Hello" , "world" );
}
That was it for the basics! Let's write a 'real' test:
pub fn sum_two (a: i32) -> i32 {
a+2
}
#[test]
fn it_works () {
assert_eq! (4, sum_two (2));
}
This is a very common use of assert_eq! : call some function with some known
arguments and compare the output of that call with the expected output.
The tests module

There is a way in which our example is not idiomatic: it lacks the tests
module . The idiomatic way of writing our example looks like this:
a+2
}
# [cfg (test)]
mod tests {
use super :: sum_two;
#[test]
fn it_works () {
}
}
There are a few changes here. The first is the inclusion of a mod tests with a
cfg attribute . The module allows us to group all our tests, and also allows us
to define support functions if necessary, all that is not part of our crate. The
cfg attribute only compiles our test code if we were trying to run the tests.
This can save compilation time, it also ensures that our tests are completely
excluded from a normal compilation.
The second change is the use statement . Because we are in an internal
module, we need to make our test available within our current scope. This
can be annoying if you have a large module, and that is why the use of the
glob facility is common . Let's change our src / lib.rs to make use of it:

a+2
}
# [cfg (test)]
mod tests {
use super :: *;
#[test]
fn it_works () {
}
}
Note the line use different. Now we run our tests:
$ test charge
running 1 test
test tests :: it_works ... ok
Doc-tests adder
running 0 tests

Works!
The current convention is to use the tests module to hold your "unit-style"
tests. Anything that just tests a small piece of functionality goes here. But
what about "integration-style" testing? For them, we have the tests directory .
The tests directory

To write an integration test, let's create a tests directory and put a tests / lib.rs
file inside, with the following content:
extern crate adder;
#[test]
fn it_works () {
assert_eq! (4, adder :: sum_two (2));
}
It looks similar to our previous tests, but slightly different. Now we have an
extern crate adder at the beginning. This is because the tests in the directory are a
separate crate, so we must import our library. This is also why tests is a great
place to write integration tests: these tests use the library just like any other
consumer would.
Let's run them:
$ test charge
Running target / debug / lib -f 71036151ee98b04
running 1 test
running 1 test

Doc-tests adder
running 0 tests

We now have three sections: Our previous tests were also run, along with the
new integration test.
That was it for the tests directory . The tests module is not necessary here,
since the complete module is dedicated to tests.
Finally let's take a look at that third section: documentation tests.
Documentation tests
Nothing is better than documentation with examples. Nothing is worse than
examples that don't work, because the code has changed since the
documentation was written. Regarding this, Rust supports the automatic
execution of the examples present in your documentation. Here's a polished
src / lib.rs with examples:
//! The àdder` crate provides functions that add numbers to other numbers.
//!
//! # Examples
//!
//!
//! assert_eq! (4, adder :: add_two (2)); //! `` ''
/// This function adds two to its argument. /// /// # Examples /// /// /// use adder ::
add_two; /// /// assert_eq! (4, add_two (2)); /// pub fn add_two (a: i32) -> i32 {a + 2}
[cfg (test)]
mod tests {use super :: *;
#[test]
fn it_works () {
assert_eq! (4, add_two (2));
}
}
Note the module-level documentation with `//!` And the function-level documentation with `///`. Rust
documentation supports Markdown in comments and treble (\ `\` \ `) delimit code blocks. It is
conventional to include the `# Examples` section, exactly like this, followed by the examples.
Let's run the tests again:
bash
$ test charge
Compiling adder v0.1.0 (file: /// Users / goyox86 / Code / rust / adder)
Running target / debug / lib-f71036151ee98b04
running 1 test
running 1 test
Doc-tests adder
running 2 tests
test _0 ... ok
test sum_two_0 ... ok

Now we have all three types of tests running! Note the names of the
documentation tests: _0 is generated for the module test, and sum_two_0 for
the function test. These numbers will auto increment with names like
sum_two_1 as more examples are added.
Conditional Compilation
Rust has a special attribute, # [cfg] , that allows you to compile code based on
an option provided to the compiler. It has two forms:
# [cfg (foo)]
# fn foo () {}
# [cfg (bar = "baz")]
# fn bar () {}
It also has some helpers:
# [cfg (any (unix, windows))]
# fn foo () {}
# [cfg (all (unix, target_pointer_width = "32"))]
# fn bar () {}
# [cfg (not (foo))]

# fn not_foo () {}
Which can be nested arbitrarily:
# [cfg (any (not (unix), all (target_os = "macos", target_arch = "powerpc")))]
# fn foo () {}
To activate or deactivate these switches, if you are using Cargo, they are
configured in the [features] section of your Cargo.toml
[features]
# No features by default
default = []
# The “secure-password” feature depends on the bcrypt package.
secure-password = [ "bcrypt" ]
When we do this, Cargo passes an option to rustc :
--cfg feature = "$ {feature_name}"
The sum of those cfg options will determine which are activated, and
consequently, which code will be compiled. Let's take this code:
# [cfg (feature = "foo")]
mod foo {
}
If we compile it with cargo build --features "foo" , Cargo will send the option --cfg
feature = "foo" to rustc , and the output will have the mod foo . If we compile with
a normal build charge , no extra option will be provided, and because of this, no
foo module will exist.
cfg_attr
You can also configure another attribute based on a cfg variable with cfg_attr :
# [cfg_attr (a, b)]
# fn foo () {}
It will be the same as # [b] if a is configured by a cfg attribute , and nothing
else.
cfg!
The syntax extension also allows you to use this type of options at any other
point in your code:
if cfg! (target_os = "macos" ) || cfg! (target_os = "ios" ) {
println! ( "Think Different!" );
}
These will be replaced by true or false at compile time, depending on
configuration options.
Documentation
Documentation is an important part of any software project and a first-class
citizen at Rust. Let's talk about the tools that Rust provides to document your
projects.
About rustdoc
The Rust distribution includes a tool, rustdoc , in charge of generating the
documentation. rustdoc is also used by Cargo through cargo doc .
Documentation can be generated in two ways: from source code, or from
Markdown files.
Documenting source code
The main way to document a Rust project is through the annotation of the
source code. For this purpose, you can use documentation comments:
/// Build a new `Rc`.
///
/// # Examples
///
///
/// use std :: rc :: Rc; /// /// let five = Rc :: new (5); /// `` `pub fn new
(value: T) -> Rc {// the implementation goes here}
The code above generates documentation that looks like [this] [rc-new] (English). I've left the
implementation out, with a regular comment instead. That's the first thing to note about this annotation:
use `///`, instead of `//`. The triple slash indicates that it is a documentation comment.
Documentation comments are written in Markdown format.

Rust maintains a record of such comments, a record that he uses when generating documentation. This
is important when documenting things like enums:
`` 'rust
/// The type Òption`. See [module level documentation] (../) for more
information.
enum Option <T> {
/// No value
None
/// Some `T` value
Some (T),
}
The above works, but this does not:
/// The type Òption`. See [module level documentation] (../) for more
information.
enum Option {
None, /// No value
Some (T), /// Some value `T`
}
You will get an error:
hello.rs:4:1: 4: 2 error: expected ident, found `}`
hello.rs:4}
^
Writing documentation comments

Either way, let's cover each part of this comment in detail:
/// Build a new `Rc <T>`.
# fn foo () {}
The first line of a documentation comment should be a short summary of its
functionality. A sentence. Only the basics. High level.
///
/// Other details about the construction of `Rc <T>` s, perhaps describing
semantics
/// complicated, maybe additional options, anything extra.
///
# fn foo () {}
Our original example only had one summary line, but if we had more to say,
we could have added more explanation in a new book.
Special sections
/// # Examples
# fn foo () {}
Below are the special sections. These are indicated with a header, # . There
are three types of header that are commonly used. These are not special
syntax, just convention, for now.
/// # Panics
# fn foo () {}
Bad and unrecoverable uses of a function (eg programming errors) in Rust
are usually indicated by panics, which at least kill the current thread. If your
role has a non-trivial contract like this, which is panicked / enforced,
documenting it is very important.
/// # Failures
# fn foo () {}
If your function or method returns a Result <T, E> , then describing the
conditions under which Err (E) returns is a good thing to do. This is slightly
less important than Panics , as it is encoded in the type system, but it is still
something to do.
/// # Safety
# fn foo () {}
If your function is unsafe (insecure), you should explain what are the
invariants that must be maintained by the caller.
/// # Examples
///
///
/// use std :: rc :: Rc; /// /// let five = Rc :: new (5); /// `` `
fn foo () {}
Third, Èxamples`, include one or more examples of the use of your function or method, and your users
will love you. These examples go inside code block annotations, which we will talk about in a moment,
they can have more than one section:
`` 'rust
/// # Examples
///
/// Simple `& str` patterns:
///
///
/// let v: Vec <& str> = "Mary had a little lamb" .split ('') .collect (); ///
assert_eq! (v, vec! ["Mary", "had", "a", "little lamb"]); /// /// /// More complex
patterns with lambdas: /// /// /// let v: Vec <& str> = "abc1def2ghi" .split (| c: char |
c.is_numeric ()). collect (); /// assert_eq! (v, vec! ["abc", "def", "ghi"]); /// `` `
fn foo () {}
Let's discuss the details of those code blocks.
#### Code block annotations

To write some Rust code in a comment, use triple bass:
`` 'rust
///
/// println! ("Hello, world"); /// `` `
fn foo () {}
If you want code other than Rust, you can add an annotation:
`` 'rust
/// `` `c
/// printf ("Hello, world \ n");
///
fn foo () {}
The syntax of this section will be highlighted according to the language you are showing. If you are
only displaying plain text, use `text`.
Here, it is important to choose the correct annotation, because `rustdoc` uses it in an interesting way: It
can be used to test your examples, so that they do not become obsolete over time. If you have any C
code but `rustdoc` thinks it's Rust, it's because you forgot the annotation,` rustdoc` complained when
trying to generate the documentation.
## Documentation as evidence
Let's discuss our sample documentation:
`` 'rust
///
/// println! ("Hello, world"); /// `` `
fn foo () {}
You'll notice that you don't need a `fn main ()` or something else. `rustdoc` will automatically add a
main () around your code, and in the right place. For example:
`` 'rust
///
fn foo () {}
It will become the test:
`` 'rust
fn main () {
use std :: rc :: Rc;
let five = Rc :: new (5);
}
Here is the complete algorithm that rustdoc uses to post-process the examples:
1. Any leftover #! [Foo] attributes are left intact as a crate attribute.
2. Some common attributes are inserted, including unused_variables ,
unused_assignments , unused_mut , unused_attributes , and dead_code . Small
examples occasionally trigger these lints.
3. If the example does not contain extern crate , then the extern crate
<micrate>; is inserted.
4. Finally, if the example does not contain fn main , the text is wrapped in fn
main () {your_code}
Sometimes this is not enough. For example, all these code examples with ///
that we've been talking about? Plain text:
/// Some documentation.
# fn foo () {}
Looks different on departure:
/// Some documentation.
# fn foo () {}
Yes, it is correct: you can add lines that start with # , and these will be
removed from the output, but they will be used in the compilation of your
code. You can use this to your advantage. In this case, the documentation
comments need to apply to some kind of function, so if I want to show just
one documentation comment, I need to add a little function definition below.
At the same time, it is there just to satisfy the compiler, so hiding it makes the
example cleaner. You can use this technique to explain longer examples in
detail, while preserving your documentation's ability to be tested. For
example, this code:
let x = 5 ;
let y = 6 ;
println! ( "{}" , x + y);
Here's an explanation, rendered:
First, we assign x the value of five:
let x = 5 ;
# let y = 6 ;
# println! ( "{}" , x + y);
Next, we assign six to y :
# let x = 5 ;
let y = 6 ;
# println! ( "{}" , x + y);
Finally, we print the sum of x and y :
# let x = 5 ;
# let y = 6 ;
println! ( "{}" , x + y);
Here's the same explanation, in plain text:
First, we assign x the value of five:
let x = 5;
# let y = 6;
# println! ("{}", x + y);
Next, we assign six to y :
# let x = 5;
let y = 6;
# println! ("{}", x + y);
Finally, we print the sum of x and y :
# let x = 5;
# let y = 6;
println! ("{}", x + y);
By repeating all parts of the example, you can ensure that your example still
compiles, showing only the parts relevant to your explanation.
Documenting macros
Here is an example of documentation to a macro:
/// Panic with a provided message unless the expression is evaluated to true.
///
/// # Examples
///
///
/// # # [macro_use] extern crate foo; /// # fn main () {/// panic_unless! (1 + 1
== 2, "The mathematics is broken."); /// #} /// /// /// should_panic /// # #
[macro_use] extern crate foo; /// # fn main () {/// panic_unless! (true == false,
"I am broken."); /// #} /// `` `
[macro_export]
macro_rules! panic_unless {($ condition: expr, $ ($ rest: expr), +) => ({if! $
condition {panic! ($ ($ rest), +);}}); }
fn main () {}
You will notice three things: we need to add our own èxtern crate` line, so that we can add the` #
[macro_use] àttribute. Second, we will need to add our own `main ()`. Finally, a judicious use of `#` to
comment on those two things, so that they are shown in the output.
### Running documentation tests
To run the tests you can:
bash
$ rustdoc --test path / to / my / crate / root.rs
# or
$ test charge
Correct, charge test tests embedded documentation as well. However, I load test
, it won't test binary crates, just libraries. This is because of the way rustdoc
works: it links to the library to be tested, but in the case of a binary, there is
nothing to link to.
There are a few more annotations that are useful to help rustdoc do the right
thing when testing your code:
/// `` ìgnore
/// fn foo () {
///
fn foo () {}
The ìgnore` directive tells Rust to ignore the code. This is the form that you will almost never want, as
it is the most generic. Instead, consider scoring with `text` if it is not code, or use` # `s to get a working
example that only shows the part that interests you.
`` 'rust
/// `` `should_panic
/// assert! (false);
///
fn foo () {}
`should_panic` tells` rustdoc` that the code must compile correctly, but without the need to successfully
pass a test.
`` 'rust
/// `` `no_run
/// loop {
/// println! ("Hello, world");
///}
///
fn foo () {}
The `no_run` attribute will compile your code, but will not execute it. This is important for examples
like "Here's how to start a network service," which you should make sure compiles, but it could cause
an infinite loop!
### Documenting modules

Rust has another type of documentation comment, `//!`. This comment does not document the next
item, it comments the item that encloses it. In other words:
`` 'rust
mod foo {
//! This is documentation for the `foo` module.
//!
//! # Examples
// ...
}
This is where you will see //! most often used: for module documentation. If
you have a module in foo.rs , frequently when you open its code you will see
this:
//! A module to use `foo`s.
//!
//! The `foo` module contains a lot of functionality blah blah blah
Documentation feedback style
Other documentation
All of this behavior works on non-Rust files as well. Because comments are
written in Markdown, they are often .md files .
When you write documentation to Markdown files, you don't need to prefix
the documentation with comments. For example:
/// # Examples
///
///
fn foo () {}
it's just
~~~ markdown
# Examples
use std :: rc :: Rc;
let five = Rc :: new (5);
~~~
when it is in a Markdown file. There is only one detail, markdown files need to have a title like this:
markdown
% Title
This is the sample documentation

This line % must be located in the first line of the file.
doc attributes
At a deeper level, documentation comments are another way to write
documentation attributes:
/// Este
# fn foo () {}
# [doc = "this"]
# fn bar () {}
they are the same as these:
//! Este
#! [doc = "/// this"]

You will not frequently see this attribute being used to write documentation,
but it can be useful when you are changing certain options, or writing a
macro.
Re-exports
rustdoc will show the documentation for a public re-export in both places:
extern crate foo;
pub use foo :: bar;

The above will create documentation for the bar within the documentation for
the crate foo , as well as the documentation for your crate. It will be the same
documentation in both places.
This behavior can be suppressed with no_inline :
extern crate foo;
# [doc (no_inline)]
pub use foo :: bar;
Controlling HTML
You can control some aspects of the HTML that rustdoc generates through the
#! [Doc] version of the attribute:
#! [doc (html_logo_url = "http://www.rust-lang.org/logos/rust-logo-

128x128-blk-v2.png",
html_favicon_url = "http://www.rust-lang.org/favicon.ico",
html_root_url = "http://doc.rust-lang.org/")]
This sets up a few options, with a logo, favicon, and root URL.
Generation options
also contains a few options on the command line, for further
rustdoc
customization:
--html-in-header FILE : includes the FILE content at the end of the <head> ... </head>
section .
--html-before-content FILE : includes the FILE content after <body> , before the
rendered content (including the search bar).
--html-after-content FILE - Includes the FILE content after all rendered content.
Safety note
Markdown in documentation comments is set raw on the final page. Be
careful with literal HTML:
/// <script> alert (document.cookie) </script>
# fn foo () {}
Iterators
Let's talk about cycles.
Remember the Rust for cycle ? Here is an example:
for x in 0..10 {
println! ("{}", x);
}
Now that you know more about Rust, we can talk in detail about how this
code works. The ranges ( 0..10 ) are iterators. An iterator is something we can
call the .next () method on repeatedly, and the iterator provides us with a
sequence of elements.
For example:
let mut range = 0..10;
loop {
match rank.next () {
Some (x) => {
println! ("{}", x);
},
None => {break}
}
}
We create a link (a variable) to the range, our iterator. Then we iterate
through the loop cycle , with an internal match . This match uses the result of
rank.next () , which gives us a reference to the next value in the iterator. next
returns an Option <i32> , in this case, which will be Some (i32) when we have a
value and None when we run out of values. If we get Some (i32) , we print it,
and if we get None , we break the loop, leaving it through break .
This code example is basically the same as our version of a for for loop . The
for loop is just a practical way to write a loop / match / break construct .
However, for loops are not the only thing that uses iterators. Write your own
iterator involves implementing the Trait Iterator . While doing so is outside
the scope of this guide, Rust provides a number of useful iterators to
accomplish various tasks. Before talking about that, we should talk about an
anti-patron. Said anti-pattern is to use ranges in the manner outlined above.
Yes, we just talked about how cool the ranges are. But they are also very
primitive. For example, if we need to iterate through the content of a vector,
we might be tempted to write something like this:
let nums = vec! [1, 2, 3];
for i in 0..nums.len () {
println! ("{}", nums [i]);
}
This is not strictly worse than using an iterator. You can iterate into vectors
directly, write this:
let nums = vec! [1, 2, 3];
for num in & nums {

println! ("{}", num);
}
There are two reasons for doing it this way. First, express what we want more
directly. We iterate through the entire vector, instead of iterating through
indexes and then indexing the vector. Second, this version is more efficient:
in the first version we will have checks of extra limits because it uses
indexing, nums [i] . In the second example and because with the iterator we
give a reference to each element at the same time, there is no limit check.
This is very common in iterators: we can ignore unnecessary limit checks,
while knowing that we are safe.
There is another detail here that is not 100% clear due to println operation ! .
num is of type & i32 . A reference to an i32 , not an i32 . println! handles
dereferencing for us, that's why we don't see it. This code is also correct:
let nums = vec! [1, 2, 3];
for num in & nums {

println! ("{}", * num);
}
Now we are referencing num explicitly. Why & nums give us references?
Firstly, because we explicitly request it with & . Second, if it gave us the data
itself, we would have to own it, which would involve creating a copy of the
data and then giving us that copy. With references, we are only borrowing a
reference to the data, and therefore we only pass a reference, without the need
to transfer the membership.
So now that we've established that ranges are sometimes not what we want,
let's talk about what we want.
There are three broad classes of things that are relevant: iterators, iterator
adapters, and consumers . Here are some definitions:
Iterators provide a sequence of values.
Iterator adapters operate on one iterator, producing a new iterator with a different
sequence of output.
Consumers operate on an iterator, producing a final set of values.
Let's talk about consumers first, because we've already seen an iterator, the
ranges.
Consumers
A consumer operates on an iterator, returning some kind of value or values.
The most common consumer is collect () . This code does not compile, but
shows the intention:
let uno_hasta_cien = (1..101) .collect ();
As you can see we call collect () on the iterator. collect () takes as many values
as the iterator provides, returning a collection of results. So why doesn't this
code compile? Rust can't determine what kinds of things you want to collect,
and that's why you need to let him know. This is the version that compiles:
let uno_hasta_cien = (1..101) .collect :: <Vec <i32>> ();
If you remember, the syntax :: <> allows you to give a hint about the type, in
our case we are saying that we want a vector of integers. It is not always
necessary to use the full type. _ will allow you to give a partial hint about the
type:
let one_up to one hundred = (1..101) .collect :: <Vec <_>> ();
This says "Collect in a Vec <T> , please, but infer that it's T for me.". _ is for
this reason sometimes called a "type placeholder".
collect () is the most common consumer, but there are others. find () is one of
them:
let mayor_a_cuarenta_y_dos = (0..100)
.find (| x | * x> 42);
match mayor_a_cuarenta_y_dos {
Some (_) => println! ("We have some numbers!"),
None => println! ("No numbers were found :("),
}
find receives a closure, and works on a reference to each element of an
iterator. Said closure returns true if the element is the one we are looking for
and false otherwise. Because we might not find an element that meets our
criteria, find returns an Option instead of an element.
Another major consumer is fold . It looks like this:
let sum = (1..4) .fold (0, | sum, x | sum + x);
. It takes two arguments: the first is an element
fold (base, | accumulator, element | ...)
called base . The second is a closure which in turn takes two arguments: the
first is called the accumulator , and the second is an element . In each
iteration, the closure is called, and the result is used as the accumulator value
in the next iteration. In the first iteration, the base is the accumulator value.
Well that's a little confusing. Let's examine the values of all things in this
iterator:
baseaccumulatorelementclosure result
0 0 one one
0 one two 3
0 3 3 6
We have called fold () with these arguments:
# (1..4)
.fold (0, | sum, x | sum + x);
So 0 is our base, sum is our accumulator, and x is our element. In the first
iteration, we assign sum to 0 and x is the first element in our range, 1 . Then
we add sum and x , which gives us 0 + 1 = 1 . In the second iteration, that
value becomes the value of our accumulator, sum , and the element is the
second element in the range, 2 . 1 + 2 = 3 and likewise becomes the
accumulator value for the last iteration. In that iteration, x is the last element,
3 , and 3 + 3 = 6 , the final result for our sum . 1 + 2 + 3 = 6 , that's the result we
get.
Whew. Fold may be a little strange at first glance, but once it clicks, you can
use it everywhere. Whenever you have a list of things, and need a single
result, fold is appropriate.
Consumers are important because of an additional property of iterators that
we haven't talked about yet: laziness. Let's talk more about iterators and
you'll see why consumers are important.
Iterators
As we've said before, an iterator is something we can call the .next () method
on repeatedly, and it returns a sequence of elements. Because we need to call
the method, the iterators can be lazy and not generate all the values in
advance. This code, for example, does not generate numbers 1-99 . Instead it
creates a value that represents the sequence:
let nums = 1..100;
Because we did nothing with the range, it did not generate the sequence. Let's
add a consumer:
let nums = (1..100) .collect :: <Vec <i32>> ();
Now collect () will require the range to supply some numbers, and therefore
will have to do the work of generating the sequence.
Ranges are one of the two basic forms of iterators that you will see. The other
is iter () . iter () can transform a vector into a simple iterator that provides one
element at a time:
let nums = vec! [1, 2, 3];
for num in nums.iter () {
println! ("{}", num);
}
These two basic iterators should be useful. There are more advanced iterators,
including those that are infinite.
Enough about iterators, Iterator Adapters are the last concept related to
Iterators that we should mention. Let's do it!
Iterator adapters
The adapters iterators take an iterator and modify it in some way, producing
a new one. The simplest is called map :
(1..100) .map (| x | x + 1);
map is called in another iterator, map produces a new iterator in which each
reference to an element has the closure that has been provided as an
argument. The previous code will give us the numbers 2-100 , well, almost! If
you compile the example, you will get a warning:
warning: unused result which must be used: iterator adapters are lazy
and
do nothing unless consumed, # [warn (unused_must_use)] on by
default
(1..100) .map (| x | x + 1);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Laziness strikes again! That closure will never run. This example does not
print any number:
(1..100) .map (| x | println! ("{}", X));
If you are trying to run a closure in an iterator to get its side effects use a for .
for i in (1 ..). take (5) {
println! ("{}", i);
}
This will print:
one
two
3
4
5
is an adapter that takes a closure as an argument. This closure returns
filter ()
true or false . The new iterator that filter () produces only elements for which
the closure returns true :
for i in (1..100) .filter (| & x | x% 2 == 0) {
println! ("{}", i);
}
This will print all even numbers between one and one hundred. (Note that
because filter does not consume the elements being iterated, a reference to
each element is passed to it, therefore, the predicate uses the & x pattern to
extract the integer.)
(one..)
.filter (| & x | x% 2 == 0)
.filter (| & x | x% 3 == 0)
.take (5)
.collect :: <Vec <i32>> ();
The above gives you a vector containing 6 , 12 , 18 , 24 , and 30 .
This is a small sample of the things that iterators, iterator adapters, and
consumers can help you with. There are a variety of really useful iterators,
along with the fact that you can write your own. Iterators provide a safe and
efficient way to manipulate all kinds of lists. They are a bit unusual at first
glance, but if you play around with them a bit, you will be hooked
Concurrence
Concurrency and parallelism are two incredibly important topics in computer
science, they are also a hot topic in the industry today. Computers
increasingly have more and more cores, even so, still some developers are not
ready to fully use us.
Rust's memory management security also applies to its concurrency history.
Even concurrent programs must be memory-safe, with no race conditions.
Rust's type system is up to the challenge, and gives you powerful avenues to
reason about concurrent code at compile time.
Before we talk about the concurrency features that come with Rust, it's
important to understand something: Rust is low-level, low enough to the
point that all of these facilities are implemented in the standard library. This
means that if you don't like some aspect of the way Rust handles
concurrency, you can implement an alternative way of doing it. Mine is a
vivid example of this principle in action.
Threads
The standard Rust library provides a library for thread handling, which
allows you to run rust code in parallel. Here is a basic example of using std ::
thread :
use std :: thread;
fn main () {
thread :: spawn (|| {
println! ( "Hello from a thread!" );
});
}
The thread :: spawn () method accepts a closure as an argument, a closure that is
executed on a new thread. thread :: spawn () returns a handle to the new thread,
which can be used to wait for the thread to finish and then extract its result:
use std :: thread;
fn main () {
let handle = thread :: spawn (|| {
"Hello from a thread!"
});
println! ( "{}" , handle.join (). unwrap ());
}
Many languages possess the ability to run threads, but it is wildly insecure.
There are whole books on how to prevent mistakes that occur as a result of
sharing mutable state. Rust helps with its rate system, preventing race
conditions at compile time. Let's talk about how you can effectively share
things between threads.
Mutable State Shared Safe
Due to Rust's type system, we have a concept that sounds like a lie: "safe
shared mutable state". Many developers agree that the shared mutable state is
very, very bad.
Someone once said:
The shared mutable state is the root of all evil. Most languages try to deal
with this problem through the 'mutable' part, but Rust confronts it by solving
the 'shared' part.
The same membership that prevents improper use of pointers also helps
eliminate race conditions, one of the worst concurrency-related bugs.
As an example, a Rust program that would have a career condition in many
languages. In Rust I would not compile:
use std :: thread;
fn main () {
let mut data = vec! [1u32, 2, 3];
for i in 0..3 {
data [i] + = 1;
});
}

}
The above produces an error:
8:17 error: capture of moved value: `data`
data [i] + = 1;
^ ~~~
In this case, we know that our code should be safe, but Rust is not sure about
it. It is not really safe, if we had a reference to data in each thread, and the
thread belongs to the reference, we would have three owners! That is wrong.
We can fix this by using the Arc <T> type , a pointer with atomic reference
count. The 'atomic' part means that it is safe to share between threads.
Arc <T> assumes one more property about its content to ensure that it is safe to
share between threads: it assumes that its content is Sync . But in our case, we
want to mutate the value. We need a guy who can make sure that only one
person at a time can mutate what's inside. For that, we can use the Mutex <T>
type . Here is the second version of our code. It still doesn't work, but for a
different reason:
use std :: thread;
use std :: sync :: Mutex;
fn main () {
let mut data = Mutex :: new (vec! [1u32, 2, 3]);
for i in 0..3 {
let data = data.lock (). unwrap ();
data [i] + = 1;
});
}

}
Here is the error:
: 9: 9: 9:22 error: the trait `core :: marker :: Send` is not implemented
for the type` std :: sync :: mutex :: MutexGuard <'_, collections :: vec ::
Vec> `[E0277]
: 11 thread :: spawn (move || {
^ ~~~~~~~~~~~~
: 9: 9: 9:22 note: `std :: sync :: mutex :: MutexGuard <'_, collections ::
vec :: Vec>` cannot be sent between threads safely
: 11 thread :: spawn (move || {
^ ~~~~~~~~~~~~
You see, Mutex has a lock method that has this signature:
fn lock (& self) -> LockResult <mutexguard>
</ mutexguard
Because not implemented for MutexGuard <T> , we cannot transfer
Send is
MutexGuard <T> between threads, which results in the error.
We can use Arc <T> to correct the error. Here is the functional version:
use std :: sync :: {Arc, Mutex};

use std :: thread;
fn main () {
let data = Arc :: new (Mutex :: new ( vec! [ 1u32 , 2 , 3 ]));
for i in 0 .. 3 {
let data = data.clone ();
let mut data = data.lock (). unwrap ();
data [i] + = 1 ;
});
}
}
Now we call clone () on our Arc , which increments the internal counter. This
handle is then moved into the new thread. Let's examine the thread body
more closely:
# use std :: sync :: {Arc, Mutex};
# use std :: thread;
# fn main () {
# let data = Arc :: new (Mutex :: new ( vec! [ 1u32 , 2 , 3 ]));
# for i in 0 .. 3 {
# let data = data.clone ();
data [i] + = 1 ;
});
#}
# thread :: sleep_ms ( 50 );
#}
First, we call lock () , which gets the mutual exclusion lock. Because this
operation may fail, this method returns a Result <T, E> , and because this is just
an example, we do unwrap () on it to get a reference to the data. Real code
would have more robust error handling here. We are free to mutate it, since
we have the blockade.
Lastly, while the threads run, we wait for the culmination of a short timer.
This is not ideal: we could have chosen a reasonable time to wait, but we will
most likely wait longer than necessary, or not long enough, depending on
how long the threads take to finish computing when the program runs.
A more precise alternative to the timer would be to use one of the
mechanisms provided by the Rust standard library for inter-thread
synchronization. Let's talk about them: the channels.
Channels
Here is a version of our code that uses channels for synchronization, instead
of waiting for a specific time:
use std :: sync :: {Arc, Mutex};

use std :: thread;
use std :: sync :: mpsc;
fn main () {
let data = Arc :: new (Mutex :: new ( 0u32 ));
let (tx, rx) = mpsc :: channel ();
for _ in 0 .. 10 {
let (data, tx) = (data.clone (), tx.clone ());

* data + = 1 ;
tx.send (());
});
}
for _ in 0 .. 10 {
rx.recv ();
}
}
We use the mpsc :: channel () method to build a new channel. We send (via send
) a single () through the channel, and then wait for the return of ten of them.
While this channel is only sending a generic signal, we can send any data that
is Send through the channel!
use std :: thread;
use std :: sync :: mpsc;
fn main () {
let (tx, rx) = mpsc :: channel ();
for _ in 0 .. 10 {
let tx = tx.clone ();

let answer = 42u32 ;
tx.send (response);
});
}
rx.recv (). ok (). expect ( "The response could not be received" );

}
A u32 is Send because we can make a copy of it. So we create a thread, and
ask it to calculate the response, it then sends the response back to us (using
send () ) through the channel.
Panics
A panic! will cause an abrupt termination of the current thread. You can use
Rust threads as a simple isolation mechanism:
use std :: thread;
let result = thread :: spawn (move || {

panic! ( "ups!" );
}). join ();
assert! (result.is_err ());

Our Thread returns a Result , which allows us to check if the thread has
panicked or not.
Error Handling
The plans best established by mice and men often go awry. "Tae a Moose",
Robert Burns
Sometimes things just go wrong. It is important to have a plan for when the
inevitable happens. Rust has rich support for handling errors that could (let's
be honest: will occur) occur in your programs.
There are two types of errors that can occur in your programs: failure and
panic. We will talk about the differences between the two, and then we will
discuss how to handle each one. Then we will discuss how to promote panic
flaws.
Fail vs. Panic

Rust uses two terms to differentiate between the two forms of error: failure,
and panic. A failure is an error from which we can somehow recover. A
panic is an unrecoverable mistake.
What do we mean by "recover"? Well, in most cases, the possibility of an
error is expected. For example, consider the parse function :
"5" .parse ();
This method converts a character string to another type. But because it is a
character string, you cannot be sure that the conversion will actually be
successful. For example, what should this be converted to ?:
"hello5world" .parse ();
The above does not work. We know that the parse () method will only be
successful for some entries. It is expected behavior. This is why we call this
error a failure .
On the other hand, sometimes there are errors that are unexpected, or from
which we cannot recover. A classic example is an assert! :
# let x = 5 ;
assert! (x == 5 );
We use assert! to declare that something is true (true). If the statement is not
true, then something is very wrong. Bad enough that you cannot continue
running in the current state. Another example is using the unreachable! () Macro
:
use Event :: NewLaunch;
enum Event {
New Launch,
}
fn probability (_: & Event) -> f64 {

// the actual implementation would be more complex, of course
0.95
}
fn descriptive_probability (event: Event) -> & 'static str {

match probability (& event) {
1.00 => "true",
0.00 => "impossible",
0.00 ... 0.25 => "very unlikely",
0.25 ... 0.50 => "unlikely",
0.50 ... 0.75 => "probable",
0.75 ... 1.00 => "very likely",
}
}
fn main () {
println! ("{}", descriptive_probability (NewLaunch));
}
The above will result in an error:
error: non-exhaustive patterns: `_` not covered [E0004]
While we know we have covered every possible case, Rust may not know.
You don't know what the probability is between 0.0 and 1.0. That is why we
add another case:
use Event :: NewLaunch;
enum Event {
New Launch,
}
fn probability (_: & Event) -> f64 {

// the actual implementation would be more complex, of course
0.95
}
fn probabilidad_descriptiva (event: Event) -> & 'static str {

match probability (& event) {
1.00 => "true" ,
0.00 => "impossible" ,
0.00 ... 0.25 => "very unlikely" ,
0.25 ... 0.50 => "unlikely" ,
0.50 ... 0.75 => "probable" ,
0.75 ... 1.00 => "very likely" ,
_ => unreachable! ()
}
}
fn main () {
println! ( "{}" , descriptive_probability (NewLaunch));
}
We should never reach case _ , because of this we use the macro to indicate
it. unreachable! () produces a different type of error than Result . Rust calls those
kinds of mistakes panic .
Handling errors with Option and Result

The simplest way to indicate that a function may fail is using the Option <T>
type . For example, the find method on strings tries to locate a pattern in the
string, it returns an Option :
let s = "foo" ;
assert_eq! (s.find ( 'f' ), Some ( 0 ));

assert_eq! (s.find ( 'z' ), None );
This is appropriate for simple cases, but does not give us much information in
the event of a failure. What if we wanted to know why the function failed?
For this, we can use the type Result <T, E> . What it looks like:
enum Result <T, E> {
Ok (T),
Err (E)
}
This enum is provided by Rust, that's why you don't need to define it if you
want to use it. The Ok (T) variant represents success, and the Err (E) variant
represents a failure. Returning a Result instead of an Option is recommended
for most non-trivial cases:
Here is an example of using Result :
# [derive (Debug)]
enum Version {Version1, Version2}
# [derive (Debug)]
enum ErrorParseo {InvalidHeadLength, Invalid Version}
fn parsear_version (header: & [ u8 ]) -> Result <Version, ErrorParseo> {

if header.len () < 1 {
return Err (ErrorParseo :: InvalidHeadLength);
}
header match [ 0 ] {
1 => Ok (Version :: Version1),
2 => Ok (Version :: Version2),
_ => Err (ErrorParseo :: InvalidHeadLength)
}
}
fn main () {
let version = parsear_version (& [ 1 , 2 , 3 , 4 ]);
match version {
Ok (v) => {
println! ( "working with version: {:?}" , v);
}
Err (e) => {
println! ( "head parsing error: {:?}" , e);
}
}
}
This function makes use of an enum, ErrorParseo , to list the errors that can
occur.
The Debug trait is the one that allows us to print the enum value using the {:?}
Format operation .
Unrecoverable errors with panic!

In the event of an unexpected error from which it cannot be recovered, the
macro panic! It is used to induce panic. Such a panic will abruptly end the
current thread of execution providing an error message:
panic! ("boom");
It results in
thread '' panicked at 'boom', hello.rs:2
when you run it.
Because these situations are relatively rare, use panics sparingly.
Promoting panic failures
In certain circumstances, even knowing that a function may fail, we may
want to treat the failure as a panic. For example, io :: stdin (). Read_line (& mut
buffer) returns a Result <usize> , when there is an error reading the line. This
allows us to manage and possibly recover in case of error.
If we don't want to handle the error, and instead just abort the program, we
can use the unwrap () method :
io :: stdin (). read_line (& mut buffer) .unwrap ();
unwrap ()will panic ( panic! ) if the Result is Err . This basically says "Give me
the value, and if something goes wrong, just abort the execution." This is less
reliable than matching the error and trying to recover, but at the same time it
is significantly shorter. Sometimes abrupt termination is appropriate.
There is a way to do the above that is a little better than unwrap () :
let mut buffer = String :: new ();

let read_bytes = io :: stdin (). read_line (& mut buffer)
.okay()
ok ()converts the Result to an Option , and expect () does the same as unwrap () ,
but receives a message as an argument. This message is passed to the panic!
underlying, providing a better error message.
Using try!
When we write code that calls many functions that return the Result type ,
error handling can be tedious. The try macro ! It hides some of the repetitive
code for error propagation in the call stack.
try! replaces:
use std :: fs :: File;

use std :: io;
use std :: io :: prelude :: *;
struct info {
name: String ,
age: i32 ,
grade: i32 ,
}
fn escribir_info (info: & Info) -> io :: Result <()> {

let mut file = File :: create ( "my_best_friends.txt" ) .unwrap ();
if let Err (e) = writeln! (& mut file, "name: {}" , info.name) {
return Err (e)
}
if let Err (e) = writeln! (& mut file, "age: {}" , info.edad) {
return Err (e)
}
if let Err (e) = writeln! (& mut file, "grade: {}" , info.rgrado) {
return Err (e)
}
return Ok (());
}
With:
use std :: fs :: File;
use std :: io;
use std :: io :: prelude :: *;
struct info {
name: String ,
age: i32 ,
grade: i32 ,
}
fn escribir_info (info: & Info) -> io :: Result <()> {

let mut file = File :: create ( "my_best_friends.txt" ) .unwrap ();
try! ( writeln! (& mut file, "name: {}" , info.name));

try! ( writeln! (& mut file, "age: {}" , info.edad));
try! ( writeln! (& mut file, "grade: {}" , info.grad));
return Ok (());
}
Wrap an expression with try! will result in the successful unwrapped ( Ok )

value , unless the result is Err , in which case Err is returned early by the
function that wraps the try.
It is important to mention the fact that you can only use try! from a function
that returns a Result , which means that you can't use try! inside main () ,
because main () doesn't return anything.
Foreign / External Function Interface
Introduction
This guide will use the snappy compression / decompression library as an
introduction to writing bindings to external code. Rust currently cannot call
code in a C ++ library directly, but snappy includes a C interface
(documented in snappy-ch ).
The following is a handy example of how to call a foreign function that will
compile assuming snappy is installed:
# #! [feature (libc)]
extern crate libc;
use libc :: size_t;
# [link (name = "snappy")]

external
fn snappy_max_compressed_length (source_length: size_t) -> size_t;
}
fn main () {
let x = unsafe {snappy_max_compressed_length (100)};
println! ("maximum length of a 100 bytes compressed buffer: {}", x);
}
The extern block is a list of function signatures in a foreign library, in this
case with the platform's C application binary interface (ABI). The # [link (...)]
attribute is used to instruct the linker to link to the snappy library so that
symbols can be resolved.
It is assumed that the interfaces to foreign functions are insecure, that is why
the calls to them must be inside an unsafe {} block as a promise to the
compiler that everything contained in it is really safe. Libraries in C
sometimes expose interfaces that are not thread-safe, and almost any function
that takes a pointer as an argument is not valid for all possible inputs because
the pointer could be a hanging pointer, and flat pointers are left behind.
outside of Rust's secure memory model.
When declaring the argument types of a foreign function, the Rust compiler
cannot check whether the declaration is correct, so specifying it correctly is
part of maintaining the correct binding at runtime.
The extern block can be extended to cover the full snappy API:
extern crate libc;
use libc :: {c_int, size_t};
# [link (name = "snappy")]

external
fn snappy_compress (input: * const u8,
input_length: size_t,
compressed: * mut u8,
compressed_length: * mut size_t) -> c_int;
fn snappy_uncompress (compressed: * const u8,
compressed_length: size_t,
uncompressed: * mut u8,
uncompressed_length: * mut size_t) -> c_int;
fn snappy_max_compressed_length (source_length: size_t) -> size_t;
fn snappy_uncompressed_length (compressed: * const u8,
compressed_length: size_t,
result: * mut size_t) -> c_int;
fn snappy_validate_compressed_buffer (compressed: * const u8,
compressed_length: size_t) -> c_int;
}
# fn main () {}
Creating a secure interface

The flat C interface needs to be wrapped in order to provide memory
management security as well as the use of high level concepts such as
vectors. A library can choose between exposing the high-level secure
interface and hiding insecure internal details.
Wrapping the functions waiting for buffers involves using the slice :: raw
module to manipulate Rust vectors as memory pointers. Rust vectors are
guaranteed to be a contiguous memory block. Length is the number of
elements currently contained, and capacity is the total size of allocated
memory. The length is less than or equal to the capacity.
# extern crate libc;
# use libc :: {c_int, size_t};
# unsafe fn snappy_validate_compressed_buffer (_: * const u8 , _: size_t)
-> c_int { 0 }
# fn main () {}
pub fn validate_buffer_compressed (src: & [ u8 ]) -> bool {
unsafe {
snappy_validate_compressed_buffer (src.as_ptr (), src.len () as
size_t) == 0
}
}
The compressed_buffer_buffer wrapper function makes use of an unsafe block , but
makes sure that calling it is safe for all inputs by excluding the unsafe from
the function signature.
The snappy_compress and snappy_uncompress functions are more complex, because
a buffer has to be assigned to maintain the output.
The snappy_max_compressed_length function can be used to assign a vector with
the maximum capacity required to store the compressed output. The vector
can then be passed to the snappy_compress function as an output parameter. An
output parameter is also passed to get the actual length after compression to
assign the length.
# use libc :: {size_t, c_int};
# unsafe fn snappy_compress (a: * const u8 , b: size_t, c: * mut u8 ,
# d: * mut size_t) -> c_int { 0 }
# unsafe fn snappy_max_compressed_length (a: size_t) -> size_t {a}
# fn main () {}
pub fn compress (orig: & [ u8 ]) -> Vec < u8 > {
unsafe {
let long_orig = orig.len () as size_t;
let porig = orig.as_ptr ();
let mut long_dest = snappy_max_compressed_length (long_orig);

let mut dest = Vec :: with_capacity (long_dest as usize);
let pdest = dest.as_mut_ptr ();
snappy_compress (porig, long_orig, pdest, & mut long_dest);

dest.set_len (long_dest as usize);
dest
}
}
The decompression is similar, because snappy stores the decompressed
length as part of the compression format and snappy_uncompressed_length will get
the exact size of the required buffer.
# use libc :: {size_t, c_int};
# unsafe fn snappy_uncompress (compressed: * const u8 ,
# compressed_length: size_t,
# uncompressed: * mut u8 ,
# uncompressed_length: * mut size_t) -> c_int { 0 }
# unsafe fn snappy_uncompressed_length (compressed: * const u8 ,
# compressed_length: size_t,
# result: * mut size_t) -> c_int { 0 }
# fn main () {}
pub fn unzip (orig: & [ u8 ]) -> Option < Vec < u8 >> {
unsafe {
let long_orig = orig.len () as size_t;
let porig = orig.as_ptr ();
let mut long_dest: size_t = 0 ;

snappy_uncompressed_length (porig, long_orig, & mut
long_dest);
let mut dest = Vec :: with_capacity (long_dest as usize);

let pdest = dest.as_mut_ptr ();
if snappy_uncompress (porig, long_orig, pdest, & mut long_dest)

== 0 {
dest.set_len (long_dest as usize);
Some (dest)
} else {
None // SNAPPY_INVALID_INPUT
}
}
}
Destroyers
External libraries usually transfer the membership of the resources to the
calling code. When this occurs, we must use the Rust destroyers to provide
security and the guarantee of the release of those resources (especially in the
case of a panic).
Callbacks from C code to Rust functions

Some external libraries require the use of callbacks to report back their status
or partial data to the caller. Functions defined in Rust can be passed to an
external library. The requirement for this is that the callback function is
marked as external and with the correct calling convention to make it possible
to call from C code.
The callback function can then be sent through a register call to the library in
C and its subsequent invocation from there.
A basic example is:
Rust code:
extern fn callback (a: i32) {
println! ("I have been called from C with the value {0}", a);
}
# [link (name = "extlib")]

external
fn register_callback (cb: extern fn (i32)) -> i32;
fn shoot_callback ();
}
fn main () {
unsafe {
register_callback (callback);
shoot_callback (); // Trigger the callback
}
}
Code C:
typedef void (* callback_rust) (int32_t) ;
callback_rust cb;
int32_t register_callback (callback_rust callback) {

cb = callback;
return 1 ;
}
void shoot_callback () {
cb ( 7 ); // Call callback (7) in Rust
}
In this example Rust's main () will call trigger_callback () in C, which in turn will
callbackback () in Rust.
Aiming callbacks at Rust objects

The example above demonstrated how a global function can be called from C
code. If I clutch sometimes I want the callback to point to a special Rust
object. This could be the object that represents the wrapper for the respective
object in C.
All of this can be accomplished by passing a flat pointer to the C library. The
C library can then include the pointer to the Rust object in the notification.
This will allow the callback to insecurely access the referenced Rust object.
Rust code:
# [repr (C)]
struct RustObject {
a: i32,
// other members
}
extern "C" fn callback (target: mut ObjectRust, to: i32) {

println! ("I have been called from C with the value {0}", a);
unsafe {
// Update the value in RustObject with the value received from the
callback
(* target) .a = a;
}
}
# [link (name = "extlib")]

external
fn register_callback (target: mut ObjectRust,
cb: extern fn (* mut ObjectRust, i32)) -> i32;
fn shoot_callback ();
}
fn main () {
// Creating the object that will be referenced in the callback
let mut object_rust = Box :: new (ObjectRust {a: 5});
unsafe {
register_callback (& mut * object_rust, callback);
shoot_callback ();
}
}
Code C:
typedef void (* callback_rust) ( void *, int32_t) ;
void * target_cb;
callback_rust cb;
int32_t register_callback ( void * callback_target, callback_rust

callback) {
cb_target = callback_target;
cb = callback;
return 1 ;
}
void shoot_callback () {
cb (cb_target, 7 ); // I will call callback (& RustObject, 7) in Rust
}
Asynchronous callbacks
In the examples above, callbacks are invoked as a direct reaction to a function
call to the external library in C. Control over the current thread is changed
from Rust to C for callback execution, but in the end the callback is executed
in the same thread that called the function that triggered the callback.
Things get more complicated when the external library creates its own
threads and invokes callbacks from them. In these cases access to Rust data
structures within callbacks is especially insecure and appropriate
synchronization mechanisms must be used. In addition to classic
synchronization mechanisms such as mutexes, one possibility in Rust is the
use of channels (in std :: sync :: mpsc ) to transfer data from the C thread that
invokes the callback to a Rust thread.
If an asynchronous callback targets a special object in the Rust address space
it is also absolutely necessary that no other callbacks be executed by the C
library after the respective Rust object has been destroyed. This can be done
by de-registering the callback in the object's destructor and designing the
library in a way that guarantees that no callback will be executed after the de-
registration.
Link
The link attribute in extern blocks provides the basic building block to instruct
rustc how to link to native libraries. Today there are two forms of the link
attribute:
# [link (name = "foo")]
# [link (name = "foo", kind = "bar")]
In both cases, foo is the name of the native library that we are linking to, and
in the second case, bar is the type of native library that the compiler is linking
to. There are currently three types of known native libraries:
Dynamics - # [link (name = "readline")]
Statics - # [link (name = "my_build_dependency", kind = "static")]
Frameworks - # [link (name = "CoreFoundation", kind = "framework")]
Note that frameworks are only available on OSX targets.

The different kind values are intended to differentiate how the native library
participates in the link. From the binding perspective, the Rust compiler
creates two types of artifacts: partial (rlib / staticlib) and final (dylib / binary).
Dependencies on native libraries and frameworks are propagated to the final
artifact boundary, while static dependencies are not propagated at all, because
static libraries are integrated directly into the subsequent artifact.
A few examples of how this model can be used are:
A native build dependency: Sometimes some C / C ++ glue is required when writing a
specific type of Rust code, but distributing the code in a library format is just a burden. In
this case, the code will be archived in a libfoo.a and then the crate rust will declare a
dependency via # [link (name = "foo", kind = "static")] .
Regardless of the type of output for the crate, the static native library will be
included in the output, meaning that distribution of the native static library is
not necessary.
A normal dynamic dependency: Common system libraries (such as readline ) are
available on a large number of systems, and often a static copy of those libraries may not
exist. When this dependency is included in a Rust crate, partial targets (like rlibs) will not
link to the library, but when the rlib is included in a final target (like a binary), the library
will be linked.
In OSX, frameworks behave with the same semantics as a dynamic library.
Unsafe blocks
Some operations, such as referencing flat pointers or calls to functions that
have been marked as unsafe are only allowed within unsafe blocks. The
unsafe blocks isolate the insecurity and are a promise to the compiler that the
insecurity will not leak out of the block.
Unsafe functions, on the other hand, advertise insecurity to the outside world.
An insecure function is written as follows:
unsafe fn kaboom (ptr: * const i32 ) -> i32 {*} ptr
This function can be invoked only from an unsafe block or another unsafe
function .
Accessing external globals
Foreign APIs sometimes export a global variable that could do something
like keep track of some global state. In order to access these variables, you
must declare them in external blocks with the static keyword :
extern crate libc;
# [link (name = "readline")]

external
static rl_readline_version: libc :: c_int;
}
fn main () {
println! ("You have version {} of readline.",
rl_readline_version as i32);
}
Alternatively, you may need to alter the global state provided by a foreign
interface. To do this, statics can be declared with mut in order to mutate
them.
extern crate libc;
use std :: ffi :: CString;

use std :: ptr;
# [link (name = "readline")]

external
static mut rl_prompt: * const libc :: c_char;
}
fn main () {
let prompt = CString :: new ("[my-awesome-shell] $"). unwrap ();
unsafe {
rl_prompt = prompt.as_ptr ();
println! ("{:?}", rl_prompt);
rl_prompt = ptr :: null ();

}
}
Note that all interaction with a static mut is insecure, both read and write.
Dealing with a mutable global state requires great care.
Foreign calling conventions
Most foreign code exposes an ABI C, and Rust defaults to the platform
calling convention when calling external functions. Some foreign functions,
notably the Windows API, use another calling convention. Rust provides a
way to inform the compiler about which convention should be used:
extern crate libc;
# [cfg (all (target_os = "win32", target_arch = "x86"))]

# [link (name = "kernel32")]
# [allow (non_snake_case)]
extern "stdcall" {
fn SetEnvironmentVariableA (n: * const u8 , v: * const u8 ) -> libc ::
c_int;
}
# fn main () {}
This applies to the entire extern block . The list of supported ABI constraints
are:
stdcall
aapcs
cdecl
fastcall
Rust
rust-intrinsic
system
C
win64
Most abys are self-explanatory, but the abi system may seem a little weird.
This constraint selects whatever the appropriate ABI is to interoperate with
the target libraries. For example, in win32 with an x86 architecture, it means
that the abi used will be stdcall . In x86_64, however, Windows uses the
convention called C , then used C . This translates to that in our previous
example, we could have used extern "system" {...} to define a block for all
Windows systems, not just x86.
Interoperability with external code
Rust ensures that the distribution of a struct is compatible with the
representation of the platform in C only if the attribute # [repr (C)] is applied. #
[repr (C, packed)] can be used to distribute members without padding. # [repr (C)]
can also be applied to an enum.
Rust boxes ( Box <T> ) use non-nullable pointers as handles that point to the
contained object. However, they should not be created manually because they
are handled by internal dispatchers. References can be safely assumed as
direct non-nullable pointers to the type. However, breaking the borrowing
check or the mutability rules is not guaranteed to be safe, which is why the
use of flat pointers ( * ) is preferred if necessary because the compiler cannot
assume many things about from them.
Vectors and character strings share the same in-memory layout, and utilities
for interacting with C APIs are available in the vec and str modules .
However, character strings are not terminated at \ 0 . If you need a character
string ending in NUL to interact with C, then you must make use of the
CString type in the std :: ffi module .
The standard library includes type aliases and function definitions for the C
standard library in the libc module , and Rust defaults to libc and libm .
The "Null Pointer Optimization"
Certain types are defined not to be null . This includes references ( & T , &
mut T ), boxes ( Box <T> ), and function pointers ( extern "abi" fn () ). When you
interface with C, pointers that can be null are sometimes used. As a special
case, a generic enum containing exactly two variants, of which one does not
contain data and the other contains a single field, is eligible for "null pointer
optimization". When said enum is instantiated with one of the non-nullable
types, it is represented as a single pointer, and the variant without data is
represented as the null pointer. So Option <extern "C" fn (c_int) -> c_int> is how one
represents a nullable function pointer using ABI of C.
Calling coding Rust from C
You may want to compile Rust code so that it can be called from C. This is
easy, but it requires certain things:
# [no_mangle]
pub extern fn hello_rust () -> * const u8 {
"Hello world! \ 0" .as_ptr ()
}
# fn main () {}
The extern makes this function adhere to the C calling convention, as
discussed in " Foreign calling conventions ". The no_mangle attribute disables
Rust's name mangling, making it easier to bind.
FFI and panics
It is important to be aware of panic! os when working with FFI. A panic! at the
limit of FFI is undefined behavior. If you are writing code that can panic, you
must run it in another thread, so the panic will not spread to C:
use std :: thread;
# [no_mangle]
pub extern fn oh_no () -> i32 {
let h = thread :: spawn (|| {
panic! ( "Oops!" );
});
match h.join () {
Ok (_) => 1 ,
Err (_) => 0 ,
}
}
# fn main () {}
Borrow and AsRef

Lost traits Borrow and AsRef are very similar, but different. Here is a brief
overview of what these traits mean:
Borrow
The Borrow trait is used when we are writing a data structure, and we want to
use a owned type or a borrowed type as a synonym for some reason.
For example, HashMap has a get method that uses Borrow :
fn get (& self, k: & Q) -> Option <& V>
where K: Borrow,
Q: Hash + Eq
This signature is complicated. Parameter K is what we are interested in now.
It refers to a parameter of the HashMap itself:
struct HashMap {
Parameter K is the type of the key that the HashMap uses . When looking at
the get () signature again , we can only use get () when the key implements
Borrow <Q> . In this way, we can create a HashMap that uses String keys but
when searching for use & str s:
use std :: collections :: HashMap;
let mut map = HashMap :: new ();

map.insert ( "Foo" .to_string (), 42 );
assert_eq! (map.get ( "Foo" ), Some (& 42 ));
This is because the standard library has a Borrow <str> for String impl .
For most types, when you want to take a type either owned or borrowed, an
& T is enough. But one area in which Borrow is effective is when there is
more than one type of borrowed security. This is especially true of references
and slices: you can both have a & T one & mut T . If we want to accept both
types, Borrow is what we need:
use std :: borrow :: Borrow;

use std :: fmt :: Display;
fn foo <T: Borrow < i32 > + Display> (a: T) {

println! ( "a is a borrowed: {}" , a);
}
let mut i = 5 ;
foo (& i);

foo (& mut i);
This will print out a is a borrowed: 5 twice.
AsRef
The AsRef trait is a conversion trait. It is used to convert some value to a
reference in generic code. Like this:
let s = "Hello" .to_string ();
fn foo <T: AsRef < str >> (s: T) {

let slice = s.as_ref ();
}
Which one should you use?

We can see how they are both kind of the same: they both deal with owned
and borrowed versions of some sort. However, they are different.
Choose Borrow when you want to abstract over different types of borrowing,
or when you are building a data structure that treats owned and borrowed
values in equivalent ways, such as hashing and comparison.
Use AsRef when you want to convert something directly into a reference, and
you're writing generic code.
Distribution channels
The Rust project uses a concept called 'distribution channels' to manage
releases.
It is important to understand this process so that you can decide which
version of Rust your project should use.
Overview
There are three channels for Rust releases:
Nocturnal (nightly)
Beta
Stable
Nightly releases are created once a day. Every six weeks, the latest nightly
release is promoted to 'Beta'. At this point, you will only receive patches that
fix serious bugs. Six weeks later the beta is promoted to 'Stable', and it
becomes the new 1.x release .
This process occurs in parallel. Every six weeks, on the same day the nocturn
goes up to beta, the beta is promoted to stable. When 1.x is released, at the
same time 1. (x + 1) -beta is released, and the night becomes the first version of
1. (x + 2) -nightly .
Choosing a version
Generally speaking, unless you have a specific reason, you should use the
stable distribution channel. Those releases are intended for a general
audience.
However, depending on your interest in Rust, you could choose the night.
The balance is as follows: on the night channel, you can make use of new
Rust features. However, unstable features are subject to change, which is why
any nightclub has the ability to break your code. If you use the stable release,
you don't have access to experimental features, but the next release of Rust
won't cause significant problems because of changes.
Helping the ecosystem through CI

What about beta? We recommend that all Rust users using the stable
distribution channel also test their beta channel continuous integration
systems. This will help warn the team in the event of an accidental
regression.
Additionally, testing against nightly can detect regressions much earlier,
which is why if you do not mind having a third build, we appreciate that you
test against all channels.
Chapter IV
Syntax and Semantics
This section breaks Rust into small pieces, one for each concept.
If you want to learn Rust from the bottom up, reading this section in order is
a very good way to do it.
These sections form a reference for each concept, if you are reading another
tutorial and you find something confusing, you can find it explained
somewhere in this section.
Variable Links
Virtually any non-'Hello World 'program uses variable links . These links to
variables look like this:
fn main () {
let x = 5 ;
}
Placing fn main () { in each example is a bit tedious, so in the future we will
skip it. If you are following step by step, be sure to edit your main () function ,
instead of leaving it out. Otherwise you will get an error.
In many languages, this is called a variable , but Rust's variable bindings
have a few tricks up their sleeve. For example the left side of a let expression
is a ' pattern ', not a simple variable name. This means that we can do things
like:
let (x, y) = ( 1 , 2 );
After this expression is evaluated, x will be one, and y will be two. The
patterns are really powerful, and they have their own section in the book. We
don't need those facilities for now, let's just keep this in our minds as we go.
Rust is a statically typed language, which means that we specify our types in
advance, and these are checked at compile time. So why does our first
example compile? Well, Rust has this thing called 'type inference'. If you can
determine the type of something, Rust doesn't require you to type the type.
We can add the type if we want. The types come after a colon ( :) :
let x: i32 = 5 ;
If I asked the rest of the class to read this out loud, you would say " x is a
link to type i32 and the value five ."
In this case we decided to represent x as a 32-bit signed integer. Rust has
many different types of primitive integers. These start with i for signed
integers and u for unsigned integers. The possible sizes for integers are 8, 16,
32, and 64 bits.
In future examples, we could annotate the type in a comment. The example
would look like this:
fn main () {
let x = 5 ; // x: i32
}
Notice the similarities between the annotation and the syntax you use with let
. Including this kind of comment is not idiomatic in Rust, but we will include
it occasionally to help you understand what types Rust infers.
By default, links are immutable . This code will not compile:
let x = 5;
x = 10;
It will result in the following error:
error: re-assignment of immutable variable `x`
x = 10;
^ ~~~~~~
If you want a variable link to be mutable, you can use mut :
let mut x = 5 ; // mut x: i32
x = 10 ;
There is no single reason why variable bindings are immutable by default, but
we can think about it through one of Rust's main focuses: security. If you
forget to say mut . the compiler will notice this, and let you know that you
have mutated something you had no intention of mutating. If the links to
variables were mutable by default, the compiler would not be able to tell you
this. If you had the intention to mutate something, then the solution is very
easy: add mut .
There are other good reasons to avoid mutable state whenever possible, but
they are outside the scope of this guide. In general, you can often avoid
explicit mutation, and this is preferable in Rust. That said, sometimes,
mutation is just what you need, which is why it is not prohibited.
Let's go back to links to variables. Variable links in Rust have one more
aspect that differs from other languages: initialization to a value is required
before you can use them.
Let's put this to the test. Change your src / main.rs file so it looks like this:
fn main () {
let x: i32 ;

}
You can use cargo build on the command line to compile it. You will get a
warning but it will still print "Hello world!":
Compiling hello_world v0.0.1 (file: /// home / you / projects /
hello_world)
src / main.rs: 2: 9: 2:10 warning: unused variable: `x`, # [warn
(unused_variable)]
on by default
src / main.rs: 2 let x: i32;
^
Rust warns us that we never make use of the variable link, but because we
never use it, there is no danger, no fault. However, things change if we
actually try to use x . Let's do that. Change your program to look like this:
fn main () {
let x: i32;
println! ("The value of x is: {}", x);

}
Try to compile it. You will get an error:
$ build charge
Compiling hello_world v0. 0.1 (file: /// home / you / projects /
hello_world)
src / main.rs: 4 : 39 : 4 : 40 error: use of possibly uninitialized variable:
`x`
src / main.rs: 4 println! ( "The value of x is: {}" , x);
^
note: in expansion of format_args!
<std macros>: 2 : 23 : 2 : 77 note: expansion site
<std macros>: 1 : 1 : 3 : 2 note: in expansion of println!
src / main.rs: 4 : 5 : 4 : 42 note: expansion site
error: aborting due to previous error
Could not compile `hello_world`.
Rust will not allow you to use a value that has not been previously initialized.
Let's talk about what we've added to println below! .
If you include a key pair ( {} , some people call them mustaches / mustaches
...) in the string to print, Rust will interpret it as a request to interpolate some
kind of value. String interpolation is a term in computer science that means
"put this inside the string." We add a comma, and then x , to indicate that we
want this to be the interpolated value. The comma is used to separate the
arguments that we pass to the functions and the macros, in the case of passing
more than one.
When you use the curly braces, Rust will try to display the value in a way
that makes sense after checking its type. If we want to specify a more detailed
format, there are a wide number of options available . For now, we will stick
to the default behavior: integers are not very difficult to print.
Features
Every Rust program has at least one function, the main function :
fn main () {
}
This is the simplest possible function declaration. As we mentioned earlier,
fn says 'this is a function', followed by the name, parentheses because this
function does not receive any arguments, and then braces to indicate the body
of the function. Here's a function called foo :
fn foo () {
}
So what about receiving arguments? Here is a function that prints a number:
fn print_number (x: i32 ) {
println! ( "x is: {}" , x);
}
Here is a complete program that makes use of print_number :
fn main () {
print_number ( 5 );
}
fn print_number (x: i32 ) {

println! ( "x is: {}" , x);
}
As you will see, function arguments work very similarly to let statements :
you add a type to the argument name, after a colon.
Here is a complete program that adds two numbers and then prints them:
fn main () {
print_sum ( 5 , 6 );
}
fn print_sum (x: i32 , y: i32 ) {

println! ( "the sum is: {}" , x + y);
}
The arguments are separated by a comma, in both cases, when you call the
function as well as when you declare it.
Unlike let , you must declare the types of the arguments. The following will
not compile:
fn print_sum (x, y) {
println! ("sum is: {}", x + y);
}
You would get the following error:
expected one of `!`, `:`, or `@`, found `)`
fn print_sum (x, y) {
This is a deliberate design decision. Although full program inference is
possible, languages that own it, like Haskell, often suggest that documenting
your types explicitly is good practice. We agree that forcing functions to
declare types while allowing inference within the function is a wonderful
compromise between complete inference and the absence of inference.
What about returning a value? Here is a function that adds one to an integer:
fn sum_one (x: i32 ) -> i32 {
x+1
}
The functions in Rust return exactly one value, and the type is declared after
an 'arrow', which is a hyphen ( - ) followed by a greater-than sign ( > ). The
last line of a function determines what it returns. You will notice the absence
of a semicolon here. Add it:
fn sum_one (x: i32) -> i32 {
x + 1;
}
We would get an error:
error: not all control paths return a value
fn sum_one (x: i32) -> i32 {
x + 1;
}
help: consider removing this semicolon:

x + 1;
^
The above reveals two interesting things about Rust: it is an expression-based
language, and the semicolons are different from other languages based on
'braces and semicolons'. These two things are related.
Expressions vs. Sentences

Rust in a language primarily based on expressions. There are only two types
of statements, everything else is an expression.
So what is the difference? Expressions return a value, and statements do not.
This is why we end up with the error 'not all control paths return a value'
here: the statement x + 1; does not return a value. There are two types of
statements in Rust: 'statement statements' and 'expression statements'.
Everything else is an expression. Let's talk about declaration statements first.
In some languages, variable links can be written as expressions, not just
statements. As in Ruby:
x=y=5
In Rust, however, using let to enter a variable link is not an expression. The
following will produce a compile-time error:
let x = (let y = 5); // expected identifier, found keyword `let`
The compiler tells us that it was waiting for the start of an expression, and a
letcan be just a statement, not an expression.
Note that assigning a variable that has been previously assigned (eg y = 5 ) is
an expression, yet its value is not particularly useful. Unlike other languages
in which an assignment is evaluated to the assigned value (ex 5 in the
previous example), in Rust the value of an assignment is an empty tuple ()
because the assigned value can have a single owner and any Another return
value would be surprising:
let mut y = 5 ;
let x = (y = 6 ); // x has the value `()`, not `6`

The second type of statement in Rust is the expression statement . Its purpose
is to convert any expression into a sentence. In practical terms, Rust's
grammar expects a sentence to be followed by more sentences. This means
that you can use semicolons to separate one expression from another. This
causes Rust to look very similar to those languages in which a semicolon is
required at the end of each line, in fact, you will see semicolons at the end of
almost every Rust line you will see.
So what is the exception that makes us say "almost"? You've already seen it
in the code above:
fn sum_one (x: i32 ) -> i32 {
x+1
}
Our function claims to return an i32 , but with a semicolon, it would return ()
. Rust determines that this is probably not what we want, and suggests
removing the semicolon in the error we saw earlier.
Early returns
But what about early returns? Rust provides a reserved word for it, return :
fn foo (x: i32 ) -> i32 {
return x;
// we will never reach this code!

x+1
}
Using a return as the last line of a function is valid, but it is considered poor
style:
fn foo (x: i32 ) -> i32 {
return x + 1 ;
}
The previous definition without the return may look a bit strange if you've
never worked with an expression-based language, but this one becomes
intuitive over time.
Divergent functions
Rust has a special syntax for 'divergent functions', which are non-returning
functions:
fn diverges () ->! {
panic! ( "This function never returns!" );
}
panic! it is a macro, similar to println! () that we have already seen. Unlike
println! () , Panic! () Causes the current thread to end abruptly displaying the
provided message.
Because this function will cause an abrupt exit, it will never return, that is
why it has the type ' ! ', which reads' diverges'. A divergent function can be
used as any type:
# fn diverges () ->! {
# panic! ("This function never returns!");
#}
let x: i32 = diverge ();
let x: String = diverge ();
Function pointers
We can also create links to variables that point to functions:
let f: fn ( i32 ) -> i32 ;
f is a binding to variable that points to a function that takes an i32 as its
argument and returns an i32 . For example:
fn mas_uno (i: i32 ) -> i32 {
i+1
}
// no type inference
let f: fn ( i32 ) -> i32 = mas_uno;
// type inference
let f = more_one;
We can then use f to call the function:
# fn mas_uno (i: i32 ) -> i32 {i + 1 }
# let f = more_one;
let six = f ( 5 );
Primitive Types
Rust has a set of types that are considered 'primitive'. This means that they
are integrated into the language. Rust is structured in such a way that the
standard library also provides a number of useful types based on primitives,
but these are the most primitive.
Boolean
Rust has a built-in Boolean type, called bool . It has two possible values true
and false :
let x = true ;
let y: bool = false ;

A common use of booleans is in if conditionals .
You can find more documentation for the bool eanos in the documentation of
the standard library (english).
char
The char type represents a single Unicode scalar value. You can create char s
with single quotes: ( ' )
let x = 'x' ;
let dos_corazones = ' �� ';
Unlike other languages, this means that char in Rust is not a single byte, but
four.
You can find more documentation for the char s in the standard library
documentation .
Numerical types
Rust has a variety of number types in a few categories: signed and unsigned,
fixed and variable, floating point, and integers.
These types consist of two parts: the category, and the size. For example, u16
is an unsigned type with a size of sixteen bits. More bits allow you to store
larger numbers.
If a number literal does not have anything that causes its type to be inferred,
default types are used:
let x = 42 ; // x has type i32
let y = 1.0 ; // and it has type f64

Here is a list of the different numeric types, with links to their documentation
in the standard library (English):
i8
i16
i32
i64
u8
u16
u32
u64
isize
usize
f32
f64
Let's look at each of the different categories.

Signed and unsigned
Integer types come in two varieties: signed and unsigned. To understand the
difference, consider a number that is four bits in size. A four-bit signed
number would allow you to store numbers from -8 to +7 . Signed numbers
use the "two's complement representation". A number of four unsigned bits,
because you don't need to save negative values, can store values from 0 to
+15 .
Unsigned types use a u for their category, and signed types use i . The i is
for integer (integer). So u8 is an eight-bit unsigned number, and an i8 is an
eight-bit signed number .
Fixed size types
Fixed-size types have a specific number of bits in their representation. Valid
sizes are 8 , 16 , 32 , and 64 . So u32 is a 32-bit unsigned integer, and i64 is
a 64-bit signed integer.
Variable size types
Rust also provides types for which the size depends on the size of the pointer
on the underlying machine. These types have the category 'size', and come in
both signed and unsigned variants. This results in two types isize and usize .
Floating point types
Rust also has two types of floating point: f32 and f64 . These correspond to
the IEEE-754 single and double precision numbers.
Arrangements
Like many programming languages, Rust has list types to represent a
sequence of things. The most basic is the arrangement , a list of elements of
the same type and of fixed size. By default the arrangements are immutable.
let a = [ 1 , 2 , 3 ]; // a: [i32; 3]
let mut m = [ 1 , 2 , 3 ]; // m: [i32; 3]
The arrays have the type [T; N] . We will talk about the T notation in the
generic section . The N is a constant at compile time, for the length of the
arrangement.
There is a shortcut for initializing each of the array elements to the same
value. In this example, each element of a will be initialized to 0 :
let a = [ 0 ; 20 ]; // a: [i32; twenty]
You can get the number of elements of the array a with a.len ()
let a = [ 1 , 2 , 3 ];
println! ( "a has {} elements" , a.len ());

You can access a particular array element with subscript notation :
let names = [ "Graydon" , "Brian" , "Niko" ]; // names: [& str; 3]
println! ( "The second name is: {}" , names [ 1 ]);

Subindices start at zero, as in most programming languages, so the first name
is names [0] and the second name is names [1] . The example above prints: The
middle name is: Brian . If you try to use a subscript that is not in the array, you
will get an error: checking the limits on access to the array is done at runtime.
Wandering access like that is the source of many bugs in system
programming languages.
You can find more documentation for s- arrays in the standard library
documentation .
Slices
A slice is a reference to (or a "view" within) another data structure. Slices are
useful for allowing secure and efficient access to a portion of an array
without involving copying. For example, you might want to refer to a single
line in a file that has been previously read from memory. By nature, a slice is
not created directly, they are created for a variable that already exists. Slices
have a length, can be mutable or immutable, and in many ways behave like
arrays:
let a = [ 0 , 1 , 2 , 3 , 4 ];
let middle = & a [ 1 .. 4 ]; // A slice of a: only elements 1, 2, and 3
let complete = & a [..]; // A slice containing all the elements of a.
Slices have the & [T] type . We will talk about T when we cover generics .
You can find more documentation for slices in the documentation of the
standard library (English)
str
The str of Rust is the most primitive type of string. As a sizeless type , and is
not very useful in itself, but becomes very useful when put behind a
reference, like & str . That is why we will leave it up to here.
You can find more documentation for str in the standard library
documentation (English)
Tuples
A tuple is an ordered list of fixed size. Like this:
let x = ( 1 , "hello" );
The parentheses and commas form this tuple of length two. Here is the same
code but with type annotations:
let x: ( i32 , & str ) = ( 1 , "hello" );
As you can see, the type of a tuple is just like the tuple, but with each position
having the type instead of the value. Careful readers will also notice that
tuples are heterogeneous: we have an i32 ya & str in this tuple. In system
programming languages, character strings are slightly more complex than in
other languages. For now just read & str as a character string slice . We will
learn more shortly.
You can assign one tuple to another, if they have the same contained types
and the same arity . Tuples have the same arity when they are the same size.
let mut x = ( 1 , 2 ); // x: (i32, i32)
let y = ( 2 , 3 ); // y: (i32, i32)
x = y;
You can access the fields of a tuple through an unstructured let . Here is an
example:
let (x, y, z) = ( 1 , 2 , 3 );
println! ( "x is {}" , x);
Remember earlier when I said that the left side of a let statement was more
powerful than simply assigning a binding? Here we are. We can place a
pattern on the left side of a let , and if it matches the right side, we can assign
multiple bindings to a variable at once. In this case, the let "unstructures" or
"part" the tuple, and assigns the parts to the three bindings to variable.
This pattern is very powerful, and we will see it repeated frequently in the
future.
You can remove ambiguity between a single-element tuple and a value
enclosed in parentheses using a comma:
( 0 ,); // single element tuple

( 0 ); // zero enclosed in parentheses
Indexed in tuples
You can also access the fields of a tuple with the indexing syntax:
let tuple = ( 1 , 2 , 3 );
let x = tuple. 0 ;
let y = tuple. 1 ;
let z = tuple. 2 ;
println! ( "x is {}" , x);

Like array indexing, it starts at zero, but unlike array indexing, they are used
. , instead of [] s.
You can find more documentation for tuples in the standard library
documentation (English)
Features
Functions also have a type! They look like this:
fn foo (x: i32 ) -> i32 {x}
let x: fn ( i32 ) -> i32 = foo;

In this case, x is a 'pointer' to a function that receives an i32 and returns an
i32 .
Comments
Now that we've seen some features, it's a good idea to learn about the
comments. Comments are notes you leave to other programmers in order to
explain some aspect of your code. The compiler mostly ignores them.
Rust has two types of comments that should interest you: line comments and
documentation comments
// Line comments are anything after '//' and extend to the end of the line
let x = 5; // this is also a line comment
// If you have a long explanation about something, you can put comments
// line some together. Put a space between your // and your comment with
the
// in order to make them more readable.
The other type of comment is a documentation comment (or doc comment).
The doc comments use /// instead of // , and support Markdown notation
inside:
/// Add one to the number provided
///
/// # Examples
///
///
/// let five = 5; /// /// assert_eq! (6, sum_one (5)); /// # fn sum_one (x: i32) -
> i32 {/// # x + 1 /// #} /// `` `fn sum_one (x: i32) -> i32 {x + 1}
There is another style of comments, `//!`, With the purpose of commenting the container items (eg
crates, modules or functions), instead of the items that follow them. They are commonly used in the
root of a crate (lib.rb) or in the root of a module (mod.rs):
//! # The Rust Standard Library //! //! The Rust Standard Library provides the
functionality //! runtime essential for building software //! Rust portable. `` ''
When writing doc comments, providing some usage examples is very, very
useful. You will notice that we have made use of a macro: assert_eq! . It
compares two values, and panics! or if these are not the same. It is very useful
in documentation. There is also another macro, assert! , which panics! or if the
supplied value is false .
You can use the rustdoc tool to generate HTML documentation from those
comments, as well as run the code in the examples as tests!
if
Rust's approach to if is not particularly complex, but is more similar to the if
you will find in languages with dynamic typing than in traditional system
languages. Let's talk a little about this, to make sure you understand all the
nuances.
if is a specific form of a more general concept, the 'branch'. The name comes
from a branch in a tree: it is a decision point, in which depending on an
option, multiple paths can be taken.
In the case of if , there is a single choice that leads to two paths:
let x = 5;
if x == 5 {
println! ("x is five!");
}
Had the value of x changed to something different, this line would not have
been printed. To be more specific, if the expression after the if is evaluated
to true , then the code block is executed. If false , that block is not invoked.
If you want something to happen in the case of false , you must use an else :
let x = 5;
if x == 5 {
} else {
println! ("x is not five :(");
}
If there is more than one case, use an else if :
let x = 5;
if x == 5 {
} else if x == 6 {
println! ("x is six!");
} else {
println! ("x is neither five nor six :(");
}
This is all very standard. However, you can also do this:
let x = 5;
let y = if x == 5 {
10
} else {
fifteen
}; // y: i32
Which we can (and probably should) write like this:
let x = 5;
let y = if x == 5 {10} else {15}; // y: i32

This works because if is an expression. The value of the expression is the
value of the last expression in the block that has been selected. An if without
an else always results in () as a value.
Cycles
Rust currently provides three approaches to performing iterative activity. loop
, while and for . Each of these approaches has its own uses.
loop
The infinite loop cycle is the simplest cycle available in Rust. Through the
use of the loop keyword , Rust provides a way to iterate indefinitely until
some termination statement is reached. The loop infinite Rust looks like this :
loop {
println! ("Itera forever!");
}
while
Rust also has a while loop . It looks like this:
let mut x = 5 ; // mut x: i32

let mut completed = false ; // mut completed: bool
while ! completed {
x+=x-3;
println! ( "{}" , x);
if x% 5 == 0 {
completed = true ;
}
}
While loops are the right choice when you are not sure how many times you
need to iterate.
If you need an infinite loop, you might be tempted to write something like
this:
while true {
However, loop is by far the best one for this case:
loop {
Rust's control flow analysis treats this construction differently than a while true
, because we know that we will iterate forever. In general, the more
information we provide to the compiler, the compiler could perform better in
relation to security and code generation, that is why you should always prefer
loop when you plan to iterate indefinitely.
for
The for loop is used to iterate a particular number of times. Cycles for Rust,
however, work differently from other programming languages way systems.
The for Rust does not look like this cycle for a "C style"
for (x = 0 ; x < 10 ; x ++) {
printf ( "% d \ n" , x);
}
Instead, Rust's for loop looks like this:
for x in 0 .. 10 {
println! ( "{}" , x); // x: i32
}
In slightly more abstract terms:
for var in expression {
code
}
The expression is an iterator . The iterator returns a series of elements. Each
element is an iteration of the cycle. That value is in turn assigned to the name
var , which is valid in the body of the cycle. Once the cycle has finished, the
next value is obtained from the iterator, and is iterated once more. When
there are no more values, the for loop ends.
In our example, 0..10 is an expression that takes a start position and an end
position, and returns an iterator above those values. The upper limit is
exclusive, so our loop will print from 0 to 9 , not 10 .
Ruth does not possess the C-style for loop , by the way. Manually controlling
each element of the cycle is complicated and error prone, even for
experienced C programmers.
List yourself
When you need to keep track of how many times you've iterated, you can use
the .enumerate () function .
In ranges:
for (i, j) in ( 5 .. 10 ) .enumerate () {
println! ( "i = {} and j = {}" , i, j);
}
Departure:
i = 0 and j = 5
i = 1 and j = 6
i = 2 and j = 7
i = 3 and j = 8
i = 4 and j = 9
Don't forget to put the parentheses around the range.
In iterators:
# let lines = "hello \ nworld" .lines ();
for (line_number, line) in lineas.enumerate () {
println! ( "{}: {}" , line_number, line);
}
Outputs:
0: Contents of line one
1: Contents of line two
2: Contents of line three
3: Contents of line four
Ending the iteration early

Let's take a look at that while loop we saw earlier:
let mut x = 5 ;
let mut completed = false ;
while ! completed {
x+=x-3;
println! ( "{}" , x);
if x% 5 == 0 {
completed = true ;
}
}
We need to maintain a binding variable mut , completed , to know when we
should get out of the cycle. Rust has two keywords to help us modify the
iteration process: break and continue .
In this case, we can write the cycle in a better way with break :
let mut x = 5 ;
loop {
x+=x-3;
println! ( "{}" , x);
if x% 5 == 0 { break ; }
}
We now loop indefinitely and use break to break the loop early. Using an
explicit return also works well for early cycle termination.
continue is similar, but instead of ending the loop, it makes us go to the next
iteration. The following will print the odd numbers:
for x in 0 .. 10 {
if x% 2 == 0 { continue ; }
println! ( "{}" , x);

}
Loop tags
You might also encounter situations where you have nested loops and need to
specify which loop your break or continue statements belong to . As in most
languages, by default a break or continue applies to the innermost loop. In the
event that you want to apply a break or continue to any of the external cycles,
you can use labels to specify to which cycle the break or continue statement
applies . The following will only print when both x and y are odd:
'exterior : for x in 0 .. 10 {
'interior : for and in 0 .. 10 {
if x% 2 == 0 { continue 'exterior ; } // continue the loop above x
if and% 2 == 0 { continue 'inside ; } // continue the loop above and
println! ( "x: {}, y: {}" , x, y);
}
}
Belonging
This guide is one of three introducing the Rust membership system. This is
one of the most unique and irresistible features of Rust, with which Rust
developers should be familiar. It is through membership that Rust achieves
his most important goal, security. There are a few different concepts, each
with its own chapter:
membership, the one you currently read
loan , and its associated characteristic 'references'
life time , an advanced loan concept
These three chapters are related, in order. You will need all three to fully
understand Rust's membership system.
Goal
Before going into detail, two important notes about the membership system.
Rust is focused on safety and speed. Rust achieves these goals through many
'zero cost abstractions', which means that at Rust, abstractions cost as little as
possible to make them work. The membership system is a prime example of a
zero cost abstraction. All the analysis that we will be talking about in this
guide is carried out at compilation time . You do not pay any cost at runtime
for any of these facilities.
However, this system has a certain cost: the learning curve. Many new Rust
users experience something we call 'fighting with the borrow checker', a
situation in which the Rust compiler refuses to compile a program which the
author thinks is valid. This occurs frequently because the programmer's
mental model of how membership works does not conform to the current
rules implemented in Rust. You probably experience similar things in the
beginning. However, there is good news: other experienced Rust developers
report that once they work with membership system rules for a period of
time, they struggle less and less with the loan checker.
With that in mind, let's learn about belonging.
Belonging
The Bindings variable holding property Rust: These 'have membership' what
are associated. This means that when a binding to a variable goes out of
scope, Rust releases the resources associated with it. For example:
fn foo () {
let v = vec! [ 1 , 2 , 3 ];
}
When v comes into scope, a new Vec <T> is created. In this case the vector
also allocates some memory from the mound , for the three elements. When v
goes out of scope at the end of foo () , Rust will clear everything related to the
vector, including the memory allocated from the mound. This occurs
deterministically, at the end of the scope.
Motion semantics
There is something more subtle here, Rust makes sure that there is only
exactly one binding to any particular resource. For example, if we have a
vector, we can assign it to another binding to variable:
let v = vec! [ 1 , 2 , 3 ];
let v2 = v;
But, if we try to use v afterwards, we get an error:
let v = vec! [1, 2, 3];
let v2 = v;
println! ("v [0] is: {}", v [0]);
The error looks like this:
error: use of moved value: `v` (use of moved value:` v`)

println! ("v [0] is: {}", v [0]);
^
Something similar happens if we define a function that takes membership,
and we try to use something after having passed it as an argument:
fn take (v: Vec) {
// what happens here is not relevant
}
let v = vec! [1, 2, 3];
take (v);
println! ("v [0] is: {}", v [0]);

The same error: 'use of moved value'. When we transfer membership into
something, we say that we have 'moved' the thing to which we are referring.
You don't need any special annotation for this, which is what Rust does by
default.
The details
The reason why we can't use a binding to variable after we have moved it is
subtle, but important. When we write code like this:
let v = vec! [ 1 , 2 , 3 ];
let v2 = v;
The first line allocates memory for the vector object, v , and for the data it
contains. The vector object is then stored in the stack stack and contains a
pointer to the content ( [1, 2, 3] ) stored in the mound . When we move v to
v2 , a copy of that pointer is created for v2 . All this means that there would
be two pointers for the vector content in the mound. This violates Rust's
safety guarantees, introducing a race condition. That is why Rust prohibits
the use of v after the movement has been carried out.
Importantly, some optimizations might remove the copy of the bytes on the
stack, depending on certain circumstances. So it may not be as inefficient as
it initially looks.
Copy Types
We have established that when we transfer the membership to another
binding to variable, we cannot use the original binding. However, there is a
trait trait that changes this behavior, it is called Copy . We haven't discussed
traits yet, but for now you can see them as an annotation made to a particular
type that adds extra behavior. For example:
let v = 1 ;
let v2 = v;
println! ( "v is: {}" , v);

In this case, v is an i32 , which implements the Copy trait . This means that,
just as in a move, when we assign v to v2 , a copy of the data is made. But,
unlike what happens in a movement, we can use v afterwards. This is
because an i32 doesn't have data pointers anywhere else, copying it means
full copying.
All primitive types implement the Copy trait and their membership is not
moved as one might assume, following the membership rules . As an example,
the following two pieces of code only compile because the i32 and bool types
implement the Copy trait .
fn main () {
let a = 5 ;
let _y = fold (a);

println! ( "{}" , a);
}
fn double (x: i32 ) -> i32 {

x*2
}
fn main () {
let a = true ;
let _y = change_truth (a);

println! ( "{}" , a);
}
fn change_truth (x: bool ) -> bool {

!x
}
If we had types that did not implement the Copy trait , we would have got a
compilation error for trying to use a moved value.
error: use of moved value: à`
println! ("{}", a);
^
We will discuss how to make your own types Copy in the traits section
More than belonging

Of course, if we need to return the membership with each function that we
write:
fn foo (v: Vec < i32 >) -> Vec < i32 > {
// do something with v
// returning membership
v
}
Things would get quite tedious. It gets even worse as we have more things
that we want to belong to:
fn foo (v1: Vec < i32 >, v2: Vec < i32 >) -> ( Vec < i32 >, Vec < i32 >, i32 )
{
// do something with v1 and v2
// returning membership, as well as the result of our function

(v1, v2, 42 )
}
let v1 = vec! [ 1 , 2 , 3 ];
let v2 = vec! [ 1 , 2 , 3 ];
let (v1, v2, answer) = foo (v1, v2);
Ugh! The return type, the return line, and the function call become much
more complicated.
Fortunately, Rust offers a facility, the loan, a facility that helps us solve this
problem.
It is the topic of the next section!
References and Loan

one of the most unique and attractive features of Rust, with which Rust
developers should be well acquainted. Membership is how Rust achieves its
highest goal, memory management security. There are a few different
concepts, each with its own chapter:
membership , the main concept
loan, the one you read now
life times , an advanced loan concept
These three chapters are related, and in order. You will need to read all three
to fully understand the membership system.
Goal
With that in mind, let's learn about the loan.
Loan
At the end of the membership section , we had an ugly function that looked
like this:
fn foo (v1: Vec < i32 >, v2: Vec < i32 >) -> ( Vec < i32 >, Vec < i32 >, i32 )
{
// returning membership, as well as the result of our function

(v1, v2, 42 )
}
let v1 = vec! [ 1 , 2 , 3 ];
let v2 = vec! [ 1 , 2 , 3 ];
let (v1, v2, answer) = foo (v1, v2);
The above, however, is not idiomatic Rust, since it does not benefit from the
advantages of the loan. Here is the first step:
fn foo (v1: & Vec < i32 >, v2: & Vec < i32 >) -> i32 {
// returning the answer

42
}
let v1 = vec! [ 1 , 2 , 3 ];
let v2 = vec! [ 1 , 2 , 3 ];
let answer = foo (& v1, & v2);
// we can use v1 and v2 here

Instead of taking Vec <i32> s as arguments, we take a reference: & Vec <i32> .
And instead of passing v1 and v2 directly, we pass & v1 and & v2 . We call
the & T type a 'reference', and instead of taking ownership of the resource, it
borrows it. A variable link that borrows something doesn't release the
resource when it goes out of scope. This means that after the foo () call , we
can again make use of the original variable bindings.
References are immutable, just like variable links. This translates to that
within foo () , the vectors cannot be changed:
fn foo (v: & Vec) {

v.push (5);
}
let v = vec! [];
foo (& v);
fails with:
error: cannot borrow immutable borrowed content `* v` as mutable

v.push (5);
^
Inserting a value causes a mutation in the vector, and we are not allowed to
do so.
references & mut

There is a second type of reference: & mut T . A 'mutable reference' that
allows you to mutate the resource you are borrowing. For example:
let mut x = 5 ;
{
let y = & mut x;
* and + = 1 ;
}
println! ( "{}" , x);
The above will print 6 . We make y a mutable reference to x , then add one
to whatever y points to. You will notice that x also had to be marked as mut
, otherwise we would not have been able to take a mutable loan at immutable
value.
You will also notice that we have added an asterisk ( * ) in front of y ,
making it * and , this is because y is a & mut reference . You will also need to
use them to access the content of a reference.
Otherwise, & mut references are like references. There is a big difference
between the two, and how they interact. You will have noticed that there is
something that does not smell very good in the previous example, since we
need that extra scope, with the { y } . If we remove them, we get an error:
error: cannot borrow `x` as immutable because it is also borrowed as

mutable
println! ("{}", x);
^
note: previous borrow of `x` occurs here; the mutable borrow prevents
subsequent moves, borrows, or modification of `x` until the borrow ends
let y = & mut x;
^
fn main () {
}
^
Apparently there are rules.
The rules
Here are the rules about the loan at Rust:
First, any loan must live in a realm no larger than that of the owner. Second,
you can have one or the other of these types of loans, but not both at the same
time:
one or more references ( & T ) to a resource,
exactly a mutable reference ( & mut T ).
You may notice that this is very similar, but not exactly the same, to the
definition of a race condition:
There is a 'race condition' when two or more pointers access the same
memory location at the same time, where at least one is writing, and the
operations are not synchronized.
With the references, you can have as many as you want, since none of them
are writing. If you are writing, and you need two or more pointers to the same
memory, you can have only one & mut at a time. This is how Rust prevents
race conditions at compile time: we will get errors if we break the rules.
With this in mind, let's consider our example again.
Thinking about scopes

Here is the code:
let mut x = 5;
let y = & mut x;
* and + = 1;
println! ("{}", x);

The above code generates the following error:
error: cannot borrow `x` as immutable because it is also borrowed as
mutable
println! ("{}", x);
^
This is because we have violated the rules: we have a & mut T pointing to x ,
and consequently we are not allowed to create any & T s. One thing or
another. The note points to how to think about this problem:
fn main () {
}
^
In other words, the mutable loan is maintained throughout the rest of our
example. What we want is for our mutable loan to end before we try to call
println! and let's make an immutable loan. At Rust, the loan is associated with
the area in which the loan is valid. Our areas look like this:
let mut x = 5;
let y = & mut x; // - + x loan & mut starts here

// |
* and + = 1; // |
// |
println! ("{}", x); // - + - attempt to borrow x here
// - + x loan & mut ends here
The scopes conflict: we cannot create an &x while y is in scope.

So when we add braces:
let mut x = 5 ;
{
let y = & mut x; // - + x loan & mut starts here
* and + = 1 ; // |
} // - + ... and ends here
println! ( "{}" , x); // <- attempt to borrow x here

No problem. Our mutable loan goes out of scope before we create an
immutable loan. The scope is key to see how long the loan lasts.
Problems that the loan prevents
Why do we have these restrictive rules? Well, as we noted, these rules
prevent race conditions. What kinds of problems do race conditions cause?
Here a few.
Iterator Invalidation
An example is 'iterator override', which occurs when you try to mutate a
collection while iterating over it. Rust's loan checker prevents this from
happening:
let mut v = vec! [ 1 , 2 , 3 ];
for i in & v {
println! ( "{}" , i);
}
The above prints from one to three. As we iterate the vectors, we are only
provided with references to their elements. v itself is immutably borrowed,
which means we can't change it while iterating:
let mut v = vec! [1, 2, 3];
for i in & v {
println! ("{}", i);
v.push (34);
}
Here is the error:

error: cannot borrow `v` as mutable because it is also borrowed as
immutable
v.push (34);
^
note: previous borrow of `v` occurs here; the immutable borrow
prevents
subsequent moves or mutable borrows of `v` until the borrow ends
for i in & v {
^
for i in & v {
println! (“{}”, i);
v.push (34);
}
^
We cannot modify v because it is borrowed by the cycle.
use after release

References should not live any longer than the resource they point to. Rust
will check the scope of your references to make sure this is true.
If Rust did not verify this property, we could accidentally use an invalid
reference. For example:
let y: & i32;
{
let x = 5;
y = & x;
}
println! ("{}", and);

We get the following error:
error: `x` does not live long enough
y = & x;
^
note: reference must be valid for the block suffix following statement 0 at
2:16 ...
let y: & i32;
{
let x = 5;
y = & x;
}
note: ... but borrowed value is only valid for the block suffix following
statement 0 at 4:18
let x = 5;
y = & x;
}
In other words, y is valid only for the area where x exists. As soon as x
leaves, reference is invalid. That is why the error says that the loan, 'does not
live long enough' ('does not live long enough') since it is not valid for the
correct amount of time.
The same problem occurs when the reference is declared before the variable
to which it refers. This is because the resources within the same scope are
released in the opposite order to the order in which they were declared:
let y: & i32;
let x = 5;
y = & x;
We get this error:

error: `x` does not live long enough
y = & x;
^
note: reference must be valid for the block suffix following statement 0 at
2:16 ...
let y: & i32;
let x = 5;
y = & x;

}
note: ... but borrowed value is only valid for the block suffix following
statement 1 at 3:14
let x = 5;
y = & x;

}
In the example above, y is declared before x , meaning that y lives longer
than x , which is not allowed.
Life Times
one of the most unique and attractive features of Rust, with which Rust
developers should be well acquainted. Membership is how Rust achieves its
highest goal, memory management security. There are a few different
concepts, each with its own chapter:
membership , the main concept
[loan] [borrowing], and its associated characteristic 'references'
times of life , the one you read now
These three chapters are related, and in order. You will need to read all three
to fully understand the membership system.
Goal
With that in mind, let's learn about life times.
Life times
Lending a reference to another resource that someone else owns can be
tricky. For example, imagine this set of operations:
I get a handle to some kind of resource.
I lend you a reference to the resource.
I decide that I am done with the resource, and release it, while you still have the
reference to it.
You decide to use the resource.
Oh no! Your reference is pointing to an invalid resource. This is called a

hanging pointer, or use after release , when the resource is memory.
To fix this, we have to make sure that step four never occurs after step three.
The Rust membership system does this through a concept called lifetimes,
which describe the scope in which a reference is valid.
When we have a function that takes a reference as an argument, we can be
implicit or explicit about the reference's lifetime:
// implicit
fn foo (x: & i32 ) {
}
// explicit
fn bar < 'a > (x: & ' a i32 ) {
}
The 'a is read' the life time a '. Technically, every reference has a lifetime
associated with it, but the compiler allows you to omit them in common
cases. Before we get to that, let's take a look at the explicit piece of code:
fn bar <'a> (...)
We talked a bit about function syntax earlier , but we didn't discuss <> s after
a function name. A function can have 'generic parameters' between the <> s,
and lifetimes are a type of generic parameter. We will discuss other types of
generics later in the book , but for now, let's focus only on the life time
aspect.
We use <> to declare our life times. This says that bar has a life time, 'a .
Had it had references as parameters, it would have looked like this:
fn bar <'a,' b = ""> (...)
So in our parameter list, we use the lifetimes that we have named:
... (x: & 'a i32)
If we wanted a referral & mut , we could have done the following:
... (x: & 'a mut i32)
If you compare & mut i32 with & 'to mut i32 , they are the same, it's just that
time of life ' to have gotten between & and mut i32 . We read & mut i32 as 'a
mutable reference to an i32 ' and & 'to mut i32 as' a mutable reference to an i32
with the lifetime 'a '.
In struct s
You will also need explicit lifetime times when working with struct s:
struct Foo < 'a > {
x: & 'to i32 ,
}
fn main () {
let y = & 5 ; // this is the same as `let _y = 5; let y = & _y; `
let f = Foo {x: y};
println! ( "{}" , fx);

}
As you can see, structs can also have lifetime. In a similar way to functions,
struct Foo < 'a > {
# x: & 'a i32 ,
#}
declares a life time, and
# struct Foo < 'a > {
x: & 'to i32 ,
#}
makes use of it. So why do we need a life time here? We need to make sure
that any reference to a Foo cannot live longer than the reference to an i32 it
contains.
impl blocks
Let's implement a method in Foo :
struct Foo < 'a > {
x: & 'to i32 ,
}
impl < 'a > Foo < ' a > {

fn x (& self ) -> & 'a i32 { self .x}
}
fn main () {
let y = & 5 ; // this is the same as `let _y = 5; let y = & _y; `
let f = Foo {x: y};
println! ( "x is: {}" , fx ());

}
As you can see, we need to declare a lifetime for Foo in the impl line . We
repeat 'a twice, just as in functions: impl <' a> defines a lifetime 'a , and Foo <'
a> makes use of it.
Multiple life time
If you have multiple references, you can use the same life time multiple
times:
fn x_o_y < 'a > (x: & ' a str , y: & 'a str ) -> & ' a str {
#x
#}
The above says that both x and y live in the same scope, and that the return
value is also alive for that scope. If you had wanted x and y to have different
lifetimes, you could have made use of multiple lifetime parameters:
fn x_o_y < 'a , ' b > (x: & 'a str , y: & ' b str ) -> & 'a str {
#x
#}
In this example, x and y have different valid scopes, but the return value has
the same life time as x .
Thinking about scopes
One way of thinking about lifetimes is to visualize the environment in which
a reference is valid. For example:
fn main () {
let y = & 5 ; // - + and enter scope
// |
// stuff // |
// |
} // - + and leaves scope
Adding our Foo :
struct Foo < 'a > {
x: & 'to i32 ,
}
fn main () {
let y = & 5 ; // - + and enter scope
let f = Foo {x: y}; // - + f enters scope
// stuff // |
// |
} // - + fyy go out of scope
Our f lives within the scope of y , that is why everything works. What
would happen otherwise? The following code would not work:
struct Foo <'a> {
x: & 'to i32,
}
fn main () {
let x; // - + x enters scope
// |
{// |
let y = & 5; // --- + and enter scope
let f = Foo {x: y}; // --- + f enters scope
x = & f.x; // | | mistake here
} // --- + fyy go out of scope
// |
println! ("{}", x); // |
} // - + x goes out of scope
Uff! As you can see here, the scopes of f and y are less than the scope of x .
But when we do x = & f.x , we make x a reference to something to be out of
scope.
Named lifetimes are a way to give these settings a name. Giving something a
name is the first step toward being able to talk about it.
'static
The lifetime called 'static' is a special lifetime. This points out that something
has the lifetime of the entire program. Most Rust developers know 'static
when dealing with character strings:
let x: & 'static str = "Hello, world." ;
Character string literals have the & 'static str type since the reference is always
alive: these are placed in the data segment of the final binary. Another
example is the global ones:
static FOO: i32 = 5 ;
let x: & 'static i32 = & FOO;
The above adds an i32 to the data segment of the binary, and x is a reference
to it.
Life times elision

Rust supports powerful type inference in function bodies, but it is prohibited
in element signatures to allow reasoning based solely on the signature.
However, for ergonomic reasons, a very restricted secondary inference called
"life time elision" applies in function firms. The "life time elision" infers
based only on the components of the signature without relying on the body of
the function, it only infers life time parameters, and does this with only three
easily memorizable and unambiguous rules. All of this makes life time
shortcuts for writing a signature, without the need to hide the types involved
since full local inference will be applied to them.
When talking about life time elision, we use the term input life time and
output life time . An input lifetime is a lifetime associated with a parameter of
a function, and an output lifetime is a lifetime associated with the return value
of a function. For example, the following function has an input lifetime:
fn foo <'a> (bar: &' a str)
It has an output lifetime:
fn foo <'a> () -> &' a str
The following has a life time in both positions:
fn foo <'a> (bar: &' a str) -> & 'a str
Here are the three rules:
Each time of life elided in the arguments of a function becomes a different time of life
parameter.
If there is exactly a single input lifetime, elided or not, that lifetime is assigned to all
ellipses lifetime in that function's return values.
If there are multiple input life times, but one of them is & self or & mut self , the
self life time is assigned to all elided output life times.
Otherwise, it is a mistake to avoid an output lifetime.
Examples
Here are some examples of functions with elided lifetimes. We have paired
each example of an elided life time with its expanded form.
fn print (s: & str); // elided
fn print <'a> (s: &' a str); // expanded
fn debug (lvl: u32, s: & str); // elided

fn debug <'a> (lvl: u32, s: &' a str); // expanded
// In the example above, `lvl` does not need a lifetime because it is not a
reference (` & `). Only things related to references (like a `struct` that
contains a reference) need lifetime.
fn substr (s: & str, until: u32) -> & str; // elided
fn substr <'a> (s: &' a str, until: u32) -> & 'a str; // expanded
fn get_str () -> & str; // ILLEGAL, no inputs
fn frob (s: & str, t: & str) -> & str; // ILLEGAL, two inputs
fn frob <'a,' b = ""> (s: & 'a str, t: &' b str) -> & str; // Expanded:
Output lifetime is ambiguous
fn get_mut (& mut self) -> & mut T; // elided

fn get_mut <'a> (&' a mut self) -> & 'a mut T; // expanded
fn args (& mut self, args: & [T]) -> & mut Command // elided
fn args <'a,' b, = "" T: ToCStr = ""> (& 'a mut self, args: &' b [T]) -> &
'a mut Command // expanded
fn new (buf: & mut [u8]) -> BufWriter; // elided

fn new <'a> (buf: &' a mut [u8]) -> BufWriter <'a> // expanded
Mutability
Mutability, is the ability that a thing has to be changed, works a little
differently in Rust than in other languages. The first aspect of mutability is
that it is not enabled by default:
let x = 5;
x = 6; // error!
We can introduce mutability with the mut keyword :
let mut x = 5 ;
x = 6 ; // no problem!
This is a link to mutable variable. When a link to variable is mutable, it
means that you are allowed to change what the link points to. So, in the
example above, you are not changing the value at x , instead, the link
changed from one i32 to another.
If you want to change what the link points to variable, you will need a
mutable reference :
let mut x = 5 ;
let y = & mut x;
y is an immutable variable link to a mutable reference, which means you can't
associate y to something else ( y = & mut z ), but you can mutate whatever y
is associated with ( * y = 5 ). A very subtle difference.
Of course, if you need both:
let mut x = 5 ;
let mut y = & mut x;
Now and it may be associated with another value, and the value that this
referencing can be changed.
It is important to note that mut is part of a pattern , so that you can do things
like:
let ( mut x, y) = ( 5 , 6 );
fn foo ( mut x: i32 ) {
#}
Internal Mutability vs. Exterior Mutability

However, when we say that something is 'immutable' in Rust, this does not
mean that it cannot be changed: what we say is that something has 'external
mutability'. Consider, for example, Arc <T> :
use std :: sync :: Arc;
let x = Arc :: new ( 5 );

let y = x.clone ();
When we call clone () , the Arc <T> needs to update the reference counter.
Although we haven't used any mut here, x is an immutable link, we also
don't take & mut 5 or any more. So what's going on?
To understand this, we must return to the core of the philosophy that guides
Rust, security in memory management, and the mechanism through which
Rust guarantees it, the membership system , and more specifically, the loan :
You can have one or the other of these two types of loan, but not both at the
same time:
one or more references ( & T ) to a resource,
exactly a mutable reference ( & mut T ).
So that's the real definition of 'immutability': is it safe to have two pointers?

In the case of Arc <T> 's, if: the mutation is completely contained within the
structure itself. It is not available to the user. For this reason, clone () & T s
returns . If I provided & mut T s, it would be a problem.
Other types, such as the std :: cell module , have the opposite: internal
mutability. For example:
use std :: cell :: RefCell;
let x = RefCell :: new ( 42 );

let y = x.borrow_mut ();
RefCel provides & mut references to what they contain through the borrow_mut
() method . Isn't this dangerous? What if we do:
use std :: cell :: RefCell;
let x = RefCell :: new (42);
let y = x.borrow_mut ();

let z = x.borrow_mut ();
# (and Z);
This, in effect, will panic at runtime. This is what RefCell does: it enforces
Rust's borrow rules at runtime, and it panics! if these rules are violated. This
allows us to approach another aspect of Rust's mutability rules. Let's talk
about it first.
Field level mutability

Mutability is a property of a loan ( & mut ) or a variable link ( let mut ). This
translates to, for example, you can't have a struct with some mutable and
some immutable fields:
struct Point {
x: i32,
mut y: i32, // nope
}
The mutability of a struct is in its link to variable:
struct Point {
x: i32,
y: i32,
}
let mut a = Point {x: 5, y: 6};
ax = 10;
let b = Point {x: 5, y: 6};
bx = 10; // error: cannot assign to immutable field `bx`

However, using Cell <T> , you can emulate field level mutability:
use std :: cell :: Cell;
struct Point {
x: i32 ,
y: Cell < i32 >,
}
let dot = Dot {x: 5 , y: Cell :: new ( 6 )};
dot.y.set ( 7 );
println! ( "y: {:?}" , punto.y);

This will print y: Cell {value: 7} . We have updated and satisfactorily.
Structures
Structures ( struct s) are a way to create more complex data types. For
example, if we were doing calculations involving coordinates in 2D space,
we would need both an x value and a y value :
let origin_x = 0 ;
let origin_y = 0 ;
A struct allows us to combine both into a single unified data type:
struct Point {
x: i32 ,
y: i32 ,
}
fn main () {
let origin = Point {x: 0 , y: 0 }; // origin: Point
println! ( "The origin is in ({}, {})" , origin.x, origin.y);

}
There is a lot going on here, so let's break it down. We declare a structure
with the keyword struct , followed by a name. By convention, structs start with
a capital letter and are camel cased: DotInTheSpace , not Dot_In_The_Space .
We can instantiate our struct via let , as usual, but we use a key: value syntax to
assign each field. The order does not need to be the same as in the original
declaration.
Finally, because we have field names, we can access them through the dot
notation: origin.x .
Values in struct s are immutable by default, just like the other links to
variables in Rust. Use mut to make them mutable:
struct Point {
x: i32 ,
y: i32 ,
}
fn main () {
let mut dot = Dot {x: 0 , y: 0 };
dot.x = 5 ;
println! ( "The origin is in ({}, {})" , dot.x, dot.y);

}
This will print The origin is at (5, 0) .
Rust does not support language level mutability of fields, that's why you can't
write something like this:
struct Point {
mut x: i32,
y: i32,
}
Mutability is a property of the variable link, not of the structure itself. If
you're used to field-level mutability, this may seem a bit strange at first, but it
simplifies things significantly. It even allows you to make things mutable
only for a short period of time:
struct Point {
x: i32,
y: i32,
}
fn main () {
let mut dot = Dot {x: 0, y: 0};
dot.x = 5;
let dot = dot; // now, this new link to variable cannot be changed
dot.y = 6; // this causes an error

}
Update syntax
A struct can include .. to indicate that you want to use a copy of some other
struct for some of the values. For example:
struct Point3d {
x: i32 ,
y: i32 ,
z: i32 ,
}
let mut dot = Dot3d {x: 0 , y: 0 , z: 0 };

point = Point3d {y: 1 , .. point};
This assigns a new y point , but maintains the old values of x and z . It does
not have to be the same structure, you can make use of this syntax when you
create new ones, and it will copy the values you do not specify:
# struct Punto3d {
# x: i32 ,
# y: i32 ,
# z: i32 ,
#}
let origin = Point3d {x: 0 , y: 0 , z: 0 };
let dot = Dot3d {z: 1 , x: 2 , .. origin};
Tuple structures (Tuple structs)

Rust has another type of data that is like a hybrid between a tuple and a struct
, called a tulla structure ( tuple struct ). Tuple structures have a name, but their
fields do not:
struct Color ( i32 , i32 , i32 );
struct Point ( i32 , i32 , i32 );
The previous two will not be the same, even if they have the same values:
# struct Color ( i32 , i32 , i32 );
# struct Point ( i32 , i32 , i32 );
let black = Color ( 0 , 0 , 0 );
let origin = Point ( 0 , 0 , 0 );
It is almost always better to use a struct than a struct tuple . Instead, we could
write Color and Punto like so:
struct Color {
red: i32 ,
blue: i32 ,
green: i32 ,
}
struct Point {
x: i32 ,
y: i32 ,
z: i32 ,
}
Now, we have names, instead of positions. Good names are important, and
with a struct , we have names.
There is a case in which a structure tuple is very useful, and it is a structure
tuple with a single element. Called pattern nuevotipo ( newtype ), since they
create a new type, different from the value it contains, expressing semantics
itself:
struct Inches ( i32 );
let length = Inches ( 10 );
let Inches (integer_length) = length;

println! ( "length is {} inches" , integer_length);
As you will notice, you can extract the entire content with a destruct let , just
like in regular tuples. In this case, the Inches (integer_length) let assigns 10 to
integer_length .
Unit-like structs
You can define a struct without any member:
struct Electron;
This struct is called type-unit ( unit-like ) because of its similarity to the empty
tuple, () , sometimes called unit ( unit ). As a tuple structure, it defines a new
type.
The above is rarely useful in itself (although it can sometimes serve as a
marker type), but in combination with other features, it can become useful.
For example, a library may require creating a structure that implements a
certain trait to handle events. If you don't have any data to save in the
structure, you can simply create a unit-type struct .
Enumerations
An enum ( enum ) in Rust is a type that represents data that can be one of a set
of possible variants:
enum Message {
Leave,
ChangeColor ( i32 , i32 , i32 )
Move {x: i32 , y: i32 },
Write ( String ),
}
Each variant can optionally have associated data. The syntax for defining
variants is similar to the syntax used to define structures ( struct s): you can
have variants without data (such as unit-type structures), variants with named
data, and variants with unnamed data (such as tuple structures). ). However,
unlike structure definitions, an enum is a single type. An enum value can
match any of the variants. For this reason, an enum is sometimes called a
'sum type': the set of possible values of the enum is the sum of the sets of
possible values for each variant.
We use the :: syntax to make use of each variant: the variants are within the
scope of the enum . Which makes the following valid:
# enum Message {
# Move {x: i32 , y: i32 },
#}
let x: Message = Message :: Move {x: 3 , y: 4 };
enum Turn Game Table {

Move {cells: i32 },
Pass,
}
let y: GameTurnTurn = TableTurnTurn :: Move {cells: 1 };

Both variants have the name Move , but because their scope is within the
enum name, both can be used without conflict.
A value of an enum type contains information about which variant it is, in
addition to any data associated with that variant. This is sometimes called
'tagged union', since the data includes a 'tag' indicating what type it is. The
compiler uses this information to make sure that we are accessing the data in
the enum in a secure way. For example, you can't just try to unstructure a
value as if it were one of the possible variants:
fn process_color_change (msg: Message) {
let Message :: ChangeColor (r, v, a) = msg; // compile-time error
}
Not supporting this type of operations may seem a bit limiting, but it is a
limitation that we can overcome. There are two ways, implementing equality
on our own, or through pattern matching with match expressions , which you
will learn in the next section. We still don't know enough about Rust to
implement equality on our own, but we'll see it in the traits section .
Constructors as functions
A constructor of an enum can also be used as a function. For example:
# enum Message {
# Write ( String ),
#}
let m = Message :: Write ( "Hello, world" .to_string ());
Is the same as
# enum Message {
# Write ( String ),
#}
fn foo (x: String ) -> Message {
Message :: Write (x)
}
let x = foo ( "Hello, world" .to_string ());

This is not immediately useful to us, but when we get to closures , we will talk
about passing functions as arguments to other functions. For example, with
iterators , we can convert a vector from String s to a vector from Message :: Write
s:
# enum Message {
# Write ( String ),
#}
let v = vec! [ "Hello" .to_string (), "World" .to_string ()];
let v1: Vec <Message> = v.into_iter (). map (Message :: Write) .collect ();
Match
Often a simple if / else is not enough, because you have more than two
possible options. Also, the conditions can be complex. Rust has a reserved
word, match , which allows you to replace complicated if / else constructions
with something more powerful. Check out:
let x = 5 ;
match x {
1 => println! ( "one" ),
2 => println! ( "two" ),
3 => println! ( "trees" ),
4 => println! ( "four" ),
5 => println! ( "five" ),
_ => println! ( "something else" ),
}
match takes an expression and then forks based on its value. Each branch arm
has the form value => expression . When the value matches, the expression of the
arm is evaluated. It is called match by the term 'pattern matching', of which
match is an implementation. There is an entire section about patterns that
covers all possible patterns.
So what is the big advantage? Well, there are a few. First of all, match
imposes check exhaustion ( 'exhaustiveness checking'). Do you see the last arm,
the one with the underscore ( _ )? If we remove that arm, Rust will give us
an error:
error: non-exhaustive patterns: `_` not covered
In other words, Rust is trying to tell us that we forgot a value. Because x is
an integer, Rust knows that x can have a number of different values - for
example, 6 . Without the _ , however, there is no matching arm, and
consequently Rust refuses to compile the code. _ acts as an 'arm that catches
everything'. If none of the other arms match, the arm with the _ will, and
since we have said 'catch everything arm', we now have an arm for every
possible value of x , and as a result, our program will compile successfully.
match is also an expression, which means that we can use it on the right side of
a let or directly where an expression is used:
let x = 5 ;
let number = match x {

1 => "one" ,
2 => "two" ,
3 => "three" ,
4 => "four" ,
5 => "five" ,
_ => "something else" ,
};
Sometimes it is a good way to convert something from one type to another.
Making match in enums

Another important use of the match keyword is to process possible variants of
an enum:
enum Message {
Leave,
ChangeColor ( i32 , i32 , i32 )
Move {x: i32 , y: i32 },
Write ( String ),
}
fn exit () { / * ... * / }
fn change_color (r: i32 , g: i32 , b: i32 ) { / * ... * / }
fn move_cursor (x: i32 , y: i32 ) { / * ... * / }
fn process_message (msg: Message) {

match msg {
Message :: Exit => exit (),
Message :: ChangeColor (r, g, b) => change_color (r, g, b),
Message :: Move {x: x, y: y} => move_cursor (x, y),
Message :: Write (s) => println! ( "{}" , s),
};
}
Again, the Rust compiler checks exhaustion, demanding that you have an arm
for each variant of the enumeration. If you leave one out, Rust will generate a
compile-time error, unless you use _ .
Unlike previous uses of match , you can't use the if statement to do this. You
can make use of an if let statement that can be seen as a short form of match .
Vector
A 'vector' is a dynamic array, implemented as the type of the standard Vec
<T> library . The T means that we can have vectors of any type (take a look
at the [generics] [generics] chapter for more information). Vectors always
house their data on the mound. You can create vectors with the vec macro ! :
let v = vec! [ 1 , 2 , 3 , 4 , 5 ]; // v: Vec <i32>
(Note that unlike the println! Macro we have used in the past, we use square
brackets [] with the vec! Macro . Rust allows you to use any in any situation,
this time it is purely by convention)
There is an alternative form of vec! to repeat an initial value:
let v = vec! [ 0 ; 10 ]; // ten zeros
Accessing elements
To get the value at a particular index of the vector, we use [] s:
let v = vec! [ 1 , 2 , 3 , 4 , 5 ];
println! ( "The third element of v is {}" , v [ 2 ]);

Indices start from 0 , so the third element is v [2] .
Iterating
Once you have a vector, you can iterate through its elements with for . There
are three versions:
let mut v = vec! [ 1 , 2 , 3 , 4 , 5 ];
for i in & v {
println! ( "A reference to {}" , i);
}
for i in & mut v {
println! ( "A mutable reference to {}" , i);
}
for i in v {
println! ( "Taking membership of the vector and its element {}" , i);
}
Character Strings
Character strings are an important concept to master for any programmer.
The character string handling system in Rust is slightly different from that of
other languages, due to its focus on system programming. As long as you
have a variable-size data structure, things can get a little difficult, and
character strings are a data structure that can vary in size. That said, Rust's
character strings also work differently than in some other system
programming languages, such as C.
Let's go into the details. A 'character string' ('string') is a sequence of Unicode
scalar values encoded as a stream of UTF-8 bytes. All character strings are
guaranteed to be a valid encoding of UTF-8 sequences. Additionally, and
unlike other system languages, character strings are not null-terminated and
can contain null bytes.
Rust has two main types of character strings: & str and String . Let's talk about
& str first . These are called 'string slices'. String literals are of type & 'static
str`:
let greeting = "Hello." ; // greeting: & 'static str
This character string is statically assigned, meaning that it is stored within our
compiled program, and exists for the full duration of its execution. The
greeting link is a reference to an aesthetically assigned string. Pieces of
character strings are of a fixed size, and cannot be mutated.
A String , on the other hand, is a character string assigned from the mound.
This chain can grow, and it is also guaranteed to be UTF-8. The String are
commonly created through conversion of a piece of character string using the
method to_string .
let mut s = "Hello" .to_string (); // mut s: String
println! ( "{}" , s);
s.push_str ( ", world." );

println! ( "{}" , s);
The String s haran coercion to a & str with & :
fn get_scrap (bit: & str ) {
println! ( "I received: {}" , piece);
}
fn main () {
let s = "Hello" .to_string ();
receive_piece (& s);
}
This coercion does not occur for functions that accept one of the traits & str ’s
instead of & str . For example, TcpStream :: connect has a parameter of type
ToSocketAddrs . A & str is fine but a String must be explicitly converted using &
* .
use std :: net :: TcpStream;
TcpStream :: connect ("192.168.0.1:3000"); // parameter & str
let address_string = "192.168.0.1:3000" .to_string ();

TcpStream :: connect (& * address_string); // converting address_string
to & str
Viewing a String as a & str is cheap, but converting the & str to a String
involves memory allocation. There is no reason to do that unless necessary!
Indexed
Because the character strings are valid UTF-8, they do not support indexing:
let s = "hello";
println! ("The first letter of s is {}", s [0]); // ERROR!!!

Access to a vector with [] is usually very fast. But, since each character
encoded in a UTF-8 string can have multiple bytes, you must traverse the
entire string to find the nᵗʰ letter of a string. This is a significantly more
expensive operation, and we do not want to create confusion. Even 'letter' is
not exactly something defined in Unicode. We can choose to see a character
string as individual bytes, or as codepoints:
let hachiko = " 忠　犬　ハ　チ　公" ;
for b in hachiko.as_bytes () {
print! ( "{}," , b);
}
println! ( "" );
for c in hachiko.chars () {
print! ( "{}," , c);
}
println! ( "" );
The above prints:
229, 191, 160, 231, 138, 172, 227, 131, 143, 227, 131, 129, 229, 133, 172,
忠, 犬, ハ, チ, 公,
As you can see, there are more bytes than characters ( char s).
You can get something similar to an index like this:
# let hachiko = " 忠　犬　ハ　チ　公" ;
let dog = hachiko.chars (). nth ( 1 ); // something like hachiko [1]
This emphasizes that we have to walk from the beginning of the chars list .
Slicing
You can get a piece of a character string with the cut syntax:
let dog = "hachiko" ;
let hachi = & dog [ 0 .. 5 ];
But note that these are byte offsets, not character offsets . So the following
will fail at runtime:
let dog = " 忠　犬　ハ　チ　公";
let hachi = & dog [0..2];
with this error:
thread '' panicked at 'index 0 and / or 2 in ` 忠　犬　ハ　チ　公 ` do not lie on
character boundary '
Concatenation
If you have a String , you can concatenate a & str at the end:
let hello = "Hello" .to_string ();
let mundo = "world!" ;
let hello_world = hello + world;

But if you have two String s, you need a & :
let hello = "Hello" .to_string ();
let mundo = "world!" .to_string ();
let hello_world = hello + & world;

This is because & String can automatically coerce a & str . This feature is
called ' Deref coercions '.
Generic
Sometimes when writing a function or data structure, we might wish that it
could work with multiple types of arguments. At Rust we can achieve this
through generics. Generics are called 'parametric polymorphism' in type
theory, which means that they are types or functions that have multiple
shapes ('poly' for multiple, 'morph' for shape) on a certain parameter
('parametric').
Either way, enough about type theory, let's look at some generic code. The
standard Rust library provides a type, Option <T> , which is generic:
enum Option <T> {
Some (T),
None ,
}
The <T> part , which you have seen a few times before, indicates that this is a
generic data type. Within the declaration of our enum, wherever we see a T
we substitute that type for the same type used in the generic one. Here's an
example of using Option <T> , with some extra annotations:
let x: Option < i32 > = Some ( 5 );
In the type declaration, we say Option <i32> . Note how similar this looks to
Option <T> . So in this Option , T has the value of i32 . On the right side of the
binding, we make a Some (T) , where T is 5 . Because 5 is an i32 , both sides
match, and Rust is happy. If they did not match, we would have got an error:
let x: Option = Some (5);
// error: mismatched types: expected `core :: option :: Option`,
// found `core :: option :: Option <_>` (expected f64 but found integral
variable)
That doesn't mean we can't create Option <T> s that contain an f64 . They
simply must match:
let x: Option < i32 > = Some ( 5 );
let y: Option < f64 > = Some ( 5.0f64 );
Very good. One definition, multiple uses.
Generics do not necessarily have to be generic on a single type. Consider
another similar type in Rust's standard library, Result <T, E> :
enum Result <T, E> {
Ok (T),
Err (E),
}
This type is generic on two types: T and E . By the way, capital letters can
be any. We could have defined Result <T, E> as:
enum Result <A, Z> {
Ok (A),
Err (Z),
}
to have wanted. The convention says that the first generic parameter must be
T , of 'type', and that we use E for 'error'. Rust, however, does not care.
The Result <T, E> type is used to return the result of a computation, with the
possibility of returning an error in the event that such computation has not
been successful.
Generic functions
We can write functions that take generic types with a similar syntax:
fn receives_any_thing <T> (x: T) {
// do something with x
}
The syntax has two parts: the <T> says "this function is generic on a type, T
", and the x: T part says "x has the type T. "
Multiple arguments can have the same type:
fn receives_two_things_from_the same_type <T> (x: T, y: T) {
// ...
}
We could have written a version that receives multiple types:
fn receives_two_things_from_different_types <T, U> (x: T, y: U) {
// ...
}
Generic structures
You can also store a generic type in a structure:
struct Point <T> {
x: T,
y: T,
}
let integer_source = Point {x: 0 , y: 0 };

let float_origin = Point {x: 0.0 , y: 0.0 };
Similarly to functions, the <T> section is where we declare generic
parameters, after that we make use of x: T in the type declaration, too.
When we want to add an implementation for the generic structure, you
simply declare the type parameter after impl :
# struct Point <T> {
# x: T,
# y: T,
#}
#
impl <T> Point <T> {
fn exchange (& mut self ) {
std :: mem :: swap (& mut self .x, & mut self .y);
}
}
So far you have only seen generics that accept absolutely any type. These are
useful in many cases, you have already seen Option <T> , and later you will
meet universal containers like Vec <T> . On the other hand, sometimes you
will want to exchange that flexibility for greater expressive power. Read
about trait limits to see why and how.
Traits
A trait is a language facility that tells the Rust compiler about the
functionality that a type must provide.
Remember the impl ? Keyword , used to call a function with the method syntax
?
struct Circle {
x: f64 ,
y: f64 ,
radius: f64 ,
}
impl Circle {
fn area (& self ) -> f64 {
std :: f64 :: consts :: PI * ( self .radio * self .radio)
}
}
The traits are similar, except that we define a trait with only the method
signature and then implement the trait for the structure. So:
struct Circle {
x: f64 ,
y: f64 ,
radius: f64 ,
}
trait HasArea {
fn area (& self ) -> f64 ;
}
impl HasArea for Circle {

}
}
As you can see, the trait block looks very similar to the impl block , but we
don't define a block, just the type signature. When we implement a trait, we
use Impl Trait for Item , instead of just Impl Item .
Trait limits for generic functions
Traits are useful because they allow a guy to make certain promises about his
behavior. Generic functions can exploit this to restrict the types they accept.
Consider this function, which doesn't compile:
fn imrimir_area (figure: T) {
println! ("This figure has an area of {}", figura.area ());
}
Rust complains:
error: no method named àrea` found for type` T` in the current scope
Because T can be of any type, we cannot be sure that it implements the area
method . But we can add a 'trait constraint' to our generic T , making sure it
implements it:
# trait HasArea {
# fn area (& self ) -> f64 ;
#}
fn print_area <T: HasArea> (shape: T) {
println! ( "This figure has an area of {}" , figura.area ());
}
The <T: hasArea> syntax translates to "any type that implements the hasArea
trait .". As traits define function type signatures, we can be sure that any type
that implements hasArea will have a .area () method .
Here's an extended example of how this works:
trait HasArea {
}
struct Circle {
x: f64 ,
y: f64 ,
radius: f64 ,
}
impl HasArea for Circle {

}
}
Square struct {
x: f64 ,
y: f64 ,
side: f64 ,
}
Impl HasArea for Square {

self. side * self. side
}
}
fn imrimir_area <T: tieneArea> (figure: T) {

println! ( "This figure has an area of {}" , figura.area ());
}
fn main () {
let c = Circle {
x: 0.0f64 ,
y: 0.0f64 ,
radius: 1.0f64 ,
};
let s = Square {
x: 0.0f64 ,
y: 0.0f64 ,
side: 1.0f64 ,
};
print_area (c);
print_area (s);
}
This program produces the output:
This figure has an area of 3.141593
This figure has an area of 1
As you can see, print_area is now generic, but it also ensures that we have
provided the correct types. If we pass an incorrect type:
print_area (5);
We get a compile-time error:
error: the trait `HasArea` is not implemented for the type` _` [E0277]
Trait limits for generic structures

Your generic structures can also benefit from trait restrictions. All you need
to do is add the constraint when you declare the type parameters. Here is a
new Rectangle <T> type and its operation is_square :
struct Rectangle <T> {
x: T,
y: T,
width: T,
height: T,
}
impl <T: PartialEq > Rectangle <T> {

fn is_square (& self ) -> bool {
self. width == self. height
}
}
fn main () {
let mut r = Rectangle {
x: 0 ,
y: 0 ,
width: 47 ,
height: 47 ,
};
assert! (r.es_cuadrado ());
r.height = 42 ;
assert! (! r.es_cuadrado ());
}
needs to check that the sides are equal, and for this the types must
is_square ()
be of a type that implements the trait core :: cmp :: PartialEq :
Impl Rectangle {...}
Now, a rectangle can be defined based on any type that can be compared by
equality.
We have defined a new Rectangle structure that accepts numbers of any
precision, objects of any type as long as they can be compared by equality.
Could we do the same for our HasArea , Square and Circle structures ? Yes, but
they need multiplication, and to work with that we need to know more about
the operator traits .
Rules for the implementation of traits

So far, we have only added trait implementations to structures, but you can
implement any trait for any type. Technically, we could implement TieneArea
for i32 :
trait HasArea {
}
impl TieneArea for i32 {

println! ( "this is silly" );
* self as f64
}
}
5 .area ();
Implementing methods on those primitive types is considered poor style,
even when possible.
This may look like the old west, but there are two restrictions on
implementing traits that prevent things from spiraling out of control. The first
is that if the trait is not defined in your scope, it does not apply. Here's an
example: the standard library provides a Write trait that adds extra
functionality to File s, making file I / O possible. By default, a File would not
have its methods:
let mut f = std :: fs :: File :: open ("foo.txt"). ok (). expect ("Failed to
open foo.txt");
let buf = b "anything"; // byte string literal. buf: & [u8; 8]
let result = f.write (buf);
# result.unwrap (); // ignore the error
Here is the error:
error: type `std :: fs :: File` does not implement any method in scope
named` write`
^ ~~~~~~~~~
We need to first use the Write trait :
use std :: io :: Write;
let mut f = std :: fs :: File :: open ("foo.txt"). ok (). expect ("Failed to

open foo.txt");
let buf = b "anything";
# result.unwrap (); // ignore the error
The above will compile without errors.
This means that even if someone does something wrong like adding methods
to i32 , it won't affect you, unless you use that trait.
There is one more restriction on the implementation of traits: one of the two,
either the trait or the type for which you are writing the impl , must be
defined by you. So, we could implement the hasArea trait for type i32 , since
HasArea is in our code. But if we tried to implement ToString , a trait provided
by Rust for i32 , we couldn't, because neither the trait nor the type is in our
code.
One last thing about traits: generic functions with a trait limit use
'monomorphization' ('monomorphization') (mono: one, morphs: shape), and
are therefore statically dispatched. What does this mean? Take a look at the
chapter on trait objects for more details.
Multiple trait limits
You have seen that you can limit a generic type parameter with a trait:
fn foo <T: Clone > (x: T) {
x.clone ();
}
If you need more than one limit, you can use + :
use std :: fmt :: Debug;
fn foo <T: Clone + Debug> (x: T) {

x.clone ();
println! ( "{:?}" , x);
}
T now needs to be both Clone and Debug .
The where clause

Writing functions with just a few generic types and a small number of trait
limits is not that ugly, but as the number increases, the syntax gets a little
weird:
fn foo <T: Clone , K: Clone + Debug> (x: T, y: K) {

x.clone ();
y.clone ();
println! ( "{:?}" , and);
}
The function name is far to the left, and the parameter list is far to the right.
Trait limits get in the way.
Rust has a solution, and it's called ' where clause ':
fn foo <T: Clone , K: Clone + Debug> (x: T, y: K) {

x.clone ();
y.clone ();
}
fn bar <T, K> (x: T, y: K) where T: Clone , K: Clone + Debug {

x.clone ();
y.clone ();
}
fn main () {
foo ( "Hello" , "world" );
bar ( "Hello" , "world" );
}
uses the syntax previously demonstrated, and bar () uses a where clause .
foo ()
All you need to do is leave the limits out when you define your type
parameters and then add a where after the parameter list. For longer lists,
blank spaces can be added:
fn bar <T, K> (x: T, y: K)

where T: Clone ,
K: Clone + Debug {
x.clone ();
y.clone ();
}
Such flexibility can add clarity in complex situations.
The where clause is also more powerful than the simplest syntax. For
example:
Trait become <Output> {
fn convert (& self ) -> Output;
}
impl become < i64 > for i32 {

fn convert (& self ) -> i64 {* self as i64 }
}
// can be called with T == i32

fn normal <T: ConvertA < i64 >> (x: & T) -> i64 {
x.convert ()
}
// can be called with T == i64

inverse fn <T> () -> T
// pesto is user ConvertA as if it were "ConvertA <i64>"
where i32 : ConvertA <T> {
42 .convert ()
}
The above demonstrates an additional feature of where : it allows limits where
the left side is an arbitrary type ( i32 in this case), not just a simple type
parameter (like T ).
Default methods
If you already know how a typical implementer will define a method, you can
allow your trait to provide a default method:
trait Foo {
fn is_valid (& self ) -> bool ;
fn is_invalid (& self ) -> bool {! self .es_valido ()}

}
Foo trait implementers need to implement es_valido () , but they do not need to
implement es_valido () . They will get it by default. They can also override the
default implementation if they want:
# trait Foo {
# fn is_valid (& self ) -> bool ;
#
# fn is_invalid (& self ) -> bool {! self .es_valido ()}
#}
struct UsaDefault;
impl Foo for UsaDefault {

fn is_valid (& self ) -> bool {
println! ( "UsaDefault.es_valid called." );
true
}
}
struct OverwriteDefault;
impl Foo for OverwriteDefault {

fn is_valid (& self ) -> bool {
println! ( "Override default._valid call." );
true
}
fn is_invalid (& self ) -> bool {

println! ( "OverwriteDefault.es_valid call!" );
true // this implementation is a self-contradiction!
}
}
let default = UsaDefault;

assert! (! default.es_valido ()); // print "UsaDefault.es_valid call."
let on = OverwriteDefault;
assert! (sobre.is_invalid ()); // prints "OverwriteDefault.com_invalid
call!"
Heritage
Sometimes implementing one trait requires implementing another:
trait Foo {
fn foo (& self );
}
trait FooBar : Foo {

fn foobar (& self );
}
FooBar implementers must also implement Foo , like this:
# trait Foo {
# fn foo (& self );
#}
# trait FooBar : Foo {
# fn foobar (& self );
#}
struct Baz;
impl Foo for Baz {

fn foo (& self ) { println! ( "foo" ); }
}
impl FooBar for Baz {

fn foobar (& self ) { println! ( "foobar" ); }
}
If we forget to implement Foo , Rust will tell us:
error: the trait `main :: Foo` is not implemented for the type` main ::
Baz` [E0277]
Drop
Now that we've discussed traits, let's talk about a particular trait provided by
the standard Rust library, Drop . The Drop trait provides a way to execute code
when a value goes out of scope. For example:
struct HasDrop;
impl Drop for HasDrop {

fn drop (& mut self ) {
println! ( "Dropping!" );
}
}
fn main () {
let x = HasDrop;
// let's do something
} // x leaves scope here

When x goes out of scope at the end of main () , the Drop code is executed.
Drop has a method, also called drop () . This method takes a mutable reference
to self .
That's it! Drop's mechanics are very simple, however there are a few details.
For example, values are dropped in the opposite order of how they were
declared. Here is another example:
Explosive struct {
power: i32 ,
}
impl Drop for Explosive {

fn drop (& mut self ) {
println! ( "BOOM multiplied by {} !!!" , self .power);
}
}
fn main () {
let firecracker = Explosive {power: 1 };
let tnt = Explosive {power: 100 };
}
The above will print:
BOOM multiplied by 100 !!!
BOOM multiplied by 1 !!!
The TNT goes first than the firecracker, because it was created later. Last to
enter, first to exit.
So what is Drop good for ? Generally, it is used to clean up any resource
associated with a struct . For example, the type Arc <T> is a guy with
reference counting. When Drop is called, it will decrement the reference
count, and if the total number of references is zero, it will clear the
underlying value.
if let
allows you to combine if and let to reduce the cost of some types of
if let
pattern matching.
For example, let's say we have some kind of Option <T> . We want to call a
function on it if it is a Some <T> , but do nothing if it is None . It would be
something like this:
# let option = Some ( 5 );
# fn foo (x: i32 ) {}
match option {
Some (x) => {foo (x)},
None => {},
}
We don't have to use match here, for example we could use if :
# fn foo (x: i32 ) {}
if option.is_some () {
let x = option.unwrap ();
foo (x);
}
Neither of these two options is particularly attractive. We can use if let to do
the same, but in a better way:
# fn foo (x: i32 ) {}
if let Some (x) = option {
foo (x);
}
If a pattern matches well, it associates any appropriate part of the value with
the identifiers in the pattern, and then evaluates the expression. If the pattern
does not match, nothing happens.
If you want to do something in case the pattern doesn't match, you can use
else :

# fn foo (x: i32 ) {}
# fn bar () {}
if let Some (x) = option {
foo (x);
} else {
Pub();
}
while let
Similarly, while let can be used when you want to conditionally iterate as long
as the value matches a certain pattern. Convert code like this:
# let option: Option < i32 > = None ;
loop {
match option {
Some (x) => println! ( "{}" , x),
_ => break ,
}
}
In code like this:
# let option: Option < i32 > = None ;
while let Some (x) = option {
println! ( "{}" , x);
}
Trait Objects
When the code involves polymorphism, a mechanism is needed to determine
which specific version should be run. This mechanism is called an office .
There are two major forms of dispatch: static dispatch and dynamic dispatch.
While it is true that Rust prefers static dispatching, it also supports dynamic
dispatching through a mechanism called 'trait objects'.
Bases
For the rest of this chapter, we will need a trait and some implementations.
Let's create a simple one, Foo . Foo has a single method that returns a String .
trait Foo {
fn method (& self ) -> String ;
}
We will also implement this trait for u8 and String :
# trait Foo { fn method (& self ) -> String ; }
impl Foo for u8 {
fn method (& self ) -> String { format! ( "u8: {}" , * self )}
}
impl Foo for String {

fn method (& self ) -> String { format! ( "string: {}" , * self )}
}
Static dispatch
We can use trait to perform static dispatch by using trait limits:
# impl Foo for u8 { fn method (& self ) -> String { format! ( "u8: {}" , * self )}}
# impl Foo for String { fn method (& self ) -> String { format! ( "string: {}" , * self )}}
fn do_something <T: Foo> (x: T) {
x.method ();
}
fn main () {
let x = 5u8 ;
let y = "Hello" .to_string ();
do_something (x);
do_something (y);
}
Rust uses 'monomorphization' for static dispatch in this code. Which means
you will create a special version of do_something () for both u8 and String , then
replacing the call places with calls to these specialized functions. In other
words, Rust generates something like this:
# impl Foo for u8 { fn method (& self ) -> String { format! ( "u8: {}" , *
self )}}
# impl Foo for String { fn method (& self ) -> String { format! ( "string:
{}" , * self )}}
fn do_something_u8 (x: u8 ) {
x.method ();
}
fn do_something_string (x: String ) {

x.method ();
}
fn main () {
let x = 5u8 ;
let y = "Hello" .to_string ();
do_something_u8 (x);
do_something_string (y);
}
The above has a great advantage: static dispatch allows function calls to be
inserted online because the receiver is known at compile time, and online
insertion is key to good optimization. Static dispatch is fast, but it comes with
a downside: 'code bloat', as a result of repeated copies of the same function
being inserted into the binary, one for each type.
Also, compilers are not perfect and can "optimize" code by slowing it down.
For example, functions inserted online in an anxious way inflate the
instruction cache (and the cache governs everything around us). This is why
# [inline] and # [inline (always)] should be used with caution, and one reason why
using dynamic dispatch is sometimes more efficient.
However, the common case is that static dispatch is more efficient. One can
have a thin wrapper function dispatched statically by performing dynamic
dispatch, but not vice versa, ie; static calls are more flexible. This is why the
standard library tries to be dynamically dispatched whenever possible.
Dynamic dispatch
Rust provides dynamic dispatch through a facility called 'trait objects'. Trait
objects, like & Foo or Box <Foo> , are normal values that store a value of any
type that implements the given trait, where the precise type can only be
determined at runtime.
A trait object can be obtained from a pointer to a specific type that
implements the trait by converting it (eg & x as & Foo ) or applying coercion
(eg using & x as an argument to a function that receives & Foo ).
Those coercions and conversions also work for pointers like & mut T a & mut
Foo and Box <T> a Box <Foo> , but that's it so far. Coercions and conversions
are identical.
This operation can be seen as the 'deletion' of the compiler's knowledge about
the specific type of the pointer, and that is why traits objects are sometimes
referred to as type deletion .
Going back to the previous example, we can use the same trait to perform
dynamic dispatch with conversion of trait objects:

self )}}
{}" , * self )}}
fn do_something (x: & Foo) {

x.method ();
}
fn main () {
let x = 5u8 ;
do_something (& x as & Foo);
}
or through coercion:
self )}}
{}" , * self )}}
fn do_something (x: & Foo) {

x.method ();
}
fn main () {
let x = "Hello" .to_string ();
do_something (& x);
}
A function that receives a trait object is not specialized for each of the types
that Foo implements : only one copy is generated, sometimes (but not
always) resulting in less code inflation. However, dynamic dispatch comes at
the cost of requiring the slowest calls to virtual functions, effectively
inhibiting any possibility of online insertion and related optimizations.
Why pointers?
Rust, unlike many managed languages, doesn't put things behind default
pointers, which results in types having different sizes. Knowing the size of a
value at compile time is important for things like passing it as an argument to
a function, moving it on the stack, and allocating (and de-allocating) space
for it in the mound for storage.
For Foo , we would need to have a value that could be smaller than a String
(24 bytes) or a u8 (1 byte), as well as any other type that Foo can implement
in dependent crates (any number of bytes). There is no way to guarantee that
the latter case can work if the values are not stored in a pointer, since those
other types can be of arbitrary size.
Placing the value behind a pointer means that the size of the value is not
relevant when we are throwing a trait object around, just the size of the
pointer itself.
Representation
Trait methods can be called on a trait object through a function pointer
register traditionally called 'vtable' (created and managed by the compiler).
Trait objects are simple and complex at the same time: their representation
and distribution is quite straightforward, but there are some rather rare error
messages and some surprising behaviors to discover.
Let's start with the simplest, the representation of a trait object at runtime.
The std :: raw module contains structs with distributions that are just as
complicated as those of built-in types, including trait objects :
# mod foo {
pub struct TraitObject {
pub data: * mut (),
pub vtable: * mut (),
}
#}
That is, a trait object like & Foo consists of a 'data' pointer and a 'vtable'
pointer.
The data pointer points to the data (of an unknown type T ) stored by the trait
object, and the vtable pointer points to the vtable (table of virtual methods')
('virtual method table') corresponding to the implementation of Foo for T .
A vtable is essentially a struct of function pointers, pointing to the particular
segment of machine code for each method implementation. A call to method
like object_trait.method () will return the correct pointer from the vtable and then
make a dynamic call of it. For example:
struct FooVtable {
destroyer: fn (* mut ()),
size: usize,
alignment: usize,
method: fn (* const ()) -> String,
}
// u8:
fn call_method_in_u8 (x: * const ()) -> String {

// the compiler guarantees that this function is only called
// with `x` pointing to a u8
let byte: & u8 = unsafe {& * (x as * const u8)};
byte.metodo ()
}
static Foo_vtable_para_u8: FooVtable = FooVtable {

destroyer: / * compiler magic * /,
size: 1,
alignment: 1,
// conversion to a function pointer
method: call_method_in_u8 as fn (* const ()) -> String,
};
// String:
fn call_method_in_String (x: * const ()) -> String {

// the compiler guarantees that this function is only called
// with `x` pointing to a String
let string: & String = unsafe {& * (x as * const String)};
string.metodo ()
}
static Foo_vtable_para_String: FooVtable = FooVtable {

destroyer: / * compiler magic * /,
// values for a 64-bit computer, divide them in half for a 32-bit
size: 24,
alignment: 8,
method: call_method_in_String as fn (* const ()) -> String,

};
The destructor field in each vtable points to a function that will clear all
resources of the vtable type: for u8 it is trivial, but for String it will free up
memory. This is necessary to take over trait objects like Box <Foo> , which
need to clear both the Box mapping as well as the inner type when they get
out of scope. The size and alignment fields store the size of the deleted type,
and its alignment requirements; these are essentially unused at the moment
since the information is embedded in the shredder, but will be used in the
future, as the trait objects are progressively made more flexible.
Suppose we have some values that implement Foo . The explicit way of
constructing and using trait Foo objects may look a bit like (ignoring
inconsistencies between types: they are pointers anyway):
let a: String = "foo" .to_string ();
let x: u8 = 1;
// let b: & Foo = & a;

let b = TraitObject {
// store the data
data: & a,
// store the methods
vtable: & Foo_vtable_para_String
};
// let y: & Foo = x;

let y = TraitObject {
// store the data
data: & x,
// store the methods
vtable: & Foo_vtable_para_u8
};
// b.metodo ();
(b.vtable.metodo) (b.data);
// and.method ();
(y.vtable.metodo) (y.data);
Object Security
Not every trait can be used to create a trait object. For example, vectors
implement Clone , but if we try to create a trait object:
let v = vec! [1, 2, 3];
let o = & v as & Clone;
We get an error:
error: cannot convert to a trait object because trait `core :: clone ::
Clone` is not object-safe [E0038]
^~
note: the trait cannot require that `Self: Sized`
^~
The error says that Clone is not 'object-safe'. Only traits that are safe for
objects can be used in creating trait objects. A trait is safe for objects if both
conditions are true:
the trait does not require Self: Sized
all its methods are safe for objects
So what makes a method safe for objects? Each method should require that
Self: Sized or all of the following:
must not have any type parameters
you shouldn't use Self
Uff! As we can see, almost all of these rules talk about Self . A good intuition
would be "except for special circumstances, if your trait method uses Self , it
is not safe for objects."
Closures
Sometimes it is useful to wrap a function and its free variables for better
clarity and reusability. The free variables that can be used come from the
outside scope and are 'closed over' when used in the function. Hence the
name 'closure'. Rust provides a very good implementation , as we will see
below.
Syntax
The closures look like this:
let sum_one = | x: i32 | x + 1 ;
assert_eq! ( 2 , sum_one ( 1 ));

We create a link to variable, sum_one and assign it to a closure. The arguments
of the closure go between pipes ( | ), and the body is an expression, in this
case x + 1 . Remember that {} is an expression, so we can also have multi-
line closures:
let sum_two = | x | {
let mut result: i32 = x;
result + = 1 ;
result + = 1 ;
Outcome
};
assert_eq! ( 4 , sum_two ( 2 ));

You'll notice a couple of things about closures that are slightly different from
the regular functions defined with fn . The first thing is that we don't need to
write down the types of the arguments and the return values. We can:
let sum_one = | x: i32 | -> i32 {x + 1 };
assert_eq! ( 2 , sum_one ( 1 ));

But we don't need to. Why? Basically, it was implemented that way for
ergonomic reasons. While specifying the full type for named functions is
useful for things like documentation and type inference, the full signature in
closures is rarely documented since they are almost always anonymous, and
do not cause error-a type problems. -distance that inference in named
functions can cause.
The second syntax is similar, but somewhat different. I've added spaces here
for easy comparison:
fn sum_one_v1 (x: i32 ) -> i32 {x + 1 }
let sum_one_v2 = | x: i32 | -> i32 {x + 1 };
let sum_one_v3 = | x: i32 | x + 1 ;
Small differences, but they are similar.
Closures and its surroundings
The environment for a closure can include links to the scope variable that
wraps them in addition to the local variables and parameters. In this way:
let num = 5 ;
let sum_num = | x: i32 | x + num;
assert_eq! ( 10 , sum_num ( 5 ));

The closure suma_num refers to the let link in its scope: num . More
specifically, borrow the link. If we do something that conflicts with that link,
we would get an error like this:
let mut num = 5;
let y = & mut num;

Which fails with:
error: cannot borrow `num` as mutable because it is also borrowed as
immutable
let y = & mut num;
^ ~~
note: previous borrow of `num` occurs here due to use in closure; the
immutable
borrow prevents subsequent moves or mutable borrows of `num` until
the borrow
ends
let sum_num = | x | x + num;
^ ~~~~~~~~~~
fn main () {
let mut num = 5;
let sum_num = | x | x + num;
let y = & mut num;

}
^
A somewhat verbose error but just as useful! As it says, we cannot borrow a
mutable loan in num because the closure is already borrowing it. If we leave
the closure out of scope, then it is possible:
let mut num = 5 ;
{
} // sum_num goes out of scope, the loan ends here
let y = & mut num;

However, if your closure requires it, Rust will take belong and move the
environment. The following does not work:
let nums = vec! [1, 2, 3];
let toma_nums = || nums;
println! ("{:?}", nums);

We get this error:
note: `nums` moved into closure environment here because it has type
`[closure (()) -> collections :: vec :: Vec]`, which is non-copyable
let toma_nums = || nums;
^ ~~~~~~
Vec <T> has membership of its content, and that is why, when referring to it
within our closure, we have to take membership of nums . It is the same as if
we had provided nums as an argument to a function that would take
membership on it.
Closures move
We can force our closure to take belong to its environment with the move
keyword :
let num = 5 ;
let take_name_num = move | x: i32 | x + num;

Now, even when the move keyword is present, variables follow normal
semantics. In this case, 5 implements Copy , and consequently num_take takes
membership of a copy of num . So what is the difference?
let mut num = 5 ;
{
let mut sum_num = | x: i32 | num + = x;
sum_num ( 5 );
}
assert_eq! ( 10 , num);
In this case, our closure took a mutable reference to num , and when we call
sum_num , it mutes the underlying value, just as we expected. We also need to
declare sum_num as mut , since we are mutating its environment.
If we change it to a closure move , it is different:
let mut num = 5 ;
{
let mut sum_num = move | x: i32 | num + = x;
sum_num ( 5 );
}
assert_eq! ( 5 , num);
We get only 5 . Instead of taking a mutable loan on our number , we take
property on a copy.
Another way to think about closures move is: they provide the closure with its
own activation record. Without move , the closure can be associated with the
activation record that created it, while a closure move is self-contained.
Which means, for example, that you generally cannot return a non- move
closure from a function.
But before talking about receiving closures as parameters and using them as
return values, we should talk a little more about their implementation. Like a
Rust system programming language it gives you a ton of control over what
your code does, and closures are no different.
Implementation of Closures
Rust's implementation of closures is a little different than other languages. In
Rust, closures are effectively an alternate syntax for traits. Before continuing,
you will need to have read the chapter on traits as well as the chapter on trait
objects .
Have you already read them? Excellent.
The key to understanding how closures work is kind of weird: Using () to
call a function, like foo () , is an overload operator. Starting from this premise,
everything else fits. At Rust we make use of the traits system to overload
operators. Calling functions is no different. There are three traits that we can
overload:
# mod foo {
pub trait Fn <Args>: FnMut <Args> {
extern "rust-call" fn call (& self, args: Args) -> Self :: Output;
}
pub trait FnMut <Args>: FnOnce <Args> {

extern "rust-call" fn call_mut (& mut self, args: Args) -> Self ::
Output;
}
pub trait FnOnce <Args> {

type Output;
extern "rust-call" fn call_once (self, args: Args) -> Self :: Output;

}
#}
You will notice a few differences between these traits, but a big one is self :
Fn receives & self , FnMut takes & mut self and FnOnce receives self . The above
covers all three types of self through the usual method call syntax. But they
have been separated into three traits, rather than just one. This gives us great
control over the type of closures we can receive.
The syntax || {} is an alternate syntax for those three traits. Rust will generate
a struct for the environment, impl the appropriate trait, and then make use of
it.
Receiving closures as arguments

Now that we know that closures are traits, then we know how to accept and
return closures: just like any other trait!
The above also means that we can choose between static or dynamic
dispatch. First, let's create a function that receives something callable,
executes a call on it, and then returns the result:
fn call_with_one <F> (some_closure: F) -> i32
where F: Fn ( i32 ) -> i32 {
some_closure ( 1 )
}
let answer = call_with_one (| x | x + 2 );
assert_eq! ( 3 , answer);
We pass our closure, |x|x+2 , to call_with_one . calling_with_one does what it
suggests: calls the closure, giving it 1 as an argument.
Let's examine the call_with_one signature in more detail:
fn call_with_one <F> (some_closure: F) -> i32
# where F: Fn ( i32 ) -> i32 {
# some_closure ( 1 )}
We receive a parameter of type F . We also return an i32 . This part is not
interesting. The following is:
# fn call_with_one <F> (some_closure: F) -> i32
where F: Fn ( i32 ) -> i32 {
# some_closure ( 1 )}
Because Fn is a trait, we can limit our generic with it. In this case, our
closure receives an i32 and returns an i32 , that is why the generic limit we
use is Fn (i32) -> i32 .
There is another key point here: because we are limiting a generic with a trait,
the call will be monomorphized, and consequently, we will be doing static
dispatch in the closure. That is super cool. In many languages, closures are
inherently assigned from the mound, and will almost always involve dynamic
dispatch. In Rust we can assign the environment of our closures from the
stack, as well as dispatch the call statically. This occurs quite frequently with
iterators and their adapters, which receive closures as arguments.
Of course, if we want dynamic dispatch, we can have it too. A trait object, as
usual, handles this case:
fn call_with_one (some_closure: & Fn ( i32 ) -> i32 ) -> i32 {
some_closure ( 1 )
}
let answer = call_with_one (& | x | x + 2 );
We now receive a trait object, an & Fn . And we have to make a reference to
our closure when we pass it to call_with_one , that is why we use & || .
Function pointers and closures
A function pointer is a kind of closure that has no environment. As a
consequence, we can pass a function pointer to any function that receives a
closure as an argument:
fn call_with_one (some_closure: & Fn ( i32 ) -> i32 ) -> i32 {
some_closure ( 1 )
}
fn sum_one (i: i32 ) -> i32 {

i+1
}
let f = sum_one;
let answer = call_with_one (& f);
In the previous example we don't need the intermediate variable f strictly, the
function name also works:
let answer = call_with_one (& sum_one);
Returning closures
It is very common for functional styled code to return closures in various
situations. If you try to return a closure, you could make an error. At first it
may seem strange, but later we will understand. You would probably try to
return a closure from a function like this:
fn factory () -> (Fn (i32) -> i32) {
let num = 5;
| x | x + num
}
let f = factory ();
let answer = f (1);

assert_eq! (6, answer);
The above generates these long, but related errors:
error: the trait `core :: marker :: Sized` is not implemented for the type
`core :: ops :: Fn (i32) -> i32` [E0277]
fn factory () -> (Fn (i32) -> i32) {
^ ~~~~~~~~~~~~~~~
note: `core :: ops :: Fn (i32) -> i32` does not have a constant size known
at compile-time
fn factory () -> (Fn (i32) -> i32) {
^ ~~~~~~~~~~~~~~~
error: the trait `core :: marker :: Sized` is not implemented for the type`
core :: ops :: Fn (i32) -> i32` [E0277]
let f = factory ();
^
note: `core :: ops :: Fn (i32) -> i32` does not have a constant size known
at compile-time
let f = factory ();
^
To return something from a function, Rust needs to know the size of the
return type. But because Fn is a trait, it can be various things of various sizes:
many types can implement Fn . An easy way to size something is by taking a
reference to it, because references have a known size. Instead of the above we
can write:
fn factory () -> & (Fn (i32) -> i32) {
let num = 5;
| x | x + num
}
let f = factory ();
let answer = f (1);

But we get another error:
error: missing lifetime specifier [E0106]
fn factory () -> & (Fn (i32) -> i32) {
^ ~~~~~~~~~~~~~~~~
Well. Because we have a reference, we need to provide a lifetime. but our
factory () function does not receive any arguments and therefore the avoidance
of life times is not possible in this case. So what options do we have? Let's try
'static :
fn factory () -> & 'static (Fn (i32) -> i32) {

let num = 5;
| x | x + num
}
let f = factory ();
let answer = f (1);

But we get another error:
error: mismatched types:
expected `& 'static core :: ops :: Fn (i32) -> i32`,
found `[closure @: 7: 9: 7:20]`
(expected & -ptr,
found closure) [E0308]
| x | x + num
^ ~~~~~~~~~~
The error tells us that we don't have a & 'static Fn (i32) -> i32 , but a [closure @
<anon>: 7: 9: 7:20] . Wait a minute, what?
Because our closure generates its own struct for the environment as well as an
implementation for Fn , FnMut and FnOnce , these types are anonymous. They
only exist for this closure. This is why Rust displays them as closure @ <anon>
instead of some auto-generated name.
The error also talks about the return type being expected to be a reference,
but what we are trying to return is not. Furthermore, we cannot directly
assign an 'static' lifetime to an object. So we will take a different approach and
return a 'trait object' by wrapping the Fn in a Box . The following almost
works:
fn factory () -> Box i32> {
let num = 5;
Box :: new (| x | x + num)

}
# fn main () {
let f = factory ();
let answer = f (1);

#}
There is one last problem:
error: closure may outlive the current function, but it borrows `num`,
which is owned by the current function [E0373]
Box :: new (| x | x + num)
^ ~~~~~~~~~~
Well, as we discussed earlier, closures borrow their environment. And in this
case, our environment is based on a 5 assigned from the stack, the variable
num . Due to this, the loan has the lifetime of the activation record. If this
closure is returned, the function call could end, the activation record would
disappear and our closure would be capturing a junk memory environment!
With one last fix, we can make it work:
fn factory () -> Box < Fn ( i32 ) -> i32 > {

let num = 5 ;
Box :: new (move | x | x + num)

}
# fn main () {
let f = factory ();
let answer = f ( 1 );
#}
By making the internal closure a move Fn , we have created a new activation

record for our closure. By wrapping it with a Box , we have provided it with a
known size, allowing you to escape our activation record.

Rust Programming Language - A Comprehensive Beginner - S Guide To Rust

Uploaded by

Rust Programming Language - A Comprehensive Beginner - S Guide To Rust

Uploaded by

A comprehensive beginner's guide to Rust

WHY LEARN A NEW PROGRAMMING LANGUAGE?..............................................................12

CALLING CODING RUST FROM C.....................................................................................197

TRAIT LIMITS FOR GENERIC FUNCTIONS............................................................................289

Why learn a new Programming Language?

First, why learn a new programming language? It is an investment of time

Where Rust Shines

Rust is a statically and strongly typed systems programming language.

The unifying principles behind Rust are:

- strictly enforcing safe borrowing of data

There is a fast-growing ecosystem of available libraries through Cargo but

rustc $1.rs && ./$1

$ curl https://sh.rustup.rs -sSf | sh

Earlier we mentioned that 'membership' is a new key concept in Rust. In Rust

Let's add another line to our example:

We have introduced another variable, and . In this case, y is a 'reference' to

let y = & x [ 0];

is a method in vectors that adds an element to the end of the vector.

let y = x [ 0 ] .clone ();

If we really want a reference, we need another option: make sure our

This membership concept is not only good at preventing dangling pointers,

With that said, let's create a directory in our project directory.

Success! Now let's see what has happened in detail.

The following is this line:

println! ( "Hello, world!" );

Then "Hello world!" it is a character string. Character strings are a surprisingly

Finally, the line ends with a semicolon ( ; ). Rust is an expression-oriented

$. / main # or main.exe in Windows

If you're coming from a dynamic language like Ruby, Python, or Javascript,

Cargo manages three things: compiling your code, downloading the

Here is our configuration file:

Put this inside:

This file is in TOML format . Let us explain the same:

TOML's goal is to be a minimal configuration format that is easy to read due

TOML is very similar to INI, but with some extra niceties.

To start a new project with Cargo, we use cargo new :

$ cargo new hello_world –bin

We are passing --bin because we are creating a binary program: if we were

Let's take a look at what Cargo has generated for us:

Here is the content of src / main.rs :

Take a look at the generated Cargo.toml :

Processing a Riddle Attempt

use std :: io;

println! ("Please enter your hunch.");

let mut hunch = String :: new ();

io :: stdin (). read_line (& mut hunch)

println! ("Your hunch was: {}", hunch);

use std :: io;

println! ("Guess the number!");

let mut hunch = String :: new ();

let foo = bar;

let foo = 5 ; // immutable.

is a type of character string, provided by the standard library. A String is

The :: new () syntax uses :: because it is an 'associated function' of a particular

io :: stdin (). read_line (& mut hunch)

This particular function returns a handle to the standard input of your

.read_line (& mut hunch)

Remember when we created hunch ? We said it was mutable. However

Because read_line () accepts a mutable reference to a character string. Your job

The purpose of those Result is to encode error handling information. Values

We only have one line left from this first example:

println! ("Your hunch was: {}", hunch);

println! ( "xyy: {} y {}" , x, y);

Generating a secret number

The [dependencies] section of Cargo.toml is like the [package] section : everything

Lots of more output! Now that we have an external dependency, Cargo

If we run cargo build , we will get a different output:

Let us now use rand . Here is our next step:

extern crate rand;

use std :: io;

let secret_number = rand :: thread_rng (). gen_range (1, 101);

println! ("The secret number is: {}", secret_number);

println! ("Please enter your hunch.");

let mut hunch = String :: new ();

io :: stdin (). read_line (& mut hunch)