Struct livesplit_core::timing::Timer

pub struct Timer { /* private fields */ }

A Timer provides all the capabilities necessary for doing speedrun attempts.

Examples

use livesplit_core::{Run, Segment, Timer, TimerPhase};

// Create a run object that we can use with at least one segment.
let mut run = Run::new();
run.set_game_name("Super Mario Odyssey");
run.set_category_name("Any%");
run.push_segment(Segment::new("Cap Kingdom"));

// Create the timer from the run.
let mut timer = Timer::new(run).expect("Run with at least one segment provided");

// Start a new attempt.
timer.start();
assert_eq!(timer.current_phase(), TimerPhase::Running);

// Create a split.
timer.split();

// The run should be finished now.
assert_eq!(timer.current_phase(), TimerPhase::Ended);

// Reset the attempt and confirm that we want to store the attempt.
timer.reset(true);

// The attempt is now over.
assert_eq!(timer.current_phase(), TimerPhase::NotRunning);

Implementations

impl Timer

pub fn new(run: Run) -> Result<Self, CreationError>

Creates a new Timer based on a Run object storing all the information about the splits. The Run object needs to have at least one segment, so that the Timer can store the final time. If a Run object with no segments is provided, the Timer creation fails.

pub fn into_shared(self) -> SharedTimer

Consumes the Timer and creates a Shared Timer that can be shared across multiple threads with multiple owners.

pub fn into_run(self, update_splits: bool) -> Run

Takes out the Run from the Timer and resets the current attempt if there is one in progress. If the splits are to be updated, all the information of the current attempt is stored in the Run’s history. Otherwise the current attempt’s information is discarded.

pub fn replace_run(&mut self, run: Run, update_splits: bool) -> Result<Run, Run>

Replaces the Run object used by the Timer with the Run object provided. If the Run provided contains no segments, it can’t be used for timing and is returned as the Err case of the Result. Otherwise the Run that was in use by the Timer is being returned. Before the Run is returned, the current attempt is reset and the splits are being updated depending on the update_splits parameter.

pub fn set_run(&mut self, run: Run) -> Result<(), Run>

Sets the Run object used by the Timer with the Run object provided. If the Run provided contains no segments, it can’t be used for timing and is returned as the Err case of the Result. The Run object in use by the Timer is dropped by this method.

pub const fn run(&self) -> &Run

Accesses the Run in use by the Timer.

pub fn mark_as_unmodified(&mut self)

Marks the Run as unmodified, so that it is known that all the changes have been saved.

pub const fn current_phase(&self) -> TimerPhase

Returns the current Timer Phase.

pub fn snapshot(&self) -> Snapshot<'_>

Creates a new snapshot of the timer at the point in time of this call. It represents a frozen state of the timer such that calculations can work with an entirely consistent view of the timer without the current time changing underneath.

pub const fn current_timing_method(&self) -> TimingMethod

Returns the currently selected Timing Method.

pub fn set_current_timing_method(&mut self, method: TimingMethod)

Sets the current Timing Method to the Timing Method provided.

pub fn toggle_timing_method(&mut self)

Toggles between the Real Time and Game Time timing methods.

pub fn current_comparison(&self) -> &str

Returns the current comparison that is being compared against. This may be a custom comparison or one of the Comparison Generators.

pub fn set_current_comparison<S: PopulateString>(
    &mut self,
    comparison: S
) -> Result<(), ()>

Tries to set the current comparison to the comparison specified. If the comparison doesn’t exist Err is returned.

pub fn current_split(&self) -> Option<&Segment>

Accesses the split the attempt is currently on. If there’s no attempt in progress or the run finished, None is returned instead.

pub const fn current_split_index(&self) -> Option<usize>

Accesses the index of the split the attempt is currently on. If there’s no attempt in progress, None is returned instead. This returns an index that is equal to the amount of segments when the attempt is finished, but has not been reset. So you need to be careful when using this value for indexing.

pub fn start(&mut self)

Starts the Timer if there is no attempt in progress. If that’s not the case, nothing happens.

pub fn split(&mut self)

If an attempt is in progress, stores the current time as the time of the current split. The attempt ends if the last split time is stored.

pub fn split_or_start(&mut self)

Starts a new attempt or stores the current time as the time of the current split. The attempt ends if the last split time is stored.

pub fn skip_split(&mut self)

Skips the current split if an attempt is in progress and the current split is not the last split.

pub fn undo_split(&mut self)

Removes the split time from the last split if an attempt is in progress and there is a previous split. The Timer Phase also switches to Running if it previously was Ended.

pub fn reset(&mut self, update_splits: bool)

Resets the current attempt if there is one in progress. If the splits are to be updated, all the information of the current attempt is stored in the Run’s history. Otherwise the current attempt’s information is discarded.

pub fn reset_and_set_attempt_as_pb(&mut self)

Resets the current attempt if there is one in progress. The splits are updated such that the current attempt’s split times are being stored as the new Personal Best.

pub fn pause(&mut self)

Pauses an active attempt that is not paused.

pub fn resume(&mut self)

Resumes an attempt that is paused.

pub fn toggle_pause(&mut self)

Toggles an active attempt between Paused and Running.

pub fn toggle_pause_or_start(&mut self)

Toggles an active attempt between Paused and Running or starts an attempt if there’s none in progress.

pub fn undo_all_pauses(&mut self)

Removes all the pause times from the current time. If the current attempt is paused, it also resumes that attempt. Additionally, if the attempt is finished, the final split time is adjusted to not include the pause times as well.

Warning

This behavior is not entirely optimal, as generally only the final split time is modified, while all other split times are left unmodified, which may not be what actually happened during the run.

pub fn switch_to_next_comparison(&mut self)

Switches the current comparison to the next comparison in the list.

pub fn switch_to_previous_comparison(&mut self)

Switches the current comparison to the previous comparison in the list.

pub fn current_attempt_duration(&self) -> TimeSpan

Returns the total duration of the current attempt. This is not affected by the start offset of the run. So if the start offset is -10s and the start() method was called 2s ago, the current time is -8s but the current attempt duration is 2s. If the timer is then however paused for 5s, the current attempt duration is still 2s. So the current attempt duration only counts the time the Timer Phase has actually been Running.

pub fn get_pause_time(&self) -> Option<TimeSpan>

Returns the total amount of time the current attempt has been paused for. None is returned if there have not been any pauses.

pub const fn is_game_time_initialized(&self) -> bool

Returns whether Game Time is currently initialized. Game Time automatically gets uninitialized for each new attempt.

pub fn initialize_game_time(&mut self)

Initializes Game Time for the current attempt. Game Time automatically gets uninitialized for each new attempt.

pub fn deinitialize_game_time(&mut self)

Deinitializes Game Time for the current attempt.

pub const fn is_game_time_paused(&self) -> bool

Returns whether the Game Timer is currently paused. If the Game Timer is not paused, it automatically increments similar to Real Time.

pub fn pause_game_time(&mut self)

Pauses the Game Timer such that it doesn’t automatically increment similar to Real Time.

pub fn resume_game_time(&mut self)

Resumes the Game Timer such that it automatically increments similar to Real Time, starting from the Game Time it was paused at.

pub fn set_game_time(&mut self, game_time: TimeSpan)

Sets the Game Time to the time specified. This also works if the Game Time is paused, which can be used as a way of updating the Game Timer periodically without it automatically moving forward. This ensures that the Game Timer never shows any time that is not coming from the game.

pub fn loading_times(&self) -> TimeSpan

Accesses the loading times. Loading times are defined as Game Time - Real Time.

pub fn set_loading_times(&mut self, time: TimeSpan)

Instead of setting the Game Time directly, this method can be used to just specify the amount of time the game has been loading. The Game Time is then automatically determined by Real Time - Loading Times.

pub fn set_custom_variable<N, V>(&mut self, name: N, value: V)where
    N: PopulateString,
    V: PopulateString,

Sets the value of a custom variable with the name specified. If the variable does not exist, a temporary variable gets created that will not be stored in the splits file.

Trait Implementations

impl Clone for Timer

fn clone(&self) -> Timer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Timer

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

Formats the value using the given formatter.

impl TotalPlaytime for Timer

fn total_playtime(&self) -> TimeSpan

Calculates the total playtime.