♻️ Timer refactor to duration.✨ Add Stopwatch struct. (#1151)

This pull request is following the discussion on the issue #1127. Additionally, it integrates the change proposed by #1112.

The list of change of this pull request:

* ✨ Add `Timer::times_finished` method that counts the number of wraps for repeating timers.
* ♻️ Refactored `Timer`
* 🐛 Fix a bug where 2 successive calls to `Timer::tick` which makes a repeating timer to finish makes `Timer::just_finished` to return `false` where it should return `true`. Minimal failing example:
```rust
use bevy::prelude::*;
let mut timer: Timer<()> = Timer::from_seconds(1.0, true);
timer.tick(1.5);
assert!(timer.finished());
assert!(timer.just_finished());
timer.tick(1.5);
assert!(timer.finished());
assert!(timer.just_finished()); // <- This fails where it should not
```
* 📚 Add extensive documentation for Timer with doc examples.
* ✨ Add a `Stopwatch` struct similar to `Timer` with extensive doc and tests.

Even if the type specialization is not retained for bevy, the doc, bugfix and added method are worth salvaging 😅.
This is my first PR for bevy, please be kind to me ❤️ .

Co-authored-by: Carter Anderson <[email protected]>

crates/bevy_core/src/time/mod.rs

@@ -1,8 +1,10 @@
 mod fixed_timestep;
+mod stopwatch;
 #[allow(clippy::module_inception)]
 mod time;
 mod timer;
 
 pub use fixed_timestep::*;
+pub use stopwatch::*;
 pub use time::*;
 pub use timer::*;

crates/bevy_core/src/time/stopwatch.rs

@@ -0,0 +1,168 @@
+use bevy_ecs::reflect::ReflectComponent;
+use bevy_reflect::Reflect;
+use bevy_utils::Duration;
+
+/// A Stopwatch is a struct that track elapsed time when started.
+///
+/// # Examples
+///
+/// ```
+/// # use bevy_core::*;
+/// use std::time::Duration;
+/// let mut stopwatch = Stopwatch::new();
+/// assert_eq!(stopwatch.elapsed_secs(), 0.0);
+/// stopwatch.tick(Duration::from_secs_f32(1.0)); // tick one second
+/// assert_eq!(stopwatch.elapsed_secs(), 1.0);
+/// stopwatch.pause();
+/// stopwatch.tick(Duration::from_secs_f32(1.0)); // paused stopwatches don't tick
+/// assert_eq!(stopwatch.elapsed_secs(), 1.0);
+/// stopwatch.reset(); // reset the stopwatch
+/// assert!(stopwatch.paused());
+/// assert_eq!(stopwatch.elapsed_secs(), 0.0);
+/// ```
+#[derive(Clone, Debug, Default, Reflect)]
+#[reflect(Component)]
+pub struct Stopwatch {
+    elapsed: Duration,
+    paused: bool,
+}
+
+impl Stopwatch {
+    /// Create a new unpaused `Stopwatch` with no elapsed time.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// let stopwatch = Stopwatch::new();
+    /// assert_eq!(stopwatch.elapsed_secs(), 0.0);
+    /// assert_eq!(stopwatch.paused(), false);
+    /// ```
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Returns the elapsed time since the last [`reset`](Stopwatch::reset)
+    /// of the stopwatch.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.tick(Duration::from_secs(1));
+    /// assert_eq!(stopwatch.elapsed(), Duration::from_secs(1));
+    /// ```
+    #[inline]
+    pub fn elapsed(&self) -> Duration {
+        self.elapsed
+    }
+
+    #[inline]
+    pub fn elapsed_secs(&self) -> f32 {
+        self.elapsed().as_secs_f32()
+    }
+
+    /// Sets the elapsed time of the stopwatch.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.set_elapsed(Duration::from_secs_f32(1.0));
+    /// assert_eq!(stopwatch.elapsed_secs(), 1.0);
+    /// ```
+    #[inline]
+    pub fn set_elapsed(&mut self, time: Duration) {
+        self.elapsed = time;
+    }
+
+    /// Advance the stopwatch by `delta` seconds.
+    /// If the stopwatch is paused, ticking will not have any effect
+    /// on elapsed time.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.tick(Duration::from_secs_f32(1.5));
+    /// assert_eq!(stopwatch.elapsed_secs(), 1.5);
+    /// ```
+    pub fn tick(&mut self, delta: Duration) -> &Self {
+        if !self.paused() {
+            self.elapsed += delta;
+        }
+        self
+    }
+
+    /// Pauses the stopwatch. Any call to [`tick`](Stopwatch::tick) while
+    /// paused will not have any effect on the elapsed time.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.pause();
+    /// stopwatch.tick(Duration::from_secs_f32(1.5));
+    /// assert!(stopwatch.paused());
+    /// assert_eq!(stopwatch.elapsed_secs(), 0.0);
+    /// ```
+    #[inline]
+    pub fn pause(&mut self) {
+        self.paused = true;
+    }
+
+    /// Unpauses the stopwatch. Resume the effect of ticking on elapsed time.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.pause();
+    /// stopwatch.tick(Duration::from_secs_f32(1.0));
+    /// stopwatch.unpause();
+    /// stopwatch.tick(Duration::from_secs_f32(1.0));
+    /// assert!(!stopwatch.paused());
+    /// assert_eq!(stopwatch.elapsed_secs(), 1.0);
+    /// ```
+    #[inline]
+    pub fn unpause(&mut self) {
+        self.paused = false;
+    }
+
+    /// Returns `true` if the stopwatch is paused.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// let mut stopwatch = Stopwatch::new();
+    /// assert!(!stopwatch.paused());
+    /// stopwatch.pause();
+    /// assert!(stopwatch.paused());
+    /// stopwatch.unpause();
+    /// assert!(!stopwatch.paused());
+    /// ```
+    #[inline]
+    pub fn paused(&self) -> bool {
+        self.paused
+    }
+
+    /// Resets the stopwatch.
+    ///
+    /// # Examples
+    /// ```
+    /// # use bevy_core::*;
+    /// use std::time::Duration;
+    /// let mut stopwatch = Stopwatch::new();
+    /// stopwatch.tick(Duration::from_secs_f32(1.5));
+    /// stopwatch.reset();
+    /// assert_eq!(stopwatch.elapsed_secs(), 0.0);
+    /// ```
+    #[inline]
+    pub fn reset(&mut self) {
+        self.elapsed = Default::default();
+    }
+}