+/livesplit-wrapper

git clone https://git.julia.blue/+/livesplit-wrapper

P1n3appl3deploy: 9b9f353f3b0e319547cabc5dcadc542d5ab54386b0170e4

gh-pages
18.4 KiB101 linesraw
1<!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="A marker trait that allows types that have some invalid bit patterns to be used in places that otherwise require [`AnyBitPattern`] or `Pod` types by performing a runtime check on a perticular set of bits. This is particularly useful for types like fieldless (‘C-style’) enums, [`char`], bool, and structs containing them."><meta name="keywords" content="rust, rustlang, rust-lang, CheckedBitPattern"><title>CheckedBitPattern in bytemuck::checked - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../../normalize.css"><link rel="stylesheet" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../../ayu.css" disabled><link rel="stylesheet" href="../../dark.css" disabled><link rel="stylesheet" href="../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../storage.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../main.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../../favicon.svg"></head><body class="rustdoc trait"><!--[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">&#9776;</button><a class="sidebar-logo" href="../../bytemuck/index.html"><div class="logo-container"><img class="rust-logo" src="../../rust-logo.svg" alt="logo"></div></a><h2 class="location"></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../../bytemuck/index.html"><div class="logo-container"><img class="rust-logo" src="../../rust-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">CheckedBitPattern</a></h2><div class="sidebar-elems"><section><div class="block"><h3 class="sidebar-title"><a href="#required-associated-types">Required Associated Types</a></h3><ul><li><a href="#associatedtype.Bits">Bits</a></li></ul></div><div class="block"><h3 class="sidebar-title"><a href="#required-methods">Required Methods</a></h3><ul><li><a href="#tymethod.is_valid_bit_pattern">is_valid_bit_pattern</a></li></ul></div><div class="block"><h3 class="sidebar-title"><a href="#foreign-impls">Implementations on Foreign Types</a></h3><ul><li><a href="#impl-CheckedBitPattern-for-bool">bool</a></li><li><a href="#impl-CheckedBitPattern-for-char">char</a></li></ul></div><div class="block"><h3 class="sidebar-title"><a href="#implementors">Implementors</a></h3></div></section><h2 class="location"><a href="index.html">In bytemuck::checked</a></h2></div></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../../bytemuck/index.html"><img class="rust-logo" src="../../rust-logo.svg" alt="logo"></a><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><button type="button">?</button></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../wheel.svg"></a></div></div></form></nav></div><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn"><span class="in-band">Trait <a href="../index.html">bytemuck</a>::<wbr><a href="index.html">checked</a>::<wbr><a class="trait" href="#">CheckedBitPattern</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span></h1><span class="out-of-band"><a class="srclink" href="../../src/bytemuck/checked.rs.html#130-141">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">&#x2212;</span>]</a></span></div><div class="item-decl"><pre class="rust trait"><code>pub unsafe trait CheckedBitPattern: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Copy.html" title="trait core::marker::Copy">Copy</a> {
2    type <a href="#associatedtype.Bits" class="associatedtype">Bits</a>: <a class="trait" href="../trait.AnyBitPattern.html" title="trait bytemuck::AnyBitPattern">AnyBitPattern</a>;
3
4    fn <a href="#tymethod.is_valid_bit_pattern" class="fnname">is_valid_bit_pattern</a>(bits: &amp;Self::<a class="associatedtype" href="trait.CheckedBitPattern.html#associatedtype.Bits" title="type bytemuck::checked::CheckedBitPattern::Bits">Bits</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.bool.html">bool</a>;
5}</code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A marker trait that allows types that have some invalid bit patterns to be
6used in places that otherwise require <a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a> or <a href="../trait.Pod.html"><code>Pod</code></a> types by
7performing a runtime check on a perticular set of bits. This is particularly
8useful for types like fieldless (‘C-style’) enums, <a href="https://doc.rust-lang.org/nightly/core/primitive.char.html" title="char"><code>char</code></a>, bool, and
9structs containing them.</p>
10<p>To do this, we define a <code>Bits</code> type which is a type with equivalent layout
11to <code>Self</code> other than the invalid bit patterns which disallow <code>Self</code> from
12being <a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a>. This <code>Bits</code> type must itself implement
13<a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a>. Then, we implement a function that checks wheter a
14certain instance of the <code>Bits</code> is also a valid bit pattern of <code>Self</code>. If
15this check passes, then we can allow casting from the <code>Bits</code> to <code>Self</code> (and
16therefore, any type which is able to be cast to <code>Bits</code> is also able to be
17cast to <code>Self</code>).</p>
18<p><a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a> is a subset of <a href="trait.CheckedBitPattern.html" title="CheckedBitPattern"><code>CheckedBitPattern</code></a>, meaning that any <code>T: AnyBitPattern</code> is also <a href="trait.CheckedBitPattern.html" title="CheckedBitPattern"><code>CheckedBitPattern</code></a>. This means you can also use
19any <a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a> type in the checked versions of casting functions in
20this module. If it’s possible, prefer implementing <a href="../trait.AnyBitPattern.html" title="AnyBitPattern"><code>AnyBitPattern</code></a> for
21your type directly instead of <a href="trait.CheckedBitPattern.html" title="CheckedBitPattern"><code>CheckedBitPattern</code></a> as it gives greater
22flexibility.</p>
23<h2 id="derive"><a href="#derive">Derive</a></h2>
24<p>A <code>#[derive(CheckedBitPattern)]</code> macro is provided under the <code>derive</code>
25feature flag which will automatically validate the requirements of this
26trait and implement the trait for you for both enums and structs. This is
27the recommended method for implementing the trait, however it’s also
28possible to do manually.</p>
29<h2 id="example"><a href="#example">Example</a></h2>
30<p>If manually implementing the trait, we can do something like so:</p>
31
32<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bytemuck::{CheckedBitPattern, NoUninit};
33
34<span class="attribute">#[repr(u32)]
35#[derive(Copy, Clone)]
36</span><span class="kw">enum </span>MyEnum {
37    Variant0 = <span class="number">0</span>,
38    Variant1 = <span class="number">1</span>,
39    Variant2 = <span class="number">2</span>,
40}
41
42<span class="kw">unsafe impl </span>CheckedBitPattern <span class="kw">for </span>MyEnum {
43    <span class="kw">type </span>Bits = u32;
44
45    <span class="kw">fn </span>is_valid_bit_pattern(bits: <span class="kw-2">&amp;</span>u32) -&gt; bool {
46        <span class="kw">match </span><span class="kw-2">*</span>bits {
47            <span class="number">0 </span>| <span class="number">1 </span>| <span class="number">2 </span>=&gt; <span class="bool-val">true</span>,
48            <span class="kw">_ </span>=&gt; <span class="bool-val">false</span>,
49        }
50    }
51}
52
53<span class="comment">// It is often useful to also implement `NoUninit` on our `CheckedBitPattern` types.
54// This will allow us to do casting of mutable references (and mutable slices).
55// It is not always possible to do so, but in this case we have no padding so it is.
56</span><span class="kw">unsafe impl </span>NoUninit <span class="kw">for </span>MyEnum {}</code></pre></div>
57<p>We can now use relevant casting functions. For example,</p>
58
59<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bytemuck::{bytes_of, bytes_of_mut};
60<span class="kw">use </span>bytemuck::checked;
61
62<span class="kw">let </span>bytes = bytes_of(<span class="kw-2">&amp;</span><span class="number">2u32</span>);
63<span class="kw">let </span>result = checked::try_from_bytes::&lt;MyEnum&gt;(bytes);
64<span class="macro">assert_eq!</span>(result, <span class="prelude-val">Ok</span>(<span class="kw-2">&amp;</span>MyEnum::Variant2));
65
66<span class="comment">// Fails for invalid discriminant
67</span><span class="kw">let </span>bytes = bytes_of(<span class="kw-2">&amp;</span><span class="number">100u32</span>);
68<span class="kw">let </span>result = checked::try_from_bytes::&lt;MyEnum&gt;(bytes);
69<span class="macro">assert!</span>(result.is_err());
70
71<span class="comment">// Since we implemented NoUninit, we can also cast mutably from an original type
72// that is `NoUninit + AnyBitPattern`:
73</span><span class="kw">let </span><span class="kw-2">mut </span>my_u32 = <span class="number">2u32</span>;
74{
75  <span class="kw">let </span>as_enum_mut = checked::cast_mut::&lt;<span class="kw">_</span>, MyEnum&gt;(<span class="kw-2">&amp;mut </span>my_u32);
76  <span class="macro">assert_eq!</span>(as_enum_mut, <span class="kw-2">&amp;mut </span>MyEnum::Variant2);
77  <span class="kw-2">*</span>as_enum_mut = MyEnum::Variant0;
78}
79<span class="macro">assert_eq!</span>(my_u32, <span class="number">0u32</span>);</code></pre></div>
80<h2 id="safety"><a href="#safety">Safety</a></h2>
81<ul>
82<li><code>Self</code> <em>must</em> have the same layout as the specified <code>Bits</code> except for
83the possible invalid bit patterns being checked during
84<a href="trait.CheckedBitPattern.html#tymethod.is_valid_bit_pattern"><code>is_valid_bit_pattern</code></a>.
85<ul>
86<li>This almost certainly means your type must be <code>#[repr(C)]</code> or a similar
87specified repr, but if you think you know better, you probably don’t. If
88you   still think you know better, be careful and have fun. And don’t mess
89it up   (I mean it).</li>
90</ul>
91</li>
92<li>If <a href="trait.CheckedBitPattern.html#tymethod.is_valid_bit_pattern"><code>is_valid_bit_pattern</code></a> returns true, then the bit pattern contained
93in <code>bits</code> must also be valid for an instance of <code>Self</code>.</li>
94<li>Probably more, don’t mess it up (I mean it 2.0)</li>
95</ul>
96</div></details><h2 id="required-associated-types" class="small-section-header">Required Associated Types<a href="#required-associated-types" class="anchor"></a></h2><div class="methods"><details class="rustdoc-toggle" open><summary><div id="associatedtype.Bits" class="method has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#136">source</a><h4 class="code-header">type <a href="#associatedtype.Bits" class="associatedtype">Bits</a>: <a class="trait" href="../trait.AnyBitPattern.html" title="trait bytemuck::AnyBitPattern">AnyBitPattern</a></h4></div></summary><div class="docblock"><p><code>Self</code> <em>must</em> have the same layout as the specified <code>Bits</code> except for
97the possible invalid bit patterns being checked during
98<a href="trait.CheckedBitPattern.html#tymethod.is_valid_bit_pattern"><code>is_valid_bit_pattern</code></a>.</p>
99</div></details></div><h2 id="required-methods" class="small-section-header">Required Methods<a href="#required-methods" class="anchor"></a></h2><div class="methods"><details class="rustdoc-toggle" open><summary><div id="tymethod.is_valid_bit_pattern" class="method has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#140">source</a><h4 class="code-header">fn <a href="#tymethod.is_valid_bit_pattern" class="fnname">is_valid_bit_pattern</a>(bits: &amp;Self::<a class="associatedtype" href="trait.CheckedBitPattern.html#associatedtype.Bits" title="type bytemuck::checked::CheckedBitPattern::Bits">Bits</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.bool.html">bool</a></h4></div></summary><div class="docblock"><p>If this function returns true, then it must be valid to reinterpret <code>bits</code>
100as <code>&amp;Self</code>.</p>
101</div></details></div><h2 id="foreign-impls" class="small-section-header">Implementations on Foreign Types<a href="#foreign-impls" class="anchor"></a></h2><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-CheckedBitPattern-for-char" class="impl has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#152-159">source</a><a href="#impl-CheckedBitPattern-for-char" class="anchor"></a><h3 class="code-header in-band">impl <a class="trait" href="trait.CheckedBitPattern.html" title="trait bytemuck::checked::CheckedBitPattern">CheckedBitPattern</a> for <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.char.html">char</a></h3></section></summary><div class="impl-items"><section id="associatedtype.Bits-1" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Bits-1" class="anchor"></a><h4 class="code-header">type <a href="#associatedtype.Bits" class="associatedtype">Bits</a> = <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u32.html">u32</a></h4></section><section id="method.is_valid_bit_pattern" class="method trait-impl has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#156-158">source</a><a href="#method.is_valid_bit_pattern" class="anchor"></a><h4 class="code-header">fn <a href="#tymethod.is_valid_bit_pattern" class="fnname">is_valid_bit_pattern</a>(bits: &amp;Self::<a class="associatedtype" href="trait.CheckedBitPattern.html#associatedtype.Bits" title="type bytemuck::checked::CheckedBitPattern::Bits">Bits</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.bool.html">bool</a></h4></section></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-CheckedBitPattern-for-bool" class="impl has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#161-171">source</a><a href="#impl-CheckedBitPattern-for-bool" class="anchor"></a><h3 class="code-header in-band">impl <a class="trait" href="trait.CheckedBitPattern.html" title="trait bytemuck::checked::CheckedBitPattern">CheckedBitPattern</a> for <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.bool.html">bool</a></h3></section></summary><div class="impl-items"><section id="associatedtype.Bits-2" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Bits-2" class="anchor"></a><h4 class="code-header">type <a href="#associatedtype.Bits" class="associatedtype">Bits</a> = <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a></h4></section><section id="method.is_valid_bit_pattern-1" class="method trait-impl has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#165-170">source</a><a href="#method.is_valid_bit_pattern-1" class="anchor"></a><h4 class="code-header">fn <a href="#tymethod.is_valid_bit_pattern" class="fnname">is_valid_bit_pattern</a>(bits: &amp;Self::<a class="associatedtype" href="trait.CheckedBitPattern.html#associatedtype.Bits" title="type bytemuck::checked::CheckedBitPattern::Bits">Bits</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.bool.html">bool</a></h4></section></div></details><h2 id="implementors" class="small-section-header">Implementors<a href="#implementors" class="anchor"></a></h2><div class="item-list" id="implementors-list"><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-CheckedBitPattern-for-T" class="impl has-srclink"><a class="srclink rightside" href="../../src/bytemuck/checked.rs.html#143-150">source</a><a href="#impl-CheckedBitPattern-for-T" class="anchor"></a><h3 class="code-header in-band">impl&lt;T:&nbsp;<a class="trait" href="../trait.AnyBitPattern.html" title="trait bytemuck::AnyBitPattern">AnyBitPattern</a>&gt; <a class="trait" href="trait.CheckedBitPattern.html" title="trait bytemuck::checked::CheckedBitPattern">CheckedBitPattern</a> for T</h3></section></summary><div class="impl-items"><section id="associatedtype.Bits-3" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Bits-3" class="anchor"></a><h4 class="code-header">type <a href="#associatedtype.Bits" class="associatedtype">Bits</a> = T</h4></section></div></details></div><script src="../../implementors/bytemuck/checked/trait.CheckedBitPattern.js" data-ignore-extern-crates="core" async></script></section></div></main><div id="rustdoc-vars" data-root-path="../../" data-current-crate="bytemuck" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (4a1467723 2022-09-23)" ></div></body></html>