11. Macros for doing arithmetic

Integer arithmetic is included in m4, with a C-like syntax. As convenient shorthands, there are builtins for simple increment and decrement operations.

11.1 Decrement and increment operators

Increment and decrement of integers are supported using the builtins incr and decr:

Builtin: incr (number)

Builtin: decr (number)

Expand to the numerical value of number, incremented or decremented, respectively, by one. Except for the empty string, the expansion is empty if number could not be parsed.

The macros incr and decr are recognized only with parameters.

incr(`4')
⇒5
decr(`7')
⇒6
incr()
error-->m4:stdin:3: empty string treated as 0 in builtin `incr'
⇒1
decr()
error-->m4:stdin:4: empty string treated as 0 in builtin `decr'
⇒-1

11.2 Evaluating integer expressions

Integer expressions are evaluated with eval:

Builtin: eval (expression, [radix = `10'], [width])

Expands to the value of expression. The expansion is empty if an error is encountered while parsing the arguments. If specified, radix and width control the format of the output.

The macro eval is recognized only with parameters.

Expressions can contain the following operators, listed in order of decreasing precedence.

+ -

Unary plus and minus

**

Exponentiation

* / %

Multiplication, division and modulo

+ -

Addition and subtraction

<< >>

Shift left or right

== != > >= < <=

Relational operators

!

Logical negation

~

Bitwise negation

&

Bitwise and

^

Bitwise exclusive-or

|

Bitwise or

&&

Logical and

||

Logical or

All operators, except exponentiation, are left associative.

Note that some older m4 implementations use `^' as an alternate operator for exponentiation, although POSIX requires the C behavior of bitwise exclusive-or. On the other hand, the precedence of `~' and `!' are different in GNU m4 than they are in C, matching the precedence in traditional m4 implementations. This behavior is likely to change in a future version to match POSIX, so use parentheses to force the desired precedence.

Within expression, (but not radix or width), numbers without a special prefix are decimal. A simple `0' prefix introduces an octal number. `0x' introduces a hexadecimal number. `0b' introduces a binary number. `0r' introduces a number expressed in any radix between 1 and 36: the prefix should be immediately followed by the decimal expression of the radix, a colon, then the digits making the number. For radix 1, leading zeros are ignored and all remaining digits must be `1'; for all other radices, the digits are `0', `1', `2', …. Beyond `9', the digits are `a', `b' … up to `z'. Lower and upper case letters can be used interchangeably in numbers prefixes and as number digits.

Parentheses may be used to group subexpressions whenever needed. For the relational operators, a true relation returns 1, and a false relation return 0.

Here are a few examples of use of eval.

eval(`-3 * 5')
⇒-15
eval(index(`Hello world', `llo') >= 0)
⇒1
eval(`0r1:0111 + 0b100 + 0r3:12')
⇒12
define(`square', `eval(`('$1`)**2')')
⇒
square(`9')
⇒81
square(square(`5')`+1')
⇒676
define(`foo', `666')
⇒
eval(`foo/6')
error-->m4:stdin:8: bad expression in eval: foo/6
⇒
eval(foo/6)
⇒111

As the last two lines show, eval does not handle macro names, even if they expand to a valid expression (or part of a valid expression). Therefore all macros must be expanded before they are passed to eval.

All evaluation is done with 32-bit signed integers, assuming 2's-complement with wrap-around. The shift operators are defined in GNU m4 by doing an implicit bit-wise and of the right-hand operand with 0x1f, and sign-extension with right shift.

eval(0x80000000 / -1)
⇒-2147483648
eval(0x80000000 % -1)
⇒0
eval(0x7fffffff)
⇒2147483647
incr(eval(0x7fffffff))
⇒-2147483648
eval(-4 >> 33)
⇒-2

If radix is specified, it specifies the radix to be used in the expansion. The default radix is 10; this is also the case if radix is the empty string. It is an error if the radix is outside the range of 1 through 36, inclusive. The result of eval is always taken to be signed. No radix prefix is output, and for radices greater than 10, the digits are lower case. The width argument specifies the minimum output width, excluding any negative sign. The result is zero-padded to extend the expansion to the requested width. It is an error if the width is negative. On error, the expansion of eval is empty.

eval(`666', `10')
⇒666
eval(`666', `11')
⇒556
eval(`666', `6')
⇒3030
eval(`666', `6', `10')
⇒0000003030
eval(`-666', `6', `10')
⇒-0000003030
eval(`10', `', `0')
⇒10
`0r1:'eval(`10', `1', `11')
⇒0r1:01111111111
eval(`10', `16')
⇒a

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.