diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3str.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3str.dtx | 56 |
1 files changed, 32 insertions, 24 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx index 3739bc8a766..1642d85a1ee 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx @@ -41,7 +41,7 @@ % }^^A % } % -% \date{Released 2017/05/29} +% \date{Released 2017/07/15} % % \maketitle % @@ -57,7 +57,7 @@ % which have category code $12$ (\enquote{other}) with the exception of % space characters which have category code $10$ (\enquote{space}). Thus % at a technical level, a \TeX{} string is a token list with the appropriate -% category codes. In this documentation, these will simply be referred to as +% category codes. In this documentation, these are simply referred to as % strings. % % String variables are simply specialised token lists, but by convention @@ -66,15 +66,22 @@ % spaces, which have category code $10$ (blank space). All the % functions in this module which accept a token list argument first % convert it to a string using \cs{tl_to_str:n} for internal processing, -% and will not treat a token list or the corresponding string +% and do not treat a token list or the corresponding string % representation differently. % +% As a string is a subset of the more general token list, it is sometimes unclear +% when one should be used over the other. +% Use a string variable for data that isn’t primarily intended for typesetting +% and for which a level of protection from unwanted expansion is suitable. +% This data type simplifies comparison of variables since there are no concerns +% about expansion of their contents. +% % Note that as string variables are a special case of token list variables % the coverage of \cs[no-index]{str_\ldots{}:N} functions is somewhat smaller than % \cs[no-index]{tl_\ldots{}:N}. % % The functions \cs{cs_to_str:N}, \cs{tl_to_str:n}, \cs{tl_to_str:N} and -% \cs{token_to_str:N} (and variants) will generate strings from the appropriate +% \cs{token_to_str:N} (and variants) generate strings from the appropriate % input: these are documented in \pkg{l3basics}, \pkg{l3tl} and \pkg{l3token}, % respectively. % @@ -97,8 +104,8 @@ % \cs{str_new:N} \meta{str~var} % \end{syntax} % Creates a new \meta{str~var} or raises an error if the name is -% already taken. The declaration is global. The \meta{str~var} will -% initially be empty. +% already taken. The declaration is global. The \meta{str~var} is +% initially empty. % \end{function} % % \begin{function}[added = 2015-09-18] @@ -107,7 +114,7 @@ % \cs{str_const:Nn} \meta{str~var} \Arg{token list} % \end{syntax} % Creates a new constant \meta{str~var} or raises an error if the name -% is already taken. The value of the \meta{str~var} will be set +% is already taken. The value of the \meta{str~var} is set % globally to the \meta{token list}, converted to a string. % \end{function} % @@ -200,7 +207,7 @@ % \begin{function}[EXP,pTF, added = 2015-09-18] % {\str_if_empty:N, \str_if_empty:c} % \begin{syntax} -% \cs{sr_if_empty_p:N} \meta{str~var} +% \cs{str_if_empty_p:N} \meta{str~var} % \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 @@ -264,8 +271,8 @@ % \end{syntax} % This function compares the \meta{test string} in turn with each % of the \meta{string cases}. If the two are equal (as described for -% \cs{str_if_eq:nnTF} then the -% associated \meta{code} is left in the input stream. If any of the +% \cs{str_if_eq:nnTF} then the associated \meta{code} is left in the +% input stream and other cases are discarded. If any of the % cases are matched, the \meta{true code} is also inserted into the % input stream (after the code for the appropriate case), while if none % match then the \meta{false code} is inserted. The function @@ -288,7 +295,8 @@ % This function compares the full expansion of the \meta{test string} % in turn with the full expansion of the \meta{string cases}. If the two % full expansions are equal (as described for \cs{str_if_eq:nnTF} then the -% associated \meta{code} is left in the input stream. If any of the +% associated \meta{code} is left in the input stream +% and other cases are discarded. If any of the % cases are matched, the \meta{true code} is also inserted into the % input stream (after the code for the appropriate case), while if none % match then the \meta{false code} is inserted. The function @@ -306,7 +314,7 @@ % \cs{str_use:N} \meta{str~var} % \end{syntax} % Recovers the content of a \meta{str~var} and places it -% directly in the input stream. An error will be raised if the variable +% directly in the input stream. An error is raised if the variable % does not exist or if it is invalid. Note that it is possible to use % a \meta{str} directly without an accessor function. % \end{function} @@ -361,7 +369,7 @@ % character, and leaves the remaining characters (if any) in the input % stream, with category codes $12$ and $10$ (for spaces). The % functions differ in the case where the first character is a space: -% \cs{str_tail:N} and \cs{str_tail:n} will trim only that space, while +% \cs{str_tail:N} and \cs{str_tail:n} only trim that space, while % \cs{str_tail_ignore_spaces:n} removes the first non-space character % and any space before it. If the \meta{token list} is empty (or % blank in the case of the \texttt{_ignore_spaces} variant), then @@ -405,7 +413,7 @@ % \iow_term:x { \str_range:nnn { abcdef } { -2 } { -1 } } % \iow_term:x { \str_range:nnn { abcdef } { 0 } { -1 } } % \end{verbatim} -% will print \texttt{bcde}, \texttt{cdef}, \texttt{ef}, and an empty +% prints \texttt{bcde}, \texttt{cdef}, \texttt{ef}, and an empty % line to the terminal. The \meta{start index} must always be smaller than % or equal to the \meta{end index}: if this is not the case then no output % is generated. Thus @@ -470,7 +478,7 @@ % As with all \pkg{expl3} functions, the input supported by % \cs{str_fold_case:n} is \emph{engine-native} characters which are or % interoperate with \textsc{utf-8}. As such, when used with \pdfTeX{} -% \emph{only} the Latin alphabet characters A--Z will be case-folded +% \emph{only} the Latin alphabet characters A--Z are case-folded % (\emph{i.e.}~the \textsc{ascii} range which coincides with % \textsc{utf-8}). Full \textsc{utf-8} support is available with both % \XeTeX{} and \LuaTeX{}, subject only to the fact that \XeTeX{} in @@ -514,7 +522,7 @@ % As with all \pkg{expl3} functions, the input supported by % \cs{str_fold_case:n} is \emph{engine-native} characters which are or % interoperate with \textsc{utf-8}. As such, when used with \pdfTeX{} -% \emph{only} the Latin alphabet characters A--Z will be case-folded +% \emph{only} the Latin alphabet characters A--Z are case-folded % (\emph{i.e.}~the \textsc{ascii} range which coincides with % \textsc{utf-8}). Full \textsc{utf-8} support is available with both % \XeTeX{} and \LuaTeX{}, subject only to the fact that \XeTeX{} in @@ -765,7 +773,7 @@ % spaces are not skipped for ease-of-input. The need to detokenize and force % expansion of input arises from the case where a |#| token is used in the % input, \emph{e.g.}~|\__str_if_eq_x:nn {#} { \tl_to_str:n {#} }|, which -% otherwise will fail as \cs{luatex_luaescapestring:D} does not double +% otherwise would fail as \cs{luatex_luaescapestring:D} does not double % such tokens. % \begin{macrocode} \cs_new:Npn \@@_if_eq_x:nn #1#2 { \pdftex_strcmp:D {#1} {#2} } @@ -1203,7 +1211,7 @@ % trick again, so that the $8$ first arguments of % \cs{@@_collect_end:nnnnnnnnw} are some \cs{or:}, followed by an % \cs{fi:}, followed by |#1| characters from the input stream. Simply -% leaving this in the input stream will close the conditional properly +% leaving this in the input stream closes the conditional properly % and the \cs{or:} disappear. % \begin{macrocode} \cs_new:Npn \@@_collect_delimit_by_q_stop:w #1; @@ -1613,7 +1621,7 @@ % Set up to read each file. As they use C-style comments, there is a need to % deal with |#|. At the same time, spaces are important so they need to be % picked up as they are important. Beyond that, the current category code -% scheme works fine. With no I/O loop available, hard-code one that will work +% scheme works fine. With no I/O loop available, hard-code one that works % quickly. % \begin{macrocode} \cs_set_protected:Npn \@@_map_inline:n #1 @@ -1664,8 +1672,8 @@ } % \end{macrocode} % Storing each exception is always done in the same way: create a constant -% token list which expands to exactly the mapping. These will have the -% category codes \enquote{now} (so should be letters) but will be detokenized +% token list which expands to exactly the mapping. These have the +% category codes \enquote{now} (so should be letters) but are later detokenized % for string use. % \begin{macrocode} \cs_set_protected:Npn \@@_store:nnnnn #1#2#3#4#5 @@ -1680,7 +1688,7 @@ } % \end{macrocode} % Parse the main Unicode data file for title case exceptions (the one-to-one -% lower and upper case mappings it contains will all be covered by the \TeX{} +% lower and upper case mappings it contains are all be covered by the \TeX{} % data). % \begin{macrocode} \cs_set_protected:Npn \@@_parse_auxi:w @@ -1694,7 +1702,7 @@ \if_int_compare:w \__str_if_eq_x:nn { #5 ~ } {#7} = 0 \exp_stop_f: \else: \tl_const:cx - { c_@@_title_ \utex_char:D "#1 _tl } + { c_@@_mixed_ \utex_char:D "#1 _tl } { \utex_char:D "#7 } \fi: } @@ -1734,7 +1742,7 @@ \use:n { \@@_parse_auxii:w #1 ~ upper ~ #4 ~ } ~ \q_stop \if_int_compare:w \__str_if_eq_x:nn {#3} {#4} = 0 \exp_stop_f: \else: - \use:n { \@@_parse_auxii:w #1 ~ title ~ #3 ~ } ~ \q_stop + \use:n { \@@_parse_auxii:w #1 ~ mixed ~ #3 ~ } ~ \q_stop \fi: } \cs_set_protected:Npn \@@_parse_auxii:w #1 ~ #2 ~ #3 ~ #4 ~ #5 \q_stop |