(gawk.info) Function Caveats

Info Catalog

(gawk.info) Function Example

(gawk.info) User-defined

(gawk.info) Return Statement

 
 Calling User-defined Functions
 ==============================
 
    "Calling a function" means causing the function to run and do its
 job.  A function call is an expression, and its value is the value
 returned by the function.
 
    A function call consists of the function name followed by the
 arguments in parentheses.  What you write in the call for the arguments
 are `awk' expressions; each time the call is executed, these
 expressions are evaluated, and the values are the actual arguments.  For
 example, here is a call to `foo' with three arguments (the first being
 a string concatenation):
 
      foo(x y, "lose", 4 * z)
 
    *Caution:* whitespace characters (spaces and tabs) are not allowed
 between the function name and the open-parenthesis of the argument list.
 If you write whitespace by mistake, `awk' might think that you mean to
 concatenate a variable with an expression in parentheses.  However, it
 notices that you used a function name and not a variable name, and
 reports an error.
 
    When a function is called, it is given a _copy_ of the values of its
 arguments.  This is known as "call by value".  The caller may use a
 variable as the expression for the argument, but the called function
 does not know this: it only knows what value the argument had.  For
 example, if you write this code:
 
      foo = "bar"
      z = myfunc(foo)
 
 then you should not think of the argument to `myfunc' as being "the
 variable `foo'."  Instead, think of the argument as the string value,
 `"bar"'.
 
    If the function `myfunc' alters the values of its local variables,
 this has no effect on any other variables.  Thus, if `myfunc' does this:
 
      function myfunc(str)
      {
        print str
        str = "zzz"
        print str
      }
 
 to change its first argument variable `str', this _does not_ change the
 value of `foo' in the caller.  The role of `foo' in calling `myfunc'
 ended when its value, `"bar"', was computed.  If `str' also exists
 outside of `myfunc', the function body cannot alter this outer value,
 because it is shadowed during the execution of `myfunc' and cannot be
 seen or changed from there.
 
    However, when arrays are the parameters to functions, they are _not_
 copied.  Instead, the array itself is made available for direct
 manipulation by the function.  This is usually called "call by
 reference".  Changes made to an array parameter inside the body of a
 function _are_ visible outside that function.  This can be *very*
 dangerous if you do not watch what you are doing.  For example:
 
      function changeit(array, ind, nvalue)
      {
           array[ind] = nvalue
      }
      
      BEGIN {
          a[1] = 1; a[2] = 2; a[3] = 3
          changeit(a, 2, "two")
          printf "a[1] = %s, a[2] = %s, a[3] = %s\n",
                  a[1], a[2], a[3]
      }
 
 This program prints `a[1] = 1, a[2] = two, a[3] = 3', because
 `changeit' stores `"two"' in the second element of `a'.
 
    Some `awk' implementations allow you to call a function that has not
 been defined, and only report a problem at run-time when the program
 actually tries to call the function. For example:
 
      BEGIN {
          if (0)
              foo()
          else
              bar()
      }
      function bar() { ... }
      # note that `foo' is not defined
 
 Since the `if' statement will never be true, it is not really a problem
 that `foo' has not been defined.  Usually though, it is a problem if a
 program calls an undefined function.
 
    If `--lint' has been specified ( Command Line Options
 Options.), `gawk' will report about calls to undefined functions.
 
    Some `awk' implementations generate a run-time error if you use the
 `next' statement ( The `next' Statement Next Statement.)  inside
 a user-defined function.  `gawk' does not have this problem.
 

Info Catalog

(gawk.info) Function Example

(gawk.info) User-defined

(gawk.info) Return Statement