From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 .../latex/contrib/l3experimental/l3str-format.dtx  | 982 +++++++++++++++++++++
 1 file changed, 982 insertions(+)
 create mode 100644 macros/latex/contrib/l3experimental/l3str-format.dtx

(limited to 'macros/latex/contrib/l3experimental/l3str-format.dtx')

diff --git a/macros/latex/contrib/l3experimental/l3str-format.dtx b/macros/latex/contrib/l3experimental/l3str-format.dtx
new file mode 100644
index 0000000000..17c2dad4a0
--- /dev/null
+++ b/macros/latex/contrib/l3experimental/l3str-format.dtx
@@ -0,0 +1,982 @@
+% \iffalse meta-comment
+%
+%% File: l3str-format.dtx
+%
+% Copyright (C) 2012-2019 The LaTeX3 Project
+%
+% It may be distributed and/or modified under the conditions of the
+% LaTeX Project Public License (LPPL), either version 1.3c of this
+% license or (at your option) any later version.  The latest version
+% of this license is in the file
+%
+%    https://www.latex-project.org/lppl.txt
+%
+% This file is part of the "l3experimental bundle" (The Work in LPPL)
+% and all files in that bundle must be distributed together.
+%
+% -----------------------------------------------------------------------
+%
+% The development version of the bundle can be found at
+%
+%    https://github.com/latex3/latex3
+%
+% for those people who are interested.
+%
+%<*driver|package>
+\RequirePackage{expl3}
+%</driver|package>
+%<*driver>
+\documentclass[full]{l3doc}
+\usepackage{amsmath}
+\begin{document}
+  \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+%
+% \title{^^A
+%   The \textsf{l3str-format} package: formatting strings of characters^^A
+% }
+%
+% \author{^^A
+%  The \LaTeX3 Project\thanks
+%    {^^A
+%      E-mail:
+%        \href{mailto:latex-team@latex-project.org}
+%          {latex-team@latex-project.org}^^A
+%    }^^A
+% }
+%
+% \date{Released 2019-08-25}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \section{Format specifications}
+%
+% In this module, we introduce the notion of a string \meta{format}.
+% The syntax follows that of Python's \texttt{format} built-in function.
+% A \meta{format specification} is a string of the form
+% \begin{equation*}
+%   \meta{format specification} = [[\meta{fill}]\meta{alignment}]
+%     [\meta{sign}] [\meta{width}] [.\meta{precision}] [\meta{style}]
+% \end{equation*}
+% where each $[\ldots]$ denotes an independent optional part.
+% \begin{itemize}
+%   \item \meta{fill} can be any character: it is assumed to be present
+%     whenever the second character of the \meta{format specification}
+%     is a valid \meta{alignment} character.
+%   \item \meta{alignment} can be |<|~(left alignment), |>|~(right
+%     alignment), |^|~(centering), or |=|~(for numeric types only).
+%   \item \meta{sign} is allowed for numeric types; it can be |+|~(show
+%     a sign for positive and negative numbers), |-|~(only put a sign
+%     for negative numbers), or a space~(show a space or a~|-|).
+%   \item \meta{width} is the minimum number of characters of the
+%     result: if the result is naturally shorter than this \meta{width},
+%     then it is padded with copies of the character \meta{fill}, with a
+%     position depending on the choice of \meta{alignment}.  If the
+%     result is naturally longer, it is not truncated.
+%   \item \meta{precision}, whose presence is indicated by a period,
+%     can have different meanings depending on the type.
+%   \item \meta{style} is one character, which controls how the given
+%     data should be formatted.  The list of allowed \meta{styles}
+%     depends on the type.
+% \end{itemize}
+% The choice of \meta{alignment} |=| is only valid for numeric types: in
+% this case the padding is inserted between the sign and the rest of the
+% number.
+%
+% \section{Formatting various data-types}
+%
+% \begin{function}[EXP]{\tl_format:Nn, \tl_format:cn, \tl_format:nn}
+%   \begin{syntax}
+%     \cs{tl_format:nn} \Arg{token list} \Arg{format specification}
+%   \end{syntax}
+%   Converts the \meta{token list} to a string according to the
+%   \meta{format specification}.  The \meta{style}, if present, must
+%   be~|s|.  If \meta{precision} is given, all characters of the string
+%   representation of the \meta{token list} beyond the first
+%   \meta{precision} characters are discarded.
+% \end{function}
+%
+% \begin{function}[EXP]{\seq_format:Nn, \seq_format:cn}
+%   \begin{syntax}
+%     \cs{seq_format:Nn} \Arg{sequence} \Arg{format specification}
+%   \end{syntax}
+%   Converts each item in the \meta{sequence} to a string according to
+%   the \meta{format specification}, and concatenates the results.
+% \end{function}
+%
+% \begin{function}[EXP]{\int_format:nn}
+%   \begin{syntax}
+%     \cs{int_format:nn} \Arg{intexpr} \Arg{format specification}
+%   \end{syntax}
+%   Evaluates the \meta{integer expression} and converts the result to a
+%   string according to the \meta{format specification}.  The
+%   \meta{precision} argument is not allowed.  The \meta{style} can be
+%   |b| for binary output, |d| for decimal output (this is the default),
+%   |o| for octal output, |X| for hexadecimal output (using capital
+%   letters).
+% \end{function}
+%
+% \begin{function}[EXP]{\fp_format:nn}
+%   \begin{syntax}
+%     \cs{fp_format:nn} \Arg{fpexpr} \Arg{format specification}
+%   \end{syntax}
+%   Evaluates the \meta{floating point expression} and converts the
+%   result to a string according to the \meta{format specification}.
+%   The \meta{style} can be
+%   \begin{itemize}
+%     \item |e| for scientific notation, with one digit before and
+%       \meta{precision} digits after the decimal separator, and an
+%       integer exponent, following |e|;
+%     \item |f| for a fixed point notation, with \meta{precision} digits
+%       after the decimal separator and no exponent;
+%     \item |g| for a general format, which uses style |f| for numbers
+%       in the range $[10^{-4}, 10^{\meta{precision}})$ and style |e|
+%       otherwise.
+%   \end{itemize}
+%   When there is no \meta{style} specifier nor \meta{precision} the
+%   number is displayed without rounding.  Otherwise the
+%   \meta{precision} defaults to~$6$.
+% \end{function}
+%
+% \section{Possibilities, and things to do}
+%
+% \begin{itemize}
+%   \item Provide a token list formatting \meta{style} which keeps the
+%     last \meta{precision} characters rather than the first
+%     \meta{precision}.
+% \end{itemize}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3str-format} implementation}
+%
+%    \begin{macrocode}
+%<*initex|package>
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%<@@=str>
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%<*package>
+\ProvidesExplPackage{l3str-format}{2019-08-25}{}
+  {L3 Experimental string formatting}
+%</package>
+%    \end{macrocode}
+%
+% \subsection{Helpers}
+%
+% \begin{macro}[EXP]{\use:nf, \use:fnf}
+%   A simple variant.
+%    \begin{macrocode}
+\cs_generate_variant:Nn \use:nn { nf }
+\cs_generate_variant:Nn \use:nnn { fnf }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\tl_to_str:f}
+%   A simple variant.
+%    \begin{macrocode}
+\cs_generate_variant:Nn \tl_to_str:n { f }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_if_digit:NTF}
+%   Here we expect |#1| to be a character with category other, or
+%   \cs{s_stop}.
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \@@_format_if_digit:N #1 { TF }
+  {
+    \if_int_compare:w 9 < 1 #1 \exp_stop_f:
+      \prg_return_true: \else: \prg_return_false: \fi:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]
+%   {\@@_format_put:nw, \@@_format_put:ow, \@@_format_put:fw}
+%   Put |#1| after an \cs{s_stop} delimiter.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_put:nw #1 #2 \s_stop { #2 \s_stop #1 }
+\cs_generate_variant:Nn \@@_format_put:nw { o , f }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP, TF]{\@@_format_if_in:nN}
+% \begin{macro}[EXP]{\@@_format_if_in_aux:NN}
+%   A copy of \cs{@@_if_contains_char:nNTF} to avoid relying on
+%   this weird internal string function.
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \@@_format_if_in:nN #1#2 { TF }
+  {
+    \@@_format_if_in_aux:NN #2 #1
+      { #2 \prg_return_false: \exp_after:wN \prg_break: \else: }
+    \prg_break_point:
+  }
+\cs_new:Npn \@@_format_if_in_aux:NN #1#2
+  {
+    \if_charcode:w #1 #2
+      \prg_return_true:
+      \exp_after:wN \prg_break:
+    \fi:
+    \@@_format_if_in_aux:NN #1
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Parsing a format specification}
+%
+% \begin{macro}[EXP]{\@@_format_parse:n}
+% \begin{macro}[EXP]
+%   {
+%     \@@_format_parse_auxi:NN,
+%     \@@_format_parse_auxii:nN,
+%     \@@_format_parse_auxiii:nN,
+%     \@@_format_parse_auxiv:nwN,
+%     \@@_format_parse_auxv:nN,
+%     \@@_format_parse_auxvi:nwN,
+%     \@@_format_parse_auxvii:nN,
+%     \@@_format_parse_end:nwn,
+%   }
+%   The goal is to parse
+%   \begin{equation*}
+%     \meta{format specification} = [[\meta{fill}]\meta{alignment}]
+%     [\meta{sign}] [\meta{width}] [.\meta{precision}] [\meta{style}]
+%   \end{equation*}
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_parse:n #1
+  {
+    \exp_last_unbraced:Nf \@@_format_parse_auxi:NN
+      { \__kernel_str_to_other:n {#1} } \s_stop \s_stop {#1}
+  }
+\cs_new:Npx \@@_format_parse_auxi:NN #1#2
+  {
+    \exp_not:N \@@_format_if_in:nNTF { < > = ^ } #2
+      { \exp_not:N \@@_format_parse_auxiii:nN { #1 #2 } }
+      {
+        \exp_not:N \@@_format_parse_auxii:nN
+          { \c_catcode_other_space_tl } #1 #2
+      }
+  }
+\cs_new:Npn \@@_format_parse_auxii:nN #1#2
+  {
+    \@@_format_if_in:nNTF { < > = ^ } #2
+      { \@@_format_parse_auxiii:nN { #1 #2 } }
+      { \@@_format_parse_auxiii:nN { #1 ? } #2 }
+  }
+\cs_new:Npx \@@_format_parse_auxiii:nN #1#2
+  {
+    \exp_not:N \@@_format_if_in:nNTF
+      { + - \c_catcode_other_space_tl }
+      #2
+      { \exp_not:N \@@_format_parse_auxiv:nwN { #1 #2 } ; }
+      { \exp_not:N \@@_format_parse_auxiv:nwN { #1 ? } ; #2 }
+  }
+\cs_new:Npn \@@_format_parse_auxiv:nwN #1#2; #3
+  {
+    \@@_format_if_digit:NTF #3
+      { \@@_format_parse_auxiv:nwN {#1} #2 #3 ; }
+      { \@@_format_parse_auxv:nN { #1 {#2} } #3 }
+  }
+\cs_new:Npn \@@_format_parse_auxv:nN #1#2
+  {
+    \token_if_eq_charcode:NNTF . #2
+      { \@@_format_parse_auxvi:nwN {#1} 0 ; }
+      { \@@_format_parse_auxvii:nN { #1 { } } #2 }
+  }
+\cs_new:Npn \@@_format_parse_auxvi:nwN #1#2; #3
+  {
+    \@@_format_if_digit:NTF #3
+      { \@@_format_parse_auxvi:nwN {#1} #2 #3 ; }
+      { \@@_format_parse_auxvii:nN { #1 {#2} } #3 }
+  }
+\cs_new:Npn \@@_format_parse_auxvii:nN #1#2
+  {
+    \token_if_eq_meaning:NNTF \s_stop #2
+      { \@@_format_parse_end:nwn { #1 ? } #2 }
+      { \@@_format_parse_end:nwn { #1 #2 } }
+  }
+\cs_new:Npn \@@_format_parse_end:nwn #1 #2 \s_stop \s_stop #3
+  {
+    \tl_if_empty:nF {#2}
+      { \__kernel_msg_expandable_error:nnn { str } { invalid-format } {#3} }
+    #1
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Alignment}
+%
+% The $4$ functions in this section receive an \meta{body}, a
+% \meta{sign}, a \meta{width} and a \meta{fill} character (exactly one
+% character).  For non-numeric types, the \meta{sign} is empty and the
+% \meta{body} is the (other) string we want to format.  For numeric
+% types, we wish to format \meta{sign} \meta{body} (both are other
+% strings).  The alignment types |<|, |>| and |^| keep \meta{sign} and
+% \meta{body} together.  The |=| alignment type, however, inserts the
+% padding between the \meta{sign} and the \meta{body}, hence the need to
+% keep those separate.
+%
+% \begin{macro}[EXP]{\@@_format_align_<:nnnN}
+%   \begin{quote}
+%     \cs{@@_format_align_<:nnnN} \Arg{body} \Arg{sign} \Arg{width}
+%     \meta{fill}
+%   \end{quote}
+%   Aligning \enquote{\meta{sign} \meta{body}} to the left
+%   entails appending |#4| the correct number of times.  Then convert
+%   the result to a string.
+%    \begin{macrocode}
+\cs_new:cpn { @@_format_align_<:nnnN } #1#2#3#4
+  {
+    \use:nf { #2 #1 }
+      {
+        \prg_replicate:nn
+          { \int_max:nn { #3 - \@@_count:n { #2 #1 } } { 0 } }
+          {#4}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_align_>:nnnN}
+%   \begin{quote}
+%     \cs{@@_format_align_>:nnnN} \Arg{body} \Arg{sign} \Arg{width}
+%     \meta{fill}
+%   \end{quote}
+%   Aligning an \enquote{\meta{sign} \meta{body}} to the right
+%   entails prepending |#4| the correct number of times.  Then convert
+%   the result to a string.
+%    \begin{macrocode}
+\cs_new:cpn { @@_format_align_>:nnnN } #1#2#3#4
+  {
+    \prg_replicate:nn
+      { \int_max:nn { #3 - \@@_count:n { #2 #1 } } { 0 } }
+      {#4}
+    #2 #1
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begingroup\catcode`\^=12
+% \begin{macro}[EXP]{\@@_format_align_^:nnnN}
+%   \begin{quote}
+%     \cs{@@_format_align_^:nnnN} \Arg{body} \Arg{sign} \Arg{width}
+%     \meta{fill}
+%   \end{quote}
+%   Centering \enquote{\meta{sign} \meta{body}} entails
+%   prepending and appending |#4| the correct number of times.  If the
+%   number of |#4| to be added is odd, we add one more after than
+%   before.
+%    \begin{macrocode}
+\cs_new:cpn { @@_format_align_^:nnnN } #1#2#3#4
+  {
+    \use:fnf
+      {
+        \prg_replicate:nn
+          {
+            \int_max:nn { 0 }
+              { #3 - \@@_count:n { #2 #1 } - 1 }
+            / 2
+          }
+          {#4}
+      }
+      { #2 #1 }
+      {
+        \prg_replicate:nn
+          {
+            \int_max:nn { 0 }
+              { #3 - \@@_count:n { #2 #1 } }
+            / 2
+          }
+          {#4}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+% \endgroup
+%
+% \begin{macro}[EXP]{\@@_format_align_=:nnnN}
+%   \begin{quote}
+%     \cs{@@_format_align_=:nnnN} \Arg{body} \Arg{sign} \Arg{width}
+%     \meta{fill}
+%   \end{quote}
+%   The special numeric alignment |=| means that we insert the
+%   appropriate number of copies of |#4| between the \meta{sign} and the
+%   \meta{body}.  Then convert the result to a string.
+%    \begin{macrocode}
+\cs_new:cpn { @@_format_align_=:nnnN } #1#2#3#4
+  {
+    \use:nf {#2}
+      {
+        \prg_replicate:nn
+          { \int_max:nn { #3 - \@@_count:n { #2 #1 } } { 0 } }
+          {#4}
+      }
+    #1
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Formatting token lists}
+%
+% \begin{macro}[EXP]{\tl_format:Nn, \tl_format:cn, \tl_format:nn}
+%   Call \cs{@@_format_tl:NNNnnNn} to read the parsed \meta{format
+%     specification}.  Then convert the result to a string.
+%    \begin{macrocode}
+\cs_new:Npn \tl_format:Nn { \exp_args:No \tl_format:nn }
+\cs_generate_variant:Nn \tl_format:Nn { c }
+\cs_new:Npn \tl_format:nn #1#2
+  {
+    \tl_to_str:f
+      {
+        \exp_last_unbraced:Nf \@@_format_tl:NNNnnNn
+          { \@@_format_parse:n {#2} }
+          {#1}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_tl:NNNnnNn}
+%   \begin{quote}
+%     \cs{@@_format_tl:NNNnnNn} \meta{fill} \meta{alignment} \meta{sign}
+%     \Arg{width} \Arg{precision} \meta{style} \Arg{token list}
+%   \end{quote}
+%   First check that the \meta{alignment} is not |=|, and set the
+%   default alignment |?| to |<|.  Place the modified information after
+%   a trailing \cs{s_stop} for later retrieval.  Then check that there
+%   was no \meta{sign}.  The width will be useful later, store it after
+%   \cs{s_stop}.  Afterwards, store the precision, and the function
+%   \cs{@@_range:nnn} that will be used to extract the first
+%   |#5| characters of the string.
+%   There is a need to use the internal function, as otherwise
+%   leading spaces would get stripped by |f|-expansion.  Finally, check
+%   that the \meta{style} is |?| or |s|.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_tl:NNNnnNn #1#2#3#4#5#6
+  {
+    \token_if_eq_charcode:NNTF #2 =
+      {
+        \__kernel_msg_expandable_error:nnnn
+          { str } { invalid-align-format } {#2} {tl}
+        \@@_format_put:nw { #1 < }
+      }
+      {
+        \token_if_eq_charcode:NNTF #2 ?
+          { \@@_format_put:nw { #1 < } }
+          { \@@_format_put:nw { #1 #2 } }
+      }
+    \token_if_eq_charcode:NNF #3 ?
+      {
+        \__kernel_msg_expandable_error:nnnn
+          { str } { invalid-sign-format } {#3} {tl}
+      }
+    \@@_format_put:nw { {#4} }
+    \tl_if_empty:nTF {#5}
+      { \@@_format_put:nw { \@@_range:nnn { {1} {-1} } } }
+      { \@@_format_put:nw { \@@_range:nnn { {1} {#5} } } }
+    \token_if_eq_charcode:NNF #6 s
+      {
+        \token_if_eq_charcode:NNF #6 ?
+          {
+            \__kernel_msg_expandable_error:nnnn
+              { str } { invalid-style-format } {#6} {tl}
+          }
+      }
+    \@@_format_tl_s:NNnnNNn
+    \s_stop
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_tl_s:NNnnNNn}
+%   \begin{quote}
+%     \cs{@@_format_tl_s:NNnnNNn} \cs{s_stop} \meta{function}
+%     \Arg{arguments} \Arg{width} \meta{fill} \meta{alignment}
+%     \Arg{token list}
+%   \end{quote}
+%   The \meta{function} and \meta{arguments} are built in such a way
+%   that |f|-expanding \meta{function} \Arg{other string}
+%   \meta{arguments} yields the piece of the \meta{other string} that we
+%   want to output.  The \meta{other string} is built from the
+%   \meta{token list} by |f|-expanding \cs{__kernel_str_to_other:n}.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_tl_s:NNnnNNn #1#2#3#4#5#6#7
+  {
+    \exp_args:Nc \exp_args:Nf
+      { @@_format_align_#6:nnnN }
+      { \exp_args:Nf #2 { \__kernel_str_to_other:n {#7} } #3 }
+      { }
+      {#4} #5
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Formatting sequences}
+%
+% \begin{macro}[EXP]{\seq_format:Nn, \seq_format:cn}
+%   Each item is formatted as a token list according to the
+%   specification.  First parse the format and expand the sequence, then
+%   loop through the items.  Eventually, convert to a string.
+%    \begin{macrocode}
+\cs_new:Npn \seq_format:Nn #1#2
+  {
+    \tl_to_str:f
+      {
+        \@@_format_seq:ff
+          { \exp_after:wN \use_i:nn \exp_after:wN \exp_stop_f: #1 }
+          { \@@_format_parse:n {#2} }
+      }
+  }
+\cs_generate_variant:Nn \seq_format:Nn { c }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_seq:nn, \@@_format_seq:ff}
+%   The first argument is the contents of a \texttt{seq} variable.  The
+%   second is a parsed \meta{format specification}.  Set up the loop.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_seq:nn #1#2
+  {
+    \@@_format_seq_loop:nnNn { } {#2}
+      #1
+      { ? \@@_format_seq_end:w } { }
+  }
+\cs_generate_variant:Nn \@@_format_seq:nn { ff }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_seq_loop:nnNn}
+%   \begin{quote}
+%     \cs{@@_format_seq_loop:nnNn} \Arg{done} \Arg{parsed format}
+%     \cs{__seq_item:n} \Arg{item}
+%   \end{quote}
+%   The first argument is the result of formatting the items read so
+%   far.  The third argument is a single token (\cs{__seq_item:n}),
+%   until we reach the end of the sequence, where |\use_none:n #3| ends
+%   the loop.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_seq_loop:nnNn #1#2#3#4
+  {
+    \use_none:n #3
+    \exp_args:Nf \@@_format_seq_loop:nnNn
+      { \use:nf {#1} { \@@_format_tl:NNNnnNn #2 {#4} } }
+      {#2}
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_seq_end:w}
+%   Pick the right piece in the loop above.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_seq_end:w #1#2#3#4 { \use_ii:nnn #3 }
+%    \end{macrocode}
+% \end{macro}
+%
+% \subsection{Formatting integers}
+%
+% \begin{macro}[EXP]{\int_format:nn}
+%   Evaluate the first argument and feed it to \cs{@@_format_int:nn}.
+%    \begin{macrocode}
+\cs_new:Npn \int_format:nn #1
+  { \exp_args:Nf \@@_format_int:nn { \int_eval:n {#1} } }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_int:nn}
+%   Parse the \meta{format specification} and feed it to
+%   \cs{@@_format_int:NNNnnNn}.  Then convert the result to a string
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_int:nn #1#2
+  {
+    \tl_to_str:f
+      {
+        \exp_last_unbraced:Nf \@@_format_int:NNNnnNn
+          { \@@_format_parse:n {#2} }
+          {#1}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_int:NNNnnNn}
+%   \begin{quote}
+%     \cs{@@_format_int:NNNnnNn} \meta{fill} \meta{alignment}
+%     \meta{sign} \Arg{width} \Arg{precision} \meta{style} \Arg{integer}
+%   \end{quote}
+%   First set the
+%   default alignment |?| to |>|.  Place the modified information after
+%   a trailing \cs{s_stop} for later retrieval.  Then check the
+%   \meta{sign}: if the integer is negative, always put~|-|.  Otherwise,
+%   if the format's \meta{sign} is |~|, put a space (with category
+%   \enquote{other}); if it is~|+| put |+|; if it is |-| (default), put
+%   nothing, represented as a brace group.  The width |#4| will be
+%   useful later, store it after \cs{s_stop}.  Afterwards, check that
+%   the \meta{precision} was absent.  Finally, dispatch depending on the
+%   \meta{style}.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_int:NNNnnNn #1#2#3#4#5#6#7
+  {
+    \token_if_eq_charcode:NNTF #2 ?
+      { \@@_format_put:nw { #1 > } }
+      { \@@_format_put:nw { #1 #2 } }
+    \int_compare:nNnTF {#7} < 0
+      { \@@_format_put:nw { - } }
+      {
+        \str_case:nnF {#3}
+          {
+            { ~ } { \@@_format_put:ow { \c_catcode_other_space_tl } }
+            { + } { \@@_format_put:nw { + } }
+          }
+          { \@@_format_put:nw { { } } }
+      }
+    \@@_format_put:nw { {#4} }
+    \tl_if_empty:nF {#5}
+      {
+        \__kernel_msg_expandable_error:nnnn
+          { str } { invalid-precision-format } {#5} {int}
+      }
+    \str_case:nnF {#6}
+      {
+        { ? } { \@@_format_int:NwnnNNn \use:n }
+        { d } { \@@_format_int:NwnnNNn \use:n }
+        { b } { \@@_format_int:NwnnNNn \int_to_bin:n }
+        { o } { \@@_format_int:NwnnNNn \int_to_oct:n }
+        { X } { \@@_format_int:NwnnNNn \int_to_Hex:n }
+      }
+      {
+        \__kernel_msg_expandable_error:nnnn
+          { str } { invalid-style-format } {#6} { int }
+        \@@_format_int:NwnnNNn \use:n
+      }
+    \s_stop {#7}
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_int:NwnnNNn}
+%   \begin{quote}
+%     \cs{@@_format_int:NwnnNNn} \meta{function} \cs{s_stop}
+%     \Arg{width} \Arg{sign} \meta{fill} \meta{alignment} \Arg{integer}
+%   \end{quote}
+%   Use the |format_align| function corresponding to the
+%   \meta{alignment}, with the following arguments:
+%   \begin{itemize}
+%     \item the string formed by combining the sign |#4| with the result
+%       of converting the absolute value of the \meta{integer} |#7|
+%       according to the conversion function |#1|;
+%     \item the \meta{width};
+%     \item the \meta{fill} character.
+%   \end{itemize}
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_int:NwnnNNn #1#2 \s_stop #3#4#5#6#7
+  {
+    \exp_args:Nc \exp_args:Nf
+      { @@_format_align_#6:nnnN }
+      { #1 { \int_abs:n {#7} } }
+      {#4}
+      {#3} #5
+  }
+%    \end{macrocode}
+% ^^A todo: note similarity with  \@@_format_tl_s:NNnnNNn
+% \end{macro}
+%
+% \subsection{Formatting floating points}
+%
+% \begin{macro}[EXP]{\fp_format:nn}
+%   Evaluate the first argument to a floating point number, and feed it
+%   to \cs{@@_format_fp:nn}.  It would be more efficient to use internal
+%   floating point numbers but efficiency is not essential and the code
+%   is cleaner this way.
+%    \begin{macrocode}
+\cs_new:Npn \fp_format:nn #1
+  { \exp_args:Nf \@@_format_fp:nn { \fp_to_tl:n {#1} } }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp:nn}
+%   Parse the \meta{format specification} and feed it to
+%   \cs{@@_format_fp:NNNnnNn}.  Then convert the result to a string
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp:nn #1#2
+  {
+    \tl_to_str:f
+      {
+        \exp_last_unbraced:Nf \@@_format_fp:NNNnnNn
+          { \@@_format_parse:n {#2} }
+          {#1}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp:NNNnnNn}
+%   \begin{quote}
+%     \cs{@@_format_fp:NNNnnNn} \meta{fill} \meta{alignment}
+%     \meta{format sign} \Arg{width} \Arg{precision} \meta{style}
+%     \Arg{floating point}
+%   \end{quote}
+%   First set the default alignment |?| to |>|.  Place the modified
+%   information after a trailing \cs{s_stop} for later retrieval.  Then
+%   check the \meta{format sign} and the \meta{fp sign}: if the floating
+%   point is negative, always put~|-|.  Otherwise (including
+%   \texttt{nan}), if the format's \meta{sign} is |~|, put a space (with
+%   category \enquote{other}); if it is~|+| put |+|; if it is |-|
+%   (default), put nothing, represented as a brace group.  The width
+%   |#4| will be useful later, store it after \cs{s_stop}.  Afterwards,
+%   check the \meta{precision}: if it was not given, replace it by $6$
+%   (default precision) unless no \meta{style} was given: in that case
+%   we want to use whatever precision is needed to fully describe the
+%   number.  Finally, dispatch depending on the \meta{style}.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp:NNNnnNn
+    #1#2#3#4#5#6#7
+  {
+    \token_if_eq_charcode:NNTF #2 ?
+      { \@@_format_put:nw { #1 > } }
+      { \@@_format_put:nw { #1 #2 } }
+    \tl_if_head_eq_charcode:nNTF {#7} -
+      { \@@_format_put:nw { - } }
+      {
+        \str_case:nnF {#3}
+          {
+            { ~ } { \@@_format_put:ow { \c_catcode_other_space_tl } }
+            { + } { \@@_format_put:nw { + } }
+          }
+          { \@@_format_put:nw { { } } }
+      }
+    \@@_format_put:nw { {#4} }
+    \tl_if_empty:nTF {#5}
+      {
+        \token_if_eq_meaning:NNTF #6 ?
+          { \@@_format_put:nw { {  } } }
+          { \@@_format_put:nw { { 6} } }
+      }
+      { \@@_format_put:nw { {#5} } }
+    \str_case:nnF {#6}
+      {
+        { e } { \@@_format_fp:wnnnNNn \@@_format_fp_e:nn }
+        { f } { \@@_format_fp:wnnnNNn \@@_format_fp_f:nn }
+        { g } { \@@_format_fp:wnnnNNn \@@_format_fp_g:nn }
+        { ? } { \@@_format_fp:wnnnNNn \@@_format_fp_g:nn }
+      }
+      {
+        \__kernel_msg_expandable_error:nnnn
+          { str } { invalid-style-format } {#6} { fp }
+        \@@_format_fp:wnnnNNn \@@_format_fp_g:nn
+      }
+    \s_stop {#7}
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp:wnnnNNn}
+%   \begin{quote}
+%     \cs{@@_format_fp:wnnnNNn} \meta{formatting function} \cs{s_stop}
+%     \Arg{precision} \Arg{width} \Arg{sign} \meta{fill}
+%     \meta{alignment} \Arg{floating point}
+%   \end{quote}
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp:wnnnNNn
+    #1 \s_stop #2 #3 #4 #5#6 #7
+  {
+    \exp_args:Nc \exp_args:Nf
+      { @@_format_align_#6:nnnN }
+      { #1 {#7} {#2} }
+      {#4}
+      {#3} #5
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp_round:nn}
+%   Round the given floating point and take the absolute value (in this
+%   order, to play nicely with unusual rounding modes if we ever
+%   implement these).
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp_round:nn #1 #2
+  { \fp_to_tl:n { abs ( round ( #1 , #2 - logb(#1) - 1 ) ) } }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp_e:nn}
+% \begin{macro}[EXP]{\@@_format_fp_e_aux:nn, \@@_format_fp_e_aux:wwn}
+%   With the |e| type, first round to |#4+1| significant figures (one
+%   before the decimal separator, |#4| after), then filter out special
+%   cases, then convert to scientific notations.  This order is
+%   important because rounding can produce infinities or zeros and
+%   because \cs{fp_to_scientific:n} does not accept |nan| nor |inf|.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp_e:nn #1#2
+  {
+    \exp_args:Nf \@@_format_fp_e_aux:nn
+      { \@@_format_fp_round:nn {#1} { #2 + 1 } }
+      {#2}
+  }
+\cs_new:Npn \@@_format_fp_e_aux:nn #1#2
+  {
+    \str_case:nnF {#1}
+      {
+        {  inf } { inf }
+        {  nan } { nan }
+      }
+      {
+        \exp_last_unbraced:Nf \@@_format_fp_e_aux:wwn
+          { \fp_to_scientific:n {#1} } ;
+          {#2}
+      }
+  }
+\cs_new:Npn \@@_format_fp_e_aux:wwn #1 . #2 e #3 ; #4
+  {
+    \@@_format_put:nw { e #3 }
+    \int_compare:nNnTF {#4} < \c__fp_prec_int
+      {
+        \@@_format_put:fw { \str_range:nnn { #2 } { 1 } { #4 } }
+        \@@_format_put:nw { #1 . }
+      }
+      {
+        \@@_format_put:fw
+          { \prg_replicate:nn { #4 - \c__fp_prec_int + 1 } { 0 } }
+        \@@_format_put:nw { #1 . #2 }
+      }
+    \use_none:n \s_stop
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp_f:nn}
+% \begin{macro}[EXP]{\@@_format_fp_f_aux:wwwn}
+%   With the |f| type, first round to |#4| (absolute) decimal places
+%   then filter out special cases, then in normal cases pad with zeros.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp_f:nn #1#2
+  {
+    \exp_args:Nf \@@_format_fp_f_aux:nn
+      { \fp_to_tl:n { abs ( round ( #1 , #2 ) ) } }
+      {#2}
+  }
+\cs_new:Npn \@@_format_fp_f_aux:nn #1#2
+  {
+    \str_case:nnF {#1}
+      {
+        { inf } { inf }
+        { nan } { nan }
+      }
+      {
+        \exp_last_unbraced:Nf \@@_format_fp_f_aux:wwwn
+          { \fp_to_decimal:n {#1} } . . ; {#2}
+      }
+  }
+\cs_new:Npn \@@_format_fp_f_aux:wwwn #1 . #2 . #3 ; #4
+  {
+    \use:nf { #1 . #2 }
+      { \prg_replicate:nn { #4 - \@@_count:n {#2} } {0} }
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp_g:nn}
+% \begin{macro}[EXP]{\@@_format_fp_g_aux:wn}
+% \begin{macro}[EXP]{\@@_format_fp_to_scientific:n, \@@_format_fp_trim:w}
+%   With the |g| type, a special case is when |#2| is empty (no style
+%   nor precision in the original specification): then we output the
+%   number without rounding (and without its sign).  Otherwise round to
+%   |#2| significant figures before filtering out special cases.  (A
+%   \meta{precision} of $0$ is treated like a precision of $1$.)
+%   Distinguish exponents $-4\leq \meta{exponent} < \meta{precision}$
+%   from others and use essentially the |f| or |e| presentations in
+%   these two cases, but trimming trailing zeros.  Because we don't need
+%   to keep a fixed number of digits after the decimal point we can
+%   simply use \cs{fp_to_decimal:n} and \cs{fp_to_scientific:n}, and in
+%   the second case post-process the result by trimming zeros and a
+%   period.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp_g:nn #1#2
+  {
+    \tl_if_empty:nTF {#2} { \fp_to_tl:n { abs(#1) } }
+      {
+        \exp_args:Nf \@@_format_fp_g_aux:nn
+          { \@@_format_fp_round:nn {#1} { \int_max:nn {1} {#2} } }
+          { \int_max:nn {1} {#2} }
+      }
+  }
+\cs_new:Npn \@@_format_fp_g_aux:nn #1#2
+  {
+    \str_case:nnF {#1}
+      {
+        { 0 } { 0 }
+        { inf } { inf }
+        { nan } { nan }
+      }
+      {
+        \fp_compare:nTF { 1e-4 <= #1 < 1e#2 }
+          { \fp_to_decimal:n {#1} }
+          {
+            \exp_last_unbraced:Nf \@@_format_fp_trim:w
+              { \fp_to_scientific:n {#1} }
+          }
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\@@_format_fp_trim:w}
+% \begin{macro}[EXP]
+%   {\@@_format_fp_trim_loop:w, \@@_format_fp_trim_dot:w, \@@_format_fp_trim_end:w}
+%   If |#1| ends with a $0$, the \texttt{loop} auxiliary takes that zero
+%   as an end-delimiter for its first argument, and the second argument
+%   is the same \texttt{loop} auxiliary.  Once the last trailing zero is
+%   reached, the second argument is the \texttt{dot} auxiliary,
+%   which removes a trailing dot if any.  We then clean-up with the
+%   \texttt{end} auxiliary, keeping only the number.
+%    \begin{macrocode}
+\cs_new:Npn \@@_format_fp_trim:w #1 e
+  {
+    \@@_format_fp_trim_loop:w #1
+      ; \@@_format_fp_trim_loop:w 0; \@@_format_fp_trim_dot:w .; \s_stop e
+  }
+\cs_new:Npn \@@_format_fp_trim_loop:w #1 0; #2 { #2 #1 ; #2 }
+\cs_new:Npn \@@_format_fp_trim_dot:w #1 .; { \@@_format_fp_trim_end:w #1 ; }
+\cs_new:Npn \@@_format_fp_trim_end:w #1 ; #2 \s_stop { #1 }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Messages}
+%
+% All of the messages are produced expandably, so there is no need for
+% an extra-text.
+%    \begin{macrocode}
+\__kernel_msg_new:nnn { str } { invalid-format }
+  { Invalid~format~'#1'. }
+\__kernel_msg_new:nnn { str } { invalid-align-format }
+  { Invalid~alignment~'#1'~for~type~'#2'. }
+\__kernel_msg_new:nnn { str } { invalid-sign-format }
+  { Invalid~sign~'#1'~for~type~'#2'. }
+\__kernel_msg_new:nnn { str } { invalid-precision-format }
+  { Invalid~precision~'#1'~for~type~'#2'. }
+\__kernel_msg_new:nnn { str } { invalid-style-format }
+  { Invalid~style~'#1'~for~type~'#2'. }
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%</initex|package>
+%    \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex
-- 
cgit v1.2.3

