File: gawk.info,  Node: Function Calls,  Next: Precedence,  Prev: Truth Values and Conditions,  Up: Expressions

6.4 Function Calls
==================

A "function" is a name for a particular calculation.  This enables you
to ask for it by name at any point in the program.  For example, the
function 'sqrt()' computes the square root of a number.

   A fixed set of functions are "built in", which means they are
available in every 'awk' program.  The 'sqrt()' function is one of
these.  *Note Built-in:: for a list of built-in functions and their
descriptions.  In addition, you can define functions for use in your
program.  *Note User-defined:: for instructions on how to do this.
Finally, 'gawk' lets you write functions in C or C++ that may be called
from your program (*note Dynamic Extensions::).

   The way to use a function is with a "function call" expression, which
consists of the function name followed immediately by a list of
"arguments" in parentheses.  The arguments are expressions that provide
the raw materials for the function's calculations.  When there is more
than one argument, they are separated by commas.  If there are no
arguments, just write '()' after the function name.  The following
examples show function calls with and without arguments:

     sqrt(x^2 + y^2)        one argument
     atan2(y, x)            two arguments
     rand()                 no arguments

     CAUTION: Do not put any space between the function name and the
     opening parenthesis!  A user-defined function name looks just like
     the name of a variable--a space would make the expression look like
     concatenation of a variable with an expression inside parentheses.
     With built-in functions, space before the parenthesis is harmless,
     but it is best not to get into the habit of using space to avoid
     mistakes with user-defined functions.

   Each function expects a particular number of arguments.  For example,
the 'sqrt()' function must be called with a single argument, the number
of which to take the square root:

     sqrt(ARGUMENT)

   Some of the built-in functions have one or more optional arguments.
If those arguments are not supplied, the functions use a reasonable
default value.  *Note Built-in:: for full details.  If arguments are
omitted in calls to user-defined functions, then those arguments are
treated as local variables.  Such local variables act like the empty
string if referenced where a string value is required, and like zero if
referenced where a numeric value is required (*note User-defined::).

   As an advanced feature, 'gawk' provides indirect function calls,
which is a way to choose the function to call at runtime, instead of
when you write the source code to your program.  We defer discussion of
this feature until later; see *note Indirect Calls::.

   Like every other expression, the function call has a value, often
called the "return value", which is computed by the function based on
the arguments you give it.  In this example, the return value of
'sqrt(ARGUMENT)' is the square root of ARGUMENT.  The following program
reads numbers, one number per line, and prints the square root of each
one:

     $ awk '{ print "The square root of", $1, "is", sqrt($1) }'
     1
     -| The square root of 1 is 1
     3
     -| The square root of 3 is 1.73205
     5
     -| The square root of 5 is 2.23607
     Ctrl-d

   A function can also have side effects, such as assigning values to
certain variables or doing I/O. This program shows how the 'match()'
function (*note String Functions::) changes the variables 'RSTART' and
'RLENGTH':

     {
         if (match($1, $2))
             print RSTART, RLENGTH
         else
             print "no match"
     }

Here is a sample run:

     $ awk -f matchit.awk
     aaccdd  c+
     -| 3 2
     foo     bar
     -| no match
     abcdefg e
     -| 5 1