<!DOCTYPE HTML> <html lang="en"> <head> <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"> <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"> <!-- MathJax --> <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> <!-- Fetch JQuery from CDN but have a local fallback --> <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script> <script> if (typeof jQuery == 'undefined') { document.write(unescape("%3Cscript src='jquery.js'%3E%3C/script%3E")); } </script> </head> <body class="light"> <!-- Set the theme before any content is loaded, prevents flash --> <script type="text/javascript"> var theme = localStorage.getItem('theme'); if (theme == null) { theme = 'light'; } $('body').removeClass().addClass(theme); </script> <!-- Hide / unhide sidebar before it is displayed --> <script type="text/javascript"> var sidebar = localStorage.getItem('sidebar'); if (sidebar === "hidden") { $("html").addClass("sidebar-hidden") } else if (sidebar === "visible") { $("html").addClass("sidebar-visible") } </script> <div id="sidebar" class="sidebar"> <ul class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong>1.</strong> Notation</a></li><li><ul class="section"><li><a href="unicode-productions.html"><strong>1.1.</strong> Unicode productions</a></li><li><a href="string-table-productions.html"><strong>1.2.</strong> String table productions</a></li></ul></li><li><a href="lexical-structure.html"><strong>2.</strong> Lexical structure</a></li><li><ul class="section"><li><a href="input-format.html"><strong>2.1.</strong> Input format</a></li><li><a href="identifiers.html"><strong>2.2.</strong> Identifiers</a></li><li><a href="comments.html"><strong>2.3.</strong> Comments</a></li><li><a href="whitespace.html"><strong>2.4.</strong> Whitespace</a></li><li><a href="tokens.html"><strong>2.5.</strong> Tokens</a></li><li><a href="paths.html"><strong>2.6.</strong> Paths</a></li></ul></li><li><a href="macros.html"><strong>3.</strong> Macros</a></li><li><ul class="section"><li><a href="macros-by-example.html"><strong>3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong>3.2.</strong> Procedural Macros</a></li></ul></li><li><a href="crates-and-source-files.html"><strong>4.</strong> Crates and source files</a></li><li><a href="items-and-attributes.html"><strong>5.</strong> Items and attributes</a></li><li><ul class="section"><li><a href="items.html"><strong>5.1.</strong> Items</a></li><li><a href="visibility-and-privacy.html"><strong>5.2.</strong> Visibility and Privacy</a></li><li><a href="attributes.html"><strong>5.3.</strong> Attributes</a></li></ul></li><li><a href="statements-and-expressions.html"><strong>6.</strong> Statements and expressions</a></li><li><ul class="section"><li><a href="statements.html"><strong>6.1.</strong> Statements</a></li><li><a href="expressions.html"><strong>6.2.</strong> Expressions</a></li></ul></li><li><a href="type-system.html"><strong>7.</strong> Type system</a></li><li><ul class="section"><li><a href="types.html"><strong>7.1.</strong> Types</a></li><li><a href="subtyping.html"><strong>7.2.</strong> Subtyping</a></li><li><a href="type-coercions.html" class="active"><strong>7.3.</strong> Type coercions</a></li></ul></li><li><a href="special-traits.html"><strong>8.</strong> Special traits</a></li><li><ul class="section"><li><a href="the-copy-trait.html"><strong>8.1.</strong> The Copy trait</a></li><li><a href="the-sized-trait.html"><strong>8.2.</strong> The Sized trait</a></li><li><a href="the-drop-trait.html"><strong>8.3.</strong> The Drop trait</a></li><li><a href="the-deref-trait.html"><strong>8.4.</strong> The Deref trait</a></li><li><a href="the-send-trait.html"><strong>8.5.</strong> The Send trait</a></li><li><a href="the-sync-trait.html"><strong>8.6.</strong> The Sync trait</a></li></ul></li><li><a href="memory-model.html"><strong>9.</strong> Memory model</a></li><li><ul class="section"><li><a href="memory-allocation-and-lifetime.html"><strong>9.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong>9.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong>9.3.</strong> Variables</a></li></ul></li><li><a href="linkage.html"><strong>10.</strong> Linkage</a></li><li><a href="unsafety.html"><strong>11.</strong> Unsafety</a></li><li><ul class="section"><li><a href="unsafe-functions.html"><strong>11.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong>11.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong>11.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong>11.4.</strong> Behavior not considered unsafe</a></li></ul></li><li><a href="influences.html">Appendix: Influences</a></li><li class="affix"><a href="undocumented.html">Appendix: As-yet-undocumented Features</a></li></ul> </div> <div id="page-wrapper" class="page-wrapper"> <div class="page"> <div id="menu-bar" class="menu-bar"> <div class="left-buttons"> <i id="sidebar-toggle" class="fa fa-bars"></i> <i id="theme-toggle" class="fa fa-paint-brush"></i> </div> <h1 class="menu-title">The Rust Reference</h1> <div class="right-buttons"> <i id="print-button" class="fa fa-print" title="Print this book"></i> </div> </div> <div id="content" class="content"> <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> </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> 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(coerce_inner(<code>T</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</p> <ul> <li>coerce_inner(<code>[T, ..n]</code>) = <code>[T]</code></li> <li>coerce_inner(<code>T</code>) = <code>U</code> where <code>T</code> is a concrete type which implements the trait <code>U</code>.</li> </ul> <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 <a href="https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md">RFC 401</a> for more details.</p> </li> <li> <p>Non capturing closures to <code>fn</code> pointers</p> </li> </ul> </div> <!-- Mobile navigation buttons --> <a href="subtyping.html" class="mobile-nav-chapters previous"> <i class="fa fa-angle-left"></i> </a> <a href="special-traits.html" class="mobile-nav-chapters next"> <i class="fa fa-angle-right"></i> </a> </div> <a href="subtyping.html" class="nav-chapters previous" title="You can navigate through the chapters using the arrow keys"> <i class="fa fa-angle-left"></i> </a> <a href="special-traits.html" class="nav-chapters next" title="You can navigate through the chapters using the arrow keys"> <i class="fa fa-angle-right"></i> </a> </div> <!-- Local fallback for Font Awesome --> <script> if ($(".fa").css("font-family") !== "FontAwesome") { $('<link rel="stylesheet" type="text/css" href="_FontAwesome/css/font-awesome.css">').prependTo('head'); } </script> <!-- Livereload script (if served using the cli tool) --> <script src="highlight.js"></script> <script src="book.js"></script> </body> </html>