summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3bitset.dtx172
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