S-Lang Run-Time Library Reference: Version 2.0.4: Stack Functions

Next Previous Contents

## 21. Stack Functions

## 21.1 dup

Synopsis

  Duplicate the value at the top of the stack

Usage

  `dup ()`

Description

  This function returns an exact duplicate of the object on top of the stack. For some objects such as arrays or structures, it creates a new reference to the object. However, for simple scalar S-Lang types such as strings, integers, and doubles, it creates a new copy of the object.

See Also

  `pop, typeof`

## 21.2 exch

Synopsis

  Exchange two items on the stack

Usage

  `exch ()`

Description

  The `exch` swaps the two top items on the stack.

See Also

  `pop, _stk_reverse, _stk_roll`

## 21.3 pop

Synopsis

  Discard an item from the stack

Usage

  `pop ()`

Description

  The `pop` function removes the top item from the stack.

See Also

  `_pop_n, __pop_args`

## 21.4 __pop_args

Synopsis

  Remove n function arguments from the stack

Usage

  `args = __pop_args(Integer_Type n)`

Description

  This function, together with the companion function `__push_args`, is useful for creating a function that takes a variable number of arguments, as well as passing the arguments of one function to another function.

  `__pop_args` removes the specified number of values from the stack and returns them as an array of structures of the corresponding length. Each structure in the array consists of a single field called `value`, which represents the value of the argument.

Example

  Consider the following function. It prints all its arguments to `stdout` separated by spaces:

  > `

  >         define print_args ()
  >         {
  >            variable i;
  >            variable args = __pop_args (_NARGS);

  >            for (i = 0; i < _NARGS; i++)
  >              {
  >                 () = fputs (string (args[i].value), stdout);
  >                 () = fputs (" ", stdout);
  >              }
  >            () = fputs ("\n", stdout);
  >            () = fflush (stdout);
  >         }

  > `

  Now consider the problem of defining a function called `ones` that returns a multi-dimensional array with all the elements set to 1. For example, `ones(10)` should return a 1-d array of 10 ones, whereas `ones(10,20)` should return a 10x20 array.

  > `

  >         define ones ()
  >         {
  >           !if (_NARGS) return 1;
  >           variable a;

  >           a = __pop_args (_NARGS);
  >           return @Array_Type (Integer_Type, [__push_args (a)]) + 1;
  >         }

  > `

  Here, `__push_args` was used to push the arguments passed to the `ones` function onto the stack to be used when dereferencing `Array_Type`.
See Also

  `__push_args, typeof, _pop_n`

## 21.5 _pop_n

Synopsis

  Remove objects from the stack

Usage

  `_pop_n (Integer_Type n);`

Description

  The `_pop_n` function removes the specified number of objects from the top of the stack.

See Also

  `_stkdepth, pop`

## 21.6 _print_stack

Synopsis

  Print the values on the stack.

Usage

  `_print_stack ()`

Description

  This function dumps out what is currently on the S-Lang stack. It does not alter the stack and it is usually used for debugging purposes.

See Also

  `_stkdepth, string, message`

## 21.7 __push_args

Synopsis

  Remove n function arguments onto the stack

Usage

  `__push_args (Struct_Type args);`

Description

  This function together with the companion function `__pop_args` is useful for the creation of functions that take a variable number of arguments. See the description of `__pop_args` for more information.

See Also

  `__pop_args, typeof, _pop_n`

## 21.8 _stkdepth

Usage

  `Get the number of objects currently on the stack`

Synopsis

  Integer_Type _stkdepth ()

Description

  The `_stkdepth` function returns number of items on the stack.

See Also

  `_print_stack, _stk_reverse, _stk_roll`

## 21.9 _stk_reverse

Synopsis

  Reverse the order of the objects on the stack

Usage

  `_stk_reverse (Integer_Type n)`

Description

  The `_stk_reverse` function reverses the order of the top `n` items on the stack.

See Also

  `_stkdepth, _stk_roll`

## 21.10 _stk_roll

Synopsis

  Roll items on the stack

Usage

  `_stk_roll (Integer_Type n)`

Description

  This function may be used to alter the arrangement of objects on the stack. Specifically, if the integer `n` is positive, the top `n` items on the stack are rotated up. If `n` is negative, the top `abs(n)` items on the stack are rotated down.

Example

  If the stack looks like:

  > `

  >         item-0
  >         item-1
  >         item-2
  >         item-3

  > `

  where `item-0` is at the top of the stack, then `_stk_roll(-3)` will change the stack to:

  > `

  >         item-2
  >         item-0
  >         item-1
  >         item-3

  > `

Notes

  This function only has an effect if `abs(n) > 1`.

See Also

  `_stkdepth, _stk_reverse, _pop_n, _print_stack`

Next Previous Contents