gawk: Pass By Value/Reference

1 
1 9.2.3.3 Passing Function Arguments by Value Or by Reference
1 ...........................................................
1 
1 In 'awk', when you declare a function, there is no way to declare
1 explicitly whether the arguments are passed "by value" or "by
1 reference".
1 
1    Instead, the passing convention is determined at runtime when the
1 function is called, according to the following rule: if the argument is
1 an array variable, then it is passed by reference.  Otherwise, the
1 argument is passed by value.
1 
1    Passing an argument by value means that when a function is called, it
1 is given a _copy_ of the value of this argument.  The caller may use a
1 variable as the expression for the argument, but the called function
1 does not know this--it only knows what value the argument had.  For
1 example, if you write the following code:
1 
1      foo = "bar"
1      z = myfunc(foo)
1 
1 then you should not think of the argument to 'myfunc()' as being "the
1 variable 'foo'."  Instead, think of the argument as the string value
1 '"bar"'.  If the function 'myfunc()' alters the values of its local
1 variables, this has no effect on any other variables.  Thus, if
1 'myfunc()' does this:
1 
1      function myfunc(str)
1      {
1         print str
1         str = "zzz"
1         print str
1      }
1 
1 to change its first argument variable 'str', it does _not_ change the
1 value of 'foo' in the caller.  The role of 'foo' in calling 'myfunc()'
1 ended when its value ('"bar"') was computed.  If 'str' also exists
1 outside of 'myfunc()', the function body cannot alter this outer value,
1 because it is shadowed during the execution of 'myfunc()' and cannot be
1 seen or changed from there.
1 
1    However, when arrays are the parameters to functions, they are _not_
1 copied.  Instead, the array itself is made available for direct
1 manipulation by the function.  This is usually termed "call by
1 reference".  Changes made to an array parameter inside the body of a
1 function _are_ visible outside that function.
1 
1      NOTE: Changing an array parameter inside a function can be very
1      dangerous if you do not watch what you are doing.  For example:
1 
1           function changeit(array, ind, nvalue)
1           {
1                array[ind] = nvalue
1           }
1 
1           BEGIN {
1               a[1] = 1; a[2] = 2; a[3] = 3
1               changeit(a, 2, "two")
1               printf "a[1] = %s, a[2] = %s, a[3] = %s\n",
1                       a[1], a[2], a[3]
1           }
1 
1      prints 'a[1] = 1, a[2] = two, a[3] = 3', because 'changeit()'
1      stores '"two"' in the second element of 'a'.
1 
1    Some 'awk' implementations allow you to call a function that has not
1 been defined.  They only report a problem at runtime, when the program
1 actually tries to call the function.  For example:
1 
1      BEGIN {
1          if (0)
1              foo()
1          else
1              bar()
1      }
1      function bar() { ... }
1      # note that `foo' is not defined
1 
1 Because the 'if' statement will never be true, it is not really a
1 problem that 'foo()' has not been defined.  Usually, though, it is a
1 problem if a program calls an undefined function.
1 
1    If '--lint' is specified (⇒Options), 'gawk' reports calls to
1 undefined functions.
1 
1    Some 'awk' implementations generate a runtime error if you use either
11 the 'next' statement or the 'nextfile' statement (⇒Next
 Statement, and ⇒Nextfile Statement) inside a user-defined
1 function.  'gawk' does not have this limitation.
1