File: gawk.info,  Node: Numeric Functions,  Next: String Functions,  Prev: Boolean Functions,  Up: Built-in

9.1.3 Numeric Functions
-----------------------

The following list describes all of the built-in functions that work
with numbers.  Optional parameters are enclosed in square
brackets ([ ]):

'atan2(Y, X)'
     Return the arctangent of 'Y / X' in radians.  You can use 'pi =
     atan2(0, -1)' to retrieve the value of pi.

'cos(X)'
     Return the cosine of X, with X in radians.

'exp(X)'
     Return the exponential of X ('e ^ X') or report an error if X is
     out of range.  The range of values X can have depends on your
     machine's floating-point representation.

'int(X)'
     Return the nearest integer to X, located between X and zero and
     truncated toward zero.  For example, 'int(3)' is 3, 'int(3.9)' is
     3, 'int(-3.9)' is -3, and 'int(-3)' is -3 as well.

'log(X)'
     Return the natural logarithm of X, if X is positive; otherwise,
     return NaN ("not a number") on IEEE 754 systems.  Additionally,
     'gawk' prints a warning message when 'x' is negative.

'rand()'
     Return a random number.  The values of 'rand()' are uniformly
     distributed between zero and one.  The value could be zero but is
     never one.(1)

     Often random integers are needed instead.  Following is a
     user-defined function that can be used to obtain a random
     nonnegative integer less than N:

          function randint(n)
          {
              return int(n * rand())
          }

     The multiplication produces a random number greater than or equal
     to zero and less than 'n'.  Using 'int()', this result is made into
     an integer between zero and 'n' - 1, inclusive.

     The following example uses a similar function to produce random
     integers between one and N.  This program prints a new random
     number for each input record:

          # Function to roll a simulated die.
          function roll(n) { return 1 + int(rand() * n) }

          # Roll 3 six-sided dice and
          # print total number of points.
          {
              printf("%d points\n", roll(6) + roll(6) + roll(6))
          }

          CAUTION: In most 'awk' implementations, including 'gawk',
          'rand()' starts generating numbers from the same starting
          number, or "seed", each time you run 'awk'.(2)  Thus, a
          program generates the same results each time you run it.  The
          numbers are random within one 'awk' run but predictable from
          run to run.  This is convenient for debugging, but if you want
          a program to do different things each time it is used, you
          must change the seed to a value that is different in each run.
          To do this, use 'srand()'.

'sin(X)'
     Return the sine of X, with X in radians.

'sqrt(X)'
     Return the positive square root of X.  'gawk' prints a warning
     message if X is negative.  Thus, 'sqrt(4)' is 2.

'srand('[X]')'
     Set the starting point, or seed, for generating random numbers to
     the value X.

     Each seed value leads to a particular sequence of random
     numbers.(3)  Thus, if the seed is set to the same value a second
     time, the same sequence of random numbers is produced again.

          CAUTION: Different 'awk' implementations use different
          random-number generators internally.  Don't expect the same
          'awk' program to produce the same series of random numbers
          when executed by different versions of 'awk'.

     If the argument X is omitted, as in 'srand()', then the current
     date and time of day are used for a seed.  This is the way to get
     random numbers that are truly unpredictable.

     The return value of 'srand()' is the previous seed.  This makes it
     easy to keep track of the seeds in case you need to consistently
     reproduce sequences of random numbers.

     POSIX does not specify the initial seed; it differs among 'awk'
     implementations.

   ---------- Footnotes ----------

   (1) The C version of 'rand()' on many Unix systems is known to
produce fairly poor sequences of random numbers.  However, nothing
requires that an 'awk' implementation use the C 'rand()' to implement
the 'awk' version of 'rand()'.  In fact, for many years, 'gawk' used the
BSD 'random()' function, which is considerably better than 'rand()', to
produce random numbers.  From version 4.1.4, courtesy of Nelson H.F.
Beebe, 'gawk' uses the Bayes-Durham shuffle buffer algorithm which
considerably extends the period of the random number generator, and
eliminates short-range and long-range correlations that might exist in
the original generator.

   (2) 'mawk' uses a different seed each time.

   (3) Computer-generated random numbers really are not truly random.
They are technically known as "pseudorandom".  This means that although
the numbers in a sequence appear to be random, you can in fact generate
the same sequence of random numbers over and over again.