GNU Info

(gawk.info)Numeric Functions

---

Next: String Functions Prev: Calling Built-in Up: Built-in

---

Enter node , (file) or (file)node

Numeric Functions
-----------------

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

`int(X)'
     This returns the nearest integer to X, located between X and zero
     and truncated toward zero.

     For example, `int(3)' is three, `int(3.9)' is three, `int(-3.9)'
     is -3, and `int(-3)' is -3 as well.

`sqrt(X)'
     This returns the positive square root of X.  `gawk' reports an
     error if X is negative.  Thus, `sqrt(4)' is two.

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

`log(X)'
     This returns the natural logarithm of X, if X is positive;
     otherwise, it reports an error.

`sin(X)'
     This returns the sine of X, with X in radians.

`cos(X)'
     This returns the cosine of X, with X in radians.

`atan2(Y, X)'
     This returns the arctangent of `Y / X' in radians.

`rand()'
     This returns a random number.  The values of `rand' are uniformly
     distributed between zero and one.  The value is never zero and
     never one.(1)

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

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

     The multiplication produces a random number greater than 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'.  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'.

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

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

     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.

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

   (1) The C version of `rand' 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, `gawk' uses the BSD `random' function, which is
considerably better than `rand', to produce random numbers.

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