Derive Macro enumset::EnumSetType
#[derive(EnumSetType)]
{
// Attributes available to this derive:
#[enumset]
}
Expand description
The procedural macro used to derive EnumSetType
, and allow enums to be used with
EnumSet
.
Limitations
Currently, the following limitations apply to what kinds of enums this macro may be used with:
- The enum must have no data fields in any variant.
- Variant discriminators must be zero or positive.
- No variant discriminator may be larger than
0xFFFFFFBF
. This is chosen to limit problems involving overflow and similar edge cases. - Variant discriminators must be defined with integer literals. Expressions like
V = 1 + 1
are not currently supported.
Additional Impls
In addition to the implementation of EnumSetType
, this procedural macro creates multiple
other impls that are either required for the macro to work, or make the procedural macro more
ergonomic to use.
A full list of traits implemented as is follows:
Copy
,Clone
,Eq
,PartialEq
implementations are created to allowEnumSet
to function properly. These automatic implementations may be suppressed using#[enumset(no_super_impls)]
, but these traits must still be implemented in another way.PartialEq
,Sub
,BitAnd
,BitOr
,BitXor
, andNot
implementations are created to allow the crate to be used more ergonomically in expressions. These automatic implementations may be suppressed using#[enumset(no_ops)]
.
Options
Options are given with #[enumset(foo)]
annotations attached to the same enum as the derive.
Multiple options may be given in the same annotation using the #[enumset(foo, bar)]
syntax.
A full list of options is as follows:
#[enumset(no_super_impls)]
prevents the derive from creating implementations required forEnumSet
to function. When this attribute is specified, implementations ofCopy
,Clone
,Eq
, andPartialEq
. This can be useful if you are using a code generator that already derives these traits. These impls should function identically to the automatically derived versions, or unintentional behavior may be a result.#[enumset(no_ops)
prevents the derive from implementing any operator traits.#[enumset(crate_name = "enumset2")]
may be used to change the name of theenumset
crate used in the generated code. When thestd
feature is enabled, enumset parsesCargo.toml
to determine the name of the crate, and this flag is unnecessary.#[enumset(repr = "u8")]
may be used to specify the in-memory representation ofEnumSet
s of this enum type. The effects of this are described in theEnumSet
documentation under “FFI, Safety andrepr
”. Allowed types areu8
,u16
,u32
,u64
andu128
. If this is not used, then the derive macro will choose a type to best fit the enum, but there are no guarantees about which type will be chosen.#[enumset(repr = "array")]
forces theEnumSet
of this type to be backed with an array, even if all the variants could fit into a primitive numeric type.
When the serde
feature is used, the following features may also be specified. These options
may be used (with no effect) when building without the feature enabled:
#[enumset(serialize_repr = "…")]
may be used to override the way theEnumSet
is serialized. Valid options areu8
,u16
,u32
,u64
,list
,map
andarray
. For more information, see the [“Serialization” section of theEnumSet
documentation] (EnumSet#serialization).#[enumset(serialize_deny_unknown)]
causes the generated deserializer to return an error for unknown bits instead of silently ignoring them.
Examples
Deriving a plain EnumSetType:
#[derive(EnumSetType)]
pub enum Enum {
A, B, C, D, E, F, G,
}
Deriving a sparse EnumSetType:
#[derive(EnumSetType)]
pub enum SparseEnum {
A = 10, B = 20, C = 30, D = 127,
}
Deriving an EnumSetType without adding ops:
#[derive(EnumSetType)]
#[enumset(no_ops)]
pub enum NoOpsEnum {
A, B, C, D, E, F, G,
}