l3str-format.dtx

% \iffalse meta-comment
%
%% File: l3str-format.dtx Copyright (C) 2012-2018 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 2018-10-17}
%
% \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{precision} defaults to $6$.  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}
% \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}{2018-10-17}{}
  {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 an internal floating point number, and
%   feed it to \cs{@@_format_fp:nn}.
%    \begin{macrocode}
\cs_new:Npn \fp_format:nn #1
  { \exp_args:Nf \@@_format_fp:nn { \__fp_parse: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:NNNnnNw
          { \@@_format_parse:n {#2} }
          #1
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_format_fp:NNNnnNw}
%   \begin{quote}
%     \cs{@@_format_fp:NNNnnNw} \meta{fill} \meta{alignment}
%     \meta{format sign} \Arg{width} \Arg{precision} \meta{style}
%     \cs{s__fp} \cs{__fp_chk:w} \meta{fp type} \meta{fp sign} \meta{fp
%       body} |;|
%   \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).  Finally, dispatch depending on the
%   \meta{style}.
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp:NNNnnNw
    #1#2#3#4#5#6 \s__fp \__fp_chk:w #7 #8
  {
    \token_if_eq_charcode:NNTF #2 ?
      { \@@_format_put:nw { #1 > } }
      { \@@_format_put:nw { #1 #2 } }
    \token_if_eq_meaning:NNTF 2 #8
      { \@@_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}
      { \@@_format_put:nw { { 6} } }
      { \@@_format_put:nw { {#5} } }
    \str_case:nnF {#6}
      {
        { e } { \@@_format_fp:wnnnNNw \@@_format_fp_e:wn }
        { f } { \@@_format_fp:wnnnNNw \@@_format_fp_f:wn }
        { g } { \@@_format_fp:wnnnNNw \@@_format_fp_g:wn }
        { ? } { \@@_format_fp:wnnnNNw \@@_format_fp_g:wn }
      }
      {
        \__kernel_msg_expandable_error:nnnn
          { str } { invalid-style-format } {#6} { fp }
        \@@_format_fp:wnnnNNw \@@_format_fp_g:wn
      }
    \s_stop
    \s__fp \__fp_chk:w #7 #8
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_format_fp:wnnnNNw}
%   \begin{quote}
%     \cs{@@_format_fp:wnnnNNw} \meta{formatting function} \cs{s_stop}
%     \Arg{precision} \Arg{width} \Arg{sign} \meta{fill}
%     \meta{alignment} \cs{s__fp} \cs{__fp_chk:w} \meta{fp type}
%     \meta{fp sign} \meta{fp body} |;|
%   \end{quote}
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp:wnnnNNw
    #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:wn}
%   Round the given floating point (not its absolute value, to play
%   nicely with unusual rounding modes).
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp_round:wn #1 ; #2
  { \__fp_parse:n { round ( #1; , #2 - \__fp_exponent:w #1; ) } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_format_fp_e:wn}
% \begin{macro}[EXP]{\@@_format_fp_e_aux:wn}
%   With the |e| type, first filter out special cases.  In the normal
%   case, round to |#4+1| significant figures (one before the decimal
%   separator, |#4| after).
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp_e:wn \s__fp \__fp_chk:w #1#2#3 ; #4
  {
    \int_case:nnF {#1}
      {
        { 0 } { \use:nf { 0 . } { \prg_replicate:nn {#4} { 0 } } e 0 }
        { 2 } { inf }
        { 3 } { nan }
      }
      {
        \exp_last_unbraced:Nf \@@_format_fp_e_aux:wn
          { \@@_format_fp_round:wn \s__fp \__fp_chk:w #1#2#3 ; { #4 + 1 } }
          {#4}
      }
  }
\cs_new:Npn \@@_format_fp_e_aux:wn
    \s__fp \__fp_chk:w #1#2 #3 #4#5#6#7 ; #8
  {
    \@@_format_put:fw { \int_eval:n { #3 - 1 } }
    \@@_format_put:nw { e }
    \int_compare:nNnTF {#8} > \c__fp_prec_int
      {
        \@@_format_put:fw { \prg_replicate:nn { #8 - \c__fp_prec_int + 1 } {0} }
        \@@_format_put:fw { \use_none:n #4#5#6#7 }
      }
      {
        \@@_format_put:fw
          { \str_range:nnn { #4#5#6#7 0 } { 2 } { #8 + 1 } }
      }
    \@@_format_put:fw { \use_i:nnnn #4 . }
    \use_none:n \s_stop
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_format_fp_f:wn}
% \begin{macro}[EXP]{\@@_format_fp_f_aux:wwwn}
%   With the |f| type, first filter out special cases.  In the normal
%   case, round to |#4| (absolute) decimal places.
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp_f:wn \s__fp \__fp_chk:w #1#2#3 ; #4
  {
    \int_case:nnF {#1}
      {
        {0} { \use:nf { 0 . } { \prg_replicate:nn {#4} { 0 } } }
        {2} { inf }
        {3} { nan }
      }
      {
        \exp_last_unbraced:Nf \@@_format_fp_f_aux:wwwn
          {
            \fp_to_decimal:n
              { abs ( round ( \s__fp \__fp_chk:w #1#2#3 ; , #4 ) ) }
          }
          . . ;
          {#4}
      }
  }
\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:wn}
% \begin{macro}[EXP]{\@@_format_fp_g_aux:wn}
% \begin{macro}[EXP]{\@@_format_fp_to_scientific:n, \@@_format_fp_trim:w}
%   With the |g| type, first filter out special cases.  In the normal
%   case, round to |#4| significant figures, then test the exponent: if
%   $-4\leq \meta{exponent} < \meta{precision}$, use the presentation
%   type |f|, otherwise use the presentation type |e|.  Also, a
%   \meta{precision} of $0$ is treated like a precision of $1$.
%   Actually, we don't reuse the |e| and |f| auxiliaries, because we
%   want to trim trailing zeros.  Thankfully, this is done by
%   \cs{fp_to_decimal:n} and \cs{fp_to_scientific:n}, acting on the
%   (absolute value of the) rounded value.
%    \begin{macrocode}
\cs_new:Npn \@@_format_fp_g:wn \s__fp \__fp_chk:w #1#2 ; #3
  {
    \int_case:nnF {#1}
      {
        {0} { 0 }
        {2} { inf }
        {3} { nan }
      }
      {
        \exp_last_unbraced:Nf \@@_format_fp_g_aux:wn
          {
            \@@_format_fp_round:wn \s__fp \__fp_chk:w #1#2 ;
              { \int_max:nn {1} {#3} }
          }
          { \int_max:nn {1} {#3} }
      }
  }
\cs_new:Npn \@@_format_fp_g_aux:wn #1; #2
  {
    \int_compare:nNnTF { \__fp_exponent:w #1; } < { -3 }
      { \@@_format_to_scientific:n }
      {
        \int_compare:nNnTF { \__fp_exponent:w #1; } > {#2}
          { \@@_format_to_scientific:n }
          { \fp_to_decimal:n }
      }
    { \__fp_set_sign_o:w 0 #1; @ \prg_do_nothing: }
  }
\cs_new:Npn \@@_format_to_scientific:n
  {
    \exp_after:wN \@@_format_fp_trim:w
    \exp:w \exp_end_continue_f:w \fp_to_scientific:n
  }
\cs_new:Npn \@@_format_fp_trim:w #1 e { \__fp_trim_zeros:w #1 ; e }
%    \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}
%
% \subsection{Todos}
%
% \begin{itemize}
%   \item Check what happens during floating point formatting when a
%     number is rounded to $0$ or $\infty$.  I think the |e| and |f|
%     types break horribly.
% \end{itemize}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex