Duplicate the value at the top of the stack
dup ()
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.
pop, typeof
Exchange two items on the stack
exch ()
The exch
swaps the two top items on the stack.
pop, _stk_reverse, _stk_roll
Discard an item from the stack
pop ()
The pop
function removes the top item from the stack.
_pop_n, __pop_args
Remove n function arguments from the stack
args = __pop_args(Integer_Type n)
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.
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
.
__push_args, typeof, _pop_n
Remove objects from the stack
_pop_n (Integer_Type n);
The _pop_n
function removes the specified number of objects
from the top of the stack.
_stkdepth, pop
Print the values on the stack.
_print_stack ()
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.
_stkdepth, string, message
Remove n function arguments onto the stack
__push_args (Struct_Type args);
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.
__pop_args, typeof, _pop_n
Get the number of objects currently on the stack
Integer_Type _stkdepth ()
The _stkdepth
function returns number of items on the stack.
_print_stack, _stk_reverse, _stk_roll
Reverse the order of the objects on the stack
_stk_reverse (Integer_Type n)
The _stk_reverse
function reverses the order of the top
n
items on the stack.
_stkdepth, _stk_roll
Roll items on the stack
_stk_roll (Integer_Type n)
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.
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
This function only has an effect if abs(n) > 1
.
_stkdepth, _stk_reverse, _pop_n, _print_stack