path: root/Master/texmf-dist/source/latex/l3experimental/l3str/l3str.dtx

% \iffalse meta-comment
%
%% File: l3str.dtx Copyright (C) 2011 The LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the "l3experimental bundle" (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %%
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX3 Project.
%%
%% -----------------------------------------------------------------------
%
%<*driver|package>
\RequirePackage{expl3}
\GetIdInfo$Id: l3str.dtx 2921 2011-10-17 13:23:36Z bruno $
  {L3 Experimental Strings}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\usepackage{amsmath}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
%
% \title{^^A
%   The \textsf{l3str} package: manipulating strings of characters^^A
%   \thanks{This file describes v\ExplFileVersion,
%     last revised \ExplFileDate.}^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released \ExplFileDate}
%
% \maketitle
%
% \begin{documentation}
%
% \LaTeX3 provides a set of functions to manipulate token lists
% as strings of characters, ignoring the category codes of those
% characters.
% 
% String variables are simply specialised token lists, but by convention
% should be named with the suffix \texttt{\ldots str}. Such variables should
% contain characters with category code $12$ (other), except spaces, which
% have category code $10$ (blank space). All the \enquote{safe} functions in
% this module first convert their argument to a string for internal processing,
% and will not treat a token list or the corresponding string representation
% differently.
%
% Most functions in this module come in three flavours:
% \begin{itemize}
%   \item \cs{str_...:N...}, which expect a token list
%     variable as their argument;
%   \item \cs{str_...:n...}, taking any token list (or string) as an argument;
%   \item \cs{str_..._ignore_spaces:n...}, which ignores any space encountered
%     during the operation: these functions are slightly faster than those
%     which take care of escaping spaces appropriately;
% \end{itemize}
% When performance is important, the internal \cs{str_..._unsafe:n...}
% functions, which expect a \enquote{safe} string in which spaces
% have category code $12$ instead of $10$, might be useful.
%
% \subsection{Conversion and input of strings}
%
% \begin{variable}
%   {
%     \c_backslash_str,
%     \c_lbrace_str,
%     \c_rbrace_str,
%     \c_hash_str,
%     \c_percent_str
%   }
%   Constant strings, containing a single character, with category code $12$.
% \end{variable}
%
% \begin{function}[EXP]{\tl_to_str:N, \tl_to_str:n}
%   \begin{syntax}
%     \cs{tl_to_str:N} \meta{tl var}
%     \cs{tl_to_str:n} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string}, leaving the resulting
%   tokens in the input stream.
% \end{function}
%
% \begin{function}{\str_set:Nn, \str_set:Nx, \str_set:cn, \str_set:cx}
%   \begin{syntax}
%     \cs{str_set:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and saves the result in \meta{str var}.
% \end{function}
%
% \begin{function}{\str_gset:Nn, \str_gset:Nx, \str_gset:cn, \str_gset:cx}
%   \begin{syntax}
%     \cs{str_gset:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and saves the result in \meta{str var} globally.
% \end{function}
%
% \begin{function}
%   {
%     \str_put_left:Nn, \str_put_left:Nx,
%     \str_put_left:cn, \str_put_left:cx
%   }
%   \begin{syntax}
%     \cs{str_put_left:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and prepends the result to \meta{str var}.
%   The current contents of the \meta{str var} are not
%   automatically converted to a string.
% \end{function}
%
% \begin{function}
%   {
%     \str_gput_left:Nn, \str_gput_left:Nx,
%     \str_gput_left:cn, \str_gput_left:cx
%   }
%   \begin{syntax}
%     \cs{str_gput_left:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and prepends the result to \meta{str var}, globally.
%   The current contents of the \meta{str var} are not
%   automatically converted to a string.
% \end{function}
%
% \begin{function}
%   {
%     \str_put_right:Nn, \str_put_right:Nx,
%     \str_put_right:cn, \str_put_right:cx
%   }
%   \begin{syntax}
%     \cs{str_put_right:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and appends the result to \meta{str var}.
%   The current contents of the \meta{str var} are not
%   automatically converted to a string.
% \end{function}
%
% \begin{function}
%   {
%     \str_gput_right:Nn, \str_gput_right:Nx,
%     \str_gput_right:cn, \str_gput_right:cx
%   }
%   \begin{syntax}
%     \cs{str_gput_right:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and appends the result to \meta{str var}, globally.
%   The current contents of the \meta{str var} are not
%   automatically converted to a string.
% \end{function}
%
% \begin{function}{\str_input:Nn, \str_ginput:Nn}
%   \begin{syntax}
%     \cs{str_input:Nn} \meta{str var} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} into a \meta{string}, and stores
%   it in the \meta{str var}, within the current \TeX{} group level
%   for the \texttt{input} variant and globally for the \texttt{ginput}
%   version.
%   Special characters can be input by
%   escaping them with a backslash.
%   \begin{itemize}
%     \item Spaces are ignored unless escaped with a backslash.
%     \item |\xhh| produces the character with code \texttt{hh}
%       in hexadecimal: when |\x| is encountered, up to two hexadecimal digits
%       (\texttt{0}--\texttt{9}, \texttt{a}--\texttt{f},
%       \texttt{A}--\texttt{F})
%       are read to give a number between $0$ and $255$.
%     \item |\x{hh...}| produces the character with code \texttt{hh...}
%       (an arbitrary number of hexadecimal digits are read):
%       this is mostly useful for \LuaTeX{} and \XeTeX{}.
%     \item |\a|, |\e|, |\f|, |\n|, |\r|, |\t| stand for specific characters:
%     \begin{center}
%       \begin{tabular}{cccc}
%         |\a| & |\^^G| & alarm  & hex \texttt{07} \\
%         |\e| & |\^^[| & escape & hex \texttt{1B} \\
%         |\f| & |\^^L| & form feed & hex \texttt{0C} \\
%         |\n| & |\^^J| & new line  & hex \texttt{0A} \\
%         |\r| & |\^^M| & carriage return & hex \texttt{0D} \\
%         |\t| & |\^^I| & horizontal tab  & hex \texttt{09} \\
%       \end{tabular}
%     \end{center}
%   \end{itemize}
%   For instance,
%   \begin{quote}
%     \cs{tl_new:N} \cs{l_my_str} \\
%     \cs{str_input:Nn} \cs{l_my_str} |{\x3C \\ \# abc\ def\^\n}|
%   \end{quote}
%   results in \cs{l_my_str} containing the characters |<\#abc def^|,
%   followed by a newline character (hex \texttt{0A})
%   since |<| has \textsc{ascii} code \texttt{3C} (in hexadecimal).
% \end{function}
%
% \subsection{Characters given by their position}
%
% \begin{function}[EXP]
%   {\str_length:N, \str_length:n, \str_length_ignore_spaces:n}
%   \begin{syntax}
%     \cs{str_length:n} \Arg{token list}
%   \end{syntax}
%   Leaves the length of the string representation of \meta{token list}
%   in the input stream as an integer denotation. The functions differ in
%   their treatment of spaces.
%   In the case of \cs{str_length:N} and \cs{str_length:n},
%   all characters including spaces are counted.
%   The \cs{str_length_ignore_spaces:n} leaves the number of non-space
%   characters in the input stream.
%   \begin{texnote}
%     The \cs{str_length:n} of a given token list may depend
%     on the category codes in effect when it is measured,
%     and the value of the \tn{escapechar}: for instance
%     |\str_length:n {\a}| may return $1$, $2$ or $3$ depending
%     on the escape character, and the category code of \texttt{a}.
%   \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\str_head:N, \str_head:n, \str_head_ignore_spaces:n}
%   \begin{syntax}
%     \cs{str_head:n} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} into a \meta{string}.
%   The first character in the \meta{string} is then
%   left in the input stream, with category code \enquote{other}.
%   The functions differ in their treatment of spaces.
%   In the case of \cs{str_head:N} and \cs{str_head:n},
%   a leading space is returned with category code $10$ (blank space).
%   The \cs{str_head_ignore_spaces:n} function leaves  the first
%   non-space character in the input stream.
%   If the \meta{token list} is empty (or blank in the case of the
%   \texttt{_ignore_spaces} variant), then nothing is left on the
%   input stream.
% \end{function}
%
% \begin{function}[EXP]{\str_tail:N, \str_tail:n, \str_tail_ignore_spaces:n}
%   \begin{syntax}
%     \cs{str_tail:n} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   removes the first 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_ignore_spaces:n} trims
%   the first non-space character.
% \end{function}
%
% \begin{function}[EXP]{\str_item:Nn, \str_item:nn, \str_item_ignore_spaces:nn}
%   \begin{syntax}
%     \cs{str_item:nn} \Arg{token list} \Arg{integer expression}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string}, and
%   leaves in the input stream the character in position
%   \meta{integer expression} of the \meta{string}.
%   In the case of \cs{str_item:Nn} and \cs{str_item:nn},
%   all characters including spaces are taken into account.
%   The \cs{str_item_ignore_spaces:nn} function skips spaces
%   in its argument.
%   If the \meta{integer expression} is negative, characters
%   are counted from the end of the \meta{string}. Hence, $-1$ is
%   the right-most character, \emph{etc.}, while $0$ is the first
%   (left-most) character.
% \end{function}
%
% \begin{function}[EXP]
%   {\str_substr:Nnn, \str_substr:nnn, \str_substr_ignore_spaces:nnn}
%   \begin{syntax}
%     \cs{str_substr:nnn} \Arg{token list} \Arg{start index} \Arg{end index}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string},
%   and leaves in the input stream the characters
%   between \meta{start index} (inclusive) and \meta{end index} (exclusive).
%   If either of \meta{start index} or \meta{end index} is negative,
%   the it is incremented by the length of the list. Both \meta{start index}
%   and \meta{end index} count from $0$ for the first (left most) character.
% \end{function}
%
% \subsection{String conditionals}
%
% \begin{function}[EXP, pTF]
%   {
%     \str_if_eq:NN,
%     \str_if_eq:nn, \str_if_eq:Vn, \str_if_eq:on, \str_if_eq:no,
%     \str_if_eq:nV, \str_if_eq:VV, \str_if_eq:xx
%   }
%   \begin{syntax}
%     \cs{str_if_eq_p:nn} \Arg{tl1} \Arg{tl2}
%     \cs{str_if_eq:nnTF} \Arg{tl1} \Arg{tl2} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Compares the two \meta{token lists} on a character by character
%   basis, and is \texttt{true} if the two lists contain the same
%   characters in the same order. Thus for example
%   \begin{verbatim}
%     \str_if_eq_p:xx { abc } { \tl_to_str:n { abc } }
%   \end{verbatim}
%   is logically \texttt{true}. All versions of these functions are fully
%   expandable (including those involving an \texttt{x}-type
%   expansion).
% \end{function}
%
% \begin{function}[EXP, pTF]
%   {\str_if_contains_char:NN, \str_if_contains_char:nN}
%   \begin{syntax}
%     \cs{str_if_contains_char:nN} \Arg{token list} \meta{char}
%   \end{syntax}
%   Converts the \meta{token list} to a \meta{string}
%   and tests whether the \meta{char} is present in the \meta{string}.
%   The \meta{char} can be given either directly, or as a one
%   letter control sequence.
% \end{function}
%
% \subsection{Byte conditionals}
%
% \begin{function}[EXP, pTF]{\str_if_bytes:N}
%   \begin{syntax}
%     \cs{str_if_bytes:NTF} \meta{str var} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{str var} only contains characters
%   in the range $0$ to $255$.
% \end{function}
%
% ^^A\begin{function}[EXP, pTF]{\str_if_UTF_viii:N}
% ^^A  \begin{syntax}
% ^^A    \cs{str_if_UTF_viii:N} \meta{str var} \Arg{true code} \Arg{false code}
% ^^A  \end{syntax}
% ^^A  Tests whether the \meta{str var} only contains characters
% ^^A  in the range $0$--$255$, and forms a valid \texttt{UTF8} string.
% ^^A  \textbf{Missing!} ^^A Missing.
% ^^A\end{function}
%
% \subsection{Byte conversion}
% 
% Byte conversions are necessary where strings are to be used in PDF
% string objects or within URLs. In both cases, only a restricted subset
% of characters are permitted.
%
% \begin{function}{\str_native_from_UTF_viii:NN}
%   \begin{syntax}
%     \cs{str_native_from_UTF_viii:NN} \meta{str~var1} \meta{str~var2}
%   \end{syntax}
%   Reads the contents of the \meta{str~var2} as an \textsc{utf8}-encoded
%   sequence of bytes, and stores the resulting characters (which can
%   now have any character code) into \meta{str~var1}.
%   This function raises an error if the \meta{str~var2} is not
%   a valid sequence of bytes in the \textsc{utf8} encoding.
%   In the \pdfTeX{} engine, this function raises an error if any of the
%   resulting characters is outside the range $0$ to $255$.
% \end{function}
%
% \begin{function}{\str_UTF_viii_from_native:NN}
%   \begin{syntax}
%     \cs{str_UTF_viii_from_native:NN} \meta{str~var1} \meta{str~var2}
%   \end{syntax}
%   Converts each character of the \meta{str~var2} into
%   a sequence of bytes, as defined by the \textsc{utf8}
%   encoding, and stores the result in \meta{str~var1}.
%   In the \pdfTeX{} engine, this function is of course
%   of very little use, but can be used without harm:
%   characters in the range $0$ to $127$ are left unchanged,
%   and characters in the range $128$ to $255$ become two-byte
%   sequences, as per the definition of \texttt{UTF8}.
% \end{function}
%
% \begin{function}
%   {\str_bytes_escape_hexadecimal:NN, \str_bytes_unescape_hexadecimal:NN}
%   \begin{syntax}
%     \cs{str_bytes_escape_hexadecimal:NN} \meta{str var1} \meta{str var2}
%     \cs{str_bytes_unescape_hexadecimal:NN} \meta{str var1} \meta{str var2}
%   \end{syntax}
%   The \texttt{escape} variant takes each character in \meta{str var1}
%   and converts it into the hexadecimal representation. The resulting
%   string is stored in \meta{str var2} within the current \TeX{} group
%   level. The \texttt{unescape} variant reverses this process.
%   Thus for example
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { Hello ( ) }
%     \str_bytes_escape_hexadecimal:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |48656C6C6F2829|,
%   while
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { 48656C6C6F2829 }
%     \str_bytes_unescape_hexadecimal:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello()|.
%   See also \tn{pdfescapehex}.
% \end{function}
%
% \begin{function}
%   {\str_bytes_escape_name:NN, \str_bytes_unescape_name:NN}
%   \begin{syntax}
%     \cs{str_bytes_escape_name:NN} \meta{str var1} \meta{str var2}
%     \cs{str_bytes_unescape_name:NN} \meta{str var1} \meta{str var2}
%   \end{syntax}
%   The \texttt{escape} variant takes each character in \meta{str var1}
%   and replaces any which cannot be used directly in a PDF string object
%   with the appropriate hexadecimal representation preceded by the |#|
%   character. The resulting
%   string is stored in \meta{str var2} within the current \TeX{} group
%   level. The \texttt{unescape} variant reverses this process. Thus for
%   example
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { Hello ( ) }
%     \str_bytes_escape_name:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello#28#29|,
%   while
%   \begin{verbatim}
%     \char_set_catcode_other:N \#
%     \str_set:Nn \l_mya_str { Hello#28#29  }
%     \str_bytes_unescape_name:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello()|.
%   See also \tn{pdfescapename}.
% \end{function}
%
% \begin{function}{\str_bytes_escape_string:NN, \str_bytes_unescape_string:NN}
%   \begin{syntax}
%     \cs{str_bytes_escape_string:NN} \meta{str var1} \meta{str var2}
%     \cs{str_bytes_unescape_string:NN} \meta{str var1} \meta{str var2}
%   \end{syntax}
%   The \texttt{escape} variant takes each character in \meta{str var1}
%   and prepends a |\| to any which cannot be used directly in a PDF string
%   object. The resulting string is stored in \meta{str var2} within the
%   current \TeX{} group level. The \texttt{unescape} variant reverses this
%   process. Thus for example
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { Hello [ ] }
%     \str_bytes_escape_string:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello\(\)|,
%   while
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { Hello\(\) }
%     \str_bytes_unescape_string:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello()|.
%   Some characters (for example a space) are converted to a three-digit
%   octal representation, so for example a space gives |\040|.
%   See also \tn{pdfescapename}.
% \end{function}
%
% \begin{function}{\str_bytes_percent_encode:NN, \str_bytes_percent_decode:NN}
%   \begin{syntax}
%     \cs{str_bytes_percent_encode:NN} meta{str var1} \meta{str var2}
%     \cs{str_bytes_percent_decode:NN} meta{str var1} \meta{str var2}
%   \end{syntax}
%   The \texttt{escape} variant takes each character in \meta{str var1}
%   and replaces any which cannot be used directly in a URL
%   with the appropriate hexadecimal representation preceded by the |%|
%   character. The resulting
%   string is stored in \meta{str var2} within the current \TeX{} group
%   level. The \texttt{unescape} variant reverses this process. Thus for
%   example
%   \begin{verbatim}
%     \str_set:Nn \l_mya_str { Hello ( ) }
%     \str_bytes_precent_encode:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello%28%29|,
%   while
%   \begin{verbatim}
%     \char_set_catcode_other:N \%
%     \str_set:Nn \l_mya_str { Hello%28%29  }
%     \str_bytes_unescape_name:NN \l_mya_str \l_myb_str
%   \end{verbatim}
%   will result in \cs{l_myb_str} containing the string |Hello()|.
% \end{function}
%
% \subsection{Internal string functions}
%
% \begin{function}[EXP]{\tl_to_other_str:N, \tl_to_other_str:n}
%   \begin{syntax}
%     \cs{tl_to_other_str:n} \Arg{token list}
%   \end{syntax}
%   Converts the \meta{token list} to an \meta{other string}, where
%   spaces have category code \enquote{other}. These functions create
%   \enquote{safe} strings.
%   \begin{texnote}
%     These functions can be \texttt{f}-expanded without fear of losing
%     a leading space, since spaces do not have category code $10$ in
%     their result.
%   \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\str_sanitize_args:Nn, \str_sanitize_args:Nnn}
%   \begin{syntax}
%     \cs{str_sanitize_args:Nnn} \meta{function}
%     ~~\Arg{token list1} \Arg{token list2}
%   \end{syntax}
%   Converts the \meta{token lists} to \enquote{safe} strings
%   (where spaces have category code \enquote{other}),
%   and hands-in the result as arguments to \meta{function}.
% \end{function}
%
% \begin{function}[rEXP]{\str_map_tokens:Nn}
%   \begin{syntax}
%     \cs{str_map_tokens:Nn} \meta{str var} \meta{tokens}
%   \end{syntax}
%   Maps the \meta{tokens} over every character in the \meta{str var}.
% \end{function}
%
% \begin{function}{\str_aux_escape:NNNn}
%   \begin{syntax}
%     \cs{str_aux_escape:NNNn} \meta{fn1} \meta{fn2} \meta{fn3} \Arg{token list}
%   \end{syntax}
%   The \meta{token list} is converted to a string, then read from
%   left to right, interpreting backslashes as escaping the next character.
%   Unescaped characters are fed to the function \meta{fn1},
%   and escaped characters are fed to the function \meta{fn2}
%   within an \texttt{x}-expansion context (typically those functions
%   perform some tests on their argument to decide how to output them).
%   The escape sequences |\a|, |\e|, |\f|, |\n|, |\r|, |\t| and |\x|
%   are recognized as described for \cs{str_input:Nn}, and those
%   are replaced by the corresponding character, then fed to
%   \meta{fn3}. The result is assigned globally to \cs{g_str_result_tl}.
% \end{function}
%
% \subsection{Possibilities}
%
% \begin{itemize}
% \item More encodings (see Heiko's \pkg{stringenc}).
%   In particular, what is needed for pdf: \texttt{UTF-16}?
% \item \cs{str_between:nnn} \Arg{str}
%   \Arg{begin delimiter} \Arg{end delimiter} giving the piece of
%   \meta{str} between \meta{begin} and \meta{end}; could be used
%   with empty \meta{begin} or \meta{end} to indicate that we
%   want everything until \meta{end} or starting from \meta{begin},
%   respectively;
% \item \cs{str_count_in:nn} \Arg{str} \Arg{substr} giving the number
%   of occurrences of \meta{substr} in \meta{str};
% \item \cs{str_if_head_eq:nN} alias of \cs{tl_if_head_eq_charcode:nN}
% \item \cs{str_if_numeric/decimal/integer:n}, perhaps in \pkg{l3fp}?
% \end{itemize}
% Some functionalities of \pkg{stringstrings} and \pkg{xstring} as well.
%
%^^A Should "str_item" be "str_char"?
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3str} implementation}
%
%    \begin{macrocode}
%<*initex|package>
%    \end{macrocode}
%
%    \begin{macrocode}
\ProvidesExplPackage
  {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
%    \end{macrocode}
%
% Those string-related functions are defined in \pkg{l3kernel}.
% \begin{itemize}
%   \item \cs{str_if_eq:nn}[pTF] and variants,
%   \item \cs{str_if_eq_return:on},
%   \item \cs{tl_to_str:n}, \cs{tl_to_str:N}, \cs{tl_to_str:c},
%   \item \cs{token_to_str:N}, \cs{cs_to_str:N}
%   \item \cs{str_head:n}, \cs{str_head_aux:w}, (copied here)
%   \item \cs{str_tail:n}, \cs{str_tail_aux:w}, (copied here)
%   \item \cs{str_length_skip_spaces} (deprecated)
%   \item \cs{str_length_loop:NNNNNNNNN} (unchanged)
% \end{itemize}
%
% \subsection{General functions}
%
% \begin{macro}[EXP,aux]{\use_i:nnnnnnnn}
%   A function which may already be defined elsewhere.
%    \begin{macrocode}
\cs_if_exist:NF \use_i:nnnnnnnn
  { \cs_new:Npn \use_i:nnnnnnnn #1#2#3#4#5#6#7#8 {#1} }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \str_set:Nn, \str_set:Nx,
%     \str_set:cn, \str_set:cx,
%     \str_gset:Nn, \str_gset:Nx,
%     \str_gset:cn, \str_gset:cx,
%     \str_put_left:Nn, \str_put_left:Nx,
%     \str_put_left:cn, \str_put_left:cx,
%     \str_gput_left:Nn, \str_gput_left:Nx,
%     \str_gput_left:cn, \str_gput_left:cx,
%     \str_put_right:Nn, \str_put_right:Nx,
%     \str_put_right:cn, \str_put_right:cx,
%     \str_gput_right:Nn, \str_gput_right:Nx,
%     \str_gput_right:cn, \str_gput_right:cx,
%   }
%   Simply convert the token list inputs to \meta{strings}.
%    \begin{macrocode}
\group_begin:
  \cs_set_protected_nopar:Npn \str_tmp:w #1
    {
      \cs_new_protected:cpx { str_ #1 :Nn } ##1##2
        { \exp_not:c { tl_ #1 :Nx } ##1 { \exp_not:N \tl_to_str:n {##2} } }
      \exp_args:Nc \cs_generate_variant:Nn { str_ #1 :Nn } { Nx , cn , cx }
    }
  \str_tmp:w { set }
  \str_tmp:w { gset }
  \str_tmp:w { put_left }
  \str_tmp:w { gput_left }
  \str_tmp:w { put_right }
  \str_tmp:w { gput_right }
\group_end:
%    \end{macrocode}
% \end{macro}
%
% \subsection{Variables and constants}
%
% \begin{macro}{\str_tmp:w}
% \begin{variable}{\g_str_tmpa_tl}
%   Internal scratch space for some functions.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_tmp:w { }
\tl_new:N \g_str_tmpa_tl
%    \end{macrocode}
% \end{variable}
% \end{macro}
%
% \begin{variable}{\g_str_result_tl}
%   The \cs{g_str_result_tl} variable is used to hold the result
%   of various internal string operations which are typically
%   performed in a group. The variable is global so that it remains
%   defined outside the group, to be assigned to a user provided variable.
%    \begin{macrocode}
\tl_new:N \g_str_result_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_str_char_int, \l_str_bytes_int}
%   When converting from various escaped forms to raw characters,
%   we often need to read several digits (hexadecimal or octal depending
%   on the case) and keep track of the corresponding character code
%   in \cs{l_str_char_int}. For \textsc{utf8} support, the number of bytes
%   of for the current character is stored in \cs{l_str_bytes_int}.
%    \begin{macrocode}
\int_new:N \l_str_char_int
\int_new:N \l_str_bytes_int
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \c_backslash_str,
%     \c_lbrace_str,
%     \c_rbrace_str,
%     \c_hash_str,
%     \c_percent_str
%   }
%   For all of those strings, \cs{cs_to_str:N} produce characters
%   with the correct category code.
%    \begin{macrocode}
\tl_const:Nx \c_backslash_str { \cs_to_str:N \\ }
\tl_const:Nx \c_lbrace_str    { \cs_to_str:N \{ }
\tl_const:Nx \c_rbrace_str    { \cs_to_str:N \} }
\tl_const:Nx \c_hash_str      { \cs_to_str:N \# }
\tl_const:Nx \c_percent_str   { \cs_to_str:N \% }
%    \end{macrocode}
% \end{variable}
%
% \subsection{Escaping spaces}
%
% \begin{macro}[EXP]{\tl_to_other_str:N, \tl_to_other_str:n}
% \begin{macro}[EXP,aux]{\tl_to_other_str_loop:w, \tl_to_other_str_end:w}
%   Replaces all spaces by \enquote{other} spaces, after converting
%   the token list to a string via \cs{tl_to_str:n}.
%    \begin{macrocode}
\group_begin:
\char_set_lccode:nn { `\* } { `\  }
\char_set_lccode:nn { `\A } { `\A }
\tl_to_lowercase:n
  {
    \group_end:
    \cs_new:Npn \tl_to_other_str:n #1
      {
        \exp_after:wN \tl_to_other_str_loop:w \tl_to_str:n {#1} ~ %
        A ~ A ~ A ~ A ~ A ~ A ~ A ~ A ~ \q_mark \q_stop
      }
    \cs_new_nopar:Npn \tl_to_other_str_loop:w
      #1 ~ #2 ~ #3 ~ #4 ~ #5 ~ #6 ~ #7 ~ #8 ~ #9 \q_stop
      {
        \if_meaning:w A #8
          \tl_to_other_str_end:w
        \fi:
        \tl_to_other_str_loop:w
        #9 #1 * #2 * #3 * #4 * #5 * #6 * #7 * #8 * \q_stop
      }
    \cs_new_nopar:Npn \tl_to_other_str_end:w \fi: #1 \q_mark #2 * A #3 \q_stop
      { \fi: #2 }
  }
\cs_new_nopar:Npn \tl_to_other_str:N { \exp_args:No \tl_to_other_str:n }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\str_sanitize_args:Nn, \str_sanitize_args:Nnn}
%   Here, \texttt{f}-expansion does not lose leading spaces,
%   since they have catcode \enquote{other} after \cs{str_sanitize:n}.
%    \begin{macrocode}
\cs_new:Npn \str_sanitize_args:Nn #1#2
  { \exp_args:Nf #1 { \tl_to_other_str:n {#2} } }
\cs_new:Npn \str_sanitize_args:Nnn #1#2#3
  {
    \exp_args:Nff #1
      { \tl_to_other_str:n {#2} }
      { \tl_to_other_str:n {#3} }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Characters given by their position}
%
% \begin{macro}[EXP]{\str_length:N}
% \begin{macro}[EXP]{\str_length:n}
% \begin{macro}[EXP]{\str_length_ignore_spaces:n}
% \begin{macro}[EXP]{\str_length_unsafe:n}
% \begin{macro}[EXP,aux]{\str_length_aux:n,\str_length_loop:NNNNNNNNN}
%   The length of a string is found by first changing all spaces
%   to other spaces using \cs{tl_to_other_str:n}, then counting
%   characters $9$ at a time. When the end is reached, |#9|
%   has the form |X|\meta{digit}, the catcode test is true,
%   the digit gets added to the sum, and the loop is terminated
%   by \cs{use_none_delimit_by_q_stop:w}.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_length:N { \exp_args:No \str_length:n }
\cs_new:Npn \str_length:n { \str_sanitize_args:Nn \str_length_unsafe:n }
\cs_new_nopar:Npn \str_length_unsafe:n #1
  { \str_length_aux:n { \str_length_loop:NNNNNNNNN #1 } }
\cs_new:Npn \str_length_ignore_spaces:n #1
  {
    \str_length_aux:n
      { \exp_after:wN \str_length_loop:NNNNNNNNN \tl_to_str:n {#1} }
  }
\cs_new:Npn \str_length_aux:n #1
  {
    \int_eval:n
      {
        #1
        { X \c_eight } { X \c_seven } { X \c_six   }
        { X \c_five  } { X \c_four  } { X \c_three }
        { X \c_two   } { X \c_one   } { X \c_zero  }
        \q_stop
      }
  }
\cs_set:Npn \str_length_loop:NNNNNNNNN #1#2#3#4#5#6#7#8#9
  {
    \if_catcode:w X #9
      \exp_after:wN \use_none_delimit_by_q_stop:w
    \fi:
    \c_nine + \str_length_loop:NNNNNNNNN
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\str_head:N}
% \begin{macro}[EXP]{\str_head:n}
% \begin{macro}[EXP]{\str_head_ignore_spaces:n}
% \begin{macro}[EXP]{\str_head_unsafe:n}
% \begin{macro}[EXP,aux]{\str_head_aux:w}
%   The cases of \cs{str_head_ignore_spaces:n} and
%   \cs{str_head_unsafe:n} are mostly identical to
%   \cs{tl_head:n}.
%   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{str_head_aux:w}
%   takes an argument delimited by a space. If |#1| starts with a
%   non-space character, \cs{use_i_delimit_by_q_stop:nw} leaves that
%   in the input stream. On the other hand, if |#1| starts with a
%   space, the \cs{str_head_aux:w} takes an empty argument, and
%   the single (braced) space in the definition of \cs{str_head_aux:w}
%   makes its way to the output. Finally, for an empty argument,
%   the (braced) empty brace group in the definition of \cs{str_head:n}
%   gives an empty result after passing through
%   \cs{use_i_delimit_by_q_stop:nw}.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_head:N { \exp_args:No \str_head:n }
\cs_set:Npn \str_head:n #1
  {
    \exp_after:wN \str_head_aux:w
    \tl_to_str:n {#1}
    { { } } ~ \q_stop
  }
\cs_set_nopar:Npn \str_head_aux:w #1 ~ %
  { \use_i_delimit_by_q_stop:nw #1 { ~ } }
\cs_new:Npn \str_head_ignore_spaces:n #1
  { \exp_after:wN \use_i_delimit_by_q_stop:nw \tl_to_str:n {#1} { } \q_stop }
\cs_new_nopar:Npn \str_head_unsafe:n #1
  { \use_i_delimit_by_q_stop:nw #1 { } \q_stop }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\str_tail:N}
% \begin{macro}[EXP]{\str_tail:n}
% \begin{macro}[EXP]{\str_tail_ignore_spaces:n}
% \begin{macro}[EXP]{\str_tail_unsafe:n}
% \begin{macro}[EXP,aux]{\str_tail_aux:w}
% \begin{macro}[EXP,aux]{\str_tail_aux_ii:w}
%   As when fetching the head of a string, the cases
%   \enquote{\texttt{ignore_spaces:n}} and \enquote{\texttt{unsafe:n}}
%   are similar to \cs{tl_tail:n}.
%   The more commonly used \cs{str_tail:n} function is a little bit
%   more convoluted: hitting the front of the string with
%   \cs{reverse_if:N} \cs{if_charcode:w} \cs{scan_stop:}
%   removes the first character (which necessarily makes the test true,
%   since it cannot match \cs{scan_stop:}). The auxiliary function inserts
%   the required \cs{fi:} to close the conditional, and leaves the tail
%   of the string in the input string. The details are such that an empty
%   string has an empty tail.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_tail:N { \exp_args:No \str_tail:n }
\cs_set:Npn \str_tail:n #1
  {
    \exp_after:wN \str_tail_aux:w
    \reverse_if:N \if_charcode:w
        \scan_stop: \tl_to_str:n {#1} X X \q_stop
  }
\cs_set_nopar:Npn \str_tail_aux:w #1 X #2 \q_stop { \fi: #1 }
\cs_new:Npn \str_tail_ignore_spaces:n #1
  {
    \exp_after:wN \str_tail_aux_ii:w
    \tl_to_str:n {#1} X { } X \q_stop
  }
\cs_new_nopar:Npn \str_tail_unsafe:n #1
  { \str_tail_aux_ii:w #1 X { } X \q_stop }
\cs_new_nopar:Npn \str_tail_aux_ii:w #1 #2 X #3 \q_stop { #2 }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP,int]{\str_skip_do:nn}
% \begin{macro}[EXP,aux]{\str_skip_aux:nnnnnnnnn}
% \begin{macro}[EXP,aux]{\str_skip_end:nn}
% \begin{macro}[EXP,aux]{\str_skip_end_ii:nwn}
%   Removes |max(#1,0)| characters then leaves |#2| in the input stream.
%   We remove characters $7$ at a time. When the number of characters
%   to remove is not a multiple of $7$, we need to remove less than
%   $7$ characters in the last step. This is done by inserting a number
%   of \texttt{X}, which are discarded as if they were part of the string.
%    \begin{macrocode}
\cs_new:Npn \str_skip_do:nn #1
  {
    \if_num:w \int_eval:w #1 > \c_seven
      \exp_after:wN \str_skip_aux:nnnnnnnnn
    \else:
      \exp_after:wN \str_skip_end:n
    \fi:
      {#1}
  }
\cs_new:Npn \str_skip_aux:nnnnnnnnn #1#2#3#4#5#6#7#8#9
  { \exp_args:Nf \str_skip_do:nn { \int_eval:n { #1 - \c_seven } } {#2} }
\cs_new:Npn \str_skip_end:n #1
  {
    \if_case:w \int_eval:w #1 \int_eval_end:
         \str_skip_end_ii:nwn { XXXXXXX }
    \or: \str_skip_end_ii:nwn { XXXXXX }
    \or: \str_skip_end_ii:nwn { XXXXX }
    \or: \str_skip_end_ii:nwn { XXXX }
    \or: \str_skip_end_ii:nwn { XXX }
    \or: \str_skip_end_ii:nwn { XX }
    \or: \str_skip_end_ii:nwn { X }
    \or: \str_skip_end_ii:nwn {  }
    \else: \str_skip_end_ii:nwn { XXXXXXX }
    \fi:
  }
\cs_new:Npn \str_skip_end_ii:nwn #1#2 \fi: #3
  { \fi: \use_i:nnnnnnnn {#3} #1 }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP,int]{\str_collect_do:nn}
% \begin{macro}[EXP,aux]{\str_collect_aux:n,\str_collect_aux:nnNNNNNNN}
% \begin{macro}[EXP,aux]
%   {
%     \str_collect_end:nn,
%     \str_collect_end_ii:nwn,
%     \str_collect_end_iii:nwNNNNNNN
%   }
%   Collects |max(#1,0)| characters, and feeds them as an argument to |#2|.
%   Again, we grab $7$ characters at a time. Instead of inserting
%   a string of \texttt{X} to fill in to a multiple of $7$, we insert
%   empty groups, so that they disappear in this context where arguments
%   are accumulated.
%    \begin{macrocode}
\cs_new:Npn \str_collect_do:nn #1#2
  { \str_collect_aux:n {#1} { \str_collect_end_iii:nwNNNNNNN {#2} } }
\cs_new:Npn \str_collect_aux:n #1
  {
    \int_compare:nNnTF {#1} > \c_seven
      { \str_collect_aux:nnNNNNNNN }
      { \str_collect_end:n }
      {#1}
  }
\cs_new:Npn \str_collect_aux:nnNNNNNNN #1#2 #3#4#5#6#7#8#9
  {
    \exp_args:Nf \str_collect_aux:n
      { \int_eval:n { #1 - \c_seven } }
      { #2 #3#4#5#6#7#8#9 }
  }
\cs_new:Npn \str_collect_end:n #1
  {
    \if_case:w \int_eval:w #1 \int_eval_end:
         \str_collect_end_ii:nwn { { } { } { } { } { } { } { } }
    \or: \str_collect_end_ii:nwn { { } { } { } { } { } { } }
    \or: \str_collect_end_ii:nwn { { } { } { } { } { } }
    \or: \str_collect_end_ii:nwn { { } { } { } { } }
    \or: \str_collect_end_ii:nwn { { } { } { } }
    \or: \str_collect_end_ii:nwn { { } { } }
    \or: \str_collect_end_ii:nwn { { } }
    \or: \str_collect_end_ii:nwn {  }
    \else: \str_collect_end_ii:nwn { { } { } { } { } { } { } { } }
    \fi:
  }
\cs_new:Npn \str_collect_end_ii:nwn #1#2 \fi: #3
  { \fi: #3 \q_stop #1 }
\cs_new:Npn \str_collect_end_iii:nwNNNNNNN #1 #2 \q_stop #3#4#5#6#7#8#9
  { #1 {#2#3#4#5#6#7#8#9} }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\str_item:Nn}
% \begin{macro}[EXP]{\str_item:nn}
% \begin{macro}[EXP]{\str_item_ignore_spaces:nn}
% \begin{macro}[EXP]{\str_item_unsafe:nn}
% \begin{macro}[EXP,aux]{\str_item_aux:nn}
%   This is mostly shuffling arguments around to avoid measuring
%   the length of the string more than once, and make sure that
%   the parameters given to \cs{str_skip_do:nn} are necessarily
%   within the bounds of the length of the string.
%   The \cs{str_item_ignore_spaces:nn} function cheats a little bit
%   in that it doesn't hand to \cs{str_item_unsafe:nn} a truly
%   \enquote{safe} string. This is alright, as everything else
%   is done with undelimited arguments.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_item:Nn { \exp_args:No \str_item:nn }
\cs_new:Npn \str_item:nn #1#2
  {
    \exp_args:Nf \tl_to_str:n
      { \str_sanitize_args:Nn \str_item_unsafe:nn {#1} {#2} }
  }
\cs_new:Npn \str_item_ignore_spaces:nn #1
  { \exp_args:No \str_item_unsafe:nn { \tl_to_str:n {#1} } }
\cs_new_nopar:Npn \str_item_unsafe:nn #1#2
  {
    \exp_args:Nff \str_item_aux:nn
      { \int_eval:n {#2} }
      { \str_length_unsafe:n {#1} }
      #1
    \q_stop
  }
\cs_new_nopar:Npn \str_item_aux:nn #1#2
  {
    \int_compare:nNnTF {#1} < \c_zero
      {
        \int_compare:nNnTF {#1} < {-#2}
          { \use_none_delimit_by_q_stop:w }
          {
            \str_skip_do:nn { #1 + #2 }
              { \use_i_delimit_by_q_stop:nw }
          }
      }
      {
        \int_compare:nNnTF {#1} < {#2}
          {
            \str_skip_do:nn {#1}
              { \use_i_delimit_by_q_stop:nw }
          }
          { \use_none_delimit_by_q_stop:w }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\str_substr:Nnn}
% \begin{macro}[EXP]{\str_substr:nnn}
% \begin{macro}[EXP]{\str_substr_ignore_spaces:nnn}
% \begin{macro}[EXP]{\str_substr_unsafe:nnn}
% \begin{macro}[EXP,aux]{\str_substr_aux:nnnw}
% \begin{macro}[EXP,aux]{\str_substr_aux_ii:nnw}
% \begin{macro}[EXP,aux]{\str_aux_eval_args:Nnnn}
% \begin{macro}[EXP,aux]{\str_aux_normalize_range:nn}
%   Sanitize the string, then limit the second and third arguments
%   to be at most the length of the string (this avoids needing
%   to check for the end of the string when grabbing characters).
%   Afterwards, skip characters, then keep some more, and finally
%   drop the end of the string.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_substr:Nnn { \exp_args:No \str_substr:nnn }
\cs_new:Npn \str_substr:nnn #1#2#3
  {
    \exp_args:Nf \tl_to_str:n
      { \str_sanitize_args:Nn \str_substr_unsafe:nnn {#1} {#2} {#3} }
  }
\cs_new:Npn \str_substr_ignore_spaces:nnn #1
  { \exp_args:No \str_substr_unsafe:nnn { \tl_to_str:n {#1} } }
\cs_new:Npn \str_substr_unsafe:nnn #1#2#3
  {
    \str_aux_eval_args:Nnnn \str_substr_aux:nnnw
      { \str_length_unsafe:n {#1} }
      {#2}
      {#3}
      #1
    \q_stop
  }
\cs_new:Npn \str_substr_aux:nnnw #1#2#3
  {
    \exp_args:Nf \str_substr_aux_ii:nnw
      { \str_aux_normalize_range:nn {#2} {#1} }
      { \str_aux_normalize_range:nn {#3} {#1} }
  }
\cs_new:Npn \str_substr_aux_ii:nnw #1#2
  {
    \str_skip_do:nn {#1}
      {
        \exp_args:Nf \str_collect_do:nn
          { \int_eval:n { #2 - #1 } }
          { \use_i_delimit_by_q_stop:nw }
      }
  }
\cs_new:Npn \str_aux_eval_args:Nnnn #1#2#3#4
  {
    \exp_after:wN #1
    \exp_after:wN { \int_value:w \int_eval:w #2 \exp_after:wN }
    \exp_after:wN { \int_value:w \int_eval:w #3 \exp_after:wN }
    \exp_after:wN { \int_value:w \int_eval:w #4 }
  }
\cs_new:Npn \str_aux_normalize_range:nn #1#2
  {
    \int_eval:n
      {
        \if_num:w #1 < \c_zero
          \if_num:w #1 < - #2 \exp_stop_f:
            \c_zero
          \else:
            #1 + #2
          \fi:
        \else:
          \if_num:w #1 < #2 \exp_stop_f:
            #1
          \else:
            #2
          \fi:
        \fi:
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Internal mapping function}
%
% \begin{macro}[rEXP,int]{\str_map_tokens:nn}
% \begin{macro}[rEXP,int]{\str_map_tokens:Nn}
% \begin{macro}[rEXP,aux]{\str_map_tokens_aux:nn}
% \begin{macro}[rEXP,aux]{\str_map_tokens_loop:nN}
% \begin{macro}[rEXP,int]{\str_map_break_do:n}
%   We simply need to be careful with spaces.
%   Spaces are fed to the mapped tokens with
%   category code $12$, not $10$.
%    \begin{macrocode}
\cs_new_nopar:Npn \str_map_tokens:Nn
  { \exp_args:No \str_map_tokens:nn }
\cs_new_nopar:Npn \str_map_tokens:nn
  { \str_sanitize_args:Nn \str_map_tokens_aux:nn }
\cs_new:Npn \str_map_tokens_aux:nn #1#2
  {
    \str_map_tokens_loop:nN {#2} #1
      { ? \use_none_delimit_by_q_recursion_stop:w } \q_recursion_stop
  }
\cs_new_nopar:Npn \str_map_tokens_loop:nN #1#2
  {
    \use_none:n #2
    #1 #2
    \str_map_tokens_loop:nN {#1}
  }
\cs_new_eq:NN \str_map_break_do:n \use_i_delimit_by_q_recursion_stop:nw
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{String conditionals}
%
% \begin{macro}[EXP,pTF]{\str_if_eq:NN}
% \begin{macro}[EXP,pTF]{\str_if_eq:nn,\str_if_eq:xx}
%   The \texttt{nn} and \texttt{xx} variants are already
%   defined in \pkg{l3basics}.
%    \begin{macrocode}
\prg_new_conditional:Npnn \str_if_eq:NN #1#2 { p , TF , T , F }
  {
    \if_int_compare:w \pdftex_strcmp:D { \tl_to_str:N #1 } { \tl_to_str:N #2 }
      = \c_zero \prg_return_true: \else: \prg_return_false: \fi:
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP,pTF]{\str_if_contains_char:NN}
% \begin{macro}[EXP,pTF]{\str_if_contains_char:nN}
% \begin{macro}[EXP,aux]{\str_if_contains_char_aux:NN}
% \begin{macro}[EXP,aux]{\str_if_contains_char_end:w}
%   Loop over the characters of the string, comparing character codes.
%   We allow |#2| to be a single-character control sequence, hence the
%   use of \cs{int_compare:nNnT} rather than \cs{token_if_eq_charcode:NNT}.
%   The loop is broken if character codes match. Otherwise we return
%   \enquote{false}.
%    \begin{macrocode}
\prg_new_conditional:Npnn \str_if_contains_char:NN #1#2 { p , T , F , TF }
  {
    \str_map_tokens:Nn #1 { \str_if_contains_char_aux:NN #2 }
    \prg_return_false:
  }
\prg_new_conditional:Npnn \str_if_contains_char:nN #1#2 { p , T , F , TF }
  {
    \str_map_tokens:nn {#1} { \str_if_contains_char_aux:NN #2 }
    \prg_return_false:
  }
\cs_new_nopar:Npn \str_if_contains_char_aux:NN #1#2
  {
    \if_num:w `#1 = `#2 \exp_stop_f:
      \str_if_contains_char_end:w
    \fi:
  }
\cs_new_nopar:Npn \str_if_contains_char_end:w \fi: #1 \prg_return_false:
  { \fi: \prg_return_true: }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP,pTF]{\str_if_bytes:N}
% \begin{macro}[EXP,aux]{\str_if_bytes_aux:N}
%   Loop over the string, checking if every character code is less than $256$.
%    \begin{macrocode}
\prg_new_conditional:Npnn \str_if_bytes:N #1 { p , T , F , TF }
  {
    \str_map_tokens:Nn #1 { \str_if_bytes_aux:N }
    \prg_return_true:
  }
\cs_new_nopar:Npn \str_if_bytes_aux:N #1
  {
    \int_compare:nNnF {`#1} < \c_two_hundred_fifty_six
      {
        \use_i_delimit_by_q_recursion_stop:nw
          { \prg_return_false: \use_none:n }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Internal conditionals}
%
% \begin{macro}[aux]{\str_aux_hexadecimal_test:NTF}
%   This test is used when reading hexadecimal digits, for the |\x| escape
%   sequence, and some conversion functions. It returns \meta{true} if the
%   token is a hexadecimal digit, and \meta{false} otherwise. It has the
%   additional side-effect of updating the value of
%   \cs{l_str_char_int} (number formed in base $16$ from the digits
%   read so far).
%    \begin{macrocode}
\prg_new_protected_conditional:Npnn \str_aux_hexadecimal_test:N #1 { TF }
  {
    \tl_if_in:onTF { \tl_to_str:n { abcdef } } {#1}
      {
        \int_set:Nn \l_str_char_int
          { \c_sixteen * \l_str_char_int + `#1 - 87 }
        \prg_return_true:
      }
      {
        \if_num:w \c_fifteen < "1 \exp_not:N #1 \exp_stop_f:
          \int_set:Nn \l_str_char_int
            { \c_sixteen * \l_str_char_int + "#1 }
          \prg_return_true:
        \else:
          \prg_return_false:
        \fi:
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[aux]{\str_aux_octal_test:NTF}
%   This test is used when reading octal digits, for
%   some conversion functions. It returns \meta{true} if the
%   token is an octal digit, and \meta{false} otherwise.
%   It has the additional side-effect of updating the value of
%   \cs{l_str_char_int} (number formed in base $8$ from the digits
%   read so far).
%    \begin{macrocode}
\prg_new_protected_conditional:Npnn \str_aux_octal_test:N #1 { TF }
  {
    \if_num:w \c_seven < '1 \exp_not:N #1 \exp_stop_f:
      \int_set:Nn \l_str_char_int
        { \c_eight * \l_str_char_int + '#1 }
      \prg_return_true:
    \else:
      \prg_return_false:
    \fi:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\str_aux_char_if_octal_digit:NTF}
%   ^^A to be removed.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_aux_char_if_octal_digit:NTF #1
  { \tl_if_in:nnTF { 01234567 } {#1} }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Conversions}
%
% \subsubsection{Simple unescaping}
%
% The code of this section is used both here for \cs{str_(g)input:Nn},
% and in the regular expression module to go through the regular expression
% once before actually parsing it. The goal in that case is to turn any
% character with a meaning in regular expressions (\texttt{*}, \texttt{?},
% \texttt{\{}, etc.) into a marker indicating that this was a special
% character,
% and replace any escaped character by the corresponding unescaped character,
% so that the \pkg{l3regex} code can avoid caring about escaping issues
% (those can become quite complex to handle in combination with ranges
% in character classes).
%
% The idea is to feed unescaped characters to one function,
% escaped characters to another, and feed |\a|, |\e|, |\f|,
% |\n|, |\r|, |\t| and |\x| converted to the appropriate
% character to a third function. Spaces are ignored unless
% escaped.
% For the \cs{str_(g)input:Nn} application, all the functions are simply
% \cs{token_to_str:N} (this ensures that spaces correctly get assigned
% category code $10$).
% For the \pkg{l3regex} applications, the functions do some further
% tests on the character they receive.
%
% \begin{macro}{\str_input:Nn,\str_ginput:Nn}
%   Simple wrappers around the internal \cs{str_aux_escape:NNNn}.
%    \begin{macrocode}
\cs_new_protected:Npn \str_input:Nn #1#2
  {
    \str_aux_escape:NNNn \token_to_str:N \token_to_str:N \token_to_str:N {#2}
    \tl_set_eq:NN #1 \g_str_result_tl
  }
\cs_new_protected:Npn \str_ginput:Nn #1#2
  {
    \str_aux_escape:NNNn \token_to_str:N \token_to_str:N \token_to_str:N {#2}
    \tl_gset_eq:NN #1 \g_str_result_tl
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{\str_aux_escape:NNNn}
% \begin{macro}[aux]{\str_aux_escape_unescaped:N}
% \begin{macro}[aux]{\str_aux_escape_escaped:N}
% \begin{macro}[aux]{\str_aux_escape_raw:N}
% \begin{macro}[aux]{\str_aux_escape_loop:N}
% \begin{macro}[aux]+\str_aux_escape_\:w+
%   Treat the argument as an \meta{escaped string},
%   and store the corresponding \meta{string} globally
%   in \cs{g_str_result_tl}.
%    \begin{macrocode}
\cs_new_eq:NN \str_aux_escape_unescaped:N \use:n
\cs_new_eq:NN \str_aux_escape_escaped:N   \use:n
\cs_new_eq:NN \str_aux_escape_raw:N       \use:n
\cs_new_protected:Npn \str_aux_escape:NNNn #1#2#3#4
  {
    \group_begin:
      \cs_set_nopar:Npn \str_aux_escape_unescaped:N { #1 }
      \cs_set_nopar:Npn \str_aux_escape_escaped:N { #2 }
      \cs_set_nopar:Npn \str_aux_escape_raw:N { #3 }
      \int_set:Nn \tex_escapechar:D { 92 }
      \tl_gset:Nx \g_str_result_tl { \tl_to_other_str:n {#4} }
      \tl_gset:Nx \g_str_result_tl
        {
          \exp_after:wN \str_aux_escape_loop:N \g_str_result_tl
          \q_recursion_tail \q_recursion_stop
        }
    \group_end:
  }
\cs_new_nopar:Npn \str_aux_escape_loop:N #1
  {
    \cs_if_exist_use:cF { str_aux_escape_\token_to_str:N #1:w }
      { \str_aux_escape_unescaped:N #1 }
    \str_aux_escape_loop:N
  }
\cs_new_nopar:cpn { str_aux_escape_ \c_backslash_str :w }
    \str_aux_escape_loop:N #1
  {
    \cs_if_exist_use:cF { str_aux_escape_/\token_to_str:N #1:w }
      { \str_aux_escape_escaped:N #1 }
    \str_aux_escape_loop:N
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[aux]+\str_aux_escape_\q_recursion_tail:w+
% \begin{macro}[aux]+\str_aux_escape_/\q_recursion_tail:w+
% \begin{macro}[aux]+\str_aux_escape_ :w+
% \begin{macro}[aux]
%   {
%     \str_aux_escape_/a:w, \str_aux_escape_/e:w, \str_aux_escape_/f:w,
%     \str_aux_escape_/n:w, \str_aux_escape_/r:w, \str_aux_escape_/t:w
%   }
%   The loop is ended upon seeing \cs{q_recursion_tail}.
%   Spaces are ignored, and |\a|, |\e|, |\f|, |\n|, |\r|, |\t| take
%   their meaning here.
%    \begin{macrocode}
\cs_new_eq:cN
  { str_aux_escape_ \c_backslash_str q_recursion_tail :w }
  \use_none_delimit_by_q_recursion_stop:w
\cs_new_eq:cN
  { str_aux_escape_ / \c_backslash_str q_recursion_tail :w }
  \use_none_delimit_by_q_recursion_stop:w
\cs_new_nopar:cpn { str_aux_escape_~:w } { }
\cs_new_nopar:cpx { str_aux_escape_/a:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^G }
\cs_new_nopar:cpx { str_aux_escape_/t:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^I }
\cs_new_nopar:cpx { str_aux_escape_/n:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^J }
\cs_new_nopar:cpx { str_aux_escape_/f:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^L }
\cs_new_nopar:cpx { str_aux_escape_/r:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^M }
\cs_new_nopar:cpx { str_aux_escape_/e:w }
  { \exp_not:N \str_aux_escape_raw:N \iow_char:N \^^[ }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[aux]{\str_aux_escape_/x:w}
% \begin{macro}[aux]{\str_aux_escape_x_test:N}
% \begin{macro}[aux]{\str_aux_escape_x_unbraced_i:N}
% \begin{macro}[aux]{\str_aux_escape_x_unbraced_ii:N}
% \begin{macro}[aux]{\str_aux_escape_x_braced_loop:N}
% \begin{macro}[aux]{\str_aux_escape_x_braced_end:N}
% \begin{macro}[aux]{\str_aux_escape_x_end:}
%   When |\x| is encountered, interrupt the assignment,
%   and distinguish the cases of a braced or unbraced syntax.
%   In the braced case, collect arbitrarily many hexadecimal digits,
%   building the number in \cs{l_str_char_int} (this is a side effect
%   of \cs{str_aux_hexadecimal_test:NTF}), and check that
%   the run of digits was interrupted by a closing brace.
%   In the unbraced case, collect up to two hexadecimal digits,
%   possibly less, building the character number in \cs{l_str_char_int}.
%   In both cases, once all digits have been collected, use
%   the \TeX{} primitive \tn{lowercase} to produce that character,
%   and use a \cs{if_false:} trick to restart the assignment.
%    \begin{macrocode}
\cs_new_nopar:cpn { str_aux_escape_/x:w } \str_aux_escape_loop:N
  {
    \if_false: { \fi: }
    \int_zero:N \l_str_char_int
    \str_aux_escape_x_test:N
  }
\cs_new_protected_nopar:Npx \str_aux_escape_x_test:N #1
  {
    \exp_not:N \token_if_eq_charcode:NNTF \c_space_token #1
      { \exp_not:N \str_aux_escape_x_test:N }
      {
        \exp_not:N \token_if_eq_charcode:NNTF \c_lbrace_str #1
          { \exp_not:N \str_aux_escape_x_braced_loop:N }
          { \exp_not:N \str_aux_escape_x_unbraced_i:N #1 }
      }
  }
\cs_new_protected_nopar:Npn \str_aux_escape_x_unbraced_i:N #1
  {
    \str_aux_hexadecimal_test:NTF #1
      { \str_aux_escape_x_unbraced_ii:N }
      { \str_aux_escape_x_end: #1 }
  }
\cs_new_protected_nopar:Npn \str_aux_escape_x_unbraced_ii:N #1
  {
    \token_if_eq_charcode:NNTF \c_space_token #1
      { \str_aux_escape_x_unbraced_ii:N }
      {
        \str_aux_hexadecimal_test:NTF #1
          { \str_aux_escape_x_end: }
          { \str_aux_escape_x_end: #1 }
      }
  }
\cs_new_protected_nopar:Npn \str_aux_escape_x_braced_loop:N #1
  {
    \token_if_eq_charcode:NNTF \c_space_token #1
      { \str_aux_escape_x_braced_loop:N }
      {
        \str_aux_hexadecimal_test:NTF #1
          { \str_aux_escape_x_braced_loop:N }
          { \str_aux_escape_x_braced_end:N #1 }
      }
  }
\cs_new_protected_nopar:Npx \str_aux_escape_x_braced_end:N #1
  {
    \exp_not:N \token_if_eq_charcode:NNTF \c_rbrace_str #1
      { \exp_not:N \str_aux_escape_x_end: }
      {
        \msg_error:nn { str } { x-missing-brace }
        \exp_not:N \str_aux_escape_x_end: #1
      }
  }
\group_begin:
  \char_set_catcode_other:N \^^@
  \cs_new_protected_nopar:Npn \str_aux_escape_x_end:
    {
      \group_begin:
      \char_set_lccode:nn { \c_zero } { \l_str_char_int }
      \tl_to_lowercase:n
        {
          \group_end:
          \tl_gput_right:Nx \g_str_result_tl
            { \if_false: } \fi:
            \str_aux_escape_raw:N ^^@
            \str_aux_escape_loop:N
        }
    }
\group_end:
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{Escape and unescape strings for PDF use}
%
% \begin{macro}{\str_aux_convert_store:}
% \begin{macro}{\str_aux_convert_store:NNn}
%    \begin{macrocode}
\group_begin:
  \char_set_catcode_other:n { `\^^@ }
  \cs_new_protected_nopar:Npn \str_aux_convert_store:
    {
      \char_set_lccode:nn { \c_zero } { \l_str_char_int }
      \tl_to_lowercase:n { \tl_gput_right:Nx \g_str_result_tl {^^@} }
    }
  \cs_new_protected_nopar:Npn \str_aux_convert_store:NNn #1#2#3
    {
      \char_set_lccode:nn { \c_zero } {#3}
      \tl_to_lowercase:n { #1 #2 {^^@} }
    }
\group_end:
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\str_aux_byte_to_hexadecimal:N}
% \begin{macro}{\str_aux_byte_to_octal:N}
%    \begin{macrocode}
\cs_new_nopar:Npn \str_aux_byte_to_hexadecimal:N #1
  {
    \int_compare:nNnTF {`#1} < { 256 }
      {
        \int_to_letter:n { \int_div_truncate:nn {`#1} \c_sixteen }
        \int_to_letter:n { \int_mod:nn {`#1} \c_sixteen }
      }
      { \msg_expandable_error:n { Invalid~byte~`#1'. } }
  }
\cs_new_nopar:Npn \str_aux_byte_to_octal:N #1
  {
    \int_compare:nNnTF {`#1} < { 64 }
      {
        0
        \int_to_letter:n { \int_div_truncate:nn {`#1} \c_eight }
        \int_to_letter:n { \int_mod:nn {`#1} \c_eight }
      }
      {
        \int_compare:nNnTF {`#1} < { 256 }
          { \int_to_octal:n {`#1} }
          { \msg_expandable_error:n { Invalid~byte~`#1'. } }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\str_bytes_escape_hexadecimal:NN}
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_bytes_escape_hexadecimal:NN #1#2
  {
    \str_set:Nx #1
      { \str_map_tokens:Nn #2 \str_aux_byte_to_hexadecimal:N }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\str_bytes_escape_name:NN}
%    \begin{macrocode}
\tl_const:Nx \c_str_bytes_escape_name_str
  { \c_hash_str \c_percent_str \c_lbrace_str \c_rbrace_str ()/<>[] }
\cs_new_protected_nopar:Npn \str_bytes_escape_name:NN #1#2
  {
    \str_set:Nx #1
      { \str_map_tokens:Nn #2 \str_bytes_escape_name_aux:N }
  }
\cs_new_nopar:Npn \str_bytes_escape_name_aux:N #1
  {
    \int_compare:nNnTF {`#1} < { "21 }
      { \c_hash_str \str_aux_byte_to_hexadecimal:N #1 }
      {
        \int_compare:nNnTF {`#1} > { "7E }
          { \c_hash_str \str_aux_byte_to_hexadecimal:N #1 }
          {
            \str_if_contains_char:NNTF \c_str_bytes_escape_name_str #1
              { \c_hash_str \str_aux_byte_to_hexadecimal:N #1 }
              {#1}
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\str_bytes_escape_string:NN}
%   Any character below (and including) space, and any character
%   above (and including) \texttt{del}, are converted to octal.
%   One backslash is added before each parenthesis and backslash.
%    \begin{macrocode}
\tl_const:Nx \c_str_bytes_escape_string_str { \c_backslash_str ( ) }
\cs_new_protected_nopar:Npn \str_bytes_escape_string:NN #1#2
  {
    \str_set:Nx #1
      { \str_map_tokens:Nn #2 \str_bytes_escape_string_aux:N }
  }
\cs_new_nopar:Npn \str_bytes_escape_string_aux:N #1
  {
    \int_compare:nNnTF {`#1} < { "21 }
      { \c_backslash_str \str_aux_byte_to_octal:N #1 }
      {
        \int_compare:nNnTF {`#1} > { "7E }
          { \c_backslash_str \str_aux_byte_to_octal:N #1 }
          {
            \str_if_contains_char:NNT \c_str_bytes_escape_string_str #1
              { \c_backslash_str }
            #1
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\str_bytes_unescape_hexadecimal:NN}
% \begin{macro}[aux]{\str_bytes_unescape_hexadecimal_aux:N}
% \begin{macro}[aux]{\str_bytes_unescape_hexadecimal_aux_ii:N}
%   Takes chars two by two, and interprets each pair as a hexadecimal code
%   for a character. Any non-hexadecimal-digit is ignored. An odd-length
%   string gets a |0| appended to it (this is equivalent to appending a |0|
%   in all cases, and dropping it if it is alone).
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_bytes_unescape_hexadecimal:NN #1#2
  {
    \group_begin:
      \tl_gclear:N \g_str_result_tl
      \int_zero:N \l_str_char_int
      \exp_last_unbraced:Nf \str_bytes_unescape_hexadecimal_aux:N
        { \tl_to_other_str:N #2 } 0
      \q_recursion_tail \q_recursion_stop
    \group_end:
    \tl_set_eq:NN #1 \g_str_result_tl
  }
\cs_new_protected_nopar:Npn \str_bytes_unescape_hexadecimal_aux:N #1
  {
    \quark_if_recursion_tail_stop:N #1
    \str_aux_hexadecimal_test:NTF #1
      { \str_bytes_unescape_hexadecimal_aux_ii:N }
      { \str_bytes_unescape_hexadecimal_aux:N }
  }
\cs_new_protected_nopar:Npn \str_bytes_unescape_hexadecimal_aux_ii:N #1
  {
    \quark_if_recursion_tail_stop:N #1
    \str_aux_hexadecimal_test:NTF #1
      {
        \str_aux_convert_store:
        \int_zero:N \l_str_char_int
        \str_bytes_unescape_hexadecimal_aux:N
      }
      { \str_bytes_unescape_hexadecimal_aux_ii:N }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\str_bytes_unescape_name:NN}
% \begin{macro}[aux]{\str_bytes_unescape_name_aux:wN}
% \begin{macro}[aux]{\str_bytes_unescape_name_aux_ii:N}
%   This changes all occurrences of |#| followed by two upper- or lowercase
%   hexadecimal digits by the corresponding unescaped character.
%    \begin{macrocode}
\group_begin:
  \char_set_lccode:nn {`\*} {`\#}
  \tl_to_lowercase:n
    {
      \group_end:
      \cs_new_protected_nopar:Npn \str_bytes_unescape_name:NN #1#2
        {
          \group_begin:
            \tl_gclear:N \g_str_result_tl
            \int_zero:N \l_str_char_int
            \exp_last_unbraced:Nf \str_bytes_unescape_name_aux:wN
              { \tl_to_other_str:N #2 }
            * \q_recursion_tail \q_recursion_stop
          \group_end:
          \tl_set_eq:NN #1 \g_str_result_tl
        }
      \cs_new_protected_nopar:Npn \str_bytes_unescape_name_aux:wN #1 * #2
        {
          \tl_gput_right:Nx \g_str_result_tl {#1}
          \quark_if_recursion_tail_stop:N #2
          \str_aux_hexadecimal_test:NTF #2
            { \str_bytes_unescape_name_aux_ii:NN #2 }
            {
              \tl_gput_right:Nx \g_str_result_tl { \c_hash_str }
              \str_bytes_unescape_name_aux:wN #2
            }
        }
    }
\cs_new_protected_nopar:Npn \str_bytes_unescape_name_aux_ii:NN #1#2
  {
    \str_aux_hexadecimal_test:NTF #2
      {
        \str_aux_convert_store:
        \int_zero:N \l_str_char_int
        \str_bytes_unescape_name_aux:wN
      }
      {
        \tl_gput_right:Nx \g_str_result_tl { \c_hash_str #1 }
        \int_zero:N \l_str_char_int
        \str_bytes_unescape_name_aux:wN #2
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\str_bytes_unescape_string:NN}
%   Here, we need to detect backslashes, which escape characters
%   as follows.
%   \begin{itemize}
%   \item[\texttt{\string\n}] Line feed ($10$)
%   \item[\texttt{\string\r}] Carriage return ($13$)
%   \item[\texttt{\string\t}] Horizontal tab ($9$)
%   \item[\texttt{\string\b}] Backspace ($8$)
%   \item[\texttt{\string\f}] Form feed ($12$)
%   \item[\texttt{(}] Left parenthesis
%   \item[\texttt{)}] Right parenthesis
%   \item[\texttt{\string\\}] Backslash
%   \item[\texttt{\string\ddd}] Character code \texttt{ddd} (octal)
%   \end{itemize}
%   If followed by an end-of-line character, the backslash and
%   the end-of-line are ignored. If followed by anything else,
%   the backslash is ignored.
%   The PDF specification indicates that LF, CR, and CRLF should be
%   converted to LF: \emph{this is not implemented here}.
%    \begin{macrocode}
\group_begin:
  \char_set_lccode:nn {`\*} {`\\}
  \char_set_catcode_other:N \^^J
  \char_set_catcode_other:N \^^M
  \tl_to_lowercase:n
    {
      \group_end:
      \cs_new_protected_nopar:Npn \str_bytes_unescape_string:NN #1#2
        {
          \group_begin:
            \tl_gclear:N \g_str_result_tl
            \exp_last_unbraced:Nf \str_bytes_unescape_string_aux:wN
              { \tl_to_other_str:N #2 }
            * \q_recursion_tail \q_recursion_stop
          \group_end:
          \tl_set_eq:NN #1 \g_str_result_tl
        }
      \cs_new_protected_nopar:Npn \str_bytes_unescape_string_aux:wN #1 * #2
        {
          \tl_gput_right:Nx \g_str_result_tl {#1}
          \quark_if_recursion_tail_stop:N #2
          \int_zero:N \l_str_char_int
          \str_aux_octal_test:NTF #2
            { \str_bytes_unescape_string_aux_d:N }
            {
              \int_set:Nn \l_str_char_int
                {
                  \prg_case_str:xxn {#2}
                    {
                      { n } { 10 }
                      { r } { 13 }
                      { t } { 9 }
                      { b } { 8 }
                      { f } { 12 }
                      { ( } { 40 }
                      { ) } { 41 }
                      { \c_backslash_str } { 92 }
                      { ^^J } { -1 }
                      { ^^M } { -1 }
                    }
                    {`#2}
                }
              \int_compare:nNnF \l_str_char_int = \c_minus_one
                { \str_aux_convert_store: }
              \str_bytes_unescape_string_aux:wN
            }
        }
    }
\cs_new_protected_nopar:Npn \str_bytes_unescape_string_aux_d:N #1
  {
    \str_aux_octal_test:NTF #1
      { \str_bytes_unescape_string_aux_dd:N }
      {
        \str_aux_convert_store:
        \str_bytes_unescape_string_aux:wN #1
      }
  }
\cs_new_protected_nopar:Npn \str_bytes_unescape_string_aux_dd:N #1
  {
    \str_aux_octal_test:NTF #1
      {
        \str_aux_convert_store:
        \str_bytes_unescape_string_aux:wN
      }
      {
        \str_aux_convert_store:
        \str_bytes_unescape_string_aux:wN #1
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Percent encoding}
%
% \begin{macro}{\str_bytes_percent_encode:NN}
%    \begin{macrocode}
\tl_const:Nx \c_str_bytes_percent_encode_str { \tl_to_str:n { [] } }
\tl_const:Nx \c_str_bytes_percent_encode_not_str { \tl_to_str:n { "-.<> } }
\cs_new_protected_nopar:Npn \str_bytes_percent_encode:NN #1#2
  {
    \str_set:Nx #1
      { \str_map_tokens:Nn #2 \str_bytes_percent_encode_aux:N }
  }
\cs_new_nopar:Npn \str_bytes_percent_encode_aux:N #1
  {
    \int_compare:nNnTF {`#1} < { "41 }
      {
        \str_if_contains_char:NNTF \c_str_bytes_percent_encode_not_str #1
          { #1 }
          { \c_percent_str \str_aux_byte_to_hexadecimal:N #1 }
      }
      {
        \int_compare:nNnTF {`#1} > { "7E }
          { \c_percent_str \str_aux_byte_to_hexadecimal:N #1 }
          {
            \str_if_contains_char:NNTF \c_str_bytes_percent_encode_str #1
              { \c_percent_str \str_aux_byte_to_hexadecimal:N #1 }
              { #1 }
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\str_bytes_percent_decode:NN}
% \begin{macro}[aux]{\str_bytes_percent_decode_aux:wN}
% \begin{macro}[aux]{\str_bytes_percent_decode_aux_ii:NN}
%    \begin{macrocode}
\group_begin:
  \char_set_lccode:nn {`\*} {`\%}
  \tl_to_lowercase:n
    {
      \group_end:
      \cs_new_protected_nopar:Npn \str_bytes_percent_decode:NN #1#2
        {
          \group_begin:
            \tl_gclear:N \g_str_result_tl
            \exp_last_unbraced:Nf \str_bytes_percent_decode_aux:wN
              { \tl_to_other_str:N #2 }
            * \q_recursion_tail \q_recursion_stop
          \group_end:
          \tl_set_eq:NN #1 \g_str_result_tl
        }
      \cs_new_protected_nopar:Npn \str_bytes_percent_decode_aux:wN #1 * #2
        {
          \tl_gput_right:Nx \g_str_result_tl {#1}
          \quark_if_recursion_tail_stop:N #2
          \int_zero:N \l_str_char_int
          \str_aux_hexadecimal_test:NTF #2
            { \str_bytes_percent_decode_aux_ii:NN #2 }
            {
              \tl_gput_right:Nx \g_str_result_tl { \c_percent_str }
              \str_bytes_percent_decode_aux:wN #2
            }
        }
    }
\cs_new_protected_nopar:Npn \str_bytes_percent_decode_aux_ii:NN #1#2
  {
    \str_aux_hexadecimal_test:NTF #2
      {
        \str_aux_convert_store:
        \str_bytes_percent_decode_aux:wN
      }
      {
        \tl_gput_right:Nx \g_str_result_tl {#1}
        \str_bytes_percent_decode_aux:wN #2
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsubsection{UTF-8 support}
%
% \begin{macro}{\str_native_from_UTF_viii:NN}
% \begin{macro}[aux]
%   {
%     \str_native_from_UTF_viii_aux_i:N,
%     \str_native_from_UTF_viii_aux_ii:nN,
%     \str_native_from_UTF_viii_aux_iii:N,
%     \str_native_from_UTF_viii_aux_iv:,
%     \str_native_from_UTF_viii_aux_v:
%   }
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_native_from_UTF_viii:NN #1#2
  {
    \group_begin:
      \tl_gclear:N \g_str_result_tl
      \exp_last_unbraced:Nf \str_native_from_UTF_viii_aux_i:N
        { \tl_to_other_str:N #2 }
      \q_recursion_tail \q_recursion_stop
    \group_end:
    \tl_set_eq:NN #1 \g_str_result_tl
  }
\cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_i:N #1
  {
    \quark_if_recursion_tail_stop:N #1
    \int_set:Nn \l_str_char_int {`#1}
    \str_native_from_UTF_viii_aux_ii:nN { 128 } \c_one
    \str_native_from_UTF_viii_aux_ii:nN { 64 }  \c_zero
    \str_native_from_UTF_viii_aux_ii:nN { 32 }  \c_two
    \str_native_from_UTF_viii_aux_ii:nN { 16 }  \c_three
    \str_native_from_UTF_viii_aux_ii:nN { 8 }   \c_four
    \msg_error:nnx { str } { utf8-invalid-byte } {#1}
    \use_i:nnn \str_native_from_UTF_viii_aux_i:N
    \q_stop
    \str_native_from_UTF_viii_aux_iii:N
  }
\cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_ii:nN #1#2
  {
    \int_compare:nNnTF \l_str_char_int < {#1}
      {
        \int_set_eq:NN \l_str_bytes_int #2
        \use_none_delimit_by_q_stop:w
      }
      { \int_sub:Nn \l_str_char_int {#1} }
  }
\cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_iii:N #1
  {
    \int_compare:nNnTF \l_str_bytes_int < \c_two
      { \str_native_from_UTF_viii_aux_iv: #1 }
      {
        \if_meaning:w \q_recursion_tail #1
          \msg_error:nn { str } { utf8-premature-end }
          \exp_after:wN \use_none_delimit_by_q_recursion_stop:w
        \fi:
        \quark_if_recursion_tail_stop:N #1
        \tex_multiply:D \l_str_char_int by 64 \scan_stop:
        \int_decr:N \l_str_bytes_int
        \int_compare:nNnTF {`#1} < { 128 }
          { \use_ii:nn }
          { \int_compare:nNnTF {`#1} < { 192 } }
          {
            \int_add:Nn \l_str_char_int { `#1 - 128 }
            \str_native_from_UTF_viii_aux_iii:N
          }
          {
            \msg_error:nnx { str } { utf8-missing-byte } {#1}
            \str_native_from_UTF_viii_aux_i:N #1
          }
      }
  }
\cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_iv:
  {
    \int_compare:nNnTF \l_str_bytes_int = \c_zero
      {
        \msg_error:nnx { str } { utf8-extra-byte }
          { \int_eval:n { \l_str_char_int + 128 } }
      }
      { \str_native_from_UTF_viii_aux_v: }
    \str_native_from_UTF_viii_aux_i:N
  }
\pdftex_if_engine:TF
  {
    \cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_v:
      {
        \int_compare:nNnTF { \l_str_char_int } < { 256 }
          { \str_aux_convert_store: }
          {
            \msg_error:nnx { str } { utf8-pdftex-overflow }
              { \int_use:N \l_str_char_int }
          }
      }
  }
  {
    \cs_new_protected_nopar:Npn \str_native_from_UTF_viii_aux_v:
      { \str_aux_convert_store: }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\str_UTF_viii_from_native:NN}
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \str_UTF_viii_from_native:NN #1#2
  {
    \group_begin:
      \tl_gclear:N \g_str_result_tl
      \str_map_tokens:Nn #2 \str_UTF_viii_from_native_aux_i:N
    \group_end:
    \tl_set_eq:NN #1 \g_str_result_tl
  }
\cs_new_protected_nopar:Npn \str_UTF_viii_from_native_aux_i:N #1
  {
    \int_set:Nn \l_str_char_int {`#1}
    \int_compare:nNnTF \l_str_char_int < { 128 }
      { \tl_gput_right:Nx \g_str_result_tl {#1} }
      {
        \tl_gclear:N \g_str_tmpa_tl
        \int_set:Nn \l_str_bytes_int { 64 }
        \str_UTF_viii_from_native_aux_ii:n { 32 }
        \str_UTF_viii_from_native_aux_ii:n { 16 }
        \str_UTF_viii_from_native_aux_ii:n { 8 }
        \ERROR % somehow the unicode char was > "1FFFFF > "10FFFF
        \tl_gclear:N \g_str_tmpa_tl
        \use_none:n \q_stop
        \int_add:Nn \l_str_char_int { 2 * \l_str_bytes_int }
        \str_aux_convert_store:
        \tl_gput_right:Nx \g_str_result_tl { \g_str_tmpa_tl }
      }
  }
\cs_new_protected_nopar:Npn \str_UTF_viii_from_native_aux_ii:n #1
  {
    \str_aux_convert_store:NNn
      \tl_gput_left:Nx \g_str_tmpa_tl
      { 128 + \int_mod:nn { \l_str_char_int } { 64 } }
    \tex_divide:D \l_str_char_int by 64 \scan_stop:
    \int_add:Nn \l_str_bytes_int {#1}
    \int_compare:nNnT \l_str_char_int < {#1}
      { \use_none_delimit_by_q_stop:w }
  }
%    \end{macrocode}
% \end{macro}
% 
% \subsection{Messages}
% 
%    \begin{macrocode}
\msg_new:nnnn { str } { x-missing-brace }
  { Missing~closing~brace~in~ \token_to_str:N \x ~byte~sequence. }
  {
    You~wrote~something~like~
    `\iow_char:N\\x\{ \int_to_hexadecimal:n { \l_str_char_int }'.~
    The~closing~brace~is~missing.
  }
\msg_new:nnn { str } { utf8-invalid-byte }
  {
    \int_compare:nNnTF {`#1} < { 256 }
      { Byte~number~ \int_eval:n {`#1} ~invalid~in~utf-8~encoding. }
      { The~character~number~ \int_eval:n {`#1} ~is~not~a~byte. }
  }
\msg_new:nnn { str } { utf8-missing-byte }
  { The~byte~number~ \int_eval:n {`#1} ~is~not~a~valid~continuation~byte. }
\msg_new:nnn { str } { utf8-extra-byte }
  { The~byte~number~ \int_eval:n {`#1} ~is~only~valid~as~a~continuation~byte. }
\msg_new:nnnn { str } { utf8-premature-end }
  { Incomplete~last~UTF8~character. }
  {
    The~sequence~of~byte~that~to~be~converted~to~UTF8~
    ended~before~the~last~character~was~complete.~Perhaps~
    it~was~mistakenly~truncated?
  }
\msg_new:nnn { str } { utf8-pdftex-overflow }
  { The~character~number~#1~is~too~big~for~pdfTeX. }
%    \end{macrocode}
%
% \subsection{Deprecated string functions}
%
% \begin{macro}{\str_length_skip_spaces:N, \str_length_skip_spaces:n}
%   The naming scheme is a little bit more consistent
%   with \enquote{ignore_spaces} instead of \enquote{skip_spaces}.
%    \begin{macrocode}
\cs_set:Npn \str_length_skip_spaces:N
  { \exp_args:No \str_length_skip_spaces:n }
\cs_set_eq:NN \str_length_skip_spaces:n \str_length_ignore_spaces:n
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex