File: gawk.info,  Node: Return Statement,  Next: Dynamic Typing,  Prev: Function Calling,  Up: User-defined

9.2.4 The 'return' Statement
----------------------------

As seen in several earlier examples, the body of a user-defined function
can contain a 'return' statement.  This statement returns control to the
calling part of the 'awk' program.  It can also be used to return a
value for use in the rest of the 'awk' program.  It looks like this:

     'return' [EXPRESSION]

   The EXPRESSION part is optional.  Due most likely to an oversight,
POSIX does not define what the return value is if you omit the
EXPRESSION.  Technically speaking, this makes the returned value
undefined, and therefore, unpredictable.  In practice, though, all
versions of 'awk' simply return the null string, which acts like zero if
used in a numeric context.

   A 'return' statement without an EXPRESSION is assumed at the end of
every function definition.  So, if control reaches the end of the
function body, then technically the function returns an unpredictable
value.  In practice, it returns the empty string.  'awk' does _not_ warn
you if you use the return value of such a function.

   Sometimes, you want to write a function for what it does, not for
what it returns.  Such a function corresponds to a 'void' function in C,
C++, or Java, or to a 'procedure' in Ada.  Thus, it may be appropriate
to not return any value; simply bear in mind that you should not be
using the return value of such a function.

   The following is an example of a user-defined function that returns a
value for the largest number among the elements of an array:

     function maxelt(vec,   i, ret)
     {
          for (i in vec) {
               if (ret == "" || vec[i] > ret)
                    ret = vec[i]
          }
          return ret
     }

You call 'maxelt()' with one argument, which is an array name.  The
local variables 'i' and 'ret' are not intended to be arguments; there is
nothing to stop you from passing more than one argument to 'maxelt()'
but the results would be strange.  The extra space before 'i' in the
function parameter list indicates that 'i' and 'ret' are local
variables.  You should follow this convention when defining functions.

   The following program uses the 'maxelt()' function.  It loads an
array, calls 'maxelt()', and then reports the maximum number in that
array:

     function maxelt(vec,   i, ret)
     {
          for (i in vec) {
               if (ret == "" || vec[i] > ret)
                    ret = vec[i]
          }
          return ret
     }

     # Load all fields of each record into nums.
     {
          for(i = 1; i <= NF; i++)
               nums[NR, i] = $i
     }

     END {
          print maxelt(nums)
     }

   Given the following input:

      1 5 23 8 16
     44 3 5 2 8 26
     256 291 1396 2962 100
     -6 467 998 1101
     99385 11 0 225

the program reports (predictably) that 99,385 is the largest value in
the array.