diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx | 172 |
1 files changed, 96 insertions, 76 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx b/Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx index 545d7c3357f..d362d59adb0 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx @@ -2,7 +2,7 @@ % %% File: l3bitset.dtx % -% Copyright (C) 2020-2023 The LaTeX Project +% Copyright (C) 2020-2024 The LaTeX Project % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -30,7 +30,7 @@ %</driver> % \fi % \title{^^A -% The \pkg{l3bitset} package\\ Bitsets^^A +% The \pkg{l3bitset} module\\ Bitsets^^A % } % % \author{^^A @@ -42,13 +42,13 @@ % }^^A % } % -% \date{Released 2023-12-11} +% \date{Released 2024-01-04} % % \maketitle % % \begin{documentation} % -% This package defines and implements the data type \texttt{bitset}, a vector of +% This module defines and implements the data type \texttt{bitset}, a vector of % bits. The size of the vector may grow dynamically. % Individual bits can be set and unset by names pointing to an index position. % The names |1|, |2|, |3|, \ldots\ are predeclared and point to the @@ -64,11 +64,11 @@ % The bitset is stored as a string (but one shouldn't rely on the internal % representation) and so the vector size is theoretically % unlimited, only restricted by \TeX-memory. But the functions to set and clear -% bits uses integer functions for the index so bitsets can't be longer +% bits use integer functions for the index so bitsets can't be longer % than $2^{31} - 1$. % The export function % \cs{bitset_to_arabic:N} can use functions from the \texttt{int} module only if -% the largest index used for this bitset is smaller then $32$, for longer +% the largest index used for this bitset is smaller than $32$, for longer % bitsets \texttt{fp} is used and this is slower. % % \section{Creating bitsets} @@ -79,8 +79,8 @@ % \cs{bitset_new:N} \meta{bitset var} \\ % \cs{bitset_new:Nn} \meta{bitset var} % ~~\{ -% ~~~~\meta{name1} |=| \meta{index1} |,| -% ~~~~\meta{name2} |=| \meta{index2} |,| \ldots{} +% ~~~~\meta{name_1} |=| \meta{index_1} |,| +% ~~~~\meta{name_2} |=| \meta{index_2} |,| \ldots{} % ~~\} % \end{syntax} % Creates a new \meta{bitset var} or raises an error if the name is already taken. @@ -101,7 +101,7 @@ % % \meta{index\ldots} should be a positive number or an % \meta{integer expression} which evaluates to a positive number. -% The expression is evaluated when the index is used, not a declaration time. +% The expression is evaluated when the index is used, not at declaration time. % The names \meta{name\ldots} % should be unique. Using a number as name, e.g.~|10=1|, is allowed, it % then overwrites the predeclared name |10|, @@ -117,8 +117,8 @@ % \begin{syntax} % \cs{bitset_addto_named_index:Nn} \meta{bitset var} % ~~\{ -% ~~~~\meta{name1} |=| \meta{index1} |,| -% ~~~~\meta{name2} |=| \meta{index2} |,| \ldots{} +% ~~~~\meta{name_1} |=| \meta{index_1} |,| +% ~~~~\meta{name_2} |=| \meta{index_2} |,| \ldots{} % ~~\} % \end{syntax} % This extends or changes the name--index pairs for \meta{bitset var} @@ -145,7 +145,7 @@ % print = 3 % } % \end{verbatim} -% it is possible to set bit $3$ by using any of this alternatives: +% it is possible to set bit $3$ by using any of these alternatives: % \begin{verbatim} % \bitset_set_true:Nn \l_pdfannot_F_bitset {Print} % \bitset_set_true:Nn \l_pdfannot_F_bitset {print} @@ -156,7 +156,7 @@ % {\bitset_if_exist:N, \bitset_if_exist:c} % \begin{syntax} % \cs{bitset_if_exist_p:N} \meta{bitset var} -% \cs{bitset_if_exist:NTF} \meta{bitset var} \Arg{true code} \Arg{false code}% +% \cs{bitset_if_exist:NTF} \meta{bitset var} \Arg{true code} \Arg{false code} % \end{syntax} % Tests whether the \meta{bitset var} exist. % \end{function} @@ -172,7 +172,7 @@ % \cs{bitset_set_true:Nn} \meta{bitset var} \Arg{name} % \end{syntax} % This sets the bit of the index position represented by \Arg{name} to $1$. -% \Arg{name} should be either one of the predeclared names +% \meta{name} should be either one of the predeclared names % |1|, |2|, |3|, \ldots, or one of the names added manually. % Index position are 1-based. % If needed the length of the bit vector is enlarged. @@ -188,7 +188,7 @@ % \end{syntax} % This unsets the bit of the index position represented by \Arg{name} (sets % it to $0$). -% \Arg{name} should be either one of the predeclared names +% \meta{name} should be either one of the predeclared names % |1|, |2|, |3|, \ldots, or one of the names added manually. % The index is $1$-based. If the index position is larger % than the current length of the bit vector @@ -213,8 +213,8 @@ % \cs{bitset_item:Nn} \meta{bitset var} \Arg{name} % \end{syntax} % \cs{bitset_item:Nn} outputs \texttt{1} if the bit with -% the index number represented by \Arg{name} is set and \texttt{0} otherwise. -% \Arg{name} is either one of the predeclared names +% the index number represented by \meta{name} is set and \texttt{0} otherwise. +% \meta{name} is either one of the predeclared names % |1|, |2|, |3|, \ldots, or one of the names added manually. % \end{function} % @@ -236,8 +236,8 @@ % This leaves the current value of the bitset expressed as % a decimal number in the input stream. If no bit has been set yet, % the output is zero. The function uses \cs{int_from_bin:n} if the largest -% index that have been set or unset is smaller then $32$, and a slower implementation -% based on \cs{fp_eval:n} otherwise. +% index that have been set or unset is smaller than $32$, and a slower +% implementation based on \cs{fp_eval:n} otherwise. % \end{function} % % \begin{function}[added = 2023-11-15] @@ -245,7 +245,8 @@ % \begin{syntax} % \cs{bitset_show:N} \meta{bitset var} % \end{syntax} -% Displays the binary and decimal value of the \meta{bitset var} on the terminal, +% Displays the binary and decimal values of the \meta{bitset var} +% on the terminal. % \end{function} % % \begin{function}[added = 2023-11-15] @@ -253,7 +254,30 @@ % \begin{syntax} % \cs{bitset_log:N} \meta{bitset var} % \end{syntax} -% Writes the value of the \meta{bitset var} in the log file. +% Writes the binary and decimal values of the \meta{bitset var} +% in the log file. +% \end{function} +% +% \begin{function}[added = 2023-11-15] +% { +% \bitset_show_named_index:N, \bitset_show_named_index:c +% } +% \begin{syntax} +% \cs{bitset_show_named_index:N} \meta{bitset var} +% \end{syntax} +% Displays declared name--index pairs of the \meta{bitset var} +% on the terminal. +% \end{function} +% +% \begin{function}[added = 2023-12-11] +% { +% \bitset_log_named_index:N, \bitset_log_named_index:c +% } +% \begin{syntax} +% \cs{bitset_log_named_index:N} \meta{bitset var} +% \end{syntax} +% Writes declared name--index pairs of the \meta{bitset var} +% in the log file. % \end{function} % % \end{documentation} @@ -270,6 +294,15 @@ %<@@=bitset> % \end{macrocode} % +% Transitional support. +% \begin{macrocode} +\cs_if_exist:NT \@expl@finalise@setup@@@@ + { + \tl_gput_right:Nn \@expl@finalise@setup@@@@ + { \declare@file@substitution { l3bitset.sty } { null.tex } } + } +% \end{macrocode} +% % A bitset is a string variable. % \begin{macro}{\bitset_new:N, \bitset_new:c} % \begin{macro}{\bitset_new:Nn, \bitset_new:cn} @@ -280,40 +313,27 @@ \cs_gset_eq:NN #1 \c_zero_str \prop_new:c { g__bitset_ \cs_to_str:N #1 _name_prop } } - \cs_new_protected:Npn \bitset_new:Nn #1 #2 { \__kernel_chk_if_free_cs:N #1 \cs_gset_eq:NN #1 \c_zero_str \prop_new:c { g__bitset_ \cs_to_str:N #1 _name_prop } \prop_gset_from_keyval:cn - { g__bitset_ \cs_to_str:N #1 _name_prop } - {#2} + { g__bitset_ \cs_to_str:N #1 _name_prop } + {#2} } \cs_generate_variant:Nn \bitset_new:N { c } +\cs_generate_variant:Nn \bitset_new:Nn { c } % \end{macrocode} % \end{macro} % \end{macro} % -% \begin{variable}{\l_@@_tmp_prop} -% A scratch prop to be able to extend the names properties. -% \begin{macrocode} -\prop_new:N \l_@@_tmp_prop -% \end{macrocode} -% \end{variable} -% % \begin{macro}{\bitset_addto_named_index:Nn} % \begin{macrocode} \cs_new_protected:Npn \bitset_addto_named_index:Nn #1#2 { - \prop_set_from_keyval:Nn \l_@@_tmp_prop {#2} - \prop_map_inline:Nn \l_@@_tmp_prop - { - \prop_gput:cnn - { g_@@_ \cs_to_str:N #1 _name_prop } - {##1} - {##2} - } + \prop_gput_from_keyval:cn + { g_@@_ \cs_to_str:N #1 _name_prop } { #2 } } % \end{macrocode} % \end{macro} @@ -329,6 +349,7 @@ \bitset_if_exist:c \str_if_exist:c { p , T , F , TF } % \end{macrocode} % \end{macro} +% % \begin{macro}{\@@_set_true:Nn, \@@_gset_true:Nn, \@@_set_false:Nn, \@@_gset_false:Nn} % \begin{macro}{\@@_set:NNnN} % The internal command uses only numbers (integer expressions) for the @@ -358,12 +379,12 @@ } } { - #1 #2 + #1 #2 { \str_range:Nnn #2 { 1 } { -1 - (#3) } #4 \str_range:Nnn #2 { 1 - (#3) } { -1 } - } + } } } } @@ -379,7 +400,7 @@ % % \begin{macro}[TF]{\@@_test_digits:n} % \begin{macro}{\@@_test_digits_end:n} -% \begin{macro}{\@@_test_digits:wn} +% \begin{macro}{\@@_test_digits:w} % \url{https://chat.stackexchange.com/transcript/message/56878159#56878159} % \begin{macrocode} \prg_new_protected_conditional:Npnn \@@_test_digits:n #1 { TF } @@ -468,14 +489,16 @@ \cs_generate_variant:Nn \bitset_gclear:N { c } % \end{macrocode} % \end{macro} -% \begin{macro} +% +% \begin{macro}[EXP] % { % \bitset_to_arabic:N, \bitset_to_arabic:c, % \bitset_to_bin:N, \bitset_to_bin:c, % } +% \begin{macro}[EXP]{\@@_to_int:nN} % The naming of the commands follow the names in the \texttt{int} module. % \cs{bitset_to_arabic:N} uses \cs{int_from_bin:n} if the string is shorter -% then $32$ and the slower \cs{fp_eval} for larger bitsets. +% than $32$ and the slower \cs{fp_eval:n} for larger bitsets. % \begin{macrocode} \cs_new:Npn \bitset_to_arabic:N #1 { @@ -486,13 +509,11 @@ #1 \q_recursion_tail \q_recursion_stop } } - \cs_new:Npn \@@_to_int:nN #1#2 { \quark_if_recursion_tail_stop_do:Nn #2 {#1} \exp_args:Nf \@@_to_int:nN { \fp_eval:n { #1 * 2 + #2 } } } - \cs_new:Npn \bitset_to_bin:N #1 { #1 @@ -501,6 +522,8 @@ \cs_generate_variant:Nn \bitset_to_bin:N { c } % \end{macrocode} % \end{macro} +% \end{macro} +% % \begin{macro} % { % \bitset_item:Nn, \bitset_item:cn @@ -518,10 +541,10 @@ { 0 - ( \prop_item:cn { g_@@_ \cs_to_str:N #1 _name_prop } {#2} ) } +0 } - } - { - 0 - } + } + { + 0 + } } \cs_generate_variant:Nn \bitset_item:Nn { c } % \end{macrocode} @@ -537,28 +560,40 @@ \cs_generate_variant:Nn \bitset_show:N { c } \cs_new_protected:Npn \bitset_log:N { \@@_show:NN \msg_log:nneeee } \cs_generate_variant:Nn \bitset_log:N { c } -\cs_new_protected:Npn \bitset_show_named_index:N { \@@_show_named_index:NN \msg_show:nneeee } -\cs_generate_variant:Nn \bitset_show_named_index:N { c } \cs_new_protected:Npn \@@_show:NN #1#2 { \__kernel_chk_defined:NT #2 { #1 { bitset } { show } - { \token_to_str:N #2 } - { \bitset_to_bin:N #2 } - { \bitset_to_arabic:N #2 } - { } + { \token_to_str:N #2 } + { \bitset_to_bin:N #2 } + { \bitset_to_arabic:N #2 } + { } } } +% \end{macrocode} +% \end{macro} +% +% \begin{macro} +% { +% \bitset_show_named_index:N, \bitset_show_named_index:c, +% \bitset_log_named_index:N, \bitset_log_named_index:c +% } +% \begin{macrocode} +\cs_new_protected:Npn \bitset_show_named_index:N + { \@@_show_named_index:NN \msg_show:nneeee } +\cs_generate_variant:Nn \bitset_show_named_index:N { c } +\cs_new_protected:Npn \bitset_log_named_index:N + { \@@_show_named_index:NN \msg_log:nneeee } +\cs_generate_variant:Nn \bitset_log_named_index:N { c } \cs_new_protected:Npn \@@_show_named_index:NN #1#2 { \__kernel_chk_defined:NT #2 { #1 { bitset } { show-names } - { \token_to_str:N #2 } - { \prop_map_function:cN { g_@@_ \cs_to_str:N #2 _name_prop } \msg_show_item:nn } - { } - { } + { \token_to_str:N #2 } + { \prop_map_function:cN { g_@@_ \cs_to_str:N #2 _name_prop } \msg_show_item:nn } + { } { } } } % \end{macrocode} @@ -566,7 +601,7 @@ % % \subsection{Messages} % \begin{macrocode} - \msg_new:nnn { bitset } { show } +\msg_new:nnn { bitset } { show } { The~bitset~#1~has~the~representation: \\ >~binary:~#2 \\ @@ -589,21 +624,6 @@ %</package> % \end{macrocode} % -% \subsection{Stub package} -% -% \begin{macrocode} -%<*stub> -% \end{macrocode} -% -% \begin{macrocode} -\ProvidesExplPackage{l3bitset}{2023-12-11}{} - {L3 Experimental bitset support} -% \end{macrocode} -% -% \begin{macrocode} -%</stub> -% \end{macrocode} -% % \end{implementation} % % \PrintIndex |