<!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 `needs_drop` fn in crate `core`.">
<meta name="keywords" content="rust, rustlang, rust-lang, needs_drop">
<title>core::mem::needs_drop - Rust</title>
<link rel="stylesheet" type="text/css" href="../../normalize.css">
<link rel="stylesheet" type="text/css" href="../../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../../main.css">
<link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico">
</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">
<a href='../../core/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a>
<p class='location'><a href='../index.html'>core</a>::<wbr><a href='index.html'>mem</a></p><script>window.sidebarCurrent = {name: 'needs_drop', ty: 'fn', relpath: ''};</script><script defer src="sidebar-items.js"></script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Function <a href='../index.html'>core</a>::<wbr><a href='index.html'>mem</a>::<wbr><a class="fn" href=''>needs_drop</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version '></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='../../src/core/mem.rs.html#353-355' title='goto source code'>[src]</a></span></h1>
<pre class='rust fn'>pub fn needs_drop<T>() -> bool</pre><div class='stability'><div class='stab unstable'><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>needs_drop </code><a href="https://github.com/rust-lang/rust/issues/41890">#41890</a>)</div></div><div class='docblock'><p>Returns whether dropping values of type <code>T</code> matters.</p>
<p>This is purely an optimization hint, and may be implemented conservatively.
For instance, always returning <code>true</code> would be a valid implementation of
this function.</p>
<p>Low level implementations of things like collections, which need to manually
drop their data, should use this function to avoid unnecessarily
trying to drop all their contents when they are destroyed. This might not
make a difference in release builds (where a loop that has no side-effects
is easily detected and eliminated), but is often a big win for debug builds.</p>
<p>Note that <code>ptr::drop_in_place</code> already performs this check, so if your workload
can be reduced to some small number of drop_in_place calls, using this is
unnecessary. In particular note that you can drop_in_place a slice, and that
will do a single needs_drop check for all the values.</p>
<p>Types like Vec therefore just <code>drop_in_place(&mut self[..])</code> without using
needs_drop explicitly. Types like HashMap, on the other hand, have to drop
values one at a time and should use this API.</p>
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
<p>Here's an example of how a collection might make use of needs_drop:</p>
<pre class="rust rust-example-rendered">
<span class="attribute">#<span class="op">!</span>[<span class="ident">feature</span>(<span class="ident">needs_drop</span>)]</span>
<span class="kw">use</span> <span class="ident">std</span>::{<span class="ident">mem</span>, <span class="ident">ptr</span>};
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">MyCollection</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> { <span class="comment">/* ... */</span> }
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> <span class="ident">Drop</span> <span class="kw">for</span> <span class="ident">MyCollection</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
<span class="kw">fn</span> <span class="ident">drop</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>) {
<span class="kw">unsafe</span> {
<span class="comment">// drop the data</span>
<span class="kw">if</span> <span class="ident">mem</span>::<span class="ident">needs_drop</span>::<span class="op"><</span><span class="ident">T</span><span class="op">></span>() {
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="self">self</span>.<span class="ident">iter_mut</span>() {
<span class="ident">ptr</span>::<span class="ident">drop_in_place</span>(<span class="ident">x</span>);
}
}
<span class="self">self</span>.<span class="ident">free_buffer</span>();
}
}
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Bfeature(needs_drop)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3A%7Bmem%2C%20ptr%7D%3B%0A%0Apub%20struct%20MyCollection%3CT%3E%20%7B%20%2F*%20...%20*%2F%20%7D%0A%0Aimpl%3CT%3E%20Drop%20for%20MyCollection%3CT%3E%20%7B%0A%20%20%20%20fn%20drop(%26mut%20self)%20%7B%0A%20%20%20%20%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%2F%2F%20drop%20the%20data%0A%20%20%20%20%20%20%20%20%20%20%20%20if%20mem%3A%3Aneeds_drop%3A%3A%3CT%3E()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20for%20x%20in%20self.iter_mut()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20ptr%3A%3Adrop_in_place(x)%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20self.free_buffer()%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%7D%0A%7D&version=nightly">Run</a></pre>
</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>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>⇤</dt>
<dd>Move up in search results</dd>
<dt>⇥</dt>
<dd>Move down in search results</dd>
<dt>⏎</dt>
<dd>Go to active search result</dd>
<dt>+</dt>
<dd>Collapse/expand 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>
</div>
</div>
</aside>
<script>
window.rootPath = "../../";
window.currentCrate = "core";
</script>
<script src="../../main.js"></script>
<script defer src="../../search-index.js"></script>
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
878cdd00a13d17a73c6619a777ef5d74
>
files
>
1658
