在开发程序的时候,我们很常需要产生出有独立名称,且为连续或是有规律的数值,用来当作界面的参数数值。举例来说,有一个函数拥有 10 种工作模式,可以透过该函数的第一个参数来传入数值 0~9 来决定要使用哪一种模式,为了方便输入,且为了确保输入的数值是在 0~9,我们通常会使用一种特殊结构作为这个参数的类型,来代入数值 0~9。如果编程语言支持枚举(enum),这个功能通常会直接使用枚举来实现。但是 Rust 编程语言的枚举有个小缺点,那就是它不方便直接利用枚举变体的「序数」(ordinal),也就是那个变体在该枚举中被定义出来的顺序,作为程序逻辑的应用。另外,如果要透过「序数」来取得对应的枚举变体,并没有内置安全的作法。
内置取得枚举变体「序数」的作法
如果要得到某枚举变体的序数,必须要使用 as 关键字,直接将枚举实体转型。程序如下:
enum Mode {
Mode1,
Mode2,
Mode3,
}
fn main() {
assert_eq!(2, Mode::Mode3 as u8);
}
但如果是枚举实体的参考,则无法使用 as 关键字来进行转型。举例来说:
enum Mode {
Mode1,
Mode2,
Mode3,
}
struct Config {
mode: Mode
}
fn foo(m: &Mode) {
assert_eq!(2, m as u8);
}
fn main() {
let config = Config {
mode: Mode::Mode3
};
foo(&config.mode);
}
以上程序,第 12 行会编译失败。需将程序修改成:
#[derive(Clone)]
enum Mode {
Mode1,
Mode2,
Mode3,
}
struct Config {
mode: Mode
}
fn foo(m: Mode) {
assert_eq!(2, m as u8);
}
fn main() {
let config = Config {
mode: Mode::Mode3
};
foo(config.mode.clone());
}
所以说这个方式并不太好用。
Enum Ordinalize
「Enum Ordinalize」是笔者开发的进程式宏套件,可以让枚举实作 Ordinalize 特性,使其拥有 from_ordinal_unsafe、from_ordinal 关联函数,以及 ordinal 方法,还有 VARIANT_COUNT、VARIANTS、VALUES 常数。
Crates.io
Cargo.toml
使用方法
使用 #[derive(Ordinalize)] 属性可以让只有单元变体(Unit Variant)的枚举实作 Ordinalize 特性。
use enum_ordinalize::Ordinalize;
#[derive(Debug, PartialEq, Eq, Ordinalize)]
enum MyEnum {
Zero,
One,
Two,
}
assert_eq!(3, MyEnum::VARIANT_COUNT);
assert_eq!([MyEnum::Zero, MyEnum::One, MyEnum::Two], MyEnum::VARIANTS);
assert_eq!([0i8, 1i8, 2i8], MyEnum::VALUES);
assert_eq!(0i8, MyEnum::Zero.ordinal());
assert_eq!(1i8, MyEnum::One.ordinal());
assert_eq!(2i8, MyEnum::Two.ordinal());
assert_eq!(Some(MyEnum::Zero), MyEnum::from_ordinal(0i8));
assert_eq!(Some(MyEnum::One), MyEnum::from_ordinal(1i8));
assert_eq!(Some(MyEnum::Two), MyEnum::from_ordinal(2i8));
assert_eq!(MyEnum::Zero, unsafe { MyEnum::from_ordinal_unsafe(0i8) });
assert_eq!(MyEnum::One, unsafe { MyEnum::from_ordinal_unsafe(1i8) });
assert_eq!(MyEnum::Two, unsafe { MyEnum::from_ordinal_unsafe(2i8) });
「序数」的大小
序数的大小是由枚举自身的大小来决定的。枚举的变体所表示的值愈大(若为负数则是愈小),则枚举的大小愈大。
例如:
use enum_ordinalize::Ordinalize;
#[derive(Debug, PartialEq, Eq, Ordinalize)]
enum MyEnum {
Zero,
One,
Two,
Thousand = 1000,
}
assert_eq!(4, MyEnum::VARIANT_COUNT);
assert_eq!([MyEnum::Zero, MyEnum::One, MyEnum::Two, MyEnum::Thousand], MyEnum::VARIANTS);
assert_eq!([0i16, 1i16, 2i16, 1000i16], MyEnum::VALUES);
assert_eq!(0i16, MyEnum::Zero.ordinal());
assert_eq!(1i16, MyEnum::One.ordinal());
assert_eq!(2i16, MyEnum::Two.ordinal());
assert_eq!(Some(MyEnum::Zero), MyEnum::from_ordinal(0i16));
assert_eq!(Some(MyEnum::One), MyEnum::from_ordinal(1i16));
assert_eq!(Some(MyEnum::Two), MyEnum::from_ordinal(2i16));
assert_eq!(MyEnum::Zero, unsafe { MyEnum::from_ordinal_unsafe(0i16) });
assert_eq!(MyEnum::One, unsafe { MyEnum::from_ordinal_unsafe(1i16) });
assert_eq!(MyEnum::Two, unsafe { MyEnum::from_ordinal_unsafe(2i16) });
为了要保存 1000,MyEnum 枚举的大小会增长,序数的大小会变成 i16,而不是 i8。
您也可以使用 #[repr(类型)] 属性来明确控制大小。举例来说:
use enum_ordinalize::Ordinalize;
#[derive(Debug, PartialEq, Eq, Ordinalize)]
#[repr(usize)]
enum MyEnum {
Zero,
One,
Two,
Thousand = 1000,
}
assert_eq!(4, MyEnum::VARIANT_COUNT);
assert_eq!([MyEnum::Zero, MyEnum::One, MyEnum::Two, MyEnum::Thousand], MyEnum::VARIANTS);
assert_eq!([0usize, 1usize, 2usize, 1000usize], MyEnum::VALUES);
assert_eq!(0usize, MyEnum::Zero.ordinal());
assert_eq!(1usize, MyEnum::One.ordinal());
assert_eq!(2usize, MyEnum::Two.ordinal());
assert_eq!(Some(MyEnum::Zero), MyEnum::from_ordinal(0usize));
assert_eq!(Some(MyEnum::One), MyEnum::from_ordinal(1usize));
assert_eq!(Some(MyEnum::Two), MyEnum::from_ordinal(2usize));
assert_eq!(MyEnum::Zero, unsafe { MyEnum::from_ordinal_unsafe(0usize) });
assert_eq!(MyEnum::One, unsafe { MyEnum::from_ordinal_unsafe(1usize) });
assert_eq!(MyEnum::Two, unsafe { MyEnum::from_ordinal_unsafe(2usize) });
好用的自动累进
变体所代表的整数是连续自动累进的,我们也可以在累进的同时,于任意的变体上设置明确的数值。
use enum_ordinalize::Ordinalize;
#[derive(Debug, PartialEq, Eq, Ordinalize)]
enum MyEnum {
Two = 2,
Three,
Four,
Eight = 8,
Nine,
NegativeTen = -10,
NegativeNine,
}
assert_eq!(7, MyEnum::VARIANT_COUNT);
assert_eq!([MyEnum::Two, MyEnum::Three, MyEnum::Four, MyEnum::Eight, MyEnum::Nine, MyEnum::NegativeTen, MyEnum::NegativeNine], MyEnum::VARIANTS);
assert_eq!([2i8, 3i8, 4i8, 8i8, 9i8, -10i8, -9i8], MyEnum::VALUES);
assert_eq!(4i8, MyEnum::Four.ordinal());
assert_eq!(9i8, MyEnum::Nine.ordinal());
assert_eq!(-9i8, MyEnum::NegativeNine.ordinal());
assert_eq!(Some(MyEnum::Four), MyEnum::from_ordinal(4i8));
assert_eq!(Some(MyEnum::Nine), MyEnum::from_ordinal(9i8));
assert_eq!(Some(MyEnum::NegativeNine), MyEnum::from_ordinal(-9i8));
assert_eq!(MyEnum::Four, unsafe { MyEnum::from_ordinal_unsafe(4i8) });
assert_eq!(MyEnum::Nine, unsafe { MyEnum::from_ordinal_unsafe(9i8) });
assert_eq!(MyEnum::NegativeNine, unsafe { MyEnum::from_ordinal_unsafe(-9i8) });
在枚举本身实作功能
基于某些情形,如果我们不想要替我们的枚举实作 Ordinalize 特性,也可以选择禁用特性的实作,逐一设置有用到的常数和函数。函数会是常数函数。名称和访问权限也都可以由我们来定义。
use enum_ordinalize::Ordinalize;
#[derive(Debug, PartialEq, Eq, Ordinalize)]
#[ordinalize(impl_trait = false)]
#[ordinalize(variant_count(pub const VARIANT_COUNT, doc = "The count of variants."))]
#[ordinalize(variants(pub const VARIANTS, doc = "List of this enum's variants."))]
#[ordinalize(values(pub const VALUES, doc = "List of values for all variants of this enum."))]
#[ordinalize(ordinal(pub const fn ordinal, doc = "Retrieve the integer number of this variant."))]
#[ordinalize(from_ordinal(pub const fn from_ordinal, doc = "Obtain a variant based on an integer number."))]
#[ordinalize(from_ordinal_unsafe(
pub const fn from_ordinal_unsafe,
doc = "Obtain a variant based on an integer number.",
doc = "# Safety",
doc = "You have to ensure that the input integer number can correspond to a variant on your own.",
))]
enum MyEnum {
A,
B,
}
assert_eq!(2, MyEnum::VARIANT_COUNT);
assert_eq!([MyEnum::A, MyEnum::B], MyEnum::VARIANTS);
assert_eq!([0i8, 1i8], MyEnum::VALUES);
assert_eq!(0i8, MyEnum::A.ordinal());
assert_eq!(1i8, MyEnum::B.ordinal());
assert_eq!(Some(MyEnum::A), MyEnum::from_ordinal(0i8));
assert_eq!(Some(MyEnum::B), MyEnum::from_ordinal(1i8));
assert_eq!(MyEnum::A, unsafe { MyEnum::from_ordinal_unsafe(0i8) });
assert_eq!(MyEnum::B, unsafe { MyEnum::from_ordinal_unsafe(1i8) });
