<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Type layout - 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" class="active"><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"><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-layout.html#type-layout" id="type-layout"><h1>Type Layout</h1></a>
<p>The layout of a type is its size, alignment, and the relative offsets of its
fields. For enums, how the discriminant is laid out and interpreted is also part
of type layout.</p>
<p>Type layout can be changed with each compilation. Instead of trying to document
exactly what is done, we only document what is guaranteed today.</p>
<a class="header" href="type-layout.html#size-and-alignment" id="size-and-alignment"><h2>Size and Alignment</h2></a>
<p>All values have an alignment and size.</p>
<p>The <em>alignment</em> of a value specifies what addresses are valid to store the value
at. A value of alignment <code>n</code> must only be stored at an address that is a
multiple of n. For example, a value with an alignment of 2 must be stored at an
even address, while a value with an alignment of 1 can be stored at any address.
Alignment is measured in bytes, and must be at least 1, and always a power of 2.
The alignment of a value can be checked with the <a href="../std/mem/fn.align_of_val.html"><code>align_of_val</code></a> function.</p>
<p>The <em>size</em> of a value is the offset in bytes between successive elements in an
array with that item type including alignment padding. The size of a value is
always a multiple of its alignment. The size of a value can be checked with the
<a href="../std/mem/fn.size_of_val.html"><code>size_of_val</code></a> function.</p>
<p>Types where all values have the same size and alignment known at compile time
implement the <a href="../std/marker/trait.Sized.html"><code>Sized</code></a> trait and can be checked with the <a href="../std/mem/fn.size_of.html"><code>size_of</code></a> and
<a href="../std/mem/fn.align_of.html"><code>align_of</code></a> functions. Types that are not <a href="../std/marker/trait.Sized.html"><code>Sized</code></a> are known as <a href="dynamically-sized-types.html">dynamically
sized types</a>. Since all values of a <code>Sized</code> type share the same size and
alignment, we refer to those shared values as the size of the type and the
alignment of the type respectively.</p>
<a class="header" href="type-layout.html#primitive-data-layout" id="primitive-data-layout"><h2>Primitive Data Layout</h2></a>
<p>The size of most primitives is given in this table.</p>
<table><thead><tr><th>Type </th><th> <code>size_of::<Type>()</code></th></tr></thead><tbody>
<tr><td>bool </td><td> 1</td></tr>
<tr><td>u8 </td><td> 1</td></tr>
<tr><td>u16 </td><td> 2</td></tr>
<tr><td>u32 </td><td> 4</td></tr>
<tr><td>u64 </td><td> 8</td></tr>
<tr><td>u128 </td><td> 16</td></tr>
<tr><td>i8 </td><td> 1</td></tr>
<tr><td>i16 </td><td> 2</td></tr>
<tr><td>i32 </td><td> 4</td></tr>
<tr><td>i64 </td><td> 8</td></tr>
<tr><td>i128 </td><td> 16</td></tr>
<tr><td>f32 </td><td> 4</td></tr>
<tr><td>f64 </td><td> 8</td></tr>
<tr><td>char </td><td> 4</td></tr>
</tbody></table>
<p><code>usize</code> and <code>isize</code> have a size big enough to contain every address on the
target platform. For example, on a 32 bit target, this is 4 bytes and on a 64
bit target, this is 8 bytes.</p>
<p>Most primitives are generally aligned to their size, although this is
platform-specific behavior. In particular, on x86 u64 and f64 are only
aligned to 32 bits.</p>
<a class="header" href="type-layout.html#pointers-and-references-layout" id="pointers-and-references-layout"><h2>Pointers and References Layout</h2></a>
<p>Pointers and references have the same layout. Mutability of the pointer or
reference does not change the layout.</p>
<p>Pointers to sized types have the same size and alignment as <code>usize</code>.</p>
<p>Pointers to unsized types are sized. The size and alignment is guaranteed to be
at least equal to the size and alignment of a pointer.</p>
<blockquote>
<p>Note: Though you should not rely on this, all pointers to <abbr
title="Dynamically Sized Types">DSTs</abbr> are currently twice the size of
the size of <code>usize</code> and have the same alignment.</p>
</blockquote>
<a class="header" href="type-layout.html#array-layout" id="array-layout"><h2>Array Layout</h2></a>
<p>Arrays are laid out so that the <code>nth</code> element of the array is offset from the
start of the array by <code>n * the size of the type</code> bytes. An array of <code>[T; n]</code>
has a size of <code>size_of::<T>() * n</code> and the same alignment of <code>T</code>.</p>
<a class="header" href="type-layout.html#slice-layout" id="slice-layout"><h2>Slice Layout</h2></a>
<p>Slices have the same layout as the section of the array they slice.</p>
<blockquote>
<p>Note: This is about the raw <code>[T]</code> type, not pointers (<code>&[T]</code>, <code>Box<[T]></code>,
etc.) to slices.</p>
</blockquote>
<a class="header" href="type-layout.html#tuple-layout" id="tuple-layout"><h2>Tuple Layout</h2></a>
<p>Tuples do not have any guarantees about their layout.</p>
<p>The exception to this is the unit tuple (<code>()</code>) which is guaranteed as a
zero-sized type to have a size of 0 and an alignment of 1.</p>
<a class="header" href="type-layout.html#trait-object-layout" id="trait-object-layout"><h2>Trait Object Layout</h2></a>
<p>Trait objects have the same layout as the value the trait object is of.</p>
<blockquote>
<p>Note: This is about the raw trait object types, not pointers (<code>&Trait</code>,
<code>Box<Trait></code>, etc.) to trait objects.</p>
</blockquote>
<a class="header" href="type-layout.html#closure-layout" id="closure-layout"><h2>Closure Layout</h2></a>
<p>Closures have no layout guarantees.</p>
<a class="header" href="type-layout.html#representations" id="representations"><h2>Representations</h2></a>
<p>All user-defined composite types (<code>struct</code>s, <code>enum</code>s, and <code>union</code>s) have a
<em>representation</em> that specifies what the layout is for the type.</p>
<p>The possible representations for a type are the default representation, <code>C</code>, the
primitive representations, and <code>packed</code>. Multiple representations can be applied
to a single type.</p>
<p>The representation of a type can be changed by applying the [<code>repr</code> attribute]
to it. The following example shows a struct with a <code>C</code> representation.</p>
<pre><code>#[repr(C)]
struct ThreeInts {
first: i16,
second: i8,
third: i32
}
</code></pre>
<blockquote>
<p>Note: As a consequence of the representation being an attribute on the item,
the representation does not depend on generic parameters. Any two types with
the same name have the same representation. For example, <code>Foo<Bar></code> and
<code>Foo<Baz></code> both have the same representation.</p>
</blockquote>
<p>The representation of a type does not change the layout of its fields. For
example, a struct with a <code>C</code> representation that contains a struct <code>Inner</code> with
the default representation will not change the layout of Inner.</p>
<a class="header" href="type-layout.html#the-default-representation" id="the-default-representation"><h3>The Default Representation</h3></a>
<p>Nominal types without a <code>repr</code> attribute have the default representation.
Informally, this representation is also called the <code>rust</code> representation.</p>
<p>There are no guarantees of data layout made by this representation.</p>
<a class="header" href="type-layout.html#the-c-representation" id="the-c-representation"><h3>The <code>C</code> Representation</h3></a>
<p>The <code>C</code> representation is designed for dual purposes. One purpose is for
creating types that are interoptable with the C Language. The second purpose is
to create types that you can soundly performing operations that rely on data
layout such as reinterpreting values as a different type.</p>
<p>Because of this dual purpose, it is possible to create types that are not useful
for interfacing with the C programming language.</p>
<p>This representation can be applied to structs, unions, and enums.</p>
<a class="header" href="type-layout.html#reprc-structs" id="reprc-structs"><h4>#[repr(C)] Structs</h4></a>
<p>The alignment of the struct is the alignment of the most-aligned field in it.</p>
<p>The size and offset of fields is determined by the following algorithm.</p>
<p>Start with a current offset of 0 bytes.</p>
<p>For each field in declaration order in the struct, first determine the size and
alignment of the field. If the current offset is not a multiple of the field's
alignment, then add padding bytes to the current offset until it is a multiple
of the field's alignment. The offset for the field is what the current offset
is now. Then increase the current offset by the size of the field.</p>
<p>Finally, the size of the struct is the current offset rounded up to the nearest
multiple of the struct's alignment.</p>
<p>Here is this algorithm described in pseudocode.</p>
<pre><code class="language-rust ignore">struct.alignment = struct.fields().map(|field| field.alignment).max();
let current_offset = 0;
for field in struct.fields_in_declaration_order() {
// Increase the current offset so that it's a multiple of the alignment
// of this field. For the first field, this will always be zero.
// The skipped bytes are called padding bytes.
current_offset += field.alignment % current_offset;
struct[field].offset = current_offset;
current_offset += field.size;
}
struct.size = current_offset + current_offset % struct.alignment;
</code></pre>
<blockquote>
<p>Note: This algorithm can produce zero-sized structs. This differs from
C where structs without data still have a size of one byte.</p>
</blockquote>
<a class="header" href="type-layout.html#reprc-unions" id="reprc-unions"><h4>#[repr(C)] Unions</h4></a>
<p>A union declared with <code>#[repr(C)]</code> will have the same size and alignment as an
equivalent C union declaration in the C language for the target platform.
The union will have a size of the maximum size of all of its fields rounded to
its alignment, and an alignment of the maximum alignment of all of its fields.
These maximums may come from different fields.</p>
<pre><code>#[repr(C)]
union Union {
f1: u16,
f2: [u8; 4],
}
assert_eq!(std::mem::size_of::<Union>(), 4); // From f2
assert_eq!(std::mem::align_of::<Union>(), 2); // From f1
#[repr(C)]
union SizeRoundedUp {
a: u32,
b: [u16; 3],
}
assert_eq!(std::mem::size_of::<SizeRoundedUp>(), 8); // Size of 6 from b,
// rounded up to 8 from
// alignment of a.
assert_eq!(std::mem::align_of::<SizeRoundedUp>(), 4); // From a
</code></pre>
<a class="header" href="type-layout.html#reprc-enums" id="reprc-enums"><h4>#[repr(C)] Enums</h4></a>
<p>For <a href="items/enumerations.html#custom-discriminant-values-for-field-less-enumerations">C-like enumerations</a>, the <code>C</code> representation has the size and alignment of
the default <code>enum</code> size and alignment for the target platform's C ABI.</p>
<blockquote>
<p>Note: The enum representation in C is implementation defined, so this is
really a "best guess". In particular, this may be incorrect when the C code
of interest is compiled with certain flags.</p>
</blockquote>
<blockquote>
<p>Warning: There are crucial differences between an <code>enum</code> in the C language and
Rust's C-like enumerations with this representation. An <code>enum</code> in C is
mostly a <code>typedef</code> plus some named constants; in other words, an object of an
<code>enum</code> type can hold any integer value. For example, this is often used for
bitflags in <code>C</code>. In contrast, Rust’s C-like enumerations can only legally hold
the discriminant values, everything else is undefined behaviour. Therefore,
using a C-like enumeration in FFI to model a C <code>enum</code> is often wrong.</p>
</blockquote>
<p>It is an error for <a href="items/enumerations.html#zero-variant-enums">zero-variant enumerations</a> to have the <code>C</code> representation.</p>
<p>For all other enumerations, the layout is unspecified.</p>
<p>Likewise, combining the <code>C</code> representation with a primitive representation, the
layout is unspecified.</p>
<a class="header" href="type-layout.html#primitive-representations" id="primitive-representations"><h3>Primitive representations</h3></a>
<p>The <em>primitive representations</em> are the representations with the same names as
the primitive integer types. That is: <code>u8</code>, <code>u16</code>, <code>u32</code>, <code>u64</code>, <code>usize</code>, <code>i8</code>,
<code>i16</code>, <code>i32</code>, <code>i64</code>, and <code>isize</code>.</p>
<p>Primitive representations can only be applied to enumerations.</p>
<p>For <a href="items/enumerations.html#custom-discriminant-values-for-field-less-enumerations">C-like enumerations</a>, they set the size and alignment to be the same as the
primitive type of the same name. For example, a C-like enumeration with a <code>u8</code>
representation can only have discriminants between 0 and 255 inclusive.</p>
<p>It is an error for <a href="items/enumerations.html#zero-variant-enums">zero-variant enumerations</a> to have a primitive
representation.</p>
<p>For all other enumerations, the layout is unspecified.</p>
<p>Likewise, combining two primitive representations together is unspecified.</p>
<a class="header" href="type-layout.html#the-align-representation" id="the-align-representation"><h3>The <code>align</code> Representation</h3></a>
<p>The <code>align</code> representation can be used on <code>struct</code>s and <code>union</code>s to raise the
alignment of the type to a given value.</p>
<p>Alignment is specified as a parameter in the form of <code>#[repr(align(x))]</code>. The
alignment value must be a power of two of type <code>u32</code>. The <code>align</code> representation
can raise the alignment of a type to be greater than it's primitive alignment,
it cannot lower the alignment of a type.</p>
<p>The <code>align</code> and <code>packed</code> representations cannot be applied on the same type and
a <code>packed</code> type cannot transitively contain another <code>align</code>ed type.</p>
<a class="header" href="type-layout.html#the-packed-representation" id="the-packed-representation"><h3>The <code>packed</code> Representation</h3></a>
<p>The <code>packed</code> representation can only be used on <code>struct</code>s and <code>union</code>s.</p>
<p>It modifies the representation (either the default or <code>C</code>) by removing any
padding bytes and forcing the alignment of the type to <code>1</code>.</p>
<p>The <code>align</code> and <code>packed</code> representations cannot be applied on the same type and
a <code>packed</code> type cannot transitively contain another <code>align</code>ed type.</p>
<blockquote>
<p>Warning: Dereferencing an unaligned pointer is [undefined behaviour] and it is
possible to <a href="https://github.com/rust-lang/rust/issues/27060">safely create unaligned pointers to <code>packed</code> fields</a>.
Like all ways to create undefined behavior in safe Rust, this is a bug.</p>
</blockquote>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="dynamically-sized-types.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="interior-mutability.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="dynamically-sized-types.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="interior-mutability.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
>
11158
