GNU macro processor - 11. Macros for doing arithmetic

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

# 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`:

    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.

## 11.2 Evaluating integer 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 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 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.

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-->51.eval:14: m4: 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.

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