<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>C - Derivable 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"><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" class="active"><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="appendix-03-derivable-traits.html#c---derivable-traits" id="c---derivable-traits"><h1>C - Derivable Traits</h1></a>
<p>In various places in the book, we discussed the <code>derive</code> attribute that is
applied to a struct or enum. This attribute generates code that implements a
trait on the annotated type with a default implementation. In this example, the
<code>#[derive(Debug)]</code> attribute implements the <code>Debug</code> trait for the <code>Point</code>
struct:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[derive(Debug)]
struct Point {
x: i32,
y: i32,
}
#}</code></pre></pre>
<p>The code that the compiler generates for the implementation of <code>Debug</code> is
similar to this code:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Point {
# x: i32,
# y: i32,
# }
#
impl ::std::fmt::Debug for Point {
fn fmt(&self, __arg_0: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
match *self {
Point { x: ref __self_0_0, y: ref __self_0_1 } => {
let mut builder = __arg_0.debug_struct("Point");
let _ = builder.field("x", &&(*__self_0_0));
let _ = builder.field("y", &&(*__self_0_1));
builder.finish()
}
}
}
}
#}</code></pre></pre>
<p>The generated code implements sensible default behavior for the <code>Debug</code> trait’s
<code>fmt</code> function: a <code>match</code> expression destructures a <code>Point</code> instance into its
field values. Then it builds up a string containing the struct’s name and each
field’s name and value. This means we’re able to use debug formatting on a
<code>Point</code> instance to see what value each field has.</p>
<p>The generated code isn’t particularly easy to read because it’s only for the
compiler to consume, rather than for programmers to read! The <code>derive</code>
attribute and the default implementation of <code>Debug</code> has saved us all of the
work of writing this code for every struct or enum that we want to be able to
print using debug formatting.</p>
<p>The <code>derive</code> attribute has default implementations for the following traits
provided by the standard library. If you want different behavior than what the
<code>derive</code> attribute provides, consult the standard library documentation for
each trait for the details needed for manual implementation of the traits.</p>
<a class="header" href="appendix-03-derivable-traits.html#standard-library-traits-that-can-be-derived" id="standard-library-traits-that-can-be-derived"><h2>Standard Library Traits that Can Be Derived</h2></a>
<p>The following sections list all of the traits in the standard library that can
be used with <code>derive</code>. Each section covers:</p>
<ul>
<li>What operators and methods deriving this trait will enable</li>
<li>What the implementation of the trait provided by <code>derive</code> does</li>
<li>What implementing the trait signifies about the type</li>
<li>The conditions in which you’re allowed or not allowed to implement the trait</li>
<li>Examples of operations that require the trait</li>
</ul>
<a class="header" href="appendix-03-derivable-traits.html#debug-for-programmer-output" id="debug-for-programmer-output"><h3><code>Debug</code> for Programmer Output</h3></a>
<p>The <code>Debug</code> trait enables debug formatting in format strings, indicated by
adding <code>:?</code> within <code>{}</code> placeholders.</p>
<p>The <code>Debug</code> trait signifies that instances of a type may be printed by
programmers in order to debug their programs by inspecting an instance of a
type at a particular point in a program’s execution.</p>
<p>An example of when <code>Debug</code> is required is the <code>assert_eq!</code> macro, which prints
the values of the instances given as arguments if the equality assertion fails
so that programmers can see why the two instances weren’t equal.</p>
<a class="header" href="appendix-03-derivable-traits.html#partialeq-and-eq-for-equality-comparisons" id="partialeq-and-eq-for-equality-comparisons"><h3><code>PartialEq</code> and <code>Eq</code> for Equality Comparisons</h3></a>
<p>The <code>PartialEq</code> trait signifies that instances of a type can be compared to
each other for equality, and enables use of the <code>==</code> and <code>!=</code> operators.</p>
<p>Deriving <code>PartialEq</code> implements the <code>eq</code> method. When derived on structs, two
instances are equal if all fields are equal, and not equal if any fields are
not equal. When derived on enums, each variant is equal to itself and not equal
to the other variants.</p>
<p>An example of when <code>PartialEq</code> is required is the <code>assert_eq!</code> macro, which
needs to be able to compare two instances of a type for equality.</p>
<p>The <code>Eq</code> trait doesn’t have any methods. It only signals that for every value
of the annotated type, the value is equal to itself. The <code>Eq</code> trait can only be
applied to types that also implement <code>PartialEq</code>. An example of types that
implements <code>PartialEq</code> but that cannot implement <code>Eq</code> are floating point number
types: the implementation of floating point numbers says that two instances of
the not-a-number value, <code>NaN</code>, are not equal to each other.</p>
<p>An example of when <code>Eq</code> is required is for keys in a <code>HashMap</code> so that the
<code>HashMap</code> can tell whether two keys are the same.</p>
<a class="header" href="appendix-03-derivable-traits.html#partialord-and-ord-for-ordering-comparisons" id="partialord-and-ord-for-ordering-comparisons"><h3><code>PartialOrd</code> and <code>Ord</code> for Ordering Comparisons</h3></a>
<p>The <code>PartialOrd</code> trait signifies that instances of a type can be compared to
each other to see which is larger than the other for sorting purposes. A type
that implements <code>PartialOrd</code> may be used with the <code><</code>, <code>></code>, <code><=</code>, and <code>>=</code>
operators. The <code>PartialOrd</code> trait can only be applied to types that also
implement <code>PartialEq</code>.</p>
<p>Deriving <code>PartialOrd</code> implements the <code>partial_cmp</code> method, which returns an
<code>Option<Ordering></code> that may be <code>None</code> if comparing the given values does not
produce an ordering. When derived on structs, two instances of the struct are
compared by comparing the value in each field in the order in which the fields
appear in the struct definition. When derived on enums, variants of the enum
declared earlier in the enum definition are greater than the variants listed
later.</p>
<p>An example of when <code>PartialOrd</code> is required is the <code>gen_range</code> method in the
<code>rand</code> crate that generates a random value in the range specified by a low
value and a high value.</p>
<p>The <code>Ord</code> trait signifies that for any two value of the annotated type, a valid
ordering exists. The <code>Ord</code> trait implements the <code>cmp</code> method, which returns an
<code>Ordering</code> rather than an <code>Option<Ordering></code> because a valid ordering will
always be possible. The <code>Ord</code> trait can only be applied to types that also
implement <code>PartialOrd</code> and <code>Eq</code> (and <code>Eq</code> requires <code>PartialEq</code>). When derived
on structs and enums, <code>cmp</code> behaves the same way as the derived implementation
for <code>partial_cmp</code> does with <code>PartialOrd</code>.</p>
<p>An example of when <code>Ord</code> is required is when storing values in a <code>BTreeSet<T></code>,
a data structure that stores data based on the sort order of the values.</p>
<a class="header" href="appendix-03-derivable-traits.html#clone-and-copy-for-duplicating-values" id="clone-and-copy-for-duplicating-values"><h3><code>Clone</code> and <code>Copy</code> for Duplicating Values</h3></a>
<p>The <code>Clone</code> trait signifies there is a way to explicitly create a duplicate of
a value, and the duplication process might involve running arbitrary code.
Deriving <code>Clone</code> implements the <code>clone</code> method. When derived, the
implementation of <code>clone</code> for the whole type calls <code>clone</code> on each of the parts
of the type, so all of the fields or values in the type must also implement
<code>Clone</code> to derive <code>Clone</code>.</p>
<p>An example of when <code>Clone</code> is required is when calling the <code>to_vec</code> method on a
slice containing instances of some type. The slice doesn’t own the instances
but the vector returned from <code>to_vec</code> will need to own its instances, so the
implementation of <code>to_vec</code> calls <code>clone</code> on each item. Thus, the type stored in
the slice must implement <code>Clone</code>.</p>
<p>The <code>Copy</code> trait signifies that a value can be duplicated by only copying bits;
no other code is necessary. The <code>Copy</code> trait does not define any methods to
prevent programmers from overloading those methods violating the assumption
that no arbitrary code is being run. You can derive <code>Copy</code> on any type whose
parts all implement <code>Copy</code>. The <code>Copy</code> trait can only be applied to types that
also implement <code>Clone</code>, as a type that implements <code>Copy</code> has a trivial
implementation of <code>Clone</code>, doing the same thing as <code>Copy</code>.</p>
<p><code>Copy</code> is rarely required; when types implement <code>Copy</code>, there are optimizations
that can be applied and the code becomes nicer because you don’t have to call
<code>clone</code>. Everything possible with <code>Copy</code> can also be accomplished with <code>Clone</code>,
but the code might be slower or have to use <code>clone</code> in places.</p>
<a class="header" href="appendix-03-derivable-traits.html#hash-for-mapping-a-value-to-a-value-of-fixed-size" id="hash-for-mapping-a-value-to-a-value-of-fixed-size"><h3><code>Hash</code> for Mapping a Value to a Value of Fixed Size</h3></a>
<p>The <code>Hash</code> trait signifies there is a way to take an instance of a type that
takes up an arbitrary amount of size and map that instance to a value of fixed
size by using a hash function. Deriving <code>Hash</code> implements the <code>hash</code> method.
When derived, the implementation of <code>hash</code> for the whole type combines the
result of calling <code>hash</code> on each of the parts of the type, so all of the fields
or values in the type must also implement <code>Hash</code> to derive <code>Hash</code>.</p>
<p>An example of when <code>Hash</code> is required is for keys in a <code>HashMap</code> so that the
<code>HashMap</code> can store data efficiently.</p>
<a class="header" href="appendix-03-derivable-traits.html#default-for-default-values" id="default-for-default-values"><h3><code>Default</code> for Default Values</h3></a>
<p>The <code>Default</code> trait signifies there is a way to create a default value for a
type. Deriving <code>Default</code> implements the <code>default</code> method. When derived, the
implementation of <code>Default</code> for the whole type calls the <code>default</code> method on
each of the parts of the type, so all of the fields or values in the type must
also implement <code>Default</code> to derive <code>Default.</code></p>
<p>A common use of <code>Default::default</code> is in combination with the struct update
syntax discussed in the “Creating Instances From Other Instances With Struct
Update Syntax” section in Chapter 5. You can customize a few fields of a struct
and then use the default values for the rest by using <code>..Default::default()</code>.</p>
<p>An example of when <code>Default</code> is required is the <code>unwrap_or_default</code> method on
<code>Option<T></code> instances. If the <code>Option<T></code> is <code>None</code>, the <code>unwrap_or_default</code>
method will return the result of <code>Default::default</code> for the type <code>T</code> stored in
the <code>Option<T></code>.</p>
<a class="header" href="appendix-03-derivable-traits.html#standard-library-traits-that-cant-be-derived" id="standard-library-traits-that-cant-be-derived"><h2>Standard Library Traits that Can’t Be Derived</h2></a>
<p>The rest of the traits defined in the standard library can’t be implemented on
your types using <code>derive</code>. These traits don’t have a sensible default behavior
they could have, so you are required to implement them in the way that makes
sense for what you are trying to accomplish with your code.</p>
<p>An example of a trait that can’t be derived is <code>Display</code>, which handles
formatting of a type for end users of your programs. You should put thought
into the appropriate way to display a type to an end user: what parts of the
type should an end user be allowed to see? What parts would they find relevant?
What format of the data would be most relevant to them? The Rust compiler
doesn’t have this insight into your application, so you must provide it.</p>
<a class="header" href="appendix-03-derivable-traits.html#making-custom-traits-derivable" id="making-custom-traits-derivable"><h2>Making Custom Traits Derivable</h2></a>
<p>The above list is not comprehensive, however: libraries can implement <code>derive</code>
for their own types! In this way, the list of traits you can use <code>derive</code> with
is truly open-ended. Implementing <code>derive</code> involves using a procedural macro,
which is covered in the next appendix, “Macros.”</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="appendix-02-operators.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="appendix-04-macros.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="appendix-02-operators.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="appendix-04-macros.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
>
566
