502 lines
39 KiB
HTML
502 lines
39 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Using Box<T> to Point to Data on the Heap - The Rust Programming Language</title>
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff">
|
||
|
||
<link rel="icon" href="favicon-de23e50b.svg">
|
||
<link rel="shortcut icon" href="favicon-8114d1fc.png">
|
||
<link rel="stylesheet" href="css/variables-8adf115d.css">
|
||
<link rel="stylesheet" href="css/general-0392ca55.css">
|
||
<link rel="stylesheet" href="css/chrome-fc474251.css">
|
||
<link rel="stylesheet" href="css/print-9e4910d8.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="fonts/fonts-9644e21d.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
|
||
<link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
|
||
<link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
<link rel="stylesheet" href="ferris-d33b75bf.css">
|
||
<link rel="stylesheet" href="theme/2018-edition-4e126c62.css">
|
||
<link rel="stylesheet" href="theme/semantic-notes-9b5766c0.css">
|
||
<link rel="stylesheet" href="theme/listing-cab26221.css">
|
||
|
||
|
||
<!-- Provide site root and default themes to javascript -->
|
||
<script>
|
||
const path_to_root = "";
|
||
const default_light_theme = "light";
|
||
const default_dark_theme = "navy";
|
||
window.path_to_searchindex_js = "searchindex-6a1da8cc.js";
|
||
</script>
|
||
<!-- Start loading toc.js asap -->
|
||
<script src="toc-0e4ce700.js"></script>
|
||
</head>
|
||
<body>
|
||
<div id="mdbook-help-container">
|
||
<div id="mdbook-help-popup">
|
||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||
<div>
|
||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||
<p>Press <kbd>?</kbd> to show this help</p>
|
||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div id="mdbook-body-container">
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
let theme = localStorage.getItem('mdbook-theme');
|
||
let 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>
|
||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||
let theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
const html = document.documentElement;
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add("js");
|
||
</script>
|
||
|
||
<input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
let sidebar = null;
|
||
const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
} else {
|
||
sidebar = 'hidden';
|
||
sidebar_toggle.checked = false;
|
||
}
|
||
if (sidebar === 'visible') {
|
||
sidebar_toggle.checked = true;
|
||
} else {
|
||
html.classList.remove('sidebar-visible');
|
||
}
|
||
</script>
|
||
|
||
<nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
|
||
<!-- populated by js -->
|
||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||
<noscript>
|
||
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
|
||
</noscript>
|
||
<div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
|
||
<div class="sidebar-resize-indicator"></div>
|
||
</div>
|
||
</nav>
|
||
|
||
<div id="mdbook-page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="mdbook-menu-bar-hover-placeholder"></div>
|
||
<div id="mdbook-menu-bar" class="menu-bar sticky">
|
||
<div class="left-buttons">
|
||
<label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
|
||
</label>
|
||
<button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
|
||
</button>
|
||
<ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
|
||
</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">
|
||
<span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
|
||
</a>
|
||
<a href="https://github.com/rust-lang/book" title="Git repository" aria-label="Git repository">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="mdbook-search-wrapper" class="hidden">
|
||
<form id="mdbook-searchbar-outer" class="searchbar-outer">
|
||
<div class="search-wrapper">
|
||
<input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
|
||
<div class="spinner-wrapper">
|
||
<span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
|
||
</div>
|
||
</div>
|
||
</form>
|
||
<div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="mdbook-searchresults-header" class="searchresults-header"></div>
|
||
<ul id="mdbook-searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="mdbook-content" class="content">
|
||
<main>
|
||
<h2 id="using-boxt-to-point-to-data-on-the-heap"><a class="header" href="#using-boxt-to-point-to-data-on-the-heap">Using <code>Box<T></code> to Point to Data on the Heap</a></h2>
|
||
<p>The most straightforward smart pointer is a box, whose type is written
|
||
<code>Box<T></code>. <em>Boxes</em> allow you to store data on the heap rather than the stack.
|
||
What remains on the stack is the pointer to the heap data. Refer to Chapter 4
|
||
to review the difference between the stack and the heap.</p>
|
||
<p>Boxes don’t have performance overhead, other than storing their data on the
|
||
heap instead of on the stack. But they don’t have many extra capabilities
|
||
either. You’ll use them most often in these situations:</p>
|
||
<ul>
|
||
<li>When you have a type whose size can’t be known at compile time, and you want
|
||
to use a value of that type in a context that requires an exact size</li>
|
||
<li>When you have a large amount of data, and you want to transfer ownership but
|
||
ensure that the data won’t be copied when you do so</li>
|
||
<li>When you want to own a value, and you care only that it’s a type that
|
||
implements a particular trait rather than being of a specific type</li>
|
||
</ul>
|
||
<p>We’ll demonstrate the first situation in <a href="#enabling-recursive-types-with-boxes">“Enabling Recursive Types with
|
||
Boxes”</a><!-- ignore -->. In the second
|
||
case, transferring ownership of a large amount of data can take a long time
|
||
because the data is copied around on the stack. To improve performance in this
|
||
situation, we can store the large amount of data on the heap in a box. Then,
|
||
only the small amount of pointer data is copied around on the stack, while the
|
||
data it references stays in one place on the heap. The third case is known as a
|
||
<em>trait object</em>, and <a href="ch18-02-trait-objects.html#using-trait-objects-to-abstract-over-shared-behavior">“Using Trait Objects to Abstract over Shared
|
||
Behavior”</a><!-- ignore --> in Chapter 18 is devoted to that
|
||
topic. So, what you learn here you’ll apply again in that section!</p>
|
||
<!-- Old headings. Do not remove or links may break. -->
|
||
<p><a id="using-boxt-to-store-data-on-the-heap"></a></p>
|
||
<h3 id="storing-data-on-the-heap"><a class="header" href="#storing-data-on-the-heap">Storing Data on the Heap</a></h3>
|
||
<p>Before we discuss the heap storage use case for <code>Box<T></code>, we’ll cover the
|
||
syntax and how to interact with values stored within a <code>Box<T></code>.</p>
|
||
<p>Listing 15-1 shows how to use a box to store an <code>i32</code> value on the heap.</p>
|
||
<figure class="listing" id="listing-15-1">
|
||
<span class="file-name">Filename: src/main.rs</span>
|
||
<pre class="playground"><code class="language-rust edition2024">fn main() {
|
||
let b = Box::new(5);
|
||
println!("b = {b}");
|
||
}</code></pre>
|
||
<figcaption><a href="#listing-15-1">Listing 15-1</a>: Storing an <code>i32</code> value on the heap using a box</figcaption>
|
||
</figure>
|
||
<p>We define the variable <code>b</code> to have the value of a <code>Box</code> that points to the
|
||
value <code>5</code>, which is allocated on the heap. This program will print <code>b = 5</code>; in
|
||
this case, we can access the data in the box similarly to how we would if this
|
||
data were on the stack. Just like any owned value, when a box goes out of
|
||
scope, as <code>b</code> does at the end of <code>main</code>, it will be deallocated. The
|
||
deallocation happens both for the box (stored on the stack) and the data it
|
||
points to (stored on the heap).</p>
|
||
<p>Putting a single value on the heap isn’t very useful, so you won’t use boxes by
|
||
themselves in this way very often. Having values like a single <code>i32</code> on the
|
||
stack, where they’re stored by default, is more appropriate in the majority of
|
||
situations. Let’s look at a case where boxes allow us to define types that we
|
||
wouldn’t be allowed to define if we didn’t have boxes.</p>
|
||
<h3 id="enabling-recursive-types-with-boxes"><a class="header" href="#enabling-recursive-types-with-boxes">Enabling Recursive Types with Boxes</a></h3>
|
||
<p>A value of a <em>recursive type</em> can have another value of the same type as part of
|
||
itself. Recursive types pose an issue because Rust needs to know at compile time
|
||
how much space a type takes up. However, the nesting of values of recursive
|
||
types could theoretically continue infinitely, so Rust can’t know how much space
|
||
the value needs. Because boxes have a known size, we can enable recursive types
|
||
by inserting a box in the recursive type definition.</p>
|
||
<p>As an example of a recursive type, let’s explore the cons list. This is a data
|
||
type commonly found in functional programming languages. The cons list type
|
||
we’ll define is straightforward except for the recursion; therefore, the
|
||
concepts in the example we’ll work with will be useful anytime you get into
|
||
more complex situations involving recursive types.</p>
|
||
<!-- Old headings. Do not remove or links may break. -->
|
||
<p><a id="more-information-about-the-cons-list"></a></p>
|
||
<h4 id="understanding-the-cons-list"><a class="header" href="#understanding-the-cons-list">Understanding the Cons List</a></h4>
|
||
<p>A <em>cons list</em> is a data structure that comes from the Lisp programming language
|
||
and its dialects, is made up of nested pairs, and is the Lisp version of a
|
||
linked list. Its name comes from the <code>cons</code> function (short for <em>construct
|
||
function</em>) in Lisp that constructs a new pair from its two arguments. By
|
||
calling <code>cons</code> on a pair consisting of a value and another pair, we can
|
||
construct cons lists made up of recursive pairs.</p>
|
||
<p>For example, here’s a pseudocode representation of a cons list containing the
|
||
list <code>1, 2, 3</code> with each pair in parentheses:</p>
|
||
<pre><code class="language-text">(1, (2, (3, Nil)))
|
||
</code></pre>
|
||
<p>Each item in a cons list contains two elements: the value of the current item
|
||
and of the next item. The last item in the list contains only a value called
|
||
<code>Nil</code> without a next item. A cons list is produced by recursively calling the
|
||
<code>cons</code> function. The canonical name to denote the base case of the recursion is
|
||
<code>Nil</code>. Note that this is not the same as the “null” or “nil” concept discussed
|
||
in Chapter 6, which is an invalid or absent value.</p>
|
||
<p>The cons list isn’t a commonly used data structure in Rust. Most of the time
|
||
when you have a list of items in Rust, <code>Vec<T></code> is a better choice to use.
|
||
Other, more complex recursive data types <em>are</em> useful in various situations,
|
||
but by starting with the cons list in this chapter, we can explore how boxes
|
||
let us define a recursive data type without much distraction.</p>
|
||
<p>Listing 15-2 contains an enum definition for a cons list. Note that this code
|
||
won’t compile yet, because the <code>List</code> type doesn’t have a known size, which
|
||
we’ll demonstrate.</p>
|
||
<figure class="listing" id="listing-15-2">
|
||
<span class="file-name">Filename: src/main.rs</span>
|
||
<pre><code class="language-rust ignore does_not_compile">enum List {
|
||
Cons(i32, List),
|
||
Nil,
|
||
}
|
||
<span class="boring">
|
||
</span><span class="boring">fn main() {}</span></code></pre>
|
||
<figcaption><a href="#listing-15-2">Listing 15-2</a>: The first attempt at defining an enum to represent a cons list data structure of <code>i32</code> values</figcaption>
|
||
</figure>
|
||
<section class="note" aria-role="note">
|
||
<p>Note: We’re implementing a cons list that holds only <code>i32</code> values for the
|
||
purposes of this example. We could have implemented it using generics, as we
|
||
discussed in Chapter 10, to define a cons list type that could store values of
|
||
any type.</p>
|
||
</section>
|
||
<p>Using the <code>List</code> type to store the list <code>1, 2, 3</code> would look like the code in
|
||
Listing 15-3.</p>
|
||
<figure class="listing" id="listing-15-3">
|
||
<span class="file-name">Filename: src/main.rs</span>
|
||
<pre><code class="language-rust ignore does_not_compile"><span class="boring">enum List {
|
||
</span><span class="boring"> Cons(i32, List),
|
||
</span><span class="boring"> Nil,
|
||
</span><span class="boring">}
|
||
</span><span class="boring">
|
||
</span>// --snip--
|
||
|
||
use crate::List::{Cons, Nil};
|
||
|
||
fn main() {
|
||
let list = Cons(1, Cons(2, Cons(3, Nil)));
|
||
}</code></pre>
|
||
<figcaption><a href="#listing-15-3">Listing 15-3</a>: Using the <code>List</code> enum to store the list <code>1, 2, 3</code></figcaption>
|
||
</figure>
|
||
<p>The first <code>Cons</code> value holds <code>1</code> and another <code>List</code> value. This <code>List</code> value is
|
||
another <code>Cons</code> value that holds <code>2</code> and another <code>List</code> value. This <code>List</code> value
|
||
is one more <code>Cons</code> value that holds <code>3</code> and a <code>List</code> value, which is finally
|
||
<code>Nil</code>, the non-recursive variant that signals the end of the list.</p>
|
||
<p>If we try to compile the code in Listing 15-3, we get the error shown in
|
||
Listing 15-4.</p>
|
||
<figure class="listing" id="listing-15-4">
|
||
<pre><code class="language-console">$ cargo run
|
||
Compiling cons-list v0.1.0 (file:///projects/cons-list)
|
||
error[E0072]: recursive type `List` has infinite size
|
||
--> src/main.rs:1:1
|
||
|
|
||
1 | enum List {
|
||
| ^^^^^^^^^
|
||
2 | Cons(i32, List),
|
||
| ---- recursive without indirection
|
||
|
|
||
help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle
|
||
|
|
||
2 | Cons(i32, Box<List>),
|
||
| ++++ +
|
||
|
||
error[E0391]: cycle detected when computing when `List` needs drop
|
||
--> src/main.rs:1:1
|
||
|
|
||
1 | enum List {
|
||
| ^^^^^^^^^
|
||
|
|
||
= note: ...which immediately requires computing when `List` needs drop again
|
||
= note: cycle used when computing whether `List` needs drop
|
||
= note: see https://rustc-dev-guide.rust-lang.org/overview.html#queries and https://rustc-dev-guide.rust-lang.org/query.html for more information
|
||
|
||
Some errors have detailed explanations: E0072, E0391.
|
||
For more information about an error, try `rustc --explain E0072`.
|
||
error: could not compile `cons-list` (bin "cons-list") due to 2 previous errors
|
||
</code></pre>
|
||
<figcaption><a href="#listing-15-4">Listing 15-4</a>: The error we get when attempting to define a recursive enum</figcaption>
|
||
</figure>
|
||
<p>The error shows this type “has infinite size.” The reason is that we’ve defined
|
||
<code>List</code> with a variant that is recursive: It holds another value of itself
|
||
directly. As a result, Rust can’t figure out how much space it needs to store a
|
||
<code>List</code> value. Let’s break down why we get this error. First, we’ll look at how
|
||
Rust decides how much space it needs to store a value of a non-recursive type.</p>
|
||
<h4 id="computing-the-size-of-a-non-recursive-type"><a class="header" href="#computing-the-size-of-a-non-recursive-type">Computing the Size of a Non-Recursive Type</a></h4>
|
||
<p>Recall the <code>Message</code> enum we defined in Listing 6-2 when we discussed enum
|
||
definitions in Chapter 6:</p>
|
||
<pre class="playground"><code class="language-rust edition2024">enum Message {
|
||
Quit,
|
||
Move { x: i32, y: i32 },
|
||
Write(String),
|
||
ChangeColor(i32, i32, i32),
|
||
}
|
||
<span class="boring">
|
||
</span><span class="boring">fn main() {}</span></code></pre>
|
||
<p>To determine how much space to allocate for a <code>Message</code> value, Rust goes
|
||
through each of the variants to see which variant needs the most space. Rust
|
||
sees that <code>Message::Quit</code> doesn’t need any space, <code>Message::Move</code> needs enough
|
||
space to store two <code>i32</code> values, and so forth. Because only one variant will be
|
||
used, the most space a <code>Message</code> value will need is the space it would take to
|
||
store the largest of its variants.</p>
|
||
<p>Contrast this with what happens when Rust tries to determine how much space a
|
||
recursive type like the <code>List</code> enum in Listing 15-2 needs. The compiler starts
|
||
by looking at the <code>Cons</code> variant, which holds a value of type <code>i32</code> and a value
|
||
of type <code>List</code>. Therefore, <code>Cons</code> needs an amount of space equal to the size of
|
||
an <code>i32</code> plus the size of a <code>List</code>. To figure out how much memory the <code>List</code>
|
||
type needs, the compiler looks at the variants, starting with the <code>Cons</code>
|
||
variant. The <code>Cons</code> variant holds a value of type <code>i32</code> and a value of type
|
||
<code>List</code>, and this process continues infinitely, as shown in Figure 15-1.</p>
|
||
<img alt="An infinite Cons list: a rectangle labeled 'Cons' split into two smaller rectangles. The first smaller rectangle holds the label 'i32', and the second smaller rectangle holds the label 'Cons' and a smaller version of the outer 'Cons' rectangle. The 'Cons' rectangles continue to hold smaller and smaller versions of themselves until the smallest comfortably sized rectangle holds an infinity symbol, indicating that this repetition goes on forever." src="img/trpl15-01.svg" class="center" style="width: 50%;" />
|
||
<p><span class="caption">Figure 15-1: An infinite <code>List</code> consisting of infinite
|
||
<code>Cons</code> variants</span></p>
|
||
<!-- Old headings. Do not remove or links may break. -->
|
||
<p><a id="using-boxt-to-get-a-recursive-type-with-a-known-size"></a></p>
|
||
<h4 id="getting-a-recursive-type-with-a-known-size"><a class="header" href="#getting-a-recursive-type-with-a-known-size">Getting a Recursive Type with a Known Size</a></h4>
|
||
<p>Because Rust can’t figure out how much space to allocate for recursively
|
||
defined types, the compiler gives an error with this helpful suggestion:</p>
|
||
<!-- manual-regeneration
|
||
after doing automatic regeneration, look at listings/ch15-smart-pointers/listing-15-03/output.txt and copy the relevant line
|
||
-->
|
||
<pre><code class="language-text">help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle
|
||
|
|
||
2 | Cons(i32, Box<List>),
|
||
| ++++ +
|
||
</code></pre>
|
||
<p>In this suggestion, <em>indirection</em> means that instead of storing a value
|
||
directly, we should change the data structure to store the value indirectly by
|
||
storing a pointer to the value instead.</p>
|
||
<p>Because a <code>Box<T></code> is a pointer, Rust always knows how much space a <code>Box<T></code>
|
||
needs: A pointer’s size doesn’t change based on the amount of data it’s
|
||
pointing to. This means we can put a <code>Box<T></code> inside the <code>Cons</code> variant instead
|
||
of another <code>List</code> value directly. The <code>Box<T></code> will point to the next <code>List</code>
|
||
value that will be on the heap rather than inside the <code>Cons</code> variant.
|
||
Conceptually, we still have a list, created with lists holding other lists, but
|
||
this implementation is now more like placing the items next to one another
|
||
rather than inside one another.</p>
|
||
<p>We can change the definition of the <code>List</code> enum in Listing 15-2 and the usage
|
||
of the <code>List</code> in Listing 15-3 to the code in Listing 15-5, which will compile.</p>
|
||
<figure class="listing" id="listing-15-5">
|
||
<span class="file-name">Filename: src/main.rs</span>
|
||
<pre class="playground"><code class="language-rust edition2024">enum List {
|
||
Cons(i32, Box<List>),
|
||
Nil,
|
||
}
|
||
|
||
use crate::List::{Cons, Nil};
|
||
|
||
fn main() {
|
||
let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil))))));
|
||
}</code></pre>
|
||
<figcaption><a href="#listing-15-5">Listing 15-5</a>: The definition of <code>List</code> that uses <code>Box<T></code> in order to have a known size</figcaption>
|
||
</figure>
|
||
<p>The <code>Cons</code> variant needs the size of an <code>i32</code> plus the space to store the box’s
|
||
pointer data. The <code>Nil</code> variant stores no values, so it needs less space on the
|
||
stack than the <code>Cons</code> variant. We now know that any <code>List</code> value will take up
|
||
the size of an <code>i32</code> plus the size of a box’s pointer data. By using a box,
|
||
we’ve broken the infinite, recursive chain, so the compiler can figure out the
|
||
size it needs to store a <code>List</code> value. Figure 15-2 shows what the <code>Cons</code>
|
||
variant looks like now.</p>
|
||
<img alt="A rectangle labeled 'Cons' split into two smaller rectangles. The first smaller rectangle holds the label 'i32', and the second smaller rectangle holds the label 'Box' with one inner rectangle that contains the label 'usize', representing the finite size of the box's pointer." src="img/trpl15-02.svg" class="center" />
|
||
<p><span class="caption">Figure 15-2: A <code>List</code> that is not infinitely sized,
|
||
because <code>Cons</code> holds a <code>Box</code></span></p>
|
||
<p>Boxes provide only the indirection and heap allocation; they don’t have any
|
||
other special capabilities, like those we’ll see with the other smart pointer
|
||
types. They also don’t have the performance overhead that these special
|
||
capabilities incur, so they can be useful in cases like the cons list where the
|
||
indirection is the only feature we need. We’ll look at more use cases for boxes
|
||
in Chapter 18.</p>
|
||
<p>The <code>Box<T></code> type is a smart pointer because it implements the <code>Deref</code> trait,
|
||
which allows <code>Box<T></code> values to be treated like references. When a <code>Box<T></code>
|
||
value goes out of scope, the heap data that the box is pointing to is cleaned
|
||
up as well because of the <code>Drop</code> trait implementation. These two traits will be
|
||
even more important to the functionality provided by the other smart pointer
|
||
types we’ll discuss in the rest of this chapter. Let’s explore these two traits
|
||
in more detail.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="ch15-00-smart-pointers.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M41.4 233.4c-12.5 12.5-12.5 32.8 0 45.3l160 160c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 256 246.6 118.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-160 160z"/></svg></span>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="ch15-02-deref.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M278.6 233.4c12.5 12.5 12.5 32.8 0 45.3l-160 160c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3L210.7 256 73.4 118.6c-12.5-12.5-12.5-32.8 0-45.3s32.8-12.5 45.3 0l160 160z"/></svg></span>
|
||
</a>
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
<a rel="prev" href="ch15-00-smart-pointers.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M41.4 233.4c-12.5 12.5-12.5 32.8 0 45.3l160 160c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 256 246.6 118.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-160 160z"/></svg></span>
|
||
</a>
|
||
|
||
<a rel="next prefetch" href="ch15-02-deref.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M278.6 233.4c12.5 12.5 12.5 32.8 0 45.3l-160 160c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3L210.7 256 73.4 118.6c-12.5-12.5-12.5-32.8 0-45.3s32.8-12.5 45.3 0l160 160z"/></svg></span>
|
||
</a>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<template id=fa-eye><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M288 32c-80.8 0-145.5 36.8-192.6 80.6C48.6 156 17.3 208 2.5 243.7c-3.3 7.9-3.3 16.7 0 24.6C17.3 304 48.6 356 95.4 399.4C142.5 443.2 207.2 480 288 480s145.5-36.8 192.6-80.6c46.8-43.5 78.1-95.4 93-131.1c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C433.5 68.8 368.8 32 288 32zM432 256c0 79.5-64.5 144-144 144s-144-64.5-144-144s64.5-144 144-144s144 64.5 144 144zM288 192c0 35.3-28.7 64-64 64c-11.5 0-22.3-3-31.6-8.4c-.2 2.8-.4 5.5-.4 8.4c0 53 43 96 96 96s96-43 96-96s-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6z"/></svg></span></template>
|
||
<template id=fa-eye-slash><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M38.8 5.1C28.4-3.1 13.3-1.2 5.1 9.2S-1.2 34.7 9.2 42.9l592 464c10.4 8.2 25.5 6.3 33.7-4.1s6.3-25.5-4.1-33.7L525.6 386.7c39.6-40.6 66.4-86.1 79.9-118.4c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C465.5 68.8 400.8 32 320 32c-68.2 0-125 26.3-169.3 60.8L38.8 5.1zM223.1 149.5C248.6 126.2 282.7 112 320 112c79.5 0 144 64.5 144 144c0 24.9-6.3 48.3-17.4 68.7L408 294.5c5.2-11.8 8-24.8 8-38.5c0-53-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6c0 10.2-2.4 19.8-6.6 28.3l-90.3-70.8zm223.1 298L373 389.9c-16.4 6.5-34.3 10.1-53 10.1c-79.5 0-144-64.5-144-144c0-6.9 .5-13.6 1.4-20.2L83.1 161.5C60.3 191.2 44 220.8 34.5 243.7c-3.3 7.9-3.3 16.7 0 24.6c14.9 35.7 46.2 87.7 93 131.1C174.5 443.2 239.2 480 320 480c47.8 0 89.9-12.9 126.2-32.5z"/></svg></span></template>
|
||
<template id=fa-copy><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M502.6 70.63l-61.25-61.25C435.4 3.371 427.2 0 418.7 0H255.1c-35.35 0-64 28.66-64 64l.0195 256C192 355.4 220.7 384 256 384h192c35.2 0 64-28.8 64-64V93.25C512 84.77 508.6 76.63 502.6 70.63zM464 320c0 8.836-7.164 16-16 16H255.1c-8.838 0-16-7.164-16-16L239.1 64.13c0-8.836 7.164-16 16-16h128L384 96c0 17.67 14.33 32 32 32h47.1V320zM272 448c0 8.836-7.164 16-16 16H63.1c-8.838 0-16-7.164-16-16L47.98 192.1c0-8.836 7.164-16 16-16H160V128H63.99c-35.35 0-64 28.65-64 64l.0098 256C.002 483.3 28.66 512 64 512h192c35.2 0 64-28.8 64-64v-32h-47.1L272 448z"/></svg></span></template>
|
||
<template id=fa-play><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg></span></template>
|
||
<template id=fa-clock-rotate-left><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M75 75L41 41C25.9 25.9 0 36.6 0 57.9V168c0 13.3 10.7 24 24 24H134.1c21.4 0 32.1-25.9 17-41l-30.8-30.8C155 85.5 203 64 256 64c106 0 192 86 192 192s-86 192-192 192c-40.8 0-78.6-12.7-109.7-34.4c-14.5-10.1-34.4-6.6-44.6 7.9s-6.6 34.4 7.9 44.6C151.2 495 201.7 512 256 512c141.4 0 256-114.6 256-256S397.4 0 256 0C185.3 0 121.3 28.7 75 75zm181 53c-13.3 0-24 10.7-24 24V256c0 6.4 2.5 12.5 7 17l72 72c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-65-65V152c0-13.3-10.7-24-24-24z"/></svg></span></template>
|
||
|
||
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="elasticlunr-ef4e11c1.min.js"></script>
|
||
<script src="mark-09e88c2c.min.js"></script>
|
||
<script src="searcher-09f2665d.js"></script>
|
||
|
||
<script src="clipboard-1626706a.min.js"></script>
|
||
<script src="highlight-abc7f01d.js"></script>
|
||
<script src="book-c22b7243.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
<script src="ferris-2317480c.js"></script>
|
||
|
||
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|