62 lines
8.6 KiB
HTML
62 lines
8.6 KiB
HTML
<!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 `forget` fn in crate `nom`."><meta name="keywords" content="rust, rustlang, rust-lang, forget"><title>nom::lib::std::mem::forget - Rust</title><link rel="stylesheet" type="text/css" href="../../../../normalize.css"><link rel="stylesheet" type="text/css" href="../../../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../../../dark.css"><link rel="stylesheet" type="text/css" href="../../../../light.css" id="themeStyle"><script src="../../../../storage.js"></script><noscript><link rel="stylesheet" href="../../../../noscript.css"></noscript><link rel="shortcut icon" href="../../../../favicon.ico"><style type="text/css">#crate-search{background-image:url("../../../../down-arrow.svg");}</style></head><body class="rustdoc fn"><!--[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='../../../../nom/index.html'><div class='logo-container'><img src='../../../../rust-logo.png' alt='logo'></div></a><div class="sidebar-elems"><p class='location'><a href='../../../index.html'>nom</a>::<wbr><a href='../../index.html'>lib</a>::<wbr><a href='../index.html'>std</a>::<wbr><a href='index.html'>mem</a></p><script>window.sidebarCurrent = {name: 'forget', ty: 'fn', 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="../../../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../../../theme.js"></script><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled 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="../../../../wheel.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><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/mem/mod.rs.html#114-116' title='goto source code'>[src]</a></span><span class='in-band'>Function <a href='../../../index.html'>nom</a>::<wbr><a href='../../index.html'>lib</a>::<wbr><a href='../index.html'>std</a>::<wbr><a href='index.html'>mem</a>::<wbr><a class="fn" href=''>forget</a></span></h1><pre class='rust fn'>pub const fn forget<T>(t: T)</pre><div class='docblock'><p>Takes ownership and "forgets" about the value <strong>without running its destructor</strong>.</p>
|
||
<p>Any resources the value manages, such as heap memory or a file handle, will linger
|
||
forever in an unreachable state. However, it does not guarantee that pointers
|
||
to this memory will remain valid.</p>
|
||
<ul>
|
||
<li>If you want to leak memory, see <a href="../../std/boxed/struct.Box.html#method.leak"><code>Box::leak</code></a>.</li>
|
||
<li>If you want to obtain a raw pointer to the memory, see <a href="../../std/boxed/struct.Box.html#method.into_raw"><code>Box::into_raw</code></a>.</li>
|
||
<li>If you want to dispose of a value properly, running its destructor, see
|
||
<a href="fn.drop.html"><code>mem::drop</code></a>.</li>
|
||
</ul>
|
||
<h1 id="safety" class="section-header"><a href="#safety">Safety</a></h1>
|
||
<p><code>forget</code> is not marked as <code>unsafe</code>, because Rust's safety guarantees
|
||
do not include a guarantee that destructors will always run. For example,
|
||
a program can create a reference cycle using <a href="../../std/rc/struct.Rc.html"><code>Rc</code></a>, or call
|
||
<a href="../../std/process/fn.exit.html"><code>process::exit</code></a> to exit without running destructors. Thus, allowing
|
||
<code>mem::forget</code> from safe code does not fundamentally change Rust's safety
|
||
guarantees.</p>
|
||
<p>That said, leaking resources such as memory or I/O objects is usually undesirable.
|
||
The need comes up in some specialized use cases for FFI or unsafe code, but even
|
||
then, <a href="struct.ManuallyDrop.html"><code>ManuallyDrop</code></a> is typically preferred.</p>
|
||
<p>Because forgetting a value is allowed, any <code>unsafe</code> code you write must
|
||
allow for this possibility. You cannot return a value and expect that the
|
||
caller will necessarily run the value's destructor.</p>
|
||
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
|
||
<p>Leak an I/O object, never closing the file:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">mem</span>;
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">fs</span>::<span class="ident">File</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">file</span> <span class="op">=</span> <span class="ident">File</span>::<span class="ident">open</span>(<span class="string">"foo.txt"</span>).<span class="ident">unwrap</span>();
|
||
<span class="ident">mem</span>::<span class="ident">forget</span>(<span class="ident">file</span>);</pre></div>
|
||
<p>The practical use cases for <code>forget</code> are rather specialized and mainly come
|
||
up in unsafe or FFI code. However, <a href="struct.ManuallyDrop.html"><code>ManuallyDrop</code></a> is usually preferred
|
||
for such cases, e.g.:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">mem</span>::<span class="ident">ManuallyDrop</span>;
|
||
|
||
<span class="kw">let</span> <span class="ident">v</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">65</span>, <span class="number">122</span>];
|
||
<span class="comment">// Before we disassemble `v` into its raw parts, make sure it</span>
|
||
<span class="comment">// does not get dropped!</span>
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">v</span> <span class="op">=</span> <span class="ident">ManuallyDrop</span>::<span class="ident">new</span>(<span class="ident">v</span>);
|
||
<span class="comment">// Now disassemble `v`. These operations cannot panic, so there cannot be a leak.</span>
|
||
<span class="kw">let</span> <span class="ident">ptr</span> <span class="op">=</span> <span class="ident">v</span>.<span class="ident">as_mut_ptr</span>();
|
||
<span class="kw">let</span> <span class="ident">cap</span> <span class="op">=</span> <span class="ident">v</span>.<span class="ident">capacity</span>();
|
||
<span class="comment">// Finally, build a `String`.</span>
|
||
<span class="kw">let</span> <span class="ident">s</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="ident">String</span>::<span class="ident">from_raw_parts</span>(<span class="ident">ptr</span>, <span class="number">2</span>, <span class="ident">cap</span>) };
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">s</span>, <span class="string">"Az"</span>);
|
||
<span class="comment">// `s` is implicitly dropped and its memory deallocated.</span></pre></div>
|
||
<p>Using <code>ManuallyDrop</code> here has two advantages:</p>
|
||
<ul>
|
||
<li>We do not "touch" <code>v</code> after disassembling it. For some types, operations
|
||
such as passing ownership (to a function like <code>mem::forget</code>) requires them to actually
|
||
be fully owned right now; that is a promise we do not want to make here as we are
|
||
in the process of transferring ownership to the new <code>String</code> we are building.</li>
|
||
<li>In case of an unexpected panic, <code>ManuallyDrop</code> is not dropped, but if the panic
|
||
occurs before <code>mem::forget</code> was called we might end up dropping invalid data,
|
||
or double-dropping. In other words, <code>ManuallyDrop</code> errs on the side of leaking
|
||
instead of erring on the side of dropping.</li>
|
||
</ul>
|
||
</div></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../../../../";window.currentCrate = "nom";</script><script src="../../../../aliases.js"></script><script src="../../../../main.js"></script><script defer src="../../../../search-index.js"></script></body></html> |