\function{__pop_args} \synopsis{Remove n function arguments from the stack} \usage{variable args = __pop_args(Integer_Type n);} \description This function together with the companion function \var{__push_args} is useful for passing the arguments of a function to another function. \var{__pop_args} returns an array of \var{n} structures with a single structure field called \var{value}, which represents the value of the argument. \example Consider the following \var{print} function. It prints all its arguments to \var{stdout} separated by spaces: #v+ define print () { 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); } #v- Now consider the problem of defining a function called \var{ones} that returns a multi-dimensional array with all the elements set to 1. For example, \exmp{ones(10)} should return a 1-d array of ones, whereas \exmp{ones(10,20)} should return a 10x20 array. #v+ define ones () { !if (_NARGS) return 1; variable a; a = __pop_args (_NARGS); return @Array_Type (Integer_Type, [__push_args (a)]) + 1; } #v- Here, \var{__push_args} was used to push on the arguments passed to the \var{ones} function onto the stack to be used when dereferencing \var{Array_Type}. \seealso{__push_args, typeof, _pop_n} \done \function{__push_args} \synopsis{Remove n function arguments onto the stack} \usage{__push_args (Struct_Type args);} \description This function together with the companion function \var{__pop_args} is useful for passing the arguments of one function to another. See the desription of \var{__pop_args} for more information. \seealso{__pop_args, typeof, _pop_n} \done \function{_pop_n} \synopsis{Remove objects from the stack} \usage{_pop_n (Integer_Type n);} \description The \var{_pop_n} function pops \var{n} objects from the top of the stack. \example #v+ define add3 () { variable x, y, z; if (_NARGS != 3) { _pop_n (_NARGS); error ("add3: Expecting 3 arguments"); } (x, y, z) = (); return x + y + z; } #v- \seealso{_stkdepth, pop} \done \function{_print_stack} \synopsis{print the values on the stack.} \usage{_print_stack ()} \description This function dumps out what is currently on the \slang. It does not alter the stack and it is usually used for debugging purposes. \seealso{_stkdepth, string} \done \function{_stk_reverse} \synopsis{Reverse the order of the objects on the stack.} \usage{_stk_reverse (Integer_Type n)} \description The \var{_stk_reverse} function reverses the order of the top \var{n} items on the stack. \seealso{_stkdepth, _stk_roll} \done \function{_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 \var{n} is positive, the top \var{n} items on the stack are rotated up. If \var{n} is negative, the top \var{abs(n)} items on the stack are rotated down. \example If the stack looks like: #v+ item-0 item-1 item-2 item-3 #v- where \exmp{item-0} is at the top of the stack, then \exmp{_stk_roll(-3)} will change the stack to: #v+ item-2 item-0 item-1 item-3 #v- \notes This function only has an effect for \exmp{abs(n) > 1}. \seealso{_stkdepth, _stk_reverse, _pop_n, _print_stack} \done \function{_stkdepth} \usage{Get the number of objects currently on the stack.} \synopsis{Integer_Type _stkdepth ()} \description The \var{_stkdepth} function returns number of items on stack prior to the call of \var{_stkdepth}. \seealso{_print_stack, _stk_reverse, _stk_roll} \done \function{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 array. However, for simple scalar S-Lang types such as strings, integers, and doubles, it creates a new copy of the object. \seealso{pop, typeof} \done \function{exch} \synopsis{Exchange two items on the stack} \usage{exch ()} \description The \var{exch} swaps the two top items on the stack. \seealso{pop, _stk_reverse, _stk_roll} \done \function{pop} \synopsis{Discard an item from the stack} \usage{pop ()} \description The \var{pop} function removes the top item from the stack. \seealso{_pop_n} \done