From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining 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> +\documentclass[full]{l3doc} +\usepackage{amsmath} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \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} +% +% \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} +% +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex -- cgit v1.2.3