Software: Apache/2.0.54 (Unix) mod_perl/1.99_09 Perl/v5.8.0 mod_ssl/2.0.54 OpenSSL/0.9.7l DAV/2 FrontPage/5.0.2.2635 PHP/4.4.0 mod_gzip/2.0.26.1a 

uname -a: Linux snow.he.net 4.4.276-v2-mono-1 #1 SMP Wed Jul 21 11:21:17 PDT 2021 i686 

uid=99(nobody) gid=98(nobody) groups=98(nobody) 

Safe-mode: OFF (not secure)

/usr/doc/slang-1.4.5/html/   drwxr-xr-x
Free 318.39 GB of 458.09 GB (69.5%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     slang-9.html (18.98 KB)      -rw-r--r--

9. Functions

A function may be thought of as a group of statements that work together to perform a computation. While there are no imposed limits upon the number statements that may occur within a function, it is considered poor programming practice if a function contains many statements. This notion stems from the belief that a function should have a simple, well defined purpose.

9.1 Declaring Functions

Like variables, functions must be declared before they can be used. The define keyword is used for this purpose. For example,

      define factorial ();

Usually, the above form is used only for recursive functions. In most cases, the function name is almost always followed by a parameter list and the body of the function:

define function-name (parameter-list) { statement-list }

The variables in the parameter-list are implicitly declared, thus, there is no need to declare them via a variable declaration statement. In fact any attempt to do so will result in a syntax error.

9.2 Parameter Passing Mechanism

Parameters to a function are always passed by value and never by reference. To see what this means, consider

     define add_10 (a) 
     {
        a = a + 10;
     }
     variable b = 0;
     add_10 (b);

S-Lang does provide a mechanism for simulating pass by reference via the reference operator. See the next section for more details.

If a function is called with a parameter in the parameter list omitted, the corresponding variable in the function will be set to NULL. To make this clear, consider the function

     define add_two_numbers (a, b)
     {
        if (a == NULL) a = 0;
        if (b == NULL) b = 0;
        return a + b;
     }

     variable s = add_two_numbers (2,3);
     variable s = add_two_numbers (2,);
     variable s = add_two_numbers (,3);
     variable s = add_two_numbers (,);

     variable s = add_two_numbers (2, NULL);
     variable s = add_two_numbers (NULL, 3);
     variable s = add_two_numbers (NULL, NULL);

     variable s = add_10 ();

9.3 Referencing Variables

One can achieve the effect of passing by reference by using the reference (&) and dereference (@) operators. Consider again the add_10 function presented in the previous section. This time we write it as

     define add_10 (a)
     {  
        @a = @a + 10;
     }
     variable b = 0;
     add_10 (&b);

The reader familiar with C will note the similarity between references in S-Lang and pointers in C.

One of the main purposes for references is that this mechanism allows reference to functions to be passed to other functions. As a simple example from elementary calculus, consider the following function which returns an approximation to the derivative of another function at a specified point:

     define derivative (f, x)
     {
        variable h = 1e-6;
        return (@f(x+h) - @f(x)) / h;
     }

     define x_squared (x)
     {
        return x^2;
     }

9.4 Functions with a Variable Number of Arguments

S-Lang functions may be defined to take a variable number of arguments. The reason for this is that the calling routine pushes the arguments onto the stack before making a function call, and it is up to the called function to pop the values off the stack and make assignments to the variables in the parameter list. These details are, for the most part, hidden from the programmer. However, they are important when a variable number of arguments are passed.

Consider the add_10 example presented earlier. This time it is written

     define add_10 ()
     {
        variable x;
        x = ();
        return x + 10;
     }
     variable s = add_10 (12);  % ==> s = 22;

First, consider what happened when add_10 is called with the the parameter 12. Internally, 12 is pushed onto the stack and then the function called. Now, consider the function itself. x is a variable local to the function. The strange looking assignment `x=()' simply takes whatever is on the stack and assigns it to x. In other words, after this statement, the value of x will be 12, since 12 will be at the top of the stack.

A generic function of the form

    define function_name (x, y, ..., z)
    {
       .
       .
    }

    define function_name ()
    {
       variable x, y, ..., z;
       z = ();
       .
       .
       y = ();
       x = ();
       .
       .
    }

    define average_n (n)
    {
       variable x, y;
       variable sum;
       
       if (n == 1) 
         {
            x = ();
            sum = x;
         }
       else if (n == 2)
         {
            y = ();
            x = ();
            sum = x + y;
         }
       else error ("average_n: only one or two values supported");
       
       return sum / n;
   }
   variable ave1 = average_n (3.0, 1);        % ==> 3.0
   variable ave2 = average_n (3.0, 5.0, 2);   % ==> 4.0

   define average_n (n)
   {
      variable sum, x;
      sum = 0;
      loop (n) 
        {
           x = ();    % get next value from stack
           sum += x;
        }
      return sum / n;
   }

Fortunately, a special variable exists that is local to every function and contains the number of values that were passed to the function. That variable has the name _NARGS and may be used as follows:

   define average_n ()
   {
      variable x, sum = 0;
      
      if (_NARGS == 0) error ("Usage: ave = average_n (x, ...);");

      loop (_NARGS)
        {
           x = ();
           sum += x;
        }
      return sum / _NARGS;
   }

9.5 Returning Values

As stated earlier, the usual way to return values from a function is via the return statement. This statement has the simple syntax

return expression-list ;

        define sum_and_diff (x, y)
        {
            variable sum, diff;

            sum = x + y;  diff = x - y;
            return sum, diff;
        }

It is extremely important to note that the calling routine must explicitly handle all values returned by a function. Although some languages such as C do not have this restriction, S-Lang does and it is a direct result of a S-Lang function's ability to return many values and accept a variable number of parameters. Examples of properly handling the above function include

       variable sum, diff;
       (sum, diff) = sum_and_diff (5, 4);  % ignore neither
       (sum, ) = sum_and_diff (5, 4);      % ignore diff
       (,) = sum_and_diff (5, 4);          % ignore both sum and diff

9.6 Multiple Assignment Statement

S-Lang functions can return more than one value, e.g.,

       define sum_and_diff (x, y)
       {
          return x + y, x - y;
       }

      sum_and_diff (9, 4);
      d = ();
      s = ();

However, the most convenient way to accomplish this is to use a multiple assignment statement such as

       (s, d) = sum_and_diff (9, 4);

     ( var_1, var_2, ..., var_n ) = expression;

     expression; var_n = (); ... var_2 = (); var_1 = ();

If you do not care about one of return values, simply omit the variable name from the list. For example,

        (s, ) = sum_and_diff (9, 4);

As another example, the jed editor provides a function called down that takes an integer argument and returns an integer. It is used to move the current editing position down the number of lines specified by the argument passed to it. It returns the number of lines it successfully moved the editing position. Often one does not care about the return value from this function. Although it is always possible to handle the return value via

       variable dummy = down (10);

       () = down (10);

Some functions return a variable number of values instead of a fixed number. Usually, the value at the top of the stack will indicate the actual number of return values. For such functions, the multiple assignment statement cannot directly be used. To see how such functions can be dealt with, consider the following function:

     define read_line (fp)
     {
        variable line;
        if (-1 == fgets (&line, fp))
          return -1;
        return (line, 0);
     }

      status = read_line (fp);
      if (status != -1)
        {
           s = ();
           .
           .
        }

Before leaving this section it is important to reiterate the fact that if a function returns a value, the caller must deal with that return value. Otherwise, the value will continue to live onto the stack and may eventually lead to a stack overflow error. Failing to handle the return value of a function is the most common mistake that inexperienced S-Lang programmers make. For example, the fflush function returns a value that many C programmer's never check. Instead of writing

      fflush (fp);

      () = fflush (fp);

9.7 Exit-Blocks

An exit-block is a set of statements that get executed when a functions returns. They are very useful for cleaning up when a function returns via an explicit call to return from deep within a function.

An exit-block is created by using the EXIT_BLOCK keyword according to the syntax

EXIT_BLOCK { statement-list }

      define simple_demo ()
      {
         variable n = 0;

         EXIT_BLOCK { message ("Exit block called."); }

         forever
          {
            if (n == 10) return;
            n++;
          }
      }

A function can contain multiple exit-blocks, but only the last one encountered during execution will actually get executed. For example,

      define simple_demo (n)
      {
         EXIT_BLOCK { return 1; }
         
         if (n != 1)
           {
              EXIT_BLOCK { return 2; }
           }
         return;
      }