bitfield struct rs
0.10.0
Makro prosedural untuk bitfields yang memungkinkan menentukan bitfields sebagai struct. Karena perpustakaan ini menyediakan makro prosedural, ia tidak memiliki dependensi runtime dan berfungsi untuk lingkungan no-std .
Default , fmt::Debug , atau defmt::Format ciri -ciri Tambahkan ini ke Cargo.toml Anda.toml:
[ dependencies ]
bitfield-struct = " 0.10 " Mari kita mulai dengan contoh sederhana. Misalkan kita ingin menyimpan beberapa data di dalam satu byte, seperti yang ditunjukkan di bawah ini:
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| P | Tingkat | S | Baik | ||||
Peti ini menghasilkan jenis pembungkus yang bagus yang membuatnya mudah untuk melakukan ini:
use bitfield_struct :: bitfield ;
/// Define your type like this with the bitfield attribute
# [ bitfield ( u8 ) ]
struct MyByte {
/// The first field occupies the least significant bits
# [ bits ( 4 ) ]
kind : usize ,
/// Booleans are 1 bit large
system : bool ,
/// The bits attribute specifies the bit size of this field
# [ bits ( 2 ) ]
level : usize ,
/// The last field spans over the most significant bits
present : bool
}
// The macro creates three accessor functions for each field:
// <name>, with_<name> and set_<name>
let my_byte = MyByte :: new ( )
. with_kind ( 15 )
. with_system ( false )
. with_level ( 3 )
. with_present ( true ) ;
assert ! ( my_byte . present ( ) ) ; Selain itu, peti ini memiliki beberapa fitur yang berguna, yang ditampilkan di sini secara lebih rinci.
Contoh di bawah ini menunjukkan bagaimana atribut dibawa dan bagaimana bilangan bulat, padding, dan tipe khusus ditangani.
use bitfield_struct :: bitfield ;
/// A test bitfield with documentation
# [ bitfield ( u64 ) ]
# [ derive ( PartialEq , Eq ) ] // <- Attributes after `bitfield` are carried over
struct MyBitfield {
/// Defaults to 16 bits for u16
int : u16 ,
/// Interpreted as 1 bit flag, with a custom default value
# [ bits ( default = true ) ]
flag : bool ,
/// Custom bit size
# [ bits ( 1 ) ]
tiny : u8 ,
/// Sign extend for signed integers
# [ bits ( 13 ) ]
negative : i16 ,
/// Supports any type with `into_bits`/`from_bits` functions
# [ bits ( 16 ) ]
custom : CustomEnum ,
/// Public field -> public accessor functions
# [ bits ( 10 ) ]
pub public : usize ,
/// Also supports read-only fields
# [ bits ( 1 , access = RO ) ]
read_only : bool ,
/// And write-only fields
# [ bits ( 1 , access = WO ) ]
write_only : bool ,
/// Padding
# [ bits ( 5 ) ]
__ : u8 ,
}
/// A custom enum
# [ derive ( Debug , PartialEq , Eq ) ]
# [ repr ( u16 ) ]
enum CustomEnum {
A = 0 ,
B = 1 ,
C = 2 ,
}
impl CustomEnum {
// This has to be a const fn
const fn into_bits ( self ) -> u16 {
self as _
}
const fn from_bits ( value : u16 ) -> Self {
match value {
0 => Self :: A ,
1 => Self :: B ,
_ => Self :: C ,
}
}
}
// Usage:
let mut val = MyBitfield :: new ( )
. with_int ( 3 << 15 )
. with_tiny ( 1 )
. with_negative ( - 3 )
. with_custom ( CustomEnum :: B )
. with_public ( 2 )
// .with_read_only(true) <- Would not compile
. with_write_only ( false ) ;
println ! ( "{val:?}" ) ;
let raw : u64 = val . into ( ) ;
println ! ( "{raw:b}" ) ;
assert_eq ! ( val . int ( ) , 3 << 15 ) ;
assert_eq ! ( val . flag ( ) , true ) ;
assert_eq ! ( val . negative ( ) , - 3 ) ;
assert_eq ! ( val . tiny ( ) , 1 ) ;
assert_eq ! ( val . custom ( ) , CustomEnum :: B ) ;
assert_eq ! ( val . public ( ) , 2 ) ;
assert_eq ! ( val . read_only ( ) , false ) ;
// const members
assert_eq ! ( MyBitfield :: FLAG_BITS , 1 ) ;
assert_eq ! ( MyBitfield :: FLAG_OFFSET , 16 ) ;
val . set_negative ( 1 ) ;
assert_eq ! ( val . negative ( ) , 1 ) ;Makro menghasilkan tiga fungsi aksesor untuk setiap bidang. Setiap aksesor juga mewarisi dokumentasi bidangnya.
Tanda tangan untuk int adalah:
// generated struct
struct MyBitfield ( u64 ) ;
impl MyBitfield {
const fn new ( ) -> Self { Self ( 0 ) }
const INT_BITS : usize = 16 ;
const INT_OFFSET : usize = 0 ;
const fn int ( & self ) -> u16 { todo ! ( ) }
const fn with_int ( self , value : u16 ) -> Self { todo ! ( ) }
const fn with_int_checked ( self , value : u16 ) -> Result < Self , ( ) > { todo ! ( ) }
const fn set_int ( & mut self , value : u16 ) { todo ! ( ) }
const fn set_int_checked ( & mut self , value : u16 ) -> Result < ( ) , ( ) > { todo ! ( ) }
// other field ...
}
// Also generates From<u64>, Into<u64>, Default, and Debug implementations...Petunjuk: Anda dapat menggunakan tindakan Rust-Analyzer "memperluas makro secara rekursif" untuk melihat kode yang dihasilkan.
Makro mendukung semua jenis yang dapat dikonversi ke jenis Bitfield yang mendasarinya. Ini bisa enum seperti dalam contoh berikut atau struct lainnya.
Nilai konversi dan default dapat ditentukan dengan parameter #[bits] berikut:
from : Fungsi Mengonversi dari bit mentah menjadi jenis kustom, default ke <ty>::from_bitsinto : Function Conversi dari tipe kustom menjadi bit mentah, default ke <ty>::into_bitsdefault : Ekspresi Kustom, default untuk memanggil <ty>::from_bits(0) use bitfield_struct :: bitfield ;
# [ bitfield ( u16 ) ]
# [ derive ( PartialEq , Eq ) ]
struct Bits {
/// Supports any convertible type
# [ bits ( 8 , default = CustomEnum :: B , from = CustomEnum :: my_from_bits ) ]
custom : CustomEnum ,
/// And nested bitfields
# [ bits ( 8 ) ]
nested : Nested ,
}
# [ derive ( Debug , PartialEq , Eq ) ]
# [ repr ( u8 ) ]
enum CustomEnum {
A = 0 ,
B = 1 ,
C = 2 ,
}
impl CustomEnum {
// This has to be a const fn
const fn into_bits ( self ) -> u8 {
self as _
}
const fn my_from_bits ( value : u8 ) -> Self {
match value {
0 => Self :: A ,
1 => Self :: B ,
_ => Self :: C ,
}
}
}
/// Bitfields implement the conversion functions automatically
# [ bitfield ( u8 ) ]
struct Nested {
# [ bits ( 4 ) ]
lo : u8 ,
# [ bits ( 4 ) ]
hi : u8 ,
} Argumen makro order opsional menentukan tata letak bit, dengan default menjadi LSB (bit paling tidak signifikan) terlebih dahulu:
use bitfield_struct :: bitfield ;
# [ bitfield ( u8 , order = Lsb ) ]
struct MyLsbByte {
/// The first field occupies the *least* significant bits
# [ bits ( 4 ) ]
kind : usize ,
system : bool ,
# [ bits ( 2 ) ]
level : usize ,
present : bool
}
let my_byte_lsb = MyLsbByte :: new ( )
. with_kind ( 10 )
. with_system ( false )
. with_level ( 2 )
. with_present ( true ) ;
// .- present
// | .- level
// | | .- system
// | | | .- kind
assert_eq ! ( my_byte_lsb . 0 , 0b1_10_0_1010 ) ;Makro menghasilkan urutan terbalik ketika MSB (bit paling signifikan) ditentukan:
use bitfield_struct :: bitfield ;
# [ bitfield ( u8 , order = Msb ) ]
struct MyMsbByte {
/// The first field occupies the *most* significant bits
# [ bits ( 4 ) ]
kind : usize ,
system : bool ,
# [ bits ( 2 ) ]
level : usize ,
present : bool
}
let my_byte_msb = MyMsbByte :: new ( )
. with_kind ( 10 )
. with_system ( false )
. with_level ( 2 )
. with_present ( true ) ;
// .- kind
// | .- system
// | | .- level
// | | | .- present
assert_eq ! ( my_byte_msb . 0 , 0b1010_0_10_1 ) ; Makro mendukung jenis khusus untuk representasi struct bitfield. Ini bisa berupa tipe endian-defining seperti dalam contoh-contoh berikut (dari endian-num ) atau struct lain yang dapat dikonversi ke dan dari tipe Bitfield utama.
Representasi dan fungsi konversi dapat ditentukan dengan parameter #[bitfield] berikut:
repr menentukan representasi bitfield dalam memorifrom untuk menentukan fungsi konversi dari rept ke tipe integer bitfieldinto untuk menentukan fungsi konversi dari tipe integer bitfield ke reprContoh ini memiliki pesanan byte kecil-endian bahkan pada mesin besar-endian:
use bitfield_struct :: bitfield ;
use endian_num :: le16 ;
# [ bitfield ( u16 , repr = le16 , from = le16 :: from_ne , into = le16 :: to_ne ) ]
struct MyLeBitfield {
# [ bits ( 4 ) ]
first_nibble : u8 ,
# [ bits ( 12 ) ]
other : u16 ,
}
let my_be_bitfield = MyLeBitfield :: new ( )
. with_first_nibble ( 0x1 )
. with_other ( 0x234 ) ;
assert_eq ! ( my_be_bitfield . into_bits ( ) . to_le_bytes ( ) , [ 0x41 , 0x23 ] ) ;Contoh ini memiliki pesanan byte besar-endian bahkan pada mesin kecil-endian:
use bitfield_struct :: bitfield ;
use endian_num :: be16 ;
# [ bitfield ( u16 , repr = be16 , from = be16 :: from_ne , into = be16 :: to_ne ) ]
struct MyBeBitfield {
# [ bits ( 4 ) ]
first_nibble : u8 ,
# [ bits ( 12 ) ]
other : u16 ,
}
let my_be_bitfield = MyBeBitfield :: new ( )
. with_first_nibble ( 0x1 )
. with_other ( 0x234 ) ;
assert_eq ! ( my_be_bitfield . into_bits ( ) . to_be_bytes ( ) , [ 0x23 , 0x41 ] ) ; Clone , Copy Secara default, makro ini mendapatkan Clone dan Copy . Anda dapat menonaktifkan ini dengan argumen clone tambahan jika semantik kloning tipe Anda memerlukannya (misalnya jenisnya memegang pointer untuk data yang dimiliki yang juga harus dikloning). Dalam hal ini, Anda dapat memberikan implementasi Anda sendiri untuk Clone dan Copy .
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , clone = false ) ]
struct CustomClone {
data : u64
}
impl Clone for CustomClone {
fn clone ( & self ) -> Self {
Self :: new ( ) . with_data ( self . data ( ) )
}
}
// optionally:
impl Copy for CustomClone { }fmt::Debug , Default Secara default, ini juga menghasilkan implementasi fmt::Debug dan Default yang sesuai dengan yang dibuat untuk struct normal oleh #[derive(Debug, Default)] . Anda dapat menonaktifkan ini dengan argumen debug dan default tambahan.
use std :: fmt :: { Debug , Formatter , Result } ;
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , debug = false , default = false ) ]
struct CustomDebug {
data : u64
}
impl Debug for CustomDebug {
fn fmt ( & self , f : & mut Formatter < ' _ > ) -> Result {
write ! ( f , "0x{:x}" , self . data ( ) )
}
}
impl Default for CustomDebug {
fn default ( ) -> Self {
Self ( 123 )
}
}
let val = CustomDebug :: default ( ) ;
println ! ( "{val:?}" )defmt::Format Makro ini secara otomatis dapat mengimplementasikan defmt::Format yang mencerminkan implementasi fmt::Debug default dengan meneruskan argumen defmt ekstra. Implementasi ini mensyaratkan peti defmt tersedia sebagai defmt , dan memiliki aturan dan peringatan yang sama dengan #[derive(defmt::Format)] .
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , defmt = true ) ]
struct DefmtExample {
data : u64
}new / Clone / Debug / Default / defmt::Format Alih -alih Booleans, Anda dapat menentukan atribut cfg(...) untuk new , clone , debug , default , dan defmt :
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , debug = cfg ( test ) , default = cfg ( feature = "foo" ) ) ]
struct CustomDebug {
data : u64
}
