Struct StopwatchImpl 

pub struct StopwatchImpl<I: Instant> { /* private fields */ }

A stopwatch measures and accumulates elapsed time between starts and stops.

Stopwatches work with any type that implements Instant.

Implementations

impl<I: Instant> StopwatchImpl<I>

pub const fn new() -> Self

Returns a stopped stopwatch with zero elapsed time.

Examples

let sw = Sw::new();
assert!(sw.is_stopped());
assert_eq!(sw.elapsed(), Duration::ZERO);

pub fn new_started() -> Self

Returns a running stopwatch initialized with zero elapsed time.

Examples

let sw = Sw::new_started();
assert!(sw.is_running());

pub const fn new_started_at(start: I) -> Self

Returns a stopwatch initialized with zero elapsed time, started at the given instant.

Examples

let now = Instant::now();
let sw_1 = Sw::new_started_at(now);
let sw_2 = Sw::new_started_at(now);
// they've both started at the same time
assert_eq!(sw_1, sw_2);
// (and had zero elapsed time when they started)
assert_eq!(sw_1.elapsed_at(now), Duration::ZERO);

pub const fn with_elapsed(elapsed: Duration) -> Self

Returns a stopped stopwatch with the given elapsed time.

Examples

let sw = Sw::with_elapsed(Duration::from_secs(1));
assert!(sw.is_stopped());
assert_eq!(sw.elapsed(), Duration::from_secs(1));

pub fn with_elapsed_started(elapsed: Duration) -> Self

Returns a running stopwatch initialized with the given elapsed time.

Examples

let sw = Sw::with_elapsed_started(Duration::from_secs(1));
assert!(sw.is_running());
assert!(sw.elapsed() >= Duration::from_secs(1));

pub const fn from_raw(elapsed: Duration, start: Option<I>) -> Self

Returns a stopwatch from its raw parts.

Internally, a StopwatchImpl combines a saved elapsed time and an instant which records the latest start time.

While the start time is Some, the stopwatch is running. When it stops, the time which has elapsed since the start time is added to the elapsed time, and the start time is set to None.

Examples

let sw = Sw::from_raw(Duration::from_secs(1), None);
assert!(sw.is_stopped());
assert_eq!(sw.elapsed(), Duration::from_secs(1));

Notes

It is possible to craft two stopwatches whose internal components differ, but are equal according to PartialEq, Eq, and Hash.

let mut elapsed = Duration::from_secs(10);
let mut start = Instant::now();
let sw_1 = Sw::from_raw(elapsed, Some(start));
let sw_2 = Sw::from_raw(
    elapsed - Duration::from_secs(1),     // now `elapsed()` is 1s less
    Some(start - Duration::from_secs(1)), // now with start pushed back, `elapsed()` is equal
);

// different components, but they are equal!
assert_eq!(sw_1, sw_2);

pub const fn from_core(core_sw: CoreSw<I>) -> Self

Constructs a StopwatchImpl from a libsw_core::Stopwatch.

pub const fn to_core(self) -> CoreSw<I>

Returns a libsw_core::Stopwatch with the same elapsed time and start.

pub const fn is_running(&self) -> bool

Returns true if the stopwatch is running.

Examples

let sw = Sw::new_started();
assert!(sw.is_running());

pub const fn is_stopped(&self) -> bool

Returns true if the stopwatch is stopped.

Examples

let sw = Sw::new();
assert!(sw.is_stopped());

pub fn elapsed(&self) -> Duration

Returns the total time elapsed. If overflow occurs, the elapsed time is saturated to Duration::MAX.

Examples

let sw = Sw::new_started();
thread::sleep(Duration::from_millis(100));
assert!(sw.elapsed() >= Duration::from_millis(100));

pub fn elapsed_at(&self, anchor: I) -> Duration

Returns the total time elapsed, measured as if the current time were anchor. If overflow occurs, the elapsed time is saturated to Duration::MAX.

Notes

anchor saturates to the last instant the stopwatch was started.

Examples

let sw_1 = Sw::new_started();
let sw_2 = sw_1.clone();
let anchor = Instant::now();
assert!(sw_1.elapsed_at(anchor) == sw_2.elapsed_at(anchor));

pub fn checked_elapsed(&self) -> Option<Duration>

Computes the total time elapsed. If overflow occurred, returns None.

Examples

let mut sw = Sw::new_started();
thread::sleep(Duration::from_millis(100));
assert!(sw.checked_elapsed().unwrap() >= Duration::from_millis(100));
sw += Duration::MAX;
assert!(sw.checked_elapsed().is_none());

pub fn checked_elapsed_at(&self, anchor: I) -> Option<Duration>

Computes the total time elapsed, measured as if the current time were anchor. If overflow occurred, returns None.

Notes

anchor saturates to the last instant the stopwatch was started.

Examples

See the documentation for checked_elapsed for a related example.

pub fn start(&mut self) -> Result<()>

Starts measuring the time elapsed.

Errors

Returns SwStart if the stopwatch is running.

Examples

let mut sw = Sw::new();
assert!(sw.start().is_ok());
assert!(sw.start().is_err());

let then = sw.elapsed();
thread::sleep(Duration::from_millis(100));
let now = sw.elapsed();
assert!(then != now);

pub fn stop(&mut self) -> Result<()>

Stops measuring the time elapsed since the last start.

Errors

Returns SwStop if the stopwatch is already stopped.

Notes

Overflows of the new elapsed time are saturated to Duration::MAX. Use StopwatchImpl::checked_stop to explicitly check for overflow.

Examples

let mut sw = Sw::new_started();
assert!(sw.stop().is_ok());
assert!(sw.stop().is_err());

let then = sw.elapsed();
thread::sleep(Duration::from_millis(100));
let now = sw.elapsed();
assert!(then == now);

pub fn start_at(&mut self, anchor: I) -> Result<()>

Starts measuring the time elapsed as if the current time were anchor.

Errors

Returns SwStart if the stopwatch is running.

Notes

If anchor is in the future, elapsed will return Duration::ZERO until the current time catches up to it.

Examples

let mut sw_1 = Sw::new();
let mut sw_2 = Sw::new();

let start = Instant::now();
// off to the races! at the same time!
sw_1.start_at(start)?;
sw_2.start_at(start)?;

thread::sleep(Duration::from_millis(100));
let anchor = Instant::now();

assert_eq!(sw_1.elapsed_at(anchor), sw_2.elapsed_at(anchor)); // 'twas a tie
assert!(sw_1.elapsed_at(anchor) >= Duration::from_millis(100));

pub fn stop_at(&mut self, anchor: I) -> Result<()>

Stops measuring the time elapsed since the last start as if the current time were anchor.

Errors

Returns SwStop if the stopwatch is already stopped.

Notes

• If anchor is earlier than the last start, there is no effect on the elapsed time.

• Overflows of the new elapsed time are saturated to Duration::MAX. Use StopwatchImpl::checked_stop_at to explicitly check for overflow.

Examples

let mut sw_1 = Sw::new_started();
let mut sw_2 = sw_1.clone();
let stop = Instant::now();
sw_1.stop_at(stop)?;
sw_2.stop_at(stop)?;
assert_eq!(sw_1, sw_2);

pub fn checked_stop(&mut self) -> Result<Option<()>>

Tries to stop the stopwatch. If the new elapsed time overflows, returns None without mutating the stopwatch.

Errors

Returns SwStop if the stopwatch is already stopped.

Examples

let mut sw = Sw::new_started();
assert!(sw.checked_stop()?.is_some());
sw.set(Duration::MAX);
sw.start()?;
assert!(sw.checked_stop()?.is_none());

pub fn checked_stop_at(&mut self, anchor: I) -> Result<Option<()>>

Tries to stop the stopwatch, as if the current time were anchor. If the new elapsed time overflows, returns None without mutating the stopwatch.

Errors

Returns SwStop if the stopwatch is already stopped.

Notes

If anchor is earlier than the last start, there is no effect on the elapsed time.

Examples

See StopwatchImpl::checked_stop for comparable example usage.

pub fn toggle(&mut self)

Toggles whether the stopwatch is running or stopped.

Notes

See stop for details about how overflow is handled.

Examples

let mut sw = Sw::new();
sw.toggle();
assert!(sw.is_running());
sw.toggle();
assert!(sw.is_stopped());

pub fn toggle_at(&mut self, anchor: I)

Toggles whether the stopwatch is running or stopped, as if the current time were anchor.

Notes

See start_at and stop_at for notes about the chronology of anchor, as well as what happens if overflow occurs.

Examples

let mut left = Sw::new();
let mut right = Sw::new_started();

// perfect swap of left and right running
let now = Instant::now();
left.toggle_at(now);
right.toggle_at(now);

assert!(left.is_running());
assert!(right.is_stopped());

pub fn checked_toggle(&mut self) -> Option<()>

Tries to toggle whether the stopwatch is running or stopped. If the new elapsed time overflows, returns None without mutating the stopwatch.

Examples

let mut sw = Sw::with_elapsed_started(Duration::MAX);
thread::sleep(Duration::from_millis(100));
// whoops, new elapsed time can't be Duration::MAX + 100ms
assert!(sw.checked_toggle().is_none());

pub fn checked_toggle_at(&mut self, anchor: I) -> Option<()>

Tries to toggle whether the stopwatch is running or stopped, as if the current time were anchor. If the new elapsed time overflows, returns None without mutating the stopwatch.

Examples

See the documentation for checked_toggle for a related example.

pub fn guard(&mut self) -> Result<Guard<'_, I>>

Starts the stopwatch, returning a Guard which when dropped, will stop the stopwatch.

Errors

Returns SwGuard if the stopwatch is running.

Examples

For examples on how to use Guards, see the struct documentation.

pub fn guard_at(&mut self, anchor: I) -> Result<Guard<'_, I>>

Starts the stopwatch as if the current time were anchor, returning a Guard, which when dropped, will stop the stopwatch.

Errors

Returns SwGuard if the stopwatch is running.

Notes

For details about anchor, see start_at. For examples on how to use Guards, see the struct documentation.

pub fn reset(&mut self)

Stops and resets the elapsed time to zero.

Examples

let mut sw = Sw::with_elapsed_started(Duration::from_secs(1));
sw.reset();
assert_eq!(sw, Sw::new());

pub fn reset_in_place(&mut self)

Resets the elapsed time to zero without affecting whether the stopwatch is running.

Examples

let mut sw = Sw::with_elapsed_started(Duration::from_secs(1));
sw.reset_in_place();
assert!(sw.is_running());
// new elapsed time is close to zero
assert!(sw.elapsed() < Duration::from_millis(1));

sw.stop()?;
sw.reset_in_place();
assert_eq!(sw, Sw::new());

pub fn reset_in_place_at(&mut self, start: I)

Resets the elapsed time to zero without affecting whether the stopwatch is running.

Notes

See start_at for notes about the chronology of anchor.

Examples

See the documentation for reset_in_place for a related example.

pub fn set(&mut self, new: Duration)

Stops and sets the total elapsed time to new.

Examples

let mut sw = Sw::new();
sw.set(Duration::from_secs(1));
assert_eq!(sw.elapsed(), Duration::from_secs(1));

pub fn set_in_place(&mut self, new: Duration)

Sets the total elapsed time to new without affecting whether the stopwatch is running.

Examples

let mut sw = Sw::new();
sw.set_in_place(Duration::from_secs(1));
assert_eq!(sw.elapsed(), Duration::from_secs(1));
assert!(sw.is_stopped());

sw.start()?;
sw.set_in_place(Duration::from_secs(2));
assert!(sw.elapsed() >= Duration::from_secs(2));
assert!(sw.is_running());

pub fn set_in_place_at(&mut self, new: Duration, anchor: I)

Sets the total elapsed time to new as if the current time were anchor, and without affecting whether the stopwatch is running.

Notes

See start_at for notes about the chronology of anchor.

Examples

See the documentation for set_in_place for a related example.

pub fn replace(&mut self, new: Duration) -> Duration

Stops and sets the total elapsed time to new, returning the previous elapsed time.

Examples

let mut sw = Sw::with_elapsed(Duration::from_secs(3));
let previous = sw.replace(Duration::from_secs(1));
assert_eq!(previous, Duration::from_secs(3));
assert_eq!(sw.elapsed(), Duration::from_secs(1));

pub fn replace_at(&mut self, new: Duration, anchor: I) -> Duration

Stops and sets the total elapsed time to new, returning the previous elapsed time as if the current time were anchor.

Notes

See elapsed_at for notes about the chronology of anchor.

Examples

See the documentation for replace for a related example.

pub const fn saturating_add(self, dur: Duration) -> Self

Adds dur to the total elapsed time. If overflow occurred, the total elapsed time is set to Duration::MAX.

let mut sw = Sw::with_elapsed(Duration::from_secs(1));
sw = sw.saturating_add(Duration::from_secs(1));
assert_eq!(sw.elapsed(), Duration::from_secs(2));
sw = sw.saturating_add(Duration::MAX);
assert_eq!(sw.elapsed(), Duration::MAX);

pub fn saturating_sub(self, dur: Duration) -> Self

Subtracts dur from the total elapsed time. If underflow occurred, the total elapsed time is set to Duration::ZERO.

Notes

See the documentation for saturating_sub_at for notes about positive overflow.

Examples

let mut sw = Sw::with_elapsed(Duration::from_secs(1));
sw = sw.saturating_sub(Duration::from_secs(1));
assert_eq!(sw.elapsed(), Duration::ZERO);
sw = sw.saturating_sub(Duration::from_secs(1));
assert_eq!(sw.elapsed(), Duration::ZERO);

pub fn saturating_sub_at(self, dur: Duration, anchor: I) -> Self

Subtracts dur from the total elapsed time, as if the current time were anchor. If underflow occurred, the total elapsed time is set to Duration::ZERO.

Notes

• If the elapsed time is overflowing (as in, would exceed Duration::MAX), the elapsed time is clamped to Duration::MAX and dur is subtracted from that.

• anchor saturates to the last instant the stopwatch was started.

Examples

let mut sw = Sw::new_started();
thread::sleep(Duration::from_millis(100));
let mut now = Instant::now();
sw = sw.saturating_sub_at(Duration::from_secs(1), now);
assert_eq!(sw.elapsed_at(now), Duration::ZERO);

pub const fn checked_add(self, dur: Duration) -> Option<Self>

Adds dur to the total elapsed time. If overflow occurred, returns None.

Examples

let mut sw = Sw::new();
sw = sw.checked_add(Duration::from_secs(1)).unwrap();
assert_eq!(sw.elapsed(), Duration::from_secs(1));
assert_eq!(sw.checked_add(Duration::MAX), None);

pub fn checked_sub(self, dur: Duration) -> Option<Self>

Subtracts dur from the total elapsed time. If overflow occurred, returns None.

Notes

See the documentation for checked_sub_at for notes about positive overflow.

Examples

let mut sw = Sw::new();
assert_eq!(sw.checked_sub(Duration::from_secs(1)), None);
sw += Duration::from_secs(1);
assert_eq!(
    sw.checked_sub(Duration::from_secs(1)),
    Some(Sw::with_elapsed(Duration::ZERO)),
);

pub fn checked_sub_at(self, dur: Duration, anchor: I) -> Option<Self>

Subtracts dur from the total elapsed time, as if the current time were anchor. If overflow occurred, returns None.

Notes

• Overflow can also occur if the elapsed time is overflowing (as in, would exceed Duration::MAX).

• anchor saturates to the last instant the stopwatch was started.

Examples

let mut sw = Sw::new_started();
thread::sleep(Duration::from_millis(100));
let now = Instant::now();
// underflow yields `None`
assert_eq!(sw.checked_sub_at(Duration::from_secs(1), now), None);

// positive overflow yields `None`
sw.set_in_place(Duration::MAX);
assert_eq!(sw.checked_sub(Duration::ZERO), None);

Trait Implementations

impl<I: Instant> Add<Duration> for StopwatchImpl<I>

fn add(self, dur: Duration) -> Self::Output

Add dur to self.

Currently this is an alias to StopwatchImpl::checked_add, but that is not a stable guarentee. If you need a guarentee on the implementation, use the checked or saturating methods explicitly.

Panics

Panics if overflow occurs.

type Output = StopwatchImpl<I>

The resulting type after applying the + operator.

impl<I: Instant> AddAssign<Duration> for StopwatchImpl<I>

fn add_assign(&mut self, dur: Duration)

Performs the += operation.

impl<I: Clone + Instant> Clone for StopwatchImpl<I>

fn clone(&self) -> StopwatchImpl<I>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<I: Instant> Debug for StopwatchImpl<I>

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

Formats the value using the given formatter.

impl<I: Instant> Default for StopwatchImpl<I>

fn default() -> Self

Returns the default stopwatch. Same as calling StopwatchImpl::new.

impl<I: Instant> From<Stopwatch<I>> for StopwatchImpl<I>

fn from(core_sw: CoreSw<I>) -> Self

Converts to this type from the input type.

impl<I: Instant> From<StopwatchImpl<I>> for Stopwatch<I>

fn from(val: StopwatchImpl<I>) -> Self

Converts to this type from the input type.

impl<I: Instant + Hash> Hash for StopwatchImpl<I>

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

Hashes self and rhs. These hashes are not dependent on the time of measurement, so they can be used to test equality.

Support

I (the Instant type used by the stopwatch) must implement Hash.

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<I: Instant> PartialEq for StopwatchImpl<I>

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

Tests for equality between self and rhs.

Stopwatches are equal if whether they are running and their elapsed time are equal.

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<I: Instant> Sub<Duration> for StopwatchImpl<I>

fn sub(self, dur: Duration) -> Self::Output

Subtract dur from self.

Currently this is an alias to StopwatchImpl::checked_sub, but that is not a stable guarentee. If you need a guarentee on the implementation, use the checked or saturating methods explicitly.

Panics

Panics if overflow occurs.

type Output = StopwatchImpl<I>

The resulting type after applying the - operator.

impl<I: Instant> SubAssign<Duration> for StopwatchImpl<I>

fn sub_assign(&mut self, dur: Duration)

Performs the -= operation.

impl<I: Copy + Instant> Copy for StopwatchImpl<I>

impl<I: Instant> Eq for StopwatchImpl<I>