Description: Documentation

## 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 __push_args is useful for passing the arguments of a function to another function. __pop_args returns an array of n structures with a single structure field called value , which represents the value of the argument.

### Example

Consider the following print function. It prints all its arguments to stdout separated by spaces:

        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);
        }

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 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 on the arguments passed to the ones function onto the stack to be used when dereferencing Array_Type .

### See also

__push_args , typeof , _pop_n

## 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 __pop_args is useful for passing the arguments of one function to another. See the desription of __pop_args for more information.

### See also

__pop_args , typeof , _pop_n

## function _pop_n

### Synopsis

Remove objects from the stack

### Usage

_pop_n (Integer_Type n);

### Description

The _pop_n function pops n objects from the top of the stack.

### Example

        define add3 ()
        {
           variable x, y, z;
           if (_NARGS != 3)
             {
                _pop_n (_NARGS);
                error ("add3: Expecting 3 arguments");
             }
           (x, y, z) = ();
           return x + y + z;
        }

### See also

_stkdepth , pop

## 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.

### See also

_stkdepth , string

## function _stk_reverse

### Synopsis

Reverse the order of the objects on the stack.

### Usage

_stk_reverse (Integer_Type n)

### Description

The _stk_reverse function reverses the order of the top n items on the stack.

### See also

_stkdepth , _stk_roll

## 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 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.

### Example

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

### Notes

This function only has an effect for abs(n) > 1 .

### See also

_stkdepth , _stk_reverse , _pop_n , _print_stack

## function _stkdepth

### Usage

Get the number of objects currently on the stack.

### Synopsis

Integer_Type _stkdepth ()

### Description

The _stkdepth function returns number of items on stack prior to the call of _stkdepth .

### See also

_print_stack , _stk_reverse , _stk_roll

## 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.

### See also

pop , typeof

## function exch

### Synopsis

Exchange two items on the stack

### Usage

exch ()

### Description

The exch swaps the two top items on the stack.

### See also

pop , _stk_reverse , _stk_roll

## function pop

### Synopsis

Discard an item from the stack

### Usage

pop ()

### Description

The pop function removes the top item from the stack.

### See also

_pop_n