<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>What is Ownership? - 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 -->
</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="foreword.html">Foreword</a></li><li class="affix"><a href="ch00-00-introduction.html">Introduction</a></li><li><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> How Functions Work</a></li><li><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li><a href="ch04-01-what-is-ownership.html" class="active"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References & Borrowing</a></li><li><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> Slices</a></li></ol></li><li><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><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li><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><a href="ch07-00-modules.html"><strong aria-hidden="true">7.</strong> Modules</a></li><li><ol class="section"><li><a href="ch07-01-mod-and-the-filesystem.html"><strong aria-hidden="true">7.1.</strong> mod and the Filesystem</a></li><li><a href="ch07-02-controlling-visibility-with-pub.html"><strong aria-hidden="true">7.2.</strong> Controlling Visibility with pub</a></li><li><a href="ch07-03-importing-names-with-use.html"><strong aria-hidden="true">7.3.</strong> Referring to Names in Different Modules</a></li></ol></li><li><a href="ch08-00-common-collections.html"><strong aria-hidden="true">8.</strong> Common Collections</a></li><li><ol class="section"><li><a href="ch08-01-vectors.html"><strong aria-hidden="true">8.1.</strong> Vectors</a></li><li><a href="ch08-02-strings.html"><strong aria-hidden="true">8.2.</strong> Strings</a></li><li><a href="ch08-03-hash-maps.html"><strong aria-hidden="true">8.3.</strong> Hash Maps</a></li></ol></li><li><a href="ch09-00-error-handling.html"><strong aria-hidden="true">9.</strong> Error Handling</a></li><li><ol class="section"><li><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong aria-hidden="true">9.1.</strong> Unrecoverable Errors with panic!</a></li><li><a href="ch09-02-recoverable-errors-with-result.html"><strong aria-hidden="true">9.2.</strong> Recoverable Errors with Result</a></li><li><a href="ch09-03-to-panic-or-not-to-panic.html"><strong aria-hidden="true">9.3.</strong> To panic! or Not To panic!</a></li></ol></li><li><a href="ch10-00-generics.html"><strong aria-hidden="true">10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ol class="section"><li><a href="ch10-01-syntax.html"><strong aria-hidden="true">10.1.</strong> Generic Data Types</a></li><li><a href="ch10-02-traits.html"><strong aria-hidden="true">10.2.</strong> Traits: Defining Shared Behavior</a></li><li><a href="ch10-03-lifetime-syntax.html"><strong aria-hidden="true">10.3.</strong> Validating References with Lifetimes</a></li></ol></li><li><a href="ch11-00-testing.html"><strong aria-hidden="true">11.</strong> Testing</a></li><li><ol class="section"><li><a href="ch11-01-writing-tests.html"><strong aria-hidden="true">11.1.</strong> Writing tests</a></li><li><a href="ch11-02-running-tests.html"><strong aria-hidden="true">11.2.</strong> Running tests</a></li><li><a href="ch11-03-test-organization.html"><strong aria-hidden="true">11.3.</strong> Test Organization</a></li></ol></li><li><a href="ch12-00-an-io-project.html"><strong aria-hidden="true">12.</strong> An I/O Project: Building a Command Line Program</a></li><li><ol class="section"><li><a href="ch12-01-accepting-command-line-arguments.html"><strong aria-hidden="true">12.1.</strong> Accepting Command Line Arguments</a></li><li><a href="ch12-02-reading-a-file.html"><strong aria-hidden="true">12.2.</strong> Reading a File</a></li><li><a href="ch12-03-improving-error-handling-and-modularity.html"><strong aria-hidden="true">12.3.</strong> Refactoring to Improve Modularity and Error Handling</a></li><li><a href="ch12-04-testing-the-librarys-functionality.html"><strong aria-hidden="true">12.4.</strong> Developing the Library’s Functionality with Test Driven Development</a></li><li><a href="ch12-05-working-with-environment-variables.html"><strong aria-hidden="true">12.5.</strong> Working with Environment Variables</a></li><li><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong aria-hidden="true">12.6.</strong> Writing Error Messages to Standard Error Instead of Standard Output</a></li></ol></li><li><a href="ch13-00-functional-features.html"><strong aria-hidden="true">13.</strong> Functional Language Features: Iterators and Closures</a></li><li><ol class="section"><li><a href="ch13-01-closures.html"><strong aria-hidden="true">13.1.</strong> Closures: Anonymous Functions that Can Capture Their Environment</a></li><li><a href="ch13-02-iterators.html"><strong aria-hidden="true">13.2.</strong> Processing a Series of Items with Iterators</a></li><li><a href="ch13-03-improving-our-io-project.html"><strong aria-hidden="true">13.3.</strong> Improving Our I/O Project</a></li><li><a href="ch13-04-performance.html"><strong aria-hidden="true">13.4.</strong> Comparing Performance: Loops vs. Iterators</a></li></ol></li><li><a href="ch14-00-more-about-cargo.html"><strong aria-hidden="true">14.</strong> More about Cargo and Crates.io</a></li><li><ol class="section"><li><a href="ch14-01-release-profiles.html"><strong aria-hidden="true">14.1.</strong> Customizing Builds with Release Profiles</a></li><li><a href="ch14-02-publishing-to-crates-io.html"><strong aria-hidden="true">14.2.</strong> Publishing a Crate to Crates.io</a></li><li><a href="ch14-03-cargo-workspaces.html"><strong aria-hidden="true">14.3.</strong> Cargo Workspaces</a></li><li><a href="ch14-04-installing-binaries.html"><strong aria-hidden="true">14.4.</strong> Installing Binaries from Crates.io with cargo install</a></li><li><a href="ch14-05-extending-cargo.html"><strong aria-hidden="true">14.5.</strong> Extending Cargo with Custom Commands</a></li></ol></li><li><a href="ch15-00-smart-pointers.html"><strong aria-hidden="true">15.</strong> Smart Pointers</a></li><li><ol class="section"><li><a href="ch15-01-box.html"><strong aria-hidden="true">15.1.</strong> Box<T> Points to Data on the Heap and Has a Known Size</a></li><li><a href="ch15-02-deref.html"><strong aria-hidden="true">15.2.</strong> The Deref Trait Allows Access to the Data Through a Reference</a></li><li><a href="ch15-03-drop.html"><strong aria-hidden="true">15.3.</strong> The Drop Trait Runs Code on Cleanup</a></li><li><a href="ch15-04-rc.html"><strong aria-hidden="true">15.4.</strong> Rc<T>, the Reference Counted Smart Pointer</a></li><li><a href="ch15-05-interior-mutability.html"><strong aria-hidden="true">15.5.</strong> RefCell<T> and the Interior Mutability Pattern</a></li><li><a href="ch15-06-reference-cycles.html"><strong aria-hidden="true">15.6.</strong> Creating Reference Cycles and Leaking Memory is Safe</a></li></ol></li><li><a href="ch16-00-concurrency.html"><strong aria-hidden="true">16.</strong> Fearless Concurrency</a></li><li><ol class="section"><li><a href="ch16-01-threads.html"><strong aria-hidden="true">16.1.</strong> Threads</a></li><li><a href="ch16-02-message-passing.html"><strong aria-hidden="true">16.2.</strong> Message Passing</a></li><li><a href="ch16-03-shared-state.html"><strong aria-hidden="true">16.3.</strong> Shared State</a></li><li><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong aria-hidden="true">16.4.</strong> Extensible Concurrency: Sync and Send</a></li></ol></li><li><a href="ch17-00-oop.html"><strong aria-hidden="true">17.</strong> Object Oriented Programming Features of Rust</a></li><li><ol class="section"><li><a href="ch17-01-what-is-oo.html"><strong aria-hidden="true">17.1.</strong> Characteristics of Object-Oriented Languages</a></li><li><a href="ch17-02-trait-objects.html"><strong aria-hidden="true">17.2.</strong> Using Trait Objects that Allow for Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong aria-hidden="true">17.3.</strong> Implementing an Object-Oriented Design Pattern</a></li></ol></li><li><a href="ch18-00-patterns.html"><strong aria-hidden="true">18.</strong> Patterns Match the Structure of Values</a></li><li><ol class="section"><li><a href="ch18-01-all-the-places-for-patterns.html"><strong aria-hidden="true">18.1.</strong> All the Places Patterns May be Used</a></li><li><a href="ch18-02-refutability.html"><strong aria-hidden="true">18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li><a href="ch18-03-pattern-syntax.html"><strong aria-hidden="true">18.3.</strong> All the Pattern Syntax</a></li></ol></li><li><a href="ch19-00-advanced-features.html"><strong aria-hidden="true">19.</strong> Advanced Features</a></li><li><ol class="section"><li><a href="ch19-01-unsafe-rust.html"><strong aria-hidden="true">19.1.</strong> Unsafe Rust</a></li><li><a href="ch19-02-advanced-lifetimes.html"><strong aria-hidden="true">19.2.</strong> Advanced Lifetimes</a></li><li><a href="ch19-03-advanced-traits.html"><strong aria-hidden="true">19.3.</strong> Advanced Traits</a></li><li><a href="ch19-04-advanced-types.html"><strong aria-hidden="true">19.4.</strong> Advanced Types</a></li><li><a href="ch19-05-advanced-functions-and-closures.html"><strong aria-hidden="true">19.5.</strong> Advanced Functions & Closures</a></li></ol></li><li><a href="ch20-00-final-project-a-web-server.html"><strong aria-hidden="true">20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ol class="section"><li><a href="ch20-01-single-threaded.html"><strong aria-hidden="true">20.1.</strong> A Single Threaded Web Server</a></li><li><a href="ch20-02-multithreaded.html"><strong aria-hidden="true">20.2.</strong> Turning our Single Threaded Server into a Multithreaded Server</a></li><li><a href="ch20-03-graceful-shutdown-and-cleanup.html"><strong aria-hidden="true">20.3.</strong> Graceful Shutdown and Cleanup</a></li></ol></li><li><a href="appendix-00.html"><strong aria-hidden="true">21.</strong> Appendix</a></li><li><ol class="section"><li><a href="appendix-01-keywords.html"><strong aria-hidden="true">21.1.</strong> A - Keywords</a></li><li><a href="appendix-02-operators.html"><strong aria-hidden="true">21.2.</strong> B - Operators and Symbols</a></li><li><a href="appendix-03-derivable-traits.html"><strong aria-hidden="true">21.3.</strong> C - Derivable Traits</a></li><li><a href="appendix-04-macros.html"><strong aria-hidden="true">21.4.</strong> D - Macros</a></li><li><a href="appendix-05-translation.html"><strong aria-hidden="true">21.5.</strong> E - Translations</a></li><li><a href="appendix-06-nightly-rust.html"><strong aria-hidden="true">21.6.</strong> F - How Rust is Made and “Nightly Rust”</a></li></ol></li></ol>
</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 <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="ch04-01-what-is-ownership.html#what-is-ownership" id="what-is-ownership"><h2>What Is Ownership?</h2></a>
<p>Rust’s central feature is <em>ownership</em>. Although the feature is straightforward
to explain, it has deep implications for the rest of the language.</p>
<p>All programs have to manage the way they use a computer’s memory while running.
Some languages have garbage collection that constantly looks for no longer used
memory as the program runs; in other languages, the programmer must explicitly
allocate and free the memory. Rust uses a third approach: memory is managed
through a system of ownership with a set of rules that the compiler checks at
compile time. None of the ownership features slow down your program while it’s
running.</p>
<p>Because ownership is a new concept for many programmers, it does take some time
to get used to. The good news is that the more experienced you become with Rust
and the rules of the ownership system, the more you’ll be able to naturally
develop code that is safe and efficient. Keep at it!</p>
<p>When you understand ownership, you’ll have a solid foundation for understanding
the features that make Rust unique. In this chapter, you’ll learn ownership by
working through some examples that focus on a very common data structure:
strings.</p>
<blockquote>
<a class="header" href="ch04-01-what-is-ownership.html#the-stack-and-the-heap" id="the-stack-and-the-heap"><h3>The Stack and the Heap</h3></a>
<p>In many programming languages, you don’t have to think about the stack and
the heap very often. But in a systems programming language like Rust, whether
a value is on the stack or the heap has more of an effect on how the language
behaves and why you have to make certain decisions. Parts of ownership will
be described in relation to the stack and the heap later in this chapter, so
here is a brief explanation in preparation.</p>
<p>Both the stack and the heap are parts of memory that is available to your code
to use at runtime, but they are structured in different ways. The stack stores
values in the order it gets them and removes the values in the opposite order.
This is referred to as <em>last in, first out</em>. Think of a stack of plates: when
you add more plates, you put them on top of the pile, and when you need a
plate, you take one off the top. Adding or removing plates from the middle or
bottom wouldn’t work as well! Adding data is called <em>pushing onto the stack</em>,
and removing data is called <em>popping off the stack</em>.</p>
<p>The stack is fast because of the way it accesses the data: it never has to
search for a place to put new data or a place to get data from because that
place is always the top. Another property that makes the stack fast is that
all data on the stack must take up a known, fixed size.</p>
<p>Data with a size unknown at compile time or a size that might change can be
stored on the heap instead. The heap is less organized: when you put data on
the heap, you ask for some amount of space. The operating system finds an
empty spot somewhere in the heap that is big enough, marks it as being in
use, and returns a <em>pointer</em>, which is the address of that location. This
process is called <em>allocating on the heap</em>, sometimes abbreviated as just
“allocating.” Pushing values onto the stack is not considered allocating.
Because the pointer is a known, fixed size, you can store the pointer on the
stack, but when you want the actual data, you have to follow the pointer.</p>
<p>Think of being seated at a restaurant. When you enter, you state the number of
people in your group, and the staff finds an empty table that fits everyone
and leads you there. If someone in your group comes late, they can ask where
you’ve been seated to find you.</p>
<p>Accessing data in the heap is slower than accessing data on the stack because
you have to follow a pointer to get there. Contemporary processors are faster
if they jump around less in memory. Continuing the analogy, consider a server
at a restaurant taking orders from many tables. It’s most efficient to get
all the orders at one table before moving on to the next table. Taking an
order from table A, then an order from table B, then one from A again, and
then one from B again would be a much slower process. By the same token, a
processor can do its job better if it works on data that’s close to other
data (as it is on the stack) rather than farther away (as it can be on the
heap). Allocating a large amount of space on the heap can also take time.</p>
<p>When your code calls a function, the values passed into the function
(including, potentially, pointers to data on the heap) and the function’s
local variables get pushed onto the stack. When the function is over, those
values get popped off the stack.</p>
<p>Keeping track of what parts of code are using what data on the heap,
minimizing the amount of duplicate data on the heap, and cleaning up unused
data on the heap so you don’t run out of space are all problems that ownership
addresses. Once you understand ownership, you won’t need to think about the
stack and the heap very often, but knowing that managing heap data is why
ownership exists can help explain why it works the way it does.</p>
</blockquote>
<a class="header" href="ch04-01-what-is-ownership.html#ownership-rules" id="ownership-rules"><h3>Ownership Rules</h3></a>
<p>First, let’s take a look at the ownership rules. Keep these rules in mind as we
work through the examples that illustrate them:</p>
<blockquote>
<ol>
<li>Each value in Rust has a variable that’s called its <em>owner</em>.</li>
<li>There can only be one owner at a time.</li>
<li>When the owner goes out of scope, the value will be dropped.</li>
</ol>
</blockquote>
<a class="header" href="ch04-01-what-is-ownership.html#variable-scope" id="variable-scope"><h3>Variable Scope</h3></a>
<p>We’ve walked through an example of a Rust program already in Chapter 2. Now
that we’re past basic syntax, we won’t include all the <code>fn main() {</code> code in
examples, so if you’re following along, you’ll have to put the following
examples inside a <code>main</code> function manually. As a result, our examples will be a
bit more concise, letting us focus on the actual details rather than
boilerplate code.</p>
<p>As a first example of ownership, we’ll look at the <em>scope</em> of some variables. A
scope is the range within a program for which an item is valid. Let’s say we
have a variable that looks like this:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let s = "hello";
#}</code></pre></pre>
<p>The variable <code>s</code> refers to a string literal, where the value of the string is
hardcoded into the text of our program. The variable is valid from the point at
which it’s declared until the end of the current <em>scope</em>. Listing 4-1 has
comments annotating where the variable <code>s</code> is valid:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
{ // s is not valid here, it’s not yet declared
let s = "hello"; // s is valid from this point forward
// do stuff with s
} // this scope is now over, and s is no longer valid
#}</code></pre></pre>
<p><span class="caption">Listing 4-1: A variable and the scope in which it is
valid</span></p>
<p>In other words, there are two important points in time here:</p>
<ul>
<li>When <code>s</code> comes <em>into scope</em>, it is valid.</li>
<li>It remains valid until it goes <em>out of scope</em>.</li>
</ul>
<p>At this point, the relationship between scopes and when variables are valid is
similar to that in other programming languages. Now we’ll build on top of this
understanding by introducing the <code>String</code> type.</p>
<a class="header" href="ch04-01-what-is-ownership.html#the-string-type" id="the-string-type"><h3>The <code>String</code> Type</h3></a>
<p>To illustrate the rules of ownership, we need a data type that is more complex
than the ones we covered in the “Data Types” section of Chapter 3. The types
covered previously are all stored on the stack and popped off the stack when
their scope is over, but we want to look at data that is stored on the heap and
explore how Rust knows when to clean up that data.</p>
<p>We’ll use <code>String</code> as the example here and concentrate on the parts of <code>String</code>
that relate to ownership. These aspects also apply to other complex data types
provided by the standard library and that you create. We’ll discuss <code>String</code> in
more depth in Chapter 8.</p>
<p>We’ve already seen string literals, where a string value is hardcoded into our
program. String literals are convenient, but they aren’t suitable for every
situation in which we may want to use text. One reason is that they’re
immutable. Another is that not every string value can be known when we write
our code: for example, what if we want to take user input and store it? For
these situations, Rust has a second string type, <code>String</code>. This type is
allocated on the heap and as such is able to store an amount of text that is
unknown to us at compile time. You can create a <code>String</code> from a string literal
using the <code>from</code> function, like so:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let s = String::from("hello");
#}</code></pre></pre>
<p>The double colon (<code>::</code>) is an operator that allows us to namespace this
particular <code>from</code> function under the <code>String</code> type rather than using some sort
of name like <code>string_from</code>. We’ll discuss this syntax more in the “Method
Syntax” section of Chapter 5 and when we talk about namespacing with modules in
“Module Definitions” in Chapter 7.</p>
<p>This kind of string <em>can</em> be mutated:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let mut s = String::from("hello");
s.push_str(", world!"); // push_str() appends a literal to a String
println!("{}", s); // This will print `hello, world!`
#}</code></pre></pre>
<p>So, what’s the difference here? Why can <code>String</code> be mutated but literals
cannot? The difference is how these two types deal with memory.</p>
<a class="header" href="ch04-01-what-is-ownership.html#memory-and-allocation" id="memory-and-allocation"><h3>Memory and Allocation</h3></a>
<p>In the case of a string literal, we know the contents at compile time, so the
text is hardcoded directly into the final executable. This is why string
literals are fast and efficient. But these properties only come from the string
literal’s immutability. Unfortunately, we can’t put a blob of memory into the
binary for each piece of text whose size is unknown at compile time and whose
size might change while running the program.</p>
<p>With the <code>String</code> type, in order to support a mutable, growable piece of text,
we need to allocate an amount of memory on the heap, unknown at compile time,
to hold the contents. This means:</p>
<ul>
<li>The memory must be requested from the operating system at runtime.</li>
<li>We need a way of returning this memory to the operating system when we’re
done with our <code>String</code>.</li>
</ul>
<p>That first part is done by us: when we call <code>String::from</code>, its implementation
requests the memory it needs. This is pretty much universal in programming
languages.</p>
<p>However, the second part is different. In languages with a <em>garbage collector
(GC)</em>, the GC keeps track and cleans up memory that isn’t being used anymore,
and we don’t need to think about it. Without a GC, it’s our responsibility to
identify when memory is no longer being used and call code to explicitly return
it, just as we did to request it. Doing this correctly has historically been a
difficult programming problem. If we forget, we’ll waste memory. If we do it
too early, we’ll have an invalid variable. If we do it twice, that’s a bug too.
We need to pair exactly one <code>allocate</code> with exactly one <code>free</code>.</p>
<p>Rust takes a different path: the memory is automatically returned once the
variable that owns it goes out of scope. Here’s a version of our scope example
from Listing 4-1 using a <code>String</code> instead of a string literal:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
{
let s = String::from("hello"); // s is valid from this point forward
// do stuff with s
} // this scope is now over, and s is no
// longer valid
#}</code></pre></pre>
<p>There is a natural point at which we can return the memory our <code>String</code> needs
to the operating system: when <code>s</code> goes out of scope. When a variable goes out
of scope, Rust calls a special function for us. This function is called <code>drop</code>,
and it’s where the author of <code>String</code> can put the code to return the memory.
Rust calls <code>drop</code> automatically at the closing <code>}</code>.</p>
<blockquote>
<p>Note: In C++, this pattern of deallocating resources at the end of an item’s
lifetime is sometimes called <em>Resource Acquisition Is Initialization (RAII)</em>.
The <code>drop</code> function in Rust will be familiar to you if you’ve used RAII
patterns.</p>
</blockquote>
<p>This pattern has a profound impact on the way Rust code is written. It may seem
simple right now, but the behavior of code can be unexpected in more
complicated situations when we want to have multiple variables use the data
we’ve allocated on the heap. Let’s explore some of those situations now.</p>
<a class="header" href="ch04-01-what-is-ownership.html#ways-variables-and-data-interact-move" id="ways-variables-and-data-interact-move"><h4>Ways Variables and Data Interact: Move</h4></a>
<p>Multiple variables can interact with the same data in different ways in Rust.
Let’s look at an example using an integer in Listing 4-2:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let x = 5;
let y = x;
#}</code></pre></pre>
<p><span class="caption">Listing 4-2: Assigning the integer value of variable <code>x</code>
to <code>y</code></span></p>
<p>We can probably guess what this is doing: “bind the value <code>5</code> to <code>x</code>; then make
a copy of the value in <code>x</code> and bind it to <code>y</code>.” We now have two variables, <code>x</code>
and <code>y</code>, and both equal <code>5</code>. This is indeed what is happening, because integers
are simple values with a known, fixed size, and these two <code>5</code> values are pushed
onto the stack.</p>
<p>Now let’s look at the <code>String</code> version:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let s1 = String::from("hello");
let s2 = s1;
#}</code></pre></pre>
<p>This looks very similar to the previous code, so we might assume that the way
it works would be the same: that is, the second line would make a copy of the
value in <code>s1</code> and bind it to <code>s2</code>. But this isn’t quite what happens.</p>
<p>Take a look at Figure 4-1 to see what is happening to <code>String</code> under the
covers. A <code>String</code> is made up of three parts, shown on the left: a pointer to
the memory that holds the contents of the string, a length, and a capacity.
This group of data is stored on the stack. On the right is the memory on the
heap that holds the contents.</p>
<p><img alt="String in memory" src="img/trpl04-01.svg" class="center" style="width: 50%;" /></p>
<p><span class="caption">Figure 4-1: Representation in memory of a <code>String</code>
holding the value <code>"hello"</code> bound to <code>s1</code></span></p>
<p>The length is how much memory, in bytes, the contents of the <code>String</code> is
currently using. The capacity is the total amount of memory, in bytes, that the
<code>String</code> has received from the operating system. The difference between length
and capacity matters, but not in this context, so for now, it’s fine to ignore
the capacity.</p>
<p>When we assign <code>s1</code> to <code>s2</code>, the <code>String</code> data is copied, meaning we copy the
pointer, the length, and the capacity that are on the stack. We do not copy the
data on the heap that the pointer refers to. In other words, the data
representation in memory looks like Figure 4-2.</p>
<p><img alt="s1 and s2 pointing to the same value" src="img/trpl04-02.svg" class="center" style="width: 50%;" /></p>
<p><span class="caption">Figure 4-2: Representation in memory of the variable <code>s2</code>
that has a copy of the pointer, length, and capacity of <code>s1</code></span></p>
<p>The representation does <em>not</em> look like Figure 4-3, which is what memory would
look like if Rust instead copied the heap data as well. If Rust did this, the
operation <code>s2 = s1</code> could be very expensive in terms of runtime performance if
the data on the heap were large.</p>
<p><img alt="s1 and s2 to two places" src="img/trpl04-03.svg" class="center" style="width: 50%;" /></p>
<p><span class="caption">Figure 4-3: Another possibility for what <code>s2 = s1</code> might
do if Rust copied the heap data as well</span></p>
<p>Earlier, we said that when a variable goes out of scope, Rust automatically
calls the <code>drop</code> function and cleans up the heap memory for that variable. But
Figure 4-2 shows both data pointers pointing to the same location. This is a
problem: when <code>s2</code> and <code>s1</code> go out of scope, they will both try to free the
same memory. This is known as a <em>double free</em> error and is one of the memory
safety bugs we mentioned previously. Freeing memory twice can lead to memory
corruption, which can potentially lead to security vulnerabilities.</p>
<p>To ensure memory safety, there’s one more detail to what happens in this
situation in Rust. Instead of trying to copy the allocated memory, Rust
considers <code>s1</code> to no longer be valid and, therefore, Rust doesn’t need to free
anything when <code>s1</code> goes out of scope. Check out what happens when you try to
use <code>s1</code> after <code>s2</code> is created; it won’t work:</p>
<pre><code class="language-rust ignore">let s1 = String::from("hello");
let s2 = s1;
println!("{}, world!", s1);
</code></pre>
<p>You’ll get an error like this because Rust prevents you from using the
invalidated reference:</p>
<pre><code class="language-text">error[E0382]: use of moved value: `s1`
--> src/main.rs:5:28
|
3 | let s2 = s1;
| -- value moved here
4 |
5 | println!("{}, world!", s1);
| ^^ value used here after move
|
= note: move occurs because `s1` has type `std::string::String`, which does
not implement the `Copy` trait
</code></pre>
<p>If you’ve heard the terms <em>shallow copy</em> and <em>deep copy</em> while working with
other languages, the concept of copying the pointer, length, and capacity
without copying the data probably sounds like making a shallow copy. But
because Rust also invalidates the first variable, instead of being called a
shallow copy, it’s known as a <em>move</em>. Here we would read this by saying that
<code>s1</code> was <em>moved</em> into <code>s2</code>. So what actually happens is shown in Figure 4-4.</p>
<p><img alt="s1 moved to s2" src="img/trpl04-04.svg" class="center" style="width: 50%;" /></p>
<p><span class="caption">Figure 4-4: Representation in memory after <code>s1</code> has been
invalidated</span></p>
<p>That solves our problem! With only <code>s2</code> valid, when it goes out of scope, it
alone will free the memory, and we’re done.</p>
<p>In addition, there’s a design choice that’s implied by this: Rust will never
automatically create “deep” copies of your data. Therefore, any <em>automatic</em>
copying can be assumed to be inexpensive in terms of runtime performance.</p>
<a class="header" href="ch04-01-what-is-ownership.html#ways-variables-and-data-interact-clone" id="ways-variables-and-data-interact-clone"><h4>Ways Variables and Data Interact: Clone</h4></a>
<p>If we <em>do</em> want to deeply copy the heap data of the <code>String</code>, not just the
stack data, we can use a common method called <code>clone</code>. We’ll discuss method
syntax in Chapter 5, but because methods are a common feature in many
programming languages, you’ve probably seen them before.</p>
<p>Here’s an example of the <code>clone</code> method in action:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let s1 = String::from("hello");
let s2 = s1.clone();
println!("s1 = {}, s2 = {}", s1, s2);
#}</code></pre></pre>
<p>This works just fine and explicitly produces the behavior shown in Figure 4-3,
where the heap data <em>does</em> get copied.</p>
<p>When you see a call to <code>clone</code>, you know that some arbitrary code is being
executed and that code may be expensive. It’s a visual indicator that something
different is going on.</p>
<a class="header" href="ch04-01-what-is-ownership.html#stack-only-data-copy" id="stack-only-data-copy"><h4>Stack-Only Data: Copy</h4></a>
<p>There’s another wrinkle we haven’t talked about yet. This code using integers,
part of which was shown earlier in Listing 4-2, works and is valid:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let x = 5;
let y = x;
println!("x = {}, y = {}", x, y);
#}</code></pre></pre>
<p>But this code seems to contradict what we just learned: we don’t have a call to
<code>clone</code>, but <code>x</code> is still valid and wasn’t moved into <code>y</code>.</p>
<p>The reason is that types such as integers that have a known size at compile
time are stored entirely on the stack, so copies of the actual values are quick
to make. That means there’s no reason we would want to prevent <code>x</code> from being
valid after we create the variable <code>y</code>. In other words, there’s no difference
between deep and shallow copying here, so calling <code>clone</code> wouldn’t do anything
different from the usual shallow copying and we can leave it out.</p>
<p>Rust has a special annotation called the <code>Copy</code> trait that we can place on
types like integers that are stored on the stack (we’ll talk more about traits
in Chapter 10). If a type has the <code>Copy</code> trait, an older variable is still
usable after assignment. Rust won’t let us annotate a type with the <code>Copy</code>
trait if the type, or any of its parts, has implemented the <code>Drop</code> trait. If
the type needs something special to happen when the value goes out of scope and
we add the <code>Copy</code> annotation to that type, we’ll get a compile time error. To
learn about how to add the <code>Copy</code> annotation to your type, see “Derivable
Traits” in Appendix C.</p>
<p>So what types are <code>Copy</code>? You can check the documentation for the given type to
be sure, but as a general rule, any group of simple scalar values can be
<code>Copy</code>, and nothing that requires allocation or is some form of resource is
<code>Copy</code>. Here are some of the types that are <code>Copy</code>:</p>
<ul>
<li>All the integer types, such as <code>u32</code>.</li>
<li>The Boolean type, <code>bool</code>, with values <code>true</code> and <code>false</code>.</li>
<li>All the floating point types, such as <code>f64</code>.</li>
<li>The character type, <code>char</code>.</li>
<li>Tuples, but only if they contain types that are also <code>Copy</code>. For example,
<code>(i32, i32)</code> is <code>Copy</code>, but <code>(i32, String)</code> is not.</li>
</ul>
<a class="header" href="ch04-01-what-is-ownership.html#ownership-and-functions" id="ownership-and-functions"><h3>Ownership and Functions</h3></a>
<p>The semantics for passing a value to a function are similar to those for
assigning a value to a variable. Passing a variable to a function will move or
copy, just as assignment does. Listing 4-3 has an example with some annotations
showing where variables go into and out of scope:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
let s = String::from("hello"); // s comes into scope
takes_ownership(s); // s's value moves into the function...
// ... and so is no longer valid here
let x = 5; // x comes into scope
makes_copy(x); // x would move into the function,
// but i32 is Copy, so it’s okay to still
// use x afterward
} // Here, x goes out of scope, then s. But because s's value was moved, nothing
// special happens.
fn takes_ownership(some_string: String) { // some_string comes into scope
println!("{}", some_string);
} // Here, some_string goes out of scope and `drop` is called. The backing
// memory is freed.
fn makes_copy(some_integer: i32) { // some_integer comes into scope
println!("{}", some_integer);
} // Here, some_integer goes out of scope. Nothing special happens.
</code></pre></pre>
<p><span class="caption">Listing 4-3: Functions with ownership and scope
annotated</span></p>
<p>If we tried to use <code>s</code> after the call to <code>takes_ownership</code>, Rust would throw a
compile time error. These static checks protect us from mistakes. Try adding
code to <code>main</code> that uses <code>s</code> and <code>x</code> to see where you can use them and where
the ownership rules prevent you from doing so.</p>
<a class="header" href="ch04-01-what-is-ownership.html#return-values-and-scope" id="return-values-and-scope"><h3>Return Values and Scope</h3></a>
<p>Returning values can also transfer ownership. Listing 4-4 is an example with
similar annotations to those in Listing 4-3:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
let s1 = gives_ownership(); // gives_ownership moves its return
// value into s1
let s2 = String::from("hello"); // s2 comes into scope
let s3 = takes_and_gives_back(s2); // s2 is moved into
// takes_and_gives_back, which also
// moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 goes out of scope but was
// moved, so nothing happens. s1 goes out of scope and is dropped.
fn gives_ownership() -> String { // gives_ownership will move its
// return value into the function
// that calls it
let some_string = String::from("hello"); // some_string comes into scope
some_string // some_string is returned and
// moves out to the calling
// function.
}
// takes_and_gives_back will take a String and return one.
fn takes_and_gives_back(a_string: String) -> String { // a_string comes into
// scope
a_string // a_string is returned and moves out to the calling function
}
</code></pre></pre>
<p><span class="caption">Listing 4-4: Transferring ownership of return
values</span></p>
<p>The ownership of a variable follows the same pattern every time: assigning a
value to another variable moves it. When a variable that includes data on the
heap goes out of scope, the value will be cleaned up by <code>drop</code> unless the data
has been moved to be owned by another variable.</p>
<p>Taking ownership and then returning ownership with every function is a bit
tedious. What if we want to let a function use a value but not take ownership?
It’s quite annoying that anything we pass in also needs to be passed back if we
want to use it again, in addition to any data resulting from the body of the
function that we might want to return as well.</p>
<p>It’s possible to return multiple values using a tuple, as shown in Listing 4-5:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
let s1 = String::from("hello");
let (s2, len) = calculate_length(s1);
println!("The length of '{}' is {}.", s2, len);
}
fn calculate_length(s: String) -> (String, usize) {
let length = s.len(); // len() returns the length of a String
(s, length)
}
</code></pre></pre>
<p><span class="caption">Listing 4-5: Returning ownership of parameters</span></p>
<p>But this is too much ceremony and a lot of work for a concept that should be
common. Luckily for us, Rust has a feature for this concept, called
<em>references</em>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch04-00-understanding-ownership.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="ch04-02-references-and-borrowing.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="ch04-00-understanding-ownership.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="ch04-02-references-and-borrowing.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
>
494
