mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-12-02 00:14:33 +01:00
Code Issues Projects Releases Packages Wiki Activity
rtic/dev/api/heapless/index.html
github-merge-queue[bot] 5b32b958a3 deploy: f17915842f
2024-11-27 19:34:22 +00:00

64 lines
No EOL
15 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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="`static` friendly data structures that don’t require dynamic memory allocation"><title>heapless - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-492a78a4a87dcc01.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="heapless" data-themes="" data-resource-suffix="" data-rustdoc-version="1.82.0 (f6e511eec 2024-10-15)" data-channel="1.82.0" data-search-js="search-a99f1315e7cc5121.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-118b08c4c78b968e.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-921df33f47b8780c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-3b12f09e550e0385.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../heapless/index.html">heapless</a><span class="version">0.8.0</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#reexports">Re-exports</a></li><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#types">Type Aliases</a></li></ul></section></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">heapless</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="../src/heapless/lib.rs.html#1-145">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p><code>static</code> friendly data structures that don’t require dynamic memory allocation</p>
<p>The core principle behind <code>heapless</code> is that its data structures are backed by a <em>static</em> memory
allocation. For example, you can think of <code>heapless::Vec</code> as an alternative version of
<code>std::Vec</code> with fixed capacity and that can’t be re-allocated on the fly (e.g. via <code>push</code>).</p>
<p>All <code>heapless</code> data structures store their memory allocation <em>inline</em> and specify their capacity
via their type parameter <code>N</code>. This means that you can instantiate a <code>heapless</code> data structure on
the stack, in a <code>static</code> variable, or even in the heap.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>heapless::Vec; <span class="comment">// fixed capacity `std::Vec`
// on the stack
</span><span class="kw">let </span><span class="kw-2">mut </span>xs: Vec&lt;u8, <span class="number">8</span>&gt; = Vec::new(); <span class="comment">// can hold up to 8 elements
</span>xs.push(<span class="number">42</span>).unwrap();
<span class="macro">assert_eq!</span>(xs.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));
<span class="comment">// in a `static` variable
</span><span class="kw">static </span><span class="kw-2">mut </span>XS: Vec&lt;u8, <span class="number">8</span>&gt; = Vec::new();
<span class="kw">let </span>xs = <span class="kw">unsafe </span>{ <span class="kw-2">&amp;mut </span>XS };
xs.push(<span class="number">42</span>);
<span class="macro">assert_eq!</span>(xs.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));
<span class="comment">// in the heap (though kind of pointless because no reallocation)
</span><span class="kw">let </span><span class="kw-2">mut </span>ys: Box&lt;Vec&lt;u8, <span class="number">8</span>&gt;&gt; = Box::new(Vec::new());
ys.push(<span class="number">42</span>).unwrap();
<span class="macro">assert_eq!</span>(ys.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));</code></pre></div>
<p>Because they have fixed capacity <code>heapless</code> data structures don’t implicitly reallocate. This
means that operations like <code>heapless::Vec.push</code> are <em>truly</em> constant time rather than amortized
constant time with potentially unbounded (depends on the allocator) worst case execution time
(which is bad / unacceptable for hard real time applications).</p>
<p><code>heapless</code> data structures don’t use a memory allocator which means no risk of an uncatchable
Out Of Memory (OOM) condition while performing operations on them. It’s certainly possible to
run out of capacity while growing <code>heapless</code> data structures, but the API lets you handle this
possibility by returning a <code>Result</code> on operations that may exhaust the capacity of the data
structure.</p>
<p>List of currently implemented data structures:</p>
<ul>
<li><a href="binary_heap/struct.BinaryHeap.html" title="struct heapless::binary_heap::BinaryHeap"><code>BinaryHeap</code></a> – priority queue</li>
<li><a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a> – hash table</li>
<li><a href="struct.IndexSet.html" title="struct heapless::IndexSet"><code>IndexSet</code></a> – hash set</li>
<li><a href="struct.LinearMap.html" title="struct heapless::LinearMap"><code>LinearMap</code></a></li>
<li><a href="struct.String.html" title="struct heapless::String"><code>String</code></a></li>
<li><a href="struct.Vec.html" title="struct heapless::Vec"><code>Vec</code></a></li>
<li><a href="mpmc/index.html" title="mod heapless::mpmc"><code>mpmc::Q*</code></a> – multiple producer multiple consumer lock-free queue</li>
<li><a href="spsc/struct.Queue.html" title="struct heapless::spsc::Queue"><code>spsc::Queue</code></a> – single producer single consumer lock-free queue</li>
</ul>
<h2 id="optional-features"><a class="doc-anchor" href="#optional-features">§</a>Optional Features</h2>
<p>The <code>heapless</code> crate provides the following optional Cargo features:</p>
<ul>
<li><code>ufmt</code>: Implement <a href="https://docs.rs/ufmt-write/"><code>ufmt_write::uWrite</code></a> for <code>String&lt;N&gt;</code> and <code>Vec&lt;u8, N&gt;</code></li>
</ul>
<h2 id="minimum-supported-rust-version-msrv"><a class="doc-anchor" href="#minimum-supported-rust-version-msrv">§</a>Minimum Supported Rust Version (MSRV)</h2>
<p>This crate does <em>not</em> have a Minimum Supported Rust Version (MSRV) and may make use of language
features and API in the standard library available in the latest stable Rust version.</p>
<p>In other words, changes in the Rust version requirement of this crate are not considered semver
breaking change and may occur in patch version releases.</p>
</div></details><h2 id="reexports" class="section-header">Re-exports<a href="#reexports" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name" id="reexport.BinaryHeap"><code>pub use binary_heap::<a class="struct" href="binary_heap/struct.BinaryHeap.html" title="struct heapless::binary_heap::BinaryHeap">BinaryHeap</a>;</code></div></li><li><div class="item-name" id="reexport.Bucket"><code>pub use indexmap::Bucket;</code></div></li><li><div class="item-name" id="reexport.Pos"><code>pub use indexmap::Pos;</code></div></li></ul><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="binary_heap/index.html" title="mod heapless::binary_heap">binary_<wbr>heap</a></div><div class="desc docblock-short">A priority queue implemented with a binary heap.</div></li><li><div class="item-name"><a class="mod" href="mpmc/index.html" title="mod heapless::mpmc">mpmc</a></div><div class="desc docblock-short">A fixed capacity Multiple-Producer Multiple-Consumer (MPMC) lock-free queue</div></li><li><div class="item-name"><a class="mod" href="sorted_linked_list/index.html" title="mod heapless::sorted_linked_list">sorted_<wbr>linked_<wbr>list</a></div><div class="desc docblock-short">A fixed sorted priority linked list, similar to <a href="binary_heap/struct.BinaryHeap.html" title="struct heapless::binary_heap::BinaryHeap"><code>BinaryHeap</code></a> but with different properties
on <code>push</code>, <code>pop</code>, etc.
For example, the sorting of the list will never <code>memcpy</code> the underlying value, so having large
objects in the list will not cause a performance hit.</div></li><li><div class="item-name"><a class="mod" href="spsc/index.html" title="mod heapless::spsc">spsc</a></div><div class="desc docblock-short">Fixed capacity Single Producer Single Consumer (SPSC) queue</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Deque.html" title="struct heapless::Deque">Deque</a></div><div class="desc docblock-short">A fixed capacity double-ended queue.</div></li><li><div class="item-name"><a class="struct" href="struct.HistoryBuffer.html" title="struct heapless::HistoryBuffer">History<wbr>Buffer</a></div><div class="desc docblock-short">A “history buffer”, similar to a write-only ring buffer of fixed length.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMap.html" title="struct heapless::IndexMap">Index<wbr>Map</a></div><div class="desc docblock-short">Fixed capacity <a href="https://docs.rs/indexmap/2/indexmap/map/struct.IndexMap.html"><code>IndexMap</code></a></div></li><li><div class="item-name"><a class="struct" href="struct.IndexMapIter.html" title="struct heapless::IndexMapIter">Index<wbr>MapIter</a></div><div class="desc docblock-short">An iterator over the items of a <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMapIterMut.html" title="struct heapless::IndexMapIterMut">Index<wbr>MapIter<wbr>Mut</a></div><div class="desc docblock-short">A mutable iterator over the items of a <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMapKeys.html" title="struct heapless::IndexMapKeys">Index<wbr>MapKeys</a></div><div class="desc docblock-short">An iterator over the keys of a <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMapValues.html" title="struct heapless::IndexMapValues">Index<wbr>MapValues</a></div><div class="desc docblock-short">An iterator over the values of a <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMapValuesMut.html" title="struct heapless::IndexMapValuesMut">Index<wbr>MapValues<wbr>Mut</a></div><div class="desc docblock-short">A mutable iterator over the values of a <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexSet.html" title="struct heapless::IndexSet">Index<wbr>Set</a></div><div class="desc docblock-short">Fixed capacity <a href="https://docs.rs/indexmap/2/indexmap/set/struct.IndexSet.html"><code>IndexSet</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexSetIter.html" title="struct heapless::IndexSetIter">Index<wbr>SetIter</a></div><div class="desc docblock-short">An iterator over the items of a <a href="struct.IndexSet.html" title="struct heapless::IndexSet"><code>IndexSet</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.LinearMap.html" title="struct heapless::LinearMap">Linear<wbr>Map</a></div><div class="desc docblock-short">A fixed capacity map / dictionary that performs lookups via linear search</div></li><li><div class="item-name"><a class="struct" href="struct.OccupiedEntry.html" title="struct heapless::OccupiedEntry">Occupied<wbr>Entry</a></div><div class="desc docblock-short">An occupied entry which can be manipulated</div></li><li><div class="item-name"><a class="struct" href="struct.OldestOrdered.html" title="struct heapless::OldestOrdered">Oldest<wbr>Ordered</a></div><div class="desc docblock-short">An iterator on the underlying buffer ordered from oldest data to newest</div></li><li><div class="item-name"><a class="struct" href="struct.String.html" title="struct heapless::String">String</a></div><div class="desc docblock-short">A fixed capacity <a href="https://doc.rust-lang.org/std/string/struct.String.html"><code>String</code></a></div></li><li><div class="item-name"><a class="struct" href="struct.VacantEntry.html" title="struct heapless::VacantEntry">Vacant<wbr>Entry</a></div><div class="desc docblock-short">A view into an empty slot in the underlying map</div></li><li><div class="item-name"><a class="struct" href="struct.Vec.html" title="struct heapless::Vec">Vec</a></div><div class="desc docblock-short">A fixed capacity <a href="https://doc.rust-lang.org/std/vec/struct.Vec.html"><code>Vec</code></a></div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.Entry.html" title="enum heapless::Entry">Entry</a></div><div class="desc docblock-short">A view into an entry in the map</div></li></ul><h2 id="types" class="section-header">Type Aliases<a href="#types" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="type" href="type.FnvIndexMap.html" title="type heapless::FnvIndexMap">FnvIndex<wbr>Map</a></div><div class="desc docblock-short">A <a href="struct.IndexMap.html" title="struct heapless::IndexMap"><code>IndexMap</code></a> using the default FNV hasher</div></li><li><div class="item-name"><a class="type" href="type.FnvIndexSet.html" title="type heapless::FnvIndexSet">FnvIndex<wbr>Set</a></div><div class="desc docblock-short">A <a href="struct.IndexSet.html" title="struct heapless::IndexSet"><code>IndexSet</code></a> using the
default FNV hasher.
A list of all Methods and Traits available for <code>FnvIndexSet</code> can be found in
the <a href="struct.IndexSet.html" title="struct heapless::IndexSet"><code>IndexSet</code></a> documentation.</div></li></ul></section></div></main></body></html>
Reference in a new issue View git blame Copy permalink