String Functions - The GNU Awk User's Guide

Next: I/O Functions, Previous: Numeric Functions, Up: Built-in

9.1.3 String-Manipulation Functions

The functions in this section look at or change the text of one or more strings. gawk understands locales (see Locales), and does all string processing in terms of characters, not bytes. This distinction is particularly important to understand for locales where one character may be represented by multiple bytes. Thus, for example, length() returns the number of characters in a string, and not the number of bytes used to represent those characters, Similarly, index() works with character indices, and not byte indices.

In the following list, optional parameters are enclosed in square brackets ([ ]). Several functions perform string substitution; the full discussion is provided in the description of the sub() function, which comes towards the end since the list is presented in alphabetic order. Those functions that are specific to gawk are marked with a pound sign (‘#’):

asort(source [, dest [, how ] ]) #

Return the number of elements in the array source. gawk sorts the contents of source and replaces the indices of the sort./usr/share/doc/gawk-doc/gawk-html/Numeric-Functions.html0000644000000000000000000002306311744546373022240 0ustar rootroot Numeric Functions - The GNU Awk User's Guide

Next: String Functions, Previous: Calling Built-in, Up: Built-in

9.1.2 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, report an error.

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.¹

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().

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.³ 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.

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, gawk uses the BSD random() function, which is considerably better than rand(), to produce random numbers.

[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 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.

./usr/share/doc/gawk-doc/gawk-html/String-Functions.html0000644000000000000000000012105711744546373022106 0ustar rootroot String Functions - The GNU Awk User's Guide

Next: I/O Functions, Previous: Numeric Functions, Up: Built-in

9.1.3 String-Manipulation Functions

asort(source [, dest [, how ] ]) #

Next: String Functions, Previous: Calling Built-in, Up: Built-in

9.1.2 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, report an error.

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.¹

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().

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.³ 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.

Footnotes

[2] mawk uses a different seed each time.

./usr/share/doc/gawk-doc/gawk-html/String-Functions.html0000644000000000000000000012105711744546373022106 0ustar rootroot String Functions - The GNU Awk User's Guide

Next: I/O Functions, Previous: Numeric Functions, Up: Built-in

9.1.3 String-Manipulation Functions

asort(source [, dest [, how ] ]) #

Next: String Functions, Previous: Calling Built-in, Up: Built-in

9.1.2 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)