gawk: Numeric Functions

1 
1 9.1.2 Numeric Functions
1 -----------------------
1 
1 The following list describes all of the built-in functions that work
1 with numbers.  Optional parameters are enclosed in square
1 brackets ([ ]):
1 
1 'atan2(Y, X)'
1      Return the arctangent of 'Y / X' in radians.  You can use 'pi =
1      atan2(0, -1)' to retrieve the value of pi.
1 
1 'cos(X)'
1      Return the cosine of X, with X in radians.
1 
1 'exp(X)'
1      Return the exponential of X ('e ^ X') or report an error if X is
1      out of range.  The range of values X can have depends on your
1      machine's floating-point representation.
1 
1 'int(X)'
1      Return the nearest integer to X, located between X and zero and
1      truncated toward zero.  For example, 'int(3)' is 3, 'int(3.9)' is
1      3, 'int(-3.9)' is -3, and 'int(-3)' is -3 as well.
1 
1 'log(X)'
1      Return the natural logarithm of X, if X is positive; otherwise,
1      return 'NaN' ("not a number") on IEEE 754 systems.  Additionally,
1      'gawk' prints a warning message when 'x' is negative.
1 
1 'rand()'
1      Return a random number.  The values of 'rand()' are uniformly
1      distributed between zero and one.  The value could be zero but is
1      never one.(1)
1 
1      Often random integers are needed instead.  Following is a
1      user-defined function that can be used to obtain a random
1      nonnegative integer less than N:
1 
1           function randint(n)
1           {
1               return int(n * rand())
1           }
1 
1      The multiplication produces a random number greater than or equal
1      to zero and less than 'n'.  Using 'int()', this result is made into
1      an integer between zero and 'n' - 1, inclusive.
1 
1      The following example uses a similar function to produce random
1      integers between one and N.  This program prints a new random
1      number for each input record:
1 
1           # Function to roll a simulated die.
1           function roll(n) { return 1 + int(rand() * n) }
1 
1           # Roll 3 six-sided dice and
1           # print total number of points.
1           {
1               printf("%d points\n", roll(6) + roll(6) + roll(6))
1           }
1 
1           CAUTION: In most 'awk' implementations, including 'gawk',
1           'rand()' starts generating numbers from the same starting
1           number, or "seed", each time you run 'awk'.(2)  Thus, a
1           program generates the same results each time you run it.  The
1           numbers are random within one 'awk' run but predictable from
1           run to run.  This is convenient for debugging, but if you want
1           a program to do different things each time it is used, you
1           must change the seed to a value that is different in each run.
1           To do this, use 'srand()'.
1 
1 'sin(X)'
1      Return the sine of X, with X in radians.
1 
1 'sqrt(X)'
1      Return the positive square root of X.  'gawk' prints a warning
1      message if X is negative.  Thus, 'sqrt(4)' is 2.
1 
1 'srand('[X]')'
1      Set the starting point, or seed, for generating random numbers to
1      the value X.
1 
1      Each seed value leads to a particular sequence of random
1      numbers.(3)  Thus, if the seed is set to the same value a second
1      time, the same sequence of random numbers is produced again.
1 
1           CAUTION: Different 'awk' implementations use different
1           random-number generators internally.  Don't expect the same
1           'awk' program to produce the same series of random numbers
1           when executed by different versions of 'awk'.
1 
1      If the argument X is omitted, as in 'srand()', then the current
1      date and time of day are used for a seed.  This is the way to get
1      random numbers that are truly unpredictable.
1 
1      The return value of 'srand()' is the previous seed.  This makes it
1      easy to keep track of the seeds in case you need to consistently
1      reproduce sequences of random numbers.
1 
1      POSIX does not specify the initial seed; it differs among 'awk'
1      implementations.
1 
1    ---------- Footnotes ----------
1 
1    (1) The C version of 'rand()' on many Unix systems is known to
1 produce fairly poor sequences of random numbers.  However, nothing
1 requires that an 'awk' implementation use the C 'rand()' to implement
1 the 'awk' version of 'rand()'.  In fact, 'gawk' uses the BSD 'random()'
1 function, which is considerably better than 'rand()', to produce random
1 numbers.
1 
1    (2) 'mawk' uses a different seed each time.
1 
1    (3) Computer-generated random numbers really are not truly random.
1 They are technically known as "pseudorandom".  This means that although
1 the numbers in a sequence appear to be random, you can in fact generate
1 the same sequence of random numbers over and over again.
1