+/livesplit-wrapper
git clone https://git.julia.blue/+/livesplit-wrapper
b0170e4
gh-pages
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 "> ☰</ 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 "> −</ 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: &Self::< a class ="associatedtype "href ="trait.CheckedBitPattern.html#associatedtype.Bits "title ="type bytemuck::checked::CheckedBitPattern::Bits "> Bits</ a > ) ->< 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 "> &</ span > u32) -> 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 > =>< span class ="bool-val "> true</ span > , 48< span class ="kw "> _</ span > =>< 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 "> &</ span >< span class ="number "> 2u32</ span > ); 63< span class ="kw "> let</ span > result = checked::try_from_bytes::<MyEnum>(bytes); 64< span class ="macro "> assert_eq!</ span > (result,< span class ="prelude-val "> Ok</ span > (< span class ="kw-2 "> &</ 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 "> &</ span >< span class ="number "> 100u32</ span > ); 68< span class ="kw "> let</ span > result = checked::try_from_bytes::<MyEnum>(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::<< span class ="kw "> _</ span > , MyEnum>(< span class ="kw-2 "> &mut</ span > my_u32); 76< span class ="macro "> assert_eq!</ span > (as_enum_mut,< span class ="kw-2 "> &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: &Self::< a class ="associatedtype "href ="trait.CheckedBitPattern.html#associatedtype.Bits "title ="type bytemuck::checked::CheckedBitPattern::Bits "> Bits</ a > ) ->< 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 > &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: &Self::< a class ="associatedtype "href ="trait.CheckedBitPattern.html#associatedtype.Bits "title ="type bytemuck::checked::CheckedBitPattern::Bits "> Bits</ a > ) ->< 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: &Self::< a class ="associatedtype "href ="trait.CheckedBitPattern.html#associatedtype.Bits "title ="type bytemuck::checked::CheckedBitPattern::Bits "> Bits</ a > ) ->< 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<T: < a class ="trait "href ="../trait.AnyBitPattern.html "title ="trait bytemuck::AnyBitPattern "> AnyBitPattern</ a > >< 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 >