[latex3-commits] [l3svn] r6013 - Clarify some code comments.
noreply at latex-project.org
noreply at latex-project.org
Sat Sep 19 01:28:16 CEST 2015
Author: bruno
Date: 2015-09-19 01:28:16 +0200 (Sat, 19 Sep 2015)
New Revision: 6013
Modified:
trunk/l3kernel/l3str.dtx
Log:
Clarify some code comments.
Modified: trunk/l3kernel/l3str.dtx
===================================================================
--- trunk/l3kernel/l3str.dtx 2015-09-18 15:29:35 UTC (rev 6012)
+++ trunk/l3kernel/l3str.dtx 2015-09-18 23:28:16 UTC (rev 6013)
@@ -224,7 +224,7 @@
% \cs{str_if_empty:NTF} \meta{str~var} \Arg{true code} \Arg{false code}
% \end{syntax}
% Tests if the \meta{string variable} is entirely empty
-% (\emph{i.e.}~contains no tokens at all).
+% (\emph{i.e.}~contains no characters at all).
% \end{function}
%
% \begin{function}[EXP,pTF, added = 2015-09-18]
@@ -846,10 +846,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int, EXP]{\@@_if_eq_x_return:nn}
-% Defined in \pkg{l3basics}.
-% \end{macro}
-%
% \begin{macro}[EXP, pTF]
% {\str_if_eq:NN, \str_if_eq:Nc, \str_if_eq:cN, \str_if_eq:cc}
% Note that \cs{str_if_eq:NN} is different from
@@ -990,19 +986,19 @@
% The \cs{str_item:nn} hands its argument with spaces escaped to
% \cs{@@_item:nn}, and makes sure to turn the result back into
% a proper string (with category code~$10$ spaces) eventually. The
-% \cs{str_item_ignore_spaces:nn} function cheats a little bit in that
-% it doesn't hand to \cs{@@_item:nn} an \enquote{other string}.
-% This is safe, as everything else is done with undelimited arguments.
-% Then evaluate the \meta{index} argument~|#2| and count characters in
-% the string, passing those two numbers to \cs{@@_item:ww} for further
-% analysis. If the \meta{index} is negative, shift by |#2|, and
-% remove that number of characters before returning the next item in
-% the input stream (and if |#1| is smaller than $-|#2|$, nothing is
-% returned). If the \meta{index} is positive, ignore that number
-% (minus one) of characters before returning the next one. The shift
-% by one is obtained by inserting an empty brace group before the
-% string in that case: that brace group also covers the case where the
-% \meta{index} is zero.
+% \cs{str_item_ignore_spaces:nn} function does not escape spaces,
+% which are thus ignored by \cs{@@_item:nn} since
+% everything else is done with undelimited arguments.
+% Evaluate the \meta{index} argument~|#2| and count characters in
+% the string, passing those two numbers to \cs{@@_item:ww} for
+% further analysis. If the \meta{index} is negative, shift it by
+% the \meta{count} to know the how many character to discard, and if
+% that is still negative give an empty result. If the \meta{index}
+% is larger than the \meta{count}, give an empty result, and
+% otherwise discard $\meta{index}-1$ characters before returning the
+% following one. The shift by $-1$ is obtained by inserting an empty
+% brace group before the string in that case: that brace group also
+% covers the case where the \meta{index} is zero.
% \begin{macrocode}
\cs_new_nopar:Npn \str_item:Nn { \exp_args:No \str_item:nn }
\cs_generate_variant:Nn \str_item:Nn { c }
@@ -1258,9 +1254,10 @@
% longer than token lists, we use specialized functions to count
% characters ignoring spaces. Namely, loop, grabbing $9$ non-space
% characters at each step, and end as soon as we reach one of the $9$
-% trailing items. The \texttt{_unsafe} variant expects a token list
-% already converted to category code $12$ characters, and is used by
-% \cs{str_item:nn}.
+% trailing items. The internal function \cs{@@_count:n}, used in
+% \cs{str_item:nn} and \cs{str_range:nnn}, is similar to
+% \cs{str_count_ignore_spaces:n} but expects its argument to already
+% be a string or a string with spaces escaped.
% \begin{macrocode}
\cs_new_nopar:Npn \str_count:N { \exp_args:No \str_count:n }
\cs_generate_variant:Nn \str_count:N { c }
@@ -1310,8 +1307,9 @@
% \begin{macro}[EXP]
% {\str_head:N, \str_head:c, \str_head:n, \str_head_ignore_spaces:n}
% \begin{macro}[EXP, aux]{\@@_head:w}
-% The \texttt{_ignore_spaces} variant is almost identical to
-% \cs{tl_head:n}. As usual, \cs{str_head:N} expands its argument and
+% The \texttt{_ignore_spaces} variant applies \cs{tl_to_str:n} then
+% grabs the first item, thus skipping spaces.
+% As usual, \cs{str_head:N} expands its argument and
% hands it to \cs{str_head:n}. To circumvent the fact that \TeX{}
% skips spaces when grabbing undelimited macro parameters,
% \cs{@@_head:w} takes an argument delimited by a space. If |#1|
@@ -1461,7 +1459,7 @@
% \c_left_brace_str,
% \c_right_brace_str,
% \c_circumflex_str,
-% \c_colojn_str,
+% \c_colon_str,
% \c_hash_str,
% \c_percent_str,
% \c_tilde_str,
More information about the latex3-commits
mailing list