pierre/RustBook
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
f836a9177d
RustBook/appendix-03-derivable-traits.html

366 lines
37 KiB
HTML
Raw Normal View History

Initial commit
2020-01-06 20:57:15 +00:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<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" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="googleFonts/css.css" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="ferris.css">
<link rel="stylesheet" href="theme/2018-edition.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
</script>
<!-- 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 = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
<ol class="chapter"><li class="expanded affix "><a href="title-page.html">The Rust Programming Language</a></li><li class="expanded affix "><a href="foreword.html">Foreword</a></li><li class="expanded affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="expanded "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li class="expanded "><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li class="expanded "><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li class="expanded "><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li class="expanded "><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li class="expanded "><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li class="expanded "><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li class="expanded "><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li class="expanded "><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> Functions</a></li><li class="expanded "><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li class="expanded "><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li class="expanded "><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li class="expanded "><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li class="expanded "><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References and Borrowing</a></li><li class="expanded "><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> The Slice Type</a></li></ol></li><li class="expanded "><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 class="expanded "><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li class="expanded "><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li class="expanded "><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li class="expanded "><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li class="expanded "><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li class="expanded "><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li class="expanded "><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 class="expanded "><a href="ch07-00-managing-growing-projects-with-packages-crates-and-modules.html"><strong aria-hidden="true">7.</strong> Managing Growing Projects with Packages, Crates, and Modules</a></li><li><ol class="section"><li class="expanded "><a href="ch07-01-packages-and-crates.html"><strong aria-hidden="true">7.1.</strong> Packages and Crates</a></li><li class="expanded "><a href="ch07-02-defining-modules-to-control-scope-and-privacy.html"><strong aria-hidden="true">7.2.</strong> Defining Modules to Control Scope and Privacy</a></li><li class="expanded "><a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html"><
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h2><a class="header" href="#appendix-c-derivable-traits" id="appendix-c-derivable-traits">Appendix C: Derivable Traits</a></h2>
<p>In various places in the book, we’ve discussed the <code>derive</code> attribute, which
you can apply to a struct or enum definition. The <code>derive</code> attribute generates
code that will implement a trait with its own default implementation on the
type you’ve annotated with the <code>derive</code> syntax.</p>
<p>In this appendix, we provide a reference of all the traits in the standard
library that you can use 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>
<p>If you want different behavior from that provided by the <code>derive</code> attribute,
consult the <a href="../std/index.html">standard library documentation</a><!-- ignore -->
for each trait for details of how to manually implement them.</p>
<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 sensible default behavior,
so it’s up to you to implement them in the way that makes sense for what you’re
trying to accomplish.</p>
<p>An example of a trait that can’t be derived is <code>Display</code>, which handles
formatting for end users. You should always consider 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, so
it can’t provide appropriate default behavior for you.</p>
<p>The list of derivable traits provided in this appendix is not comprehensive:
libraries can implement <code>derive</code> for their own traits, making the list of
traits you can use <code>derive</code> with truly open-ended. Implementing <code>derive</code>
involves using a procedural macro, which is covered in the
<a href="ch19-06-macros.html#macros">“Macros”</a><!-- ignore --> section of Chapter 19.</p>
<h3><a class="header" href="#debug-for-programmer-output" id="debug-for-programmer-output"><code>Debug</code> for Programmer Output</a></h3>
<p>The <code>Debug</code> trait enables debug formatting in format strings, which you
indicate by adding <code>:?</code> within <code>{}</code> placeholders.</p>
<p>The <code>Debug</code> trait allows you to print instances of a type for debugging
purposes, so you and other programmers using your type can inspect an instance
at a particular point in a program’s execution.</p>
<p>The <code>Debug</code> trait is required, for example, in use of the <code>assert_eq!</code> macro.
This macro prints the values of instances given as arguments if the equality
assertion fails so programmers can see why the two instances weren’t equal.</p>
<h3><a class="header" href="#partialeq-and-eq-for-equality-comparisons" id="partialeq-and-eq-for-equality-comparisons"><code>PartialEq</code> and <code>Eq</code> for Equality Comparisons</a></h3>
<p>The <code>PartialEq</code> trait allows you to compare instances of a type to check 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 <code>PartialEq</code> is derived on
structs, two instances are equal only if <em>all</em> fields are equal, and the
instances are 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>The <code>PartialEq</code> trait is required, for example, with the use of 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 has no methods. Its purpose is to signal 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>, although not all types that
implement <code>PartialEq</code> can implement <code>Eq</code>. One example of this is floating point
number types: the implementation of floating point numbers states that two
instances of the not-a-number (<code>NaN</code>) value are not equal to each other.</p>
<p>An example of when <code>Eq</code> is required is for keys in a <code>HashMap&lt;K, V&gt;</code> so the
<code>HashMap&lt;K, V&gt;</code> can tell whether two keys are the same.</p>
<h3><a class="header" href="#partialord-and-ord-for-ordering-comparisons" id="partialord-and-ord-for-ordering-comparisons"><code>PartialOrd</code> and <code>Ord</code> for Ordering Comparisons</a></h3>
<p>The <code>PartialOrd</code> trait allows you to compare instances of a type for sorting
purposes. A type that implements <code>PartialOrd</code> can be used with the <code>&lt;</code>, <code>&gt;</code>,
<code>&lt;=</code>, and <code>&gt;=</code> operators. You can only apply the <code>PartialOrd</code> trait 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&lt;Ordering&gt;</code> that will be <code>None</code> when the values given don’t produce an
ordering. An example of a value that doesn’t produce an ordering, even though
most values of that type can be compared, is the not-a-number (<code>NaN</code>) floating
point value. Calling <code>partial_cmp</code> with any floating point number and the <code>NaN</code>
floating point value will return <code>None</code>.</p>
<p>When derived on structs, <code>PartialOrd</code> compares two instances 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 considered less than the variants listed later.</p>
<p>The <code>PartialOrd</code> trait is required, for example, for the <code>gen_range</code> method
from 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 allows you to know that for any two values of the annotated
type, a valid ordering will exist. The <code>Ord</code> trait implements the <code>cmp</code> method,
which returns an <code>Ordering</code> rather than an <code>Option&lt;Ordering&gt;</code> because a valid
ordering will always be possible. You can only apply the <code>Ord</code> trait 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&lt;T&gt;</code>,
a data structure that stores data based on the sort order of the values.</p>
<h3><a class="header" href="#clone-and-copy-for-duplicating-values" id="clone-and-copy-for-duplicating-values"><code>Clone</code> and <code>Copy</code> for Duplicating Values</a></h3>
<p>The <code>Clone</code> trait allows you to explicitly create a deep copy of a value, and
the duplication process might involve running arbitrary code and copying heap
data. See the <a href="ch04-01-what-is-ownership.html#ways-variables-and-data-interact-clone">“Ways Variables and Data Interact:
Clone”</a><!-- ignore --> section in
Chapter 4 for more information on <code>Clone</code>.</p>
<p>Deriving <code>Clone</code> implements the <code>clone</code> method, which when implemented for the
whole type, calls <code>clone</code> on each of the parts of the type. This means all 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. The slice doesn’t own the type instances it contains, but the vector
returned from <code>to_vec</code> will need to own its instances, so <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 allows you to duplicate a value by only copying bits stored on
the stack; no arbitrary code is necessary. See the <a href="ch04-01-what-is-ownership.html#stack-only-data-copy">“Stack-Only Data:
Copy”</a><!-- ignore --> section in Chapter 4 for more
information on <code>Copy</code>.</p>
<p>The <code>Copy</code> trait doesn’t define any methods to prevent programmers from
overloading those methods and violating the assumption that no arbitrary code
is being run. That way, all programmers can assume that copying a value will be
very fast.</p>
<p>You can derive <code>Copy</code> on any type whose parts all implement <code>Copy</code>. You can
only apply the <code>Copy</code> trait to types that also implement <code>Clone</code>, because a
type that implements <code>Copy</code> has a trivial implementation of <code>Clone</code> that
performs the same task as <code>Copy</code>.</p>
<p>The <code>Copy</code> trait is rarely required; types that implement <code>Copy</code> have
optimizations available, meaning you don’t have to call <code>clone</code>, which makes
the code more concise.</p>
<p>Everything possible with <code>Copy</code> you can also accomplish with <code>Clone</code>, but the
code might be slower or have to use <code>clone</code> in places.</p>
<h3><a class="header" href="#hash-for-mapping-a-value-to-a-value-of-fixed-size" id="hash-for-mapping-a-value-to-a-value-of-fixed-size"><code>Hash</code> for Mapping a Value to a Value of Fixed Size</a></h3>
<p>The <code>Hash</code> trait allows you to take an instance of a type of arbitrary size and
map that instance to a value of fixed size using a hash function. Deriving
<code>Hash</code> implements the <code>hash</code> method. The derived implementation of the <code>hash</code>
method combines the result of calling <code>hash</code> on each of the parts of the type,
meaning all fields or values must also implement <code>Hash</code> to derive <code>Hash</code>.</p>
<p>An example of when <code>Hash</code> is required is in storing keys in a <code>HashMap&lt;K, V&gt;</code>
to store data efficiently.</p>
<h3><a class="header" href="#default-for-default-values" id="default-for-default-values"><code>Default</code> for Default Values</a></h3>
<p>The <code>Default</code> trait allows you to create a default value for a type. Deriving
<code>Default</code> implements the <code>default</code> function. The derived implementation of the
<code>default</code> function calls the <code>default</code> function on each part of the type,
meaning all fields or values in the type must also implement <code>Default</code> to
derive <code>Default</code>.</p>
<p>The <code>Default::default</code> function is commonly used in combination with the struct
update syntax discussed in the <a href="ch05-01-defining-structs.html#creating-instances-from-other-instances-with-struct-update-syntax">“Creating Instances From Other Instances With
Struct Update
Syntax”</a><!-- ignore -->
section in Chapter 5. You can customize a few fields of a struct and then
set and use a default value for the rest of the fields by using
<code>..Default::default()</code>.</p>
<p>The <code>Default</code> trait is required when you use the method <code>unwrap_or_default</code> on
<code>Option&lt;T&gt;</code> instances, for example. If the <code>Option&lt;T&gt;</code> is <code>None</code>, the method
<code>unwrap_or_default</code> will return the result of <code>Default::default</code> for the type
<code>T</code> stored in the <code>Option&lt;T&gt;</code>.</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-useful-development-tools.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-useful-development-tools.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playpen_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="ferris.js"></script>
</body>
</html>
Reference in New Issue Copy Permalink