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