/usr/share/doc/m4-doc/Format.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: Format</title>

<meta name="description" content="GNU M4 1.4.18 macro processor: Format">
<meta name="keywords" content="GNU M4 1.4.18 macro processor: Format">
<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="Text-handling.html#Text-handling" rel="up" title="Text handling">
<link href="Arithmetic.html#Arithmetic" rel="next" title="Arithmetic">
<link href="Patsubst.html#Patsubst" rel="prev" title="Patsubst">
<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="Format"></a>
<div class="header">
<p>
Previous: <a href="Patsubst.html#Patsubst" accesskey="p" rel="prev">Patsubst</a>, Up: <a href="Text-handling.html#Text-handling" accesskey="u" rel="up">Text handling</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="Formatting-strings-_0028printf_002dlike_0029"></a>
<h3 class="section">11.7 Formatting strings (printf-like)</h3>

<a name="index-formatted-output"></a>
<a name="index-output_002c-formatted"></a>
<a name="index-GNU-extensions-13"></a>
<p>Formatted output can be made with <code>format</code>:
</p>
<dl>
<dt><a name="index-format"></a>Builtin: <strong>format</strong> <em>(<var>format-string</var>, &hellip;)</em></dt>
<dd><p>Works much like the C function <code>printf</code>.  The first argument
<var>format-string</var> can contain &lsquo;<samp>%</samp>&rsquo; specifications which are
satisfied by additional arguments, and the expansion of <code>format</code> is
the formatted string.
</p>
<p>The macro <code>format</code> is recognized only with parameters.
</p></dd></dl>

<p>Its use is best described by a few examples:
</p>
<div class="example">
<pre class="example">define(`foo', `The brown fox jumped over the lazy dog')
&rArr;
format(`The string &quot;%s&quot; uses %d characters', foo, len(foo))
&rArr;The string &quot;The brown fox jumped over the lazy dog&quot; uses 38 characters
format(`%*.*d', `-1', `-1', `1')
&rArr;1
format(`%.0f', `56789.9876')
&rArr;56790
len(format(`%-*X', `5000', `1'))
&rArr;5000
ifelse(format(`%010F', `infinity'), `       INF', `success',
       format(`%010F', `infinity'), `  INFINITY', `success',
       format(`%010F', `infinity'))
&rArr;success
ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
       format(`%.1A', `1.999'), `0X2.0P+0', `success',
       format(`%.1A', `1.999'))
&rArr;success
format(`%g', `0xa.P+1')
&rArr;20
</pre></div>

<p>Using the <code>forloop</code> macro defined earlier (see <a href="Forloop.html#Forloop">Forloop</a>), this
example shows how <code>format</code> can be used to produce tabular output.
</p>
<div class="example">
<pre class="example">$ <kbd>m4 -I examples</kbd>
include(`forloop.m4')
&rArr;
forloop(`i', `1', `10', `format(`%6d squared is %10d
', i, eval(i**2))')
&rArr;     1 squared is          1
&rArr;     2 squared is          4
&rArr;     3 squared is          9
&rArr;     4 squared is         16
&rArr;     5 squared is         25
&rArr;     6 squared is         36
&rArr;     7 squared is         49
&rArr;     8 squared is         64
&rArr;     9 squared is         81
&rArr;    10 squared is        100
&rArr;
</pre></div>

<p>The builtin <code>format</code> is modeled after the ANSI C &lsquo;<samp>printf</samp>&rsquo;
function, and supports these &lsquo;<samp>%</samp>&rsquo; specifiers: &lsquo;<samp>c</samp>&rsquo;, &lsquo;<samp>s</samp>&rsquo;,
&lsquo;<samp>d</samp>&rsquo;, &lsquo;<samp>o</samp>&rsquo;, &lsquo;<samp>x</samp>&rsquo;, &lsquo;<samp>X</samp>&rsquo;, &lsquo;<samp>u</samp>&rsquo;, &lsquo;<samp>a</samp>&rsquo;, &lsquo;<samp>A</samp>&rsquo;,
&lsquo;<samp>e</samp>&rsquo;, &lsquo;<samp>E</samp>&rsquo;, &lsquo;<samp>f</samp>&rsquo;, &lsquo;<samp>F</samp>&rsquo;, &lsquo;<samp>g</samp>&rsquo;, &lsquo;<samp>G</samp>&rsquo;, and
&lsquo;<samp>%</samp>&rsquo;; it supports field widths and precisions, and the flags
&lsquo;<samp>+</samp>&rsquo;, &lsquo;<samp>-</samp>&rsquo;, &lsquo;<samp> </samp>&rsquo;, &lsquo;<samp>0</samp>&rsquo;, &lsquo;<samp>#</samp>&rsquo;, and &lsquo;<samp>'</samp>&rsquo;.  For
integer specifiers, the width modifiers &lsquo;<samp>hh</samp>&rsquo;, &lsquo;<samp>h</samp>&rsquo;, and
&lsquo;<samp>l</samp>&rsquo; are recognized, and for floating point specifiers, the width
modifier &lsquo;<samp>l</samp>&rsquo; is recognized.  Items not yet supported include
positional arguments, the &lsquo;<samp>n</samp>&rsquo;, &lsquo;<samp>p</samp>&rsquo;, &lsquo;<samp>S</samp>&rsquo;, and &lsquo;<samp>C</samp>&rsquo;
specifiers, the &lsquo;<samp>z</samp>&rsquo;, &lsquo;<samp>t</samp>&rsquo;, &lsquo;<samp>j</samp>&rsquo;, &lsquo;<samp>L</samp>&rsquo; and &lsquo;<samp>ll</samp>&rsquo;
modifiers, and any platform extensions available in the native
<code>printf</code>.  For more details on the functioning of <code>printf</code>,
see the C Library Manual, or the POSIX specification (for
example, &lsquo;<samp>%a</samp>&rsquo; is supported even on platforms that haven&rsquo;t yet
implemented C99 hexadecimal floating point output natively).
</p>
<p>Unrecognized specifiers result in a warning.  It is anticipated that a
future release of GNU <code>m4</code> will support more specifiers,
and give better warnings when various problems such as overflow are
encountered.  Likewise, escape sequences are not yet recognized.
</p>
<div class="example">
<pre class="example">format(`%p', `0')
error&rarr;m4:stdin:1: Warning: unrecognized specifier in `%p'
&rArr;
</pre></div>


<hr>
<div class="header">
<p>
Previous: <a href="Patsubst.html#Patsubst" accesskey="p" rel="prev">Patsubst</a>, Up: <a href="Text-handling.html#Text-handling" accesskey="u" rel="up">Text handling</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 / Format.html
