OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.33 Map (Hash Table) | Up: 8 API Reference | 8.35 Scientific Notation Parsing > | 9 Release Notes >>

## 8.34 Stack

### 8.34.1 Constants

### 8.34.2 Stack types

#### 8.34.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.34.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.34.3 Types

#### 8.34.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.34.4 Routines

#### 8.34.4.1 new

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

creates 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.34.4.2 is_empty

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

determines 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.34.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.34.4.4 at

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

fetches 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.34.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.34.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 2:

    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.34.4.7 last

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

retrieves 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.34.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, and so on.

##### 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.34.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, and so on.

##### 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.34.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, and so on.

##### 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.34.4.11 swap

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

swaps 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.34.4.12 dup

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

repeats the top element of a stack.

##### Parameters:

1. `sk` : the stack.

##### 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.

##### Side Effect:

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

##### 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.34.4.13 set

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

updates 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 one, 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.34.4.14 clear

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

wipes out a stack.

##### Parameters:

1. `sk` : the stack to clear.

##### Side Effect:

The stack contents is emptied.

##### See Also:

new, is_empty

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.33 Map (Hash Table) | Up: 8 API Reference | 8.35 Scientific Notation Parsing > | 9 Release Notes >>