Trait regex_automata::StateID
source · pub unsafe trait StateID: Clone + Copy + Debug + Eq + Hash + PartialEq + PartialOrd + Ord {
// Required methods
fn from_usize(n: usize) -> Self;
fn to_usize(self) -> usize;
fn max_id() -> usize;
fn read_bytes(slice: &[u8]) -> Self;
fn write_bytes(self, slice: &mut [u8]);
}
Expand description
A trait describing the representation of a DFA’s state identifier.
The purpose of this trait is to safely express both the possible state
identifier representations that can be used in a DFA and to convert between
state identifier representations and types that can be used to efficiently
index memory (such as usize
).
In general, one should not need to implement this trait explicitly. In
particular, this crate provides implementations for u8
, u16
, u32
,
u64
and usize
. (u32
and u64
are only provided for targets that can
represent all corresponding values in a usize
.)
§Safety
This trait is unsafe because the correctness of its implementations may be
relied upon by other unsafe code. For example, one possible way to
implement this trait incorrectly would be to return a maximum identifier
in max_id
that is greater than the real maximum identifier. This will
likely result in wrap-on-overflow semantics in release mode, which can in
turn produce incorrect state identifiers. Those state identifiers may then
in turn access out-of-bounds memory in a DFA’s search routine, where bounds
checks are explicitly elided for performance reasons.
Required Methods§
sourcefn from_usize(n: usize) -> Self
fn from_usize(n: usize) -> Self
Convert from a usize
to this implementation’s representation.
Implementors may assume that n <= Self::max_id
. That is, implementors
do not need to check whether n
can fit inside this implementation’s
representation.
sourcefn to_usize(self) -> usize
fn to_usize(self) -> usize
Convert this implementation’s representation to a usize
.
Implementors must not return a usize
value greater than
Self::max_id
and must not permit overflow when converting between the
implementor’s representation and usize
. In general, the preferred
way for implementors to achieve this is to simply not provide
implementations of StateID
that cannot fit into the target platform’s
usize
.
sourcefn max_id() -> usize
fn max_id() -> usize
Return the maximum state identifier supported by this representation.
Implementors must return a correct bound. Doing otherwise may result in memory unsafety.
sourcefn read_bytes(slice: &[u8]) -> Self
fn read_bytes(slice: &[u8]) -> Self
Read a single state identifier from the given slice of bytes in native endian format.
Implementors may assume that the given slice has length at least
size_of::<Self>()
.
sourcefn write_bytes(self, slice: &mut [u8])
fn write_bytes(self, slice: &mut [u8])
Write this state identifier to the given slice of bytes in native endian format.
Implementors may assume that the given slice has length at least
size_of::<Self>()
.