<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Advanced Types - 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="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme -->
<!-- Fetch Clipboard.js from CDN but have a local fallback -->
<script src="https://cdn.jsdelivr.net/clipboard.js/1.6.1/clipboard.min.js"></script>
<script>
if (typeof Clipboard == 'undefined') {
document.write(unescape("%3Cscript src='clipboard.min.js'%3E%3C/script%3E"));
}
</script>
</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;
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
document.querySelector('html').classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li><a href="ch01-00-introduction.html"><strong aria-hidden="true">1.</strong> Introduction</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-how-rust-is-made-and-nightly-rust.html"><strong aria-hidden="true">1.3.</strong> How Rust is Made and “Nightly Rust”</a></li></ol></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Guessing Game Tutorial</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"><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> Is Rust an Object-Oriented Programming Language?</a></li><li><ol class="section"><li><a href="ch17-01-what-is-oo.html"><strong aria-hidden="true">17.1.</strong> What Does Object-Oriented Mean?</a></li><li><a href="ch17-02-trait-objects.html"><strong aria-hidden="true">17.2.</strong> Trait Objects for Using Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong aria-hidden="true">17.3.</strong> Object-Oriented Design Pattern Implementations</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" class="active"><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-slow-requests.html"><strong aria-hidden="true">20.2.</strong> How Slow Requests Affect Throughput</a></li><li><a href="ch20-03-designing-the-interface.html"><strong aria-hidden="true">20.3.</strong> Designing the Thread Pool Interface</a></li><li><a href="ch20-04-storing-threads.html"><strong aria-hidden="true">20.4.</strong> Creating the Thread Pool and Storing Threads</a></li><li><a href="ch20-05-sending-requests-via-channels.html"><strong aria-hidden="true">20.5.</strong> Sending Requests to Threads Via Channels</a></li><li><a href="ch20-06-graceful-shutdown-and-cleanup.html"><strong aria-hidden="true">20.6.</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-newest-features.html"><strong aria-hidden="true">21.6.</strong> F - Newest Features</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="submenu">
<li><button class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li><button class="theme" id="rust">Rust</button></li>
<li><button class="theme" id="coal">Coal</button></li>
<li><button class="theme" id="navy">Navy</button></li>
<li><button class="theme" id="ayu">Ayu</button></li>
</ul>
</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>
<!-- 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="ch19-04-advanced-types.html#advanced-types" id="advanced-types"><h2>Advanced Types</h2></a>
<p>The Rust type system has some features that we’ve mentioned in this book but
haven’t yet discussed. We’ll start our discussion on advanced types with a more
general discussion about why newtypes are useful as types. We’ll then move to
type aliases, a feature similar to newtypes but with slightly different
semantics. We’ll also discuss the <code>!</code> type and dynamically sized types.</p>
<a class="header" href="ch19-04-advanced-types.html#using-the-newtype-pattern-for-type-safety-and-abstraction" id="using-the-newtype-pattern-for-type-safety-and-abstraction"><h3>Using the Newtype Pattern for Type Safety and Abstraction</h3></a>
<blockquote>
<p>This section assumes you’ve read the newtype pattern section in the “Advanced
Traits” section.</p>
</blockquote>
<p>The newtype pattern is useful for other things beyond what we’ve discussed so
far, including statically enforcing that values are never confused, and as
indication of the units of a value. We actually had an example of this in
Listing 19-23: the <code>Millimeters</code> and <code>Meters</code> structs both wrap <code>u32</code> values in
a newtype. If we write a function with a parameter of type <code>Millimeters</code>, we
won’t be able to compile a program that accidentally tries to call that
function with a value of type <code>Meters</code> or a plain <code>u32</code>.</p>
<p>Another use is in abstracting away some implementation details of a type: the
wrapper type can expose a public API that’s different to the API of the private
inner type, if we used it directly to restrict the available functionality, for
example.</p>
<p>Newtypes can also hide internal generic types. For example, we could provide a
<code>People</code> type to wrap a <code>HashMap<i32, String></code> that stores a person’s ID
associated with their name. Code using <code>People</code> would only interact with the
public API we provide, such as a method to add a name string to the <code>People</code>
collection, and that code wouldn’t need to know that we assign an <code>i32</code> ID to
names internally. The newtype pattern is a lightweight way to achieve
encapsulation to hide implementation details that we discussed in the
“Encapsulation that Hides Implementation Details” section of Chapter 17.</p>
<a class="header" href="ch19-04-advanced-types.html#type-aliases-create-type-synonyms" id="type-aliases-create-type-synonyms"><h3>Type Aliases Create Type Synonyms</h3></a>
<p>Alongside the newtype pattern, Rust provides the ability to declare a <em>type
alias</em> to give an existing type another name. For this we use the <code>type</code>
keyword. For example, we can create the alias <code>Kilometers</code> to <code>i32</code> like so:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
type Kilometers = i32;
#}</code></pre></pre>
<p>This means <code>Kilometers</code> is a <em>synonym</em> for <code>i32</code>; unlike the <code>Millimeters</code> and
<code>Meters</code> types we created in Listing 19-23, <code>Kilometers</code> is not a separate, new
type. Values that have the type <code>Kilometers</code> will be treated exactly the same
as values of type <code>i32</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
type Kilometers = i32;
let x: i32 = 5;
let y: Kilometers = 5;
println!("x + y = {}", x + y);
#}</code></pre></pre>
<p>Because <code>Kilometers</code> and <code>i32</code>, are the same type, we can add values of both
types, and we can also pass <code>Kilometers</code> values to functions that take <code>i32</code>
parameters. With this method, though, we don’t get the type checking benefits
that we get from the newtype pattern discussed in the previous section.</p>
<p>The main use case for type synonyms is to reduce repetition. For example, we
may have a lengthy type like this:</p>
<pre><code class="language-rust ignore">Box<Fn() + Send + 'static>
</code></pre>
<p>Writing this out in function signatures and as type annotations all over the
place can be tiresome and error-prone. Imagine having a project full of code
like that in Listing 19-32:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let f: Box<Fn() + Send + 'static> = Box::new(|| println!("hi"));
fn takes_long_type(f: Box<Fn() + Send + 'static>) {
// --snip--
}
fn returns_long_type() -> Box<Fn() + Send + 'static> {
// --snip--
# Box::new(|| ())
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-32: Using a long type in many places</span></p>
<p>A type alias makes this code more manageable by reducing the repetition. Here,
we’ve introduced an alias named <code>Thunk</code> for the verbose type, and can replace
all uses of the type with the shorter <code>Thunk</code> as shown in Listing 19-33:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
type Thunk = Box<Fn() + Send + 'static>;
let f: Thunk = Box::new(|| println!("hi"));
fn takes_long_type(f: Thunk) {
// --snip--
}
fn returns_long_type() -> Thunk {
// --snip--
# Box::new(|| ())
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-33: Introducing a type alias <code>Thunk</code> to reduce
repetition</span></p>
<p>Much easier to read and write! Choosing a good name for a type alias can help
communicate your intent as well (<em>thunk</em> is a word for code to be evaluated at
a later time, so it’s an appropriate name for a closure that gets stored).</p>
<p>Type aliases are also commonly used with the <code>Result<T, E></code> type for reducing
repetition. Consider the <code>std::io</code> module in the standard library. I/O
operations often return a <code>Result<T, E></code> to handle situations when operations
fail to work. This library has a <code>std::io::Error</code> struct that represents all
possible I/O errors. Many of the functions in <code>std::io</code> will be returning
<code>Result<T, E></code> where the <code>E</code> is <code>std::io::Error</code>, such as these functions in
the <code>Write</code> trait:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
use std::io::Error;
use std::fmt;
pub trait Write {
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>;
fn flush(&mut self) -> Result<(), Error>;
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>;
fn write_fmt(&mut self, fmt: fmt::Arguments) -> Result<(), Error>;
}
#}</code></pre></pre>
<p>We have <code>Result<..., Error></code> repeated a lot. As such, <code>std::io</code> has this type
alias declaration:</p>
<pre><code class="language-rust ignore">type Result<T> = Result<T, std::io::Error>;
</code></pre>
<p>Because this is in the <code>std::io</code> module, we can use the fully qualified alias
<code>std::io::Result<T></code>; that is, a <code>Result<T, E></code> with the <code>E</code> filled in as
<code>std::io::Error</code>. The <code>Write</code> trait function signatures end up looking like
this:</p>
<pre><code class="language-rust ignore">pub trait Write {
fn write(&mut self, buf: &[u8]) -> Result<usize>;
fn flush(&mut self) -> Result<()>;
fn write_all(&mut self, buf: &[u8]) -> Result<()>;
fn write_fmt(&mut self, fmt: Arguments) -> Result<()>;
}
</code></pre>
<p>The type alias helps in two ways: this is easier to write <em>and</em> it gives us a
consistent interface across all of <code>std::io</code>. Because it’s an alias, it is just
another <code>Result<T, E></code>, which means we can use any methods that work on
<code>Result<T, E></code> with it, as well as special syntax like <code>?</code>.</p>
<a class="header" href="ch19-04-advanced-types.html#the--never-type-that-never-returns" id="the--never-type-that-never-returns"><h3>The <code>!</code> Never Type that Never Returns</h3></a>
<p>Rust has a special type named <code>!</code> that’s known in type theory lingo as the
<em>empty type</em>, because it has no values. We prefer to call it the <em>never type</em>,
because it stands in the place of the return type when a function will never
return. For example:</p>
<pre><code class="language-rust ignore">fn bar() -> ! {
// --snip--
}
</code></pre>
<p>This is read as “the function <code>bar</code> returns never.” Functions that return never
are called <em>diverging functions</em>. We can’t create values of the type <code>!</code>, so
<code>bar</code> can never possibly return.</p>
<p>But what use is a type you can never create values for? If you think all the
way back to Chapter 2, we had some code that looked like the code we’ve
reproduced here in Listing 19-34:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# let guess = "3";
# loop {
let guess: u32 = match guess.trim().parse() {
Ok(num) => num,
Err(_) => continue,
};
# break;
# }
#}</code></pre></pre>
<p><span class="caption">Listing 19-34: A <code>match</code> with an arm that ends in
<code>continue</code></span></p>
<p>At the time, we skipped over some details in this code. In Chapter 6 in “The
<code>match</code> Control Flow Operator” section, we covered that <code>match</code> arms must all
return the same type. This, for example, doesn’t work:</p>
<pre><code class="language-rust ignore">let guess = match guess.trim().parse() {
Ok(_) => 5,
Err(_) => "hello",
}
</code></pre>
<p>The type of <code>guess</code> here would have to be both an integer and a string, and
Rust requires that <code>guess</code> can only have one type. So what does <code>continue</code>
return? How were we allowed to return a <code>u32</code> from one arm and have another arm
that ends with <code>continue</code> in Listing 19-34?</p>
<p>As you may have guessed, <code>continue</code> has a value of <code>!</code>. That is, when Rust goes
to compute the type of <code>guess</code>, it looks at both of the match arms, the former
with a value of <code>u32</code>, and the latter a value of <code>!</code>. Because <code>!</code> can never
have a value, Rust decides that the type of <code>guess</code> is <code>u32</code>.</p>
<p>The formal way of describing this behavior is that expressions of type <code>!</code> can
be coerced into any other type. We’re allowed to end this <code>match</code> arm with
<code>continue</code> because <code>continue</code> doesn’t actually return a value; it instead moves
control back to the top of the loop, so in the <code>Err</code> case, we never actually
assign a value to <code>guess</code>.</p>
<!-- I'm not sure I'm following what would then occur in the event of an error,
literally nothing? -->
<!-- The block returns control to the enclosing loop; I'm not sure how to
clarify this other than what we already have here, do you have any suggestions?
I wouldn't say it's "literally nothing" because it does do something, it
returns control to the loop and the next iteration of the loop happens...
/Carol -->
<p>The never type is also useful with <code>panic!</code>. Remember the <code>unwrap</code> function
that we call on <code>Option<T></code> values to produce a value or panic? Here’s its
definition:</p>
<pre><code class="language-rust ignore">impl<T> Option<T> {
pub fn unwrap(self) -> T {
match self {
Some(val) => val,
None => panic!("called `Option::unwrap()` on a `None` value"),
}
}
}
</code></pre>
<p>Here, the same thing happens as in the <code>match</code> in Listing 19-34: we know that
<code>val</code> has the type <code>T</code>, and <code>panic!</code> has the type <code>!</code>, so the result of the
overall <code>match</code> expression is <code>T</code>. This works because <code>panic!</code> doesn’t produce
a value; it ends the program. In the <code>None</code> case, we won’t be returning a value
from <code>unwrap</code>, so this code is valid.</p>
<p>One final expression that has the type <code>!</code> is a <code>loop</code>:</p>
<pre><code class="language-rust ignore">print!("forever ");
loop {
print!("and ever ");
}
</code></pre>
<p>Here, the loop never ends, so the value of the expression is <code>!</code>. This wouldn’t
be true if we included a <code>break</code>, however, as the loop would terminate when it
got to the <code>break</code>.</p>
<a class="header" href="ch19-04-advanced-types.html#dynamically-sized-types--sized" id="dynamically-sized-types--sized"><h3>Dynamically Sized Types & <code>Sized</code></h3></a>
<p>Due to Rust’s need to know things like how much space to allocate for a value
of a particular type, there’s a corner of its type system that can be
confusing: the concept of <em>dynamically sized types</em>. Sometimes referred to as
‘DSTs’ or ‘unsized types’, these types let us talk about types whose size we
can only know at runtime.</p>
<p>Let’s dig into the details of a dynamically sized type that we’ve been using
this whole book: <code>str</code>. That’s right, not <code>&str</code>, but <code>str</code> on its own, is a
DST. We can’t know how long the string is until runtime, meaning we can’t
create a variable of type <code>str</code>, nor can we take an argument of type <code>str</code>.
Consider this code, which does not work:</p>
<pre><code class="language-rust ignore">let s1: str = "Hello there!";
let s2: str = "How's it going?";
</code></pre>
<!-- Why do they need to have the same memory layout? Perhaps I'm not
understanding fully what is meant by the memory layout, is it worth explaining
that a little in this section? -->
<!-- I've reworded /Carol -->
<p>Rust needs to know how much memory to allocate for any value of a particular
type, and all values of a type must use the same amount of memory. If we were
allowed to write this code, that would mean these two <code>str</code> values would need
to take up the exact same amount of space, but they have different lengths:
<code>s1</code> needs 12 bytes of storage, and <code>s2</code> needs 15. This is why it’s not
possible to create a variable holding a dynamically sized type.</p>
<p>So what to do? You already know the answer in this case: we make the types of
<code>s1</code> and <code>s2</code> a <code>&str</code> rather than <code>str</code>. If you think back to the “String
Slices” section of Chapter 4, we said that the slice data structure stores the
starting position and the length of the slice.</p>
<p>So while a <code>&T</code> is a single value that stores the memory address of where the
<code>T</code> is located, a <code>&str</code> is <em>two</em> values: the address of the <code>str</code> and its
length. As such, a <code>&str</code> has a size we can know at compile time: it’s two
times the size of a <code>usize</code> in length. That is, we always know the size of a
<code>&str</code>, no matter how long the string it refers to is. This is the general way
in which dynamically sized types are used in Rust; they have an extra bit of
metadata that stores the size of the dynamic information. This leads us to the
golden rule of dynamically sized types: we must always put values of
dynamically sized types behind a pointer of some kind.</p>
<p>We can combine <code>str</code> with all kinds of pointers: <code>Box<str></code>, for example, or
<code>Rc<str></code>. In fact, you’ve seen this before, but with a different dynamically
sized type: traits. Every trait is a dynamically sized type we can refer to by
using the name of the trait. In Chapter 17 in the “Using Trait Objects that
Allow for Values of Different Types” section, we mentioned that in order to use
traits as trait objects, we have to put them behind a pointer like <code>&Trait</code> or
<code>Box<Trait></code> (<code>Rc<Trait></code> would work too). Traits being dynamically sized is
the reason we have to do that!</p>
<a class="header" href="ch19-04-advanced-types.html#the-sized-trait" id="the-sized-trait"><h4>The <code>Sized</code> Trait</h4></a>
<!-- If we end up keeping the section on object safety in ch 17, we should add
a back reference here. /Carol -->
<!-- I think we dropped that one, right? -->
<!-- We cut a large portion of it, including the part about `Sized`, so I
didn't add a back reference. /Carol -->
<p>To work with DSTs, Rust has a particular trait to determine if a type’s size is
known at compile time or not: the <code>Sized</code> trait. This trait is automatically
implemented for everything whose size is known at compile time. In addition,
Rust implicitly adds a bound on <code>Sized</code> to every generic function. That is, a
generic function definition like this:</p>
<pre><code class="language-rust ignore">fn generic<T>(t: T) {
// --snip--
}
</code></pre>
<p>is actually treated as if we had written this:</p>
<pre><code class="language-rust ignore">fn generic<T: Sized>(t: T) {
// --snip--
}
</code></pre>
<p>By default, generic functions will only work on types that have a known size at
compile time. There is, however, special syntax you can use to relax this
restriction:</p>
<pre><code class="language-rust ignore">fn generic<T: ?Sized>(t: &T) {
// --snip--
}
</code></pre>
<p>A trait bound on <code>?Sized</code> is the opposite of a trait bound on <code>Sized</code>; that is,
we would read this as “<code>T</code> may or may not be <code>Sized</code>”. This syntax is only
available for <code>Sized</code>, no other traits.</p>
<p>Also note we switched the type of the <code>t</code> parameter from <code>T</code> to <code>&T</code>: because
the type might not be <code>Sized</code>, we need to use it behind some kind of pointer.
In this case, we’ve chosen a reference.</p>
<p>Next let’s talk about functions and closures!</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch19-03-advanced-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="ch19-05-advanced-functions-and-closures.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="ch19-03-advanced-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="ch19-05-advanced-functions-and-closures.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>
<!-- Local fallback for Font Awesome -->
<script>
if (getComputedStyle(document.querySelector(".fa")).fontFamily !== "FontAwesome") {
var link = document.createElement('link');
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = '_FontAwesome/css/font-awesome.css';
document.head.insertBefore(link, document.head.firstChild)
}
</script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS script -->
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
fdedb3cf2140df9b6d419a2338ab1caa
>
files
>
658
