<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Type coercions - The Rust Reference</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="_FontAwesome/css/font-awesome.css">
<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="src/theme/reference.css">
</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 + ' 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">
<ol class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong aria-hidden="true">1.</strong> Notation</a></li><li><a href="lexical-structure.html"><strong aria-hidden="true">2.</strong> Lexical structure</a></li><li><ol class="section"><li><a href="input-format.html"><strong aria-hidden="true">2.1.</strong> Input format</a></li><li><a href="keywords.html"><strong aria-hidden="true">2.2.</strong> Keywords</a></li><li><a href="identifiers.html"><strong aria-hidden="true">2.3.</strong> Identifiers</a></li><li><a href="comments.html"><strong aria-hidden="true">2.4.</strong> Comments</a></li><li><a href="whitespace.html"><strong aria-hidden="true">2.5.</strong> Whitespace</a></li><li><a href="tokens.html"><strong aria-hidden="true">2.6.</strong> Tokens</a></li><li><a href="paths.html"><strong aria-hidden="true">2.7.</strong> Paths</a></li></ol></li><li><a href="macros.html"><strong aria-hidden="true">3.</strong> Macros</a></li><li><ol class="section"><li><a href="macros-by-example.html"><strong aria-hidden="true">3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">3.2.</strong> Procedural Macros</a></li></ol></li><li><a href="crates-and-source-files.html"><strong aria-hidden="true">4.</strong> Crates and source files</a></li><li><a href="items-and-attributes.html"><strong aria-hidden="true">5.</strong> Items and attributes</a></li><li><ol class="section"><li><a href="items.html"><strong aria-hidden="true">5.1.</strong> Items</a></li><li><ol class="section"><li><a href="items/modules.html"><strong aria-hidden="true">5.1.1.</strong> Modules</a></li><li><a href="items/extern-crates.html"><strong aria-hidden="true">5.1.2.</strong> Extern crates</a></li><li><a href="items/use-declarations.html"><strong aria-hidden="true">5.1.3.</strong> Use declarations</a></li><li><a href="items/functions.html"><strong aria-hidden="true">5.1.4.</strong> Functions</a></li><li><a href="items/type-aliases.html"><strong aria-hidden="true">5.1.5.</strong> Type aliases</a></li><li><a href="items/structs.html"><strong aria-hidden="true">5.1.6.</strong> Structs</a></li><li><a href="items/enumerations.html"><strong aria-hidden="true">5.1.7.</strong> Enumerations</a></li><li><a href="items/unions.html"><strong aria-hidden="true">5.1.8.</strong> Unions</a></li><li><a href="items/constant-items.html"><strong aria-hidden="true">5.1.9.</strong> Constant items</a></li><li><a href="items/static-items.html"><strong aria-hidden="true">5.1.10.</strong> Static items</a></li><li><a href="items/traits.html"><strong aria-hidden="true">5.1.11.</strong> Traits</a></li><li><a href="items/implementations.html"><strong aria-hidden="true">5.1.12.</strong> Implementations</a></li><li><a href="items/external-blocks.html"><strong aria-hidden="true">5.1.13.</strong> External blocks</a></li></ol></li><li><a href="items/generics.html"><strong aria-hidden="true">5.2.</strong> Type and lifetime parameters</a></li><li><a href="items/associated-items.html"><strong aria-hidden="true">5.3.</strong> Associated Items</a></li><li><a href="visibility-and-privacy.html"><strong aria-hidden="true">5.4.</strong> Visibility and Privacy</a></li><li><a href="attributes.html"><strong aria-hidden="true">5.5.</strong> Attributes</a></li></ol></li><li><a href="statements-and-expressions.html"><strong aria-hidden="true">6.</strong> Statements and expressions</a></li><li><ol class="section"><li><a href="statements.html"><strong aria-hidden="true">6.1.</strong> Statements</a></li><li><a href="expressions.html"><strong aria-hidden="true">6.2.</strong> Expressions</a></li><li><ol class="section"><li><a href="expressions/literal-expr.html"><strong aria-hidden="true">6.2.1.</strong> Literal expressions</a></li><li><a href="expressions/path-expr.html"><strong aria-hidden="true">6.2.2.</strong> Path expressions</a></li><li><a href="expressions/block-expr.html"><strong aria-hidden="true">6.2.3.</strong> Block expressions</a></li><li><a href="expressions/operator-expr.html"><strong aria-hidden="true">6.2.4.</strong> Operator expressions</a></li><li><a href="expressions/grouped-expr.html"><strong aria-hidden="true">6.2.5.</strong> Grouped expressions</a></li><li><a href="expressions/array-expr.html"><strong aria-hidden="true">6.2.6.</strong> Array and index expressions</a></li><li><a href="expressions/tuple-expr.html"><strong aria-hidden="true">6.2.7.</strong> Tuple and index expressions</a></li><li><a href="expressions/struct-expr.html"><strong aria-hidden="true">6.2.8.</strong> Struct expressions</a></li><li><a href="expressions/enum-variant-expr.html"><strong aria-hidden="true">6.2.9.</strong> Enum variant expressions</a></li><li><a href="expressions/call-expr.html"><strong aria-hidden="true">6.2.10.</strong> Call expressions</a></li><li><a href="expressions/method-call-expr.html"><strong aria-hidden="true">6.2.11.</strong> Method call expressions</a></li><li><a href="expressions/field-expr.html"><strong aria-hidden="true">6.2.12.</strong> Field access expressions</a></li><li><a href="expressions/closure-expr.html"><strong aria-hidden="true">6.2.13.</strong> Closure expressions</a></li><li><a href="expressions/loop-expr.html"><strong aria-hidden="true">6.2.14.</strong> Loop expressions</a></li><li><a href="expressions/range-expr.html"><strong aria-hidden="true">6.2.15.</strong> Range expressions</a></li><li><a href="expressions/if-expr.html"><strong aria-hidden="true">6.2.16.</strong> If and if let expressions</a></li><li><a href="expressions/match-expr.html"><strong aria-hidden="true">6.2.17.</strong> Match expressions</a></li><li><a href="expressions/return-expr.html"><strong aria-hidden="true">6.2.18.</strong> Return expressions</a></li></ol></li></ol></li><li><a href="type-system.html"><strong aria-hidden="true">7.</strong> Type system</a></li><li><ol class="section"><li><a href="types.html"><strong aria-hidden="true">7.1.</strong> Types</a></li><li><a href="dynamically-sized-types.html"><strong aria-hidden="true">7.2.</strong> Dynamically Sized Types</a></li><li><a href="type-layout.html"><strong aria-hidden="true">7.3.</strong> Type layout</a></li><li><a href="interior-mutability.html"><strong aria-hidden="true">7.4.</strong> Interior mutability</a></li><li><a href="subtyping.html"><strong aria-hidden="true">7.5.</strong> Subtyping and Variance</a></li><li><a href="trait-bounds.html"><strong aria-hidden="true">7.6.</strong> Trait and lifetime bounds</a></li><li><a href="type-coercions.html" class="active"><strong aria-hidden="true">7.7.</strong> Type coercions</a></li><li><a href="destructors.html"><strong aria-hidden="true">7.8.</strong> Destructors</a></li><li><a href="lifetime-elision.html"><strong aria-hidden="true">7.9.</strong> Lifetime elision</a></li></ol></li><li><a href="special-types-and-traits.html"><strong aria-hidden="true">8.</strong> Special types and traits</a></li><li><a href="memory-model.html"><strong aria-hidden="true">9.</strong> Memory model</a></li><li><ol class="section"><li><a href="memory-allocation-and-lifetime.html"><strong aria-hidden="true">9.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong aria-hidden="true">9.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong aria-hidden="true">9.3.</strong> Variables</a></li></ol></li><li><a href="linkage.html"><strong aria-hidden="true">10.</strong> Linkage</a></li><li><a href="unsafety.html"><strong aria-hidden="true">11.</strong> Unsafety</a></li><li><ol class="section"><li><a href="unsafe-functions.html"><strong aria-hidden="true">11.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong aria-hidden="true">11.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong aria-hidden="true">11.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong aria-hidden="true">11.4.</strong> Behavior not considered unsafe</a></li></ol></li><li><a href="influences.html">Appendix: Influences</a></li><li class="affix"><a href="undocumented.html">Appendix: As-yet-undocumented Features</a></li><li class="affix"><a href="glossary.html">Appendix: Glossary</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<header><p class="warning">
For now, this reference is a best-effort document. We strive for validity
and completeness, but are not yet there. In the future, the docs and lang
teams will work together to figure out how best to do this. Until then, this
is a best-effort attempt. If you find something wrong or missing, file an
<a href="https://github.com/rust-lang-nursery/reference/issues">issue</a> or
send in a pull request.
</p></header>
<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 <span class="default">(default)</span></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 Reference</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>
<a class="header" href="type-coercions.html#type-coercions" id="type-coercions"><h1>Type coercions</h1></a>
<p>Coercions are defined in <a href="https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md">RFC 401</a>. <a href="https://github.com/rust-lang/rfcs/blob/master/text/1558-closure-to-fn-coercion.md">RFC 1558</a> then expanded on that.
A coercion is implicit and has no syntax.</p>
<a class="header" href="type-coercions.html#coercion-sites" id="coercion-sites"><h2>Coercion sites</h2></a>
<p>A coercion can only occur at certain coercion sites in a program; these are
typically places where the desired type is explicit or can be derived by
propagation from explicit types (without type inference). Possible coercion
sites are:</p>
<ul>
<li>
<p><code>let</code> statements where an explicit type is given.</p>
<p>For example, <code>42</code> is coerced to have type <code>i8</code> in the following:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let _: i8 = 42;
#}</code></pre></pre>
</li>
<li>
<p><code>static</code> and <code>const</code> statements (similar to <code>let</code> statements).</p>
</li>
<li>
<p>Arguments for function calls</p>
<p>The value being coerced is the actual parameter, and it is coerced to
the type of the formal parameter.</p>
<p>For example, <code>42</code> is coerced to have type <code>i8</code> in the following:</p>
<pre><pre class="playpen"><code class="language-rust">fn bar(_: i8) { }
fn main() {
bar(42);
}
</code></pre></pre>
<p>For method calls, the receiver (<code>self</code> parameter) can only take advantage
of <a href="type-coercions.html#unsized-coercions">unsized coercions</a>.</p>
</li>
<li>
<p>Instantiations of struct or variant fields</p>
<p>For example, <code>42</code> is coerced to have type <code>i8</code> in the following:</p>
<pre><pre class="playpen"><code class="language-rust">struct Foo { x: i8 }
fn main() {
Foo { x: 42 };
}
</code></pre></pre>
</li>
<li>
<p>Function results, either the final line of a block if it is not
semicolon-terminated or any expression in a <code>return</code> statement</p>
<p>For example, <code>42</code> is coerced to have type <code>i8</code> in the following:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
fn foo() -> i8 {
42
}
#}</code></pre></pre>
</li>
</ul>
<p>If the expression in one of these coercion sites is a coercion-propagating
expression, then the relevant sub-expressions in that expression are also
coercion sites. Propagation recurses from these new coercion sites.
Propagating expressions and their relevant sub-expressions are:</p>
<ul>
<li>
<p>Array literals, where the array has type <code>[U; n]</code>. Each sub-expression in
the array literal is a coercion site for coercion to type <code>U</code>.</p>
</li>
<li>
<p>Array literals with repeating syntax, where the array has type <code>[U; n]</code>. The
repeated sub-expression is a coercion site for coercion to type <code>U</code>.</p>
</li>
<li>
<p>Tuples, where a tuple is a coercion site to type <code>(U_0, U_1, ..., U_n)</code>.
Each sub-expression is a coercion site to the respective type, e.g. the
zeroth sub-expression is a coercion site to type <code>U_0</code>.</p>
</li>
<li>
<p>Parenthesized sub-expressions (<code>(e)</code>): if the expression has type <code>U</code>, then
the sub-expression is a coercion site to <code>U</code>.</p>
</li>
<li>
<p>Blocks: if a block has type <code>U</code>, then the last expression in the block (if
it is not semicolon-terminated) is a coercion site to <code>U</code>. This includes
blocks which are part of control flow statements, such as <code>if</code>/<code>else</code>, if
the block has a known type.</p>
</li>
</ul>
<a class="header" href="type-coercions.html#coercion-types" id="coercion-types"><h2>Coercion types</h2></a>
<p>Coercion is allowed between the following types:</p>
<ul>
<li>
<p><code>T</code> to <code>U</code> if <code>T</code> is a subtype of <code>U</code> (<em>reflexive case</em>)</p>
</li>
<li>
<p><code>T_1</code> to <code>T_3</code> where <code>T_1</code> coerces to <code>T_2</code> and <code>T_2</code> coerces to <code>T_3</code>
(<em>transitive case</em>)</p>
<p>Note that this is not fully supported yet</p>
</li>
<li>
<p><code>&mut T</code> to <code>&T</code></p>
</li>
<li>
<p><code>*mut T</code> to <code>*const T</code></p>
</li>
<li>
<p><code>&T</code> to <code>*const T</code></p>
</li>
<li>
<p><code>&mut T</code> to <code>*mut T</code></p>
</li>
<li>
<p><code>&T</code> or <code>&mut T</code> to <code>&U</code> if <code>T</code> implements <code>Deref<Target = U></code>. For example:</p>
<pre><pre class="playpen"><code class="language-rust">use std::ops::Deref;
struct CharContainer {
value: char,
}
impl Deref for CharContainer {
type Target = char;
fn deref<'a>(&'a self) -> &'a char {
&self.value
}
}
fn foo(arg: &char) {}
fn main() {
let x = &mut CharContainer { value: 'y' };
foo(x); //&mut CharContainer is coerced to &char.
}
</code></pre></pre>
</li>
<li>
<p><code>&mut T</code> to <code>&mut U</code> if <code>T</code> implements <code>DerefMut<Target = U></code>.</p>
</li>
<li>
<p>TyCtor(<code>T</code>) to TyCtor(<code>U</code>), where TyCtor(<code>T</code>) is one of</p>
<ul>
<li><code>&T</code></li>
<li><code>&mut T</code></li>
<li><code>*const T</code></li>
<li><code>*mut T</code></li>
<li><code>Box<T></code></li>
</ul>
<p>and where <code>T</code> can obtained from <code>U</code> by <a href="type-coercions.html#unsized-coercions">unsized coercion</a>.</p>
<!--In the future, coerce_inner will be recursively extended to tuples and
structs. In addition, coercions from sub-traits to super-traits will be
added. See [RFC 401] for more details.-->
</li>
<li>
<p>Non capturing closures to <code>fn</code> pointers</p>
</li>
<li>
<p><code>!</code> to any <code>T</code></p>
</li>
</ul>
<a class="header" href="type-coercions.html#unsized-coercions" id="unsized-coercions"><h3>Unsized Coercions</h3></a>
<p>The following coercions are called <code>unsized coercions</code>, since they
relate to converting sized types to unsized types, and are permitted in a few
cases where other coercions are not, as described above. They can still happen
anywhere else a coercion can occur.</p>
<p>Two traits, [<code>Unsize</code>] and [<code>CoerceUnsized</code>], are used
to assist in this process and expose it for library use. The compiler following
coercions are built-in and, if <code>T</code> can be coerced to <code>U</code> with one of the, then
the compiler will provide an implementation of <code>Unsize<U></code> for <code>T</code>:</p>
<ul>
<li>
<p><code>[T; n]</code> to <code>[T]</code>.</p>
</li>
<li>
<p><code>T</code> to <code>U</code>, when <code>U</code> is a trait object type and either <code>T</code> implements <code>U</code> or
<code>T</code> is a trait object for a subtrait of <code>U</code>.</p>
</li>
<li>
<p><code>Foo<..., T, ...></code> to <code>Foo<..., U, ...></code>, when:</p>
<ul>
<li><code>Foo</code> is a struct.</li>
<li><code>T</code> implements <code>Unsize<U></code>.</li>
<li>The last field of <code>Foo</code> has a type involving <code>T</code>.</li>
<li>If that field has type <code>Bar<T></code>, then <code>Bar<T></code> implements <code>Unsized<Bar<U>></code>.</li>
<li>T is not part of the type of any other fields.</li>
</ul>
</li>
</ul>
<p>Additionally, a type <code>Foo<T></code> can implement <code>CoerceUnsized<Foo<U>></code> when <code>T</code>
implements <code>Unsize<U></code> or <code>CoerceUnsized<Foo<U>></code>. This allows it to provide a
unsized coercion to <code>Foo<U></code>.</p>
<blockquote>
<p>Note: While the definition of the unsized coercions and their implementation
has been stabilized, the traits themselves are not yet stable and therefore
can't be used directly in stable Rust.</p>
</blockquote>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="trait-bounds.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="destructors.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="trait-bounds.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="destructors.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 src="searchindex.js" type="text/javascript" charset="utf-8"></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 -->
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
11157
