[nasm:master] doc: document the %num() function

[nasm-bot for H. Peter Anvin]

Commit-ID:  e7dd0e8e3f6c314938fba573cd5cbef86f9ed9b8
Gitweb:     http://repo.or.cz/w/nasm.git?a=commitdiff;h=e7dd0e8e3f6c314938fba573cd5cbef86f9ed9b8
Author:     H. Peter Anvin <hpa at zytor.com>
AuthorDate: Tue, 15 Nov 2022 17:12:25 -0800
Committer:  H. Peter Anvin <hpa at zytor.com>
CommitDate: Tue, 15 Nov 2022 17:13:22 -0800

doc: document the %num() function

Add documentation for the %num() preprocessor function.

Signed-off-by: H. Peter Anvin <hpa at zytor.com>


---
 doc/nasmdoc.src | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 111dea36..39c38480 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -2255,6 +2255,17 @@ and \i{detokenization} are performed for the arguments of the
 directives.
 
 
+\S{pcdirect} \i{Directives} processing
+
+Remaining preprocessor \i{directives} are processed. It is specific
+to each directive to what extend the above expansions or the ones
+specified in \k{pcfinal} are performed on their arguments.
+
+It is specific to each directive to what extent \i{inline expansions}
+and \i{detokenization} are performed for the arguments of the
+directives.
+
+
 \S{pcsmacro} \i{Inline expansions} and other \I{preprocessor directives}directives
 
 In this step, the following expansions are performed on each line:
@@ -2276,10 +2287,6 @@ below), the parameters to that macro are expanded at this time. See
 \b \i{Macro-local labels} are converted into unique strings, see
 \k{maclocal}.
 
-\b Remaining preprocessor \i{directives} are processed. It is specific
-to each directive to what extend the above expansions or the ones
-specified in \k{pcfinal} are performed on their arguments.
-
 
 \S{pcmmacro} \i{Multi-Line Macro Expansion}
 
@@ -2923,6 +2930,26 @@ argument to the conditional using \c{\{\}}:
 \c %endif
 
 
+\S{f_num} \i\c{%num()} Function
+
+The \c{%num()} function evaluates its arguments as expressions, and
+then produces a quoted string encoding the first argument as an
+\e{unsigned} integer. The second argument is the encoding base (from 2
+to 64, default 10) and the third argument is the desired number of
+digits (max 253, default -1).
+
+Only the first argument is required.
+
+If the number of digits is negative, NASM will add additional digits
+if needed, if positive the string is truncated to the number of digits
+specified. 0 is treated as -1, except that the input number 0
+generates an empty string (thus, the first digit will never be zero.)
+
+The full 64-symbol set used is, in order:
+
+\c 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ at _
+
+
 \S{f_sel} \i\c{%sel()} Function
 
 The \c{%sel()} function evaluates its first argument as an