<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `pointer` primitive in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, pointer"><title>pointer - Rust</title><link rel="stylesheet" type="text/css" href="../normalize1.35.0.css"><link rel="stylesheet" type="text/css" href="../rustdoc1.35.0.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../dark1.35.0.css"><link rel="stylesheet" type="text/css" href="../light1.35.0.css" id="themeStyle"><script src="../storage1.35.0.js"></script><noscript><link rel="stylesheet" href="../noscript1.35.0.css"></noscript><link rel="shortcut icon" href="../favicon1.35.0.ico"><style type="text/css">#crate-search{background-image:url("../down-arrow1.35.0.svg");}</style></head><body class="rustdoc primitive"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../std/index.html'><img src='../rust-logo1.35.0.png' alt='logo' width='100'></a><p class='location'>Primitive Type pointer</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.add">add</a><a href="#method.add-1">add</a><a href="#method.align_offset">align_offset</a><a href="#method.align_offset-1">align_offset</a><a href="#method.as_mut">as_mut</a><a href="#method.as_ref">as_ref</a><a href="#method.as_ref-1">as_ref</a><a href="#method.copy_from">copy_from</a><a href="#method.copy_from_nonoverlapping">copy_from_nonoverlapping</a><a href="#method.copy_to">copy_to</a><a href="#method.copy_to-1">copy_to</a><a href="#method.copy_to_nonoverlapping">copy_to_nonoverlapping</a><a href="#method.copy_to_nonoverlapping-1">copy_to_nonoverlapping</a><a href="#method.drop_in_place">drop_in_place</a><a href="#method.is_null">is_null</a><a href="#method.is_null-1">is_null</a><a href="#method.offset">offset</a><a href="#method.offset-1">offset</a><a href="#method.offset_from">offset_from</a><a href="#method.offset_from-1">offset_from</a><a href="#method.read">read</a><a href="#method.read-1">read</a><a href="#method.read_unaligned">read_unaligned</a><a href="#method.read_unaligned-1">read_unaligned</a><a href="#method.read_volatile">read_volatile</a><a href="#method.read_volatile-1">read_volatile</a><a href="#method.replace">replace</a><a href="#method.sub">sub</a><a href="#method.sub-1">sub</a><a href="#method.swap">swap</a><a href="#method.wrapping_add">wrapping_add</a><a href="#method.wrapping_add-1">wrapping_add</a><a href="#method.wrapping_offset">wrapping_offset</a><a href="#method.wrapping_offset-1">wrapping_offset</a><a href="#method.wrapping_offset_from">wrapping_offset_from</a><a href="#method.wrapping_offset_from-1">wrapping_offset_from</a><a href="#method.wrapping_sub">wrapping_sub</a><a href="#method.wrapping_sub-1">wrapping_sub</a><a href="#method.write">write</a><a href="#method.write_bytes">write_bytes</a><a href="#method.write_unaligned">write_unaligned</a><a href="#method.write_volatile">write_volatile</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Clone">Clone</a><a href="#impl-CoerceUnsized%3C*const%20U%3E">CoerceUnsized<*const U></a><a href="#impl-CoerceUnsized%3C*mut%20U%3E">CoerceUnsized<*mut U></a><a href="#impl-Copy">Copy</a><a href="#impl-Debug">Debug</a><a href="#impl-DispatchFromDyn%3C*const%20U%3E">DispatchFromDyn<*const U></a><a href="#impl-DispatchFromDyn%3C*mut%20U%3E">DispatchFromDyn<*mut U></a><a href="#impl-Eq">Eq</a><a href="#impl-Hash">Hash</a><a href="#impl-Ord">Ord</a><a href="#impl-PartialEq%3C*const%20T%3E">PartialEq<*const T></a><a href="#impl-PartialEq%3C*mut%20T%3E">PartialEq<*mut T></a><a href="#impl-PartialOrd%3C*const%20T%3E">PartialOrd<*const T></a><a href="#impl-PartialOrd%3C*mut%20T%3E">PartialOrd<*mut T></a><a href="#impl-Pointer">Pointer</a><a href="#impl-Send">!Send</a><a href="#impl-Sync">!Sync</a><a href="#impl-UnwindSafe">UnwindSafe</a></div></div><p class='location'><a href='index.html'>std</a></p><script>window.sidebarCurrent = {name: 'pointer', ty: 'primitive', relpath: ''};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../brush1.35.0.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../theme1.35.0.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../settings.html"><img src="../wheel1.35.0.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span></span><span class='in-band'>Primitive Type <a class="primitive" href=''>pointer</a></span></h1><div class='docblock'><p>Raw, unsafe pointers, <code>*const T</code>, and <code>*mut T</code>.</p>
<p><em><a href="ptr/index.html">See also the <code>std::ptr</code> module</a>.</em></p>
<p>Working with raw pointers in Rust is uncommon,
typically limited to a few patterns.</p>
<p>Use the <a href="../std/ptr/fn.null.html"><code>null</code></a> and <a href="../std/ptr/fn.null_mut.html"><code>null_mut</code></a> functions to create null pointers, and the
<a href="../std/primitive.pointer.html#method.is_null"><code>is_null</code></a> method of the <code>*const T</code> and <code>*mut T</code> types to check for null.
The <code>*const T</code> and <code>*mut T</code> types also define the <a href="../std/primitive.pointer.html#method.offset"><code>offset</code></a> method, for
pointer math.</p>
<h1 id="common-ways-to-create-raw-pointers" class="section-header"><a href="#common-ways-to-create-raw-pointers">Common ways to create raw pointers</a></h1><h2 id="1-coerce-a-reference-t-or-mutable-reference-mut-t" class="section-header"><a href="#1-coerce-a-reference-t-or-mutable-reference-mut-t">1. Coerce a reference (<code>&T</code>) or mutable reference (<code>&mut T</code>).</a></h2>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">my_num</span>: <span class="ident">i32</span> <span class="op">=</span> <span class="number">10</span>;
<span class="kw">let</span> <span class="ident">my_num_ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">my_num</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">my_speed</span>: <span class="ident">i32</span> <span class="op">=</span> <span class="number">88</span>;
<span class="kw">let</span> <span class="ident">my_speed_ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">my_speed</span>;<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20my_num%3A%20i32%20%3D%2010%3B%0Alet%20my_num_ptr%3A%20*const%20i32%20%3D%20%26my_num%3B%0Alet%20mut%20my_speed%3A%20i32%20%3D%2088%3B%0Alet%20my_speed_ptr%3A%20*mut%20i32%20%3D%20%26mut%20my_speed%3B%0A%7D">Run</a></pre></div>
<p>To get a pointer to a boxed value, dereference the box:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">my_num</span>: <span class="ident">Box</span><span class="op"><</span><span class="ident">i32</span><span class="op">></span> <span class="op">=</span> <span class="ident">Box</span>::<span class="ident">new</span>(<span class="number">10</span>);
<span class="kw">let</span> <span class="ident">my_num_ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">*</span><span class="ident">my_num</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">my_speed</span>: <span class="ident">Box</span><span class="op"><</span><span class="ident">i32</span><span class="op">></span> <span class="op">=</span> <span class="ident">Box</span>::<span class="ident">new</span>(<span class="number">88</span>);
<span class="kw">let</span> <span class="ident">my_speed_ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="kw-2">*</span><span class="ident">my_speed</span>;<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20my_num%3A%20Box%3Ci32%3E%20%3D%20Box%3A%3Anew(10)%3B%0Alet%20my_num_ptr%3A%20*const%20i32%20%3D%20%26*my_num%3B%0Alet%20mut%20my_speed%3A%20Box%3Ci32%3E%20%3D%20Box%3A%3Anew(88)%3B%0Alet%20my_speed_ptr%3A%20*mut%20i32%20%3D%20%26mut%20*my_speed%3B%0A%7D">Run</a></pre></div>
<p>This does not take ownership of the original allocation
and requires no resource management later,
but you must not use the pointer after its lifetime.</p>
<h2 id="2-consume-a-box-boxt" class="section-header"><a href="#2-consume-a-box-boxt">2. Consume a box (<code>Box<T></code>).</a></h2>
<p>The <a href="../std/boxed/struct.Box.html#method.into_raw"><code>into_raw</code></a> function consumes a box and returns
the raw pointer. It doesn't destroy <code>T</code> or deallocate any memory.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">my_speed</span>: <span class="ident">Box</span><span class="op"><</span><span class="ident">i32</span><span class="op">></span> <span class="op">=</span> <span class="ident">Box</span>::<span class="ident">new</span>(<span class="number">88</span>);
<span class="kw">let</span> <span class="ident">my_speed</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="ident">Box</span>::<span class="ident">into_raw</span>(<span class="ident">my_speed</span>);
<span class="comment">// By taking ownership of the original `Box<T>` though</span>
<span class="comment">// we are obligated to put it together later to be destroyed.</span>
<span class="kw">unsafe</span> {
<span class="ident">drop</span>(<span class="ident">Box</span>::<span class="ident">from_raw</span>(<span class="ident">my_speed</span>));
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20my_speed%3A%20Box%3Ci32%3E%20%3D%20Box%3A%3Anew(88)%3B%0Alet%20my_speed%3A%20*mut%20i32%20%3D%20Box%3A%3Ainto_raw(my_speed)%3B%0A%0A%2F%2F%20By%20taking%20ownership%20of%20the%20original%20%60Box%3CT%3E%60%20though%0A%2F%2F%20we%20are%20obligated%20to%20put%20it%20together%20later%20to%20be%20destroyed.%0Aunsafe%20%7B%0A%20%20%20%20drop(Box%3A%3Afrom_raw(my_speed))%3B%0A%7D%0A%7D">Run</a></pre></div>
<p>Note that here the call to <a href="../std/mem/fn.drop.html"><code>drop</code></a> is for clarity - it indicates
that we are done with the given value and it should be destroyed.</p>
<h2 id="3-get-it-from-c" class="section-header"><a href="#3-get-it-from-c">3. Get it from C.</a></h2>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">libc</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">mem</span>;
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="kw">unsafe</span> {
<span class="kw">let</span> <span class="ident">my_num</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="ident">libc</span>::<span class="ident">malloc</span>(<span class="ident">mem</span>::<span class="ident">size_of</span>::<span class="op"><</span><span class="ident">i32</span><span class="op">></span>()) <span class="kw">as</span> <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span>;
<span class="kw">if</span> <span class="ident">my_num</span>.<span class="ident">is_null</span>() {
<span class="macro">panic</span><span class="macro">!</span>(<span class="string">"failed to allocate memory"</span>);
}
<span class="ident">libc</span>::<span class="ident">free</span>(<span class="ident">my_num</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">libc</span>::<span class="ident">c_void</span>);
}
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(rustc_private)%5D%0Aextern%20crate%20libc%3B%0A%0Ause%20std%3A%3Amem%3B%0A%0Afn%20main()%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20let%20my_num%3A%20*mut%20i32%20%3D%20libc%3A%3Amalloc(mem%3A%3Asize_of%3A%3A%3Ci32%3E())%20as%20*mut%20i32%3B%0A%20%20%20%20%20%20%20%20if%20my_num.is_null()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20panic!(%22failed%20to%20allocate%20memory%22)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20libc%3A%3Afree(my_num%20as%20*mut%20libc%3A%3Ac_void)%3B%0A%20%20%20%20%7D%0A%7D&version=nightly">Run</a></pre></div>
<p>Usually you wouldn't literally use <code>malloc</code> and <code>free</code> from Rust,
but C APIs hand out a lot of pointers generally, so are a common source
of raw pointers in Rust.</p>
</div><h2 id='methods' class='small-section-header'>Methods<a href='#methods' class='anchor'></a></h2><h3 id='impl' class='impl'><code class='in-band'>impl<T> <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#950-1566' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.is_null' class="method"><code id='is_null.v'>pub fn <a href='#method.is_null' class='fnname'>is_null</a>(self) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#969-973' title='goto source code'>[src]</a></h4><div class='docblock'><p>Returns <code>true</code> if the pointer is null.</p>
<p>Note that unsized types have many possible null pointers, as only the
raw data pointer is considered, not their length, vtable, etc.
Therefore, two pointers that are null may still not compare equal to
each other.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"Follow the rabbit"</span>;
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>();
<span class="macro">assert</span><span class="macro">!</span>(<span class="op">!</span><span class="ident">ptr</span>.<span class="ident">is_null</span>());<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22Follow%20the%20rabbit%22%3B%0Alet%20ptr%3A%20*const%20u8%20%3D%20s.as_ptr()%3B%0Aassert!(!ptr.is_null())%3B%0A%7D">Run</a></pre></div>
</div><h4 id='method.as_ref' class="method"><code id='as_ref.v'>pub unsafe fn <a href='#method.as_ref' class='fnname'>as_ref</a><'a>(self) -> <a class="enum" href="../std/option/enum.Option.html" title="enum std::option::Option">Option</a><<a class="primitive" href="primitive.reference.html">&'a </a>T></code><div class='since' title='Stable since Rust version 1.9.0'>1.9.0</div><a class='srclink' href='../src/core/ptr.rs.html#1018-1024' title='goto source code'>[src]</a></h4><div class='docblock'><p>Returns <code>None</code> if the pointer is null, or else returns a reference to
the value wrapped in <code>Some</code>.</p>
<h1 id="safety" class="section-header"><a href="#safety">Safety</a></h1>
<p>While this method and its mutable counterpart are useful for
null-safety, it is important to note that this is still an unsafe
operation because the returned value could be pointing to invalid
memory.</p>
<p>Additionally, the lifetime <code>'a</code> returned is arbitrarily chosen and does
not necessarily reflect the actual lifetime of the data.</p>
<h1 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="kw-2">&</span><span class="number">10u8</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span>;
<span class="kw">unsafe</span> {
<span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">val_back</span>) <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">as_ref</span>() {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"We got back the value: {}!"</span>, <span class="ident">val_back</span>);
}
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20ptr%3A%20*const%20u8%20%3D%20%2610u8%20as%20*const%20u8%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20if%20let%20Some(val_back)%20%3D%20ptr.as_ref()%20%7B%0A%20%20%20%20%20%20%20%20println!(%22We%20got%20back%20the%20value%3A%20%7B%7D!%22%2C%20val_back)%3B%0A%20%20%20%20%7D%0A%7D%0A%7D">Run</a></pre></div>
<h1 id="null-unchecked-version" class="section-header"><a href="#null-unchecked-version">Null-unchecked version</a></h1>
<p>If you are sure the pointer can never be null and are looking for some kind of
<code>as_ref_unchecked</code> that returns the <code>&T</code> instead of <code>Option<&T></code>, know that you can
dereference the pointer directly.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="kw-2">&</span><span class="number">10u8</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span>;
<span class="kw">unsafe</span> {
<span class="kw">let</span> <span class="ident">val_back</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">*</span><span class="ident">ptr</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"We got back the value: {}!"</span>, <span class="ident">val_back</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20ptr%3A%20*const%20u8%20%3D%20%2610u8%20as%20*const%20u8%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20let%20val_back%20%3D%20%26*ptr%3B%0A%20%20%20%20println!(%22We%20got%20back%20the%20value%3A%20%7B%7D!%22%2C%20val_back)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.offset' class="method"><code id='offset.v'>pub unsafe fn <a href='#method.offset' class='fnname'>offset</a>(self, count: <a class="primitive" href="primitive.isize.html">isize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><a class='srclink' href='../src/core/ptr.rs.html#1076-1078' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer.</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-1" class="section-header"><a href="#safety-1">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum, <strong>in bytes</strong> must fit in a usize.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-2" class="section-header"><a href="#examples-2">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"123"</span>;
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>();
<span class="kw">unsafe</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">offset</span>(<span class="number">1</span>) <span class="kw">as</span> <span class="ident">char</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">offset</span>(<span class="number">2</span>) <span class="kw">as</span> <span class="ident">char</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22123%22%3B%0Alet%20ptr%3A%20*const%20u8%20%3D%20s.as_ptr()%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.offset(1)%20as%20char)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.offset(2)%20as%20char)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_offset' class="method"><code id='wrapping_offset.v'>pub fn <a href='#method.wrapping_offset' class='fnname'>wrapping_offset</a>(self, count: <a class="primitive" href="primitive.isize.html">isize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><div class='since' title='Stable since Rust version 1.16.0'>1.16.0</div><a class='srclink' href='../src/core/ptr.rs.html#1120-1124' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-2" class="section-header"><a href="#safety-2">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).
In particular, the resulting pointer may <em>not</em> be used to access a
different allocated object than the one <code>self</code> points to. In other
words, <code>x.wrapping_offset(y.wrapping_offset_from(x))</code> is
<em>not</em> the same as <code>y</code>, and dereferencing it is undefined behavior
unless <code>x</code> and <code>y</code> point into the same allocated object.</p>
<p>Always use <code>.offset(count)</code> instead when possible, because <code>offset</code>
allows the compiler to optimize better. If you need to cross object
boundaries, cast the pointer to an integer and do the arithmetic there.</p>
<h1 id="examples-3" class="section-header"><a href="#examples-3">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements</span>
<span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_ptr</span>();
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="kw">let</span> <span class="ident">end_rounded_up</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_offset</span>(<span class="number">6</span>);
<span class="comment">// This loop prints "1, 3, 5, "</span>
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">end_rounded_up</span> {
<span class="kw">unsafe</span> {
<span class="macro">print</span><span class="macro">!</span>(<span class="string">"{}, "</span>, <span class="kw-2">*</span><span class="ident">ptr</span>);
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_offset</span>(<span class="ident">step</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%0Afn%20main()%20%7B%0Alet%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*const%20u8%20%3D%20data.as_ptr()%3B%0Alet%20step%20%3D%202%3B%0Alet%20end_rounded_up%20%3D%20ptr.wrapping_offset(6)%3B%0A%0A%2F%2F%20This%20loop%20prints%20%221%2C%203%2C%205%2C%20%22%0Awhile%20ptr%20!%3D%20end_rounded_up%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20print!(%22%7B%7D%2C%20%22%2C%20*ptr)%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_offset(step)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.offset_from' class="method"><code id='offset_from.v'>pub unsafe fn <a href='#method.offset_from' class='fnname'>offset_from</a>(self, origin: <a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.isize.html">isize</a></code><a class='srclink' href='../src/core/ptr.rs.html#1189-1198' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>ptr_offset_from</code> <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a>)</div></div><div class='docblock'><p>Calculates the distance between two pointers. The returned value is in
units of T: the distance in bytes is divided by <code>mem::size_of::<T>()</code>.</p>
<p>This function is the inverse of <a href="#method.offset"><code>offset</code></a>.</p>
<h1 id="safety-3" class="section-header"><a href="#safety-3">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and other pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The distance between the pointers, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The distance between the pointers, in bytes, must be an exact multiple
of the size of <code>T</code>.</p>
</li>
<li>
<p>The distance being in bounds cannot rely on "wrapping around" the address space.</p>
</li>
</ul>
<p>The compiler and standard library generally try to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>ptr_into_vec.offset_from(vec.as_ptr())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <a href="#method.wrapping_offset_from"><code>wrapping_offset_from</code></a> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<p>This function panics if <code>T</code> is a Zero-Sized Type ("ZST").</p>
<h1 id="examples-4" class="section-header"><a href="#examples-4">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="attribute">#![<span class="ident">feature</span>(<span class="ident">ptr_offset_from</span>)]</span>
<span class="kw">let</span> <span class="ident">a</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">5</span>];
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">a</span>[<span class="number">1</span>];
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">a</span>[<span class="number">3</span>];
<span class="kw">unsafe</span> {
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">offset_from</span>(<span class="ident">ptr2</span>), <span class="op">-</span><span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">offset</span>(<span class="number">2</span>), <span class="ident">ptr2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">offset</span>(<span class="op">-</span><span class="number">2</span>), <span class="ident">ptr1</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(ptr_offset_from)%5D%0A%0Afn%20main()%20%7B%0Alet%20a%20%3D%20%5B0%3B%205%5D%3B%0Alet%20ptr1%3A%20*const%20i32%20%3D%20%26a%5B1%5D%3B%0Alet%20ptr2%3A%20*const%20i32%20%3D%20%26a%5B3%5D%3B%0Aunsafe%20%7B%0A%20%20%20%20assert_eq!(ptr2.offset_from(ptr1)%2C%202)%3B%0A%20%20%20%20assert_eq!(ptr1.offset_from(ptr2)%2C%20-2)%3B%0A%20%20%20%20assert_eq!(ptr1.offset(2)%2C%20ptr2)%3B%0A%20%20%20%20assert_eq!(ptr2.offset(-2)%2C%20ptr1)%3B%0A%7D%0A%7D&version=nightly">Run</a></pre></div>
</div><h4 id='method.wrapping_offset_from' class="method"><code id='wrapping_offset_from.v'>pub fn <a href='#method.wrapping_offset_from' class='fnname'>wrapping_offset_from</a>(self, origin: <a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.isize.html">isize</a></code><a class='srclink' href='../src/core/ptr.rs.html#1236-1242' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>ptr_wrapping_offset_from</code> <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a>)</div></div><div class='docblock'><p>Calculates the distance between two pointers. The returned value is in
units of T: the distance in bytes is divided by <code>mem::size_of::<T>()</code>.</p>
<p>If the address different between the two pointers is not a multiple of
<code>mem::size_of::<T>()</code> then the result of the division is rounded towards
zero.</p>
<p>Though this method is safe for any two pointers, note that its result
will be mostly useless if the two pointers aren't into the same allocated
object, for example if they point to two different local variables.</p>
<h1 id="panics-1" class="section-header"><a href="#panics-1">Panics</a></h1>
<p>This function panics if <code>T</code> is a zero-sized type.</p>
<h1 id="examples-5" class="section-header"><a href="#examples-5">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="attribute">#![<span class="ident">feature</span>(<span class="ident">ptr_wrapping_offset_from</span>)]</span>
<span class="kw">let</span> <span class="ident">a</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">5</span>];
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">a</span>[<span class="number">1</span>];
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">a</span>[<span class="number">3</span>];
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr2</span>), <span class="op">-</span><span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">wrapping_offset</span>(<span class="number">2</span>), <span class="ident">ptr2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset</span>(<span class="op">-</span><span class="number">2</span>), <span class="ident">ptr1</span>);
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="number">3</span> <span class="kw">as</span> <span class="kw">_</span>;
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">i32</span> <span class="op">=</span> <span class="number">13</span> <span class="kw">as</span> <span class="kw">_</span>;
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(ptr_wrapping_offset_from)%5D%0A%0Afn%20main()%20%7B%0Alet%20a%20%3D%20%5B0%3B%205%5D%3B%0Alet%20ptr1%3A%20*const%20i32%20%3D%20%26a%5B1%5D%3B%0Alet%20ptr2%3A%20*const%20i32%20%3D%20%26a%5B3%5D%3B%0Aassert_eq!(ptr2.wrapping_offset_from(ptr1)%2C%202)%3B%0Aassert_eq!(ptr1.wrapping_offset_from(ptr2)%2C%20-2)%3B%0Aassert_eq!(ptr1.wrapping_offset(2)%2C%20ptr2)%3B%0Aassert_eq!(ptr2.wrapping_offset(-2)%2C%20ptr1)%3B%0A%0Alet%20ptr1%3A%20*const%20i32%20%3D%203%20as%20_%3B%0Alet%20ptr2%3A%20*const%20i32%20%3D%2013%20as%20_%3B%0Aassert_eq!(ptr2.wrapping_offset_from(ptr1)%2C%202)%3B%0A%7D&version=nightly">Run</a></pre></div>
</div><h4 id='method.add' class="method"><code id='add.v'>pub unsafe fn <a href='#method.add' class='fnname'>add</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1294-1298' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer (convenience for <code>.offset(count as isize)</code>).</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-4" class="section-header"><a href="#safety-4">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum must fit in a <code>usize</code>.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-6" class="section-header"><a href="#examples-6">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"123"</span>;
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>();
<span class="kw">unsafe</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">add</span>(<span class="number">1</span>) <span class="kw">as</span> <span class="ident">char</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">add</span>(<span class="number">2</span>) <span class="kw">as</span> <span class="ident">char</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22123%22%3B%0Alet%20ptr%3A%20*const%20u8%20%3D%20s.as_ptr()%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.add(1)%20as%20char)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.add(2)%20as%20char)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.sub' class="method"><code id='sub.v'>pub unsafe fn <a href='#method.sub' class='fnname'>sub</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1351-1355' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer (convenience for
<code>.offset((count as isize).wrapping_neg())</code>).</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-5" class="section-header"><a href="#safety-5">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset cannot exceed <code>isize::MAX</code> <strong>bytes</strong>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum must fit in a usize.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len()).sub(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-7" class="section-header"><a href="#examples-7">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"123"</span>;
<span class="kw">unsafe</span> {
<span class="kw">let</span> <span class="ident">end</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>().<span class="ident">add</span>(<span class="number">3</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">end</span>.<span class="ident">sub</span>(<span class="number">1</span>) <span class="kw">as</span> <span class="ident">char</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">end</span>.<span class="ident">sub</span>(<span class="number">2</span>) <span class="kw">as</span> <span class="ident">char</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22123%22%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20let%20end%3A%20*const%20u8%20%3D%20s.as_ptr().add(3)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*end.sub(1)%20as%20char)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*end.sub(2)%20as%20char)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_add' class="method"><code id='wrapping_add.v'>pub fn <a href='#method.wrapping_add' class='fnname'>wrapping_add</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1392-1396' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.
(convenience for <code>.wrapping_offset(count as isize)</code>)</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-6" class="section-header"><a href="#safety-6">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).</p>
<p>Always use <code>.add(count)</code> instead when possible, because <code>add</code>
allows the compiler to optimize better.</p>
<h1 id="examples-8" class="section-header"><a href="#examples-8">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements</span>
<span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_ptr</span>();
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="kw">let</span> <span class="ident">end_rounded_up</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="number">6</span>);
<span class="comment">// This loop prints "1, 3, 5, "</span>
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">end_rounded_up</span> {
<span class="kw">unsafe</span> {
<span class="macro">print</span><span class="macro">!</span>(<span class="string">"{}, "</span>, <span class="kw-2">*</span><span class="ident">ptr</span>);
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="ident">step</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%0Afn%20main()%20%7B%0Alet%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*const%20u8%20%3D%20data.as_ptr()%3B%0Alet%20step%20%3D%202%3B%0Alet%20end_rounded_up%20%3D%20ptr.wrapping_add(6)%3B%0A%0A%2F%2F%20This%20loop%20prints%20%221%2C%203%2C%205%2C%20%22%0Awhile%20ptr%20!%3D%20end_rounded_up%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20print!(%22%7B%7D%2C%20%22%2C%20*ptr)%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_add(step)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_sub' class="method"><code id='wrapping_sub.v'>pub fn <a href='#method.wrapping_sub' class='fnname'>wrapping_sub</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1433-1437' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.
(convenience for <code>.wrapping_offset((count as isize).wrapping_sub())</code>)</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-7" class="section-header"><a href="#safety-7">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).</p>
<p>Always use <code>.sub(count)</code> instead when possible, because <code>sub</code>
allows the compiler to optimize better.</p>
<h1 id="examples-9" class="section-header"><a href="#examples-9">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements (backwards)</span>
<span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_ptr</span>();
<span class="kw">let</span> <span class="ident">start_rounded_down</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_sub</span>(<span class="number">2</span>);
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="number">4</span>);
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="comment">// This loop prints "5, 3, 1, "</span>
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">start_rounded_down</span> {
<span class="kw">unsafe</span> {
<span class="macro">print</span><span class="macro">!</span>(<span class="string">"{}, "</span>, <span class="kw-2">*</span><span class="ident">ptr</span>);
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_sub</span>(<span class="ident">step</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%20(backwards)%0Afn%20main()%20%7B%0Alet%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*const%20u8%20%3D%20data.as_ptr()%3B%0Alet%20start_rounded_down%20%3D%20ptr.wrapping_sub(2)%3B%0Aptr%20%3D%20ptr.wrapping_add(4)%3B%0Alet%20step%20%3D%202%3B%0A%2F%2F%20This%20loop%20prints%20%225%2C%203%2C%201%2C%20%22%0Awhile%20ptr%20!%3D%20start_rounded_down%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20print!(%22%7B%7D%2C%20%22%2C%20*ptr)%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_sub(step)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.read' class="method"><code id='read.v'>pub unsafe fn <a href='#method.read' class='fnname'>read</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1447-1451' title='goto source code'>[src]</a></h4><div class='docblock'><p>Reads the value from <code>self</code> without moving it. This leaves the
memory in <code>self</code> unchanged.</p>
<p>See <a href="./ptr/fn.read.html"><code>ptr::read</code></a> for safety concerns and examples.</p>
</div><h4 id='method.read_volatile' class="method"><code id='read_volatile.v'>pub unsafe fn <a href='#method.read_volatile' class='fnname'>read_volatile</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1465-1469' title='goto source code'>[src]</a></h4><div class='docblock'><p>Performs a volatile read of the value from <code>self</code> without moving it. This
leaves the memory in <code>self</code> unchanged.</p>
<p>Volatile operations are intended to act on I/O memory, and are guaranteed
to not be elided or reordered by the compiler across other volatile
operations.</p>
<p>See <a href="./ptr/fn.read_volatile.html"><code>ptr::read_volatile</code></a> for safety concerns and examples.</p>
</div><h4 id='method.read_unaligned' class="method"><code id='read_unaligned.v'>pub unsafe fn <a href='#method.read_unaligned' class='fnname'>read_unaligned</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1481-1485' title='goto source code'>[src]</a></h4><div class='docblock'><p>Reads the value from <code>self</code> without moving it. This leaves the
memory in <code>self</code> unchanged.</p>
<p>Unlike <code>read</code>, the pointer may be unaligned.</p>
<p>See <a href="./ptr/fn.read_unaligned.html"><code>ptr::read_unaligned</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_to' class="method"><code id='copy_to.v'>pub unsafe fn <a href='#method.copy_to' class='fnname'>copy_to</a>(self, dest: <a class="primitive" href="primitive.pointer.html">*mut T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1497-1501' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>self</code> to <code>dest</code>. The source
and destination may overlap.</p>
<p>NOTE: this has the <em>same</em> argument order as <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a>.</p>
<p>See <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_to_nonoverlapping' class="method"><code id='copy_to_nonoverlapping.v'>pub unsafe fn <a href='#method.copy_to_nonoverlapping' class='fnname'>copy_to_nonoverlapping</a>(self, dest: <a class="primitive" href="primitive.pointer.html">*mut T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1513-1517' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>self</code> to <code>dest</code>. The source
and destination may <em>not</em> overlap.</p>
<p>NOTE: this has the <em>same</em> argument order as <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a>.</p>
<p>See <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a> for safety concerns and examples.</p>
</div><h4 id='method.align_offset' class="method"><code id='align_offset.v'>pub fn <a href='#method.align_offset' class='fnname'>align_offset</a>(self, align: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.usize.html">usize</a></code><a class='srclink' href='../src/core/ptr.rs.html#1558-1565' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>align_offset</code> <a href="https://github.com/rust-lang/rust/issues/44488">#44488</a>)</div></div><div class='docblock'><p>Computes the offset that needs to be applied to the pointer in order to make it aligned to
<code>align</code>.</p>
<p>If it is not possible to align the pointer, the implementation returns
<code>usize::max_value()</code>.</p>
<p>The offset is expressed in number of <code>T</code> elements, and not bytes. The value returned can be
used with the <code>offset</code> or <code>offset_to</code> methods.</p>
<p>There are no guarantees whatsover that offsetting the pointer will not overflow or go
beyond the allocation that the pointer points into. It is up to the caller to ensure that
the returned offset is correct in all terms other than alignment.</p>
<h1 id="panics-2" class="section-header"><a href="#panics-2">Panics</a></h1>
<p>The function panics if <code>align</code> is not a power-of-two.</p>
<h1 id="examples-10" class="section-header"><a href="#examples-10">Examples</a></h1>
<p>Accessing adjacent <code>u8</code> as <code>u16</code></p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> [<span class="number">5u8</span>, <span class="number">6u8</span>, <span class="number">7u8</span>, <span class="number">8u8</span>, <span class="number">9u8</span>];
<span class="kw">let</span> <span class="ident">ptr</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">x</span>[<span class="ident">n</span>] <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span>;
<span class="kw">let</span> <span class="ident">offset</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">align_offset</span>(<span class="ident">align_of</span>::<span class="op"><</span><span class="ident">u16</span><span class="op">></span>());
<span class="kw">if</span> <span class="ident">offset</span> <span class="op"><</span> <span class="ident">x</span>.<span class="ident">len</span>() <span class="op">-</span> <span class="ident">n</span> <span class="op">-</span> <span class="number">1</span> {
<span class="kw">let</span> <span class="ident">u16_ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">add</span>(<span class="ident">offset</span>) <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u16</span>;
<span class="macro">assert_ne</span><span class="macro">!</span>(<span class="kw-2">*</span><span class="ident">u16_ptr</span>, <span class="number">500</span>);
} <span class="kw">else</span> {
<span class="comment">// while the pointer can be aligned via `offset`, it would point</span>
<span class="comment">// outside the allocation</span>
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(align_offset)%5D%0Afn%20main()%20%7B%0Afn%20foo(n%3A%20usize)%20%7B%0Ause%20std%3A%3Amem%3A%3Aalign_of%3B%0Aunsafe%20%7B%0Alet%20x%20%3D%20%5B5u8%2C%206u8%2C%207u8%2C%208u8%2C%209u8%5D%3B%0Alet%20ptr%20%3D%20%26x%5Bn%5D%20as%20*const%20u8%3B%0Alet%20offset%20%3D%20ptr.align_offset(align_of%3A%3A%3Cu16%3E())%3B%0Aif%20offset%20%3C%20x.len()%20-%20n%20-%201%20%7B%0A%20%20%20%20let%20u16_ptr%20%3D%20ptr.add(offset)%20as%20*const%20u16%3B%0A%20%20%20%20assert_ne!(*u16_ptr%2C%20500)%3B%0A%7D%20else%20%7B%0A%20%20%20%20%2F%2F%20while%20the%20pointer%20can%20be%20aligned%20via%20%60offset%60%2C%20it%20would%20point%0A%20%20%20%20%2F%2F%20outside%20the%20allocation%0A%7D%0A%7D%20%7D%0A%7D&version=nightly">Run</a></pre></div>
</div></div><h3 id='impl-1' class='impl'><code class='in-band'>impl<T> <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-1' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#1570-2338' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.is_null-1' class="method"><code id='is_null.v-1'>pub fn <a href='#method.is_null-1' class='fnname'>is_null</a>(self) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#1589-1593' title='goto source code'>[src]</a></h4><div class='docblock'><p>Returns <code>true</code> if the pointer is null.</p>
<p>Note that unsized types have many possible null pointers, as only the
raw data pointer is considered, not their length, vtable, etc.
Therefore, two pointers that are null may still not compare equal to
each other.</p>
<h1 id="examples-11" class="section-header"><a href="#examples-11">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">s</span> <span class="op">=</span> [<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>];
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u32</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_mut_ptr</span>();
<span class="macro">assert</span><span class="macro">!</span>(<span class="op">!</span><span class="ident">ptr</span>.<span class="ident">is_null</span>());<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20mut%20s%20%3D%20%5B1%2C%202%2C%203%5D%3B%0Alet%20ptr%3A%20*mut%20u32%20%3D%20s.as_mut_ptr()%3B%0Aassert!(!ptr.is_null())%3B%0A%7D">Run</a></pre></div>
</div><h4 id='method.as_ref-1' class="method"><code id='as_ref.v-1'>pub unsafe fn <a href='#method.as_ref-1' class='fnname'>as_ref</a><'a>(self) -> <a class="enum" href="../std/option/enum.Option.html" title="enum std::option::Option">Option</a><<a class="primitive" href="primitive.reference.html">&'a </a>T></code><div class='since' title='Stable since Rust version 1.9.0'>1.9.0</div><a class='srclink' href='../src/core/ptr.rs.html#1638-1644' title='goto source code'>[src]</a></h4><div class='docblock'><p>Returns <code>None</code> if the pointer is null, or else returns a reference to
the value wrapped in <code>Some</code>.</p>
<h1 id="safety-8" class="section-header"><a href="#safety-8">Safety</a></h1>
<p>While this method and its mutable counterpart are useful for
null-safety, it is important to note that this is still an unsafe
operation because the returned value could be pointing to invalid
memory.</p>
<p>Additionally, the lifetime <code>'a</code> returned is arbitrarily chosen and does
not necessarily reflect the actual lifetime of the data.</p>
<h1 id="examples-12" class="section-header"><a href="#examples-12">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u8</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="number">10u8</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u8</span>;
<span class="kw">unsafe</span> {
<span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">val_back</span>) <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">as_ref</span>() {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"We got back the value: {}!"</span>, <span class="ident">val_back</span>);
}
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20ptr%3A%20*mut%20u8%20%3D%20%26mut%2010u8%20as%20*mut%20u8%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20if%20let%20Some(val_back)%20%3D%20ptr.as_ref()%20%7B%0A%20%20%20%20%20%20%20%20println!(%22We%20got%20back%20the%20value%3A%20%7B%7D!%22%2C%20val_back)%3B%0A%20%20%20%20%7D%0A%7D%0A%7D">Run</a></pre></div>
<h1 id="null-unchecked-version-1" class="section-header"><a href="#null-unchecked-version-1">Null-unchecked version</a></h1>
<p>If you are sure the pointer can never be null and are looking for some kind of
<code>as_ref_unchecked</code> that returns the <code>&T</code> instead of <code>Option<&T></code>, know that you can
dereference the pointer directly.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u8</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="number">10u8</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u8</span>;
<span class="kw">unsafe</span> {
<span class="kw">let</span> <span class="ident">val_back</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">*</span><span class="ident">ptr</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"We got back the value: {}!"</span>, <span class="ident">val_back</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20ptr%3A%20*mut%20u8%20%3D%20%26mut%2010u8%20as%20*mut%20u8%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20let%20val_back%20%3D%20%26*ptr%3B%0A%20%20%20%20println!(%22We%20got%20back%20the%20value%3A%20%7B%7D!%22%2C%20val_back)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.offset-1' class="method"><code id='offset.v-1'>pub unsafe fn <a href='#method.offset-1' class='fnname'>offset</a>(self, count: <a class="primitive" href="primitive.isize.html">isize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><a class='srclink' href='../src/core/ptr.rs.html#1696-1698' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer.</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-9" class="section-header"><a href="#safety-9">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum, <strong>in bytes</strong> must fit in a usize.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-13" class="section-header"><a href="#examples-13">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">s</span> <span class="op">=</span> [<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>];
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u32</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_mut_ptr</span>();
<span class="kw">unsafe</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">offset</span>(<span class="number">1</span>));
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">offset</span>(<span class="number">2</span>));
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20mut%20s%20%3D%20%5B1%2C%202%2C%203%5D%3B%0Alet%20ptr%3A%20*mut%20u32%20%3D%20s.as_mut_ptr()%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.offset(1))%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.offset(2))%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_offset-1' class="method"><code id='wrapping_offset.v-1'>pub fn <a href='#method.wrapping_offset-1' class='fnname'>wrapping_offset</a>(self, count: <a class="primitive" href="primitive.isize.html">isize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><div class='since' title='Stable since Rust version 1.16.0'>1.16.0</div><a class='srclink' href='../src/core/ptr.rs.html#1739-1743' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.
<code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-10" class="section-header"><a href="#safety-10">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).
In particular, the resulting pointer may <em>not</em> be used to access a
different allocated object than the one <code>self</code> points to. In other
words, <code>x.wrapping_offset(y.wrapping_offset_from(x))</code> is
<em>not</em> the same as <code>y</code>, and dereferencing it is undefined behavior
unless <code>x</code> and <code>y</code> point into the same allocated object.</p>
<p>Always use <code>.offset(count)</code> instead when possible, because <code>offset</code>
allows the compiler to optimize better. If you need to cross object
boundaries, cast the pointer to an integer and do the arithmetic there.</p>
<h1 id="examples-14" class="section-header"><a href="#examples-14">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_mut_ptr</span>();
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="kw">let</span> <span class="ident">end_rounded_up</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_offset</span>(<span class="number">6</span>);
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">end_rounded_up</span> {
<span class="kw">unsafe</span> {
<span class="kw-2">*</span><span class="ident">ptr</span> <span class="op">=</span> <span class="number">0</span>;
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_offset</span>(<span class="ident">step</span>);
}
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">data</span>, <span class="kw-2">&</span>[<span class="number">0</span>, <span class="number">2</span>, <span class="number">0</span>, <span class="number">4</span>, <span class="number">0</span>]);<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%0Afn%20main()%20%7B%0Alet%20mut%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*mut%20u8%20%3D%20data.as_mut_ptr()%3B%0Alet%20step%20%3D%202%3B%0Alet%20end_rounded_up%20%3D%20ptr.wrapping_offset(6)%3B%0A%0Awhile%20ptr%20!%3D%20end_rounded_up%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20*ptr%20%3D%200%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_offset(step)%3B%0A%7D%0Aassert_eq!(%26data%2C%20%26%5B0%2C%202%2C%200%2C%204%2C%200%5D)%3B%0A%7D">Run</a></pre></div>
</div><h4 id='method.as_mut' class="method"><code id='as_mut.v'>pub unsafe fn <a href='#method.as_mut' class='fnname'>as_mut</a><'a>(self) -> <a class="enum" href="../std/option/enum.Option.html" title="enum std::option::Option">Option</a><<a class="primitive" href="primitive.reference.html">&'a mut </a>T></code><div class='since' title='Stable since Rust version 1.9.0'>1.9.0</div><a class='srclink' href='../src/core/ptr.rs.html#1767-1773' title='goto source code'>[src]</a></h4><div class='docblock'><p>Returns <code>None</code> if the pointer is null, or else returns a mutable
reference to the value wrapped in <code>Some</code>.</p>
<h1 id="safety-11" class="section-header"><a href="#safety-11">Safety</a></h1>
<p>As with <code>as_ref</code>, this is unsafe because it cannot verify the validity
of the returned pointer, nor can it ensure that the lifetime <code>'a</code>
returned is indeed a valid lifetime for the contained data.</p>
<h1 id="examples-15" class="section-header"><a href="#examples-15">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">s</span> <span class="op">=</span> [<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>];
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">u32</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_mut_ptr</span>();
<span class="kw">let</span> <span class="ident">first_value</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="ident">ptr</span>.<span class="ident">as_mut</span>().<span class="ident">unwrap</span>() };
<span class="kw-2">*</span><span class="ident">first_value</span> <span class="op">=</span> <span class="number">4</span>;
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{:?}"</span>, <span class="ident">s</span>); <span class="comment">// It'll print: "[4, 2, 3]".</span><a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20mut%20s%20%3D%20%5B1%2C%202%2C%203%5D%3B%0Alet%20ptr%3A%20*mut%20u32%20%3D%20s.as_mut_ptr()%3B%0Alet%20first_value%20%3D%20unsafe%20%7B%20ptr.as_mut().unwrap()%20%7D%3B%0A*first_value%20%3D%204%3B%0Aprintln!(%22%7B%3A%3F%7D%22%2C%20s)%3B%20%2F%2F%20It'll%20print%3A%20%22%5B4%2C%202%2C%203%5D%22.%0A%7D">Run</a></pre></div>
</div><h4 id='method.offset_from-1' class="method"><code id='offset_from.v-1'>pub unsafe fn <a href='#method.offset_from-1' class='fnname'>offset_from</a>(self, origin: <a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.isize.html">isize</a></code><a class='srclink' href='../src/core/ptr.rs.html#1838-1840' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>ptr_offset_from</code> <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a>)</div></div><div class='docblock'><p>Calculates the distance between two pointers. The returned value is in
units of T: the distance in bytes is divided by <code>mem::size_of::<T>()</code>.</p>
<p>This function is the inverse of <a href="#method.offset-1"><code>offset</code></a>.</p>
<h1 id="safety-12" class="section-header"><a href="#safety-12">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and other pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The distance between the pointers, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The distance between the pointers, in bytes, must be an exact multiple
of the size of <code>T</code>.</p>
</li>
<li>
<p>The distance being in bounds cannot rely on "wrapping around" the address space.</p>
</li>
</ul>
<p>The compiler and standard library generally try to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>ptr_into_vec.offset_from(vec.as_ptr())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <a href="#method.wrapping_offset_from-1"><code>wrapping_offset_from</code></a> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="panics-3" class="section-header"><a href="#panics-3">Panics</a></h1>
<p>This function panics if <code>T</code> is a Zero-Sized Type ("ZST").</p>
<h1 id="examples-16" class="section-header"><a href="#examples-16">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="attribute">#![<span class="ident">feature</span>(<span class="ident">ptr_offset_from</span>)]</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">a</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">5</span>];
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">a</span>[<span class="number">1</span>];
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">a</span>[<span class="number">3</span>];
<span class="kw">unsafe</span> {
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">offset_from</span>(<span class="ident">ptr2</span>), <span class="op">-</span><span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">offset</span>(<span class="number">2</span>), <span class="ident">ptr2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">offset</span>(<span class="op">-</span><span class="number">2</span>), <span class="ident">ptr1</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(ptr_offset_from)%5D%0A%0Afn%20main()%20%7B%0Alet%20mut%20a%20%3D%20%5B0%3B%205%5D%3B%0Alet%20ptr1%3A%20*mut%20i32%20%3D%20%26mut%20a%5B1%5D%3B%0Alet%20ptr2%3A%20*mut%20i32%20%3D%20%26mut%20a%5B3%5D%3B%0Aunsafe%20%7B%0A%20%20%20%20assert_eq!(ptr2.offset_from(ptr1)%2C%202)%3B%0A%20%20%20%20assert_eq!(ptr1.offset_from(ptr2)%2C%20-2)%3B%0A%20%20%20%20assert_eq!(ptr1.offset(2)%2C%20ptr2)%3B%0A%20%20%20%20assert_eq!(ptr2.offset(-2)%2C%20ptr1)%3B%0A%7D%0A%7D&version=nightly">Run</a></pre></div>
</div><h4 id='method.wrapping_offset_from-1' class="method"><code id='wrapping_offset_from.v-1'>pub fn <a href='#method.wrapping_offset_from-1' class='fnname'>wrapping_offset_from</a>(self, origin: <a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.isize.html">isize</a></code><a class='srclink' href='../src/core/ptr.rs.html#1878-1880' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>ptr_wrapping_offset_from</code> <a href="https://github.com/rust-lang/rust/issues/41079">#41079</a>)</div></div><div class='docblock'><p>Calculates the distance between two pointers. The returned value is in
units of T: the distance in bytes is divided by <code>mem::size_of::<T>()</code>.</p>
<p>If the address different between the two pointers is not a multiple of
<code>mem::size_of::<T>()</code> then the result of the division is rounded towards
zero.</p>
<p>Though this method is safe for any two pointers, note that its result
will be mostly useless if the two pointers aren't into the same allocated
object, for example if they point to two different local variables.</p>
<h1 id="panics-4" class="section-header"><a href="#panics-4">Panics</a></h1>
<p>This function panics if <code>T</code> is a zero-sized type.</p>
<h1 id="examples-17" class="section-header"><a href="#examples-17">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="attribute">#![<span class="ident">feature</span>(<span class="ident">ptr_wrapping_offset_from</span>)]</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">a</span> <span class="op">=</span> [<span class="number">0</span>; <span class="number">5</span>];
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">a</span>[<span class="number">1</span>];
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="kw-2">&</span><span class="kw-2">mut</span> <span class="ident">a</span>[<span class="number">3</span>];
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr2</span>), <span class="op">-</span><span class="number">2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr1</span>.<span class="ident">wrapping_offset</span>(<span class="number">2</span>), <span class="ident">ptr2</span>);
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset</span>(<span class="op">-</span><span class="number">2</span>), <span class="ident">ptr1</span>);
<span class="kw">let</span> <span class="ident">ptr1</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="number">3</span> <span class="kw">as</span> <span class="kw">_</span>;
<span class="kw">let</span> <span class="ident">ptr2</span>: <span class="kw-2">*</span><span class="kw-2">mut</span> <span class="ident">i32</span> <span class="op">=</span> <span class="number">13</span> <span class="kw">as</span> <span class="kw">_</span>;
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">ptr2</span>.<span class="ident">wrapping_offset_from</span>(<span class="ident">ptr1</span>), <span class="number">2</span>);<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(ptr_wrapping_offset_from)%5D%0A%0Afn%20main()%20%7B%0Alet%20mut%20a%20%3D%20%5B0%3B%205%5D%3B%0Alet%20ptr1%3A%20*mut%20i32%20%3D%20%26mut%20a%5B1%5D%3B%0Alet%20ptr2%3A%20*mut%20i32%20%3D%20%26mut%20a%5B3%5D%3B%0Aassert_eq!(ptr2.wrapping_offset_from(ptr1)%2C%202)%3B%0Aassert_eq!(ptr1.wrapping_offset_from(ptr2)%2C%20-2)%3B%0Aassert_eq!(ptr1.wrapping_offset(2)%2C%20ptr2)%3B%0Aassert_eq!(ptr2.wrapping_offset(-2)%2C%20ptr1)%3B%0A%0Alet%20ptr1%3A%20*mut%20i32%20%3D%203%20as%20_%3B%0Alet%20ptr2%3A%20*mut%20i32%20%3D%2013%20as%20_%3B%0Aassert_eq!(ptr2.wrapping_offset_from(ptr1)%2C%202)%3B%0A%7D&version=nightly">Run</a></pre></div>
</div><h4 id='method.add-1' class="method"><code id='add.v-1'>pub unsafe fn <a href='#method.add-1' class='fnname'>add</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1932-1936' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer (convenience for <code>.offset(count as isize)</code>).</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-13" class="section-header"><a href="#safety-13">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset, <strong>in bytes</strong>, cannot overflow an <code>isize</code>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum must fit in a <code>usize</code>.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-18" class="section-header"><a href="#examples-18">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"123"</span>;
<span class="kw">let</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>();
<span class="kw">unsafe</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">add</span>(<span class="number">1</span>) <span class="kw">as</span> <span class="ident">char</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">ptr</span>.<span class="ident">add</span>(<span class="number">2</span>) <span class="kw">as</span> <span class="ident">char</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22123%22%3B%0Alet%20ptr%3A%20*const%20u8%20%3D%20s.as_ptr()%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.add(1)%20as%20char)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*ptr.add(2)%20as%20char)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.sub-1' class="method"><code id='sub.v-1'>pub unsafe fn <a href='#method.sub-1' class='fnname'>sub</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#1989-1993' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer (convenience for
<code>.offset((count as isize).wrapping_neg())</code>).</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-14" class="section-header"><a href="#safety-14">Safety</a></h1>
<p>If any of the following conditions are violated, the result is Undefined
Behavior:</p>
<ul>
<li>
<p>Both the starting and resulting pointer must be either in bounds or one
byte past the end of the same allocated object.</p>
</li>
<li>
<p>The computed offset cannot exceed <code>isize::MAX</code> <strong>bytes</strong>.</p>
</li>
<li>
<p>The offset being in bounds cannot rely on "wrapping around" the address
space. That is, the infinite-precision sum must fit in a usize.</p>
</li>
</ul>
<p>The compiler and standard library generally tries to ensure allocations
never reach a size where an offset is a concern. For instance, <code>Vec</code>
and <code>Box</code> ensure they never allocate more than <code>isize::MAX</code> bytes, so
<code>vec.as_ptr().add(vec.len()).sub(vec.len())</code> is always safe.</p>
<p>Most platforms fundamentally can't even construct such an allocation.
For instance, no known 64-bit platform can ever serve a request
for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
However, some 32-bit and 16-bit platforms may successfully serve a request for
more than <code>isize::MAX</code> bytes with things like Physical Address
Extension. As such, memory acquired directly from allocators or memory
mapped files <em>may</em> be too large to handle with this function.</p>
<p>Consider using <code>wrapping_offset</code> instead if these constraints are
difficult to satisfy. The only advantage of this method is that it
enables more aggressive compiler optimizations.</p>
<h1 id="examples-19" class="section-header"><a href="#examples-19">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">s</span>: <span class="kw-2">&</span><span class="ident">str</span> <span class="op">=</span> <span class="string">"123"</span>;
<span class="kw">unsafe</span> {
<span class="kw">let</span> <span class="ident">end</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">s</span>.<span class="ident">as_ptr</span>().<span class="ident">add</span>(<span class="number">3</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">end</span>.<span class="ident">sub</span>(<span class="number">1</span>) <span class="kw">as</span> <span class="ident">char</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">end</span>.<span class="ident">sub</span>(<span class="number">2</span>) <span class="kw">as</span> <span class="ident">char</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20s%3A%20%26str%20%3D%20%22123%22%3B%0A%0Aunsafe%20%7B%0A%20%20%20%20let%20end%3A%20*const%20u8%20%3D%20s.as_ptr().add(3)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*end.sub(1)%20as%20char)%3B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20*end.sub(2)%20as%20char)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_add-1' class="method"><code id='wrapping_add.v-1'>pub fn <a href='#method.wrapping_add-1' class='fnname'>wrapping_add</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2030-2034' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.
(convenience for <code>.wrapping_offset(count as isize)</code>)</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-15" class="section-header"><a href="#safety-15">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).</p>
<p>Always use <code>.add(count)</code> instead when possible, because <code>add</code>
allows the compiler to optimize better.</p>
<h1 id="examples-20" class="section-header"><a href="#examples-20">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements</span>
<span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_ptr</span>();
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="kw">let</span> <span class="ident">end_rounded_up</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="number">6</span>);
<span class="comment">// This loop prints "1, 3, 5, "</span>
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">end_rounded_up</span> {
<span class="kw">unsafe</span> {
<span class="macro">print</span><span class="macro">!</span>(<span class="string">"{}, "</span>, <span class="kw-2">*</span><span class="ident">ptr</span>);
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="ident">step</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%0Afn%20main()%20%7B%0Alet%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*const%20u8%20%3D%20data.as_ptr()%3B%0Alet%20step%20%3D%202%3B%0Alet%20end_rounded_up%20%3D%20ptr.wrapping_add(6)%3B%0A%0A%2F%2F%20This%20loop%20prints%20%221%2C%203%2C%205%2C%20%22%0Awhile%20ptr%20!%3D%20end_rounded_up%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20print!(%22%7B%7D%2C%20%22%2C%20*ptr)%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_add(step)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.wrapping_sub-1' class="method"><code id='wrapping_sub.v-1'>pub fn <a href='#method.wrapping_sub-1' class='fnname'>wrapping_sub</a>(self, count: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2071-2075' title='goto source code'>[src]</a></h4><div class='docblock'><p>Calculates the offset from a pointer using wrapping arithmetic.
(convenience for <code>.wrapping_offset((count as isize).wrapping_sub())</code>)</p>
<p><code>count</code> is in units of T; e.g., a <code>count</code> of 3 represents a pointer
offset of <code>3 * size_of::<T>()</code> bytes.</p>
<h1 id="safety-16" class="section-header"><a href="#safety-16">Safety</a></h1>
<p>The resulting pointer does not need to be in bounds, but it is
potentially hazardous to dereference (which requires <code>unsafe</code>).</p>
<p>Always use <code>.sub(count)</code> instead when possible, because <code>sub</code>
allows the compiler to optimize better.</p>
<h1 id="examples-21" class="section-header"><a href="#examples-21">Examples</a></h1>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="comment">// Iterate using a raw pointer in increments of two elements (backwards)</span>
<span class="kw">let</span> <span class="ident">data</span> <span class="op">=</span> [<span class="number">1u8</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">ptr</span>: <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span> <span class="op">=</span> <span class="ident">data</span>.<span class="ident">as_ptr</span>();
<span class="kw">let</span> <span class="ident">start_rounded_down</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_sub</span>(<span class="number">2</span>);
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_add</span>(<span class="number">4</span>);
<span class="kw">let</span> <span class="ident">step</span> <span class="op">=</span> <span class="number">2</span>;
<span class="comment">// This loop prints "5, 3, 1, "</span>
<span class="kw">while</span> <span class="ident">ptr</span> <span class="op">!=</span> <span class="ident">start_rounded_down</span> {
<span class="kw">unsafe</span> {
<span class="macro">print</span><span class="macro">!</span>(<span class="string">"{}, "</span>, <span class="kw-2">*</span><span class="ident">ptr</span>);
}
<span class="ident">ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">wrapping_sub</span>(<span class="ident">step</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%2F%2F%20Iterate%20using%20a%20raw%20pointer%20in%20increments%20of%20two%20elements%20(backwards)%0Afn%20main()%20%7B%0Alet%20data%20%3D%20%5B1u8%2C%202%2C%203%2C%204%2C%205%5D%3B%0Alet%20mut%20ptr%3A%20*const%20u8%20%3D%20data.as_ptr()%3B%0Alet%20start_rounded_down%20%3D%20ptr.wrapping_sub(2)%3B%0Aptr%20%3D%20ptr.wrapping_add(4)%3B%0Alet%20step%20%3D%202%3B%0A%2F%2F%20This%20loop%20prints%20%225%2C%203%2C%201%2C%20%22%0Awhile%20ptr%20!%3D%20start_rounded_down%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20print!(%22%7B%7D%2C%20%22%2C%20*ptr)%3B%0A%20%20%20%20%7D%0A%20%20%20%20ptr%20%3D%20ptr.wrapping_sub(step)%3B%0A%7D%0A%7D">Run</a></pre></div>
</div><h4 id='method.read-1' class="method"><code id='read.v-1'>pub unsafe fn <a href='#method.read-1' class='fnname'>read</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2085-2089' title='goto source code'>[src]</a></h4><div class='docblock'><p>Reads the value from <code>self</code> without moving it. This leaves the
memory in <code>self</code> unchanged.</p>
<p>See <a href="./ptr/fn.read.html"><code>ptr::read</code></a> for safety concerns and examples.</p>
</div><h4 id='method.read_volatile-1' class="method"><code id='read_volatile.v-1'>pub unsafe fn <a href='#method.read_volatile-1' class='fnname'>read_volatile</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2103-2107' title='goto source code'>[src]</a></h4><div class='docblock'><p>Performs a volatile read of the value from <code>self</code> without moving it. This
leaves the memory in <code>self</code> unchanged.</p>
<p>Volatile operations are intended to act on I/O memory, and are guaranteed
to not be elided or reordered by the compiler across other volatile
operations.</p>
<p>See <a href="./ptr/fn.read_volatile.html"><code>ptr::read_volatile</code></a> for safety concerns and examples.</p>
</div><h4 id='method.read_unaligned-1' class="method"><code id='read_unaligned.v-1'>pub unsafe fn <a href='#method.read_unaligned-1' class='fnname'>read_unaligned</a>(self) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2119-2123' title='goto source code'>[src]</a></h4><div class='docblock'><p>Reads the value from <code>self</code> without moving it. This leaves the
memory in <code>self</code> unchanged.</p>
<p>Unlike <code>read</code>, the pointer may be unaligned.</p>
<p>See <a href="./ptr/fn.read_unaligned.html"><code>ptr::read_unaligned</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_to-1' class="method"><code id='copy_to.v-1'>pub unsafe fn <a href='#method.copy_to-1' class='fnname'>copy_to</a>(self, dest: <a class="primitive" href="primitive.pointer.html">*mut T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2135-2139' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>self</code> to <code>dest</code>. The source
and destination may overlap.</p>
<p>NOTE: this has the <em>same</em> argument order as <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a>.</p>
<p>See <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_to_nonoverlapping-1' class="method"><code id='copy_to_nonoverlapping.v-1'>pub unsafe fn <a href='#method.copy_to_nonoverlapping-1' class='fnname'>copy_to_nonoverlapping</a>(self, dest: <a class="primitive" href="primitive.pointer.html">*mut T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2151-2155' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>self</code> to <code>dest</code>. The source
and destination may <em>not</em> overlap.</p>
<p>NOTE: this has the <em>same</em> argument order as <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a>.</p>
<p>See <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_from' class="method"><code id='copy_from.v'>pub unsafe fn <a href='#method.copy_from' class='fnname'>copy_from</a>(self, src: <a class="primitive" href="primitive.pointer.html">*const T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2167-2171' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>src</code> to <code>self</code>. The source
and destination may overlap.</p>
<p>NOTE: this has the <em>opposite</em> argument order of <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a>.</p>
<p>See <a href="./ptr/fn.copy.html"><code>ptr::copy</code></a> for safety concerns and examples.</p>
</div><h4 id='method.copy_from_nonoverlapping' class="method"><code id='copy_from_nonoverlapping.v'>pub unsafe fn <a href='#method.copy_from_nonoverlapping' class='fnname'>copy_from_nonoverlapping</a>(self, src: <a class="primitive" href="primitive.pointer.html">*const T</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2183-2187' title='goto source code'>[src]</a></h4><div class='docblock'><p>Copies <code>count * size_of<T></code> bytes from <code>src</code> to <code>self</code>. The source
and destination may <em>not</em> overlap.</p>
<p>NOTE: this has the <em>opposite</em> argument order of <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a>.</p>
<p>See <a href="./ptr/fn.copy_nonoverlapping.html"><code>ptr::copy_nonoverlapping</code></a> for safety concerns and examples.</p>
</div><h4 id='method.drop_in_place' class="method"><code id='drop_in_place.v'>pub unsafe fn <a href='#method.drop_in_place' class='fnname'>drop_in_place</a>(self)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2196-2198' title='goto source code'>[src]</a></h4><div class='docblock'><p>Executes the destructor (if any) of the pointed-to value.</p>
<p>See <a href="./ptr/fn.drop_in_place.html"><code>ptr::drop_in_place</code></a> for safety concerns and examples.</p>
</div><h4 id='method.write' class="method"><code id='write.v'>pub unsafe fn <a href='#method.write' class='fnname'>write</a>(self, val: T)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2208-2212' title='goto source code'>[src]</a></h4><div class='docblock'><p>Overwrites a memory location with the given value without reading or
dropping the old value.</p>
<p>See <a href="./ptr/fn.write.html"><code>ptr::write</code></a> for safety concerns and examples.</p>
</div><h4 id='method.write_bytes' class="method"><code id='write_bytes.v'>pub unsafe fn <a href='#method.write_bytes' class='fnname'>write_bytes</a>(self, val: <a class="primitive" href="primitive.u8.html">u8</a>, count: <a class="primitive" href="primitive.usize.html">usize</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2222-2226' title='goto source code'>[src]</a></h4><div class='docblock'><p>Invokes memset on the specified pointer, setting <code>count * size_of::<T>()</code>
bytes of memory starting at <code>self</code> to <code>val</code>.</p>
<p>See <a href="./ptr/fn.write_bytes.html"><code>ptr::write_bytes</code></a> for safety concerns and examples.</p>
</div><h4 id='method.write_volatile' class="method"><code id='write_volatile.v'>pub unsafe fn <a href='#method.write_volatile' class='fnname'>write_volatile</a>(self, val: T)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2240-2244' title='goto source code'>[src]</a></h4><div class='docblock'><p>Performs a volatile write of a memory location with the given value without
reading or dropping the old value.</p>
<p>Volatile operations are intended to act on I/O memory, and are guaranteed
to not be elided or reordered by the compiler across other volatile
operations.</p>
<p>See <a href="./ptr/fn.write_volatile.html"><code>ptr::write_volatile</code></a> for safety concerns and examples.</p>
</div><h4 id='method.write_unaligned' class="method"><code id='write_unaligned.v'>pub unsafe fn <a href='#method.write_unaligned' class='fnname'>write_unaligned</a>(self, val: T)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2256-2260' title='goto source code'>[src]</a></h4><div class='docblock'><p>Overwrites a memory location with the given value without reading or
dropping the old value.</p>
<p>Unlike <code>write</code>, the pointer may be unaligned.</p>
<p>See <a href="./ptr/fn.write_unaligned.html"><code>ptr::write_unaligned</code></a> for safety concerns and examples.</p>
</div><h4 id='method.replace' class="method"><code id='replace.v'>pub unsafe fn <a href='#method.replace' class='fnname'>replace</a>(self, src: T) -> T</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2270-2274' title='goto source code'>[src]</a></h4><div class='docblock'><p>Replaces the value at <code>self</code> with <code>src</code>, returning the old
value, without dropping either.</p>
<p>See <a href="./ptr/fn.replace.html"><code>ptr::replace</code></a> for safety concerns and examples.</p>
</div><h4 id='method.swap' class="method"><code id='swap.v'>pub unsafe fn <a href='#method.swap' class='fnname'>swap</a>(self, with: <a class="primitive" href="primitive.pointer.html">*mut T</a>)</code><div class='since' title='Stable since Rust version 1.26.0'>1.26.0</div><a class='srclink' href='../src/core/ptr.rs.html#2285-2289' title='goto source code'>[src]</a></h4><div class='docblock'><p>Swaps the values at two mutable locations of the same type, without
deinitializing either. They may overlap, unlike <code>mem::swap</code> which is
otherwise equivalent.</p>
<p>See <a href="./ptr/fn.swap.html"><code>ptr::swap</code></a> for safety concerns and examples.</p>
</div><h4 id='method.align_offset-1' class="method"><code id='align_offset.v-1'>pub fn <a href='#method.align_offset-1' class='fnname'>align_offset</a>(self, align: <a class="primitive" href="primitive.usize.html">usize</a>) -> <a class="primitive" href="primitive.usize.html">usize</a></code><a class='srclink' href='../src/core/ptr.rs.html#2330-2337' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>align_offset</code> <a href="https://github.com/rust-lang/rust/issues/44488">#44488</a>)</div></div><div class='docblock'><p>Computes the offset that needs to be applied to the pointer in order to make it aligned to
<code>align</code>.</p>
<p>If it is not possible to align the pointer, the implementation returns
<code>usize::max_value()</code>.</p>
<p>The offset is expressed in number of <code>T</code> elements, and not bytes. The value returned can be
used with the <code>offset</code> or <code>offset_to</code> methods.</p>
<p>There are no guarantees whatsover that offsetting the pointer will not overflow or go
beyond the allocation that the pointer points into. It is up to the caller to ensure that
the returned offset is correct in all terms other than alignment.</p>
<h1 id="panics-5" class="section-header"><a href="#panics-5">Panics</a></h1>
<p>The function panics if <code>align</code> is not a power-of-two.</p>
<h1 id="examples-22" class="section-header"><a href="#examples-22">Examples</a></h1>
<p>Accessing adjacent <code>u8</code> as <code>u16</code></p>
<div class="example-wrap"><pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> [<span class="number">5u8</span>, <span class="number">6u8</span>, <span class="number">7u8</span>, <span class="number">8u8</span>, <span class="number">9u8</span>];
<span class="kw">let</span> <span class="ident">ptr</span> <span class="op">=</span> <span class="kw-2">&</span><span class="ident">x</span>[<span class="ident">n</span>] <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u8</span>;
<span class="kw">let</span> <span class="ident">offset</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">align_offset</span>(<span class="ident">align_of</span>::<span class="op"><</span><span class="ident">u16</span><span class="op">></span>());
<span class="kw">if</span> <span class="ident">offset</span> <span class="op"><</span> <span class="ident">x</span>.<span class="ident">len</span>() <span class="op">-</span> <span class="ident">n</span> <span class="op">-</span> <span class="number">1</span> {
<span class="kw">let</span> <span class="ident">u16_ptr</span> <span class="op">=</span> <span class="ident">ptr</span>.<span class="ident">add</span>(<span class="ident">offset</span>) <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">u16</span>;
<span class="macro">assert_ne</span><span class="macro">!</span>(<span class="kw-2">*</span><span class="ident">u16_ptr</span>, <span class="number">500</span>);
} <span class="kw">else</span> {
<span class="comment">// while the pointer can be aligned via `offset`, it would point</span>
<span class="comment">// outside the allocation</span>
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(align_offset)%5D%0Afn%20main()%20%7B%0Afn%20foo(n%3A%20usize)%20%7B%0Ause%20std%3A%3Amem%3A%3Aalign_of%3B%0Aunsafe%20%7B%0Alet%20x%20%3D%20%5B5u8%2C%206u8%2C%207u8%2C%208u8%2C%209u8%5D%3B%0Alet%20ptr%20%3D%20%26x%5Bn%5D%20as%20*const%20u8%3B%0Alet%20offset%20%3D%20ptr.align_offset(align_of%3A%3A%3Cu16%3E())%3B%0Aif%20offset%20%3C%20x.len()%20-%20n%20-%201%20%7B%0A%20%20%20%20let%20u16_ptr%20%3D%20ptr.add(offset)%20as%20*const%20u16%3B%0A%20%20%20%20assert_ne!(*u16_ptr%2C%20500)%3B%0A%7D%20else%20%7B%0A%20%20%20%20%2F%2F%20while%20the%20pointer%20can%20be%20aligned%20via%20%60offset%60%2C%20it%20would%20point%0A%20%20%20%20%2F%2F%20outside%20the%20allocation%0A%7D%0A%7D%20%7D%0A%7D&version=nightly">Run</a></pre></div>
</div></div><h2 id='implementations' class='small-section-header'>Trait Implementations<a href='#implementations' class='anchor'></a></h2><div id='implementations-list'><h3 id='impl-Clone' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/clone/trait.Clone.html" title="trait std::clone::Clone">Clone</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Clone' class='anchor'></a><a class='srclink' href='../src/core/clone.rs.html#199-204' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.clone' class="method hidden"><code id='clone.v'>fn <a href='../std/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> <a class="primitive" href="primitive.pointer.html">*mut T</a></code><a class='srclink' href='../src/core/clone.rs.html#201-203' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Returns a copy of the value. <a href="../std/clone/trait.Clone.html#tymethod.clone">Read more</a></p>
</div><h4 id='method.clone_from' class="method"><code id='clone_from.v'>fn <a href='../std/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: <a class="primitive" href="primitive.reference.html">&</a>Self)</code><a class='srclink' href='../src/core/clone.rs.html#131-133' title='goto source code'>[src]</a></h4><div class='docblock'><p>Performs copy-assignment from <code>source</code>. <a href="../std/clone/trait.Clone.html#method.clone_from">Read more</a></p>
</div></div><h3 id='impl-Clone-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/clone/trait.Clone.html" title="trait std::clone::Clone">Clone</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Clone-1' class='anchor'></a><a class='srclink' href='../src/core/clone.rs.html#191-196' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.clone-1' class="method hidden"><code id='clone.v-1'>fn <a href='../std/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> <a class="primitive" href="primitive.pointer.html">*const T</a></code><a class='srclink' href='../src/core/clone.rs.html#193-195' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Returns a copy of the value. <a href="../std/clone/trait.Clone.html#tymethod.clone">Read more</a></p>
</div><h4 id='method.clone_from-1' class="method"><code id='clone_from.v-1'>fn <a href='../std/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: <a class="primitive" href="primitive.reference.html">&</a>Self)</code><a class='srclink' href='../src/core/clone.rs.html#131-133' title='goto source code'>[src]</a></h4><div class='docblock'><p>Performs copy-assignment from <code>source</code>. <a href="../std/clone/trait.Clone.html#method.clone_from">Read more</a></p>
</div></div><h3 id='impl-Eq' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.Eq.html" title="trait std::cmp::Eq">Eq</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Eq' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2474' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Eq-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.Eq.html" title="trait std::cmp::Eq">Eq</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Eq-1' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2465' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-DispatchFromDyn%3C*mut%20U%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="../std/ops/trait.DispatchFromDyn.html" title="trait std::ops::DispatchFromDyn">DispatchFromDyn</a><<a class="primitive" href="primitive.pointer.html">*mut U</a>> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../std/marker/trait.Unsize.html" title="trait std::marker::Unsize">Unsize</a><U> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>,<br> U: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-DispatchFromDyn%3C*mut%20U%3E' class='anchor'></a><a class='srclink' href='../src/core/ops/unsize.rs.html#102' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-DispatchFromDyn%3C*const%20U%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="../std/ops/trait.DispatchFromDyn.html" title="trait std::ops::DispatchFromDyn">DispatchFromDyn</a><<a class="primitive" href="primitive.pointer.html">*const U</a>> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../std/marker/trait.Unsize.html" title="trait std::marker::Unsize">Unsize</a><U> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>,<br> U: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-DispatchFromDyn%3C*const%20U%3E' class='anchor'></a><a class='srclink' href='../src/core/ops/unsize.rs.html#99' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-CoerceUnsized%3C*const%20U%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="../std/ops/trait.CoerceUnsized.html" title="trait std::ops::CoerceUnsized">CoerceUnsized</a><<a class="primitive" href="primitive.pointer.html">*const U</a>> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../std/marker/trait.Unsize.html" title="trait std::marker::Unsize">Unsize</a><U> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>,<br> U: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-CoerceUnsized%3C*const%20U%3E' class='anchor'></a><a class='srclink' href='../src/core/ops/unsize.rs.html#65' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-CoerceUnsized%3C*mut%20U%3E' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="../std/ops/trait.CoerceUnsized.html" title="trait std::ops::CoerceUnsized">CoerceUnsized</a><<a class="primitive" href="primitive.pointer.html">*mut U</a>> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../std/marker/trait.Unsize.html" title="trait std::marker::Unsize">Unsize</a><U> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>,<br> U: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-CoerceUnsized%3C*mut%20U%3E' class='anchor'></a><a class='srclink' href='../src/core/ops/unsize.rs.html#62' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-CoerceUnsized%3C*const%20U%3E-1' class='impl'><code class='in-band'>impl<T, U> <a class="trait" href="../std/ops/trait.CoerceUnsized.html" title="trait std::ops::CoerceUnsized">CoerceUnsized</a><<a class="primitive" href="primitive.pointer.html">*const U</a>> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../std/marker/trait.Unsize.html" title="trait std::marker::Unsize">Unsize</a><U> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>,<br> U: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-CoerceUnsized%3C*const%20U%3E-1' class='anchor'></a><a class='srclink' href='../src/core/ops/unsize.rs.html#69' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Send' class='impl'><code class='in-band'>impl<T> !<a class="trait" href="../std/marker/trait.Send.html" title="trait std::marker::Send">Send</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Send' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#43' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Send-1' class='impl'><code class='in-band'>impl<T> !<a class="trait" href="../std/marker/trait.Send.html" title="trait std::marker::Send">Send</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Send-1' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#41' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Pointer' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/fmt/trait.Pointer.html" title="trait std::fmt::Pointer">Pointer</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Pointer' class='anchor'></a><a class='srclink' href='../src/core/fmt/mod.rs.html#2006-2031' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.fmt' class="method hidden"><code id='fmt.v'>fn <a href='../std/fmt/trait.Pointer.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="enum" href="../std/result/enum.Result.html" title="enum std::result::Result">Result</a><<a class="primitive" href="primitive.unit.html">()</a>, <a class="struct" href="../std/fmt/struct.Error.html" title="struct std::fmt::Error">Error</a>></code><a class='srclink' href='../src/core/fmt/mod.rs.html#2007-2030' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Formats the value using the given formatter.</p>
</div></div><h3 id='impl-Pointer-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/fmt/trait.Pointer.html" title="trait std::fmt::Pointer">Pointer</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Pointer-1' class='anchor'></a><a class='srclink' href='../src/core/fmt/mod.rs.html#2034-2038' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.fmt-1' class="method hidden"><code id='fmt.v-1'>fn <a href='../std/fmt/trait.Pointer.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="enum" href="../std/result/enum.Result.html" title="enum std::result::Result">Result</a><<a class="primitive" href="primitive.unit.html">()</a>, <a class="struct" href="../std/fmt/struct.Error.html" title="struct std::fmt::Error">Error</a>></code><a class='srclink' href='../src/core/fmt/mod.rs.html#2035-2037' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Formats the value using the given formatter.</p>
</div></div><h3 id='impl-PartialOrd%3C*const%20T%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.PartialOrd.html" title="trait std::cmp::PartialOrd">PartialOrd</a><<a class="primitive" href="primitive.pointer.html">*const T</a>> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-PartialOrd%3C*const%20T%3E' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2688-2705' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.partial_cmp' class="method hidden"><code id='partial_cmp.v'>fn <a href='../std/cmp/trait.PartialOrd.html#tymethod.partial_cmp' class='fnname'>partial_cmp</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="enum" href="../std/option/enum.Option.html" title="enum std::option::Option">Option</a><<a class="enum" href="../std/cmp/enum.Ordering.html" title="enum std::cmp::Ordering">Ordering</a>></code><a class='srclink' href='../src/core/ptr.rs.html#2690-2692' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method returns an ordering between <code>self</code> and <code>other</code> values if one exists. <a href="../std/cmp/trait.PartialOrd.html#tymethod.partial_cmp">Read more</a></p>
</div><h4 id='method.lt' class="method hidden"><code id='lt.v'>fn <a href='../std/cmp/trait.PartialOrd.html#method.lt' class='fnname'>lt</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2695' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests less than (for <code>self</code> and <code>other</code>) and is used by the <code><</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.lt">Read more</a></p>
</div><h4 id='method.le' class="method hidden"><code id='le.v'>fn <a href='../std/cmp/trait.PartialOrd.html#method.le' class='fnname'>le</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2698' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests less than or equal to (for <code>self</code> and <code>other</code>) and is used by the <code><=</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.le">Read more</a></p>
</div><h4 id='method.gt' class="method hidden"><code id='gt.v'>fn <a href='../std/cmp/trait.PartialOrd.html#method.gt' class='fnname'>gt</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2701' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests greater than (for <code>self</code> and <code>other</code>) and is used by the <code>></code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.gt">Read more</a></p>
</div><h4 id='method.ge' class="method hidden"><code id='ge.v'>fn <a href='../std/cmp/trait.PartialOrd.html#method.ge' class='fnname'>ge</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2704' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests greater than or equal to (for <code>self</code> and <code>other</code>) and is used by the <code>>=</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.ge">Read more</a></p>
</div></div><h3 id='impl-PartialOrd%3C*mut%20T%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.PartialOrd.html" title="trait std::cmp::PartialOrd">PartialOrd</a><<a class="primitive" href="primitive.pointer.html">*mut T</a>> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-PartialOrd%3C*mut%20T%3E' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2722-2739' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.partial_cmp-1' class="method hidden"><code id='partial_cmp.v-1'>fn <a href='../std/cmp/trait.PartialOrd.html#tymethod.partial_cmp' class='fnname'>partial_cmp</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="enum" href="../std/option/enum.Option.html" title="enum std::option::Option">Option</a><<a class="enum" href="../std/cmp/enum.Ordering.html" title="enum std::cmp::Ordering">Ordering</a>></code><a class='srclink' href='../src/core/ptr.rs.html#2724-2726' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method returns an ordering between <code>self</code> and <code>other</code> values if one exists. <a href="../std/cmp/trait.PartialOrd.html#tymethod.partial_cmp">Read more</a></p>
</div><h4 id='method.lt-1' class="method hidden"><code id='lt.v-1'>fn <a href='../std/cmp/trait.PartialOrd.html#method.lt' class='fnname'>lt</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2729' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests less than (for <code>self</code> and <code>other</code>) and is used by the <code><</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.lt">Read more</a></p>
</div><h4 id='method.le-1' class="method hidden"><code id='le.v-1'>fn <a href='../std/cmp/trait.PartialOrd.html#method.le' class='fnname'>le</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2732' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests less than or equal to (for <code>self</code> and <code>other</code>) and is used by the <code><=</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.le">Read more</a></p>
</div><h4 id='method.gt-1' class="method hidden"><code id='gt.v-1'>fn <a href='../std/cmp/trait.PartialOrd.html#method.gt' class='fnname'>gt</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2735' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests greater than (for <code>self</code> and <code>other</code>) and is used by the <code>></code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.gt">Read more</a></p>
</div><h4 id='method.ge-1' class="method hidden"><code id='ge.v-1'>fn <a href='../std/cmp/trait.PartialOrd.html#method.ge' class='fnname'>ge</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2738' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests greater than or equal to (for <code>self</code> and <code>other</code>) and is used by the <code>>=</code> operator. <a href="../std/cmp/trait.PartialOrd.html#method.ge">Read more</a></p>
</div></div><h3 id='impl-PartialEq%3C*const%20T%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.PartialEq.html" title="trait std::cmp::PartialEq">PartialEq</a><<a class="primitive" href="primitive.pointer.html">*const T</a>> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-PartialEq%3C*const%20T%3E' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2459-2462' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.eq' class="method hidden"><code id='eq.v'>fn <a href='../std/cmp/trait.PartialEq.html#tymethod.eq' class='fnname'>eq</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2461' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests for <code>self</code> and <code>other</code> values to be equal, and is used by <code>==</code>. <a href="../std/cmp/trait.PartialEq.html#tymethod.eq">Read more</a></p>
</div><h4 id='method.ne' class="method"><code id='ne.v'><div class="docblock attributes">#[must_use]
</div>fn <a href='../std/cmp/trait.PartialEq.html#method.ne' class='fnname'>ne</a>(&self, other: <a class="primitive" href="primitive.reference.html">&</a>Rhs) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/cmp.rs.html#200' title='goto source code'>[src]</a></h4><div class='docblock'><p>This method tests for <code>!=</code>.</p>
</div></div><h3 id='impl-PartialEq%3C*mut%20T%3E' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.PartialEq.html" title="trait std::cmp::PartialEq">PartialEq</a><<a class="primitive" href="primitive.pointer.html">*mut T</a>> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-PartialEq%3C*mut%20T%3E' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2468-2471' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.eq-1' class="method hidden"><code id='eq.v-1'>fn <a href='../std/cmp/trait.PartialEq.html#tymethod.eq' class='fnname'>eq</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/ptr.rs.html#2470' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method tests for <code>self</code> and <code>other</code> values to be equal, and is used by <code>==</code>. <a href="../std/cmp/trait.PartialEq.html#tymethod.eq">Read more</a></p>
</div><h4 id='method.ne-1' class="method"><code id='ne.v-1'><div class="docblock attributes">#[must_use]
</div>fn <a href='../std/cmp/trait.PartialEq.html#method.ne' class='fnname'>ne</a>(&self, other: <a class="primitive" href="primitive.reference.html">&</a>Rhs) -> <a class="primitive" href="primitive.bool.html">bool</a></code><a class='srclink' href='../src/core/cmp.rs.html#200' title='goto source code'>[src]</a></h4><div class='docblock'><p>This method tests for <code>!=</code>.</p>
</div></div><h3 id='impl-Ord' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.Ord.html" title="trait std::cmp::Ord">Ord</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Ord' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2674-2685' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.cmp' class="method hidden"><code id='cmp.v'>fn <a href='../std/cmp/trait.Ord.html#tymethod.cmp' class='fnname'>cmp</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*const T</a>) -> <a class="enum" href="../std/cmp/enum.Ordering.html" title="enum std::cmp::Ordering">Ordering</a></code><a class='srclink' href='../src/core/ptr.rs.html#2676-2684' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method returns an <code>Ordering</code> between <code>self</code> and <code>other</code>. <a href="../std/cmp/trait.Ord.html#tymethod.cmp">Read more</a></p>
</div><h4 id='method.max' class="method"><code id='max.v'>fn <a href='../std/cmp/trait.Ord.html#method.max' class='fnname'>max</a>(self, other: Self) -> Self</code><div class='since' title='Stable since Rust version 1.21.0'>1.21.0</div><a class='srclink' href='../src/core/cmp.rs.html#549-552' title='goto source code'>[src]</a></h4><div class='docblock'><p>Compares and returns the maximum of two values. <a href="../std/cmp/trait.Ord.html#method.max">Read more</a></p>
</div><h4 id='method.min' class="method"><code id='min.v'>fn <a href='../std/cmp/trait.Ord.html#method.min' class='fnname'>min</a>(self, other: Self) -> Self</code><div class='since' title='Stable since Rust version 1.21.0'>1.21.0</div><a class='srclink' href='../src/core/cmp.rs.html#566-569' title='goto source code'>[src]</a></h4><div class='docblock'><p>Compares and returns the minimum of two values. <a href="../std/cmp/trait.Ord.html#method.min">Read more</a></p>
</div><h4 id='method.clamp' class="method"><code id='clamp.v'>fn <a href='../std/cmp/trait.Ord.html#method.clamp' class='fnname'>clamp</a>(self, min: Self, max: Self) -> Self</code><a class='srclink' href='../src/core/cmp.rs.html#590-600' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>clamp</code> <a href="https://github.com/rust-lang/rust/issues/44095">#44095</a>)</div></div><div class='docblock'><p>Restrict a value to a certain interval. <a href="../std/cmp/trait.Ord.html#method.clamp">Read more</a></p>
</div></div><h3 id='impl-Ord-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/cmp/trait.Ord.html" title="trait std::cmp::Ord">Ord</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Ord-1' class='anchor'></a><a class='srclink' href='../src/core/ptr.rs.html#2708-2719' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.cmp-1' class="method hidden"><code id='cmp.v-1'>fn <a href='../std/cmp/trait.Ord.html#tymethod.cmp' class='fnname'>cmp</a>(&self, other: &<a class="primitive" href="primitive.pointer.html">*mut T</a>) -> <a class="enum" href="../std/cmp/enum.Ordering.html" title="enum std::cmp::Ordering">Ordering</a></code><a class='srclink' href='../src/core/ptr.rs.html#2710-2718' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>This method returns an <code>Ordering</code> between <code>self</code> and <code>other</code>. <a href="../std/cmp/trait.Ord.html#tymethod.cmp">Read more</a></p>
</div><h4 id='method.max-1' class="method"><code id='max.v-1'>fn <a href='../std/cmp/trait.Ord.html#method.max' class='fnname'>max</a>(self, other: Self) -> Self</code><div class='since' title='Stable since Rust version 1.21.0'>1.21.0</div><a class='srclink' href='../src/core/cmp.rs.html#549-552' title='goto source code'>[src]</a></h4><div class='docblock'><p>Compares and returns the maximum of two values. <a href="../std/cmp/trait.Ord.html#method.max">Read more</a></p>
</div><h4 id='method.min-1' class="method"><code id='min.v-1'>fn <a href='../std/cmp/trait.Ord.html#method.min' class='fnname'>min</a>(self, other: Self) -> Self</code><div class='since' title='Stable since Rust version 1.21.0'>1.21.0</div><a class='srclink' href='../src/core/cmp.rs.html#566-569' title='goto source code'>[src]</a></h4><div class='docblock'><p>Compares and returns the minimum of two values. <a href="../std/cmp/trait.Ord.html#method.min">Read more</a></p>
</div><h4 id='method.clamp-1' class="method"><code id='clamp.v-1'>fn <a href='../std/cmp/trait.Ord.html#method.clamp' class='fnname'>clamp</a>(self, min: Self, max: Self) -> Self</code><a class='srclink' href='../src/core/cmp.rs.html#590-600' title='goto source code'>[src]</a></h4><div class='stability'><div class='stab unstable'><span class='emoji'>🔬</span> This is a nightly-only experimental API. (<code>clamp</code> <a href="https://github.com/rust-lang/rust/issues/44095">#44095</a>)</div></div><div class='docblock'><p>Restrict a value to a certain interval. <a href="../std/cmp/trait.Ord.html#method.clamp">Read more</a></p>
</div></div><h3 id='impl-Debug' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/fmt/trait.Debug.html" title="trait std::fmt::Debug">Debug</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Debug' class='anchor'></a><a class='srclink' href='../src/core/fmt/mod.rs.html#2061-2063' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.fmt-2' class="method hidden"><code id='fmt.v-2'>fn <a href='../std/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="enum" href="../std/result/enum.Result.html" title="enum std::result::Result">Result</a><<a class="primitive" href="primitive.unit.html">()</a>, <a class="struct" href="../std/fmt/struct.Error.html" title="struct std::fmt::Error">Error</a>></code><a class='srclink' href='../src/core/fmt/mod.rs.html#2062' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Formats the value using the given formatter. <a href="../std/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></div><h3 id='impl-Debug-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/fmt/trait.Debug.html" title="trait std::fmt::Debug">Debug</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Debug-1' class='anchor'></a><a class='srclink' href='../src/core/fmt/mod.rs.html#2057-2059' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.fmt-3' class="method hidden"><code id='fmt.v-3'>fn <a href='../std/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="enum" href="../std/result/enum.Result.html" title="enum std::result::Result">Result</a><<a class="primitive" href="primitive.unit.html">()</a>, <a class="struct" href="../std/fmt/struct.Error.html" title="struct std::fmt::Error">Error</a>></code><a class='srclink' href='../src/core/fmt/mod.rs.html#2058' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Formats the value using the given formatter. <a href="../std/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></div><h3 id='impl-Sync' class='impl'><code class='in-band'>impl<T> !<a class="trait" href="../std/marker/trait.Sync.html" title="trait std::marker::Sync">Sync</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Sync' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#382' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Sync-1' class='impl'><code class='in-band'>impl<T> !<a class="trait" href="../std/marker/trait.Sync.html" title="trait std::marker::Sync">Sync</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Sync-1' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#380' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Hash' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/hash/trait.Hash.html" title="trait std::hash::Hash">Hash</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Hash' class='anchor'></a><a class='srclink' href='../src/core/hash/mod.rs.html#693-707' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.hash' class="method hidden"><code id='hash.v'>fn <a href='../std/hash/trait.Hash.html#tymethod.hash' class='fnname'>hash</a><H>(&self, state: <a class="primitive" href="primitive.reference.html">&mut </a>H) <span class="where fmt-newline">where<br> H: <a class="trait" href="../std/hash/trait.Hasher.html" title="trait std::hash::Hasher">Hasher</a>, </span></code><a class='srclink' href='../src/core/hash/mod.rs.html#694-706' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Feeds this value into the given [<code>Hasher</code>]. <a href="../std/hash/trait.Hash.html#tymethod.hash">Read more</a></p>
</div><h4 id='method.hash_slice' class="method"><code id='hash_slice.v'>fn <a href='../std/hash/trait.Hash.html#method.hash_slice' class='fnname'>hash_slice</a><H>(data: <a class="primitive" href="primitive.slice.html">&[Self]</a>, state: <a class="primitive" href="primitive.reference.html">&mut </a>H) <span class="where fmt-newline">where<br> H: <a class="trait" href="../std/hash/trait.Hasher.html" title="trait std::hash::Hasher">Hasher</a>, </span></code><div class='since' title='Stable since Rust version 1.3.0'>1.3.0</div><a class='srclink' href='../src/core/hash/mod.rs.html#193-199' title='goto source code'>[src]</a></h4><div class='docblock'><p>Feeds a slice of this type into the given [<code>Hasher</code>]. <a href="../std/hash/trait.Hash.html#method.hash_slice">Read more</a></p>
</div></div><h3 id='impl-Hash-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/hash/trait.Hash.html" title="trait std::hash::Hash">Hash</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Hash-1' class='anchor'></a><a class='srclink' href='../src/core/hash/mod.rs.html#676-690' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='method.hash-1' class="method hidden"><code id='hash.v-1'>fn <a href='../std/hash/trait.Hash.html#tymethod.hash' class='fnname'>hash</a><H>(&self, state: <a class="primitive" href="primitive.reference.html">&mut </a>H) <span class="where fmt-newline">where<br> H: <a class="trait" href="../std/hash/trait.Hasher.html" title="trait std::hash::Hasher">Hasher</a>, </span></code><a class='srclink' href='../src/core/hash/mod.rs.html#677-689' title='goto source code'>[src]</a></h4><div class='docblock hidden'><p>Feeds this value into the given [<code>Hasher</code>]. <a href="../std/hash/trait.Hash.html#tymethod.hash">Read more</a></p>
</div><h4 id='method.hash_slice-1' class="method"><code id='hash_slice.v-1'>fn <a href='../std/hash/trait.Hash.html#method.hash_slice' class='fnname'>hash_slice</a><H>(data: <a class="primitive" href="primitive.slice.html">&[Self]</a>, state: <a class="primitive" href="primitive.reference.html">&mut </a>H) <span class="where fmt-newline">where<br> H: <a class="trait" href="../std/hash/trait.Hasher.html" title="trait std::hash::Hasher">Hasher</a>, </span></code><div class='since' title='Stable since Rust version 1.3.0'>1.3.0</div><a class='srclink' href='../src/core/hash/mod.rs.html#193-199' title='goto source code'>[src]</a></h4><div class='docblock'><p>Feeds a slice of this type into the given [<code>Hasher</code>]. <a href="../std/hash/trait.Hash.html#method.hash_slice">Read more</a></p>
</div></div><h3 id='impl-Copy' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/marker/trait.Copy.html" title="trait std::marker::Copy">Copy</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Copy' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#689' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-Copy-1' class='impl'><code class='in-band'>impl<T> <a class="trait" href="../std/marker/trait.Copy.html" title="trait std::marker::Copy">Copy</a> for <a class="primitive" href="primitive.pointer.html">*const T</a> <span class="where fmt-newline">where<br> T: ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>, </span></code><a href='#impl-Copy-1' class='anchor'></a><a class='srclink' href='../src/core/marker.rs.html#686' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-UnwindSafe' class='impl'><code class='in-band'>impl<T: <a class="trait" href="../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> <a class="trait" href="../std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for <a class="primitive" href="primitive.pointer.html">*const T</a></code><a href='#impl-UnwindSafe' class='anchor'></a><div class='since' title='Stable since Rust version 1.9.0'>1.9.0</div><a class='srclink' href='../src/std/panic.rs.html#206' title='goto source code'>[src]</a></h3><div class='impl-items'></div><h3 id='impl-UnwindSafe-1' class='impl'><code class='in-band'>impl<T: <a class="trait" href="../std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> + ?<a class="trait" href="../std/marker/trait.Sized.html" title="trait std::marker::Sized">Sized</a>> <a class="trait" href="../std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for <a class="primitive" href="primitive.pointer.html">*mut T</a></code><a href='#impl-UnwindSafe-1' class='anchor'></a><div class='since' title='Stable since Rust version 1.9.0'>1.9.0</div><a class='srclink' href='../src/std/panic.rs.html#208' title='goto source code'>[src]</a></h3><div class='impl-items'></div></div></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g., <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g., <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g., <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../";window.currentCrate = "std";</script><script src="../aliases.js"></script><script src="../main1.35.0.js"></script><script defer src="../search-index.js"></script></body></html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
16503
