Struct serial_num::Serial

pub struct Serial(_);

Two-byte serial number with wraparound.

A serial number is an identifier assigned incrementally to an item. In many cases, you can use a u32 or u64 and call it a day, without having to worry about overflow. The niche benefit of this type is that it only uses the space of a u16, with the problem of overflow solved by wraparound.

This is an “opaque” type, similar to Instants. Serial numbers get their significance when being compare to one another, but there is no method to get the “inner counter”. Another similarity is that there is no “maximum” serial number, since every serial number has a successor.

The window used for comparing two serial numbers is half of our number space, (u16::MAX-1)/2 = 32767. If two serial numbers are within that window, we simply compare the numbers as you normally would. If we compare numbers that do not fit into that window, like 5 and 65000, the comparison is flipped, and we say 65000 < 5. This is based on the assumption that we got to 5 by increasing 65000 beyond the point of wraparound at u16::MAX-1 = 65534. The assumption only holds if the items you assign serial numbers to have a short enough lifetime. The ordering of items in your state will get messed up if there is an item that is the 32767th successor of another item.

The final value in our number space, u16::MAX, is reserved for the special NAN value. This is done to save space - you don’t need to wrap this type in an Option if only some items are assigned a serial number.

Implementations

impl Serial

pub const NAN: Self = _

Special value representing “no serial number”.

By convention, we say this “serial number” is less than any other. It cannot be increased, or added to.

pub fn is_nan(self) -> bool

Returns true if this number is NAN.

pub fn increase(&mut self)

Increases self with wraparound.

pub fn increase_get(&mut self) -> Self

Increases self with wraparound, and returns a copy.

pub fn get_increase(&mut self) -> Self

Returns a copy of self, and increases self with wraparound.

pub fn dist(self, other: Self) -> u16

Distance with wraparound.

For the signed difference, use Self::diff().

If one of the number is NAN, the maximum distance of 32767 is returned. If both are NAN, we say the distance is 0.

pub fn diff(self, other: Self) -> i16

Difference with wraparound.

If self < other, the result is negative, and if self > other, the result is positive.

For the unsigned distance, use Self::dist().

If one of the number is NAN, the maximum difference of (-)32767 is returned. If both are NAN, we say the difference is 0.

Trait Implementations

impl Add<u16> for Serial

fn add(self, rhs: u16) -> Self::Output

Addition with wraparound.

You can add any u16 to the serial number, but be aware that due to the wraparound semantics, adding more than (u16::MAX-1)/2 = 32767 leads to a result that is less than self. Adding u16::MAX will wraparound to the same value.

If self.is_nan(), the returned serial number is also NAN.

type Output = Serial

The resulting type after applying the + operator.

impl Clone for Serial

fn clone(&self) -> Serial

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Serial

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Serial

fn default() -> Serial

Returns the “default value” for a type.

impl Hash for Serial

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Serial

fn cmp(&self, other: &Self) -> Ordering

Compare with wraparound.

By convention, we say NAN is less than any other serial number.

Based on RFC1982.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Serial> for Serial

fn eq(&self, other: &Serial) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<Serial> for Serial

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Partial comparison with wraparound.

Returns None if one of the values is NAN.

Based on RFC1982.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Serial

impl Eq for Serial

impl StructuralEq for Serial

impl StructuralPartialEq for Serial