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.
Exchange two items on the stack
exch ()
The exch swaps the two top items on the stack.
Discard an item from the stack
pop ()
The pop function removes the top item from the stack.
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);
}
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;
}
__push_args was used to push the arguments passed to
the ones function onto the stack to be used when dereferencing
Array_Type.
This function has been superseded by the __pop_list function,
which returns the objects as a list instead of an array of structures.
Convert items on the stack to a List_Type
List_Type = __pop_list (Int_Type n)
This function removes a specified number of items from the stack and converts returns them in the form of a list.
define print_args ()
{
variable list = __pop_list (_NARGS);
variable i;
_for i (0, length(list)-1, 1)
{
vmessage ("arg[%d]: %S", i, list[i]);
}
}
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.
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.
Move 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.
This function has been superseded by the __push_list function.
Push the elements of a list to the stack
__push_list (List_Type list)
This function pushes the elements of a list to the stack.
private define list_to_array (list)
{
return [__push_list (list)];
}
Get the number of objects currently on the stack
Integer_Type _stkdepth ()
The _stkdepth function returns number of items on the stack.
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.
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
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.