<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Stack Functions</TITLE>
<LINK HREF="slangfun-19.html" REL=next>
<LINK HREF="slangfun-17.html" REL=previous>
<LINK HREF="slangfun.html#toc18" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-19.html">Next</A>
<A HREF="slangfun-17.html">Previous</A>
<A HREF="slangfun.html#toc18">Contents</A>
<HR>
<H2><A NAME="s18">18. Stack Functions</A></H2>
<P>
<H2><A NAME="__pop_args"></A> <A NAME="ss18.1">18.1 <B>__pop_args</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove n function arguments from the stack
<DT><B> Usage </B><DD><P><CODE>variable args = __pop_args(Integer_Type n);</CODE>
<DT><B> Description </B><DD><P>This function together with the companion function <CODE>__push_args</CODE>
is useful for passing the arguments of a function to another function.
<CODE>__pop_args</CODE> returns an array of <CODE>n</CODE> structures with a
single structure field called <CODE>value</CODE>, which represents the value
of the argument.
<DT><B> Example </B><DD><P>Consider the following <CODE>print</CODE> function. It prints all its
arguments to <CODE>stdout</CODE> separated by spaces:
<BLOCKQUOTE><CODE>
<PRE>
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);
}
</PRE>
</CODE></BLOCKQUOTE>
Now consider the problem of defining a function called <CODE>ones</CODE>
that returns a multi-dimensional array with all the elements set to
1. For example, <CODE>ones(10)</CODE> should return a 1-d array of ones,
whereas <CODE>ones(10,20)</CODE> should return a 10x20 array.
<BLOCKQUOTE><CODE>
<PRE>
define ones ()
{
!if (_NARGS) return 1;
variable a;
a = __pop_args (_NARGS);
return @Array_Type (Integer_Type, [__push_args (a)]) + 1;
}
</PRE>
</CODE></BLOCKQUOTE>
Here, <CODE>__push_args</CODE> was used to push on the arguments passed to
the <CODE>ones</CODE> function onto the stack to be used when dereferencing
<CODE>Array_Type</CODE>.
<DT><B> See Also </B><DD><P><CODE>__push_args, typeof, _pop_n</CODE>
</DL>
<P>
<P>
<H2><A NAME="__push_args"></A> <A NAME="ss18.2">18.2 <B>__push_args</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove n function arguments onto the stack
<DT><B> Usage </B><DD><P><CODE>__push_args (Struct_Type args);</CODE>
<DT><B> Description </B><DD><P>This function together with the companion function <CODE>__pop_args</CODE>
is useful for passing the arguments of one function to another.
See the desription of <CODE>__pop_args</CODE> for more information.
<DT><B> See Also </B><DD><P><CODE>__pop_args, typeof, _pop_n</CODE>
</DL>
<P>
<P>
<H2><A NAME="_pop_n"></A> <A NAME="ss18.3">18.3 <B>_pop_n</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove objects from the stack
<DT><B> Usage </B><DD><P><CODE>_pop_n (Integer_Type n);</CODE>
<DT><B> Description </B><DD><P>The <CODE>_pop_n</CODE> function pops <CODE>n</CODE> objects from the top of the
stack.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
define add3 ()
{
variable x, y, z;
if (_NARGS != 3)
{
_pop_n (_NARGS);
error ("add3: Expecting 3 arguments");
}
(x, y, z) = ();
return x + y + z;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>_stkdepth, pop</CODE>
</DL>
<P>
<P>
<H2><A NAME="_print_stack"></A> <A NAME="ss18.4">18.4 <B>_print_stack</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>print the values on the stack.
<DT><B> Usage </B><DD><P><CODE>_print_stack ()</CODE>
<DT><B> Description </B><DD><P>This function dumps out what is currently on the <B>S-lang</B>. It does not
alter the stack and it is usually used for debugging purposes.
<DT><B> See Also </B><DD><P><CODE>_stkdepth, string</CODE>
</DL>
<P>
<P>
<H2><A NAME="_stk_reverse"></A> <A NAME="ss18.5">18.5 <B>_stk_reverse</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Reverse the order of the objects on the stack.
<DT><B> Usage </B><DD><P><CODE>_stk_reverse (Integer_Type n)</CODE>
<DT><B> Description </B><DD><P>The <CODE>_stk_reverse</CODE> function reverses the order of the top
<CODE>n</CODE> items on the stack.
<DT><B> See Also </B><DD><P><CODE>_stkdepth, _stk_roll</CODE>
</DL>
<P>
<P>
<H2><A NAME="_stk_roll"></A> <A NAME="ss18.6">18.6 <B>_stk_roll</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Roll items on the stack
<DT><B> Usage </B><DD><P><CODE>_stk_roll (Integer_Type n);</CODE>
<DT><B> Description </B><DD><P>This function may be used to alter the arrangement of objects on the
stack. Specifically, if the integer <CODE>n</CODE> is positive, the top
<CODE>n</CODE> items on the stack are rotated up. If
<CODE>n</CODE> is negative, the top <CODE>abs(n)</CODE> items on the stack are
rotated down.
<DT><B> Example </B><DD><P>If the stack looks like:
<BLOCKQUOTE><CODE>
<PRE>
item-0
item-1
item-2
item-3
</PRE>
</CODE></BLOCKQUOTE>
where <CODE>item-0</CODE> is at the top of the stack, then
<CODE>_stk_roll(-3)</CODE> will change the stack to:
<BLOCKQUOTE><CODE>
<PRE>
item-2
item-0
item-1
item-3
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>This function only has an effect for <CODE>abs(n) > 1</CODE>.
<DT><B> See Also </B><DD><P><CODE>_stkdepth, _stk_reverse, _pop_n, _print_stack</CODE>
</DL>
<P>
<P>
<H2><A NAME="_stkdepth"></A> <A NAME="ss18.7">18.7 <B>_stkdepth</B></A>
</H2>
<P>
<DL>
<DT><B> Usage </B><DD><P><CODE>Get the number of objects currently on the stack.</CODE>
<DT><B> Synopsis </B><DD><P>Integer_Type _stkdepth ()
<DT><B> Description </B><DD><P>The <CODE>_stkdepth</CODE> function returns number of items on stack prior
to the call of <CODE>_stkdepth</CODE>.
<DT><B> See Also </B><DD><P><CODE>_print_stack, _stk_reverse, _stk_roll</CODE>
</DL>
<P>
<P>
<H2><A NAME="dup"></A> <A NAME="ss18.8">18.8 <B>dup</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Duplicate the value at the top of the stack
<DT><B> Usage </B><DD><P><CODE>dup ()</CODE>
<DT><B> Description </B><DD><P>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.
<DT><B> See Also </B><DD><P><CODE>pop, typeof</CODE>
</DL>
<P>
<P>
<H2><A NAME="exch"></A> <A NAME="ss18.9">18.9 <B>exch</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Exchange two items on the stack
<DT><B> Usage </B><DD><P><CODE>exch ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>exch</CODE> swaps the two top items on the stack.
<DT><B> See Also </B><DD><P><CODE>pop, _stk_reverse, _stk_roll</CODE>
</DL>
<P>
<P>
<H2><A NAME="pop"></A> <A NAME="ss18.10">18.10 <B>pop</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Discard an item from the stack
<DT><B> Usage </B><DD><P><CODE>pop ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>pop</CODE> function removes the top item from the stack.
<DT><B> See Also </B><DD><P><CODE>_pop_n</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-19.html">Next</A>
<A HREF="slangfun-17.html">Previous</A>
<A HREF="slangfun.html#toc18">Contents</A>
</BODY>
</HTML>
