Struct SnowflakeComparator 

pub struct SnowflakeComparator { /* private fields */ }

A type to compare Snowflakes with timestamps.

Snowflakes already form a total order. However, this is only loosely based on the snowflake’s timestamp, as the entire snowflake is taken into consideration when comparing two snowflakes. I.e., if your snowflake layout contains instance-specific constant parts like a machine ID, a snowflake that was generated after another snowflake can still be smaller.

To compare a snowflake with a given timestamp, simply create a comparator using from_system_time or Snowflake’s TryFrom implementation.

Limitations

Note that some timestamps that can theoretically be represented in a Snowflake can’t be represented by this type. To exceed this type’s limit, you’d need a timestamp that’s roughly 585 million years after the Unix epoch, however. In those cases, this type’s constructors return an error instead. If you don’t need to worry about timestamps this large in your implementation, you should be able to unwrap all Results returned by this type’s associated functions.

Implementations

impl SnowflakeComparator

pub fn from_system_time(time: SystemTime) -> Result<Self>

Creates a new snowflake comparator for the given system time.

If the system time can’t be represented by the underlying data type, this returns Error::FatalSnowflakeExhaustion instead. If time precedes the Unix epoch, this returns Error::InvalidEpoch instead.

If you’re sure your timestamp doesn’t precede the Unix epoch and doesn’t exceed the limits discussed in the structure documentation, you can safely unwrap this function’s result.

If you want to create a comparator from a snowflake’s timestamp, you should use the TryFrom implementation instead.

Example

use snowdon::{Snowflake, SnowflakeComparator};
use std::time::{Duration, SystemTime};

// This example uses Twitter's snowflake layout and epoch
let snowflake = Snowflake::from_raw(1541815603606036480).unwrap();
// Create a comparator for the first second of 2022
let comparator = SnowflakeComparator::from_system_time(
    SystemTime::UNIX_EPOCH + Duration::from_secs(1640995200),
)
.unwrap();
assert!(comparator < snowflake);
// Create a comparator for the first second of 2023
let comparator = SnowflakeComparator::from_system_time(
    SystemTime::UNIX_EPOCH + Duration::from_secs(1672531200),
)
.unwrap();
assert!(comparator > snowflake);

pub fn from_timestamp<E>(timestamp: u64) -> Result<Self>

where E: Epoch,

Creates a new snowflake comparator for the given timestamp.

The timestamp is interpreted in the context of the Epoch provided as a type parameter. I.e., it’s the number of milliseconds since the start of the given epoch.

If the underlying data type can’t represent the requested timestamp, this function returns Error::FatalSnowflakeExhaustion instead.

If you want to avoid passing your snowflake epoch to this function everytime you compare snowflakes with a timestamp, you might want to use from_system_time instead.

You should consider using the TryFrom implementation instead if you’re creating a comparator using another snowflake’s timestamp.

Example

use snowdon::{Snowflake, SnowflakeComparator};
use std::time::{Duration, SystemTime};

#[derive(Debug)]
struct TwitterEpoch;

impl Epoch for TwitterEpoch {
    fn millis_since_unix() -> u64 {
        // The epoch used by Twitter
        1288834974657
    }
}

// This example uses Twitter's snowflake layout and epoch
let snowflake = Snowflake::from_raw(1541815603606036480).unwrap();
// Create a comparator using the timestamp of our snowflake
let comparator = SnowflakeComparator::from_timestamp::<TwitterEpoch>(
    1541815603606036480 >> 22,
)
.unwrap();
assert_eq!(snowflake, comparator);
// Instead of constructing the comparator ourselves, we can use
// the comparator's `TryFrom` implementation:
assert_eq!(comparator, SnowflakeComparator::try_from(snowflake).unwrap());
// Create a comparator for the first second of 2022
let comparator =
    SnowflakeComparator::from_timestamp::<TwitterEpoch>(352160225343).unwrap();
assert!(comparator < snowflake);

pub fn from_raw_timestamp(timestamp: u64) -> Self

Creates a new snowflake comparator from the given timestamp.

Note that the timestamp passed to this function is the number of milliseconds since the Unix epoch. I.e., if the timestamp you want to compare your snowflakes with uses the snowflakes’ epoch, you’ll have to convert it to a timestamp using the Unix epoch before passing it to this function.

Usually, you shouldn’t use this function directly. Instead, use from_system_time or from_timestamp to get a snowflake comparator that works with your snowflakes.

If you want to create a comparator from a snowflake’s timestamp, you should use the TryFrom implementation instead.

From implementation

Unlike from_system_time, there’s no From<u64> implementation for snowflake comparators. While this implementation would be fairly straightforward, we intentionally don’t provide it, as it’s misleading in most cases. Without a clear name that mentions that we’re expecting a “raw timestamp”, users might expect the From implementation to take an integer representation of a snowflake as the parameter.

Trait Implementations

impl Clone for SnowflakeComparator

fn clone(&self) -> SnowflakeComparator

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SnowflakeComparator

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SnowflakeComparator

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for SnowflakeComparator

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 SnowflakeComparator

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

Returns how this snowflake comparator compares to the other comparator.

Specifically, this returns Ordering::Less, Ordering::Equal, or Ordering::Greater if this comparator’s timestamp precedes the other comparator’s timestamp, is equal to it, or succeeds it, respectively.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<L, E> PartialEq<Snowflake<L, E>> for SnowflakeComparator

where L: Layout, E: Epoch,

fn eq(&self, other: &Snowflake<L, E>) -> bool

Returns whether this snowflake comparator represents the same timestamp as the provided snowflake.

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

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

impl<L, E> PartialEq<SnowflakeComparator> for Snowflake<L, E>

where L: Layout, E: Epoch,

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

Returns whether this snowflake’s timestamp is the same as the provided comparator’s timestamp.

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

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

impl PartialEq for SnowflakeComparator

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

Returns whether this snowflake comparator represents the same timestamp as the other.

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

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

impl<L, E> PartialOrd<Snowflake<L, E>> for SnowflakeComparator

where L: Layout, E: Epoch,

fn partial_cmp(&self, other: &Snowflake<L, E>) -> Option<Ordering>

Returns how this snowflake comparator compares to the provided snowflake.

Specifically, this returns Ordering::Less, Ordering::Equal, or Ordering::Greater if this comparator’s timestamp precedes the snowflake’s timestamp, is equal to it, or succeeds it, respectively.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<L, E> PartialOrd<SnowflakeComparator> for Snowflake<L, E>

where L: Layout, E: Epoch,

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

Returns how this snowflake compares to the given snowflake comparator.

Specifically, this returns Ordering::Less, Ordering::Equal, or Ordering::Greater if this snowflake’s timestamp precedes the comparator’s timestamp, is equal to it, or succeeds it, respectively.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd for SnowflakeComparator

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

Returns how this snowflake comparator compares to the other comparator.

Specifically, this returns Ordering::Less, Ordering::Equal, or Ordering::Greater if this comparator’s timestamp precedes the other comparator’s timestamp, is equal to it, or succeeds it, respectively.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for SnowflakeComparator

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<L, E> TryFrom<Snowflake<L, E>> for SnowflakeComparator

where L: Layout, E: Epoch,

fn try_from(value: Snowflake<L, E>) -> Result<Self, Self::Error>

Tries to convert the given snowflake into a snowflake comparator.

The conversion can fail if the comparator’s underlying data type doesn’t support the snowflake’s timestamp. However, this only occurs for timestamps that are roughly 585 million years after the Unix epoch. Unless you know that your application has to deal with timestamps this large, you can safely unwrap the result returned by this conversion.

Converting from references

Snowflakes implement Copy, so you can even use this conversion method with references:

use snowdon::{Epoch, Layout, Snowflake, SnowflakeComparator};

let snowflake = Snowflake::<MyParams, MyParams>::from_raw(100 << 22)?;

fn foo(snowflake: &Snowflake<MyParams, MyParams>) {
    let _ = SnowflakeComparator::try_from(*snowflake).unwrap();
}

foo(&snowflake);

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<SystemTime> for SnowflakeComparator

fn try_from(value: SystemTime) -> Result<Self, Self::Error>

Tries to create a snowflake comparator for the given system time.

This function returns an error if value exceeds the underlying data type of the comparator. Refer to SnowflakeComparator::from_system_time for more information.

type Error = Error

The type returned in the event of a conversion error.

impl Copy for SnowflakeComparator

impl Eq for SnowflakeComparator