Typed-Stack: A Typed Racket stack library🔗ℹ

Lehi Toskin

typed-stack is a stack implementation written in Typed Racket that contains many different procedures to operate on the stack.

struct
(struct Stack (contents)
#:mutable)
contents : (Listof A)

This is the basis of the library. The core is a list that gets manipulated through the various procedures. The "top" or "beginning" of the stack refers to the first element of the contents list, while the "bottom" or "end" of the stack refers to the last element of the contents list; items on the left side of the list are the newest and the items on the right side are the oldest.

1 Procedures🔗ℹ

Almost every procedure has two forms: one that mutates state and a functional counterpart. Functional versions of the procedures will return the stack as it was modified while the procedures that mutate state will return Void.

procedure
(make-stack v ...) → (Stack A)
v : Any

Returns a stack of type A containing the values v.

procedure
(empty-stack) → (Stack Any)

Returns an empty stack.

procedure
(stack->list stk) → (Listof A)
stk : (Stack A)

Takes a stack and returns a list.

procedure
(stack->string stk) → String
stk : (Stack A)

Takes a stack and returns a string of the contents of the stack, starting from the bottom.

procedure
(stack-empty? stk) → Boolean
stk : (Stack A)

Determines if the given stack is empty.

procedure
(stack-length stk) → Nonnegative-Integer
stk : (Stack A)

Returns the length of the stack.

procedure
(stack=? stk1 stk2) → Boolean
stk1 : (Stack A)
stk2 : (Stack B)

Checks if both stacks are equal?.

procedure
(top stk) → A
stk : (Stack A)

Returns the item at the top of the stack. Will fail if the stack is empty.

procedure
(in-stack stk) → (Sequenceof A)
stk : (Stack A)

Returns a sequence to iterate over the items in the stack from top to bottom.

procedure
(pop stk) → (Values A (Stack A))
stk : (Stack A)
procedure
(pop! stk) → A
stk : (Stack A)

Pops the top item of the stack. pop will return the values of the top of the stack as well as the remainder of the stack. pop! will only return the top.

procedure
(push stk val) → (Stack A)
  stk : (Stack A)
  val : A
procedure
(push! stk val) → Void
  stk : (Stack A)
  val : A

Pushes an item to the top of the stack.

procedure
(push* stk val ...) → (Stack A)
  stk : (Stack A)
  val : A
procedure
(push*! stk val ...) → Void
  stk : (Stack A)
  val : A

Pushes a number of items to the stack at once. They are evaluated from right to left and appear in the stack as-entered.

procedure
(push-dup stk) → (Stack A)
stk : (Stack A)
procedure
(push-dup! stk) → Void
stk : (Stack A)

Pushes a copy of the top item onto the stack. Will fail if the stack is empty.

procedure
(pop-all! stk) → Void
stk : (Stack A)

Pops all items from the stack.

procedure
(swap stk) → (Stack A)
stk : (Stack A)
procedure
(swap! stk) → Void
stk : (Stack A)

Swaps the top two items in the stack. Will fail if the stack is empty.

procedure
(push-over stk) → (Stack A)
stk : (Stack A)
procedure
(push-over! stk) → Void
stk : (Stack A)

Pushes a copy of the second topmost item onto the stack.

procedure
(rotate stk) → (Stack A)
stk : (Stack A)
procedure
(rotate! stk) → Void
stk : (Stack A)

Rotates the top three items in the stack downwards such that (Stack '(3 2 1)) becomes (Stack '(1 3 2)).

procedure
(reverse-rotate stk) → (Stack A)
stk : (Stack A)
procedure
(reverse-rotate! stk) → Void
stk : (Stack A)

Rotates the top three items in the stack upwards such that (stack '(3 2 1)) becomes (stack '(2 1 3)).

procedure
(pop-nip stk) → (Stack A)
stk : (Stack A)
procedure
(pop-nip! stk) → Void
stk : (Stack A)

Removes the second topmost item from the stack.

procedure
(push-tuck stk) → (Stack A)
stk : (Stack A)
procedure
(push-tuck! stk) → Void
stk : (Stack A)

Swaps the top two items in the stack and then pushes a copy of the former top item.

procedure
(push-pick stk i) → (Stack A)
  stk : (Stack A)
  i : Nonnegative-Integer
procedure
(push-pick! stk i) → Void
  stk : (Stack A)
  i : Nonnegative-Integer

Pushes a copy of the specified index to the top of the stack. The index starts at the top of the stack.

procedure
(roll stk i) → (Stack A)
  stk : (Stack A)
  i : Nonnegative-Integer
procedure
(roll! stk i) → Void
  stk : (Stack A)
  i : Nonnegative-Integer

Removes the item from the stack at the given index and pushes it to the top of the stack. The index starts at the top of the stack.

2 License🔗ℹ

The code in this package and this documentation is under the BSD 3-clause.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this

list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,

this list of conditions and the following disclaimer in the documentation

and/or other materials provided with the distribution.

* Neither the name of typed-stack nor the names of its

contributors may be used to endorse or promote products derived from

this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.