bitfield struct rs
0.10.0
الماكرو الإجرائي لـ BitFields التي تسمح بتحديد حقول Bitfields كهياكل. نظرًا لأن هذه المكتبة توفر ماكرو إجرائيًا ، فليس لها تبعيات في وقت التشغيل وتعمل على بيئات no-std .
Default ، fmt::Debug ، أو defmt::Format Traits أضف هذا إلى Cargo.toml :
[ dependencies ]
bitfield-struct = " 0.10 " لنبدأ بمثال بسيط. لنفترض أننا نريد تخزين بيانات متعددة داخل بايت واحد ، كما هو موضح أدناه:
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| ص | مستوى | ق | عطوف | ||||
يولد هذا الصندوق نوع غلاف جميل يجعل من السهل القيام بذلك:
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 ( ) ) ; بالإضافة إلى ذلك ، يحتوي هذا الصندوق على بعض الميزات المفيدة ، والتي تظهر هنا بمزيد من التفصيل.
يوضح المثال أدناه كيف يتم تنفيذ السمات وكيف يتم التعامل مع الأعداد الصحيحة الموقعة والحشو والأنواع المخصصة.
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 ) ;يقوم الماكرو بإنشاء ثلاث وظائف ملحق لكل حقل. يرث كل ملحق أيضًا وثائق مجاله.
توقيعات int هي:
// 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...تلميح: يمكنك استخدام إجراء Rust-analyzer "توسيع الماكرو بشكل متكرر" لعرض الرمز الذي تم إنشاؤه.
يدعم الماكرو أي أنواع قابلة للتحويل إلى نوع Bitfield الأساسي. يمكن أن يكون هذا التعدادات كما في المثال التالي أو أي بنية أخرى.
يمكن تحديد القيم الافتراضية والقيم الافتراضية مع معلمات #[bits] التالية:
from : دالة تحويل من بت الخام إلى النوع المخصص ، الافتراضيات إلى <ty>::from_bitsinto : دالة تحويل من النوع المخصص إلى أجزاء خام ، الافتراضيات إلى <ty>::into_bitsdefault : تعبير مخصص ، الافتراضية للاتصال <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 ,
} تحدد وسيطة الماكرو order تخطيط البتات ، مع الافتراضي هو LSB (أقل أهمية) أولاً:
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 ) ;يولد الماكرو الترتيب العكسي عند تحديد MSB (أهم بت):
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 ) ; يدعم الماكرو الأنواع المخصصة لتمثيل بنية Bitfield. يمكن أن يكون هذا نوعًا محددًا للإنديان كما في الأمثلة التالية (من endian-num ) أو أي بنية أخرى يمكن تحويلها من وإلى نوع Bitfield الرئيسي.
يمكن تحديد التمثيل ووظائف التحويل الخاصة به مع معلمات #[bitfield] التالية:
repr تمثيل Bitfield في الذاكرةfrom تحديد وظيفة التحويل من repr إلى نوع عدد صحيح من Bitfieldinto تحديد وظيفة التحويل من نوع عدد صحيح في Bitfield إلى reprيحتوي هذا المثال على ترتيب بايت ليتل إنديان حتى على الآلات الكبرى:
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 ] ) ;يحتوي هذا المثال على ترتيب بايت كبير من الإنديان حتى على آلات Little-Indian:
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 بشكل افتراضي ، يستمد هذا الماكرو Clone Copy . يمكنك تعطيل ذلك باستخدام وسيطة clone إضافية إذا كانت دلالات استنساخ نوعك تتطلب ذلك (على سبيل المثال ، يحمل النوع مؤشرًا للبيانات المملوكة التي يجب استنساخها أيضًا). في هذه الحالة ، يمكنك توفير تطبيقاتك الخاصة Clone 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 بشكل افتراضي ، فإنه يولد أيضًا fmt::Debug والتطبيقات Default مماثلة لتلك التي تم إنشاؤها للهياكل العادية بواسطة #[derive(Debug, Default)] . يمكنك تعطيل هذا مع debug الإضافية والوسائط default .
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 يمكن لهذا الماكرو تلقائيًا تطبيق defmt::Format يعكس تطبيق fmt::Debug الافتراضي عن طريق تمرير وسيطة defmt الإضافية. يتطلب هذا التنفيذ أن يكون Defmt Crate متاحًا كـ defmt ، وله نفس القواعد والتحذيرات مثل #[derive(defmt::Format)] .
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , defmt = true ) ]
struct DefmtExample {
data : u64
}new / Clone / Debug / Default / defmt::Format بدلاً من المنطقية ، يمكنك تحديد سمات cfg(...) لاستنساخ new ، clone ، debug ، default و defmt :
use bitfield_struct :: bitfield ;
# [ bitfield ( u64 , debug = cfg ( test ) , default = cfg ( feature = "foo" ) ) ]
struct CustomDebug {
data : u64
}
