Go to the first, previous, next, last section, table of contents.


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.

Decrement and increment operators

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

incr(number)
decr(number)

which expand to the numerical value of number, incremented, or decremented, respectively, by one.

incr(4)
=>5
decr(7)
=>6

The builtin macros incr and decr are recognized only when given arguments.

Evaluating integer or rational expressions

Integer expressions are evaluated with eval:

eval(expression, opt radix, opt width)

which expands to the value of expression.

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

-
Unary minus
**
Exponentiation
* / % :
Multiplication, division, modulo and ratio
+ -
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 many m4 implementations use `^' as an alternate operator for the exponentiation, while many others use `^' for the bitwise exclusive-or. GNU m4 changed its behavior: it used to exponentiate for `^', it now computes the bitwise exclusive-or.

Numbers without special prefix are given decimal. A simple `0' prefix introduces an octal number. `0x' introduces an 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 any radix, 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.

Calculations are done in at lease 32 bit, but m4 will use wider integers if available.

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
define(`square', `eval(($1)**2)')
=>
square(9)
=>81
square(square(5)+1)
=>676
define(`foo', `666')
=>
eval(`foo'/6)
error-->m4: in: 7: Bad expression in eval: foo/6
=>
eval(foo/6)
=>111

As the second to last example shows, 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.

If radix is specified, it specifies the radix to be used in the expansion. The default radix is 10. The result of eval is always taken to be signed. The width argument specifies a minimum output width. The result is zero-padded to extend the expansion to the requested width.

eval(666, 10)
=>666
eval(666, 11)
=>556
eval(666, 6)
=>3030
eval(666, 6, 10)
=>0000003030
eval(-666, 6, 10)
=>-000003030

Take note that radix cannot be larger than 36.

The builtin macro eval is recognized only when given arguments.

Multiple precision arithmetic

When m4 is compiled with a multiple precision arithmetic library (see section Experimental features in GNU m4), a builtin mpeval is defined.

It is almost identical to eval, except the calculations are done with infinite precision. Numbers may be of any length.

The : operator rationally divides two numbers and canonicalizes the result. The / operator always returns the quotient of the division. To convert a rational value to integral, divide (/) by 1. Some operators such as %, <<, >>, ~, &, | and ^ operate only on integers and will truncate any rational remainder. ** assumes that the exponent is integral.


Go to the first, previous, next, last section, table of contents.