pierre/RustBook
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
f836a9177d
RustBook/ch10-03-lifetime-syntax.html

870 lines
64 KiB
HTML
Raw Normal View History

Initial commit
2020-01-06 20:57:15 +00:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Validating References with Lifetimes - 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" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="googleFonts/css.css" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<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="ferris.css">
<link rel="stylesheet" href="theme/2018-edition.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
</script>
<!-- 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 = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('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">
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
<ol class="chapter"><li class="expanded affix "><a href="title-page.html">The Rust Programming Language</a></li><li class="expanded affix "><a href="foreword.html">Foreword</a></li><li class="expanded affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="expanded "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li class="expanded "><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li class="expanded "><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li class="expanded "><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li class="expanded "><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li class="expanded "><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li class="expanded "><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li class="expanded "><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li class="expanded "><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> Functions</a></li><li class="expanded "><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li class="expanded "><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li class="expanded "><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li class="expanded "><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li class="expanded "><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References and Borrowing</a></li><li class="expanded "><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> The Slice Type</a></li></ol></li><li class="expanded "><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li class="expanded "><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li class="expanded "><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li class="expanded "><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li class="expanded "><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li class="expanded "><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li class="expanded "><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li class="expanded "><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li class="expanded "><a href="ch07-00-managing-growing-projects-with-packages-crates-and-modules.html"><strong aria-hidden="true">7.</strong> Managing Growing Projects with Packages, Crates, and Modules</a></li><li><ol class="section"><li class="expanded "><a href="ch07-01-packages-and-crates.html"><strong aria-hidden="true">7.1.</strong> Packages and Crates</a></li><li class="expanded "><a href="ch07-02-defining-modules-to-control-scope-and-privacy.html"><strong aria-hidden="true">7.2.</strong> Defining Modules to Control Scope and Privacy</a></li><li class="expanded "><a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html"><
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<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 (default)</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>
<h2><a class="header" href="#validating-references-with-lifetimes" id="validating-references-with-lifetimes">Validating References with Lifetimes</a></h2>
<p>One detail we didn’t discuss in the <a href="ch04-02-references-and-borrowing.html#references-and-borrowing">“References and
Borrowing”</a><!-- ignore --> section in Chapter 4 is
that every reference in Rust has a <em>lifetime</em>, which is the scope for which
that reference is valid. Most of the time, lifetimes are implicit and
inferred, just like most of the time, types are inferred. We must annotate
types when multiple types are possible. In a similar way, we must annotate
lifetimes when the lifetimes of references could be related in a few different
ways. Rust requires us to annotate the relationships using generic lifetime
parameters to ensure the actual references used at runtime will definitely be
valid.</p>
<p>The concept of lifetimes is somewhat different from tools in other programming
languages, arguably making lifetimes Rust’s most distinctive feature. Although
we won’t cover lifetimes in their entirety in this chapter, we’ll discuss
common ways you might encounter lifetime syntax so you can become familiar with
the concepts.</p>
<h3><a class="header" href="#preventing-dangling-references-with-lifetimes" id="preventing-dangling-references-with-lifetimes">Preventing Dangling References with Lifetimes</a></h3>
<p>The main aim of lifetimes is to prevent dangling references, which cause a
program to reference data other than the data it’s intended to reference.
Consider the program in Listing 10-17, which has an outer scope and an inner
scope.</p>
<pre><code class="language-rust ignore does_not_compile">{
let r;
{
let x = 5;
r = &amp;x;
}
println!(&quot;r: {}&quot;, r);
}
</code></pre>
<p><span class="caption">Listing 10-17: An attempt to use a reference whose value
has gone out of scope</span></p>
<blockquote>
<p>Note: The examples in Listings 10-17, 10-18, and 10-24 declare variables
without giving them an initial value, so the variable name exists in the
outer scope. At first glance, this might appear to be in conflict with Rust’s
having no null values. However, if we try to use a variable before giving it
a value, we’ll get a compile-time error, which shows that Rust indeed does
not allow null values.</p>
</blockquote>
<p>The outer scope declares a variable named <code>r</code> with no initial value, and the
inner scope declares a variable named <code>x</code> with the initial value of 5. Inside
the inner scope, we attempt to set the value of <code>r</code> as a reference to <code>x</code>. Then
the inner scope ends, and we attempt to print the value in <code>r</code>. This code won’t
compile because the value <code>r</code> is referring to has gone out of scope before we
try to use it. Here is the error message:</p>
<pre><code class="language-text">error[E0597]: `x` does not live long enough
--&gt; src/main.rs:7:5
|
6 | r = &amp;x;
| - borrow occurs here
7 | }
| ^ `x` dropped here while still borrowed
...
10 | }
| - borrowed value needs to live until here
</code></pre>
<p>The variable <code>x</code> doesn’t “live long enough.” The reason is that <code>x</code> will be out
of scope when the inner scope ends on line 7. But <code>r</code> is still valid for the
outer scope; because its scope is larger, we say that it “lives longer.” If
Rust allowed this code to work, <code>r</code> would be referencing memory that was
deallocated when <code>x</code> went out of scope, and anything we tried to do with <code>r</code>
wouldn’t work correctly. So how does Rust determine that this code is invalid?
It uses a borrow checker.</p>
<h3><a class="header" href="#the-borrow-checker" id="the-borrow-checker">The Borrow Checker</a></h3>
<p>The Rust compiler has a <em>borrow checker</em> that compares scopes to determine
whether all borrows are valid. Listing 10-18 shows the same code as Listing
10-17 but with annotations showing the lifetimes of the variables.</p>
<pre><code class="language-rust ignore does_not_compile">{
let r; // ---------+-- 'a
// |
{ // |
let x = 5; // -+-- 'b |
r = &amp;x; // | |
} // -+ |
// |
println!(&quot;r: {}&quot;, r); // |
} // ---------+
</code></pre>
<p><span class="caption">Listing 10-18: Annotations of the lifetimes of <code>r</code> and
<code>x</code>, named <code>'a</code> and <code>'b</code>, respectively</span></p>
<p>Here, we’ve annotated the lifetime of <code>r</code> with <code>'a</code> and the lifetime of <code>x</code>
with <code>'b</code>. As you can see, the inner <code>'b</code> block is much smaller than the outer
<code>'a</code> lifetime block. At compile time, Rust compares the size of the two
lifetimes and sees that <code>r</code> has a lifetime of <code>'a</code> but that it refers to memory
with a lifetime of <code>'b</code>. The program is rejected because <code>'b</code> is shorter than
<code>'a</code>: the subject of the reference doesn’t live as long as the reference.</p>
<p>Listing 10-19 fixes the code so it doesn’t have a dangling reference and
compiles without any errors.</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>{
let x = 5; // ----------+-- 'b
// |
let r = &amp;x; // --+-- 'a |
// | |
println!(&quot;r: {}&quot;, r); // | |
// --+ |
} // ----------+
<span class="boring">}
</span></code></pre></pre>
<p><span class="caption">Listing 10-19: A valid reference because the data has a
longer lifetime than the reference</span></p>
<p>Here, <code>x</code> has the lifetime <code>'b</code>, which in this case is larger than <code>'a</code>. This
means <code>r</code> can reference <code>x</code> because Rust knows that the reference in <code>r</code> will
always be valid while <code>x</code> is valid.</p>
<p>Now that you know where the lifetimes of references are and how Rust analyzes
lifetimes to ensure references will always be valid, let’s explore generic
lifetimes of parameters and return values in the context of functions.</p>
<h3><a class="header" href="#generic-lifetimes-in-functions" id="generic-lifetimes-in-functions">Generic Lifetimes in Functions</a></h3>
<p>Let’s write a function that returns the longer of two string slices. This
function will take two string slices and return a string slice. After we’ve
implemented the <code>longest</code> function, the code in Listing 10-20 should print <code>The longest string is abcd</code>.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore">fn main() {
let string1 = String::from(&quot;abcd&quot;);
let string2 = &quot;xyz&quot;;
let result = longest(string1.as_str(), string2);
println!(&quot;The longest string is {}&quot;, result);
}
</code></pre>
<p><span class="caption">Listing 10-20: A <code>main</code> function that calls the <code>longest</code>
function to find the longer of two string slices</span></p>
<p>Note that we want the function to take string slices, which are references,
because we don’t want the <code>longest</code> function to take ownership of its
parameters. We want to allow the function to accept slices of a <code>String</code> (the
type stored in the variable <code>string1</code>) as well as string literals (which is
what variable <code>string2</code> contains).</p>
<p>Refer to the <a href="ch04-03-slices.html#string-slices-as-parameters">“String Slices as Parameters”</a><!--
ignore --> section in Chapter 4 for more discussion about why the parameters we
use in Listing 10-20 are the ones we want.</p>
<p>If we try to implement the <code>longest</code> function as shown in Listing 10-21, it
won’t compile.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore does_not_compile">fn longest(x: &amp;str, y: &amp;str) -&gt; &amp;str {
if x.len() &gt; y.len() {
x
} else {
y
}
}
</code></pre>
<p><span class="caption">Listing 10-21: An implementation of the <code>longest</code>
function that returns the longer of two string slices but does not yet
compile</span></p>
<p>Instead, we get the following error that talks about lifetimes:</p>
<pre><code class="language-text">error[E0106]: missing lifetime specifier
--&gt; src/main.rs:1:33
|
1 | fn longest(x: &amp;str, y: &amp;str) -&gt; &amp;str {
| ^ expected lifetime parameter
|
= help: this function's return type contains a borrowed value, but the
signature does not say whether it is borrowed from `x` or `y`
</code></pre>
<p>The help text reveals that the return type needs a generic lifetime parameter
on it because Rust can’t tell whether the reference being returned refers to
<code>x</code> or <code>y</code>. Actually, we don’t know either, because the <code>if</code> block in the body
of this function returns a reference to <code>x</code> and the <code>else</code> block returns a
reference to <code>y</code>!</p>
<p>When we’re defining this function, we don’t know the concrete values that will
be passed into this function, so we don’t know whether the <code>if</code> case or the
<code>else</code> case will execute. We also don’t know the concrete lifetimes of the
references that will be passed in, so we can’t look at the scopes as we did in
Listings 10-18 and 10-19 to determine whether the reference we return will
always be valid. The borrow checker can’t determine this either, because it
doesn’t know how the lifetimes of <code>x</code> and <code>y</code> relate to the lifetime of the
return value. To fix this error, we’ll add generic lifetime parameters that
define the relationship between the references so the borrow checker can
perform its analysis.</p>
<h3><a class="header" href="#lifetime-annotation-syntax" id="lifetime-annotation-syntax">Lifetime Annotation Syntax</a></h3>
<p>Lifetime annotations don’t change how long any of the references live. Just
as functions can accept any type when the signature specifies a generic type
parameter, functions can accept references with any lifetime by specifying a
generic lifetime parameter. Lifetime annotations describe the relationships of
the lifetimes of multiple references to each other without affecting the
lifetimes.</p>
<p>Lifetime annotations have a slightly unusual syntax: the names of lifetime
parameters must start with an apostrophe (<code>'</code>) and are usually all lowercase and
very short, like generic types. Most people use the name <code>'a</code>. We place
lifetime parameter annotations after the <code>&amp;</code> of a reference, using a space to
separate the annotation from the reference’s type.</p>
<p>Here are some examples: a reference to an <code>i32</code> without a lifetime parameter, a
reference to an <code>i32</code> that has a lifetime parameter named <code>'a</code>, and a mutable
reference to an <code>i32</code> that also has the lifetime <code>'a</code>.</p>
<pre><code class="language-rust ignore">&amp;i32 // a reference
&amp;'a i32 // a reference with an explicit lifetime
&amp;'a mut i32 // a mutable reference with an explicit lifetime
</code></pre>
<p>One lifetime annotation by itself doesn’t have much meaning, because the
annotations are meant to tell Rust how generic lifetime parameters of multiple
references relate to each other. For example, let’s say we have a function with
the parameter <code>first</code> that is a reference to an <code>i32</code> with lifetime <code>'a</code>. The
function also has another parameter named <code>second</code> that is another reference to
an <code>i32</code> that also has the lifetime <code>'a</code>. The lifetime annotations indicate
that the references <code>first</code> and <code>second</code> must both live as long as that generic
lifetime.</p>
<h3><a class="header" href="#lifetime-annotations-in-function-signatures" id="lifetime-annotations-in-function-signatures">Lifetime Annotations in Function Signatures</a></h3>
<p>Now let’s examine lifetime annotations in the context of the <code>longest</code>
function. As with generic type parameters, we need to declare generic lifetime
parameters inside angle brackets between the function name and the parameter
list. The constraint we want to express in this signature is that all the
references in the parameters and the return value must have the same lifetime.
We’ll name the lifetime <code>'a</code> and then add it to each reference, as shown in
Listing 10-22.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>fn longest&lt;'a&gt;(x: &amp;'a str, y: &amp;'a str) -&gt; &amp;'a str {
if x.len() &gt; y.len() {
x
} else {
y
}
}
<span class="boring">}
</span></code></pre></pre>
<p><span class="caption">Listing 10-22: The <code>longest</code> function definition
specifying that all the references in the signature must have the same lifetime
<code>'a</code></span></p>
<p>This code should compile and produce the result we want when we use it with the
<code>main</code> function in Listing 10-20.</p>
<p>The function signature now tells Rust that for some lifetime <code>'a</code>, the function
takes two parameters, both of which are string slices that live at least as
long as lifetime <code>'a</code>. The function signature also tells Rust that the string
slice returned from the function will live at least as long as lifetime <code>'a</code>.
In practice, it means that the lifetime of the reference returned by the
<code>longest</code> function is the same as the smaller of the lifetimes of the
references passed in. These constraints are what we want Rust to enforce.
Remember, when we specify the lifetime parameters in this function signature,
we’re not changing the lifetimes of any values passed in or returned. Rather,
we’re specifying that the borrow checker should reject any values that don’t
adhere to these constraints. Note that the <code>longest</code> function doesn’t need to
know exactly how long <code>x</code> and <code>y</code> will live, only that some scope can be
substituted for <code>'a</code> that will satisfy this signature.</p>
<p>When annotating lifetimes in functions, the annotations go in the function
signature, not in the function body. Rust can analyze the code within the
function without any help. However, when a function has references to or from
code outside that function, it becomes almost impossible for Rust to figure out
the lifetimes of the parameters or return values on its own. The lifetimes
might be different each time the function is called. This is why we need to
annotate the lifetimes manually.</p>
<p>When we pass concrete references to <code>longest</code>, the concrete lifetime that is
substituted for <code>'a</code> is the part of the scope of <code>x</code> that overlaps with the
scope of <code>y</code>. In other words, the generic lifetime <code>'a</code> will get the concrete
lifetime that is equal to the smaller of the lifetimes of <code>x</code> and <code>y</code>. Because
we’ve annotated the returned reference with the same lifetime parameter <code>'a</code>,
the returned reference will also be valid for the length of the smaller of the
lifetimes of <code>x</code> and <code>y</code>.</p>
<p>Let’s look at how the lifetime annotations restrict the <code>longest</code> function by
passing in references that have different concrete lifetimes. Listing 10-23 is
a straightforward example.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn longest&lt;'a&gt;(x: &amp;'a str, y: &amp;'a str) -&gt; &amp;'a str {
</span><span class="boring"> if x.len() &gt; y.len() {
</span><span class="boring"> x
</span><span class="boring"> } else {
</span><span class="boring"> y
</span><span class="boring"> }
</span><span class="boring">}
</span><span class="boring">
</span>fn main() {
let string1 = String::from(&quot;long string is long&quot;);
{
let string2 = String::from(&quot;xyz&quot;);
let result = longest(string1.as_str(), string2.as_str());
println!(&quot;The longest string is {}&quot;, result);
}
}
</code></pre></pre>
<p><span class="caption">Listing 10-23: Using the <code>longest</code> function with
references to <code>String</code> values that have different concrete lifetimes</span></p>
<p>In this example, <code>string1</code> is valid until the end of the outer scope, <code>string2</code>
is valid until the end of the inner scope, and <code>result</code> references something
that is valid until the end of the inner scope. Run this code, and you’ll see
that the borrow checker approves of this code; it will compile and print <code>The longest string is long string is long</code>.</p>
<p>Next, let’s try an example that shows that the lifetime of the reference in
<code>result</code> must be the smaller lifetime of the two arguments. We’ll move the
declaration of the <code>result</code> variable outside the inner scope but leave the
assignment of the value to the <code>result</code> variable inside the scope with
<code>string2</code>. Then we’ll move the <code>println!</code> that uses <code>result</code> outside the inner
scope, after the inner scope has ended. The code in Listing 10-24 will not
compile.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore does_not_compile">fn main() {
let string1 = String::from(&quot;long string is long&quot;);
let result;
{
let string2 = String::from(&quot;xyz&quot;);
result = longest(string1.as_str(), string2.as_str());
}
println!(&quot;The longest string is {}&quot;, result);
}
</code></pre>
<p><span class="caption">Listing 10-24: Attempting to use <code>result</code> after <code>string2</code>
has gone out of scope</span></p>
<p>When we try to compile this code, we’ll get this error:</p>
<pre><code class="language-text">error[E0597]: `string2` does not live long enough
--&gt; src/main.rs:15:5
|
14 | result = longest(string1.as_str(), string2.as_str());
| ------- borrow occurs here
15 | }
| ^ `string2` dropped here while still borrowed
16 | println!(&quot;The longest string is {}&quot;, result);
17 | }
| - borrowed value needs to live until here
</code></pre>
<p>The error shows that for <code>result</code> to be valid for the <code>println!</code> statement,
<code>string2</code> would need to be valid until the end of the outer scope. Rust knows
this because we annotated the lifetimes of the function parameters and return
values using the same lifetime parameter <code>'a</code>.</p>
<p>As humans, we can look at this code and see that <code>string1</code> is longer than
<code>string2</code> and therefore <code>result</code> will contain a reference to <code>string1</code>.
Because <code>string1</code> has not gone out of scope yet, a reference to <code>string1</code> will
still be valid for the <code>println!</code> statement. However, the compiler can’t see
that the reference is valid in this case. We’ve told Rust that the lifetime of
the reference returned by the <code>longest</code> function is the same as the smaller of
the lifetimes of the references passed in. Therefore, the borrow checker
disallows the code in Listing 10-24 as possibly having an invalid reference.</p>
<p>Try designing more experiments that vary the values and lifetimes of the
references passed in to the <code>longest</code> function and how the returned reference
is used. Make hypotheses about whether or not your experiments will pass the
borrow checker before you compile; then check to see if you’re right!</p>
<h3><a class="header" href="#thinking-in-terms-of-lifetimes" id="thinking-in-terms-of-lifetimes">Thinking in Terms of Lifetimes</a></h3>
<p>The way in which you need to specify lifetime parameters depends on what your
function is doing. For example, if we changed the implementation of the
<code>longest</code> function to always return the first parameter rather than the longest
string slice, we wouldn’t need to specify a lifetime on the <code>y</code> parameter. The
following code will compile:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>fn longest&lt;'a&gt;(x: &amp;'a str, y: &amp;str) -&gt; &amp;'a str {
x
}
<span class="boring">}
</span></code></pre></pre>
<p>In this example, we’ve specified a lifetime parameter <code>'a</code> for the parameter
<code>x</code> and the return type, but not for the parameter <code>y</code>, because the lifetime of
<code>y</code> does not have any relationship with the lifetime of <code>x</code> or the return value.</p>
<p>When returning a reference from a function, the lifetime parameter for the
return type needs to match the lifetime parameter for one of the parameters. If
the reference returned does <em>not</em> refer to one of the parameters, it must refer
to a value created within this function, which would be a dangling reference
because the value will go out of scope at the end of the function. Consider
this attempted implementation of the <code>longest</code> function that won’t compile:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore does_not_compile">fn longest&lt;'a&gt;(x: &amp;str, y: &amp;str) -&gt; &amp;'a str {
let result = String::from(&quot;really long string&quot;);
result.as_str()
}
</code></pre>
<p>Here, even though we’ve specified a lifetime parameter <code>'a</code> for the return
type, this implementation will fail to compile because the return value
lifetime is not related to the lifetime of the parameters at all. Here is the
error message we get:</p>
<pre><code class="language-text">error[E0597]: `result` does not live long enough
--&gt; src/main.rs:3:5
|
3 | result.as_str()
| ^^^^^^ does not live long enough
4 | }
| - borrowed value only lives until here
|
note: borrowed value must be valid for the lifetime 'a as defined on the
function body at 1:1...
--&gt; src/main.rs:1:1
|
1 | / fn longest&lt;'a&gt;(x: &amp;str, y: &amp;str) -&gt; &amp;'a str {
2 | | let result = String::from(&quot;really long string&quot;);
3 | | result.as_str()
4 | | }
| |_^
</code></pre>
<p>The problem is that <code>result</code> goes out of scope and gets cleaned up at the end
of the <code>longest</code> function. We’re also trying to return a reference to <code>result</code>
from the function. There is no way we can specify lifetime parameters that
would change the dangling reference, and Rust won’t let us create a dangling
reference. In this case, the best fix would be to return an owned data type
rather than a reference so the calling function is then responsible for
cleaning up the value.</p>
<p>Ultimately, lifetime syntax is about connecting the lifetimes of various
parameters and return values of functions. Once they’re connected, Rust has
enough information to allow memory-safe operations and disallow operations that
would create dangling pointers or otherwise violate memory safety.</p>
<h3><a class="header" href="#lifetime-annotations-in-struct-definitions" id="lifetime-annotations-in-struct-definitions">Lifetime Annotations in Struct Definitions</a></h3>
<p>So far, we’ve only defined structs to hold owned types. It’s possible for
structs to hold references, but in that case we would need to add a lifetime
annotation on every reference in the struct’s definition. Listing 10-25 has a
struct named <code>ImportantExcerpt</code> that holds a string slice.</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">struct ImportantExcerpt&lt;'a&gt; {
part: &amp;'a str,
}
fn main() {
let novel = String::from(&quot;Call me Ishmael. Some years ago...&quot;);
let first_sentence = novel.split('.')
.next()
.expect(&quot;Could not find a '.'&quot;);
let i = ImportantExcerpt { part: first_sentence };
}
</code></pre></pre>
<p><span class="caption">Listing 10-25: A struct that holds a reference, so its
definition needs a lifetime annotation</span></p>
<p>This struct has one field, <code>part</code>, that holds a string slice, which is a
reference. As with generic data types, we declare the name of the generic
lifetime parameter inside angle brackets after the name of the struct so we can
use the lifetime parameter in the body of the struct definition. This
annotation means an instance of <code>ImportantExcerpt</code> can’t outlive the reference
it holds in its <code>part</code> field.</p>
<p>The <code>main</code> function here creates an instance of the <code>ImportantExcerpt</code> struct
that holds a reference to the first sentence of the <code>String</code> owned by the
variable <code>novel</code>. The data in <code>novel</code> exists before the <code>ImportantExcerpt</code>
instance is created. In addition, <code>novel</code> doesn’t go out of scope until after
the <code>ImportantExcerpt</code> goes out of scope, so the reference in the
<code>ImportantExcerpt</code> instance is valid.</p>
<h3><a class="header" href="#lifetime-elision" id="lifetime-elision">Lifetime Elision</a></h3>
<p>You’ve learned that every reference has a lifetime and that you need to specify
lifetime parameters for functions or structs that use references. However, in
Chapter 4 we had a function in Listing 4-9, which is shown again in Listing
10-26, that compiled without lifetime annotations.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>fn first_word(s: &amp;str) -&gt; &amp;str {
let bytes = s.as_bytes();
for (i, &amp;item) in bytes.iter().enumerate() {
if item == b' ' {
return &amp;s[0..i];
}
}
&amp;s[..]
}
<span class="boring">}
</span></code></pre></pre>
<p><span class="caption">Listing 10-26: A function we defined in Listing 4-9 that
compiled without lifetime annotations, even though the parameter and return
type are references</span></p>
<p>The reason this function compiles without lifetime annotations is historical:
in early versions (pre-1.0) of Rust, this code wouldn’t have compiled because
every reference needed an explicit lifetime. At that time, the function
signature would have been written like this:</p>
<pre><code class="language-rust ignore">fn first_word&lt;'a&gt;(s: &amp;'a str) -&gt; &amp;'a str {
</code></pre>
<p>After writing a lot of Rust code, the Rust team found that Rust programmers
were entering the same lifetime annotations over and over in particular
situations. These situations were predictable and followed a few deterministic
patterns. The developers programmed these patterns into the compiler’s code so
the borrow checker could infer the lifetimes in these situations and wouldn’t
need explicit annotations.</p>
<p>This piece of Rust history is relevant because it’s possible that more
deterministic patterns will emerge and be added to the compiler. In the future,
even fewer lifetime annotations might be required.</p>
<p>The patterns programmed into Rust’s analysis of references are called the
<em>lifetime elision rules</em>. These aren’t rules for programmers to follow; they’re
a set of particular cases that the compiler will consider, and if your code
fits these cases, you don’t need to write the lifetimes explicitly.</p>
<p>The elision rules don’t provide full inference. If Rust deterministically
applies the rules but there is still ambiguity as to what lifetimes the
references have, the compiler won’t guess what the lifetime of the remaining
references should be. In this case, instead of guessing, the compiler will give
you an error that you can resolve by adding the lifetime annotations that
specify how the references relate to each other.</p>
<p>Lifetimes on function or method parameters are called <em>input lifetimes</em>, and
lifetimes on return values are called <em>output lifetimes</em>.</p>
<p>The compiler uses three rules to figure out what lifetimes references have when
there aren’t explicit annotations. The first rule applies to input lifetimes,
and the second and third rules apply to output lifetimes. If the compiler gets
to the end of the three rules and there are still references for which it can’t
figure out lifetimes, the compiler will stop with an error. These rules apply
to <code>fn</code> definitions as well as <code>impl</code> blocks.</p>
<p>The first rule is that each parameter that is a reference gets its own lifetime
parameter. In other words, a function with one parameter gets one lifetime
parameter: <code>fn foo&lt;'a&gt;(x: &amp;'a i32)</code>; a function with two parameters gets two
separate lifetime parameters: <code>fn foo&lt;'a, 'b&gt;(x: &amp;'a i32, y: &amp;'b i32)</code>; and so
on.</p>
<p>The second rule is if there is exactly one input lifetime parameter, that
lifetime is assigned to all output lifetime parameters: <code>fn foo&lt;'a&gt;(x: &amp;'a i32) -&gt; &amp;'a i32</code>.</p>
<p>The third rule is if there are multiple input lifetime parameters, but one of
them is <code>&amp;self</code> or <code>&amp;mut self</code> because this is a method, the lifetime of <code>self</code>
is assigned to all output lifetime parameters. This third rule makes methods
much nicer to read and write because fewer symbols are necessary.</p>
<p>Let’s pretend we’re the compiler. We’ll apply these rules to figure out what
the lifetimes of the references in the signature of the <code>first_word</code> function
in Listing 10-26 are. The signature starts without any lifetimes associated
with the references:</p>
<pre><code class="language-rust ignore">fn first_word(s: &amp;str) -&gt; &amp;str {
</code></pre>
<p>Then the compiler applies the first rule, which specifies that each parameter
gets its own lifetime. We’ll call it <code>'a</code> as usual, so now the signature is
this:</p>
<pre><code class="language-rust ignore">fn first_word&lt;'a&gt;(s: &amp;'a str) -&gt; &amp;str {
</code></pre>
<p>The second rule applies because there is exactly one input lifetime. The second
rule specifies that the lifetime of the one input parameter gets assigned to
the output lifetime, so the signature is now this:</p>
<pre><code class="language-rust ignore">fn first_word&lt;'a&gt;(s: &amp;'a str) -&gt; &amp;'a str {
</code></pre>
<p>Now all the references in this function signature have lifetimes, and the
compiler can continue its analysis without needing the programmer to annotate
the lifetimes in this function signature.</p>
<p>Let’s look at another example, this time using the <code>longest</code> function that had
no lifetime parameters when we started working with it in Listing 10-21:</p>
<pre><code class="language-rust ignore">fn longest(x: &amp;str, y: &amp;str) -&gt; &amp;str {
</code></pre>
<p>Let’s apply the first rule: each parameter gets its own lifetime. This time we
have two parameters instead of one, so we have two lifetimes:</p>
<pre><code class="language-rust ignore">fn longest&lt;'a, 'b&gt;(x: &amp;'a str, y: &amp;'b str) -&gt; &amp;str {
</code></pre>
<p>You can see that the second rule doesn’t apply because there is more than one
input lifetime. The third rule doesn’t apply either, because <code>longest</code> is a
function rather than a method, so none of the parameters are <code>self</code>. After
working through all three rules, we still haven’t figured out what the return
type’s lifetime is. This is why we got an error trying to compile the code in
Listing 10-21: the compiler worked through the lifetime elision rules but still
couldn’t figure out all the lifetimes of the references in the signature.</p>
<p>Because the third rule really only applies in method signatures, we’ll look at
lifetimes in that context next to see why the third rule means we don’t have to
annotate lifetimes in method signatures very often.</p>
<h3><a class="header" href="#lifetime-annotations-in-method-definitions" id="lifetime-annotations-in-method-definitions">Lifetime Annotations in Method Definitions</a></h3>
<p>When we implement methods on a struct with lifetimes, we use the same syntax as
that of generic type parameters shown in Listing 10-11. Where we declare and
use the lifetime parameters depends on whether they’re related to the struct
fields or the method parameters and return values.</p>
<p>Lifetime names for struct fields always need to be declared after the <code>impl</code>
keyword and then used after the struct’s name, because those lifetimes are part
of the struct’s type.</p>
<p>In method signatures inside the <code>impl</code> block, references might be tied to the
lifetime of references in the struct’s fields, or they might be independent. In
addition, the lifetime elision rules often make it so that lifetime annotations
aren’t necessary in method signatures. Let’s look at some examples using the
struct named <code>ImportantExcerpt</code> that we defined in Listing 10-25.</p>
<p>First, we’ll use a method named <code>level</code> whose only parameter is a reference to
<code>self</code> and whose return value is an <code>i32</code>, which is not a reference to anything:</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span><span class="boring">struct ImportantExcerpt&lt;'a&gt; {
</span><span class="boring"> part: &amp;'a str,
</span><span class="boring">}
</span><span class="boring">
</span>impl&lt;'a&gt; ImportantExcerpt&lt;'a&gt; {
fn level(&amp;self) -&gt; i32 {
3
}
}
<span class="boring">}
</span></code></pre></pre>
<p>The lifetime parameter declaration after <code>impl</code> and its use after the type name
are required, but we’re not required to annotate the lifetime of the reference
to <code>self</code> because of the first elision rule.</p>
<p>Here is an example where the third lifetime elision rule applies:</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span><span class="boring">struct ImportantExcerpt&lt;'a&gt; {
</span><span class="boring"> part: &amp;'a str,
</span><span class="boring">}
</span><span class="boring">
</span>impl&lt;'a&gt; ImportantExcerpt&lt;'a&gt; {
fn announce_and_return_part(&amp;self, announcement: &amp;str) -&gt; &amp;str {
println!(&quot;Attention please: {}&quot;, announcement);
self.part
}
}
<span class="boring">}
</span></code></pre></pre>
<p>There are two input lifetimes, so Rust applies the first lifetime elision rule
and gives both <code>&amp;self</code> and <code>announcement</code> their own lifetimes. Then, because
one of the parameters is <code>&amp;self</code>, the return type gets the lifetime of <code>&amp;self</code>,
and all lifetimes have been accounted for.</p>
<h3><a class="header" href="#the-static-lifetime" id="the-static-lifetime">The Static Lifetime</a></h3>
<p>One special lifetime we need to discuss is <code>'static</code>, which means that this
reference <em>can</em> live for the entire duration of the program. All string
literals have the <code>'static</code> lifetime, which we can annotate as follows:</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>let s: &amp;'static str = &quot;I have a static lifetime.&quot;;
<span class="boring">}
</span></code></pre></pre>
<p>The text of this string is stored directly in the program’s binary, which
is always available. Therefore, the lifetime of all string literals is
<code>'static</code>.</p>
<p>You might see suggestions to use the <code>'static</code> lifetime in error messages. But
before specifying <code>'static</code> as the lifetime for a reference, think about
whether the reference you have actually lives the entire lifetime of your
program or not. You might consider whether you want it to live that long, even
if it could. Most of the time, the problem results from attempting to create a
dangling reference or a mismatch of the available lifetimes. In such cases, the
solution is fixing those problems, not specifying the <code>'static</code> lifetime.</p>
<h2><a class="header" href="#generic-type-parameters-trait-bounds-and-lifetimes-together" id="generic-type-parameters-trait-bounds-and-lifetimes-together">Generic Type Parameters, Trait Bounds, and Lifetimes Together</a></h2>
<p>Let’s briefly look at the syntax of specifying generic type parameters, trait
bounds, and lifetimes all in one function!</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>use std::fmt::Display;
fn longest_with_an_announcement&lt;'a, T&gt;(x: &amp;'a str, y: &amp;'a str, ann: T) -&gt; &amp;'a str
where T: Display
{
println!(&quot;Announcement! {}&quot;, ann);
if x.len() &gt; y.len() {
x
} else {
y
}
}
<span class="boring">}
</span></code></pre></pre>
<p>This is the <code>longest</code> function from Listing 10-22 that returns the longer of
two string slices. But now it has an extra parameter named <code>ann</code> of the generic
type <code>T</code>, which can be filled in by any type that implements the <code>Display</code>
trait as specified by the <code>where</code> clause. This extra parameter will be printed
before the function compares the lengths of the string slices, which is why the
<code>Display</code> trait bound is necessary. Because lifetimes are a type of generic,
the declarations of the lifetime parameter <code>'a</code> and the generic type parameter
<code>T</code> go in the same list inside the angle brackets after the function name.</p>
<h2><a class="header" href="#summary" id="summary">Summary</a></h2>
<p>We covered a lot in this chapter! Now that you know about generic type
parameters, traits and trait bounds, and generic lifetime parameters, you’re
ready to write code without repetition that works in many different situations.
Generic type parameters let you apply the code to different types. Traits and
trait bounds ensure that even though the types are generic, they’ll have the
behavior the code needs. You learned how to use lifetime annotations to ensure
that this flexible code won’t have any dangling references. And all of this
analysis happens at compile time, which doesn’t affect runtime performance!</p>
<p>Believe it or not, there is much more to learn on the topics we discussed in
this chapter: Chapter 17 discusses trait objects, which are another way to use
traits. Chapter 19 covers more complex scenarios involving lifetime annotations
as well as some advanced type system features. But next, you’ll learn how to
write tests in Rust so you can make sure your code is working the way it should.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch10-02-traits.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="ch11-00-testing.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="ch10-02-traits.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="ch11-00-testing.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 type="text/javascript">
window.playpen_copyable = true;
</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 -->
<script type="text/javascript" src="ferris.js"></script>
</body>
</html>
Reference in New Issue Copy Permalink