<!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 `RawVec` struct in crate `alloc`."><meta name="keywords" content="rust, rustlang, rust-lang, RawVec"><title>alloc::raw_vec::RawVec - 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><link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico"></head><body class="rustdoc struct"><!--[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='../../alloc/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Struct RawVec</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.new_in">new_in</a><a href="#method.with_capacity_in">with_capacity_in</a><a href="#method.with_capacity_zeroed_in">with_capacity_zeroed_in</a><a href="#method.new">new</a><a href="#method.with_capacity">with_capacity</a><a href="#method.with_capacity_zeroed">with_capacity_zeroed</a><a href="#method.from_raw_parts_in">from_raw_parts_in</a><a href="#method.from_raw_parts">from_raw_parts</a><a href="#method.from_box">from_box</a><a href="#method.ptr">ptr</a><a href="#method.cap">cap</a><a href="#method.alloc">alloc</a><a href="#method.alloc_mut">alloc_mut</a><a href="#method.double">double</a><a href="#method.double_in_place">double_in_place</a><a href="#method.try_reserve_exact">try_reserve_exact</a><a href="#method.reserve_exact">reserve_exact</a><a href="#method.try_reserve">try_reserve</a><a href="#method.reserve">reserve</a><a href="#method.reserve_in_place">reserve_in_place</a><a href="#method.shrink_to_fit">shrink_to_fit</a><a href="#method.into_box">into_box</a><a href="#method.dealloc_buffer">dealloc_buffer</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Drop">Drop</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-Send">Send</a><a href="#impl-Sync">Sync</a></div></div><p class='location'><a href='../index.html'>alloc</a>::<wbr><a href='index.html'>raw_vec</a></p><script>window.sidebarCurrent = {name: 'RawVec', ty: 'struct', 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 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"><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='in-band'>Struct <a href='../index.html'>alloc</a>::<wbr><a href='index.html'>raw_vec</a>::<wbr><a class="struct" href=''>RawVec</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/alloc/raw_vec.rs.html#50-54' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust struct'>pub struct RawVec<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a> = <a class="struct" href="../../alloc/alloc/struct.Global.html" title="struct alloc::alloc::Global">Global</a>> { /* fields omitted */ }</pre></div><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>A low-level utility for more ergonomically allocating, reallocating, and deallocating
a buffer of memory on the heap without having to worry about all the corner cases
involved. This type is excellent for building your own data structures like Vec and VecDeque.
In particular:</p>
<ul>
<li>Produces Unique::empty() on zero-sized types</li>
<li>Produces Unique::empty() on zero-length allocations</li>
<li>Catches all overflows in capacity computations (promotes them to "capacity overflow" panics)</li>
<li>Guards against 32-bit systems allocating more than isize::MAX bytes</li>
<li>Guards against overflowing your length</li>
<li>Aborts on OOM</li>
<li>Avoids freeing Unique::empty()</li>
<li>Contains a ptr::Unique and thus endows the user with all related benefits</li>
</ul>
<p>This type does not in anyway inspect the memory that it manages. When dropped it <em>will</em>
free its memory, but it <em>won't</em> try to Drop its contents. It is up to the user of RawVec
to handle the actual things <em>stored</em> inside of a RawVec.</p>
<p>Note that a RawVec always forces its capacity to be usize::MAX for zero-sized types.
This enables you to use capacity growing logic catch the overflows in your length
that might occur with zero-sized types.</p>
<p>However this means that you need to be careful when roundtripping this type
with a <code>Box<[T]></code>: <code>cap()</code> won't yield the len. However <code>with_capacity</code>,
<code>shrink_to_fit</code>, and <code>from_box</code> will actually set RawVec's private capacity
field. This allows zero-sized types to not be special-cased by consumers of
this type.</p>
</div>
<h2 id='methods' class='small-section-header'>
Methods<a href='#methods' class='anchor'></a>
</h2>
<h3 id='impl' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a>> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A></code><a href='#impl' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#56-118' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.new_in' class="method"><span id='new_in.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub const fn <a href='#method.new_in' class='fnname'>new_in</a>(a: A) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#59-71' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Like <code>new</code> but parameterized over the choice of allocator for
the returned RawVec.</p>
</div><h4 id='method.with_capacity_in' class="method"><span id='with_capacity_in.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.with_capacity_in' class='fnname'>with_capacity_in</a>(cap: usize, a: A) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#76-78' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Like <code>with_capacity</code> but parameterized over the choice of
allocator for the returned RawVec.</p>
</div><h4 id='method.with_capacity_zeroed_in' class="method"><span id='with_capacity_zeroed_in.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.with_capacity_zeroed_in' class='fnname'>with_capacity_zeroed_in</a>(cap: usize, a: A) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#83-85' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Like <code>with_capacity_zeroed</code> but parameterized over the choice
of allocator for the returned RawVec.</p>
</div></div><h3 id='impl-1' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, <a class="struct" href="../../alloc/alloc/struct.Global.html" title="struct alloc::alloc::Global">Global</a>></code><a href='#impl-1' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#120-155' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.new' class="method"><span id='new.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub const fn <a href='#method.new' class='fnname'>new</a>() -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#126-128' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Creates the biggest possible RawVec (on the system heap)
without allocating. If T has positive size, then this makes a
RawVec with capacity 0. If T has 0 size, then it makes a
RawVec with capacity <code>usize::MAX</code>. Useful for implementing
delayed allocation.</p>
</div><h4 id='method.with_capacity' class="method"><span id='with_capacity.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.with_capacity' class='fnname'>with_capacity</a>(cap: usize) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#146-148' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Creates a RawVec (on the system heap) with exactly the
capacity and alignment requirements for a <code>[T; cap]</code>. This is
equivalent to calling RawVec::new when <code>cap</code> is 0 or T is
zero-sized. Note that if <code>T</code> is zero-sized this means you will
<em>not</em> get a RawVec with the requested capacity!</p>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<ul>
<li>Panics if the requested capacity exceeds <code>usize::MAX</code> bytes.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
<h1 id="aborts" class="section-header"><a href="#aborts">Aborts</a></h1>
<p>Aborts on OOM</p>
</div><h4 id='method.with_capacity_zeroed' class="method"><span id='with_capacity_zeroed.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.with_capacity_zeroed' class='fnname'>with_capacity_zeroed</a>(cap: usize) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#152-154' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Like <code>with_capacity</code> but guarantees the buffer is zeroed.</p>
</div></div><h3 id='impl-2' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a>> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A></code><a href='#impl-2' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#157-172' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.from_raw_parts_in' class="method"><span id='from_raw_parts_in.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub unsafe fn <a href='#method.from_raw_parts_in' class='fnname'>from_raw_parts_in</a>(ptr: *mut T, cap: usize, a: A) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#165-171' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Reconstitutes a RawVec from a pointer, capacity, and allocator.</p>
<h1 id="undefined-behavior" class="section-header"><a href="#undefined-behavior">Undefined Behavior</a></h1>
<p>The ptr must be allocated (via the given allocator <code>a</code>), and with the given capacity. The
capacity cannot exceed <code>isize::MAX</code> (only a concern on 32-bit systems).
If the ptr and capacity come from a RawVec created via <code>a</code>, then this is guaranteed.</p>
</div></div><h3 id='impl-3' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, <a class="struct" href="../../alloc/alloc/struct.Global.html" title="struct alloc::alloc::Global">Global</a>></code><a href='#impl-3' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#174-198' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.from_raw_parts' class="method"><span id='from_raw_parts.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub unsafe fn <a href='#method.from_raw_parts' class='fnname'>from_raw_parts</a>(ptr: *mut T, cap: usize) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#182-188' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Reconstitutes a RawVec from a pointer, capacity.</p>
<h1 id="undefined-behavior-1" class="section-header"><a href="#undefined-behavior-1">Undefined Behavior</a></h1>
<p>The ptr must be allocated (on the system heap), and with the given capacity. The
capacity cannot exceed <code>isize::MAX</code> (only a concern on 32-bit systems).
If the ptr and capacity come from a RawVec, then this is guaranteed.</p>
</div><h4 id='method.from_box' class="method"><span id='from_box.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.from_box' class='fnname'>from_box</a>(slice: <a class="struct" href="../../alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><[T]>) -> Self</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#191-197' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Converts a <code>Box<[T]></code> into a <code>RawVec<T></code>.</p>
</div></div><h3 id='impl-4' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a>> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A></code><a href='#impl-4' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#200-624' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.ptr' class="method"><span id='ptr.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.ptr' class='fnname'>ptr</a>(&self) -> *mut T</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#204-206' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Gets a raw pointer to the start of the allocation. Note that this is
Unique::empty() if <code>cap = 0</code> or T is zero-sized. In the former case, you must
be careful.</p>
</div><h4 id='method.cap' class="method"><span id='cap.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.cap' class='fnname'>cap</a>(&self) -> usize</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#212-218' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Gets the capacity of the allocation.</p>
<p>This will always be <code>usize::MAX</code> if <code>T</code> is zero-sized.</p>
</div><h4 id='method.alloc' class="method"><span id='alloc.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.alloc' class='fnname'>alloc</a>(&self) -> &A</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#221-223' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Returns a shared reference to the allocator backing this RawVec.</p>
</div><h4 id='method.alloc_mut' class="method"><span id='alloc_mut.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.alloc_mut' class='fnname'>alloc_mut</a>(&mut self) -> &mut A</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#226-228' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Returns a mutable reference to the allocator backing this RawVec.</p>
</div><h4 id='method.double' class="method"><span id='double.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.double' class='fnname'>double</a>(&mut self)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#294-340' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Doubles the size of the type's backing allocation. This is common enough
to want to do that it's easiest to just have a dedicated method. Slightly
more efficient logic can be provided for this than the general case.</p>
<p>This function is ideal for when pushing elements one-at-a-time because
you don't need to incur the costs of the more general computations
reserve needs to do to guard against overflow. You do however need to
manually check if your <code>len == cap</code>.</p>
<h1 id="panics-1" class="section-header"><a href="#panics-1">Panics</a></h1>
<ul>
<li>Panics if T is zero-sized on the assumption that you managed to exhaust
all <code>usize::MAX</code> slots in your imaginary buffer.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
<h1 id="aborts-1" class="section-header"><a href="#aborts-1">Aborts</a></h1>
<p>Aborts on OOM</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">struct</span> <span class="ident">MyVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
<span class="ident">buf</span>: <span class="ident">RawVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span>,
<span class="ident">len</span>: <span class="ident">usize</span>,
}
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> <span class="ident">MyVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">push</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>, <span class="ident">elem</span>: <span class="ident">T</span>) {
<span class="kw">if</span> <span class="self">self</span>.<span class="ident">len</span> <span class="op">==</span> <span class="self">self</span>.<span class="ident">buf</span>.<span class="ident">cap</span>() { <span class="self">self</span>.<span class="ident">buf</span>.<span class="ident">double</span>(); }
<span class="comment">// double would have aborted or panicked if the len exceeded</span>
<span class="comment">// `isize::MAX` so this is safe to do unchecked now.</span>
<span class="kw">unsafe</span> {
<span class="ident">ptr</span>::<span class="ident">write</span>(<span class="self">self</span>.<span class="ident">buf</span>.<span class="ident">ptr</span>().<span class="ident">offset</span>(<span class="self">self</span>.<span class="ident">len</span> <span class="kw">as</span> <span class="ident">isize</span>), <span class="ident">elem</span>);
}
<span class="self">self</span>.<span class="ident">len</span> <span class="op">+=</span> <span class="number">1</span>;
}
}</pre>
</div><h4 id='method.double_in_place' class="method"><span id='double_in_place.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.double_in_place' class='fnname'>double_in_place</a>(&mut self) -> bool</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#356-389' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Attempts to double the size of the type's backing allocation in place. This is common
enough to want to do that it's easiest to just have a dedicated method. Slightly
more efficient logic can be provided for this than the general case.</p>
<p>Returns true if the reallocation attempt has succeeded, or false otherwise.</p>
<h1 id="panics-2" class="section-header"><a href="#panics-2">Panics</a></h1>
<ul>
<li>Panics if T is zero-sized on the assumption that you managed to exhaust
all <code>usize::MAX</code> slots in your imaginary buffer.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
</div><h4 id='method.try_reserve_exact' class="method"><span id='try_reserve_exact.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.try_reserve_exact' class='fnname'>try_reserve_exact</a>(<br> &mut self, <br> used_cap: usize, <br> needed_extra_cap: usize<br>) -> <a class="enum" href="../../core/result/enum.Result.html" title="enum core::result::Result">Result</a><(), <a class="enum" href="../../alloc/alloc/enum.CollectionAllocErr.html" title="enum alloc::alloc::CollectionAllocErr">CollectionAllocErr</a>></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#392-396' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>The same as <code>reserve_exact</code>, but returns on errors instead of panicking or aborting.</p>
</div><h4 id='method.reserve_exact' class="method"><span id='reserve_exact.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.reserve_exact' class='fnname'>reserve_exact</a>(&mut self, used_cap: usize, needed_extra_cap: usize)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#418-424' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Ensures that the buffer contains at least enough space to hold
<code>used_cap + needed_extra_cap</code> elements. If it doesn't already,
will reallocate the minimum possible amount of memory necessary.
Generally this will be exactly the amount of memory necessary,
but in principle the allocator is free to give back more than
we asked for.</p>
<p>If <code>used_cap</code> exceeds <code>self.cap()</code>, this may fail to actually allocate
the requested space. This is not really unsafe, but the unsafe
code <em>you</em> write that relies on the behavior of this function may break.</p>
<h1 id="panics-3" class="section-header"><a href="#panics-3">Panics</a></h1>
<ul>
<li>Panics if the requested capacity exceeds <code>usize::MAX</code> bytes.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
<h1 id="aborts-2" class="section-header"><a href="#aborts-2">Aborts</a></h1>
<p>Aborts on OOM</p>
</div><h4 id='method.try_reserve' class="method"><span id='try_reserve.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.try_reserve' class='fnname'>try_reserve</a>(<br> &mut self, <br> used_cap: usize, <br> needed_extra_cap: usize<br>) -> <a class="enum" href="../../core/result/enum.Result.html" title="enum core::result::Result">Result</a><(), <a class="enum" href="../../alloc/alloc/enum.CollectionAllocErr.html" title="enum alloc::alloc::CollectionAllocErr">CollectionAllocErr</a>></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#441-444' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>The same as <code>reserve</code>, but returns on errors instead of panicking or aborting.</p>
</div><h4 id='method.reserve' class="method"><span id='reserve.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.reserve' class='fnname'>reserve</a>(&mut self, used_cap: usize, needed_extra_cap: usize)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#498-504' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Ensures that the buffer contains at least enough space to hold
<code>used_cap + needed_extra_cap</code> elements. If it doesn't already have
enough capacity, will reallocate enough space plus comfortable slack
space to get amortized <code>O(1)</code> behavior. Will limit this behavior
if it would needlessly cause itself to panic.</p>
<p>If <code>used_cap</code> exceeds <code>self.cap()</code>, this may fail to actually allocate
the requested space. This is not really unsafe, but the unsafe
code <em>you</em> write that relies on the behavior of this function may break.</p>
<p>This is ideal for implementing a bulk-push operation like <code>extend</code>.</p>
<h1 id="panics-4" class="section-header"><a href="#panics-4">Panics</a></h1>
<ul>
<li>Panics if the requested capacity exceeds <code>usize::MAX</code> bytes.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
<h1 id="aborts-3" class="section-header"><a href="#aborts-3">Aborts</a></h1>
<p>Aborts on OOM</p>
<h1 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">struct</span> <span class="ident">MyVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
<span class="ident">buf</span>: <span class="ident">RawVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span>,
<span class="ident">len</span>: <span class="ident">usize</span>,
}
<span class="kw">impl</span><span class="op"><</span><span class="ident">T</span>: <span class="ident">Clone</span><span class="op">></span> <span class="ident">MyVec</span><span class="op"><</span><span class="ident">T</span><span class="op">></span> {
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">push_all</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>, <span class="ident">elems</span>: <span class="kw-2">&</span>[<span class="ident">T</span>]) {
<span class="self">self</span>.<span class="ident">buf</span>.<span class="ident">reserve</span>(<span class="self">self</span>.<span class="ident">len</span>, <span class="ident">elems</span>.<span class="ident">len</span>());
<span class="comment">// reserve would have aborted or panicked if the len exceeded</span>
<span class="comment">// `isize::MAX` so this is safe to do unchecked now.</span>
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="ident">elems</span> {
<span class="kw">unsafe</span> {
<span class="ident">ptr</span>::<span class="ident">write</span>(<span class="self">self</span>.<span class="ident">buf</span>.<span class="ident">ptr</span>().<span class="ident">offset</span>(<span class="self">self</span>.<span class="ident">len</span> <span class="kw">as</span> <span class="ident">isize</span>), <span class="ident">x</span>.<span class="ident">clone</span>());
}
<span class="self">self</span>.<span class="ident">len</span> <span class="op">+=</span> <span class="number">1</span>;
}
}
}</pre>
</div><h4 id='method.reserve_in_place' class="method"><span id='reserve_in_place.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.reserve_in_place' class='fnname'>reserve_in_place</a>(<br> &mut self, <br> used_cap: usize, <br> needed_extra_cap: usize<br>) -> bool</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#522-562' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Attempts to ensure that the buffer contains at least enough space to hold
<code>used_cap + needed_extra_cap</code> elements. If it doesn't already have
enough capacity, will reallocate in place enough space plus comfortable slack
space to get amortized <code>O(1)</code> behavior. Will limit this behaviour
if it would needlessly cause itself to panic.</p>
<p>If <code>used_cap</code> exceeds <code>self.cap()</code>, this may fail to actually allocate
the requested space. This is not really unsafe, but the unsafe
code <em>you</em> write that relies on the behavior of this function may break.</p>
<p>Returns true if the reallocation attempt has succeeded, or false otherwise.</p>
<h1 id="panics-5" class="section-header"><a href="#panics-5">Panics</a></h1>
<ul>
<li>Panics if the requested capacity exceeds <code>usize::MAX</code> bytes.</li>
<li>Panics on 32-bit platforms if the requested capacity exceeds
<code>isize::MAX</code> bytes.</li>
</ul>
</div><h4 id='method.shrink_to_fit' class="method"><span id='shrink_to_fit.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.shrink_to_fit' class='fnname'>shrink_to_fit</a>(&mut self, amount: usize)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#574-623' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Shrinks the allocation down to the specified amount. If the given amount
is 0, actually completely deallocates.</p>
<h1 id="panics-6" class="section-header"><a href="#panics-6">Panics</a></h1>
<p>Panics if the given amount is <em>larger</em> than the current capacity.</p>
<h1 id="aborts-4" class="section-header"><a href="#aborts-4">Aborts</a></h1>
<p>Aborts on OOM.</p>
</div></div><h3 id='impl-5' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, <a class="struct" href="../../alloc/alloc/struct.Global.html" title="struct alloc::alloc::Global">Global</a>></code><a href='#impl-5' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#693-709' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.into_box' class="method"><div class="important-traits"><div class='tooltip'>ⓘ<span class='tooltiptext'>Important traits for <a class="struct" href="../../alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><I></span></div><div class="content hidden"><h3 class="important">Important traits for <a class="struct" href="../../alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><I></h3><code class="content"><span class="where fmt-newline">impl<I: <a class="trait" href="../../core/iter/iterator/trait.Iterator.html" title="trait core::iter::iterator::Iterator">Iterator</a> + ?<a class="trait" href="../../core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>> <a class="trait" href="../../core/iter/iterator/trait.Iterator.html" title="trait core::iter::iterator::Iterator">Iterator</a> for <a class="struct" href="../../alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><I></span><span class="where fmt-newline"> type <a href='../../core/iter/iterator/trait.Iterator.html#associatedtype.Item' class="type">Item</a> = I::<a class="type" href="../../core/iter/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::iterator::Iterator::Item">Item</a>;</span></code></div></div><span id='into_box.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub unsafe fn <a href='#method.into_box' class='fnname'>into_box</a>(self) -> <a class="struct" href="../../alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><[T]></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#702-708' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Converts the entire buffer into <code>Box<[T]></code>.</p>
<p>While it is not <em>strictly</em> Undefined Behavior to call
this procedure while some of the RawVec is uninitialized,
it certainly makes it trivial to trigger it.</p>
<p>Note that this will correctly reconstitute any <code>cap</code> changes
that may have been performed. (see description of type for details)</p>
</div></div><h3 id='impl-6' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a>> <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A></code><a href='#impl-6' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#711-721' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.dealloc_buffer' class="method"><span id='dealloc_buffer.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub unsafe fn <a href='#method.dealloc_buffer' class='fnname'>dealloc_buffer</a>(&mut self)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#713-720' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><details><summary><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>alloc </code><a href="https://github.com/rust-lang/rust/issues/27783">#27783</a>)</summary><p>this library is unlikely to be stabilized in its current form or name</p>
</details></div></div><div class='docblock'><p>Frees the memory owned by the RawVec <em>without</em> trying to Drop its contents.</p>
</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-Drop' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A: <a class="trait" href="../../alloc/alloc/trait.Alloc.html" title="trait alloc::alloc::Alloc">Alloc</a>> <a class="trait" href="../../core/ops/drop/trait.Drop.html" title="trait core::ops::drop::Drop">Drop</a> for <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A></code><a href='#impl-Drop' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#723-728' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.drop' class="method"><span id='drop.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='../../core/ops/drop/trait.Drop.html#tymethod.drop' class='fnname'>drop</a>(&mut self)</code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/alloc/raw_vec.rs.html#725-727' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Frees the memory owned by the RawVec <em>without</em> trying to Drop its contents.</p>
</div></div></div>
<h2 id='synthetic-implementations' class='small-section-header'>
Auto Trait Implementations<a href='#synthetic-implementations' class='anchor'></a>
</h2>
<div id='synthetic-implementations-list'>
<h3 id='impl-Send' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A> <a class="trait" href="../../core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A> <span class="where fmt-newline">where<br> A: <a class="trait" href="../../core/marker/trait.Send.html" title="trait core::marker::Send">Send</a>,<br> T: <a class="trait" href="../../core/marker/trait.Send.html" title="trait core::marker::Send">Send</a>, </span></code><a href='#impl-Send' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Sync' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl<T, A> <a class="trait" href="../../core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="../../alloc/raw_vec/struct.RawVec.html" title="struct alloc::raw_vec::RawVec">RawVec</a><T, A> <span class="where fmt-newline">where<br> A: <a class="trait" href="../../core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a>,<br> T: <a class="trait" href="../../core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a>, </span></code><a href='#impl-Sync' class='anchor'></a></span></td><td><span class='out-of-band'></span></td></tr></tbody></table></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 = "alloc";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
253
