spsUtil (version 0.2.2.1)

historyStack: history stack structure and methods

Description

Some methods for a history stack data structure. It can store history of certain repeating actions. For example, building the back-end of a file/image editor, allow undo/redo actions.

Value

an R6 class object

Methods

Public methods

• historyStack$new()

• historyStack$clear()

• historyStack$get()

• historyStack$getPos()

• historyStack$status()

• historyStack$forward()

• historyStack$backward()

• historyStack$add()

• historyStack$clone()

---

Method new()

create the history object

Usage

historyStack$new(items = NULL, limit = 25, verbose = TRUE)

Arguments

items

list, initial history step items to store on start

limit

int, how many history steps can be stored in the stack, default 25 steps

verbose

bool, print some verbose message?

---

Method clear()

clear all history steps in the stack

Usage

historyStack$clear()

---

Method get()

retrieve the history from a certain position in the stack

Usage

historyStack$get(pos = private$pos)

Arguments

pos

int, which position to get the history from, default is current step.

---

Method getPos()

get current step position in the history stack

Usage

historyStack$getPos()

---

Method status()

print out some status of the stack

Usage

historyStack$status()

Returns

returns a list of `pos`: current position (int); `len`: current length of the history stack (int); `limit`: history stack storing limit (int); `first`: is current step position the first of the stack (bool); `last`: is current step position the last of the stack (bool)

---

Method forward()

move one step forward in the history stack and return item in that position

Usage

historyStack$forward()

---

Method backward()

move one step backward in the history stack and return item in that position

Usage

historyStack$backward()

---

Method add()

Add an item to the history and move one step forward

Usage

historyStack$add(item)

Arguments

item

any object you want to add to the stack. Everything store in the item will be moved into a list, so even if item may be something length > 1, it will still be treated as a single item and single history step.

Details

If current position is not the last position, and when a new step item is added to the stack, all history records (items) after current position will be removed before adding the new history item.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

historyStack$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Details

1. If the stack reaches the limit and you are trying to add more history, the first history step will be removed , all history will be shift to the left by one step and finally add the new step to the end. 2. When history returning methods are called, like the `get()`, `forward()`, `backward()` methods, it will not directly return the item saved, but a list, contains 4 components: 1. item, the actual item stored; 2. pos, current posistion value; 3. first, boolean value, if this history is stored on the first position of stack; 4. last, boolean value, if this history is stored on the last position of stack; 3. If you `forward` beyond last step, or `backward` to prior the first step, it will be stopped with errors. 4. Starting history stack with no initial history will return a special stack, where the `pos = 0`, `len = 0`, `first = TRUE`, and `last = TRUE`. This means you cannot move forward or backward. When you `get()`, it will be an empty list `list()`. After adding any new history, `pos` will never be 0 again, it will always be a larger than 0 value.

Examples

his <- historyStack$new()
# add some history
his$add(1)
his$add(2)
his$add(3)
his$add(4)
his$add(5)
# check status
his$status()
# get item at current history position
his$get()
# go back to previous step
his$backward()
# going back to step 2
his$backward()
his$backward()
# going forward 1 step tp step 3
his$forward()
# check current status
his$status()
# adding a new step at position 3 will remove the old step 4,5 before adding
his$add("new 4")
# only 3 steps + 1 new step = 4 steps left
his$status()