<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Advanced Traits - 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" class="active"><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-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-03-advanced-traits.html#advanced-traits" id="advanced-traits"><h2>Advanced Traits</h2></a>
<p>We first covered traits in the “Traits: Defining Shared Behavior” section of
Chapter 10 but, like lifetimes, we didn’t get to some of the more advanced
details. Now that we know more Rust, we can get into the nitty-gritty.</p>
<a class="header" href="ch19-03-advanced-traits.html#associated-types-specify-placeholder-types-in-trait-definitions" id="associated-types-specify-placeholder-types-in-trait-definitions"><h3>Associated Types Specify Placeholder Types in Trait Definitions</h3></a>
<p><em>Associated types</em> are a way of associating a type placeholder with a trait
such that the trait method definitions can use these placeholder types in their
signatures. The implementor of a trait will specify the concrete type to be
used in this type’s place for the particular implementation. That way, we can
define a trait that uses some types without needing to know exactly what those
types are until the trait is implemented.</p>
<!-- Can you say what this is useful for -- it seems like a way to not to have
to specify a type prior to use, is that right? -->
<!-- Prior to trait implementation, yes. /Carol -->
<p>We’ve described most of the things in this chapter as being needed very rarely.
Associated types are somewhere in the middle; they’re used more rarely than the
rest of the book, but more commonly than many of the things in this chapter.</p>
<p>One example of a trait with an associated type is the <code>Iterator</code> trait provided
by the standard library. This has an associated type named <code>Item</code> that stands
in for the type of the values it’s iterating over. In “The <code>Iterator</code> Trait and
the <code>next</code> Method” section of Chapter 13, we mentioned that the definition of
the <code>Iterator</code> trait is as shown in Listing 19-20:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
pub trait Iterator {
type Item;
fn next(&mut self) -> Option<Self::Item>;
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-20: The definition of the <code>Iterator</code> trait
that has an associated type <code>Item</code></span></p>
<p>The <code>Iterator</code> trait has an associated type named <code>Item</code>. This is a placeholder
type, and the <code>next</code> method will return values of type <code>Option<Self::Item></code>.
Implementors of this trait will specify the concrete type for <code>Item</code>, and the
<code>next</code> method will return an <code>Option</code> containing a value of that concrete type.</p>
<a class="header" href="ch19-03-advanced-traits.html#associated-types-versus-generics" id="associated-types-versus-generics"><h4>Associated Types Versus Generics</h4></a>
<p>This may seem like a similar concept to generics, in that it allows us to
define a function without specifying what types it can deal with. So why use
associated types?</p>
<p>Let’s examine the difference with an example that implements the <code>Iterator</code>
trait on the <code>Counter</code> struct from Chapter 13. In Listing 13-21, we specified
that the <code>Item</code> type was <code>u32</code>:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><code class="language-rust ignore">impl Iterator for Counter {
type Item = u32;
fn next(&mut self) -> Option<Self::Item> {
// --snip--
</code></pre>
<p>This feels similar to generics. So why not just define the <code>Iterator</code> trait
with generics as shown in Listing 19-21?</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
pub trait Iterator<T> {
fn next(&mut self) -> Option<T>;
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-21: A hypothetical definition of the
<code>Iterator</code> trait using generics</span></p>
<p>The difference lies in the fact that when using generics like in Listing 19-21,
we have to annotate the types in each implementation. This is because we can
also implement <code>Iterator<String> for Counter</code>, or any other type, which would
give us multiple implementations of <code>Iterator</code> for <code>Counter</code>. In other words,
when a trait has a generic parameter, it can be implemented for a type multiple
times, changing the concrete types of the generic type parameters each time.
When we use the <code>next</code> method on <code>Counter</code>, we’d then have to provide type
annotations to indicate which implementation of <code>Iterator</code> we wanted to use.</p>
<p>With associated types, we don’t need to annotate types because we can’t
implement a trait on a type multiple times. With Listing 19-20, we can only
choose once what the type of <code>Item</code> will be, because there can only be one <code>impl Iterator for Counter</code>. We don’t have to specify that we want an iterator of
<code>u32</code> values everywhere that we call <code>next</code> on <code>Counter</code>.</p>
<a class="header" href="ch19-03-advanced-traits.html#default-generic-type-parameters-and-operator-overloading" id="default-generic-type-parameters-and-operator-overloading"><h3>Default Generic Type Parameters and Operator Overloading</h3></a>
<p>When we use generic type parameters, we can specify a default concrete type for
the generic type. This eliminates the need for implementors of the trait to
specify a concrete type if the default type works. The syntax for specifying a
default type for a generic type is to put <code><PlaceholderType=ConcreteType></code> when
declaring the generic type.</p>
<p>A great example of a situation where this is useful is with operator
overloading. Operator overloading is customizing the behavior of an operator
(like <code>+</code>) in particular situations.</p>
<!-- Are we safe in assuming the reader is familiar with operator overloading
and why/when to use it, or is it worth giving a quick definition here? -->
<!-- Added /Carol -->
<p>Rust does not allow you to create your own operators or overload arbitrary
operators, but you <em>can</em> overload the operations and corresponding traits
listed in <code>std::ops</code> by implementing the traits associated with the operator.
For example, in Listing 19-22 we overload the <code>+</code> operator to add two <code>Point</code>
instances together. We do this by implementing the <code>Add</code> trait on a <code>Point</code>
struct:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">use std::ops::Add;
#[derive(Debug,PartialEq)]
struct Point {
x: i32,
y: i32,
}
impl Add for Point {
type Output = Point;
fn add(self, other: Point) -> Point {
Point {
x: self.x + other.x,
y: self.y + other.y,
}
}
}
fn main() {
assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 },
Point { x: 3, y: 3 });
}
</code></pre></pre>
<p><span class="caption">Listing 19-22: Implementing the <code>Add</code> trait to overload
the <code>+</code> operator for <code>Point</code> instances</span></p>
<p>The <code>add</code> method adds the <code>x</code> values of two <code>Point</code> instances together and the
<code>y</code> values of two <code>Point</code> instances together to create a new <code>Point</code>. The <code>Add</code>
trait has an associated type named <code>Output</code> that determines the type returned
from the <code>add</code> method.</p>
<p>The default generic type here is within the <code>Add</code> trait. Here’s its definition:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
trait Add<RHS=Self> {
type Output;
fn add(self, rhs: RHS) -> Self::Output;
}
#}</code></pre></pre>
<p>This should look generally familiar, as a trait with one method and an
associated type. The new part here is the <code>RHS=Self</code> in the angle brackets:
this syntax is called <em>default type parameters</em>. The <code>RHS</code> generic type
parameter---short for “right hand side”---that’s used to define the type of the
<code>rhs</code> parameter in the <code>add</code> method. If we don’t specify a concrete type for
<code>RHS</code> when we implement the <code>Add</code> trait, the type of <code>RHS</code> will default to
<code>Self</code>, which will be the type we’re implementing <code>Add</code> on.</p>
<!-- Can you say what we're looking out for in this next trait -->
<!-- Done/reworked to be less repetitive with the Point example /Carol -->
<p>When we implemented <code>Add</code> for <code>Point</code>, we made use of the default for <code>RHS</code>
because we wanted to add two <code>Point</code> instances together. Let’s look at an
example of implementing the <code>Add</code> trait where we want to customize the <code>RHS</code>
type rather than using the default.</p>
<p>We have two structs holding values in different units, <code>Millimeters</code> and
<code>Meters</code>. We want to be able to add values in millimeters to values in meters,
and have the implementation of <code>Add</code> do the conversion correctly. We can
implement <code>Add</code> for <code>Millimeters</code> with <code>Meters</code> as the right hand side as shown
in Listing 19-23:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
use std::ops::Add;
struct Millimeters(u32);
struct Meters(u32);
impl Add<Meters> for Millimeters {
type Output = Millimeters;
fn add(self, other: Meters) -> Millimeters {
Millimeters(self.0 + (other.0 * 1000))
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-23: Implementing the <code>Add</code> trait on
<code>Millimeters</code> to be able to add <code>Millimeters</code> to <code>Meters</code></span></p>
<p>To be able to add <code>Millimeters</code> and <code>Meters</code>, we specify <code>impl Add<Meters></code> to
set the value of the <code>RHS</code> type parameter instead of using the default of
<code>Self</code>.</p>
<p>Default type parameters are used in two main ways:</p>
<ol>
<li>To extend a type without breaking existing code.</li>
<li>To allow customization in specific cases most users won’t need.</li>
</ol>
<!-- Above, in 2., do you mean customization used in corner cases? -->
<!-- Yes, I'm not sure how that's different than what we've stated here or how
it could be clearer /Carol-->
<p>The standard library’s <code>Add</code> trait is an example of the second purpose: most of
the time, you’re adding two like types together, but it gives the ability for
customizing beyond that. Using a default type parameter in the <code>Add</code> trait
definition means you don’t have to specify the extra parameter most of the
time. In other words, a little bit of implementation boilerplate isn’t needed,
making it easier to use the trait.</p>
<p>The first purpose is similar, but in reverse: if we want to add a type
parameter to an existing trait, we can give it a default to let us extend the
functionality of the trait without breaking the existing implementation code.</p>
<a class="header" href="ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name" id="fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name"><h3>Fully Qualified Syntax for Disambiguation: Calling Methods with the Same Name</h3></a>
<p>Nothing in Rust prevents a trait from having a method with the same name as
another trait’s method, nor can it prevent us from implementing both of these
traits on one type. It’s also possible to have a method implemented directly on
the type with the same name as methods from traits as well!</p>
<!-- Same name as the type, you mean? -->
<!-- No, the same name as methods implemented from traits. I've tried to
clarify /Carol -->
<p>When calling methods with the same name, then, we need to tell Rust which one
we want to use. Consider the code in Listing 19-24 where we’ve defined two
traits, <code>Pilot</code> and <code>Wizard</code>, that both have a method called <code>fly</code>. We then
implement both traits on a type <code>Human</code> that itself already has a method named
<code>fly</code> implemented on it. Each <code>fly</code> method does something different:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
trait Pilot {
fn fly(&self);
}
trait Wizard {
fn fly(&self);
}
struct Human;
impl Pilot for Human {
fn fly(&self) {
println!("This is your captain speaking.");
}
}
impl Wizard for Human {
fn fly(&self) {
println!("Up!");
}
}
impl Human {
fn fly(&self) {
println!("*waving arms furiously*");
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-24: Two traits defined to have a <code>fly</code> method,
and implementations of those traits on the <code>Human</code> type in addition to a <code>fly</code>
method on <code>Human</code> directly</span></p>
<p>When we call <code>fly</code> on an instance of <code>Human</code>, the compiler defaults to calling
the method that is directly implemented on the type, as shown in Listing 19-25:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># trait Pilot {
# fn fly(&self);
# }
#
# trait Wizard {
# fn fly(&self);
# }
#
# struct Human;
#
# impl Pilot for Human {
# fn fly(&self) {
# println!("This is your captain speaking.");
# }
# }
#
# impl Wizard for Human {
# fn fly(&self) {
# println!("Up!");
# }
# }
#
# impl Human {
# fn fly(&self) {
# println!("*waving arms furiously*");
# }
# }
#
fn main() {
let person = Human;
person.fly();
}
</code></pre></pre>
<p><span class="caption">Listing 19-25: Calling <code>fly</code> on an instance of
<code>Human</code></span></p>
<p>Running this will print out <code>*waving arms furiously*</code>, which shows that Rust
called the <code>fly</code> method implemented on <code>Human</code> directly.</p>
<p>In order to call the <code>fly</code> methods from either the <code>Pilot</code> trait or the
<code>Wizard</code> trait, we need to use more explicit syntax in order to specify which
<code>fly</code> method we mean. This syntax is demonstrated in Listing 19-26:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># trait Pilot {
# fn fly(&self);
# }
#
# trait Wizard {
# fn fly(&self);
# }
#
# struct Human;
#
# impl Pilot for Human {
# fn fly(&self) {
# println!("This is your captain speaking.");
# }
# }
#
# impl Wizard for Human {
# fn fly(&self) {
# println!("Up!");
# }
# }
#
# impl Human {
# fn fly(&self) {
# println!("*waving arms furiously*");
# }
# }
#
fn main() {
let person = Human;
Pilot::fly(&person);
Wizard::fly(&person);
person.fly();
}
</code></pre></pre>
<p><span class="caption">Listing 19-26: Specifying which trait’s <code>fly</code> method we
want to call</span></p>
<p>Specifying the trait name before the method name clarifies to Rust which
implementation of <code>fly</code> we want to call. We could also choose to write
<code>Human::fly(&person)</code>, which is equivalent to <code>person.fly()</code> that we had in
Listing 19-26, but is a bit longer to write if we don’t need to disambiguate.</p>
<p>Running this code will print:</p>
<pre><code class="language-text">This is your captain speaking.
Up!
*waving arms furiously*
</code></pre>
<p>Because the <code>fly</code> method takes a <code>self</code> parameter, if we had two <em>types</em> that
both implement one <em>trait</em>, Rust can figure out which implementation of a trait
to use based on the type of <code>self</code>.</p>
<p>However, associated functions that are part of traits don’t have a <code>self</code>
parameter. When two types in the same scope implement that trait, Rust can’t
figure out which type we mean unless we use <em>fully qualified syntax</em>. For
example, take the <code>Animal</code> trait in Listing 19-27 that has the associated
function <code>baby_name</code>, the implementation of <code>Animal</code> for the struct <code>Dog</code>, and
the associated function <code>baby_name</code> defined on <code>Dog</code> directly:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">trait Animal {
fn baby_name() -> String;
}
struct Dog;
impl Dog {
fn baby_name() -> String {
String::from("Spot")
}
}
impl Animal for Dog {
fn baby_name() -> String {
String::from("puppy")
}
}
fn main() {
println!("A baby dog is called a {}", Dog::baby_name());
}
</code></pre></pre>
<p><span class="caption">Listing 19-27: A trait with an associated function and a
type that has an associated function with the same name that also implements
the trait</span></p>
<p>This code is for an animal shelter where they want to give all puppies the name
Spot, which is implemented in the <code>baby_name</code> associated function that is
defined on <code>Dog</code>. The <code>Dog</code> type also implements the trait <code>Animal</code>, which
describes characteristics that all animals have. Baby dogs are called puppies,
and that is expressed in the implementation of the <code>Animal</code> trait on <code>Dog</code> in
the <code>baby_name</code> function associated with the <code>Animal</code> trait.</p>
<p>In <code>main</code>, we’re calling the <code>Dog::baby_name</code> function, which calls the
associated function defined on <code>Dog</code> directly. This code prints:</p>
<pre><code class="language-text">A baby dog is called a Spot
</code></pre>
<p>This isn’t what we wanted. We want to call the <code>baby_name</code> function that’s part
of the <code>Animal</code> trait that we implemented on <code>Dog</code> so that we print <code>A baby dog is called a puppy</code>. The technique we used in Listing 19-26 doesn’t help here;
if we change <code>main</code> to be the code in Listing 19-28, we’ll get a compilation
error:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><code class="language-rust ignore">fn main() {
println!("A baby dog is called a {}", Animal::baby_name());
}
</code></pre>
<p><span class="caption">Listing 19-28: Attempting to call the <code>baby_name</code>
function from the <code>Animal</code> trait, but Rust doesn’t know which implementation to
use</span></p>
<p>Because <code>Animal::baby_name</code> is an associated function rather than a method, and
thus doesn’t have a <code>self</code> parameter, Rust has no way to figure out which
implementation of <code>Animal::baby_name</code> we want. We’ll get this compiler error:</p>
<pre><code class="language-text">error[E0283]: type annotations required: cannot resolve `_: Animal`
--> src/main.rs:20:43
|
20 | println!("A baby dog is called a {}", Animal::baby_name());
| ^^^^^^^^^^^^^^^^^
|
= note: required by `Animal::baby_name`
</code></pre>
<p>To disambiguate and tell Rust that we want to use the implementation of
<code>Animal</code> for <code>Dog</code>, we need to use <em>fully qualified syntax</em>, which is the most
specific we can be when calling a function. Listing 19-29 demonstrates how to
use fully qualified syntax:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># trait Animal {
# fn baby_name() -> String;
# }
#
# struct Dog;
#
# impl Dog {
# fn baby_name() -> String {
# String::from("Spot")
# }
# }
#
# impl Animal for Dog {
# fn baby_name() -> String {
# String::from("puppy")
# }
# }
#
fn main() {
println!("A baby dog is called a {}", <Dog as Animal>::baby_name());
}
</code></pre></pre>
<p><span class="caption">Listing 19-29: Using fully qualified syntax to specify
that we want to call the <code>baby_name</code> function from the <code>Animal</code> trait as
implemented on <code>Dog</code></span></p>
<p>We’re providing Rust with a type annotation within the angle brackets, and
we’re specifying that we want to call the <code>baby_name</code> method from the <code>Animal</code>
trait as implemented on <code>Dog</code> by saying that we want to treat the <code>Dog</code> type as
an <code>Animal</code> for this function call. This code will now print what we want:</p>
<pre><code class="language-text">A baby dog is called a puppy
</code></pre>
<p>In general, fully qualified syntax is defined as:</p>
<pre><code class="language-rust ignore"><Type as Trait>::function(receiver_if_method, next_arg, ...);
</code></pre>
<p>For associated functions, there would not be a <code>receiver</code>, there would only be
the list of other arguments. We could choose to use fully qualified syntax
everywhere that we call functions or methods. However, we’re allowed to leave
out any part of this syntax that Rust is able to figure out from other
information in the program. We only need to use this more verbose syntax in
cases where there are multiple implementations that use the same name and Rust
needs help in order to know which implementation we want to call.</p>
<a class="header" href="ch19-03-advanced-traits.html#using-supertraits-to-require-one-traits-functionality-within-another-trait" id="using-supertraits-to-require-one-traits-functionality-within-another-trait"><h3>Using Supertraits to Require One Trait’s Functionality Within Another Trait</h3></a>
<p>Sometimes, we may need one trait to use another trait’s functionality. In this
case, we need to be able to rely on the dependent trait also being implemented.
The trait we’re relying on is a <em>supertrait</em> of the trait we’re implementing.</p>
<p>For example, let’s say we want to make an <code>OutlinePrint</code> trait with an
<code>outline_print</code> method that will print out a value framed in asterisks. That
is, given a <code>Point</code> struct that implements <code>Display</code> to result in <code>(x, y)</code>,
when we call <code>outline_print</code> on a <code>Point</code> instance that has 1 for <code>x</code> and 3 for
<code>y</code>, it should print the following:</p>
<pre><code class="language-text">**********
* *
* (1, 3) *
* *
**********
</code></pre>
<p>In the implementation of <code>outline_print</code>, we want to use the <code>Display</code> trait’s
functionality. We therefore need to specify that the <code>OutlinePrint</code> trait will
only work for types that also implement <code>Display</code> and therefore provide the
functionality that <code>OutlinePrint</code> needs. We can do that in the trait definition
by specifying <code>OutlinePrint: Display</code>. This is similar to adding a trait bound
to the trait. Listing 19-30 shows an implementation of the <code>OutlinePrint</code> trait:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
use std::fmt;
trait OutlinePrint: fmt::Display {
fn outline_print(&self) {
let output = self.to_string();
let len = output.len();
println!("{}", "*".repeat(len + 4));
println!("*{}*", " ".repeat(len + 2));
println!("* {} *", output);
println!("*{}*", " ".repeat(len + 2));
println!("{}", "*".repeat(len + 4));
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 19-30: Implementing the <code>OutlinePrint</code> trait that
requires the functionality from <code>Display</code></span></p>
<p>Because we’ve specified that <code>OutlinePrint</code> requires the <code>Display</code> trait, we
can use the <code>to_string</code> function that’s automatically implemented for any type
that implements <code>Display</code>. If we tried to use <code>to_string</code> without adding<code>: Display</code> after the trait name we’d get an error saying that no method named
<code>to_string</code> was found for the type <code>&Self</code> in the current scope.</p>
<p>Let’s see what happens if we try to implement <code>OutlinePrint</code> on a type that
doesn’t implement <code>Display</code>, such as the <code>Point</code> struct:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# trait OutlinePrint {}
struct Point {
x: i32,
y: i32,
}
impl OutlinePrint for Point {}
#}</code></pre></pre>
<p>We’ll get an error saying that <code>Display</code> is required but not implemented:</p>
<pre><code class="language-text">error[E0277]: the trait bound `Point: std::fmt::Display` is not satisfied
--> src/main.rs:20:6
|
20 | impl OutlinePrint for Point {}
| ^^^^^^^^^^^^ `Point` cannot be formatted with the default formatter;
try using `:?` instead if you are using a format string
|
= help: the trait `std::fmt::Display` is not implemented for `Point`
</code></pre>
<p>Once we implement <code>Display</code> on <code>Point</code> and satisfy the constraint that
<code>OutlinePrint</code> requires, like so:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Point {
# x: i32,
# y: i32,
# }
#
use std::fmt;
impl fmt::Display for Point {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "({}, {})", self.x, self.y)
}
}
#}</code></pre></pre>
<p>Then, implementing the <code>OutlinePrint</code> trait on <code>Point</code> will compile
successfully and we can call <code>outline_print</code> on a <code>Point</code> instance to display
it within an outline of asterisks.</p>
<a class="header" href="ch19-03-advanced-traits.html#the-newtype-pattern-to-implement-external-traits-on-external-types" id="the-newtype-pattern-to-implement-external-traits-on-external-types"><h3>The Newtype Pattern to Implement External Traits on External Types</h3></a>
<p>In Chapter 10 in the “Implementing a Trait on a Type” section, we mentioned the
orphan rule that says we’re allowed to implement a trait on a type as long as
either the trait or the type are local to our crate. It is possible to get
around this restriction using the <em>newtype pattern</em>, which involves creating a
new type in a tuple struct (we covered tuple structs in the “Tuple Structs
without Named Fields to Create Different Types” section of Chapter 5). The
tuple struct will have one field and will be a thin wrapper around the type we
want to implement a trait for. Then the wrapper type is local to our crate, and
we can implement the trait on the wrapper. “Newtype” is a term originating from
the Haskell programming language. There’s no runtime performance penalty for
using this pattern, and the wrapper type is elided at compile time.</p>
<p>As an example, we want to implement <code>Display</code> on <code>Vec</code>, which the orphan rule
prevents us from doing directly because the <code>Display</code> trait and the <code>Vec</code> type
are both defined outside of our crate. We can make a <code>Wrapper</code> struct that
holds an instance of <code>Vec</code>, then we can implement <code>Display</code> on <code>Wrapper</code> and
use the <code>Vec</code> value as shown in Listing 19-31:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">use std::fmt;
struct Wrapper(Vec<String>);
impl fmt::Display for Wrapper {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "[{}]", self.0.join(", "))
}
}
fn main() {
let w = Wrapper(vec![String::from("hello"), String::from("world")]);
println!("w = {}", w);
}
</code></pre></pre>
<p><span class="caption">Listing 19-31: Creating a <code>Wrapper</code> type around
<code>Vec<String></code> to be able to implement <code>Display</code></span></p>
<p>The implementation of <code>Display</code> uses <code>self.0</code> to access the inner <code>Vec</code>,
because <code>Wrapper</code> is a tuple struct and the <code>Vec</code> is the item at index 0 in the
tuple. Then we can use the functionality of the <code>Display</code> type on <code>Wrapper</code>.</p>
<!-- What is self.0? I think the syntax here might need a bit more talking
through -->
<!-- `Wrapper` is a tuple struct; we covered those in chapter 5, added a back
reference to that section in the first paragraph of this section but we've used
the `.0` syntax in multiple places before here /Carol -->
<p>The downside of this method is that, because <code>Wrapper</code> is a new type, it
doesn’t have the methods of the value it’s holding; we’d have to implement all
the methods of <code>Vec</code> directly on <code>Wrapper</code>, so that it can delegate to
<code>self.0</code>--- this allows us to treat <code>Wrapper</code> exactly like a <code>Vec</code>. If we
wanted the new type to have every single method that the inner type has,
implementing the <code>Deref</code> trait (discussed in Chapter 15 in the “Treating Smart
Pointers like Regular References with the <code>Deref</code> Trait” section) on the
wrapper to return the inner type can be a solution. If we don’t want the
wrapper type to have all the methods of the inner type, in order to restrict
the wrapper type’s behavior for example, we’d have to implement just the
methods we do want ourselves.</p>
<p>That’s how the newtype pattern is used in relation to traits; it’s also a
useful pattern without having traits involved. Let’s switch focus now to talk
about some advanced ways to interact with Rust’s type system.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch19-02-advanced-lifetimes.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-04-advanced-types.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-02-advanced-lifetimes.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-04-advanced-types.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
>
657
