1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
\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
|
