OpenEuphoria

8.33 Stack

8.33.1 Constants

8.33.2 Stack types

8.33.2.1 FIFO

include std/stack.e
namespace stack
public constant FIFO

FIFO: like people standing in line: first item in is first item out

8.33.2.2 FILO

include std/stack.e
namespace stack
public constant FILO

FILO: like for a stack of plates : first item in is last item out

8.33.3 Types

8.33.3.1 stack

include std/stack.e
namespace stack
public type stack(object obj_p)

A stack is a sequence of objects with some internal data.

8.33.4 Routines

8.33.4.1 new

include std/stack.e
namespace stack
public function new(integer typ = FILO)

Create a new stack.

Parameters:

1. stack_type : an integer, defining the semantics of the stack. The default is FILO.

Returns:

An empty stack, note that the variable storing the stack must not be an integer. The resources allocated for the stack will be automatically cleaned up if the reference count of the returned value drops to zero, or if passed in a call to delete.

Comments:

There are two sorts of stacks, designated by the types FIFO and FILO:

• A FIFO stack is one where the first item to be pushed is popped first. People standing in queue form a FIFO stack.
• A FILO stack is one where the item pushed last is popped first. A column of coins is of the FILO kind.

See Also:

is_empty

8.33.4.2 is_empty

include std/stack.e
namespace stack
public function is_empty(stack sk)

Determine whether a stack is empty.

Parameters:

1. sk : the stack being queried.

Returns:

An integer, 1 if the stack is empty, else 0.

See Also:

size

8.33.4.3 size

include std/stack.e
namespace stack
public function size(stack sk)

Returns how many elements a stack has.

Parameters:

1. sk : the stack being queried.

Returns:

An integer, the number of elements in sk.

8.33.4.4 at

include std/stack.e
namespace stack
public function at(stack sk, integer idx = 1)

Fetch a value from the stack without removing it from the stack.

Parameters:

1. sk : the stack being queried
2. idx : an integer, the place to inspect. The default is 1 (top item).

Returns:

An object, the idx-th item of the stack.

Errors:

If the supplied value of idx does not correspond to an existing element, an error occurs.

Comments:

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

idx can be less than 1, in which case it refers relative to the end item. Thus, 0 stands for the end element.

Example 1:

stack sk = new(FILO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)

at(sk, 0)  --> 5
at(sk, -1) --> "abc"
at(sk, 1)  --> 2.3
at(sk, 2)  --> "abc"

Example 2:

stack sk = new(FIFO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)
at(sk, 0)  --> 2.3
at(sk, -1) --> "abc"
at(sk, 1)  --> 5
at(sk, 2)  --> "abc"

See Also:

size, top, peek_top, peek_end

8.33.4.5 push

include std/stack.e
namespace stack
public procedure push(stack sk, object value)

Adds something to a stack.

Parameters:

1. sk : the stack to augment
2. value : an object, the value to push.

Comments:

value appears at the end of FIFO stacks and the top of FILO stacks. The size of the stack increases by one.

Example 1:

stack sk = new(FIFO)

push(sk,5)
push(sk,"abc")
push(sk, 2.3)
top(sk)  --> 5
last(sk) --> 2.3

Example 2:

stack sk = new(FILO)

push(sk,5)
push(sk,"abc")
push(sk, 2.3)
top(sk)  --> 2.3
last(sk) --> 5

See Also:

pop, top

8.33.4.6 top

include std/stack.e
namespace stack
public function top(stack sk)

Retrieve the top element on a stack.

Parameters:

1. sk : the stack to inspect.

Returns:

An object, the top element on a stack.

Comments:

This call is equivalent to at(sk,1).

Example 1:

stack sk = new(FILO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)

top(sk) --> 2.3

Example 1:

stack sk = new(FIFO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)

top(sk) --> 5

See Also:

at, pop, peek_top, last

8.33.4.7 last

include std/stack.e
namespace stack
public function last(stack sk)

Retrieve the end element on a stack.

Parameters:

1. sk : the stack to inspect.

Returns:

An object, the end element on a stack.

Comments:

This call is equivalent to at(sk,0).

Example 1:

stack sk = new(FILO)

push(sk,5)
push(sk,"abc")
push(sk, 2.3)

last(sk) --> 5

Example 2:

stack sk = new(FIFO)

push(sk,5)
push(sk,"abc")
push(sk, 2.3)

last(sk) --> 2.3

See Also:

at, pop, peek_end, top

8.33.4.8 pop

include std/stack.e
namespace stack
public function pop(stack sk, integer idx = 1)

Removes an object from a stack.

Parameters:

1. sk : the stack to pop
2. idx : integer. The n-th item to pick from the stack. The default is 1.

Returns:

An item, from the stack, which is also removed from the stack.

Errors:

• If the stack is empty, an error occurs.
• If the idx is greater than the number of items in the stack, an error occurs.

Comments:

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

When idx is omitted the 'top' of the stack is removed and returned. When idx is supplied, it represents the N-th item from the top to be removed and returned. Thus an idx of 2 returns the 2nd item from the top, a value of 3 returns the 3rd item from the top, etc ...

Example 1:

stack sk = new(FIFO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? size(sk) -- 3
? pop(sk) -- 1
? size(sk) -- 2
? pop(sk) -- 2
? size(sk) -- 1
? pop(sk) -- 3
? size(sk) -- 0
? pop(sk) -- *error*

Example 2:

stack sk = new(FILO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? size(sk) -- 3
? pop(sk) -- 3
? size(sk) -- 2
? pop(sk) -- 2
? size(sk) -- 1
? pop(sk) -- 1
? size(sk) -- 0
? pop(sk) -- *error*

Example 3:

stack sk = new(FILO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
push(sk, 4)
-- stack contains {1,2,3,4} (oldest to newest)
? size(sk) -- 4
? pop(sk, 2) -- Pluck out the 2nd newest item .. 3
? size(sk) -- 3 
-- stack now contains {1,2,4}

Example 4:

stack sk = new(FIFO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
push(sk, 4)
-- stack contains {1,2,3,4} (oldest to newest)
? size(sk) -- 4
? pop(sk, 2) -- Pluck out the 2nd oldest item .. 2
? size(sk) -- 3 
-- stack now contains {1,3,4}

See Also:

push, top, is_empty

8.33.4.9 peek_top

include std/stack.e
namespace stack
public function peek_top(stack sk, integer idx = 1)

Gets an object, relative to the top, from a stack.

Parameters:

1. sk : the stack to get from.
2. idx : integer. The n-th item to get from the stack. The default is 1.

Returns:

An item, from the stack, which is not removed from the stack.

Errors:

• If the stack is empty, an error occurs.
• If the idx is greater than the number of items in the stack, an error occurs.

Comments:

This is identical to pop except that it does not remove the item.

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

When idx is omitted the 'top' of the stack is returned. When idx is supplied, it represents the N-th item from the top to be returned. Thus an idx of 2 returns the 2nd item from the top, a value of 3 returns the 3rd item from the top, etc ...

Example 1:

stack sk = new(FIFO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? peek_top(sk) -- 1
? peek_top(sk,2) -- 2
? peek_top(sk,3) -- 3
? peek_top(sk,4) -- *error*
? peek_top(sk, size(sk)) -- 3 (end item)

Example 2:

stack sk = new(FILO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? peek_top(sk) -- 3
? peek_top(sk,2) -- 2
? peek_top(sk,3) -- 1
? peek_top(sk,4) -- *error*
? peek_top(sk, size(sk)) -- 1 (end item)

See Also:

pop, top, is_empty, size, peek_end

8.33.4.10 peek_end

include std/stack.e
namespace stack
public function peek_end(stack sk, integer idx = 1)

Gets an object, relative to the end, from a stack.

Parameters:

1. sk : the stack to get from.
2. idx : integer. The n-th item from the end to get from the stack. The default is 1.

Returns:

An item, from the stack, which is not removed from the stack.

Errors:

• If the stack is empty, an error occurs.
• If the idx is greater than the number of items in the stack, an error occurs.

Comments:

• For FIFO stacks (queues), the end item is the newest item in the stack.
• For FILO stacks, the end item is the oldest item in the stack.

When idx is omitted the 'end' of the stack is returned. When idx is supplied, it represents the N-th item from the end to be returned. Thus an idx of 2 returns the 2nd item from the end, a value of 3 returns the 3rd item from the end, etc ...

Example 1:

stack sk = new(FIFO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? peek_end(sk) -- 3
? peek_end(sk,2) -- 2
? peek_end(sk,3) -- 1
? peek_end(sk,4) -- *error*
? peek_end(sk, size(sk)) -- 3 (top item)

Example 2:

stack sk = new(FILO)
push(sk, 1)
push(sk, 2)
push(sk, 3)
? peek_end(sk) -- 1
? peek_end(sk,2) -- 2
? peek_end(sk,3) -- 3
? peek_end(sk,4) -- *error*
? peek_end(sk, size(sk)) -- 3 (top item)

See Also:

pop, top, is_empty, size, peek_top

8.33.4.11 swap

include std/stack.e
namespace stack
public procedure swap(stack sk)

Swap the top two elements of a stack

Parameters:

1. sk : the stack to swap.

Returns:

A copy, of the original stack, with the top two elements swapped.

Comments:

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

Errors:

If the stack has less than two elements, an error occurs.

Example 1:

stack sk = new(FILO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)
push(sk, "")

? peek_top(sk, 1) --> ""
? peek_top(sk, 2) --> 2.3

swap(sk)

? peek_top(sk, 1) --> 2.3
? peek_top(sk, 2) --> ""

Example 2:

stack sk = new(FIFO)

push(sk, 5)
push(sk, "abc")
push(sk, 2.3)
push(sk, "")

peek_top(sk, 1) --> 5
peek_top(sk, 2) --> "abc"

swap(sk)

peek_top(sk, 1) --> "abc"
peek_top(sk, 2) --> 5

8.33.4.12 dup

include std/stack.e
namespace stack
public procedure dup(stack sk)

Repeat the top element of a stack.

Parameters:

1. sk : the stack.

Side effects:

The value of top() is pushed onto the stack, thus the stack size grows by one.

Comments:

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

Errors:

If the stack has no elements, an error occurs.

Example 1:

stack sk = new(FILO)

push(sk,5)
push(sk,"abc")
push(sk, "")

dup(sk)

peek_top(sk,1) --> ""
peek_top(sk,2) --> "abc"
size(sk)       --> 3

dup(sk)

peek_top(sk,1) --> ""
peek_top(sk,2) --> ""
peek_top(sk,3) --> "abc"
size(sk)       --> 4

Example 1:

stack sk = new(FIFO)

push(sk, 5)
push(sk, "abc")
push(sk, "")

dup(sk)

peek_top(sk, 1) --> 5
peek_top(sk, 2) --> "abc"
size(sk)        --> 3

dup(sk)

peek_top(sk, 1) --> 5
peek_top(sk, 2) --> 5
peek_top(sk, 3) --> "abc"
size(sk)        --> 4

8.33.4.13 set

include std/stack.e
namespace stack
public procedure set(stack sk, object val, integer idx = 1)

Update a value on the stack

Parameters:

1. sk : the stack being queried
2. val : an object, the value to place on the stack
3. idx : an integer, the place to inspect. The default is 1 (the top item)

Errors:

If the supplied value of idx does not correspond to an existing element, an error occurs.

Comments:

• For FIFO stacks (queues), the top item is the oldest item in the stack.
• For FILO stacks, the top item is the newest item in the stack.

idx can be less than 1, in which case it refers to an element relative to the end of the stack. Thus, 0 stands for the end element.

See Also:

size, top

8.33.4.14 clear

include std/stack.e
namespace stack
public procedure clear(stack sk)

Wipe out a stack.

Parameters:

1. sk : the stack to clear.

Side effect:

The stack contents is emptied.

See Also:

new, is_empty