/usr/share/doc/m4-doc/Eval.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 
This manual (31 December 2016) is for GNU M4 (version
1.4.18), a package containing an implementation of the m4 macro
language.

Copyright (C) 1989-1994, 2004-2014, 2016 Free Software
Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License." -->
<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU M4 1.4.18 macro processor: Eval</title>

<meta name="description" content="GNU M4 1.4.18 macro processor: Eval">
<meta name="keywords" content="GNU M4 1.4.18 macro processor: Eval">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Indices.html#Indices" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Arithmetic.html#Arithmetic" rel="up" title="Arithmetic">
<link href="Shell-commands.html#Shell-commands" rel="next" title="Shell commands">
<link href="Incr.html#Incr" rel="prev" title="Incr">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Eval"></a>
<div class="header">
<p>
Previous: <a href="Incr.html#Incr" accesskey="p" rel="prev">Incr</a>, Up: <a href="Arithmetic.html#Arithmetic" accesskey="u" rel="up">Arithmetic</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Evaluating-integer-expressions"></a>
<h3 class="section">12.2 Evaluating integer expressions</h3>

<a name="index-integer-expression-evaluation"></a>
<a name="index-evaluation_002c-of-integer-expressions"></a>
<a name="index-expressions_002c-evaluation-of-integer"></a>
<p>Integer expressions are evaluated with <code>eval</code>:
</p>
<dl>
<dt><a name="index-eval"></a>Builtin: <strong>eval</strong> <em>(<var>expression</var>, <span class="roman">[</span><var>radix</var> = &lsquo;<samp>10</samp>&rsquo;<span class="roman">]</span>, <span class="roman">[</span><var>width</var><span class="roman">]</span>)</em></dt>
<dd><p>Expands to the value of <var>expression</var>.  The expansion is empty
if a problem is encountered while parsing the arguments.  If specified,
<var>radix</var> and <var>width</var> control the format of the output.
</p>
<p>Calculations are done with 32-bit signed numbers.  Overflow silently
results in wraparound.  A warning is issued if division by zero is
attempted, or if <var>expression</var> could not be parsed.
</p>
<p>Expressions can contain the following operators, listed in order of
decreasing precedence.
</p>
<dl compact="compact">
<dt>&lsquo;<samp>()</samp>&rsquo;</dt>
<dd><p>Parentheses
</p></dd>
<dt>&lsquo;<samp>+  -  ~  !</samp>&rsquo;</dt>
<dd><p>Unary plus and minus, and bitwise and logical negation
</p></dd>
<dt>&lsquo;<samp>**</samp>&rsquo;</dt>
<dd><p>Exponentiation
</p></dd>
<dt>&lsquo;<samp>*  /  %</samp>&rsquo;</dt>
<dd><p>Multiplication, division, and modulo
</p></dd>
<dt>&lsquo;<samp>+  -</samp>&rsquo;</dt>
<dd><p>Addition and subtraction
</p></dd>
<dt>&lsquo;<samp>&lt;&lt;  &gt;&gt;</samp>&rsquo;</dt>
<dd><p>Shift left or right
</p></dd>
<dt>&lsquo;<samp>&gt;  &gt;=  &lt;  &lt;=</samp>&rsquo;</dt>
<dd><p>Relational operators
</p></dd>
<dt>&lsquo;<samp>==  !=</samp>&rsquo;</dt>
<dd><p>Equality operators
</p></dd>
<dt>&lsquo;<samp>&amp;</samp>&rsquo;</dt>
<dd><p>Bitwise and
</p></dd>
<dt>&lsquo;<samp>^</samp>&rsquo;</dt>
<dd><p>Bitwise exclusive-or
</p></dd>
<dt>&lsquo;<samp>|</samp>&rsquo;</dt>
<dd><p>Bitwise or
</p></dd>
<dt>&lsquo;<samp>&amp;&amp;</samp>&rsquo;</dt>
<dd><p>Logical and
</p></dd>
<dt>&lsquo;<samp>||</samp>&rsquo;</dt>
<dd><p>Logical or
</p></dd>
</dl>

<p>The macro <code>eval</code> is recognized only with parameters.
</p></dd></dl>

<p>All binary operators, except exponentiation, are left associative.  C
operators that perform variable assignment, such as &lsquo;<samp>+=</samp>&rsquo; or
&lsquo;<samp>--</samp>&rsquo;, are not implemented, since <code>eval</code> only operates on
constants, not variables.  Attempting to use them results in an error.
However, since traditional implementations treated &lsquo;<samp>=</samp>&rsquo; as an
undocumented alias for &lsquo;<samp>==</samp>&rsquo; as opposed to an assignment operator,
this usage is supported as a special case.  Be aware that a future
version of GNU M4 may support assignment semantics as an
extension when POSIX mode is not requested, and that using
&lsquo;<samp>=</samp>&rsquo; to check equality is not portable.
</p>
<div class="example">
<pre class="example">eval(`2 = 2')
error&rarr;m4:stdin:1: Warning: recommend ==, not =, for equality operator
&rArr;1
eval(`++0')
error&rarr;m4:stdin:2: invalid operator in eval: ++0
&rArr;
eval(`0 |= 1')
error&rarr;m4:stdin:3: invalid operator in eval: 0 |= 1
&rArr;
</pre></div>

<p>Note that some older <code>m4</code> implementations use &lsquo;<samp>^</samp>&rsquo; as an
alternate operator for the exponentiation, although POSIX
requires the C behavior of bitwise exclusive-or.  The precedence of the
negation operators, &lsquo;<samp>~</samp>&rsquo; and &lsquo;<samp>!</samp>&rsquo;, was traditionally lower than
equality.  The unary operators could not be used reliably more than once
on the same term without intervening parentheses.  The traditional
precedence of the equality operators &lsquo;<samp>==</samp>&rsquo; and &lsquo;<samp>!=</samp>&rsquo; was
identical instead of lower than the relational operators such as
&lsquo;<samp>&lt;</samp>&rsquo;, even through GNU M4 1.4.8.  Starting with version
1.4.9, GNU M4 correctly follows POSIX precedence
rules.  M4 scripts designed to be portable between releases must be
aware that parentheses may be required to enforce C precedence rules.
Likewise, division by zero, even in the unused branch of a
short-circuiting operator, is not always well-defined in other
implementations.
</p>
<p>Following are some examples where the current version of M4 follows C
precedence rules, but where older versions and some other
implementations of <code>m4</code> require explicit parentheses to get the
correct result:
</p>
<div class="example">
<pre class="example">eval(`1 == 2 &gt; 0')
&rArr;1
eval(`(1 == 2) &gt; 0')
&rArr;0
eval(`! 0 * 2')
&rArr;2
eval(`! (0 * 2)')
&rArr;1
eval(`1 | 1 ^ 1')
&rArr;1
eval(`(1 | 1) ^ 1')
&rArr;0
eval(`+ + - ~ ! ~ 0')
&rArr;1
eval(`2 || 1 / 0')
&rArr;1
eval(`0 || 1 / 0')
error&rarr;m4:stdin:9: divide by zero in eval: 0 || 1 / 0
&rArr;
eval(`0 &amp;&amp; 1 % 0')
&rArr;0
eval(`2 &amp;&amp; 1 % 0')
error&rarr;m4:stdin:11: modulo by zero in eval: 2 &amp;&amp; 1 % 0
&rArr;
</pre></div>

<a name="index-GNU-extensions-14"></a>
<p>As a GNU extension, the operator &lsquo;<samp>**</samp>&rsquo; performs integral
exponentiation.  The operator is right-associative, and if evaluated,
the exponent must be non-negative, and at least one of the arguments
must be non-zero, or a warning is issued.
</p>
<div class="example">
<pre class="example">eval(`2 ** 3 ** 2')
&rArr;512
eval(`(2 ** 3) ** 2')
&rArr;64
eval(`0 ** 1')
&rArr;0
eval(`2 ** 0')
&rArr;1
eval(`0 ** 0')
&rArr;
error&rarr;m4:stdin:5: divide by zero in eval: 0 ** 0
eval(`4 ** -2')
error&rarr;m4:stdin:6: negative exponent in eval: 4 ** -2
&rArr;
</pre></div>

<p>Within <var>expression</var>, (but not <var>radix</var> or <var>width</var>), numbers
without a special prefix are decimal.  A simple &lsquo;<samp>0</samp>&rsquo; prefix
introduces an octal number.  &lsquo;<samp>0x</samp>&rsquo; introduces a hexadecimal number.
As GNU extensions, &lsquo;<samp>0b</samp>&rsquo; introduces a binary number.
&lsquo;<samp>0r</samp>&rsquo; 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 &lsquo;<samp>1</samp>&rsquo;;
for all other radices, the digits are &lsquo;<samp>0</samp>&rsquo;, &lsquo;<samp>1</samp>&rsquo;, &lsquo;<samp>2</samp>&rsquo;,
&hellip;.  Beyond &lsquo;<samp>9</samp>&rsquo;, the digits are &lsquo;<samp>a</samp>&rsquo;, &lsquo;<samp>b</samp>&rsquo; &hellip; up
to &lsquo;<samp>z</samp>&rsquo;.  Lower and upper case letters can be used interchangeably
in numbers prefixes and as number digits.
</p>
<p>Parentheses may be used to group subexpressions whenever needed.  For the
relational operators, a true relation returns <code>1</code>, and a false
relation return <code>0</code>.
</p>
<p>Here are a few examples of use of <code>eval</code>.
</p>
<div class="example">
<pre class="example">eval(`-3 * 5')
&rArr;-15
eval(`-99 / 10')
&rArr;-9
eval(`-99 % 10')
&rArr;-9
eval(`99 % -10')
&rArr;9
eval(index(`Hello world', `llo') &gt;= 0)
&rArr;1
eval(`0r1:0111 + 0b100 + 0r3:12')
&rArr;12
define(`square', `eval(`($1) ** 2')')
&rArr;
square(`9')
&rArr;81
square(square(`5')` + 1')
&rArr;676
define(`foo', `666')
&rArr;
eval(`foo / 6')
error&rarr;m4:stdin:11: bad expression in eval: foo / 6
&rArr;
eval(foo / 6)
&rArr;111
</pre></div>

<p>As the last two lines show, <code>eval</code> 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 <code>eval</code>.
</p>
<p>Some calculations are not portable to other implementations, since they
have undefined semantics in C, but GNU <code>m4</code> has
well-defined behavior on overflow.  When shifting, an out-of-range shift
amount is implicitly brought into the range of 32-bit signed integers
using an implicit bit-wise and with 0x1f).
</p>
<div class="example">
<pre class="example">define(`max_int', eval(`0x7fffffff'))
&rArr;
define(`min_int', incr(max_int))
&rArr;
eval(min_int` &lt; 0')
&rArr;1
eval(max_int` &gt; 0')
&rArr;1
ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
&rArr;overflow occurred
min_int
&rArr;-2147483648
eval(`0x80000000 % -1')
&rArr;0
eval(`-4 &gt;&gt; 1')
&rArr;-2
eval(`-4 &gt;&gt; 33')
&rArr;-2
</pre></div>

<p>If <var>radix</var> is specified, it specifies the radix to be used in the
expansion.  The default radix is 10; this is also the case if
<var>radix</var> is the empty string.  A warning results if the radix is
outside the range of 1 through 36, inclusive.  The result of <code>eval</code>
is always taken to be signed.  No radix prefix is output, and for
radices greater than 10, the digits are lower case.  The <var>width</var>
argument specifies the minimum output width, excluding any negative
sign.  The result is zero-padded to extend the expansion to the
requested width.  A warning results if the width is negative.  If
<var>radix</var> or <var>width</var> is out of bounds, the expansion of
<code>eval</code> is empty.
</p>
<div class="example">
<pre class="example">eval(`666', `10')
&rArr;666
eval(`666', `11')
&rArr;556
eval(`666', `6')
&rArr;3030
eval(`666', `6', `10')
&rArr;0000003030
eval(`-666', `6', `10')
&rArr;-0000003030
eval(`10', `', `0')
&rArr;10
`0r1:'eval(`10', `1', `11')
&rArr;0r1:01111111111
eval(`10', `16')
&rArr;a
eval(`1', `37')
error&rarr;m4:stdin:9: radix 37 in builtin `eval' out of range
&rArr;
eval(`1', , `-1')
error&rarr;m4:stdin:10: negative width to builtin `eval'
&rArr;
eval()
error&rarr;m4:stdin:11: empty string treated as 0 in builtin `eval'
&rArr;0
</pre></div>

<hr>
<div class="header">
<p>
Previous: <a href="Incr.html#Incr" accesskey="p" rel="prev">Incr</a>, Up: <a href="Arithmetic.html#Arithmetic" accesskey="u" rel="up">Arithmetic</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
m4-doc 1.4.18-1 / usr / share / doc / m4-doc / Eval.html
