+/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 ="Find the offset in bytes of the given `$field` of `$Type`. Requires an already initialized `$instance` value to work with. ">< meta name ="keywords "content ="rust, rustlang, rust-lang, offset_of ">< title > offset_of in bytemuck - 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 macro "> <!--[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 >< div class ="sidebar-elems ">< h2 class ="location ">< a href ="index.html "> In bytemuck</ 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 "> Macro< a href ="index.html "> bytemuck</ a > ::< wbr >< a class ="macro "href ="# "> offset_of</ 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/offset_of.rs.html#115-135 "> 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 ">< div class ="example-wrap ">< pre class ="rust macro ">< code >< span class ="macro "> macro_rules!</ span > offset_of { 2 (< span class ="macro-nonterminal "> $instance</ span > :expr,< span class ="macro-nonterminal "> $Type</ span > :path,< span class ="macro-nonterminal "> $field</ span > :tt) => { ... }; 3 (< span class ="macro-nonterminal "> $Type</ span > :path,< span class ="macro-nonterminal "> $field</ span > :tt) => { ... }; 4}</ code ></ pre ></ div > 5</ div >< details class ="rustdoc-toggle top-doc "open >< summary class ="hideme ">< span > Expand description</ span ></ summary >< div class ="docblock ">< p > Find the offset in bytes of the given< code > $field</ code > of< code > $Type</ code > . Requires an 6already initialized< code > $instance</ code > value to work with.</ p > 7< p > This is similar to the macro from< a href ="https://docs.rs/memoffset ">< code > memoffset</ code ></ a > , 8however it uses no< code > unsafe</ code > code.</ p > 9< p > This macro has a 3-argument and 2-argument version.</ p > 10< ul > 11< li > In the 3-arg version you specify an instance of the type, the type itself, 12and the field name.</ li > 13< li > In the 2-arg version the macro will call the< a href ="https://doc.rust-lang.org/nightly/core/default/trait.Default.html#tymethod.default ">< code > default</ code ></ a > 14method to make a temporary instance of the type for you.</ li > 15</ ul > 16< p > The output of this macro is the byte offset of the field (as a< code > usize</ code > ). The 17calculations of the macro are fixed across the entire program, but if the 18type used is< code > repr(Rust)</ code > then they’re< em > not</ em > fixed across compilations or 19compilers.</ p > 20< h3 id ="examples ">< a href ="#examples "> Examples</ a ></ h3 >< h4 id ="3-arg-usage ">< a href ="#3-arg-usage "> 3-arg Usage</ a ></ h4 > 21< div class ="example-wrap ">< pre class ="rust rust-example-rendered ">< code >< span class ="comment "> // enums can't derive default, and for this example we don't pick one 22</ span >< span class ="kw "> enum</ span > MyExampleEnum { 23 A, 24 B, 25 C, 26} 27 28< span class ="comment "> // so now our struct here doesn't have Default 29</ span >< span class ="attribute "> #[repr(C)] 30</ span >< span class ="kw "> struct</ span > MyNotDefaultType { 31< span class ="kw "> pub</ span > counter: i32, 32< span class ="kw "> pub</ span > some_field: MyExampleEnum, 33} 34 35< span class ="comment "> // but we provide an instance of the type and it's all good. 36</ span >< span class ="kw "> let</ span > val = MyNotDefaultType { counter:< span class ="number "> 5</ span > , some_field: MyExampleEnum::A }; 37< span class ="macro "> assert_eq!</ span > (< span class ="macro "> offset_of!</ span > (val, MyNotDefaultType, some_field),< span class ="number "> 4</ span > );</ code ></ pre ></ div > 38< h4 id ="2-arg-usage ">< a href ="#2-arg-usage "> 2-arg Usage</ a ></ h4 > 39< div class ="example-wrap ">< pre class ="rust rust-example-rendered ">< code >< span class ="attribute "> #[derive(Default)] 40#[repr(C)] 41</ span >< span class ="kw "> struct</ span > Vertex { 42< span class ="kw "> pub</ span > loc: [f32;< span class ="number "> 3</ span > ], 43< span class ="kw "> pub</ span > color: [f32;< span class ="number "> 3</ span > ], 44} 45< span class ="comment "> // if the type impls Default the macro can make its own default instance. 46</ span >< span class ="macro "> assert_eq!</ span > (< span class ="macro "> offset_of!</ span > (Vertex, loc),< span class ="number "> 0</ span > ); 47< span class ="macro "> assert_eq!</ span > (< span class ="macro "> offset_of!</ span > (Vertex, color),< span class ="number "> 12</ span > );</ code ></ pre ></ div > 48< h2 id ="usage-with-reprpacked-structs ">< a href ="#usage-with-reprpacked-structs "> Usage with< code > #[repr(packed)]</ code > structs</ a ></ h2 > 49< p > Attempting to compute the offset of a< code > #[repr(packed)]</ code > struct with 50< code > bytemuck::offset_of!</ code > requires an< code > unsafe</ code > block. We hope to relax this in 51the future, but currently it is required to work around a soundness hole in 52Rust (See< a href ="https://github.com/rust-lang/rust/issues/27060 "> rust-lang/rust#27060</ a > ).</ p > 53< p style ="background:rgba(255,181,77,0.16);padding:0.75em; "> 54< strong > Warning:</ strong > This is only true for versions of bytemuck> 551.4.0. Previous versions of 56< code style ="background:rgba(41,24,0,0.1); "> bytemuck::offset_of!</ code > 57will only emit a warning when used on the field of a packed struct in safe 58code, which can lead to unsoundness. 59</ p > 60< p > For example, the following will fail to compile:</ p > 61 62< div class ="example-wrap compile_fail ">< div class ='tooltip '> ⓘ</ div >< pre class ="rust rust-example-rendered ">< code >< span class ="attribute "> #[repr(C, packed)] 63#[derive(Default)] 64</ span >< span class ="kw "> struct</ span > Example { 65 field: u32, 66} 67< span class ="comment "> // Doesn't compile: 68</ span >< span class ="kw "> let</ span > _offset =< span class ="macro "> bytemuck::offset_of!</ span > (Example, field);</ code ></ pre ></ div > 69< p > While the error message this generates will mention the 70< code > safe_packed_borrows</ code > lint, the macro will still fail to compile even if 71that lint is< code > #[allow]</ code > ed:</ p > 72 73< div class ="example-wrap compile_fail ">< div class ='tooltip '> ⓘ</ div >< pre class ="rust rust-example-rendered ">< code >< span class ="comment "> // Still doesn't compile: 74</ span >< span class ="attribute "> #[allow(safe_packed_borrows)] 75</ span > { 76< span class ="kw "> let</ span > _offset =< span class ="macro "> bytemuck::offset_of!</ span > (Example, field); 77}</ code ></ pre ></ div > 78< p > This< em > can</ em > be worked around by using< code > unsafe</ code > , but it is only sound to do so 79if you can guarantee that taking a reference to the field is sound.</ p > 80< p > In practice, this means it only works for fields of align(1) types, or if 81you know the field’s offset in advance (defeating the point of< code > offset_of</ code > ) 82and can prove that the struct’s alignment and the field’s offset are enough 83to prove the field’s alignment.</ p > 84< p > Once the< code > raw_ref</ code > macros are available, a future version of this crate will 85use them to lift the limitations of packed structs. For the duration of the 86< code > 1.x</ code > version of this crate that will be behind an on-by-default cargo 87feature (to maintain minimum rust version support).</ p > 88</ div ></ details ></ 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 >