<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Tutorial: Guessing Game - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="src/theme/first-edition.css">
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="README.html">Introduction</a></li><li><a href="getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><a href="guessing-game.html" class="active"><strong aria-hidden="true">2.</strong> Tutorial: Guessing Game</a></li><li><a href="syntax-and-semantics.html"><strong aria-hidden="true">3.</strong> Syntax and Semantics</a></li><li><ol class="section"><li><a href="variable-bindings.html"><strong aria-hidden="true">3.1.</strong> Variable Bindings</a></li><li><a href="functions.html"><strong aria-hidden="true">3.2.</strong> Functions</a></li><li><a href="primitive-types.html"><strong aria-hidden="true">3.3.</strong> Primitive Types</a></li><li><a href="comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li><a href="if.html"><strong aria-hidden="true">3.5.</strong> if</a></li><li><a href="loops.html"><strong aria-hidden="true">3.6.</strong> Loops</a></li><li><a href="vectors.html"><strong aria-hidden="true">3.7.</strong> Vectors</a></li><li><a href="ownership.html"><strong aria-hidden="true">3.8.</strong> Ownership</a></li><li><a href="references-and-borrowing.html"><strong aria-hidden="true">3.9.</strong> References and Borrowing</a></li><li><a href="lifetimes.html"><strong aria-hidden="true">3.10.</strong> Lifetimes</a></li><li><a href="mutability.html"><strong aria-hidden="true">3.11.</strong> Mutability</a></li><li><a href="structs.html"><strong aria-hidden="true">3.12.</strong> Structs</a></li><li><a href="enums.html"><strong aria-hidden="true">3.13.</strong> Enums</a></li><li><a href="match.html"><strong aria-hidden="true">3.14.</strong> Match</a></li><li><a href="patterns.html"><strong aria-hidden="true">3.15.</strong> Patterns</a></li><li><a href="method-syntax.html"><strong aria-hidden="true">3.16.</strong> Method Syntax</a></li><li><a href="strings.html"><strong aria-hidden="true">3.17.</strong> Strings</a></li><li><a href="generics.html"><strong aria-hidden="true">3.18.</strong> Generics</a></li><li><a href="traits.html"><strong aria-hidden="true">3.19.</strong> Traits</a></li><li><a href="drop.html"><strong aria-hidden="true">3.20.</strong> Drop</a></li><li><a href="if-let.html"><strong aria-hidden="true">3.21.</strong> if let</a></li><li><a href="trait-objects.html"><strong aria-hidden="true">3.22.</strong> Trait Objects</a></li><li><a href="closures.html"><strong aria-hidden="true">3.23.</strong> Closures</a></li><li><a href="ufcs.html"><strong aria-hidden="true">3.24.</strong> Universal Function Call Syntax</a></li><li><a href="crates-and-modules.html"><strong aria-hidden="true">3.25.</strong> Crates and Modules</a></li><li><a href="const-and-static.html"><strong aria-hidden="true">3.26.</strong> const and static</a></li><li><a href="attributes.html"><strong aria-hidden="true">3.27.</strong> Attributes</a></li><li><a href="type-aliases.html"><strong aria-hidden="true">3.28.</strong> type aliases</a></li><li><a href="casting-between-types.html"><strong aria-hidden="true">3.29.</strong> Casting between types</a></li><li><a href="associated-types.html"><strong aria-hidden="true">3.30.</strong> Associated Types</a></li><li><a href="unsized-types.html"><strong aria-hidden="true">3.31.</strong> Unsized Types</a></li><li><a href="operators-and-overloading.html"><strong aria-hidden="true">3.32.</strong> Operators and Overloading</a></li><li><a href="deref-coercions.html"><strong aria-hidden="true">3.33.</strong> Deref coercions</a></li><li><a href="macros.html"><strong aria-hidden="true">3.34.</strong> Macros</a></li><li><a href="raw-pointers.html"><strong aria-hidden="true">3.35.</strong> Raw Pointers</a></li><li><a href="unsafe.html"><strong aria-hidden="true">3.36.</strong> unsafe</a></li></ol></li><li><a href="effective-rust.html"><strong aria-hidden="true">4.</strong> Effective Rust</a></li><li><ol class="section"><li><a href="the-stack-and-the-heap.html"><strong aria-hidden="true">4.1.</strong> The Stack and the Heap</a></li><li><a href="testing.html"><strong aria-hidden="true">4.2.</strong> Testing</a></li><li><a href="conditional-compilation.html"><strong aria-hidden="true">4.3.</strong> Conditional Compilation</a></li><li><a href="documentation.html"><strong aria-hidden="true">4.4.</strong> Documentation</a></li><li><a href="iterators.html"><strong aria-hidden="true">4.5.</strong> Iterators</a></li><li><a href="concurrency.html"><strong aria-hidden="true">4.6.</strong> Concurrency</a></li><li><a href="error-handling.html"><strong aria-hidden="true">4.7.</strong> Error Handling</a></li><li><a href="choosing-your-guarantees.html"><strong aria-hidden="true">4.8.</strong> Choosing your Guarantees</a></li><li><a href="ffi.html"><strong aria-hidden="true">4.9.</strong> FFI</a></li><li><a href="borrow-and-asref.html"><strong aria-hidden="true">4.10.</strong> Borrow and AsRef</a></li><li><a href="release-channels.html"><strong aria-hidden="true">4.11.</strong> Release Channels</a></li><li><a href="using-rust-without-the-standard-library.html"><strong aria-hidden="true">4.12.</strong> Using Rust without the standard library</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">4.13.</strong> Procedural Macros (and custom derive)</a></li></ol></li><li><a href="glossary.html"><strong aria-hidden="true">5.</strong> Glossary</a></li><li><a href="syntax-index.html"><strong aria-hidden="true">6.</strong> Syntax Index</a></li><li><a href="bibliography.html"><strong aria-hidden="true">7.</strong> Bibliography</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="draft-warning" class="warning">
<span class="message">You are reading an <strong>outdated</strong> edition of TRPL. For more, go <a href="../index.html">here</a>.</span>
<button type="button" id="hide-draft-warning" title="Hide draft warning" class="button">
<i class="fa fa-times"></i>
</button>
</div>
<!-- Hide / unhide warning before it is displayed -->
<script type="text/javascript">
var warning = localStorage.getItem('trpl-first-edition-draft-warning');
if (warning === 'hidden') {
Array
.from(document.querySelectorAll('#page-wrapper'))
.forEach(function(block) { block.classList.remove('has-warning'); });
var elem = document.getElementById("draft-warning");
elem.parentNode.removeChild(elem);
}
document.addEventListener("DOMContentLoaded", function(event) {
document.getElementById("hide-draft-warning").addEventListener("click", function(e) {
var elem = document.getElementById("draft-warning");
elem.parentNode.removeChild(elem);
localStorage.setItem('trpl-first-edition-draft-warning', 'hidden');
});
});
</script>
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="guessing-game.html#guessing-game" id="guessing-game"><h1>Guessing Game</h1></a>
<p>Let’s learn some Rust! For our first project, we’ll implement a classic
beginner programming problem: the guessing game. Here’s how it works: Our
program will generate a random integer between one and a hundred. It will then
prompt us to enter a guess. Upon entering our guess, it will tell us if we’re
too low or too high. Once we guess correctly, it will congratulate us. Sounds
good?</p>
<p>Along the way, we’ll learn a little bit about Rust. The next chapter, ‘Syntax
and Semantics’, will dive deeper into each part.</p>
<a class="header" href="guessing-game.html#set-up" id="set-up"><h1>Set up</h1></a>
<p>Let’s set up a new project. Go to your projects directory. Remember how we had
to create our directory structure and a <code>Cargo.toml</code> for <code>hello_world</code>? Cargo
has a command that does that for us. Let’s give it a shot:</p>
<pre><code class="language-bash">$ cd ~/projects
$ cargo new guessing_game --bin
Created binary (application) `guessing_game` project
$ cd guessing_game
</code></pre>
<p>We pass the name of our project to <code>cargo new</code>, and then the <code>--bin</code> flag,
since we’re making a binary, rather than a library.</p>
<p>Check out the generated <code>Cargo.toml</code>:</p>
<pre><code class="language-toml">[package]
name = "guessing_game"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
</code></pre>
<p>Cargo gets this information from your environment. If it’s not correct, go ahead
and fix that.</p>
<p>Finally, Cargo generated a ‘Hello, world!’ for us. Check out <code>src/main.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
println!("Hello, world!");
}
</code></pre></pre>
<p>Let’s try compiling what Cargo gave us:</p>
<pre><code class="language-{bash}">$ cargo build
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.53 secs
</code></pre>
<p>Excellent! Open up your <code>src/main.rs</code> again. We’ll be writing all of
our code in this file.</p>
<p>Remember the <code>run</code> command from last chapter? Try it out again here:</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
Running `target/debug/guessing_game`
Hello, world!
</code></pre>
<p>Great! Our game is just the kind of project <code>run</code> is good for: we need
to quickly test each iteration before moving on to the next one.</p>
<a class="header" href="guessing-game.html#processing-a-guess" id="processing-a-guess"><h1>Processing a Guess</h1></a>
<p>Let’s get to it! The first thing we need to do for our guessing game is
allow our player to input a guess. Put this in your <code>src/main.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust no_run">use std::io;
fn main() {
println!("Guess the number!");
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
println!("You guessed: {}", guess);
}
</code></pre></pre>
<p>There’s a lot here! Let’s go over it, bit by bit.</p>
<pre><code class="language-rust ignore">use std::io;
</code></pre>
<p>We’ll need to take user input, and then print the result as output. As such, we
need the <code>io</code> library from the standard library. Rust only imports a few things
by default into every program, <a href="../../std/prelude/index.html">the ‘prelude’</a>. If it’s not in the
prelude, you’ll have to <code>use</code> it directly. There is also a second ‘prelude’, the
<a href="../../std/io/prelude/index.html"><code>io</code> prelude</a>, which serves a similar function: you import it, and it
imports a number of useful, <code>io</code>-related things.</p>
<pre><code class="language-rust ignore">fn main() {
</code></pre>
<p>As you’ve seen before, the <code>main()</code> function is the entry point into your
program. The <code>fn</code> syntax declares a new function, the <code>()</code>s indicate that
there are no arguments, and <code>{</code> starts the body of the function. Because
we didn’t include a return type, it’s assumed to be <code>()</code>, an empty
<a href="primitive-types.html#tuples">tuple</a>.</p>
<pre><code class="language-rust ignore"> println!("Guess the number!");
println!("Please input your guess.");
</code></pre>
<p>We previously learned that <code>println!()</code> is a <a href="macros.html">macro</a> that
prints a <a href="strings.html">string</a> to the screen.</p>
<pre><code class="language-rust ignore"> let mut guess = String::new();
</code></pre>
<p>Now we’re getting interesting! There’s a lot going on in this little line.
The first thing to notice is that this is a <a href="variable-bindings.html">let statement</a>, which is
used to create ‘variable bindings’. They take this form:</p>
<pre><code class="language-rust ignore">let foo = bar;
</code></pre>
<p>This will create a new binding named <code>foo</code>, and bind it to the value <code>bar</code>. In
many languages, this is called a ‘variable’, but Rust’s variable bindings have
a few tricks up their sleeves.</p>
<p>For example, they’re <a href="mutability.html">immutable</a> by default. That’s why our example
uses <code>mut</code>: it makes a binding mutable, rather than immutable. <code>let</code> doesn’t
take a name on the left hand side of the assignment, it actually accepts a
‘<a href="patterns.html">pattern</a>’. We’ll use patterns later. It’s easy enough
to use for now:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let foo = 5; // `foo` is immutable.
let mut bar = 5; // `bar` is mutable.
#}</code></pre></pre>
<p>Oh, and <code>//</code> will start a comment, until the end of the line. Rust ignores
everything in <a href="comments.html">comments</a>.</p>
<p>So now we know that <code>let mut guess</code> will introduce a mutable binding named
<code>guess</code>, but we have to look at the other side of the <code>=</code> for what it’s
bound to: <code>String::new()</code>.</p>
<p><code>String</code> is a string type, provided by the standard library. A
<a href="../../std/string/struct.String.html"><code>String</code></a> is a growable, UTF-8 encoded bit of text.</p>
<p>The <code>::new()</code> syntax uses <code>::</code> because this is an ‘associated function’ of
a particular type. That is to say, it’s associated with <code>String</code> itself,
rather than a particular instance of a <code>String</code>. Some languages call this a
‘static method’.</p>
<p>This function is named <code>new()</code>, because it creates a new, empty <code>String</code>.
You’ll find a <code>new()</code> function on many types, as it’s a common name for making
a new value of some kind.</p>
<p>Let’s move forward:</p>
<pre><code class="language-rust ignore"> io::stdin().read_line(&mut guess)
.expect("Failed to read line");
</code></pre>
<p>That’s a lot more! Let’s go bit-by-bit. The first line has two parts. Here’s
the first:</p>
<pre><code class="language-rust ignore">io::stdin()
</code></pre>
<p>Remember how we <code>use</code>d <code>std::io</code> on the first line of the program? We’re now
calling an associated function on it. If we didn’t <code>use std::io</code>, we could
have written this line as <code>std::io::stdin()</code>.</p>
<p>This particular function returns a handle to the standard input for your
terminal. More specifically, a <a href="../../std/io/struct.Stdin.html">std::io::Stdin</a>.</p>
<p>The next part will use this handle to get input from the user:</p>
<pre><code class="language-rust ignore">.read_line(&mut guess)
</code></pre>
<p>Here, we call the <a href="../../std/io/struct.Stdin.html#method.read_line"><code>read_line</code></a> method on our handle.
<a href="method-syntax.html">Methods</a> are like associated functions, but are only available on a
particular instance of a type, rather than the type itself. We’re also passing
one argument to <code>read_line()</code>: <code>&mut guess</code>.</p>
<p>Remember how we bound <code>guess</code> above? We said it was mutable. However,
<code>read_line</code> doesn’t take a <code>String</code> as an argument: it takes a <code>&mut String</code>.
Rust has a feature called ‘<a href="references-and-borrowing.html">references</a>’, which allows you to have
multiple references to one piece of data, which can reduce copying. References
are a complex feature, as one of Rust’s major selling points is how safe and
easy it is to use references. We don’t need to know a lot of those details to
finish our program right now, though. For now, all we need to know is that
like <code>let</code> bindings, references are immutable by default. Hence, we need to
write <code>&mut guess</code>, rather than <code>&guess</code>.</p>
<p>Why does <code>read_line()</code> take a mutable reference to a string? Its job is
to take what the user types into standard input, and place that into a
string. So it takes that string as an argument, and in order to add
the input, it needs to be mutable.</p>
<p>But we’re not quite done with this line of code, though. While it’s
a single line of text, it’s only the first part of the single logical line of
code:</p>
<pre><code class="language-rust ignore"> .expect("Failed to read line");
</code></pre>
<p>When you call a method with the <code>.foo()</code> syntax, you may introduce a newline
and other whitespace. This helps you split up long lines. We <em>could</em> have
done:</p>
<pre><code class="language-rust ignore"> io::stdin().read_line(&mut guess).expect("Failed to read line");
</code></pre>
<p>But that gets hard to read. So we’ve split it up, two lines for two method
calls. We already talked about <code>read_line()</code>, but what about <code>expect()</code>? Well,
we already mentioned that <code>read_line()</code> puts what the user types into the <code>&mut String</code> we pass it. But it also returns a value: in this case, an
<a href="../../std/io/type.Result.html"><code>io::Result</code></a>. Rust has a number of types named <code>Result</code> in its
standard library: a generic <a href="../../std/result/enum.Result.html"><code>Result</code></a>, and then specific versions for
sub-libraries, like <code>io::Result</code>.</p>
<p>The purpose of these <code>Result</code> types is to encode error handling information.
Values of the <code>Result</code> type, like any type, have methods defined on them. In
this case, <code>io::Result</code> has an <a href="../../std/result/enum.Result.html#method.expect"><code>expect()</code> method</a> that takes a value
it’s called on, and if it isn’t a successful one, <a href="error-handling.html"><code>panic!</code></a>s with a
message you passed it. A <code>panic!</code> like this will cause our program to crash,
displaying the message.</p>
<p>If we do not call <code>expect()</code>, our program will compile, but
we’ll get a warning:</p>
<pre><code class="language-bash">$ cargo build
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
warning: unused result which must be used, #[warn(unused_must_use)] on by default
--> src/main.rs:10:5
|
10 | io::stdin().read_line(&mut guess);
| ^
Finished debug [unoptimized + debuginfo] target(s) in 0.42 secs
</code></pre>
<p>Rust warns us that we haven’t used the <code>Result</code> value. This warning comes from
a special annotation that <code>io::Result</code> has. Rust is trying to tell you that
you haven’t handled a possible error. The right way to suppress the error is
to actually write error handling. Luckily, if we want to crash if there’s
a problem, we can use <code>expect()</code>. If we can recover from the
error somehow, we’d do something else, but we’ll save that for a future
project.</p>
<p>There’s only one line of this first example left:</p>
<pre><code class="language-rust ignore"> println!("You guessed: {}", guess);
}
</code></pre>
<p>This prints out the string we saved our input in. The <code>{}</code>s are a placeholder,
and so we pass it <code>guess</code> as an argument. If we had multiple <code>{}</code>s, we would
pass multiple arguments:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let x = 5;
let y = 10;
println!("x and y: {} and {}", x, y);
#}</code></pre></pre>
<p>Easy.</p>
<p>Anyway, that’s the tour. We can run what we have with <code>cargo run</code>:</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.44 secs
Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6
</code></pre>
<p>All right! Our first part is done: we can get input from the keyboard,
and then print it back out.</p>
<a class="header" href="guessing-game.html#generating-a-secret-number" id="generating-a-secret-number"><h1>Generating a secret number</h1></a>
<p>Next, we need to generate a secret number. Rust does not yet include random
number functionality in its standard library. The Rust team does, however,
provide a <a href="https://crates.io/crates/rand"><code>rand</code> crate</a>. A ‘crate’ is a package of Rust code.
We’ve been building a ‘binary crate’, which is an executable. <code>rand</code> is a
‘library crate’, which contains code that’s intended to be used with other
programs.</p>
<p>Using external crates is where Cargo really shines. Before we can write
the code using <code>rand</code>, we need to modify our <code>Cargo.toml</code>. Open it up, and
add these few lines at the bottom:</p>
<pre><code class="language-toml">[dependencies]
rand = "0.3.0"
</code></pre>
<p>The <code>[dependencies]</code> section of <code>Cargo.toml</code> is like the <code>[package]</code> section:
everything that follows it is part of it, until the next section starts.
Cargo uses the dependencies section to know what dependencies on external
crates you have, and what versions you require. In this case, we’ve specified version <code>0.3.0</code>,
which Cargo understands to be any release that’s compatible with this specific version.
Cargo understands <a href="http://semver.org">Semantic Versioning</a>, which is a standard for writing version
numbers. A bare number like above is actually shorthand for <code>^0.3.0</code>,
meaning "anything compatible with 0.3.0".
If we wanted to use only <code>0.3.0</code> exactly, we could say <code>rand = "=0.3.0"</code>
(note the two equal signs).
We could also use a range of versions.
<a href="http://doc.crates.io/specifying-dependencies.html">Cargo’s documentation</a> contains more details.</p>
<p>Now, without changing any of our code, let’s build our project:</p>
<pre><code class="language-bash">$ cargo build
Updating registry `https://github.com/rust-lang/crates.io-index`
Downloading rand v0.3.14
Downloading libc v0.2.17
Compiling libc v0.2.17
Compiling rand v0.3.14
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 5.88 secs
</code></pre>
<p>(You may see different versions, of course.)</p>
<p>Lots of new output! Now that we have an external dependency, Cargo fetches the
latest versions of everything from the registry, which is a copy of data from
<a href="https://crates.io">Crates.io</a>. Crates.io is where people in the Rust ecosystem
post their open source Rust projects for others to use.</p>
<p>After updating the registry, Cargo checks our <code>[dependencies]</code> and downloads
any we don’t have yet. In this case, while we only said we wanted to depend on
<code>rand</code>, we’ve also grabbed a copy of <code>libc</code>. This is because <code>rand</code> depends on
<code>libc</code> to work. After downloading them, it compiles them, and then compiles
our project.</p>
<p>If we run <code>cargo build</code> again, we’ll get different output:</p>
<pre><code class="language-bash">$ cargo build
Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
</code></pre>
<p>That’s right, nothing was done! Cargo knows that our project has been built, and that
all of its dependencies are built, and so there’s no reason to do all that
stuff. With nothing to do, it simply exits. If we open up <code>src/main.rs</code> again,
make a trivial change, and then save it again, we’ll only see two lines:</p>
<pre><code class="language-bash">$ cargo build
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.45 secs
</code></pre>
<p>So, we told Cargo we wanted any <code>0.3.x</code> version of <code>rand</code>, and so it fetched the latest
version at the time this was written, <code>v0.3.14</code>. But what happens when next
week, version <code>v0.3.15</code> comes out, with an important bugfix? While getting
bugfixes is important, what if <code>0.3.15</code> contains a regression that breaks our
code?</p>
<p>The answer to this problem is the <code>Cargo.lock</code> file you’ll now find in your
project directory. When you build your project for the first time, Cargo
figures out all of the versions that fit your criteria, and then writes them
to the <code>Cargo.lock</code> file. When you build your project in the future, Cargo
will see that the <code>Cargo.lock</code> file exists, and then use that specific version
rather than do all the work of figuring out versions again. This lets you
have a repeatable build automatically. In other words, we’ll stay at <code>0.3.14</code>
until we explicitly upgrade, and so will anyone who we share our code with,
thanks to the lock file.</p>
<p>What about when we <em>do</em> want to use <code>v0.3.15</code>? Cargo has another command,
<code>update</code>, which says ‘ignore the lock, figure out all the latest versions that
fit what we’ve specified. If that works, write those versions out to the lock
file’. But, by default, Cargo will only look for versions larger than <code>0.3.0</code>
and smaller than <code>0.4.0</code>. If we want to move to <code>0.4.x</code>, we’d have to update
the <code>Cargo.toml</code> directly. When we do, the next time we <code>cargo build</code>, Cargo
will update the index and re-evaluate our <code>rand</code> requirements.</p>
<p>There’s a lot more to say about <a href="http://doc.crates.io">Cargo</a> and <a href="http://doc.crates.io/crates-io.html">its
ecosystem</a>, but for now, that’s all we need to know. Cargo makes
it really easy to re-use libraries, and so Rustaceans tend to write smaller
projects which are assembled out of a number of sub-packages.</p>
<p>Let’s get on to actually <em>using</em> <code>rand</code>. Here’s our next step:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
println!("You guessed: {}", guess);
}
</code></pre>
<p>The first thing we’ve done is change the first line. It now says
<code>extern crate rand</code>. Because we declared <code>rand</code> in our <code>[dependencies]</code>, we
can use <code>extern crate</code> to let Rust know we’ll be making use of it. This also
does the equivalent of a <code>use rand;</code> as well, so we can make use of anything
in the <code>rand</code> crate by prefixing it with <code>rand::</code>.</p>
<p>Next, we added another <code>use</code> line: <code>use rand::Rng</code>. We’re going to use a
method in a moment, and it requires that <code>Rng</code> be in scope to work. The basic
idea is this: methods are defined on something called ‘traits’, and for the
method to work, it needs the trait to be in scope. For more about the
details, read the <a href="traits.html">traits</a> section.</p>
<p>There are two other lines we added, in the middle:</p>
<pre><code class="language-rust ignore"> let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
</code></pre>
<p>We use the <code>rand::thread_rng()</code> function to get a copy of the random number
generator, which is local to the particular <a href="concurrency.html">thread</a> of execution
we’re in. Because we <code>use rand::Rng</code>’d above, it has a <code>gen_range()</code> method
available. This method takes two arguments, and generates a number between
them. It’s inclusive on the lower bound, but exclusive on the upper bound,
so we need <code>1</code> and <code>101</code> to get a number ranging from one to a hundred.</p>
<p>The second line prints out the secret number. This is useful while
we’re developing our program, so we can easily test it out. But we’ll be
deleting it for the final version. It’s not much of a game if it prints out
the answer when you start it up!</p>
<p>Try running our new program a few times:</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.55 secs
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4
$ cargo run
Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5
</code></pre>
<p>Great! Next up: comparing our guess to the secret number.</p>
<a class="header" href="guessing-game.html#comparing-guesses" id="comparing-guesses"><h1>Comparing guesses</h1></a>
<p>Now that we’ve got user input, let’s compare our guess to the secret number.
Here’s our next step, though it doesn’t quite compile yet:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
}
</code></pre>
<p>A few new bits here. The first is another <code>use</code>. We bring a type called
<code>std::cmp::Ordering</code> into scope. Then, five new lines at the bottom that use
it:</p>
<pre><code class="language-rust ignore">match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
</code></pre>
<p>The <code>cmp()</code> method can be called on anything that can be compared, and it
takes a reference to the thing you want to compare it to. It returns the
<code>Ordering</code> type we <code>use</code>d earlier. We use a <a href="match.html"><code>match</code></a> statement to
determine exactly what kind of <code>Ordering</code> it is. <code>Ordering</code> is an
<a href="enums.html"><code>enum</code></a>, short for ‘enumeration’, which looks like this:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
enum Foo {
Bar,
Baz,
}
#}</code></pre></pre>
<p>With this definition, anything of type <code>Foo</code> can be either a
<code>Foo::Bar</code> or a <code>Foo::Baz</code>. We use the <code>::</code> to indicate the
namespace for a particular <code>enum</code> variant.</p>
<p>The <a href="../../std/cmp/enum.Ordering.html"><code>Ordering</code></a> <code>enum</code> has three possible variants: <code>Less</code>, <code>Equal</code>,
and <code>Greater</code>. The <code>match</code> statement takes a value of a type, and lets you
create an ‘arm’ for each possible value. Since we have three types of
<code>Ordering</code>, we have three arms:</p>
<pre><code class="language-rust ignore">match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
</code></pre>
<p>If it’s <code>Less</code>, we print <code>Too small!</code>, if it’s <code>Greater</code>, <code>Too big!</code>, and if
<code>Equal</code>, <code>You win!</code>. <code>match</code> is really useful, and is used often in Rust.</p>
<p>I did mention that this won’t quite compile yet, though. Let’s try it:</p>
<pre><code class="language-bash">$ cargo build
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
error[E0308]: mismatched types
--> src/main.rs:23:21
|
23 | match guess.cmp(&secret_number) {
| ^^^^^^^^^^^^^^ expected struct `std::string::String`, found integral variable
|
= note: expected type `&std::string::String`
= note: found type `&{integer}`
error: aborting due to previous error
error: Could not compile `guessing_game`.
To learn more, run the command again with --verbose.
</code></pre>
<p>Whew! This is a big error. The core of it is that we have ‘mismatched types’.
Rust has a strong, static type system. However, it also has type inference.
When we wrote <code>let guess = String::new()</code>, Rust was able to infer that <code>guess</code>
should be a <code>String</code>, and so it doesn’t make us write out the type. And with
our <code>secret_number</code>, there are a number of types which can have a value
between one and a hundred: <code>i32</code>, a thirty-two-bit number, or <code>u32</code>, an
unsigned thirty-two-bit number, or <code>i64</code>, a sixty-four-bit number or others.
So far, that hasn’t mattered, and so Rust defaults to an <code>i32</code>. However, here,
Rust doesn’t know how to compare the <code>guess</code> and the <code>secret_number</code>. They
need to be the same type. Ultimately, we want to convert the <code>String</code> we
read as input into a real number type, for comparison. We can do that
with two more lines. Here’s our new program:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = guess.trim().parse()
.expect("Please type a number!");
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
}
</code></pre>
<p>The new two lines:</p>
<pre><code class="language-rust ignore"> let guess: u32 = guess.trim().parse()
.expect("Please type a number!");
</code></pre>
<p>Wait a minute, I thought we already had a <code>guess</code>? We do, but Rust allows us
to ‘shadow’ the previous <code>guess</code> with a new one. This is often used in this
exact situation, where <code>guess</code> starts as a <code>String</code>, but we want to convert it
to an <code>u32</code>. Shadowing lets us re-use the <code>guess</code> name, rather than forcing us
to come up with two unique names like <code>guess_str</code> and <code>guess</code>, or something
else.</p>
<p>We bind <code>guess</code> to an expression that looks like something we wrote earlier:</p>
<pre><code class="language-rust ignore">guess.trim().parse()
</code></pre>
<p>Here, <code>guess</code> refers to the old <code>guess</code>, the one that was a <code>String</code> with our
input in it. The <code>trim()</code> method on <code>String</code>s will eliminate any white space at
the beginning and end of our string. This is important, as we had to press the
‘return’ key to satisfy <code>read_line()</code>. This means that if we type <code>5</code> and hit
return, <code>guess</code> looks like this: <code>5\n</code>. The <code>\n</code> represents ‘newline’, the
enter key. <code>trim()</code> gets rid of this, leaving our string with only the <code>5</code>. The
<a href="../../std/primitive.str.html#method.parse"><code>parse()</code> method on strings</a> parses a string into some kind of number.
Since it can parse a variety of numbers, we need to give Rust a hint as to the
exact type of number we want. Hence, <code>let guess: u32</code>. The colon (<code>:</code>) after
<code>guess</code> tells Rust we’re going to annotate its type. <code>u32</code> is an unsigned,
thirty-two bit integer. Rust has <a href="primitive-types.html#numeric-types">a number of built-in number types</a>,
but we’ve chosen <code>u32</code>. It’s a good default choice for a small positive number.</p>
<p>Just like <code>read_line()</code>, our call to <code>parse()</code> could cause an error. What if
our string contained <code>A👍%</code>? There’d be no way to convert that to a number. As
such, we’ll do the same thing we did with <code>read_line()</code>: use the <code>expect()</code>
method to crash if there’s an error.</p>
<p>Let’s try our program out!</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.57 secs
Running `target/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
76
You guessed: 76
Too big!
</code></pre>
<p>Nice! You can see I even added spaces before my guess, and it still figured
out that I guessed 76. Run the program a few times, and verify that guessing
the number works, as well as guessing a number too small.</p>
<p>Now we’ve got most of the game working, but we can only make one guess. Let’s
change that by adding loops!</p>
<a class="header" href="guessing-game.html#looping" id="looping"><h1>Looping</h1></a>
<p>The <code>loop</code> keyword gives us an infinite loop. Let’s add that in:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
loop {
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = guess.trim().parse()
.expect("Please type a number!");
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => println!("You win!"),
}
}
}
</code></pre>
<p>And try it out. But wait, didn’t we just add an infinite loop? Yup. Remember
our discussion about <code>parse()</code>? If we give a non-number answer, we’ll <code>panic!</code>
and quit. Observe:</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.58 secs
Running `target/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit
thread 'main' panicked at 'Please type a number!'
</code></pre>
<p>Ha! <code>quit</code> actually quits. As does any other non-number input. Well, this is
suboptimal to say the least. First, let’s actually quit when you win the game:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
loop {
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = guess.trim().parse()
.expect("Please type a number!");
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => {
println!("You win!");
break;
}
}
}
}
</code></pre>
<p>By adding the <code>break</code> line after the <code>You win!</code>, we’ll exit the loop when we
win. Exiting the loop also means exiting the program, since it’s the last
thing in <code>main()</code>. We have only one more tweak to make: when someone inputs a
non-number, we don’t want to quit, we want to ignore it. We can do that
like this:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
println!("The secret number is: {}", secret_number);
loop {
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = match guess.trim().parse() {
Ok(num) => num,
Err(_) => continue,
};
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => {
println!("You win!");
break;
}
}
}
}
</code></pre>
<p>These are the lines that changed:</p>
<pre><code class="language-rust ignore">let guess: u32 = match guess.trim().parse() {
Ok(num) => num,
Err(_) => continue,
};
</code></pre>
<p>This is how you generally move from ‘crash on error’ to ‘actually handle the
error’, by switching from <code>expect()</code> to a <code>match</code> statement. A <code>Result</code> is
returned by <code>parse()</code>, this is an <code>enum</code> like <code>Ordering</code>, but in this case,
each variant has some data associated with it: <code>Ok</code> is a success, and <code>Err</code> is a
failure. Each contains more information: the successfully parsed integer, or an
error type. In this case, we <code>match</code> on <code>Ok(num)</code>, which sets the name <code>num</code> to
the unwrapped <code>Ok</code> value (the integer), and then we return it on the
right-hand side. In the <code>Err</code> case, we don’t care what kind of error it is, so
we just use the catch all <code>_</code> instead of a name. This catches everything that
isn't <code>Ok</code>, and <code>continue</code> lets us move to the next iteration of the loop; in
effect, this enables us to ignore all errors and continue with our program.</p>
<p>Now we should be good! Let’s try:</p>
<pre><code class="language-bash">$ cargo run
Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
Finished debug [unoptimized + debuginfo] target(s) in 0.57 secs
Running `target/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!
</code></pre>
<p>Awesome! With one tiny last tweak, we have finished the guessing game. Can you
think of what it is? That’s right, we don’t want to print out the secret
number. It was good for testing, but it kind of ruins the game. Here’s our
final source:</p>
<pre><code class="language-rust ignore">extern crate rand;
use std::io;
use std::cmp::Ordering;
use rand::Rng;
fn main() {
println!("Guess the number!");
let secret_number = rand::thread_rng().gen_range(1, 101);
loop {
println!("Please input your guess.");
let mut guess = String::new();
io::stdin().read_line(&mut guess)
.expect("Failed to read line");
let guess: u32 = match guess.trim().parse() {
Ok(num) => num,
Err(_) => continue,
};
println!("You guessed: {}", guess);
match guess.cmp(&secret_number) {
Ordering::Less => println!("Too small!"),
Ordering::Greater => println!("Too big!"),
Ordering::Equal => {
println!("You win!");
break;
}
}
}
}
</code></pre>
<a class="header" href="guessing-game.html#complete" id="complete"><h1>Complete!</h1></a>
<p>This project showed you a lot: <code>let</code>, <code>match</code>, methods, associated
functions, using external crates, and more.</p>
<p>At this point, you have successfully built the Guessing Game! Congratulations!</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="getting-started.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="syntax-and-semantics.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="getting-started.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="syntax-and-semantics.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
664
