Struct Clock 

pub struct Clock<Tz: TimeZone> { /* private fields */ }

A testable source of time

By using a Clock as the source of time in your code, you can choose in testing to replace it with a fake. Your test harness can then control how your production code sees time passing.

Implementations

impl Clock<Utc>

pub fn new() -> Self

Create a new UTC clock that matches wall-clock time

Examples found in repository

examples/basic.rs (line 10)

    pub fn new() -> Self {
        Self::new_with_clock(Clock::new())
    }

impl<Tz: TimeZone> Clock<Tz>

where <Tz as TimeZone>::Offset: Display,

pub fn new_with_timezone(timezone: Tz) -> Self

Create a new clock in this TimeZone

pub fn new_fake(start: DateTime<Tz>) -> Self

Create a new fake clock in this [‘TimeZone’].

Note that the time reported by this clock will not change from start until the clock is advanced using Clock::advance().

pub fn now(&self) -> DateTime<Tz>

Get the current time

Examples found in repository

examples/basic.rs (line 18)

    pub fn get_time(&self) -> String {
        self.clock.now().to_rfc2822()
    }

pub fn is_fake(&self) -> bool

Check whether the clock is fake

Using this in production code defeats the point, but you may wish to use it in utilities that could be called from either production or test code.

pub fn split(&self) -> Clock<Tz>

Divide this clock

This is equivalent to Clone when using the default, wall clock. The following discussion pertains only to the fake clock case which is intended to be used in testing; in that sense, getting it wrong is likely to be caught by the tests themselves.

When using the fake clock, things become more complicated to enable testing. Clones of the same clock are divided into groups. When you call clone, you get a new clock in the same group as the clock you clone. If you want a Clock in a new group of its own, you must call Clock::split.

For the clock to advance, all groups must either be sleeping or advancing - that means someone must have called either sleep or advance on exactly one instance in each group. So you can think of a group as being the clocks in one execution context (task/thread).

pub async fn advance(&mut self, duration: Duration) -> (DateTime<Tz>, Duration)

Move a fake clock forward by some duration

This will panic if called on a wall clock.

pub fn advance_blocking( &mut self, duration: Duration, ) -> (DateTime<Tz>, Duration)

Move a fake clock forward by some duration

This will panic if called on a wall clock.

pub async fn sleep(&mut self, duration: Duration)

Sleep for some duration

pub fn sleep_blocking(&mut self, duration: Duration)

Sleep for some duration

This should not be called from an async context.

Trait Implementations

impl<Tz: Clone + TimeZone> Clone for Clock<Tz>

fn clone(&self) -> Clock<Tz>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Tz: Debug + TimeZone> Debug for Clock<Tz>

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

Formats the value using the given formatter.

impl Default for Clock<Utc>

fn default() -> Self

Returns the “default value” for a type.