summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-07-29 20:47:01 +0000
committerKarl Berry <karl@freefriends.org>2015-07-29 20:47:01 +0000
commitdb0facd61cf60ed3452c300b54f11c0524a50a53 (patch)
tree74963ac7b29b8e5c006ddeee61b1fe8b5c28a068 /Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
parentc65840a39db649af13ec3ceefaa2481d37d1e086 (diff)
l3 (29jul15)
git-svn-id: svn://tug.org/texlive/trunk@37997 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3seq.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3seq.dtx98
1 files changed, 96 insertions, 2 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
index 8fc257e4d54..7b81df583c8 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3seq.dtx Copyright (C) 1990-2014 The LaTeX3 Project
+%% File: l3seq.dtx Copyright (C) 1990-2015 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
@@ -37,7 +37,7 @@
\documentclass[full]{l3doc}
%</driver>
%<*driver|package>
-\GetIdInfo$Id: l3seq.dtx 5354 2014-08-23 01:35:39Z bruno $
+\GetIdInfo$Id: l3seq.dtx 5681 2015-07-24 03:01:31Z bruno $
{L3 Sequences and stacks}
%</driver|package>
%<*driver>
@@ -737,6 +737,100 @@
% Adds the \Arg{item} to the top of the \meta{sequence}.
% \end{function}
%
+% \section{Sequences as sets}
+%
+% Sequences can also be used as sets, such that all of their items are
+% distinct. Usage of sequences as sets is not currently widespread,
+% hence no specific set function is provided. Instead, it is explained
+% here how common set operations can be performed by combining several
+% functions described in earlier sections. When using sequences to
+% implement sets, one should be careful not to rely on the order of
+% items in the sequence representing the set.
+%
+% Sets should not contain several occurences of a given item. To make
+% sure that a \meta{sequence variable} only has distinct items, use
+% \cs{seq_remove_duplicates:N} \meta{sequence variable}. This function
+% is relatively slow, and to avoid performance issues one should only
+% use it when necessary.
+%
+% Some operations on a set \meta{seq~var} are straightforward. For
+% instance, \cs{seq_count:N} \meta{seq~var} expands to the number of
+% items, while \cs{seq_if_in:Nn(TF)} \meta{seq~var} \Arg{item} tests if
+% the \meta{item} is in the set.
+%
+% Adding an \meta{item} to a set \meta{seq~var} can be done by appending
+% it to the \meta{seq~var} if it is not already in the \meta{seq~var}:
+% \begin{quote}\ttfamily
+% \cs{seq_if_in:NnF} \meta{seq~var} \Arg{item} \\
+% \ \ \{ \cs{seq_put_right:Nn} \meta{seq~var} \Arg{item} \}
+% \end{quote}
+% Removing an \meta{item} from a set \meta{seq~var} can be done using
+% \cs{seq_remove_all:Nn},
+% \begin{quote}\ttfamily
+% \cs{seq_remove_all:Nn} \meta{seq~var} \Arg{item}
+% \end{quote}
+%
+% The intersection of two sets \meta{seq~var_1} and \meta{seq~var_2} can
+% be stored into \meta{seq~var_3} by collecting items of
+% \meta{seq~var_1} which are in \meta{seq~var_2}.
+% \begin{quote}\ttfamily
+% \cs{seq_clear:N} \meta{seq~var_3} \\
+% \cs{seq_map_inline:Nn} \meta{seq~var_1} \\
+% \ \ \{ \\
+% \ \ \ \ \cs{seq_if_in:NnT} \meta{seq~var_2} \{\#1\} \\
+% \ \ \ \ \ \ \{ \cs{seq_put_right:Nn} \meta{seq~var_3} \{\#1\} \} \\
+% \ \ \}
+% \end{quote}
+% The code as written here only works if \meta{seq~var_3} is different
+% from the other two sequence variables. To cover all cases, items
+% should first be collected in a sequence
+% |\l__|\meta{pkg}|_internal_seq|, then \meta{seq~var_3} should be set
+% equal to this internal sequence. The same remark applies to other set
+% functions.
+%
+% The union of two sets \meta{seq~var_1} and \meta{seq~var_2} can be
+% stored into \meta{seq~var_3} through
+% \begin{quote}\ttfamily
+% \cs{seq_concat:NNN} \meta{seq~var_3} \meta{seq~var_1} \meta{seq~var_2} \\
+% \cs{seq_remove_duplicates:N} \meta{seq~var_3}
+% \end{quote}
+% or by adding items to (a copy of) \meta{seq~var_1} one by one
+% \begin{quote}\ttfamily
+% \cs{seq_set_eq:NN} \meta{seq~var_3} \meta{seq~var_1} \\
+% \cs{seq_map_inline:Nn} \meta{seq~var_2} \\
+% \ \ \{ \\
+% \ \ \ \ \cs{seq_if_in:NnF} \meta{seq~var_3} \{\#1\} \\
+% \ \ \ \ \ \ \{ \cs{seq_put_right:Nn} \meta{seq~var_3} \{\#1\} \} \\
+% \ \ \}
+% \end{quote}
+% The second approach is faster than the first when the \meta{seq~var_2}
+% is short compared to \meta{seq~var_1}.
+%
+% The difference of two sets \meta{seq~var_1} and \meta{seq~var_2} can
+% be stored into \meta{seq~var_3} by removing items of the
+% \meta{seq~var_2} from (a copy of) the \meta{seq~var_1} one by one.
+% \begin{quote}\ttfamily
+% \cs{seq_set_eq:NN} \meta{seq~var_3} \meta{seq~var_1} \\
+% \cs{seq_map_inline:Nn} \meta{seq~var_2} \\
+% \ \ \{ \cs{seq_remove_all:Nn} \meta{seq~var_3} \{\#1\} \}
+% \end{quote}
+%
+% The symmetric difference of two sets \meta{seq~var_1} and
+% \meta{seq~var_2} can be stored into \meta{seq~var_3} by computing the
+% difference between \meta{seq~var_1} and \meta{seq~var_2} and storing
+% the result as |\l__|\meta{pkg}|_internal_seq|, then the difference
+% between \meta{seq~var_2} and \meta{seq~var_1}, and finally
+% concatenating the two differences to get the symmetric differences.
+% \begin{quote}\ttfamily
+% \cs{seq_set_eq:NN} |\l__|\meta{pkg}|_internal_seq| \meta{seq~var_1} \\
+% \cs{seq_map_inline:Nn} \meta{seq~var_2} \\
+% \ \ \{ \cs{seq_remove_all:Nn} |\l__|\meta{pkg}|_internal_seq| \{\#1\} \} \\
+% \cs{seq_set_eq:NN} \meta{seq~var_3} \meta{seq~var_2} \\
+% \cs{seq_map_inline:Nn} \meta{seq~var_1} \\
+% \ \ \{ \cs{seq_remove_all:Nn} \meta{seq~var_3} \{\#1\} \} \\
+% \cs{seq_concat:NNN} \meta{seq~var_3} \meta{seq~var_3} |\l__|\meta{pkg}|_internal_seq|
+% \end{quote}
+%
% \section{Constant and scratch sequences}
%
% \begin{variable}[added = 2012-07-02]{\c_empty_seq}