Struct undo::History

pub struct History<R> { /* fields omitted */ }

A history of commands.

Unlike Record which maintains a linear undo history, History maintains an undo tree containing every edit made to the receiver. By switching between different branches in the tree, the user can get to any previous state of the receiver.

Examples

#[derive(Debug)]
struct Add(char);

impl Command<String> for Add {
    fn apply(&mut self, s: &mut String) -> undo::Result {
        s.push(self.0);
        Ok(())
    }

    fn undo(&mut self, s: &mut String) -> undo::Result {
        self.0 = s.pop().ok_or("`s` is empty")?;
        Ok(())
    }
}

fn main() -> undo::Result {
    let mut history = History::default();
    history.apply(Add('a'))?;
    history.apply(Add('b'))?;
    history.apply(Add('c'))?;
    let abc = history.root();
    assert_eq!(history.as_receiver(), "abc");
    history.go_to(abc, 1).unwrap()?;
    assert_eq!(history.as_receiver(), "a");
    history.apply(Add('f'))?;
    history.apply(Add('g'))?;
    assert_eq!(history.as_receiver(), "afg");
    history.go_to(abc, 3).unwrap()?;
    assert_eq!(history.as_receiver(), "abc");
    Ok(())
}

Methods

impl<R> History<R>

pub fn new(
    receiver: impl Into<R>
) -> History<R>

Returns a new history.

pub fn builder() -> HistoryBuilder<R>

Returns a builder for a history.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more commands.

Panics

Panics if the new capacity overflows usize.

pub fn capacity(&self) -> usize

Returns the capacity of the history.

pub fn len(&self) -> usize

Returns the number of commands in the current branch of the history.

pub fn is_empty(&self) -> bool

Returns true if the current branch of the history is empty.

pub fn limit(&self) -> usize

Returns the limit of the history.

pub fn set_limit(&mut self, limit: usize) -> usize

Sets the limit of the history and returns the new limit.

If this limit is reached it will start popping of commands at the beginning of the history when new commands are applied. No limit is set by default which means it may grow indefinitely.

If limit < len the first commands will be removed until len == limit. However, if the current active command is going to be removed, the limit is instead adjusted to len - active so the active command is not removed.

Panics

Panics if limit is 0.

pub fn connect(
    &mut self,
    f: impl FnMut(Signal) + Send + Sync + 'static
) -> Option<impl FnMut(Signal) + Send + Sync + 'static> where
    R: 'static, 

Sets how the signal should be handled when the state changes.

The previous signal handler is returned if it exists.

pub fn can_undo(&self) -> bool

Returns true if the history can undo.

pub fn can_redo(&self) -> bool

Returns true if the history can redo.

pub fn set_saved(&mut self, saved: bool)

Marks the receiver as currently being in a saved or unsaved state.

pub fn is_saved(&self) -> bool

Returns true if the receiver is in a saved state, false otherwise.

pub fn revert(&mut self) -> Option<Result> where
    R: 'static, 

Revert the changes done to the receiver since the saved state.

pub fn root(&self) -> usize

Returns the current branch.

pub fn current(&self) -> usize

Returns the position of the current command.

pub fn clear(&mut self)

Removes all commands from the history without undoing them.

pub fn apply(
    &mut self,
    command: impl Command<R> + 'static
) -> Result where
    R: 'static, 

Pushes the command to the top of the history and executes its apply method.

Errors

If an error occur when executing apply the error is returned and the state of the history is left unchanged.

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

Calls the undo method for the active command and sets the previous one as the new active one.

Errors

If an error occur when executing undo the error is returned and the state of the history is left unchanged.

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

Calls the redo method for the active command and sets the next one as the new active one.

Errors

If an error occur when executing redo the error is returned and the state of the history is left unchanged.

pub fn go_to(&mut self, branch: usize, current: usize) -> Option<Result> where
    R: 'static, 

Repeatedly calls undo or redo until the command in branch at current is reached.

Errors

If an error occur when executing undo or redo the error is returned and the state of the history is left unchanged.

pub fn time_travel<Tz: TimeZone>(&mut self, to: &DateTime<Tz>) -> Option<Result>

Go back or forward in time.

pub fn extend<C: Command<R> + 'static>(
    &mut self,
    commands: impl IntoIterator<Item = C>
) -> Result where
    R: 'static, 

Applies each command in the iterator.

Errors

If an error occur when executing apply the error is returned and the remaining commands in the iterator are discarded.

pub fn checkpoint(&mut self) -> Checkpoint<History<R>, R>

Returns a checkpoint.

pub fn queue(&mut self) -> Queue<History<R>, R>

Returns a queue.

pub fn as_receiver(&self) -> &R

Returns a reference to the receiver.

pub fn as_mut_receiver(&mut self) -> &mut R

Returns a mutable reference to the receiver.

This method should only be used when doing changes that should not be able to be undone.

pub fn into_receiver(self) -> R

Consumes the history, returning the receiver.

Trait Implementations

impl<R> AsRef<R> for History<R>

fn as_ref(&self) -> &R

Performs the conversion.

impl<R> AsMut<R> for History<R>

fn as_mut(&mut self) -> &mut R

Performs the conversion.

impl<R> From<R> for History<R>

fn from(receiver: R) -> History<R>

Performs the conversion.

impl<R> From<Record<R>> for History<R>

fn from(record: Record<R>) -> History<R>

Performs the conversion.

impl<R> From<History<R>> for Record<R>

fn from(history: History<R>) -> Record<R>

Performs the conversion.

impl<R: Default> Default for History<R>

fn default() -> History<R>

Returns the "default value" for a type.

impl<R: Debug> Debug for History<R>

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

Formats the value using the given formatter.