[latex3-commits] [git/LaTeX3-latex3-latex3] l3bitset-2: update new functions to always create names (931bf46f4)

[Ulrike Fischer]

Repository : https://github.com/latex3/latex3
On branch  : l3bitset-2
Link       : https://github.com/latex3/latex3/commit/931bf46f4e911fd6b832ca4cce622005910be041

>---------------------------------------------------------------

commit 931bf46f4e911fd6b832ca4cce622005910be041
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Tue Dec 29 14:55:49 2020 +0100

    update new functions to always create names


>---------------------------------------------------------------

931bf46f4e911fd6b832ca4cce622005910be041
 l3experimental/l3bitset/l3bitset.dtx | 122 ++++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 24 deletions(-)

diff --git a/l3experimental/l3bitset/l3bitset.dtx b/l3experimental/l3bitset/l3bitset.dtx
index 2eb01c6d8..485a5e5b2 100644
--- a/l3experimental/l3bitset/l3bitset.dtx
+++ b/l3experimental/l3bitset/l3bitset.dtx
@@ -68,22 +68,76 @@
 % bitsets \texttt{fp} is used and this is slower.
 %
 % \section{Creating bitsets}
-% \begin{function}[added = 2020-12-13]
-%   {\bitset_new:N,\bitset_new:c}
+% \begin{function}[added = 2020-12-13,updated=2020-12-29]
+%   {\bitset_new:N,\bitset_new:c,\bitset_new:Nn, \bitset_new:cn}
 %   \begin{syntax}
 %     \cs{bitset_new:N}  \meta{bitset var} \\
+%     \cs{bitset_new:Nn} \meta{bitset var}
+%      \{
+%         \meta{name1} |=| \meta{index1} |,|
+%         \meta{name2} |=| \meta{index2} |,| \ldots{}
+%      \}
 %   \end{syntax}
 % Creates a new \meta{bitset var} or raises an error if the name is already taken.
 % The declaration is global. The \meta{bitset var} is initially 0.
 %
-%  Bitsets are implemented as string variables consisting of
-%  \texttt{1}'s and \texttt{0}'s.
-%  The rightmost number is the index position 1, so
-%  the string variable can be viewed directly as the binary number.
-%  But one shouldn't rely on the internal representation, but use the
-%  dedicated \cs{bitset_to_bin:N} instead to get the binary number.
+% Bitsets are implemented as string variables consisting of
+% \texttt{1}'s and \texttt{0}'s.
+% The rightmost number is the index position 1, so
+% the string variable can be viewed directly as the binary number.
+% But one shouldn't rely on the internal representation, but use the
+% dedicated \cs{bitset_to_bin:N} instead to get the binary number.
+%
+% The name--index pairs given in the second
+% argument of \cs{bitset_new:Nn} declares names for some indices,
+% which can be used to set and unset bits.
+%
+% For example after this setting
+%
+%  \begin{verbatim}
+%  \bitset_new:Nn \l_pdfannot_F_bitset
+%    {
+%      Invisible      = 1,
+%      Hidden         = 2,
+%      Print          = 3,
+%      NoZoom         = 4,
+%      NoRotate       = 5,
+%      NoView         = 6,
+%      ReadOnly       = 7,
+%      Locked         = 8,
+%      ToggleNoView   = 9,
+%      LockedContents = 10
+%    }
+%  \end{verbatim}
+%  it is possible to set bit 3 by using
+%  |\bitset_set_true:Nn \l_pdfannot_F_bitset {Print}|
+%
+% The declaration of such names is global.
+% \meta{index\ldots} should be an \meta{integer expression}
+% which evaluates to a positive number. The names \meta{name\ldots}
+% should be unique. Using a number as name, e.g |10=1|, is allowed,
+% but the index position |10| can then only be reached if some other
+% name for it exists, e.g. |ten=10|.
+% It is not necessary to give every index
+% a name, and an index can have more than one name. The named index
+% can be extended or changed with the next function.
+%
+% \end{function}
+% \begin{function}[added = 2020-12-19]
+%   {\bitset_addto_named_index:Nn}
+%   \begin{syntax}
+%     \cs{bitset_addto_named_index:Nn} \meta{bitset var}
+%      \{
+%         \meta{name1} |=| \meta{index1} |,|
+%         \meta{name2} |=| \meta{index2} |,| \ldots{}
+%      \}
+%   \end{syntax}
+% This adds (or updates) the name--index pairs for \meta{bitset var}
+% as described for \cs{bitset_new:Nn}.
 % \end{function}
 %
+
+%
 % \begin{function}[EXP, pTF,added = 2020-12-14]
 %   { \bitset_if_exist:N, \bitset_if_exist:c  }
 %   \begin{syntax}
@@ -277,11 +331,46 @@
   {
     \__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 _key_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 _key_prop }
+    \prop_gset_from_keyval:cn
+       { g__bitset_\cs_to_str:N #1 _key_prop }
+       { #2 }
+  }
 \cs_generate_variant:Nn \bitset_new:N {c}
 %    \end{macrocode}
 % \end{macro}
+% \begin{variable}{\l_@@_tmpa_prop}
+% A scratch prop to be able to extend the names properties.
+%    \begin{macrocode}
+\prop_new:N \l_@@_tmpa_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_@@_tmpa_prop
+       { #2 }
+     \prop_map_inline:Nn \l_@@_tmpa_prop
+       {
+         \prop_gput:cnn
+           { g_@@_\cs_to_str:N #1 _key_prop }
+           { ##1 }
+           { ##2 }
+       }
+  }
+%    \end{macrocode}
+% \end{macro}
 % \begin{macro}[pTF]
 %   {
 %     \bitset_if_exist:N, \bitset_if_exist:c
@@ -497,22 +586,7 @@
 
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}
-%  {
-%    \bitset_addto_named_index:Nn
-%  }
-%    \begin{macrocode}
-\cs_new_protected:Npn  \bitset_addto_named_index:Nn #1 #2
-  {
-     \prop_if_exist:cF { g_@@_\cs_to_str:N #1 _key_prop }
-       {
-         \prop_new:c { g_@@_\cs_to_str:N #1 _key_prop }
-       }
-     \prop_gset_from_keyval:cn
-       { g_@@_\cs_to_str:N #1 _key_prop }
-       { #2 }
-  }
-%    \end{macrocode}
+
 % \begin{macro}
 %   {
 %     \bitset_set_true_key:Nn, \bitset_set_true_key:cn,