summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3seq.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3seq.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3seq.dtx1391
1 files changed, 0 insertions, 1391 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3seq.dtx b/Master/texmf-dist/source/latex/expl3/l3seq.dtx
deleted file mode 100644
index 6e5c536616d..00000000000
--- a/Master/texmf-dist/source/latex/expl3/l3seq.dtx
+++ /dev/null
@@ -1,1391 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: l3seq.dtx Copyright (C) 1990-2011 by
-%% The LaTeX3 Project <latex-team@latex-project.org>
-%%
-%% 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 "expl3 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{l3names}
-\GetIdInfo$Id: l3seq.dtx 2245 2011-04-21 19:45:31Z joseph $
- {The LaTeX3 kernel: sequences and stacks}
-%</driver|package>
-%<*driver>
-\documentclass[full]{l3doc}
-\usepackage{csquotes}
-\begin{document}
- \DocInput{\jobname.dtx}
-\end{document}
-%</driver>
-% \fi
-%
-% \GetFileInfo{\jobname.sty}
-%
-% \title{^^A
-% \fileinfo
-% \thanks{This file describes v\fileversion, last revised \filedate.}^^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 \filedate}
-%
-% \maketitle
-%
-% \begin{documentation}
-%
-% \LaTeX3 implements a \enquote{sequence} data type, which contain
-% an ordered list of entries which may contain any \meta{balanced text}.
-% It is possible to map functions to sequences such that the function
-% is applied to every item in the sequence.
-%
-% Sequences are also used to implement stack functions in \LaTeX3. This
-% is achieved using a number of dedicated stack functions.
-%
-% \section{Creating and initialising sequences}
-%
-% \begin{function}{\seq_new:N, \seq_new:c}
-% \begin{syntax}
-% \cs{seq_new:N} \meta{sequence}
-% \end{syntax}
-% Creates a new \meta{sequence} or raises an error if the name is
-% already taken. The declaration is global. The \meta{sequence} will
-% initially contain no items.
-% \end{function}
-%
-% \begin{function}{\seq_clear:N, \seq_clear:c}
-% \begin{syntax}
-% \cs{seq_clear:N} \meta{sequence}
-% \end{syntax}
-% Clears all items from the \meta{sequence} within the scope of
-% the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}{\seq_gclear:N, \seq_gclear:c}
-% \begin{syntax}
-% \cs{seq_gclear:N} \meta{sequence}
-% \end{syntax}
-% Clears all entries from the \meta{sequence} globally.
-% \end{function}
-%
-% \begin{function}{\seq_clear_new:N, \seq_clear_new:c}
-% \begin{syntax}
-% \cs{seq_clear_new:N} \meta{sequence}
-% \end{syntax}
-% If the \meta{sequence} already exists, clears it within the scope
-% of the current \TeX{} group. If the \meta{sequence} is not defined,
-% it will be created (using \cs{seq_new:N}). Thus the sequence is
-% guaranteed to be available and clear within the current \TeX{}
-% group. The \meta{sequence} will exist globally, but the content
-% outside of the current \TeX{} group is not specified.
-% \end{function}
-%
-% \begin{function}{\seq_gclear_new:N, \seq_gclear_new:c}
-% \begin{syntax}
-% \cs{seq_gclear_new:N} \meta{sequence}
-% \end{syntax}
-% If the \meta{sequence} already exists, clears it globally. If the
-% \meta{sequence} is not defined, it will be created (using
-% \cs{seq_new:N}). Thus the sequence is guaranteed to be available
-% and globally clear.
-% \end{function}
-%
-% \begin{function}
-% {\seq_set_eq:NN, \seq_set_eq:cN, \seq_set_eq:Nc, \seq_set_eq:cc}
-% \begin{syntax}
-% \cs{seq_set_eq:NN} \meta{sequence1} \meta{sequence2}
-% \end{syntax}
-% Sets the content of \meta{sequence1} equal to that of
-% \meta{sequence2}. This assignment is restricted to the current
-% \TeX{} group level.
-% \end{function}
-%
-% \begin{function}
-% {\seq_gset_eq:NN, \seq_gset_eq:cN, \seq_gset_eq:Nc, \seq_gset_eq:cc}
-% \begin{syntax}
-% \cs{seq_gset_eq:NN} \meta{sequence1} \meta{sequence2}
-% \end{syntax}
-% Sets the content of \meta{sequence1} equal to that of
-% \meta{sequence2}. This assignment is global and so is not
-% limited by the current \TeX{} group level.
-% \end{function}
-%
-% \begin{function}{\seq_concat:NNN, \seq_concat:ccc}
-% \begin{syntax}
-% \cs{seq_concat:NNN} \meta{sequence1} \meta{sequence2} \meta{sequence3}
-% \end{syntax}
-% Concatenates the content of \meta{sequence2} and \meta{sequence3}
-% together and saves the result in \meta{sequence1}. The items in
-% \meta{sequence2} will be placed at the left side of the new sequence.
-% This operation is local to the current \TeX{} group and will
-% remove any existing content in \meta{sequence1}.
-% \end{function}
-%
-% \begin{function}{\seq_gconcat:NNN, \seq_gconcat:ccc}
-% \begin{syntax}
-% \cs{seq_gconcat:NNN} \meta{sequence1} \meta{sequence2} \meta{sequence3}
-% \end{syntax}
-% Concatenates the content of \meta{sequence2} and \meta{sequence3}
-% together and saves the result in \meta{sequence1}. The items in
-% \meta{sequence2} will be placed at the left side of the new sequence.
-% This operation is global and will remove any existing content in
-% \meta{sequence1}.
-% \end{function}
-%
-% \section{Appending data to sequences}
-%
-% \begin{function}{
-% \seq_put_left:Nn, \seq_put_left:NV, \seq_put_left:Nv,
-% \seq_put_left:No, \seq_put_left:Nx,
-% \seq_put_left:cn, \seq_put_left:cV, \seq_put_left:cv,
-% \seq_put_left:co, \seq_put_left:cx
-% }
-% \begin{syntax}
-% \cs{seq_put_left:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Appends the \meta{item} to the left of the \meta{sequence}.
-% The assignment is restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}{
-% \seq_gput_left:Nn, \seq_gput_left:NV, \seq_gput_left:Nv,
-% \seq_gput_left:No, \seq_gput_left:Nx,
-% \seq_gput_left:cn, \seq_gput_left:cV, \seq_gput_left:cv,
-% \seq_gput_left:co, \seq_gput_left:cx
-% }
-% \begin{syntax}
-% \cs{seq_gput_left:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Appends the \meta{item} to the left of the \meta{sequence}.
-% The assignment is global.
-% \end{function}
-%
-% \begin{function}{
-% \seq_put_right:Nn, \seq_put_right:NV, \seq_put_right:Nv,
-% \seq_put_right:No, \seq_put_right:Nx,
-% \seq_put_right:cn, \seq_put_right:cV, \seq_put_right:cv,
-% \seq_put_right:co, \seq_put_right:cx
-% }
-% \begin{syntax}
-% \cs{seq_put_right:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Appends the \meta{item} to the right of the \meta{sequence}.
-% The assignment is restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}{
-% \seq_gput_right:Nn, \seq_gput_right:NV, \seq_gput_right:Nv,
-% \seq_gput_right:No, \seq_gput_right:Nx,
-% \seq_gput_right:cn, \seq_gput_right:cV, \seq_gput_right:cv,
-% \seq_gput_right:co, \seq_gput_right:cx
-% }
-% \begin{syntax}
-% \cs{seq_gput_right:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Appends the \meta{item} to the right of the \meta{sequence}.
-% The assignment is global.
-% \end{function}
-%
-% \section{Recovering items from sequences}
-%
-% Items can be recovered from either the left or the right of sequences.
-% For implementation reasons, the actions at the left of the sequence are
-% faster than those acting on the right. These functions all assign the
-% recovered material locally, \emph{i.e.}~setting the
-% \meta{token list variable} used with \cs{tl_set:Nn} and \emph{never}
-% \cs{tl_gset:Nn}.
-%
-% \begin{function}{\seq_get_left:NN, \seq_get_left:cN}
-% \begin{syntax}
-% \cs{seq_get_left:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Stores the left-most item from a \meta{sequence} in the
-% \meta{token list variable} without removing it from the
-% \meta{sequence}. The \meta{token list variable} is assigned locally.
-% If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_get_right:NN, \seq_get_right:cN}
-% \begin{syntax}
-% \cs{seq_get_right:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Stores the right-most item from a \meta{sequence} in the
-% \meta{token list variable} without removing it from the
-% \meta{sequence}. The \meta{token list variable} is assigned locally.
-% If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_pop_left:NN, \seq_pop_left:cN}
-% \begin{syntax}
-% \cs{seq_pop_left:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the left-most item from a \meta{sequence} into the
-% \meta{token list variable}, \emph{i.e}.~removes the item from the
-% sequence and stores it in the \meta{token list variable}.
-% Both of the variables are assigned locally. If \meta{sequence} is
-% empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_gpop_left:NN, \seq_gpop_left:cN}
-% \begin{syntax}
-% \cs{seq_gpop_left:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the left-most item from a \meta{sequence} into the
-% \meta{token list variable}, \emph{i.e}.~removes the item from the
-% sequence and stores it in the \meta{token list variable}.
-% The \meta{sequence} is modified globally, while the assignment of
-% the \meta{token list variable} is local.
-% If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_pop_right:NN, \seq_pop_right:cN}
-% \begin{syntax}
-% \cs{seq_pop_right:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the right-most item from a \meta{sequence} into the
-% \meta{token list variable}, \emph{i.e}.~removes the item from the
-% sequence and storesitin in the \meta{token list variable}.
-% Both of the variables are assigned locally. If \meta{sequence} is
-% empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_gpop_right:NN, \seq_gpop_right:cN}
-% \begin{syntax}
-% \cs{seq_gpop_right:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the right-most item from a \meta{sequence} into the
-% \meta{token list variable}, \emph{i.e}.~removes the item from the
-% sequence and stores it in the \meta{token list variable}.
-% The \meta{sequence} is modified globally, while the assignment of
-% the \meta{token list variable} is local.
-% If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \section{Modifying sequences}
-%
-% While sequences are normally used as ordered lists, it may be
-% necessary to modify the content. The functions here may be used
-% to update sequences, while retaining the order of the unaffected
-% entries.
-%
-% \begin{function}{\seq_remove_duplicates:N, \seq_remove_duplicates:c}
-% \begin{syntax}
-% \cs{seq_remove_duplicates:N} \meta{sequence}
-% \end{syntax}
-% Removes duplicate items from the \meta{sequence}, leaving
-% left most copy of each item in the \meta{sequence}. The \meta{item}
-% comparison takes place on a token basis, as for \cs{tl_if_eq:nn(TF)}.
-% The removal is local to the current \TeX{} group.
-% \begin{texnote}
-% This function iterates through every item in the \meta{sequence} and
-% does a comparison with the \meta{items} already checked. It is therefore
-% relatively slow with large sequences.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}{\seq_gremove_duplicates:N, \seq_gremove_duplicates:c}
-% \begin{syntax}
-% \cs{seq_gremove_duplicates:N} \meta{sequence}
-% \end{syntax}
-% Removes duplicate items from the \meta{sequence}, leaving
-% left most copy of each item in the \meta{sequence}. The \meta{item}
-% comparison takes place on a token basis, as for \cs{tl_if_eq:nn(TF)}.
-% The removal is applied globally.
-% \begin{texnote}
-% This function iterates through every item in the \meta{sequence} and
-% does a comparison with the \meta{items} already checked. It is therefore
-% relatively slow with large sequences.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}{\seq_remove_all:Nn, \seq_remove_all:cn}
-% \begin{syntax}
-% \cs{seq_remove_all:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Removes every occurrence of \meta{item} from the \meta{sequence}.
-% The \meta{item} comparison takes place on a token basis, as for
-% \cs{tl_if_eq:nn(TF)}. The removal is local to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}{\seq_gremove_all:Nn, \seq_gremove_all:cn}
-% \begin{syntax}
-% \cs{seq_gremove_all:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Removes each occurrence of \meta{item} from the \meta{sequence}.
-% The \meta{item} comparison takes place on a token basis, as for
-% \cs{tl_if_eq:nn(TF)}. The removal is applied globally.
-% \end{function}
-%
-% \subsection{Sequence conditionals}
-%
-% \begin{function}[EXP,pTF]{\seq_if_empty:N, \seq_if_empty:c}
-% \begin{syntax}
-% \cs{seq_if_empty_p:N} \meta{sequence}
-% \cs{seq_if_empty:NTF} \meta{sequence} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the \meta{sequence} is empty (containing no items). The
-% branching versions then leave either \meta{true code} or
-% \meta{false code} in the input stream, as appropriate to the truth of
-% the test and the variant of the function chosen. The logical truth of
-% the test is left in the input stream by the predicate version.
-% \end{function}
-%
-% \begin{function}[TF]{
-% \seq_if_in:Nn, \seq_if_in:NV, \seq_if_in:Nv, \seq_if_in:No, \seq_if_in:Nx,
-% \seq_if_in:cn, \seq_if_in:cV, \seq_if_in:cv, \seq_if_in:co, \seq_if_in:cx
-% }
-% \begin{syntax}
-% \cs{seq_if_in:NnTF} \meta{sequence} \Arg{item}
-% ~~\Arg{true code} \Arg{false code}
-% \end{syntax}
-% Tests if the \meta{item} is present in the \meta{sequence}.
-% Either the \meta{true code} or \meta{false code} is left in the input
-% stream, as appropriate to the truth of the test and the variant of the
-% function
-% chosen.
-% \end{function}
-%
-% \section{Mapping to sequences}
-%
-% \begin{function}[EXP]{\seq_map_function:NN, \seq_map_function:cN}
-% \begin{syntax}
-% \cs{seq_map_function:NN} \meta{sequence} \meta{function}
-% \end{syntax}
-% Applies \meta{function} to every \meta{item} stored in the
-% \meta{sequence}. The \meta{function} will receive one argument for
-% each iteration. The \meta{items} are returned from left to right.
-% The function \cs{seq_map_inline:Nn} is in general more efficient
-% than \cs{seq_map_function:NN}.
-% One mapping may be nested inside another.
-% \end{function}
-%
-% \begin{function}{\seq_map_inline:Nn, \seq_map_inline:cn}
-% \begin{syntax}
-% \cs{seq_map_inline:Nn} \meta{sequence} \Arg{inline function}
-% \end{syntax}
-% Applies \meta{inline function} to every \meta{item} stored
-% within the \meta{sequence}. The \meta{inline function} should
-% consist of code which will receive the \meta{item} as |#1|.
-% One in line mapping can be nested inside another. The \meta{items}
-% are returned from left to right.
-% \end{function}
-%
-% \begin{function}{
-% \seq_map_variable:NNn, \seq_map_variable:Ncn,
-% \seq_map_variable:cNn, \seq_map_variable:ccn
-% }
-% \begin{syntax}
-% \cs{seq_map_variable:Nn} \meta{sequence}
-% ~~\meta{tl~var.} \Arg{function using tl~var.}
-% \end{syntax}
-% Stores each entry in the \meta{sequence} in turn in the
-% \meta{tl~var.}\ and applies the \meta{function using tl~var.}
-% The \meta{function} will usually consist of code making use of
-% the \meta{tl~var.}, but this is not enforced. One variable
-% mapping can be nested inside another. The \meta{items}
-% are returned from left to right. One variable mapping may be
-% nested inside another.
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_map_break:}
-% \begin{syntax}
-% \cs{seq_map_break:}
-% \end{syntax}
-% Used to terminate a \cs{seq_map_\ldots} function before all
-% entries in the \meta{sequence} have been processed. This will
-% normally take place within a conditional statement, for example
-% \begin{verbatim}
-% \seq_map_inline:Nn \l_my_seq
-% {
-% \str_if_eq:nnTF { #1 } { bingo }
-% { \seq_map_break: }
-% {
-% % Do something useful
-% }
-% }
-% \end{verbatim}
-% Use outside of a \cs{seq_map_\ldots} scenario will lead low
-% level \TeX{} errors.
-% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{seq_break_point:n} before further items are taken
-% from the input stream. This will depend on the design of the mapping
-% function.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_map_break:n}
-% \begin{syntax}
-% \cs{seq_map_break:n} \Arg{tokens}
-% \end{syntax}
-% Used to terminate a \cs{seq_map_\ldots} function before all
-% entries in the \meta{sequence} have been processed, inserting
-% the \meta{tokens} after the mapping has ended. This will
-% normally take place within a conditional statement, for example
-% \begin{verbatim}
-% \seq_map_inline:Nn \l_my_seq
-% {
-% \str_if_eq:nnTF { #1 } { bingo }
-% { \seq_map_break:n { <tokens> } }
-% {
-% % Do something useful
-% }
-% }
-% \end{verbatim}
-% Use outside of a \cs{seq_map_\ldots} scenario will lead low
-% level \TeX{} errors.
-% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{seq_break_point:n} before the \meta{tokens} are
-% inserted into the input stream.
-% This will depend on the design of the mapping function.
-% \end{texnote}
-% \end{function}
-%
-% \subsection{Sequences as stacks}
-%
-% Sequences can be used as stacks, where data is pushed to and popped
-% from the top of the sequence. (The left of a sequence is the top, for
-% performance reasons.) The stack functions for sequences are not
-% intended to be mixed with the general ordered data functions detailed
-% in the previous section: a sequence should either be used as an
-% ordered data type or as a stack, but not in both ways.
-%
-% \begin{function}{\seq_get:NN, \seq_get:cN}
-% \begin{syntax}
-% \cs{seq_get:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Reads the top item from a \meta{sequence} into the
-% \meta{token list variable} without removing it from the
-% \meta{sequence}. The \meta{token list variable} is assigned locally.
-% If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_pop:NN, \seq_pop:cN}
-% \begin{syntax}
-% \cs{seq_pop:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the top item from a \meta{sequence} into the
-% \meta{token list variable}. Both of the variables are assigned
-% locally. If \meta{sequence} is empty an error will be raised.
-% \end{function}
-%
-% \begin{function}{\seq_gpop:NN, \seq_gpop:cN}
-% \begin{syntax}
-% \cs{seq_gpop:NN} \meta{sequence} \meta{token list variable}
-% \end{syntax}
-% Pops the top item from a \meta{sequence} into the
-% \meta{token list variable}. The \meta{sequence} is modified globally,
-% while the \meta{token list variable} is assigned locally. If
-% \meta{sequence} is empty the marker an error will be raised.
-% \end{function}
-%
-% \begin{function}{
-% \seq_push:Nn, \seq_push:NV, \seq_push:Nv, \seq_push:No, \seq_push:Nx,
-% \seq_push:cn, \seq_push:cV, \seq_push:cv, \seq_push:co, \seq_push:cx
-% }
-% \begin{syntax}
-% \cs{seq_push:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Adds the \Arg{item} to the top of the \meta{sequence}.
-% The assignment is restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}{
-% \seq_gpush:Nn, \seq_gpush:NV, \seq_gpush:Nv, \seq_gpush:No, \seq_gpush:Nx,
-% \seq_gpush:cn, \seq_gpush:cV, \seq_gpush:cv, \seq_gpush:co, \seq_gpush:cx
-% }
-% \begin{syntax}
-% \cs{seq_gpush:Nn} \meta{sequence} \Arg{item}
-% \end{syntax}
-% Pushes the \meta{item} onto the end of the top of the
-% \meta{sequence}. The assignment is global.
-% \end{function}
-%
-% \section{Viewing sequences}
-%
-% \begin{function}{\seq_show:N, \seq_show:c}
-% \begin{syntax}
-% \cs{seq_show:N} \meta{sequence}
-% \end{syntax}
-% Displays the entries in the \meta{sequence} in the terminal.
-% \end{function}
-%
-% \end{documentation}
-%
-% \begin{implementation}
-%
-% \section{Internal sequence functions}
-%
-% \begin{function}{\seq_if_empty_err_break:N}
-% \begin{syntax}
-% \cs{seq_if_empty_err_break:N} \meta{sequence}
-% \end{syntax}
-% Tests if the \meta{sequence} is empty, and if so issues an error
-% message before skipping over any tokens up to \cs{seq_break_point:n}.
-% This function is used to avoid more serious errors which would
-% otherwise occur if some internal functions were applied to an
-% empty \meta{sequence}.
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_item:n}
-% \begin{syntax}
-% \cs{seq_item:n} \meta{item}
-% \end{syntax}
-% The internal token used to begin each sequence entry. If expanded
-% outside of a mapping or manipulation function, an error will be
-% raised. The definition should always be set globally.
-% \end{function}
-%
-% \begin{function}{\seq_push_item_def:n, \seq_push_item_def:x}
-% \begin{syntax}
-% \cs{seq_push_item_def:n} \Arg{code}
-% \end{syntax}
-% Saves the definition of \cs{seq_item:n} and redefines it to
-% accept one parameter and expand to \meta{code}. This function
-% should always be balanced by use of \cs{seq_pop_item_def:}.
-% \end{function}
-%
-% \begin{function}{\seq_pop_item_def:}
-% \begin{syntax}
-% \cs{seq_pop_item_def:}
-% \end{syntax}
-% Restores the definition of \cs{seq_item:n} most recently saved by
-% \cs{seq_push_item_def:n}. This function should always be used in
-% a balanced pair with \cs{seq_push_item_def:n}.
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_break:}
-% \begin{syntax}
-% \cs{seq_break:}
-% \end{syntax}
-% Used to terminate sequence functions by gobbling all tokens
-% up to \cs{seq_break_point:n}. This function is a copy of
-% \cs{seq_map_break:}, but is used in situations which are
-% not mappings.
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_break:n}
-% \begin{syntax}
-% \cs{seq_break:n} \Arg{tokens}
-% \end{syntax}
-% Used to terminate sequence functions by gobbling all tokens
-% up to \cs{seq_break_point:n}, then inserting the \meta{tokens}
-% before continuing reading the input stream. This function is a copy
-% of \cs{seq_map_break:n}, but is used in situations which are
-% not mappings.
-% \end{function}
-%
-% \begin{function}[EXP]{\seq_break_point:n}
-% \begin{syntax}
-% \cs{seq_break_point:n} \meta{tokens}
-% \end{syntax}
-% Used to mark the end of a recursion or mapping: the functions
-% \cs{seq_map_break:} and \cs{seq_map_break:n} use this to break out
-% of the loop. After the loop ends the \meta{tokens} are inserted into
-% the input stream. This occurs even if the the break functions are
-% \emph{not} applied: \cs{seq_break_point:n} is functionally-equivalent
-% in these cases to \cs{use:n}.
-% \end{function}
-%
-% \section{Sequence implementation}
-%
-% \TestFiles{m3seq002,m3seq003}
-%
-% \begin{macrocode}
-%<*initex|package>
-% \end{macrocode}
-%
-% \begin{macrocode}
-%<*package>
-\ProvidesExplPackage
- {\filename}{\filedate}{\fileversion}{\filedescription}
-\package_check_loaded_expl:
-%</package>
-% \end{macrocode}
-%
-% A sequence is a control sequence whose top-level expansion is of
-% the form \enquote{\cs{seq_item:n} \marg{item$_1$}
-% \ldots \cs{seq_item:n} \marg{item$_n$}}. An earlier implementation
-% used the structure \enquote{\cs{seq_elt:w} \meta{item$_1$}
-% \cs{seq_elt_end:} \ldots \cs{seq_elt:w} \meta{item$_n$}
-% \cs{seq_elt_end:}}. This allows rapid searching using a delimited
-% function, but is not suitable for items containing |{|, |}| and |#|
-% tokens, and which also leads to the loss of surrounding braces
-% around items.
-%
-% \begin{macro}[int]{\seq_item:n}
-% The delimiter is always defined, but when used incorrectly simply
-% removes its argument and hits an undefined control sequence to
-% raise an error.
-% \begin{macrocode}
-\cs_new:Npn \seq_item:n
- {
- \seq_use_error:
- \use_none:n
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[aux]{\l_seq_tmpa_tl, \l_seq_tmpb_tl}
-% Scratch space for various internal uses.
-% \begin{macrocode}
-\tl_new:N \l_seq_tmpa_tl
-\tl_new:N \l_seq_tmpb_tl
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Allocation and initialisation}
-%
-% \begin{macro}{\seq_new:N,\seq_new:c}
-% \UnitTested
-% Internally, sequences are just token lists.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_new:N \tl_new:N
-\cs_new_eq:NN \seq_new:c \tl_new:c
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\seq_clear:N, \seq_clear:c}
-% \UnitTested
-% \begin{macro}{\seq_gclear:N, \seq_gclear:c}
-% \UnitTested
-% Clearing sequences is just the same as clearing token lists.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_clear:N \tl_clear:N
-\cs_new_eq:NN \seq_clear:c \tl_clear:c
-\cs_new_eq:NN \seq_gclear:N \tl_gclear:N
-\cs_new_eq:NN \seq_gclear:c \tl_gclear:c
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_clear_new:N, \seq_clear_new:c}
-% \UnitTested
-% \begin{macro}{\seq_gclear_new:N, \seq_gclear_new:c}
-% \UnitTested
-% Once again a simply copy from the token list functions.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_clear_new:N \tl_clear_new:N
-\cs_new_eq:NN \seq_clear_new:c \tl_clear_new:c
-\cs_new_eq:NN \seq_gclear_new:N \tl_gclear_new:N
-\cs_new_eq:NN \seq_gclear_new:c \tl_gclear_new:c
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_set_eq:NN, \seq_set_eq:cN, \seq_set_eq:Nc, \seq_set_eq:cc}
-% \UnitTested
-% \begin{macro}
-% {\seq_gset_eq:NN, \seq_gset_eq:cN, \seq_gset_eq:Nc, \seq_gset_eq:cc}
-% \UnitTested
-% Once again, these are simply copies from the token list functions.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_set_eq:NN \tl_set_eq:NN
-\cs_new_eq:NN \seq_set_eq:Nc \tl_set_eq:Nc
-\cs_new_eq:NN \seq_set_eq:cN \tl_set_eq:cN
-\cs_new_eq:NN \seq_set_eq:cc \tl_set_eq:cc
-\cs_new_eq:NN \seq_gset_eq:NN \tl_gset_eq:NN
-\cs_new_eq:NN \seq_gset_eq:Nc \tl_gset_eq:Nc
-\cs_new_eq:NN \seq_gset_eq:cN \tl_gset_eq:cN
-\cs_new_eq:NN \seq_gset_eq:cc \tl_gset_eq:cc
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_concat:NNN, \seq_concat:ccc}
-% \UnitTested
-% \begin{macro}{\seq_gconcat:NNN, \seq_gconcat:ccc}
-% \UnitTested
-% Concatenating sequences is easy.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_concat:NNN #1#2#3
- { \tl_set:Nx #1 { \exp_not:o {#2} \exp_not:o {#3} } }
-\cs_new_protected_nopar:Npn \seq_gconcat:NNN #1#2#3
- { \tl_gset:Nx #1 { \exp_not:o {#2} \exp_not:o {#3} } }
-\cs_generate_variant:Nn \seq_concat:NNN { ccc }
-\cs_generate_variant:Nn \seq_gconcat:NNN { ccc }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Appending data to either end}
-%
-% \begin{macro}{
-% \seq_put_left:Nn, \seq_put_left:NV, \seq_put_left:Nv,
-% \seq_put_left:No, \seq_put_left:Nx,
-% \seq_put_left:cn, \seq_put_left:cV, \seq_put_left:cv,
-% \seq_put_left:co, \seq_put_left:cx
-% }
-% \UnitTested
-% \begin{macro}{
-% \seq_put_right:Nn, \seq_put_right:NV, \seq_put_right:Nv,
-% \seq_put_right:No, \seq_put_right:Nx,
-% \seq_put_right:cn, \seq_put_right:cV, \seq_put_right:cv,
-% \seq_put_right:co, \seq_put_right:cx
-% }
-% \UnitTested
-% The code here is just a wrapper for adding to token lists.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_put_left:Nn #1#2
- { \tl_put_left:Nn #1 { \seq_item:n {#2} } }
-\cs_new_protected:Npn \seq_put_right:Nn #1#2
- { \tl_put_right:Nn #1 { \seq_item:n {#2} } }
-\cs_generate_variant:Nn \seq_put_left:Nn { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_put_left:Nn { c , cV , cv , co , cx }
-\cs_generate_variant:Nn \seq_put_right:Nn { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_put_right:Nn { c , cV , cv , co , cx }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{
-% \seq_gput_left:Nn, \seq_gput_left:NV, \seq_gput_left:Nv,
-% \seq_gput_left:No, \seq_gput_left:Nx,
-% \seq_gput_left:cn, \seq_gput_left:cV, \seq_gput_left:cv,
-% \seq_gput_left:co, \seq_gput_left:cx
-% }
-% \begin{macro}{
-% \seq_gput_right:Nn, \seq_gput_right:NV, \seq_gput_right:Nv,
-% \seq_gput_right:No, \seq_gput_right:Nx,
-% \seq_gput_right:cn, \seq_gput_right:cV,\seq_gput_right:cv,
-% \seq_gput_right:co, \seq_gput_right:cx
-% }
-% The same for global addition.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_gput_left:Nn #1#2
- { \tl_gput_left:Nn #1 { \seq_item:n {#2} } }
-\cs_new_protected:Npn \seq_gput_right:Nn #1#2
- { \tl_gput_right:Nn #1 { \seq_item:n {#2} } }
-\cs_generate_variant:Nn \seq_gput_left:Nn { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_gput_left:Nn { c , cV , cv , co , cx }
-\cs_generate_variant:Nn \seq_gput_right:Nn { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_gput_right:Nn { c , cV , cv , co , cx }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Breaking sequence functions}
-%
-% \begin{macro}[int]{\seq_break:}
-% \begin{macro}[int]{\seq_break:n}
-% To break a function, the special token \cs{seq_break_point:n} is
-% used to find the end of the code. Any ending code is then inserted
-% before the return value of \cs{seq_map_break:n} is inserted.
-% \begin{macrocode}
-\cs_new:Npn \seq_break: #1 \seq_break_point:n #2 {#2}
-\cs_new:Npn \seq_break:n #1#2 \seq_break_point:n #3 { #3 #1 }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_map_break:}
-% \UnitTested
-% \begin{macro}{\seq_map_break:n}
-% \UnitTested
-% Semantically-logical copies of the break functions for use inside
-% mappings.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_map_break: \seq_break:
-\cs_new_eq:NN \seq_map_break:n \seq_break:n
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[int]{\seq_break_point:n}
-% Normally, the marker token will not be executed, but if it is then
-% the end code is simply inserted.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_break_point:n \use:n
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[int]{\seq_if_empty_err_break:N}
-% A function to check that sequences really have some content. This
-% is optimised for speed, hence the direct primitive use.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_if_empty_err_break:N #1
- {
- \tex_ifx:D #1 \c_empty_tl
- \msg_kernel_bug:x { Empty~sequence~\token_to_str:N #1 }
- \exp_after:wN \seq_break:
- \tex_fi:D
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Mapping to sequences}
-%
-% \begin{macro}{\seq_map_function:NN, \seq_map_function:cN}
-% \UnitTested
-% \begin{macro}[aux]{\seq_map_function_aux:NNn}
-% The idea here is to apply the code of |#2| to each item in the
-% sequence without altering the definition of \cs{seq_item:n}. This
-% is done as by noting that every odd token in the sequence must be
-% \cs{seq_item:n}, which can be gobbled by \cs{use_none:n}. At the end of
-% the loop, |#2| is instead |? \seq_map_break:|, which therefore breaks the
-% loop without needing to do a (relatively-expensive) quark test.
-% \begin{macrocode}
-\cs_new:Npn \seq_map_function:NN #1#2
- {
- \exp_after:wN \seq_map_function_aux:NNn \exp_after:wN #2 #1
- { ? \seq_map_break: } { }
- \seq_break_point:n { }
- }
-\cs_new:Npn \seq_map_function_aux:NNn #1#2#3
- {
- \use_none:n #2
- #1 {#3}
- \seq_map_function_aux:NNn #1
- }
-\cs_generate_variant:Nn \seq_map_function:NN { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[aux]{\g_seq_nesting_depth_int}
-% A counter to keep track of nested functions.
-% \begin{macrocode}
-\int_new:N \g_seq_nesting_depth_int
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[int]{\seq_push_item_def:n, \seq_push_item_def:x}
-% \begin{macro}[aux]{\seq_push_item_def_aux:}
-% \begin{macro}[int]{\seq_pop_item_def:}
-% The definition of \cs{seq_item:n} needs to be saved and restored at
-% various points within the mapping and manipulation code. That is handled
-% here: as always, this approach uses global assignments.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_push_item_def:n
- {
- \seq_push_item_def_aux:
- \cs_gset:Npn \seq_item:n ##1
- }
-\cs_new_protected:Npn \seq_push_item_def:x
- {
- \seq_push_item_def_aux:
- \cs_gset:Npx \seq_item:n ##1
- }
-\cs_new_protected:Npn \seq_push_item_def_aux:
- {
- \cs_gset_eq:cN { seq_item_ \int_use:N \g_seq_nesting_depth_int :n }
- \seq_item:n
- \int_gincr:N \g_seq_nesting_depth_int
- }
-\cs_new_protected_nopar:Npn \seq_pop_item_def:
- {
- \int_gdecr:N \g_seq_nesting_depth_int
- \cs_gset_eq:Nc \seq_item:n
- { seq_item_ \int_use:N \g_seq_nesting_depth_int :n }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_map_inline:Nn, \seq_map_inline:cn}
-% \UnitTested
-% The idea here is that \cs{seq_item:n} is already \enquote{applied} to
-% each item in a sequence, and so an in-line mapping is just a case of
-% redefining \cs{seq_item:n}.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_map_inline:Nn #1#2
- {
- \seq_push_item_def:n {#2}
- #1
- \seq_break_point:n { \seq_pop_item_def: }
- }
-\cs_generate_variant:Nn \seq_map_inline:Nn { c }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{
-% \seq_map_variable:NNn,\seq_map_variable:Ncn,
-% \seq_map_variable:cNn,\seq_map_variable:ccn
-% }
-% \UnitTested
-% This is just a specialised version of the in-line mapping function,
-% using an \texttt{x}-type expansion for the code set up so that the
-% number of |#| tokens required is as expected.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_map_variable:NNn #1#2#3
- {
- \seq_push_item_def:x
- {
- \tl_set:Nn \exp_not:N #2 {##1}
- \exp_not:n {#3}
- }
- #1
- \seq_break_point:n { \seq_pop_item_def: }
- }
-\cs_generate_variant:Nn \seq_map_variable:NNn { Nc }
-\cs_generate_variant:Nn \seq_map_variable:NNn { c , cc }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Sequence stacks}
-%
-% The same functions as for sequences, but with the correct naming.
-%
-% \begin{macro}{
-% \seq_push:Nn, \seq_push:NV, \seq_push:Nv, \seq_push:No, \seq_push:Nx,
-% \seq_push:cn, \seq_push:cV, \seq_push:cV, \seq_push:co, \seq_push:cx
-% }
-% \UnitTested
-% \begin{macro}{
-% \seq_gpush:Nn, \seq_gpush:NV, \seq_gpush:Nv, \seq_gpush:No, \seq_gpush:Nx,
-% \seq_gpush:cn, \seq_gpush:cV, \seq_gpush:cv, \seq_gpush:co, \seq_gpush:cx
-% }
-% \UnitTested
-% Pushing to a sequence is the same as adding on the left.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_push:Nn \seq_put_left:Nn
-\cs_new_eq:NN \seq_push:NV \seq_put_left:NV
-\cs_new_eq:NN \seq_push:Nv \seq_put_left:Nv
-\cs_new_eq:NN \seq_push:No \seq_put_left:No
-\cs_new_eq:NN \seq_push:Nx \seq_put_left:Nx
-\cs_new_eq:NN \seq_push:cn \seq_put_left:cn
-\cs_new_eq:NN \seq_push:cV \seq_put_left:cV
-\cs_new_eq:NN \seq_push:cv \seq_put_left:cv
-\cs_new_eq:NN \seq_push:co \seq_put_left:co
-\cs_new_eq:NN \seq_push:cx \seq_put_left:cx
-\cs_new_eq:NN \seq_gpush:Nn \seq_gput_left:Nn
-\cs_new_eq:NN \seq_gpush:NV \seq_gput_left:NV
-\cs_new_eq:NN \seq_gpush:Nv \seq_gput_left:Nv
-\cs_new_eq:NN \seq_gpush:No \seq_gput_left:No
-\cs_new_eq:NN \seq_gpush:Nx \seq_gput_left:Nx
-\cs_new_eq:NN \seq_gpush:cn \seq_gput_left:cn
-\cs_new_eq:NN \seq_gpush:cV \seq_gput_left:cV
-\cs_new_eq:NN \seq_gpush:cv \seq_gput_left:cv
-\cs_new_eq:NN \seq_gpush:co \seq_gput_left:co
-\cs_new_eq:NN \seq_gpush:cx \seq_gput_left:cx
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_get_left:NN, \seq_get_left:cN}
-% \UnitTested
-% \begin{macro}[aux]{\seq_get_left_aux:Nw}
-% Getting an item from the left of a sequence is pretty easy: just
-% trim off the first item after removing the \cs{seq_item:n} at
-% the start.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_get_left:NN #1#2
- {
- \seq_if_empty_err_break:N #1
- \exp_after:wN \seq_get_left_aux:Nw #1 \q_stop #2
- \seq_break_point:n { }
- }
-\cs_new_protected:Npn \seq_get_left_aux:Nw \seq_item:n #1#2 \q_stop #3
- { \tl_set:Nn #3 {#1} }
-\cs_generate_variant:Nn \seq_get_left:NN { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_pop_left:NN, \seq_pop_left:cN}
-% \UnitTested
-% \begin{macro}{\seq_gpop_left:NN, \seq_gpop_left:cN}
-% \UnitTested
-% \begin{macro}[aux]{\seq_pop_left_aux:NNN}
-% \begin{macro}[aux]{\seq_pop_left_aux:Nw}
-% The approach to popping an item is pretty similar to that to get
-% an item, with the only difference being that the sequence itself has
-% to be redefined. This makes it more sensible to use an auxiliary
-% function for the local and global cases.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_pop_left:NN
- { \seq_pop_left_aux:NNN \tl_set:Nn }
-\cs_new_protected_nopar:Npn \seq_gpop_left:NN
- { \seq_pop_left_aux:NNN \tl_gset:Nn }
-\cs_new_protected_nopar:Npn \seq_pop_left_aux:NNN #1#2#3
- {
- \seq_if_empty_err_break:N #2
- \exp_after:wN \seq_pop_left_aux:Nw #2 \q_stop #1#2#3
- \seq_break_point:n { }
- }
-\cs_new_protected:Npn \seq_pop_left_aux:Nw \seq_item:n #1#2 \q_stop #3#4#5
- {
- #3 #4 {#2}
- \tl_set:Nn #5 {#1}
- }
-\cs_generate_variant:Nn \seq_pop_left:NN { c }
-\cs_generate_variant:Nn \seq_gpop_left:NN { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_get_right:NN, \seq_get_right:cN}
-% \UnitTested
-% \begin{macro}[aux]{\seq_get_right_aux:NN}
-% \begin{macro}[aux]{\seq_get_right_loop:nn}
-% The idea here is to remove the very first \cs{seq_item:n} from the
-% sequence, leaving a token list starting with the first braced entry.
-% Two arguments at a time are then grabbed: apart from the right-hand end of
-% the sequence, this will be a brace group followed by \cs{seq_item:n}. The
-% set up code means that these all disappear. At the end of the sequence,
-% the assignment is placed in front of the very last entry in the sequence,
-% before a tidying-up step takes place to remove the loop and reset the
-% meaning of \cs{seq_item:n}.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_get_right:NN #1#2
- {
- \seq_if_empty_err_break:N #1
- \seq_get_right_aux:NN #1#2
- \seq_break_point:n { }
- }
-\cs_new_protected_nopar:Npn \seq_get_right_aux:NN #1#2
- {
- \seq_push_item_def:n { }
- \exp_after:wN \exp_after:wN \exp_after:wN \seq_get_right_loop:nn
- \exp_after:wN \use_none:n #1
- { \tl_set:Nn #2 }
- { }
- {
- \seq_pop_item_def:
- \seq_break:
- }
-}
-\cs_new:Npn \seq_get_right_loop:nn #1#2
- {
- #2 {#1}
- \seq_get_right_loop:nn
- }
-\cs_generate_variant:Nn \seq_get_right:NN { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_pop_right:NN, \seq_pop_right:cN}
-% \UnitTested
-% \begin{macro}{\seq_gpop_right:NN, \seq_gpop_right:cN}
-% \UnitTested
-% \begin{macro}[aux]{\seq_get_right_aux:NNN, \seq_get_right_aux_ii:NNN}
-% The approach to popping from the right is a bit more involved, but does
-% use some of the same ideas as getting from the right. What is needed is a
-% \enquote{flexible length} way to set a token list variable. This is supplied
-% by the |{ \tex_iffalse:D } \tex_fi:D| \ldots |\tex_iffalse:D { \tex_fi:D }|
-% construct. Using an \texttt{x}-type expansion and a \enquote{non-expanding}
-% definition for \cs{seq_item:n}, the left-most $n - 1$ entries in a
-% sequence of $n$ items will be stored back in the sequence. That needs
-% a loop of unknown length, hence using the strange \cs{tex_iffalse:D}
-% way of including brackets. When the last item of the sequence is reached,
-% the closing bracket for the assignment is inserted, and |\tl_set:Nn #3|
-% is inserted in front of the final entry. This therefore does the pop
-% assignment, then a final loop clears up the code.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_pop_right:NN
- { \seq_pop_right_aux:NNN \tl_set:Nx }
-\cs_new_protected_nopar:Npn \seq_gpop_right:NN
- { \seq_pop_right_aux:NNN \tl_gset:Nx }
-\cs_new_protected_nopar:Npn \seq_pop_right_aux:NNN #1#2#3
- {
- \seq_if_empty_err_break:N #2
- \seq_pop_right_aux_ii:NNN #1 #2 #3
- \seq_break_point:n { }
- }
-\cs_new_protected_nopar:Npn \seq_pop_right_aux_ii:NNN #1#2#3
- {
- \seq_push_item_def:n { \exp_not:n { \seq_item:n {##1} } }
- #1 #2 { \tex_iffalse:D } \tex_fi:D
- \exp_after:wN \exp_after:wN \exp_after:wN \seq_get_right_loop:nn
- \exp_after:wN \use_none:n #2
- {
- \tex_iffalse:D { \tex_fi:D }
- \tl_set:Nn #3
- }
- { }
- {
- \seq_pop_item_def:
- \seq_break:
- }
- }
-\cs_generate_variant:Nn \seq_pop_right:NN { c }
-\cs_generate_variant:Nn \seq_gpop_right:NN { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_get:NN, \seq_get:cN}
-% \UnitTested
-% \begin{macro}{\seq_pop:NN, \seq_pop:cN}
-% \UnitTested
-% \begin{macro}{\seq_gpop:NN, \seq_gpop:cN}
-% \UnitTested
-% In most cases, getting items from the stack does not need to specify
-% that this is from the left. So alias are provided.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_get:NN \seq_get_left:NN
-\cs_new_eq:NN \seq_get:cN \seq_get_left:cN
-\cs_new_eq:NN \seq_pop:NN \seq_pop_left:NN
-\cs_new_eq:NN \seq_pop:cN \seq_pop_left:cN
-\cs_new_eq:NN \seq_gpop:NN \seq_gpop_left:NN
-\cs_new_eq:NN \seq_gpop:cN \seq_gpop_left:cN
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Sequence conditionals}
-%
-% \begin{macro}[pTF]{\seq_if_empty:N, \seq_if_empty:c}
-% \UnitTested
-% Simple copies from the token list variable material.
-% \begin{macrocode}
-\prg_new_eq_conditional:NNn \seq_if_empty:N \tl_if_empty:N
- { p , T , F , TF }
-\prg_new_eq_conditional:NNn \seq_if_empty:c \tl_if_empty:c
- { p , T , F , TF }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[TF]{
-% \seq_if_in:Nn, \seq_if_in:NV, \seq_if_in:Nv, \seq_if_in:No, \seq_if_in:Nx,
-% \seq_if_in:cn, \seq_if_in:cV, \seq_if_in:cv, \seq_if_in:co, \seq_if_in:cx
-% }
-% \UnitTested
-% \begin{macro}[aux]{\seq_if_in_aux:}
-% The approach here is to define \cs{seq_item:n} to compare its
-% argument with the test sequence. If the two items are equal, the
-% mapping is terminated and \cs{prg_return_true:} is inserted. On the
-% other hand, if there is no match then the loop will break returning
-% \cs{prg_return_false:}. In either case, \cs{seq_break_point:n}
-% ensures that the group ends before the logical value is returned.
-% Everything is inside a group so that \cs{seq_item:n} is preserved
-% in nested situations.
-% \begin{macrocode}
-\prg_new_protected_conditional:Npnn \seq_if_in:Nn #1#2
- { T , F , TF }
- {
- \group_begin:
- \tl_set:Nn \l_seq_tmpa_tl {#2}
- \cs_set_protected:Npn \seq_item:n ##1
- {
- \tl_set:Nn \l_seq_tmpb_tl {##1}
- \tex_ifx:D \l_seq_tmpa_tl \l_seq_tmpb_tl
- \exp_after:wN \seq_if_in_aux:
- \tex_fi:D
- }
- #1
- \seq_break:n { \prg_return_false: }
- \seq_break_point:n { \group_end: }
- }
-\cs_new_nopar:Npn \seq_if_in_aux: { \seq_break:n { \prg_return_true: } }
-\cs_generate_variant:Nn \seq_if_in:NnT { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_if_in:NnT { c , cV , cv , co , cx }
-\cs_generate_variant:Nn \seq_if_in:NnF { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_if_in:NnF { c , cV , cv , co , cx }
-\cs_generate_variant:Nn \seq_if_in:NnTF { NV , Nv , No , Nx }
-\cs_generate_variant:Nn \seq_if_in:NnTF { c , cV , cv , co , cx }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Modifying sequences}
-%
-% \begin{macro}[aux]{\l_seq_remove_seq}
-% An internal sequence for the removal routines.
-% \begin{macrocode}
-\seq_new:N \l_seq_remove_seq
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\seq_remove_duplicates:N, \seq_remove_duplicates:c}
-% \UnitTested
-% \begin{macro}{\seq_gremove_duplicates:N, \seq_gremove_duplicates:c}
-% \UnitTested
-% \begin{macro}[aux]{\seq_remove_duplicates_aux:NN}
-% Removing duplicates means making a new list then copying it.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_remove_duplicates:N
- { \seq_remove_duplicates_aux:NN \seq_set_eq:NN }
-\cs_new_protected:Npn \seq_gremove_duplicates:N
- { \seq_remove_duplicates_aux:NN \seq_gset_eq:NN }
-\cs_new_protected:Npn \seq_remove_duplicates_aux:NN #1#2
- {
- \seq_clear:N \l_seq_remove_seq
- \seq_map_inline:Nn #2
- {
- \seq_if_in:NnF \l_seq_remove_seq {##1}
- { \seq_put_right:Nn \l_seq_remove_seq {##1} }
- }
- #1 #2 \l_seq_remove_seq
- }
-\cs_generate_variant:Nn \seq_remove_duplicates:N { c }
-\cs_generate_variant:Nn \seq_gremove_duplicates:N { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\seq_remove_all:Nn, \seq_remove_all:cn}
-% \UnitTested
-% \begin{macro}{\seq_gremove_all:Nn, \seq_gremove_all:cn}
-% \UnitTested
-% \begin{macro}[aux]{\seq_remove_all_aux:NNn}
-% The idea of the code here is to avoid a relatively expensive addition of
-% items one at a time to an intermediate sequence.
-% The approach taken is therefore similar to
-% that in \cs{seq_pop_right_aux_ii:NNN}, using a \enquote{flexible}
-% \texttt{x}-type expansion to do most of the work. As \cs{tl_if_eq:nnT}
-% is not expandable, a two-part strategy is needed. First, the
-% \texttt{x}-type expansion uses \cs{str_if_eq:nnT} to find potential
-% matches. If one is found, the expansion is halted and the necessary
-% set up takes place to use the \cs{tl_if_eq:NNT} test. The \texttt{x}-type
-% is started again, including all of the items copied already. This will
-% happen repeatedly until the entire sequence has been scanned. The code
-% is set up to avoid needing and intermediate scratch list: the lead-off
-% \texttt{x}-type expansion (|#1 #2 {#2}|) will ensure that nothing is
-% lost.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_remove_all:Nn
- { \seq_remove_all_aux:NNn \tl_set:Nx }
-\cs_new_protected:Npn \seq_gremove_all:Nn
- { \seq_remove_all_aux:NNn \tl_gset:Nx }
-\cs_new_protected:Npn \seq_remove_all_aux:NNn #1#2#3
- {
- \seq_push_item_def:n
- {
- \str_if_eq:nnT {##1} {#3}
- {
- \tex_iffalse:D { \tex_fi:D }
- \tl_set:Nn \l_seq_tmpb_tl {##1}
- #1 #2
- { \tex_iffalse:D } \tex_fi:D
- \exp_not:o {#2}
- \tl_if_eq:NNT \l_seq_tmpa_tl \l_seq_tmpb_tl
- { \use_none:nn }
- }
- \exp_not:n { \seq_item:n {##1} }
- }
- \tl_set:Nn \l_seq_tmpa_tl {#3}
- #1 #2 {#2}
- \seq_pop_item_def:
- }
-\cs_generate_variant:Nn \seq_remove_all:Nn { c }
-\cs_generate_variant:Nn \seq_gremove_all:Nn { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \section{Viewing sequences}
-%
-% \begin{macro}[aux]{\l_seq_show_tl}
-% Used to store the material for display.
-% \begin{macrocode}
-\tl_new:N \l_seq_show_tl
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\seq_show:N, \seq_show:c}
-% \UnitTested
-% \begin{macro}[aux]{\seq_show_aux:n}
-% \begin{macro}[aux]{\seq_show_aux:w}
-% The aim of the mapping here is to create a token list containing the
-% formatted sequence. The very first item needs the new line and \verb*|> |
-% removing, which is achieved using a \texttt{w}-type auxiliary. To avoid
-% a low-level \TeX{} error if there is an empty sequence, a simple test is
-% used to keep the output \enquote{clean}.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \seq_show:N #1
- {
- \seq_if_empty:NTF #1
- {
- \iow_term:x { Sequence~\token_to_str:N #1 \c_space_tl is~empty }
- \tl_show:n { }
- }
- {
- \iow_term:x
- {
- Sequence~\token_to_str:N #1 \c_space_tl
- contains~the~items~(without~outer~braces):
- }
- \tl_set:Nx \l_seq_show_tl
- { \seq_map_function:NN #1 \seq_show_aux:n }
- \etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN
- { \exp_after:wN \seq_show_aux:w \l_seq_show_tl }
- }
- }
-\cs_new:Npn \seq_show_aux:n #1
- {
- \iow_newline: > \c_space_tl \c_space_tl
- \iow_char:N \{ \exp_not:n {#1} \iow_char:N \}
- }
-\cs_new:Npn \seq_show_aux:w #1 > ~ { }
-\cs_generate_variant:Nn \seq_show:N { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Depreciated interfaces}
-%
-% A few functions which are no longer documented: these were moved
-% here on or before 2011-04-20, and will be removed entirely by
-% 2011-07-20.
-%
-% \begin{macro}{\seq_top:NN, \seq_top:cN}
-% These are old stack functions.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_top:NN \seq_get_left:NN
-\cs_new_eq:NN \seq_top:cN \seq_get_left:cN
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\seq_display:N, \seq_display:c}
-% An older name for \cs{seq_show:N}.
-% \begin{macrocode}
-\cs_new_eq:NN \seq_display:N \seq_show:N
-\cs_new_eq:NN \seq_display:c \seq_show:c
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</initex|package>
-% \end{macrocode}
-%
-% \end{implementation}
-%
-% \PrintIndex \ No newline at end of file