The LATEX3 Interfaces

The LATEX3 Project∗

July 20, 2014

Abstract

This is the reference documentation for the expl3 programming environment. The
expl3 modules set up an experimental naming scheme for LATEX commands, which
allow the LATEX programmer to systematically name functions and variables, and
specify the argument types of functions.

The TEX and ε-TEX primitives are all given a new name according to these con-
ventions. However, in the main direct use of the primitives is not required or en-
couraged: the expl3 modules define an independent low-level LATEX3 programming
language.

At present, the expl3 modules are designed to be loaded on top of LATEX 2ε . In time,
a LATEX3 format will be produced based on this code. This allows the code to be
used in LATEX 2ε packages now while a stand-alone LATEX3 is developed.

While expl3 is still experimental, the bundle is now regarded as broadly

stable. The syntax conventions and functions provided are now ready
for wider use. There may still be changes to some functions, but these
will be minor when compared to the scope of expl3.

New modules will be added to the distributed version of expl3 as they

reach maturity.

∗ E-mail: [email protected]

i
Contents

I Introduction to expl3 and this document 1

1 Naming functions and variables 1
1.1 Terminological inexactitude . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Documentation conventions 3

3 Formal language conventions which apply generally 5

4 TEX concepts not supported by LATEX3 6

II The l3bootstrap package: Bootstrap code 7

1 Using the LATEX3 modules 7
1.1 Internal functions and variables . . . . . . . . . . . . . . . . . . . . . . . 8

III The l3names package: Namespace for primitives 9

1 Setting up the LATEX3 programming language 9

IV The l3basics package: Basic definitions 10

1 No operation functions 10

2 Grouping material 10

3 Control sequences and functions 11

3.1 Defining functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Defining new functions using parameter text . . . . . . . . . . . . . . . 12
3.3 Defining new functions using the signature . . . . . . . . . . . . . . . . 14
3.4 Copying control sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5 Deleting control sequences . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.6 Showing control sequences . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.7 Converting to and from control sequences . . . . . . . . . . . . . . . . . 18

4 Using or removing tokens and arguments 19

4.1 Selecting tokens from delimited arguments . . . . . . . . . . . . . . . . 21

5 Predicates and conditionals 21

5.1 Tests on control sequences . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2 Engine-specific conditionals . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 Primitive conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

ii
6 Internal kernel functions 24

V The l3expan package: Argument expansion 26

1 Defining new variants 26

2 Methods for defining variants 27

3 Introducing the variants 27

4 Manipulating the first argument 28

5 Manipulating two arguments 29

6 Manipulating three arguments 30

7 Unbraced expansion 31

8 Preventing expansion 31

9 Internal functions and variables 33

VI The l3prg package: Control structures 34

1 Defining a set of conditional functions 34

2 The boolean data type 36

3 Boolean expressions 38

4 Logical loops 39

5 Producing n copies 40

6 Detecting TEX’s mode 40

7 Primitive conditionals 41

8 Internal programming functions 41

VII The l3quark package: Quarks 43

1 Introduction to quarks and scan marks 43
1.1 Quarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

2 Defining quarks 44

iii
3 Quark tests 44

4 Recursion 45

5 An example of recursion with quarks 46

6 Internal quark functions 46

7 Scan marks 47

VIII The l3token package: Token manipulation 48

1 All possible tokens 48

2 Character tokens 49

3 Generic tokens 52

4 Converting tokens 53

5 Token conditionals 53

6 Peeking ahead at the next token 57

7 Decomposing a macro definition 60

IX The l3int package: Integers 61

1 Integer expressions 61

2 Creating and initialising integers 62

3 Setting and incrementing integers 63

4 Using integers 64

5 Integer expression conditionals 64

6 Integer expression loops 66

7 Integer step functions 68

8 Formatting integers 68

9 Converting from other formats to integers 70

10 Viewing integers 71

iv
11 Constant integers 72

12 Scratch integers 72

13 Primitive conditionals 73

14 Internal functions 73

X The l3skip package: Dimensions and skips 75

1 Creating and initialising dim variables 75

2 Setting dim variables 76

3 Utilities for dimension calculations 76

4 Dimension expression conditionals 77

5 Dimension expression loops 79

6 Using dim expressions and variables 80

7 Viewing dim variables 82

8 Constant dimensions 82

9 Scratch dimensions 82

10 Creating and initialising skip variables 83

11 Setting skip variables 83

12 Skip expression conditionals 84

13 Using skip expressions and variables 84

14 Viewing skip variables 85

15 Constant skips 85

16 Scratch skips 85

17 Inserting skips into the output 86

18 Creating and initialising muskip variables 86

19 Setting muskip variables 87

v
20 Using muskip expressions and variables 87

21 Viewing muskip variables 88

22 Constant muskips 88

23 Scratch muskips 88

24 Primitive conditional 88

25 Internal functions 89

XI The l3tl package: Token lists 90

1 Creating and initialising token list variables 91

2 Adding data to token list variables 92

3 Modifying token list variables 92

4 Reassigning token list category codes 93

5 Reassigning token list character codes 93

6 Token list conditionals 94

7 Mapping to token lists 96

8 Using token lists 98

9 Working with the content of token lists 98

10 The first token from a token list 100

11 Using a single item 102

12 Viewing token lists 102

13 Constant token lists 103

14 Scratch token lists 103

15 Internal functions 103

XII The l3str package:Strings 104

vi
1 The first character from a string 104
1.1 Tests on strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

2 String manipulation 106

2.1 Internal string functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

XIII The l3seq package: Sequences and stacks 107

1 Creating and initialising sequences 107

2 Appending data to sequences 108

3 Recovering items from sequences 108

4 Recovering values from sequences with branching 110

5 Modifying sequences 111

6 Sequence conditionals 112

7 Mapping to sequences 112

8 Using the content of sequences directly 114

9 Sequences as stacks 114

10 Constant and scratch sequences 116

11 Viewing sequences 116

12 Internal sequence functions 116

XIV The l3clist package: Comma separated lists 117

1 Creating and initialising comma lists 117

2 Adding data to comma lists 118

3 Modifying comma lists 119

4 Comma list conditionals 120

5 Mapping to comma lists 121

6 Using the content of comma lists directly 123

7 Comma lists as stacks 123

vii
8 Using a single item 125

9 Viewing comma lists 125

10 Constant and scratch comma lists 125

XV The l3prop package: Property lists 127

1 Creating and initialising property lists 127

2 Adding entries to property lists 128

3 Recovering values from property lists 128

4 Modifying property lists 129

5 Property list conditionals 129

6 Recovering values from property lists with branching 130

7 Mapping to property lists 130

8 Viewing property lists 131

9 Scratch property lists 132

10 Constants 132

11 Internal property list functions 132

XVI The l3box package: Boxes 133

1 Creating and initialising boxes 133

2 Using boxes 134

3 Measuring and setting box dimensions 134

4 Box conditionals 135

5 The last box inserted 136

6 Constant boxes 136

7 Scratch boxes 136

8 Viewing box contents 136

viii
9 Horizontal mode boxes 137

10 Vertical mode boxes 138

11 Primitive box conditionals 140

XVII The l3coffins package: Coffin code layer 141

1 Creating and initialising coffins 141

2 Setting coffin content and poles 141

3 Joining and using coffins 143

4 Measuring coffins 143

5 Coffin diagnostics 144

5.1 Constants and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

XVIII The l3color package: Color support 145

1 Color in boxes 145

XIX The l3msg package: Messages 146

1 Creating new messages 146

2 Contextual information for messages 147

3 Issuing messages 148

4 Redirecting messages 150

5 Low-level message functions 151

6 Kernel-specific functions 152

7 Expandable errors 153

8 Internal l3msg functions 154

XX The l3keys package: Key–value interfaces 156

1 Creating keys 157

ix
2 Sub-dividing keys 161

3 Choice and multiple choice keys 161

4 Setting keys 163

5 Handling of unknown keys 164

6 Selective key setting 165

7 Utility functions for keys 166

8 Low-level interface for parsing key–val lists 166

XXI The l3file package: File and I/O operations 168

1 File operation functions 168
1.1 Input–output stream management . . . . . . . . . . . . . . . . . . . . . 169
1.2 Reading from files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

2 Writing to files 171

2.1 Wrapping lines in output . . . . . . . . . . . . . . . . . . . . . . . . . . 173
2.2 Constant input–output streams . . . . . . . . . . . . . . . . . . . . . . . 174
2.3 Primitive conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
2.4 Internal file functions and variables . . . . . . . . . . . . . . . . . . . . 174
2.5 Internal input–output functions . . . . . . . . . . . . . . . . . . . . . . 175

XXII The l3fp package: floating points 176

1 Creating and initialising floating point variables 177

2 Setting floating point variables 177

3 Using floating point numbers 178

4 Floating point conditionals 179

5 Floating point expression loops 181

6 Some useful constants, and scratch variables 182

7 Floating point exceptions 183

8 Viewing floating points 184

x
9 Floating point expressions 184
9.1 Input of floating point numbers . . . . . . . . . . . . . . . . . . . . . . . 184
9.2 Precedence of operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
9.3 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

10 Disclaimer and roadmap 191

XXIII The l3candidates package: Experimental additions to

l3kernel 194
1 Important notice 194

2 Additions to l3box 194

2.1 Affine transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
2.2 Viewing part of a box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
2.3 Internal variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

3 Additions to l3coffins 197

4 Additions to l3file 198

5 Additions to l3prop 200

6 Additions to l3seq 200

7 Additions to l3skip 201

8 Additions to l3tl 201

9 Additions to l3tokens 204

XXIV The l3drivers package: Drivers 205

1 Box clipping 205

2 Box rotation and scaling 206

3 Color support 206

Index 207

xi
Part I
Introduction to expl3 and this
document
This document is intended to act as a comprehensive reference manual for the expl3
language. A general guide to the LATEX3 programming language is found in expl3.pdf.

1 Naming functions and variables

LATEX3 does not use @ as a “letter” for defining internal macros. Instead, the symbols _
and : are used in internal macro names to provide structure. The name of each function
is divided into logical units using _, while : separates the name of the function from the
argument specifier (“arg-spec”). This describes the arguments expected by the function.
In most cases, each argument is represented by a single letter. The complete list of
arg-spec letters for a function is referred to as the signature of the function.
Each function name starts with the module to which it belongs. Thus apart from a
small number of very basic functions, all expl3 function names contain at least one under-
score to divide the module name from the descriptive name of the function. For example,
all functions concerned with comma lists are in module clist and begin \clist_.
Every function must include an argument specifier. For functions which take no
arguments, this will be blank and the function name will end :. Most functions take one
or more arguments, and use the following argument specifiers:
D The D specifier means do not use. All of the TEX primitives are initially \let to a D
name, and some are then given a second name. Only the kernel team should use
anything with a D specifier!
N and n These mean no manipulation, of a single token for N and of a set of tokens given
in braces for n. Both pass the argument through exactly as given. Usually, if you
use a single token for an n argument, all will be well.

c This means csname, and indicates that the argument will be turned into a csname
before being used. So So \foo:c {ArgumentOne} will act in the same way as
\foo:N \ArgumentOne.
V and v These mean value of variable. The V and v specifiers are used to get the con-
tent of a variable without needing to worry about the underlying TEX structure
containing the data. A V argument will be a single token (similar to N), for example
\foo:V \MyVariable; on the other hand, using v a csname is constructed first, and
then the value is recovered, for example \foo:v {MyVariable}.
o This means expansion once. In general, the V and v specifiers are favoured over o
for recovering stored information. However, o is useful for correctly processing
information with delimited arguments.

1
x The x specifier stands for exhaustive expansion: every token in the argument is fully
expanded until only unexpandable ones remain. The TEX \edef primitive carries
out this type of expansion. Functions which feature an x-type argument are in
general not expandable, unless specifically noted.
f The f specifier stands for full expansion, and in contrast to x stops at the first non-
expandable item (reading the argument from left to right) without trying to expand
it. For example, when setting a token list variable (a macro used for storage), the
sequence
\tl_set:Nn \l_mya_tl { A }
\tl_set:Nn \l_myb_tl { B }
\tl_set:Nf \l_mya_tl { \l_mya_tl \l_myb_tl }
will leave \l_mya_tl with the content A\l_myb_tl, as A cannot be expanded and
so terminates expansion before \l_myb_tl is considered.
T and F For logic tests, there are the branch specifiers T (true) and F (false). Both
specifiers treat the input in the same way as n (no change), but make the logic
much easier to see.
p The letter p indicates TEX parameters. Normally this will be used for delimited func-
tions as expl3 provides better methods for creating simple sequential arguments.
w Finally, there is the w specifier for weird arguments. This covers everything else, but
mainly applies to delimited values (where the argument must be terminated by
some arbitrary string).
Notice that the argument specifier describes how the argument is processed prior to being
passed to the underlying function. For example, \foo:c will take its argument, convert
it to a control sequence and pass it to \foo:N.
Variables are named in a similar manner to functions, but begin with a single letter
to define the type of variable:
c Constant: global parameters whose value should not be changed.
g Parameters whose value should only be set globally.
l Parameters whose value should only be set locally.
Each variable name is then build up in a similar way to that of a function, typically
starting with the module1 name and then a descriptive part. Variables end with a short
identifier to show the variable type:
bool Either true or false.
box Box register.
1 The module names are not used in case of generic scratch registers defined in the data type modules,

e.g., the int module contains some scratch variables called \l_tmpa_int, \l_tmpb_int, and so on. In
such a case adding the module name up front to denote the module and in the back to indicate the type,
as in \l_int_tmpa_int would be very unreadable.

2
clist Comma separated list.
coffin a “box with handles” — a higher-level data type for carrying out box alignment
operations.
dim “Rigid” lengths.

fp floating-point values;
int Integer-valued count register.
prop Property list.

seq “Sequence”: a data-type used to implement lists (with access at both ends) and
stacks.
skip “Rubber” lengths.
stream An input or output stream (for reading from or writing to, respectively).

tl Token list variables: placeholder for a token list.

1.1 Terminological inexactitude

A word of warning. In this document, and others referring to the expl3 programming
modules, we often refer to “variables” and “functions” as if they were actual constructs
from a real programming language. In truth, TEX is a macro processor, and functions
are simply macros that may or may not take arguments and expand to their replacement
text. Many of the common variables are also macros, and if placed into the input stream
will simply expand to their definition as well — a “function” with no arguments and a
“token list variable” are in truth one and the same. On the other hand, some “variables”
are actually registers that must be initialised and their values set and retrieved with
specific functions.
The conventions of the expl3 code are designed to clearly separate the ideas of
“macros that contain data” and “macros that contain code”, and a consistent wrapper is
applied to all forms of “data” whether they be macros or actually registers. This means
that sometimes we will use phrases like “the function returns a value”, when actually we
just mean “the macro expands to something”. Similarly, the term “execute” might be
used in place of “expand” or it might refer to the more specific case of “processing in
TEX’s stomach” (if you are familiar with the TEXbook parlance).
If in doubt, please ask; chances are we’ve been hasty in writing certain definitions
and need to be told to tighten up our terminology.

2 Documentation conventions
This document is typeset with the experimental l3doc class; several conventions are used
to help describe the features of the code. A number of conventions are used here to make
the documentation clearer.

3
 Each group of related functions is given in a box. For a function with a “user” name,
this might read:

\ExplSyntaxOn \ExplSyntaxOn ... \ExplSyntaxOff

\ExplSyntaxOff
The textual description of how the function works would appear here. The syntax of
the function is shown in mono-spaced text to the right of the box. In this example, the
function takes no arguments and so the name of the function is simply reprinted.
For programming functions, which use _ and : in their name there are a few addi-
tional conventions: If two related functions are given with identical names but different
argument specifiers, these are termed variants of each other, and the latter functions are
printed in grey to show this more clearly. They will carry out the same function but will
take different types of argument:

\seq_new:N \seq_new:N hsequence i

\seq_new:c
When a number of variants are described, the arguments are usually illustrated only for
the base function. Here, hsequencei indicates that \seq_new:N expects the name of a
sequence. From the argument specifier, \seq_new:c also expects a sequence name, but
as a name rather than as a control sequence. Each argument given in the illustration
should be described in the following text.

Fully expandable functions Some functions are fully expandable, which allows it
to be used within an x-type argument (in plain TEX terms, inside an \edef), as well
as within an f-type argument. These fully expandable functions are indicated in the
documentation by a star:

\cs_to_str:N ? \cs_to_str:N hcs i

As with other functions, some text should follow which explains how the function works.
Usually, only the star will indicate that the function is expandable. In this case, the
function expects a hcsi, shorthand for a hcontrol sequencei.

Restricted expandable functions A few functions are fully expandable but cannot
be fully expanded within an f-type argument. In this case a hollow star is used to indicate
this:

\seq_map_function:NN I \seq_map_function:NN hseq i hfunction i

Conditional functions Conditional (if) functions are normally defined in three vari-
ants, with T, F and TF argument specifiers. This allows them to be used for different
“true”/“false” branches, depending on which outcome the conditional is being used to
test. To indicate this without repetition, this information is given in a shortened form:

4
\xetex_if_engine:TF ? \xetex_if_engine:TF {htrue code i} {hfalse code i}
The underlining and italic of TF indicates that \xetex_if_engine:T, \xetex_if_-
engine:F and \xetex_if_engine:TF are all available. Usually, the illustration will use
the TF variant, and so both htrue codei and hfalse codei will be shown. The two variant
forms T and F take only htrue codei and hfalse codei, respectively. Here, the star also
shows that this function is expandable. With some minor exceptions, all conditional
functions in the expl3 modules should be defined in this way.
Variables, constants and so on are described in a similar manner:

\l_tmpa_tl A short piece of text will describe the variable: there is no syntax illustration in this case.
In some cases, the function is similar to one in LATEX 2ε or plain TEX. In these cases,
the text will include an extra “TEXhackers note” section:

\token_to_str:N ? \token_to_str:N htoken i

The normal description text.

TEXhackers note: Detail for the experienced TEX or LATEX 2ε programmer. In this case,
it would point out that this function is the TEX primitive \string.

Changes to behaviour When new functions are added to expl3, the date of first
inclusion is given in the documentation. Where the documented behaviour of a function
changes after it is first introduced, the date of the update will also be given. This means
that the programmer can be sure that any release of expl3 after the date given will contain
the function of interest with expected behaviour as described. Note that changes to code
internals, including bug fixes, are not recorded in this way unless they impact on the
expected behaviour.

3 Formal language conventions which apply generally

As this is a formal reference guide for LATEX3 programming, the descriptions of functions
are intended to be reasonably “complete”. However, there is also a need to avoid repeti-
tion. Formal ideas which apply to general classes of function are therefore summarised
here.
For tests which have a TF argument specification, the test if evaluated to give a
logically TRUE or FALSE result. Depending on this result, either the htrue codei or the
hfalse codei will be left in the input stream. In the case where the test is expandable,
and a predicate (_p) variant is available, the logical value determined by the test is left
in the input stream: this will typically be part of a larger logical construct.

5
4 TEX concepts not supported by LATEX3
The TEX concept of an “\outer” macro is not supported at all by LATEX3. As such, the
functions provided here may break when used on top of LATEX 2ε if \outer tokens are
used in the arguments.

6
 Part II
The l3bootstrap package
Bootstrap code
1 Using the LATEX3 modules
The modules documented in source3 are designed to be used on top of LATEX 2ε and
are loaded all as one with the usual \usepackage{expl3} or \RequirePackage{expl3}
instructions. These modules will also form the basis of the LATEX3 format, but work in
this area is incomplete and not included in this documentation at present.
As the modules use a coding syntax different from standard LATEX 2ε it provides a
few functions for setting it up.

\ExplSyntaxOn \ExplSyntaxOn hcode i \ExplSyntaxOff

\ExplSyntaxOff
The \ExplSyntaxOn function switches to a category code régime in which spaces are
Updated: 2011-08-13 ignored and in which the colon (:) and underscore (_) are treated as “letters”, thus
allowing access to the names of code functions and variables. Within this environment,
~ is used to input a space. The \ExplSyntaxOff reverts to the document category code
régime.

\ProvidesExplPackage \RequirePackage{expl3}
\ProvidesExplClass \ProvidesExplPackage {hpackage i} {hdate i} {hversion i} {hdescription i}
\ProvidesExplFile These functions act broadly in the same way as the LATEX 2ε kernel functions \ProvidesPackage,
\ProvidesClass and \ProvidesFile. However, they also implicitly switch \ExplSyntaxOn
for the remainder of the code with the file. At the end of the file, \ExplSyntaxOff will
be called to reverse this. (This is the same concept as LATEX 2ε provides in turning on
\makeatletter within package and class code.)

\GetIdInfo \RequirePackage{l3bootstrap}
\GetIdInfo $Id: hSVN info field i $ {hdescription i}
Updated: 2012-06-04
Extracts all information from a SVN field. Spaces are not ignored in these fields. The in-
formation pieces are stored in separate control sequences with \ExplFileName for the part
of the file name leading up to the period, \ExplFileDate for date, \ExplFileVersion
for version and \ExplFileDescription for the description.
To summarize: Every single package using this syntax should identify itself using
one of the above methods. Special care is taken so that every package or class file loaded
with \RequirePackage or alike are loaded with usual LATEX 2ε category codes and the
LATEX3 category code scheme is reloaded when needed afterwards. See implementation
for details. If you use the \GetIdInfo command you can use the information when
loading a package with
\ProvidesExplPackage{\ExplFileName}
{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}

7
 1.1 Internal functions and variables

\l__kernel_expl_bool A boolean which records the current code syntax status: true if currently inside a code
environment. This variable should only be set by \ExplSyntaxOn/\ExplSyntaxOff.

8
 Part III
The l3names package
Namespace for primitives
1 Setting up the LATEX3 programming language
This module is at the core of the LATEX3 programming language. It performs the following
tasks:
• defines new names for all TEX primitives;
• switches to the category code régime for programming;

• provides support settings for building the code as a TEX format.

This module is entirely dedicated to primitives, which should not be used directly
within LATEX3 code (outside of “kernel-level” code). As such, the primitives are not
documented here: The TEXbook, TEX by Topic and the manuals for pdfTEX, XETEX and
LuaTEX should be consulted for details of the primitives. These are named based on the
engine which first introduced them:
\tex_... Introduced by TEX itself;
\etex_... Introduced by the ε-TEX extensions;
\pdftex_... Introduced by pdfTEX;

\xetex_... Introduced by XETEX;

\luatex_... Introduced by LuaTEX.

9
 Part IV
The l3basics package
Basic definitions
As the name suggest this package holds some basic definitions which are needed by most
or all other packages in this set.
Here we describe those functions that are used all over the place. With that we mean
functions dealing with the construction and testing of control sequences. Furthermore
the basic parts of conditional processing are covered; conditional processing dealing with
specific data types is described in the modules specific for the respective data types.

1 No operation functions

\prg_do_nothing: ? \prg_do_nothing:
An expandable function which does nothing at all: leaves nothing in the input stream
after a single expansion.

\scan_stop: \scan_stop:
A non-expandable function which does nothing. Does not vanish on expansion but pro-
duces no typeset output.

2 Grouping material

\group_begin: \group_begin:
\group_end: \group_end:
These functions begin and end a group for definition purposes. Assignments are local
to groups unless carried out in a global manner. (A small number of exceptions to this
rule will be noted as necessary elsewhere in this document.) Each \group_begin: must
be matched by a \group_end:, although this does not have to occur within the same
function. Indeed, it is often necessary to start a group within one function and finish it
within another, for example when seeking to use non-standard category codes.

\group_insert_after:N \group_insert_after:N htoken i

Adds htokeni to the list of htokensi to be inserted when the current group level ends. The
list of htokensi to be inserted will be empty at the beginning of a group: multiple appli-
cations of \group_insert_after:N may be used to build the inserted list one htokeni
at a time. The current group level may be closed by a \group_end: function or by a
token with category code 2 (close-group). The later will be a } if standard category codes
apply.

10
3 Control sequences and functions
As TEX is a macro language, creating new functions means creating macros. At point of
use, a function is replaced by the replacement text (“code”) in which each parameter in
the code (#1, #2, etc.) is replaced the appropriate arguments absorbed by the function.
In the following, hcodei is therefore used as a shorthand for “replacement text”.
Functions which are not “protected” will be fully expanded inside an x expansion.
In contrast, “protected” functions are not expanded within x expansions.

3.1 Defining functions

Functions can be created with no requirement that they are declared first (in contrast
to variables, which must always be declared). Declaring a function before setting up the
code means that the name chosen will be checked and an error raised if it is already in
use. The name of a function can be checked at the point of definition using the \cs_-
new... functions: this is recommended for all functions which are defined for the first
time.
There are three ways to define new functions. All classes define a function to ex-
pand to the substitution text. Within the substitution text the actual parameters are
substituted for the formal parameters (#1, #2, . . . ).

new Create a new function with the new scope, such as \cs_new:Npn. The definition is
global and will result in an error if it is already defined.
set Create a new function with the set scope, such as \cs_set:Npn. The definition is
restricted to the current TEX group and will not result in an error if the function
is already defined.

gset Create a new function with the gset scope, such as \cs_gset:Npn. The definition
is global and will not result in an error if the function is already defined.
Within each set of scope there are different ways to define a function. The differences
depend on restrictions on the actual parameters and the expandability of the resulting
function.

nopar Create a new function with the nopar restriction, such as \cs_set_nopar:Npn.
The parameter may not contain \par tokens.
protected Create a new function with the protected restriction, such as \cs_set_-
protected:Npn. The parameter may contain \par tokens but the function will not
expand within an x-type expansion.
Finally, the functions in Subsections 3.2 and 3.3 are primarily meant to define base
functions only. Base functions can only have the following argument specifiers:
N and n No manipulation.

T and F Functionally equivalent to n (you are actually encouraged to use the family of
\prg_new_conditional: functions described in Section 1).

11
 p and w These are special cases.
The \cs_new: functions below (and friends) do not stop you from using other argu-
ment specifiers in your function names, but they do not handle expansion for you. You
should define the base function and then use \cs_generate_variant:Nn to generate
custom variants as described in Section 2.

3.2 Defining new functions using parameter text

\cs_new:Npn \cs_new:Npn hfunction i hparameters i {hcode i}

\cs_new:(cpn|Npx|cpx)
Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
definition is global and an error will result if the hfunctioni is already defined.

\cs_new_nopar:Npn \cs_new_nopar:Npn hfunction i hparameters i {hcode i}

\cs_new_nopar:(cpn|Npx|cpx)
Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When the
hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The definition
is global and an error will result if the hfunctioni is already defined.

\cs_new_protected:Npn \cs_new_protected:Npn hfunction i hparameters i {hcode i}

\cs_new_protected:(cpn|Npx|cpx)

Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
hfunctioni will not expand within an x-type argument. The definition is global and an
error will result if the hfunctioni is already defined.

\cs_new_protected_nopar:Npn \cs_new_protected_nopar:Npn hfunction i hparameters i {hcode i}

\cs_new_protected_nopar:(cpn|Npx|cpx)

Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When the
hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The hfunctioni
will not expand within an x-type argument. The definition is global and an error will
result if the hfunctioni is already defined.

\cs_set:Npn \cs_set:Npn hfunction i hparameters i {hcode i}

\cs_set:(cpn|Npx|cpx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
assignment of a meaning to the hfunctioni is restricted to the current TEX group level.

12
 \cs_set_nopar:Npn \cs_set_nopar:Npn hfunction i hparameters i {hcode i}
\cs_set_nopar:(cpn|Npx|cpx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When the
hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The assignment
of a meaning to the hfunctioni is restricted to the current TEX group level.

\cs_set_protected:Npn \cs_set_protected:Npn hfunction i hparameters i {hcode i}

\cs_set_protected:(cpn|Npx|cpx)

Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
assignment of a meaning to the hfunctioni is restricted to the current TEX group level.
The hfunctioni will not expand within an x-type argument.

\cs_set_protected_nopar:Npn \cs_set_protected_nopar:Npn hfunction i hparameters i {hcode i}

\cs_set_protected_nopar:(cpn|Npx|cpx)

Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When
the hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The as-
signment of a meaning to the hfunctioni is restricted to the current TEX group level. The
hfunctioni will not expand within an x-type argument.

\cs_gset:Npn \cs_gset:Npn hfunction i hparameters i {hcode i}

\cs_gset:(cpn|Npx|cpx)
Globally sets hfunctioni to expand to hcodei as replacement text. Within the hcodei,
the hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
assignment of a meaning to the hfunctioni is not restricted to the current TEX group
level: the assignment is global.

\cs_gset_nopar:Npn \cs_gset_nopar:Npn hfunction i hparameters i {hcode i}

\cs_gset_nopar:(cpn|Npx|cpx)
Globally sets hfunctioni to expand to hcodei as replacement text. Within the hcodei,
the hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function.
When the hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The
assignment of a meaning to the hfunctioni is not restricted to the current TEX group
level: the assignment is global.

\cs_gset_protected:Npn \cs_gset_protected:Npn hfunction i hparameters i {hcode i}

\cs_gset_protected:(cpn|Npx|cpx)

Globally sets hfunctioni to expand to hcodei as replacement text. Within the hcodei,
the hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
assignment of a meaning to the hfunctioni is not restricted to the current TEX group level:
the assignment is global. The hfunctioni will not expand within an x-type argument.

13
 \cs_gset_protected_nopar:Npn \cs_gset_protected_nopar:Npn hfunction i hparameters i {hcode i}
\cs_gset_protected_nopar:(cpn|Npx|cpx)

Globally sets hfunctioni to expand to hcodei as replacement text. Within the hcodei,
the hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function.
When the hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The
assignment of a meaning to the hfunctioni is not restricted to the current TEX group level:
the assignment is global. The hfunctioni will not expand within an x-type argument.

3.3 Defining new functions using the signature

\cs_new:Nn \cs_new:Nn hfunction i {hcode i}

\cs_new:(cn|Nx|cx)
Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
number of hparametersi is detected automatically from the function signature. These
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
definition is global and an error will result if the hfunctioni is already defined.

\cs_new_nopar:Nn \cs_new_nopar:Nn hfunction i {hcode i}

\cs_new_nopar:(cn|Nx|cx)
Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
number of hparametersi is detected automatically from the function signature. These
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When the
hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The definition
is global and an error will result if the hfunctioni is already defined.

\cs_new_protected:Nn \cs_new_protected:Nn hfunction i {hcode i}

\cs_new_protected:(cn|Nx|cx)
Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
number of hparametersi is detected automatically from the function signature. These
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. The
hfunctioni will not expand within an x-type argument. The definition is global and an
error will result if the hfunctioni is already defined.

\cs_new_protected_nopar:Nn \cs_new_protected_nopar:Nn hfunction i {hcode i}

\cs_new_protected_nopar:(cn|Nx|cx)

Creates hfunctioni to expand to hcodei as replacement text. Within the hcodei, the
number of hparametersi is detected automatically from the function signature. These
hparametersi (#1, #2, etc.) will be replaced by those absorbed by the function. When the
hfunctioni is used the hparametersi absorbed cannot contain \par tokens. The hfunctioni
will not expand within an x-type argument. The definition is global and an error will
result if the hfunctioni is already defined.

14
 \cs_set:Nn \cs_set:Nn hfunction i {hcode i}
\cs_set:(cn|Nx|cx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. The assignment of a
meaning to the hfunctioni is restricted to the current TEX group level.

\cs_set_nopar:Nn \cs_set_nopar:Nn hfunction i {hcode i}

\cs_set_nopar:(cn|Nx|cx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. When the hfunctioni
is used the hparametersi absorbed cannot contain \par tokens. The assignment of a
meaning to the hfunctioni is restricted to the current TEX group level.

\cs_set_protected:Nn \cs_set_protected:Nn hfunction i {hcode i}

\cs_set_protected:(cn|Nx|cx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. The hfunctioni will
not expand within an x-type argument. The assignment of a meaning to the hfunctioni
is restricted to the current TEX group level.

\cs_set_protected_nopar:Nn \cs_set_protected_nopar:Nn hfunction i {hcode i}

\cs_set_protected_nopar:(cn|Nx|cx)

Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. When the hfunctioni
is used the hparametersi absorbed cannot contain \par tokens. The hfunctioni will not
expand within an x-type argument. The assignment of a meaning to the hfunctioni is
restricted to the current TEX group level.

\cs_gset:Nn \cs_gset:Nn hfunction i {hcode i}

\cs_gset:(cn|Nx|cx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. The assignment of a
meaning to the hfunctioni is global.

\cs_gset_nopar:Nn \cs_gset_nopar:Nn hfunction i {hcode i}

\cs_gset_nopar:(cn|Nx|cx)
Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. When the hfunctioni
is used the hparametersi absorbed cannot contain \par tokens. The assignment of a
meaning to the hfunctioni is global.

15
\cs_gset_protected:Nn \cs_gset_protected:Nn hfunction i {hcode i}
\cs_gset_protected:(cn|Nx|cx)

Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. The hfunctioni will
not expand within an x-type argument. The assignment of a meaning to the hfunctioni
is global.

\cs_gset_protected_nopar:Nn \cs_gset_protected_nopar:Nn hfunction i {hcode i}

\cs_gset_protected_nopar:(cn|Nx|cx)

Sets hfunctioni to expand to hcodei as replacement text. Within the hcodei, the number of
hparametersi is detected automatically from the function signature. These hparametersi
(#1, #2, etc.) will be replaced by those absorbed by the function. When the hfunctioni
is used the hparametersi absorbed cannot contain \par tokens. The hfunctioni will not
expand within an x-type argument. The assignment of a meaning to the hfunctioni is
global.

\cs_generate_from_arg_count:NNnn \cs_generate_from_arg_count:NNnn hfunction i hcreator i hnumber i

\cs_generate_from_arg_count:(cNnn|Ncnn) hcode i
Updated: 2012-01-14

Uses the hcreatori function (which should have signature Npn, for example \cs_new:Npn)
to define a hfunctioni which takes hnumberi arguments and has hcodei as replacement
text. The hnumberi of arguments is an integer expression, evaluated as detailed for
\int_eval:n.

3.4 Copying control sequences

Control sequences (not just functions as defined above) can be set to have the same
meaning using the functions described here. Making two control sequences equivalent
means that the second control sequence is a copy of the first (rather than a pointer to
it). Thus the old and new control sequence are not tied together: changes to one are not
reflected in the other.
In the following text “cs” is used as an abbreviation for “control sequence”.

\cs_new_eq:NN \cs_new_eq:NN hcs1 i hcs2 i

\cs_new_eq:(Nc|cN|cc) \cs_new_eq:NN hcs1 i htoken i
Globally creates hcontrol sequence1 i and sets it to have the same meaning as hcontrol
sequence2 i or htokeni. The second control sequence may subsequently be altered without
affecting the copy.

16
 \cs_set_eq:NN \cs_set_eq:NN hcs1 i hcs2 i
\cs_set_eq:(Nc|cN|cc) \cs_set_eq:NN hcs1 i htoken i
Sets hcontrol sequence1 i to have the same meaning as hcontrol sequence2 i (or htokeni).
The second control sequence may subsequently be altered without affecting the copy.
The assignment of a meaning to the hcontrol sequence1 i is restricted to the current TEX
group level.

\cs_gset_eq:NN \cs_gset_eq:NN hcs1 i hcs2 i

\cs_gset_eq:(Nc|cN|cc) \cs_gset_eq:NN hcs1 i htoken i
Globally sets hcontrol sequence1 i to have the same meaning as hcontrol sequence2 i (or
htokeni). The second control sequence may subsequently be altered without affecting the
copy. The assignment of a meaning to the hcontrol sequence1 i is not restricted to the
current TEX group level: the assignment is global.

3.5 Deleting control sequences

There are occasions where control sequences need to be deleted. This is handled in a
very simple manner.

\cs_undefine:N \cs_undefine:N hcontrol sequence i

\cs_undefine:c
Sets hcontrol sequencei to be globally undefined.
Updated: 2011-09-15

3.6 Showing control sequences

\cs_meaning:N ? \cs_meaning:N hcontrol sequence i

\cs_meaning:c ?
This function expands to the meaning of the hcontrol sequencei control sequence. This
Updated: 2011-12-22 will show the hreplacement texti for a macro.

TEXhackers note: This is TEX’s \meaning primitive. The c variant correctly reports
undefined arguments.

\cs_show:N \cs_show:N hcontrol sequence i

\cs_show:c
Displays the definition of the hcontrol sequencei on the terminal.
Updated: 2012-09-09
TEXhackers note: This is similar to the TEX primitive \show, wrapped to a fixed number
of characters per line.

17
 3.7 Converting to and from control sequences

\use:c ? \use:c {hcontrol sequence name i}

Converts the given hcontrol sequence namei into a single control sequence token. This
process requires two expansions. The content for hcontrol sequence namei may be literal
material or from other expandable functions. The hcontrol sequence namei must, when
fully expanded, consist of character tokens which are not active: typically, they will be
of category code 10 (space), 11 (letter) or 12 (other), or a mixture of these.
As an example of the \use:c function, both
\use:c { a b c }
and
\tl_new:N \l_my_tl
\tl_set:Nn \l_my_tl { a b c }
\use:c { \tl_use:N \l_my_tl }
would be equivalent to
\abc
after two expansions of \use:c.

\cs_if_exist_use:N ? \cs_if_exist_use:N hcontrol sequence i

\cs_if_exist_use:c ?
Tests whether the hcontrol sequencei is currently defined (whether as a function or another
New: 2012-11-10 control sequence type), and if it does inserts the hcontrol sequencei into the input stream.

\cs_if_exist_use:NTF ? \cs_if_exist_use:NTF hcontrol sequence i {htrue code i} {hfalse code i}

\cs_if_exist_use:cTF ?
Tests whether the hcontrol sequencei is currently defined (whether as a function or another
New: 2012-11-10 control sequence type), and if it does inserts the hcontrol sequencei into the input stream
followed by the htrue codei.

\cs:w ? \cs:w hcontrol sequence name i \cs_end:

\cs_end: ?
Converts the given hcontrol sequence namei into a single control sequence token. This
process requires one expansion. The content for hcontrol sequence namei may be literal
material or from other expandable functions. The hcontrol sequence namei must, when
fully expanded, consist of character tokens which are not active: typically, they will be
of category code 10 (space), 11 (letter) or 12 (other), or a mixture of these.

TEXhackers note: These are the TEX primitives \csname and \endcsname.

As an example of the \cs:w and \cs_end: functions, both

\cs:w a b c \cs_end:
and

18
 \tl_new:N \l_my_tl
\tl_set:Nn \l_my_tl { a b c }
\cs:w \tl_use:N \l_my_tl \cs_end:
would be equivalent to

\abc
after one expansion of \cs:w.

\cs_to_str:N ? \cs_to_str:N hcontrol sequence i

Converts the given hcontrol sequencei into a series of characters with category code 12
(other), except spaces, of category code 10. The sequence will not include the current
escape token, cf. \token_to_str:N. Full expansion of this function requires exactly 2
expansion steps, and so an x-type expansion, or two o-type expansions will be required
to convert the hcontrol sequencei to a sequence of characters in the input stream. In most
cases, an f-expansion will be correct as well, but this loses a space at the start of the
result.

4 Using or removing tokens and arguments

Tokens in the input can be read and used or read and discarded. If one or more tokens
are wrapped in braces then in absorbing them the outer set will be removed. At the same
time, the category code of each token is set when the token is read by a function (if it is
read more than once, the category code is determined by the the situation in force when
first function absorbs the token).

\use:n ? \use:n {hgroup1 i}

\use:(nn|nnn|nnnn) ? \use:nn {hgroup1 i} {hgroup2 i}
\use:nnn {hgroup1 i} {hgroup2 i} {hgroup3 i}
\use:nnnn {hgroup1 i} {hgroup2 i} {hgroup3 i} {hgroup4 i}
As illustrated, these functions will absorb between one and four arguments, as indicated
by the argument specifier. The braces surrounding each argument will be removed leaving
the remaining tokens in the input stream. The category code of these tokens will also be
fixed by this process (if it has not already been by some other absorption). All of these
functions require only a single expansion to operate, so that one expansion of
\use:nn { abc } { { def } }
will result in the input stream containing

abc { def }
i.e. only the outer braces will be removed.

19
 \use_i:nn ? \use_i:nn {harg1 i} {harg2 i}
\use_ii:nn ?
These functions absorb two arguments from the input stream. The function \use_i:nn
discards the second argument, and leaves the content of the first argument in the input
stream. \use_ii:nn discards the first argument and leaves the content of the second
argument in the input stream. The category code of these tokens will also be fixed (if
it has not already been by some other absorption). A single expansion is needed for the
functions to take effect.

\use_i:nnn ? \use_i:nnn {harg1 i} {harg2 i} {harg3 i}

\use_ii:nnn ?
These functions absorb three arguments from the input stream. The function \use_i:nnn
\use_iii:nnn ?
discards the second and third arguments, and leaves the content of the first argument in
the input stream. \use_ii:nnn and \use_iii:nnn work similarly, leaving the content of
second or third arguments in the input stream, respectively. The category code of these
tokens will also be fixed (if it has not already been by some other absorption). A single
expansion is needed for the functions to take effect.

\use_i:nnnn ? \use_i:nnnn {harg1 i} {harg2 i} {harg3 i} {harg4 i}

\use_ii:nnnn ?
These functions absorb four arguments from the input stream. The function \use_-
\use_iii:nnnn ?
\use_iv:nnnn ?
i:nnnn discards the second, third and fourth arguments, and leaves the content of the
first argument in the input stream. \use_ii:nnnn, \use_iii:nnnn and \use_iv:nnnn
work similarly, leaving the content of second, third or fourth arguments in the input
stream, respectively. The category code of these tokens will also be fixed (if it has not
already been by some other absorption). A single expansion is needed for the functions
to take effect.

\use_i_ii:nnn ? \use_i_ii:nnn {harg1 i} {harg2 i} {harg3 i}

This functions will absorb three arguments and leave the content of the first and second
in the input stream. The category code of these tokens will also be fixed (if it has not
already been by some other absorption). A single expansion is needed for the functions
to take effect. An example:
\use_i_ii:nnn { abc } { { def } } { ghi }
will result in the input stream containing

abc { def }
i.e. the outer braces will be removed and the third group will be removed.

\use_none:n ? \use_none:n {hgroup1 i}

\use_none:(nn|nnn|nnnn|nnnnn|nnnnnn|nnnnnnn|nnnnnnnn|nnnnnnnnn) ?

These functions absorb between one and nine groups from the input stream, leaving
nothing on the resulting input stream. These functions work after a single expansion.
One or more of the n arguments may be an unbraced single token (i.e. an N argument).

20
 \use:x \use:x {hexpandable tokens i}
Updated: 2011-12-31 Fully expands the hexpandable tokensi and inserts the result into the input stream at the
current location. Any hash characters (#) in the argument must be doubled.

4.1 Selecting tokens from delimited arguments

A different kind of function for selecting tokens from the token stream are those that use
delimited arguments.

\use_none_delimit_by_q_nil:w ? \use_none_delimit_by_q_nil:w hbalanced text i \q_nil

\use_none_delimit_by_q_stop:w ? \use_none_delimit_by_q_stop:w hbalanced text i \q_stop
\use_none_delimit_by_q_recursion_stop:w ? \use_none_delimit_by_q_recursion_stop:w hbalanced text i
\q_recursion_stop
Absorb the hbalanced texti form the input stream delimited by the marker given in the
function name, leaving nothing in the input stream.

\use_i_delimit_by_q_nil:nw ? \use_i_delimit_by_q_nil:nw {hinserted tokens i} hbalanced text i

\use_i_delimit_by_q_stop:nw ? \q_nil
\use_i_delimit_by_q_recursion_stop:nw ? \use_i_delimit_by_q_stop:nw {hinserted tokens i} hbalanced
text i \q_stop
\use_i_delimit_by_q_recursion_stop:nw {hinserted tokens i}
hbalanced text i \q_recursion_stop
Absorb the hbalanced texti form the input stream delimited by the marker given in the
function name, leaving hinserted tokensi in the input stream for further processing.

5 Predicates and conditionals

LATEX3 has three concepts for conditional flow processing:
Branching conditionals Functions that carry out a test and then execute, depending
on its result, either the code supplied as the htrue codei or the hfalse codei. These
arguments are denoted with T and F, respectively. An example would be

\cs_if_free:cTF {abc} {htrue codei} {hfalse codei}

a function that will turn the first argument into a control sequence (since it’s marked
as c) then checks whether this control sequence is still free and then depending on
the result carry out the code in the second argument (true case) or in the third
argument (false case).
These type of functions are known as “conditionals”; whenever a TF function is
defined it will usually be accompanied by T and F functions as well. These are
provided for convenience when the branch only needs to go a single way. Package
writers are free to choose which types to define but the kernel definitions will always
provide all three versions.

21
 Important to note is that these branching conditionals with htrue codei and/or
hfalse codei are always defined in a way that the code of the chosen alternative can
operate on following tokens in the input stream.
These conditional functions may or may not be fully expandable, but if they are
expandable they will be accompanied by a “predicate” for the same test as described
below.
Predicates “Predicates” are functions that return a special type of boolean value which
can be tested by the boolean expression parser. All functions of this type are
expandable and have names that end with _p in the description part. For example,
\cs_if_free_p:N

would be a predicate function for the same type of test as the conditional described
above. It would return “true” if its argument (a single token denoted by N) is still
free for definition. It would be used in constructions like
\bool_if:nTF {
\cs_if_free_p:N \l_tmpz_tl || \cs_if_free_p:N \g_tmpz_tl
} {htrue codei} {hfalse codei}
For each predicate defined, a “branching conditional” will also exist that behaves
like a conditional described above.
Primitive conditionals There is a third variety of conditional, which is the original
concept used in plain TEX and LATEX 2ε . Their use is discouraged in expl3 (although
still used in low-level definitions) because they are more fragile and in many cases
require more expansion control (hence more code) than the two types of conditionals
described above.

\c_true_bool Constants that represent true and false, respectively. Used to implement predicates.
\c_false_bool

5.1 Tests on control sequences

\cs_if_eq_p:NN ? \cs_if_eq_p:NN {hcs1 i} {hcs2 i}

\cs_if_eq:NNTF ? \cs_if_eq:NNTF {hcs1 i} {hcs2 i} {htrue code i} {hfalse code i}
Compares the definition of two hcontrol sequencesi and is logically true the same, i.e. if
they have exactly the same definition when examined with \cs_show:N.

\cs_if_exist_p:N ? \cs_if_exist_p:N hcontrol sequence i

\cs_if_exist_p:c ? \cs_if_exist:NTF hcontrol sequence i {htrue code i} {hfalse code i}
\cs_if_exist:NTF ? Tests whether the hcontrol sequencei is currently defined (whether as a function or another
\cs_if_exist:cTF ?
control sequence type). Any valid definition of hcontrol sequencei will evaluate as true.

22
 \cs_if_free_p:N ? \cs_if_free_p:N hcontrol sequence i
\cs_if_free_p:c ? \cs_if_free:NTF hcontrol sequence i {htrue code i} {hfalse code i}
\cs_if_free:NTF ? Tests whether the hcontrol sequencei is currently free to be defined. This test will be
\cs_if_free:cTF ?
false if the hcontrol sequencei currently exists (as defined by \cs_if_exist:N).

5.2 Engine-specific conditionals

\luatex_if_engine_p: ? \luatex_if_engine:TF {htrue code i} {hfalse code i}

\luatex_if_engine:TF ?
Detects is the document is being compiled using LuaTEX.
Updated: 2011-09-06

\pdftex_if_engine_p: ? \pdftex_if_engine:TF {htrue code i} {hfalse code i}

\pdftex_if_engine:TF ?
Detects is the document is being compiled using pdfTEX.
Updated: 2011-09-06

\xetex_if_engine_p: ? \xetex_if_engine:TF {htrue code i} {hfalse code i}

\xetex_if_engine:TF ?
Detects is the document is being compiled using XETEX.
Updated: 2011-09-06

5.3 Primitive conditionals

The ε-TEX engine itself provides many different conditionals. Some expand whatever
comes after them and others don’t. Hence the names for these underlying functions will
often contain a :w part but higher level functions are often available. See for instance
\int_compare_p:nNn which is a wrapper for \if_int_compare:w.
Certain conditionals deal with specific data types like boxes and fonts and are de-
scribed there. The ones described below are either the universal conditionals or deal with
control sequences. We will prefix primitive conditionals with \if_.

\if_true: ? \if_true: htrue code i \else: hfalse code i \fi:

\if_false: ? \if_false: htrue code i \else: hfalse code i \fi:
\or: ? \reverse_if:N hprimitive conditional i
\else: ? \if_true: always executes htrue codei, while \if_false: always executes hfalse codei.
\fi: ?
\reverse_if:N reverses any two-way primitive conditional. \else: and \fi: delimit
\reverse_if:N ?
the branches of the conditional. \or: is used in case switches, see l3int for more.

TEXhackers note: These are equivalent to their corresponding TEX primitive conditionals;
\reverse_if:N is ε-TEX’s \unless.

23
 \if_meaning:w ? \if_meaning:w harg1 i harg2 i htrue code i \else: hfalse code i \fi:
\if_meaning:w executes htrue codei when harg1 i and harg2 i are the same, otherwise it
executes hfalse codei. harg1 i and harg2 i could be functions, variables, tokens; in all cases
the unexpanded definitions are compared.

TEXhackers note: This is TEX’s \ifx.

\if:w ? \if:w htoken1 i htoken2 i htrue code i \else: hfalse code i \fi:
\if_charcode:w ? \if_catcode:w htoken1 i htoken2 i htrue code i \else: hfalse code i \fi:
\if_catcode:w ? These conditionals will expand any following tokens until two unexpandable tokens are
left. If you wish to prevent this expansion, prefix the token in question with \exp_not:N.
\if_catcode:w tests if the category codes of the two tokens are the same whereas \if:w
tests if the character codes are identical. \if_charcode:w is an alternative name for
\if:w.

\if_cs_exist:N ? \if_cs_exist:N hcs i htrue code i \else: hfalse code i \fi:

\if_cs_exist:w ? \if_cs_exist:w htokens i \cs_end: htrue code i \else: hfalse code i \fi:
Check if hcsi appears in the hash table or if the control sequence that can be formed
from htokensi appears in the hash table. The latter function does not turn the control
sequence in question into \scan_stop:! This can be useful when dealing with control
sequences which cannot be entered as a single token.

\if_mode_horizontal: ? \if_mode_horizontal: htrue code i \else: hfalse code i \fi:

\if_mode_vertical: ?
Execute htrue codei if currently in horizontal mode, otherwise execute hfalse codei. Sim-
\if_mode_math: ?
\if_mode_inner: ? ilar for the other functions.

6 Internal kernel functions

\__chk_if_exist_cs:N \__chk_if_exist_cs:N hcs i

\__chk_if_exist_cs:c
This function checks that hcsi exists according to the criteria for \cs_if_exist_p:N, and
if not raises a kernel-level error.

\__chk_if_free_cs:N \__chk_if_free_cs:N hcs i

\__chk_if_free_cs:c
This function checks that hcsi is free according to the criteria for \cs_if_free_p:N, and
if not raises a kernel-level error.

\__chk_if_exist_var:N \__chk_if_exist_var:N hvar i

This function checks that hvari is defined according to the criteria for \cs_if_free_p:N,
and if not raises a kernel-level error. This function is only created if the package option
check-declarations is active.

24
\__cs_count_signature:N ? \__cs_count_signature:N hfunction i
\__cs_count_signature:c ?
Splits the hfunctioni into the hnamei (i.e. the part before the colon) and the hsignaturei
(i.e. after the colon). The hnumberi of tokens in the hsignaturei is then left in the input
stream. If there was no hsignaturei then the result is the marker value −1.

\__cs_split_function:NN ? \__cs_split_function:NN hfunction i hprocessor i

Splits the hfunctioni into the hnamei (i.e. the part before the colon) and the hsignaturei
(i.e. after the colon). This information is then placed in the input stream after the
hprocessori function in three parts: the hnamei, the hsignaturei and a logic token indi-
cating if a colon was found (to differentiate variables from function names). The hnamei
will not include the escape character, and both the hnamei and hsignaturei are made
up of tokens with category code 12 (other). The hprocessori should be a function with
argument specification :nnN (plus any trailing arguments needed).

\__cs_get_function_name:N ? \__cs_get_function_name:N hfunction i

Splits the hfunctioni into the hnamei (i.e. the part before the colon) and the hsignaturei
(i.e. after the colon). The hnamei is then left in the input stream without the escape
character present made up of tokens with category code 12 (other).

\__cs_get_function_signature:N ? \__cs_get_function_signature:N hfunction i

Splits the hfunctioni into the hnamei (i.e. the part before the colon) and the hsignaturei
(i.e. after the colon). The hsignaturei is then left in the input stream made up of tokens
with category code 12 (other).

\__cs_tmp:w Function used for various short-term usages, for instance defining functions whose defini-
tion involves tokens which are hard to insert normally (spaces, characters with category
other).

\__kernel_register_show:N \__kernel_register_show:N hregister i

\__kernel_register_show:c
Used to show the contents of a TEX register at the terminal, formatted such that internal
parts of the mechanism are not visible.

\__prg_case_end:nw ? \__prg_case_end:nw {hcode i} htokens i \q_mark {htrue code i} \q_mark {hfalse code i}
\q_stop
Used to terminate case statements (\int_case:nnTF, etc.) by removing trailing htokensi
and the end marker \q_stop, inserting the hcodei for the successful case (if one is found)
and either the true code or false code for the over all outcome, as appropriate.

25
Part V
The l3expan package
Argument expansion
This module provides generic methods for expanding TEX arguments in a systematic
manner. The functions in this module all have prefix exp.
Not all possible variations are implemented for every base function. Instead only
those that are used within the LATEX3 kernel or otherwise seem to be of general interest
are implemented. Consult the module description to find out which functions are actually
defined. The next section explains how to define missing variants.

1 Defining new variants

The definition of variant forms for base functions may be necessary when writing new
functions or when applying a kernel function in a situation that we haven’t thought of
before.
Internally preprocessing of arguments is done with functions from the \exp_ mod-
ule. They all look alike, an example would be \exp_args:NNo. This function has three
arguments, the first and the second are a single tokens, while the third argument should
be given in braces. Applying \exp_args:NNo will expand the content of third argument
once before any expansion of the first and second arguments. If \seq_gpush:No was not
defined it could be coded in the following way:
\exp_args:NNo \seq_gpush:Nn
\g_file_name_stack
\l_tmpa_tl
In other words, the first argument to \exp_args:NNo is the base function and the other
arguments are preprocessed and then passed to this base function. In the example the
first argument to the base function should be a single token which is left unchanged
while the second argument is expanded once. From this example we can also see how the
variants are defined. They just expand into the appropriate \exp_ function followed by
the desired base function, e.g.
\cs_new_nopar:Npn \seq_gpush:No { \exp_args:NNo \seq_gpush:Nn }
Providing variants in this way in style files is uncritical as the \cs_new_nopar:Npn func-
tion will silently accept definitions whenever the new definition is identical to an already
given one. Therefore adding such definition to later releases of the kernel will not make
such style files obsolete.
The steps above may be automated by using the function \cs_generate_-
variant:Nn, described next.

26
 2 Methods for defining variants

\cs_generate_variant:Nn \cs_generate_variant:Nn hparent control sequence i {hvariant argument specifiers i}

Updated: 2013-07-09 This function is used to define argument-specifier variants of the hparent control sequencei
for LATEX3 code-level macros. The hparent control sequencei is first separated into the
hbase namei and horiginal argument specifieri. The comma-separated list of hvariant
argument specifiersi is then used to define variants of the horiginal argument specifieri
where these are not already defined. For each hvarianti given, a function is created which
will expand its arguments as detailed and pass them to the hparent control sequencei. So
for example
\cs_set:Npn \foo:Nn #1#2 { code here }
\cs_generate_variant:Nn \foo:Nn { c }

will create a new function \foo:cn which will expand its first argument into a control
sequence name and pass the result to \foo:Nn. Similarly
\cs_generate_variant:Nn \foo:Nn { NV , cV }
would generate the functions \foo:NV and \foo:cV in the same way. The \cs_-
generate_variant:Nn function can only be applied if the hparent control sequencei is
already defined. If the hparent control sequencei is protected then the new sequence will
also be protected. The hvarianti is created globally, as is any \exp_args:Nhvariant i
function needed to carry out the expansion.

3 Introducing the variants

The available internal functions for argument expansion come in two flavours, some of
them are faster then others. Therefore it is usually best to follow the following guidelines
when defining new functions that are supposed to come with variant forms:
• Arguments that might need expansion should come first in the list of arguments to
make processing faster.
• Arguments that should consist of single tokens should come first.
• Arguments that need full expansion (i.e., are denoted with x) should be avoided if
possible as they can not be processed expandably, i.e., functions of this type will
not work correctly in arguments that are themselves subject to x expansion.
• In general, unless in the last position, multi-token arguments n, f, and o will need
special processing which is not fast. Therefore it is best to use the optimized
functions, namely those that contain only N, c, V, and v, and, in the last position,
o, f, with possible trailing N or n, which are not expanded.

The V type returns the value of a register, which can be one of tl, num, int, skip,
dim, toks, or built-in TEX registers. The v type is the same except it first creates a

27
 control sequence out of its argument before returning the value. This recent addition to
the argument specifiers may shake things up a bit as most places where o is used will be
replaced by V. The documentation you are currently reading will therefore require a fair
bit of re-writing.
In general, the programmer should not need to be concerned with expansion control.
When simply using the content of a variable, functions with a V specifier should be used.
For those referred to by (cs)name, the v specifier is available for the same purpose. Only
when specific expansion steps are needed, such as when using delimited arguments, should
the lower-level functions with o specifiers be employed.
The f type is so special that it deserves an example. Let’s pretend we want to set
the control sequence whose name is given by b \l_tmpa_tl b equal to the list of tokens
\aaa a. Furthermore we want to store the execution of it in a htl vari. In this example
we assume \l_tmpa_tl contains the text string lur. The straightforward approach is
\tl_set:No \l_tmpb_tl { \tl_set:cn { b \l_tmpa_tl b } { \aaa a } }
Unfortunately this only puts \exp_args:Nc \tl_set:Nn {b \l_tmpa_tl b} { \aaa a }
into \l_tmpb_tl and not \tl_set:Nn \blurb { \aaa a } as we probably wanted. Us-
ing \tl_set:Nx is not an option as that will die horribly. Instead we can do a
\tl_set:Nf \l_tmpb_tl { \tl_set:cn { b \l_tmpa_tl b } { \aaa a } }
which puts the desired result in \l_tmpb_tl. It requires \tl_set:Nf to be defined as
\cs_set_nopar:Npn \tl_set:Nf { \exp_args:NNf \tl_set:Nn }
If you use this type of expansion in conditional processing then you should stick to using
TF type functions only as it does not try to finish any \if... \fi: itself!

4 Manipulating the first argument

These functions are described in detail: expansion of multiple tokens follows the same
rules but is described in a shorter fashion.

\exp_args:No ? \exp_args:No hfunction i {htokens i} ...

This function absorbs two arguments (the hfunctioni name and the htokensi). The
htokensi are expanded once, and the result is inserted in braces into the input stream af-
ter reinsertion of the hfunctioni. Thus the hfunctioni may take more than one argument:
all others will be left unchanged.

\exp_args:Nc ? \exp_args:Nc hfunction i {htokens i}

\exp_args:cc ?
This function absorbs two arguments (the hfunctioni name and the htokensi). The
htokensi are expanded until only characters remain, and are then turned into a con-
trol sequence. (An internal error will occur if such a conversion is not possible). The
result is inserted into the input stream after reinsertion of the hfunctioni. Thus the
hfunctioni may take more than one argument: all others will be left unchanged.
The :cc variant constructs the hfunctioni name in the same manner as described for
the htokensi.

28
 \exp_args:NV ? \exp_args:NV hfunction i hvariable i
This function absorbs two arguments (the names of the hfunctioni and the hvariablei).
The content of the hvariablei are recovered and placed inside braces into the input stream
after reinsertion of the hfunctioni. Thus the hfunctioni may take more than one argument:
all others will be left unchanged.

\exp_args:Nv ? \exp_args:Nv hfunction i {htokens i}

This function absorbs two arguments (the hfunctioni name and the htokensi). The
htokensi are expanded until only characters remain, and are then turned into a con-
trol sequence. (An internal error will occur if such a conversion is not possible). This
control sequence should be the name of a hvariablei. The content of the hvariablei are re-
covered and placed inside braces into the input stream after reinsertion of the hfunctioni.
Thus the hfunctioni may take more than one argument: all others will be left unchanged.

\exp_args:Nf ? \exp_args:Nf hfunction i {htokens i}

This function absorbs two arguments (the hfunctioni name and the htokensi). The
htokensi are fully expanded until the first non-expandable token or space is found, and
the result is inserted in braces into the input stream after reinsertion of the hfunctioni.
Thus the hfunctioni may take more than one argument: all others will be left unchanged.

\exp_args:Nx \exp_args:Nx hfunction i {htokens i}

This function absorbs two arguments (the hfunctioni name and the htokensi) and ex-
haustively expands the htokensi second. The result is inserted in braces into the input
stream after reinsertion of the hfunctioni. Thus the hfunctioni may take more than one
argument: all others will be left unchanged.

5 Manipulating two arguments

\exp_args:NNo ? \exp_args:NNc htoken1 i htoken2 i {htokens i}

\exp_args:(NNc|NNv|NNV|NNf|Nco|Ncf|Ncc|NVV) ?

These optimized functions absorb three arguments and expand the second and third as
detailed by their argument specifier. The first argument of the function is then the next
item on the input stream, followed by the expansion of the second and third arguments.

\exp_args:Nno ? \exp_args:Noo htoken i {htokens1 i} {htokens2 i}

\exp_args:(NnV|Nnf|Noo|Nof|Noc|Nff|Nfo|Nnc) ?
Updated: 2012-01-14

These functions absorb three arguments and expand the second and third as detailed by
their argument specifier. The first argument of the function is then the next item on
the input stream, followed by the expansion of the second and third arguments. These
functions need special (slower) processing.

29
\exp_args:NNx \exp_args:NNx htoken1 i htoken2 i {htokens i}
\exp_args:(Nnx|Ncx|Nox|Nxo|Nxx)

These functions absorb three arguments and expand the second and third as detailed by
their argument specifier. The first argument of the function is then the next item on
the input stream, followed by the expansion of the second and third arguments. These
functions are not expandable.

6 Manipulating three arguments

\exp_args:NNNo ? \exp_args:NNNo htoken1 i htoken2 i htoken3 i {htokens i}

\exp_args:(NNNV|Nccc|NcNc|NcNo|Ncco) ?

These optimized functions absorb four arguments and expand the second, third and
fourth as detailed by their argument specifier. The first argument of the function is then
the next item on the input stream, followed by the expansion of the second argument,
etc.

\exp_args:NNoo ? \exp_args:NNNo htoken1 i htoken2 i htoken3 i {htokens i}

\exp_args:(NNno|Nnno|Nnnc|Nooo) ?

These functions absorb four arguments and expand the second, third and fourth as de-
tailed by their argument specifier. The first argument of the function is then the next
item on the input stream, followed by the expansion of the second argument, etc. These
functions need special (slower) processing.

\exp_args:NNnx \exp_args:NNnx htoken1 i htoken2 i {htokens1 i} {htokens2 i}

\exp_args:(NNox|Nnnx|Nnox|Noox|Ncnx|Nccx)

These functions absorb four arguments and expand the second, third and fourth as de-
tailed by their argument specifier. The first argument of the function is then the next
item on the input stream, followed by the expansion of the second argument, etc.

30
 7 Unbraced expansion

\exp_last_unbraced:Nf ? \exp_last_unbraced:Nno htoken i

\exp_last_unbraced:(NV|No|Nv|Nco|NcV|NNV|NNo|Nno|Noo|Nfo|NNNV|NNNo|NnNo) ? htokens1 i htokens2 i
Updated: 2012-02-12

These functions absorb the number of arguments given by their specification, carry out
the expansion indicated and leave the results in the input stream, with the last argument
not surrounded by the usual braces. Of these, the :Nno, :Noo, and :Nfo variants need
special (slower) processing.

TEXhackers note: As an optimization, the last argument is unbraced by some of those

functions before expansion. This can cause problems if the argument is empty: for instance,
\exp_last_unbraced:Nf \mypkg_foo:w { } \q_stop leads to an infinite loop, as the quark is
f-expanded.

\exp_last_unbraced:Nx \exp_last_unbraced:Nx hfunction i {htokens i}

This functions fully expands the htokensi and leaves the result in the input stream after
reinsertion of hfunctioni. This function is not expandable.

\exp_last_two_unbraced:Noo ? \exp_last_two_unbraced:Noo htoken i htokens1 i {htokens2 i}

This function absorbs three arguments and expand the second and third once. The first
argument of the function is then the next item on the input stream, followed by the
expansion of the second and third arguments, which are not wrapped in braces. This
function needs special (slower) processing.

\exp_after:wN ? \exp_after:wN htoken1 i htoken2 i

Carries out a single expansion of htoken2 i (which may consume arguments) prior to
the expansion of htoken1 i. If htoken2 i is a TEX primitive, it will be executed rather
than expanded, while if htoken2 i has not expansion (for example, if it is a character)
then it will be left unchanged. It is important to notice that htoken1 i may be any single
token, including group-opening and -closing tokens ({ or } assuming normal TEX category
codes). Unless specifically required, expansion should be carried out using an appropriate
argument specifier variant or the appropriate \exp_arg:N function.

TEXhackers note: This is the TEX primitive \expandafter renamed.

8 Preventing expansion
Despite the fact that the following functions are all about preventing expansion, they’re
designed to be used in an expandable context and hence are all marked as being ‘expand-
able’ since they themselves will not appear after the expansion has completed.

31
 \exp_not:N ? \exp_not:N htoken i
Prevents expansion of the htokeni in a context where it would otherwise be expanded,
for example an x-type argument.

TEXhackers note: This is the TEX \noexpand primitive.

\exp_not:c ? \exp_not:c {htokens i}

Expands the htokensi until only unexpandable content remains, and then converts this
into a control sequence. Further expansion of this control sequence is then inhibited.

\exp_not:n ? \exp_not:n {htokens i}

Prevents expansion of the htokensi in a context where they would otherwise be expanded,
for example an x-type argument.

TEXhackers note: This is the ε-TEX \unexpanded primitive. Hence its argument must
be surrounded by braces.

\exp_not:V ? \exp_not:V hvariable i

Recovers the content of the hvariablei, then prevents expansion of this material in a
context where it would otherwise be expanded, for example an x-type argument.

\exp_not:v ? \exp_not:v {htokens i}

Expands the htokensi until only unexpandable content remains, and then converts this
into a control sequence (which should be a hvariablei name). The content of the hvariablei
is recovered, and further expansion is prevented in a context where it would otherwise
be expanded, for example an x-type argument.

\exp_not:o ? \exp_not:o {htokens i}

Expands the htokensi once, then prevents any further expansion in a context where they
would otherwise be expanded, for example an x-type argument.

\exp_not:f ? \exp_not:f {htokens i}

Expands htokensi fully until the first unexpandable token is found. Expansion then
stops, and the result of the expansion (including any tokens which were not expanded)
is protected from further expansion.

\exp_stop_f: ? \function:f htokens i \exp_stop_f: hmore tokens i

Updated: 2011-06-03 This function terminates an f-type expansion. Thus if a function \function:f starts
an f-type expansion and all of htokensi are expandable \exp_stop:f will terminate the
expansion of tokens even if hmore tokensi are also expandable. The function itself is an
implicit space token. Inside an x-type expansion, it will retain its form, but when typeset
it produces the underlying space (␣).

32
 9 Internal functions and variables

\l__exp_internal_tl The \exp_ module has its private variables to temporarily store results of the argument
expansion. This is done to avoid interference with other functions using temporary
variables.

\::n \cs_set_nopar:Npn \exp_args:Ncof { \::c \::o \::f \::: }

\::N
Internal forms for the base expansion types. These names do not conform to the general
\::p
\::c
LATEX3 approach as this makes them more readily visible in the log and so forth.
\::o
\::f
\::x
\::v
\::V
\:::

33
 Part VI
The l3prg package
Control structures
Conditional processing in LATEX3 is defined as something that performs a series of tests,
possibly involving assignments and calling other functions that do not read further ahead
in the input stream. After processing the input, a state is returned. The typical states
returned are htruei and hfalsei but other states are possible, say an herrori state for
erroneous input, e.g., text as input in a function comparing integers.
LATEX3 has two forms of conditional flow processing based on these states. The firs
form is predicate functions that turn the returned state into a boolean htruei or hfalsei.
For example, the function \cs_if_free_p:N checks whether the control sequence given
as its argument is free and then returns the boolean htruei or hfalsei values to be used in
testing with \if_predicate:w or in functions to be described below. The second form
is the kind of functions choosing a particular argument from the input stream based on
the result of the testing as in \cs_if_free:NTF which also takes one argument (the N)
and then executes either true or false depending on the result. Important to note here
is that the arguments are executed after exiting the underlying \if...\fi: structure.

1 Defining a set of conditional functions

\prg_new_conditional:Npnn \prg_new_conditional:Npnn \hname i:harg spec i hparameters i {hconditions i} {hcode i}

\prg_new_conditional:Nnn \prg_new_conditional:Nnn \hname i:harg spec i {hconditions i} {hcode i}
\prg_set_conditional:Npnn These functions create a family of conditionals using the same {hcodei} to perform the
\prg_set_conditional:Nnn
test created. Those conditionals are expandable if hcodei is. The new versions will
Updated: 2012-02-06 check for existing definitions and perform assignments globally (cf. \cs_new:Npn) whereas
the set versions do no check and perform assignments locally (cf. \cs_set:Npn). The
conditionals created are dependent on the comma-separated list of hconditionsi, which
should be one or more of p, T, F and TF.

\prg_new_protected_conditional:Npnn \prg_new_protected_conditional:Npnn \hname i:harg spec i hparameters i

\prg_new_protected_conditional:Nnn {hconditions i} {hcode i}
\prg_set_protected_conditional:Npnn \prg_new_protected_conditional:Nnn \hname i:harg spec i
\prg_set_protected_conditional:Nnn {hconditions i} {hcode i}
Updated: 2012-02-06

These functions create a family of protected conditionals using the same {hcodei} to
perform the test created. The hcodei does not need to be expandable. The new version will
check for existing definitions and perform assignments globally (cf. \cs_new:Npn) whereas
the set version will not (cf. \cs_set:Npn). The conditionals created are depended on
the comma-separated list of hconditionsi, which should be one or more of T, F and TF
(not p).

34
 The conditionals are defined by \prg_new_conditional:Npnn and friends as:
• \hname i_p:harg spec i — a predicate function which will supply either a logical
true or logical false. This function is intended for use in cases where one or more
logical tests are combined to lead to a final outcome. This function will not work
properly for protected conditionals.

• \hname i:harg spec iT — a function with one more argument than the original harg
speci demands. The htrue branchi code in this additional argument will be left on
the input stream only if the test is true.
• \hname i:harg spec iF — a function with one more argument than the original harg
speci demands. The hfalse branchi code in this additional argument will be left on
the input stream only if the test is false.
• \hname i:harg spec iTF — a function with two more argument than the original
harg speci demands. The htrue branchi code in the first additional argument will
be left on the input stream if the test is true, while the hfalse branchi code in the
second argument will be left on the input stream if the test is false.
The hcodei of the test may use hparametersi as specified by the second argument to \prg_-
set_conditional:Npnn: this should match the hargument specificationi but this is not
enforced. The Nnn versions infer the number of arguments from the argument specification
given (cf. \cs_new:Nn, etc.). Within the hcodei, the functions \prg_return_true: and
\prg_return_false: are used to indicate the logical outcomes of the test.
An example can easily clarify matters here:
\prg_set_conditional:Npnn \foo_if_bar:NN #1#2 { p , T , TF }
{
\if_meaning:w \l_tmpa_tl #1
\prg_return_true:
\else:
\if_meaning:w \l_tmpa_tl #2
\prg_return_true:
\else:
\prg_return_false:
\fi:
\fi:
}
This defines the function \foo_if_bar_p:NN, \foo_if_bar:NNTF and \foo_if_bar:NNT
but not \foo_if_bar:NNF (because F is missing from the hconditionsi list). The return
statements take care of resolving the remaining \else: and \fi: before returning the
state. There must be a return statement for each branch; failing to do so will result in
erroneous output if that branch is executed.

35
\prg_new_eq_conditional:NNn \prg_new_eq_conditional:NNn \hname1 i:harg spec1 i \hname2 i:harg spec2 i
\prg_set_eq_conditional:NNn {hconditions i}

These functions copies a family of conditionals. The new version will check for existing
definitions (cf. \cs_new:Npn) whereas the set version will not (cf. \cs_set:Npn). The
conditionals copied are depended on the comma-separated list of hconditionsi, which
should be one or more of p, T, F and TF.

\prg_return_true: ? \prg_return_true:
\prg_return_false: ? \prg_return_false:
These ‘return’ functions define the logical state of a conditional statement. They appear
within the code for a conditional function generated by \prg_set_conditional:Npnn,
etc, to indicate when a true or false branch has been taken. While they may appear
multiple times each within the code of such conditionals, the execution of the conditional
must result in the expansion of one of these two functions exactly once.
The return functions trigger what is internally an f-expansion process to complete the
evaluation of the conditional. Therefore, after \prg_return_true: or \prg_return_-
false: there must be no non-expandable material in the input stream for the remainder
of the expansion of the conditional code. This includes other instances of either of these
functions.

2 The boolean data type

This section describes a boolean data type which is closely connected to conditional
processing as sometimes you want to execute some code depending on the value of a
switch (e.g., draft/final) and other times you perhaps want to use it as a predicate
function in an \if_predicate:w test. The problem of the primitive \if_false: and
\if_true: tokens is that it is not always safe to pass them around as they may interfere
with scanning for termination of primitive conditional processing. Therefore, we employ
two canonical booleans: \c_true_bool or \c_false_bool. Besides preventing problems
as described above, it also allows us to implement a simple boolean parser supporting
the logical operations And, Or, Not, etc. which can then be used on both the boolean
type and predicate functions.
All conditional \bool_ functions except assignments are expandable and expect the
input to also be fully expandable (which will generally mean being constructed from
predicate functions, possibly nested).

\bool_new:N \bool_new:N hboolean i

\bool_new:c
Creates a new hbooleani or raises an error if the name is already taken. The declaration
is global. The hbooleani will initially be false.

\bool_set_false:N \bool_set_false:N hboolean i

\bool_set_false:c
Sets hbooleani logically false.
\bool_gset_false:N
\bool_gset_false:c

36
 \bool_set_true:N \bool_set_true:N hboolean i
\bool_set_true:c
Sets hbooleani logically true.
\bool_gset_true:N
\bool_gset_true:c

\bool_set_eq:NN \bool_set_eq:NN hboolean1 i hboolean2 i

\bool_set_eq:(cN|Nc|cc)
Sets the content of hboolean1 i equal to that of hboolean2 i.
\bool_gset_eq:NN
\bool_gset_eq:(cN|Nc|cc)

\bool_set:Nn \bool_set:Nn hboolean i {hboolexpr i}

\bool_set:cn
Evaluates the hboolean expressioni as described for \bool_if:n(TF), and sets the
\bool_gset:Nn
\bool_gset:cn hbooleani variable to the logical truth of this evaluation.

Updated: 2012-07-08

\bool_if_p:N ? \bool_if_p:N hboolean i

\bool_if_p:c ? \bool_if:NTF hboolean i {htrue code i} {hfalse code i}
\bool_if:NTF ? Tests the current truth of hbooleani, and continues expansion based on this result.
\bool_if:cTF ?

\bool_show:N \bool_show:N hboolean i

\bool_show:c
Displays the logical truth of the hbooleani on the terminal.
New: 2012-02-09

\bool_show:n \bool_show:n {hboolean expression i}

New: 2012-02-09 Displays the logical truth of the hboolean expressioni on the terminal.
Updated: 2012-07-08

\bool_if_exist_p:N ? \bool_if_exist_p:N hboolean i

\bool_if_exist_p:c ? \bool_if_exist:NTF hboolean i {htrue code i} {hfalse code i}
\bool_if_exist:NTF ? Tests whether the hbooleani is currently defined. This does not check that the hbooleani
\bool_if_exist:cTF ?
really is a boolean variable.
New: 2012-03-03

\l_tmpa_bool A scratch boolean for local assignment. It is never used by the kernel code, and so is
\l_tmpb_bool safe for use with any LATEX3-defined function. However, it may be overwritten by other
non-kernel code and so should only be used for short-term storage.

\g_tmpa_bool A scratch boolean for global assignment. It is never used by the kernel code, and so is
\g_tmpb_bool safe for use with any LATEX3-defined function. However, it may be overwritten by other
non-kernel code and so should only be used for short-term storage.

37
 3 Boolean expressions
As we have a boolean datatype and predicate functions returning boolean htruei or hfalsei
values, it seems only fitting that we also provide a parser for hboolean expressionsi.
A boolean expression is an expression which given input in the form of predicate
functions and boolean variables, return boolean htruei or hfalsei. It supports the logical
operations And, Or and Not as the well-known infix operators &&, || and ! with their
usual precedences. In addition to this, parentheses can be used to isolate sub-expressions.
For example,
\int_compare_p:n { 1 = 1 } &&
(
\int_compare_p:n { 2 = 3 } ||
\int_compare_p:n { 4 = 4 } ||
\int_compare_p:n { 1 = \error } % is skipped
) &&
! ( \int_compare_p:n { 2 = 4 } )
is a valid boolean expression. Note that minimal evaluation is carried out whenever
possible so that whenever a truth value cannot be changed any more, the remaining tests
within the current group are skipped.

\bool_if_p:n ? \bool_if_p:n {hboolean expression i}

\bool_if:nTF ? \bool_if:nTF {hboolean expression i} {htrue code i} {hfalse code i}
Updated: 2012-07-08 Tests the current truth of hboolean expressioni, and continues expansion based on this
result. The hboolean expressioni should consist of a series of predicates or boolean vari-
ables with the logical relationship between these defined using && (“And”), || (“Or”), !
(“Not”) and parentheses. Minimal evaluation is used in the processing, so that once a
result is defined there is not further expansion of the tests. For example
\bool_if_p:n
{
\int_compare_p:nNn { 1 } = { 1 }
&&
(
\int_compare_p:nNn { 2 } = { 3 } ||
\int_compare_p:nNn { 4 } = { 4 } ||
\int_compare_p:nNn { 1 } = { \error } % is skipped
)
&&
! \int_compare_p:nNn { 2 } = { 4 }
}
will be true and will not evaluate \int_compare_p:nNn { 1 } = { \error }. The
logical Not applies to the next predicate or group.

38
 \bool_not_p:n ? \bool_not_p:n {hboolean expression i}
Updated: 2012-07-08 Function version of !(hboolean expressioni) within a boolean expression.

\bool_xor_p:nn ? \bool_xor_p:nn {hboolexpr1 i} {hboolexpr2 i}

Updated: 2012-07-08 Implements an “exclusive or” operation between two boolean expressions. There is no
infix operation for this logical operator.

4 Logical loops
Loops using either boolean expressions or stored boolean values.

\bool_do_until:Nn I \bool_do_until:Nn hboolean i {hcode i}

\bool_do_until:cn I
Places the hcodei in the input stream for TEX to process, and then checks the logical value
of the hbooleani. If it is false then the hcodei will be inserted into the input stream again
and the process will loop until the hbooleani is true.

\bool_do_while:Nn I \bool_do_while:Nn hboolean i {hcode i}

\bool_do_while:cn I
Places the hcodei in the input stream for TEX to process, and then checks the logical
value of the hbooleani. If it is true then the hcodei will be inserted into the input stream
again and the process will loop until the hbooleani is false.

\bool_until_do:Nn I \bool_until_do:Nn hboolean i {hcode i}

\bool_until_do:cn I
This function firsts checks the logical value of the hbooleani. If it is false the hcodei is
placed in the input stream and expanded. After the completion of the hcodei the truth
of the hbooleani is re-evaluated. The process will then loop until the hbooleani is true.

\bool_while_do:Nn I \bool_while_do:Nn hboolean i {hcode i}

\bool_while_do:cn I
This function firsts checks the logical value of the hbooleani. If it is true the hcodei is
placed in the input stream and expanded. After the completion of the hcodei the truth
of the hbooleani is re-evaluated. The process will then loop until the hbooleani is false.

\bool_do_until:nn I \bool_do_until:nn {hboolean expression i} {hcode i}

Updated: 2012-07-08 Places the hcodei in the input stream for TEX to process, and then checks the logical
value of the hboolean expressioni as described for \bool_if:nTF. If it is false then the
hcodei will be inserted into the input stream again and the process will loop until the
hboolean expressioni evaluates to true.

\bool_do_while:nn I \bool_do_while:nn {hboolean expression i} {hcode i}

Updated: 2012-07-08 Places the hcodei in the input stream for TEX to process, and then checks the logical
value of the hboolean expressioni as described for \bool_if:nTF. If it is true then the
hcodei will be inserted into the input stream again and the process will loop until the
hboolean expressioni evaluates to false.

39
 \bool_until_do:nn I \bool_until_do:nn {hboolean expression i} {hcode i}
Updated: 2012-07-08 This function firsts checks the logical value of the hboolean expressioni (as described for
\bool_if:nTF). If it is false the hcodei is placed in the input stream and expanded.
After the completion of the hcodei the truth of the hboolean expressioni is re-evaluated.
The process will then loop until the hboolean expressioni is true.

\bool_while_do:nn I \bool_while_do:nn {hboolean expression i} {hcode i}

Updated: 2012-07-08 This function firsts checks the logical value of the hboolean expressioni (as described for
\bool_if:nTF). If it is true the hcodei is placed in the input stream and expanded. After
the completion of the hcodei the truth of the hboolean expressioni is re-evaluated. The
process will then loop until the hboolean expressioni is false.

5 Producing n copies

\prg_replicate:nn ? \prg_replicate:nn {hinteger expression i} {htokens i}

Updated: 2011-07-04 Evaluates the hinteger expressioni (which should be zero or positive) and creates the
resulting number of copies of the htokensi. The function is both expandable and safe for
nesting. It yields its result after two expansion steps.

6 Detecting TEX’s mode

\mode_if_horizontal_p: ? \mode_if_horizontal_p:
\mode_if_horizontal:TF ? \mode_if_horizontal:TF {htrue code i} {hfalse code i}
Detects if TEX is currently in horizontal mode.

\mode_if_inner_p: ? \mode_if_inner_p:
\mode_if_inner:TF ? \mode_if_inner:TF {htrue code i} {hfalse code i}
Detects if TEX is currently in inner mode.

\mode_if_math_p: ? \mode_if_math:TF {htrue code i} {hfalse code i}

\mode_if_math:TF ?
Detects if TEX is currently in maths mode.
Updated: 2011-09-05

\mode_if_vertical_p: ? \mode_if_vertical_p:
\mode_if_vertical:TF ? \mode_if_vertical:TF {htrue code i} {hfalse code i}
Detects if TEX is currently in vertical mode.

40
 7 Primitive conditionals

\if_predicate:w ? \if_predicate:w hpredicate i htrue code i \else: hfalse code i \fi:

This function takes a predicate function and branches according to the result. (In practice
this function would also accept a single boolean variable in place of the hpredicatei but
to make the coding clearer this should be done through \if_bool:N.)

\if_bool:N ? \if_bool:N hboolean i htrue code i \else: hfalse code i \fi:

This function takes a boolean variable and branches according to the result.

8 Internal programming functions

\group_align_safe_begin: ? \group_align_safe_begin:
\group_align_safe_end: ? ...
\group_align_safe_end:
Updated: 2011-08-11
These functions are used to enclose material in a TEX alignment environment within a
specially-constructed group. This group is designed in such a way that it does not add
brace groups to the output but does act as a group for the & token inside \halign. This
is necessary to allow grabbing of tokens for testing purposes, as TEX uses group level
to determine the effect of alignment tokens. Without the special grouping, the use of a
function such as \peek_after:Nw will result in a forbidden comparison of the internal
\endtemplate token, yielding a fatal error. Each \group_align_safe_begin: must be
matched by a \group_align_safe_end:, although this does not have to occur within
the same function.

\scan_align_safe_stop: \scan_align_safe_stop:
Updated: 2011-09-06 Stops TEX’s scanner looking for expandable control sequences at the beginning of an
alignment cell. This function is required, for example, to obtain the expected output
when testing \mode_if_math:TF at the start of a math array cell: placing \scan_-
align_safe_stop: before \mode_if_math:TF will give the correct result. This function
does not destroy any kerning if used in other locations, but does render functions non-
expandable.

TEXhackers note: This is a protected version of \prg_do_nothing:, which therefore stops

TEX’s scanner in the circumstances described without producing any affect on the output.

\__prg_variable_get_scope:N ? \__prg_variable_get_scope:N hvariable i

Returns the scope (g for global, blank otherwise) for the hvariablei.

\__prg_variable_get_type:N ? \__prg_variable_get_type:N hvariable i

Returns the type of hvariablei (tl, int, etc.)

41
\__prg_break_point:Nn ? \__prg_break_point:Nn \htype i_map_break: htokens i
Used to mark the end of a recursion or mapping: the functions \htype i_map_break: and
\htype i_map_break:n use this to break out of the loop. After the loop ends, the htokensi
are inserted into the input stream. This occurs even if the break functions are not applied:
\__prg_break_point:Nn is functionally-equivalent in these cases to \use_ii:nn.

\__prg_map_break:Nn ? \__prg_map_break:Nn \htype i_map_break: {huser code i}

...
\__prg_break_point:Nn \htype i_map_break: {hending code i}
Breaks a recursion in mapping contexts, inserting in the input stream the huser codei
after the hending codei for the loop. The function breaks loops, inserting their hending
codei, until reaching a loop with the same htypei as its first argument. This \htype i_-
map_break: argument is simply used as a recognizable marker for the htypei.

\g__prg_map_int This integer is used by non-expandable mapping functions to track the level of nesting
in force. The functions \__prg_map_1:w, \__prg_map_2:w, etc., labelled by \g__prg_-
map_int hold functions to be mapped over various list datatypes in inline and variable
mappings.

\__prg_break_point: ? This copy of \prg_do_nothing: is used to mark the end of a fast short-term recursions:
the function \__prg_break:n uses this to break out of the loop.

\__prg_break: ? \__prg_break:n {htokens i} ... \__prg_break_point:

\__prg_break:n ?
Breaks a recursion which has no hending codei and which is not a user-breakable mapping
(see for instance \prop_get:Nn), and inserts htokensi in the input stream.

42
Part VII
The l3quark package
Quarks
1 Introduction to quarks and scan marks
Two special types of constants in LATEX3 are “quarks” and “scan marks”. By convention
all constants of type quark start out with \q_, and scan marks start with \s_. Scan
marks are for internal use by the kernel: they are not intended for more general use.

1.1 Quarks
Quarks are control sequences that expand to themselves and should therefore never be
executed directly in the code. This would result in an endless loop!
They are meant to be used as delimiter in weird functions, with the most command
use case as the ‘stop token’ (i.e. \q_stop). For example, when writing a macro to parse
a user-defined date

\date_parse:n {19/June/1981}
one might write a command such as
\cs_new:Npn \date_parse:n #1 { \date_parse_aux:w #1 \q_stop }
\cs_new:Npn \date_parse_aux:w #1 / #2 / #3 \q_stop
{ <do something with the date> }

Quarks are sometimes also used as error return values for functions that receive
erroneous input. For example, in the function \prop_get:NnN to retrieve a value stored
in some key of a property list, if the key does not exist then the return value is the quark
\q_no_value. As mentioned above, such quarks are extremely fragile and it is imperative
when using such functions that code is carefully written to check for pathological cases
to avoid leakage of a quark into an uncontrolled environment.
Quarks also permit the following ingenious trick when parsing tokens: when you
pick up a token in a temporary variable and you want to know whether you have picked
up a particular quark, all you have to do is compare the temporary variable to the quark
using \tl_if_eq:NNTF. A set of special quark testing functions is set up below. All the
quark testing functions are expandable although the ones testing only single tokens are
much faster. An example of the quark testing functions and their use in recursion can
be seen in the implementation of \clist_map_function:NN.

43
 2 Defining quarks

\quark_new:N \quark_new:N hquark i

Creates a new hquarki which expands only to hquarki. The hquarki will be defined
globally, and an error message will be raised if the name was already taken.

\q_stop Used as a marker for delimited arguments, such as

\cs_set:Npn \tmp:w #1#2 \q_stop {#1}

\q_mark Used as a marker for delimited arguments when \q_stop is already in use.

Quark to mark a null value in structured variables or functions. Used as an end delimiter
when this may itself may need to be tested (in contrast to \q_stop, which is only ever
used as a delimiter).

\q_no_value A canonical value for a missing value, when one is requested from a data structure. This
is therefore used as a “return” value by functions such as \prop_get:NnN if there is no
data to return.

3 Quark tests
The method used to define quarks means that the single token (N) tests are faster than
the multi-token (n) tests. The later should therefore only be used when the argument
can definitely take more than a single token.

\quark_if_nil_p:N ? \quark_if_nil_p:N htoken i

\quark_if_nil:NTF ? \quark_if_nil:NTF htoken i {htrue code i} {hfalse code i}
Tests if the htokeni is equal to \q_nil.

\quark_if_nil_p:n ? \quark_if_nil_p:n {htoken list i}

\quark_if_nil_p:(o|V) ? \quark_if_nil:nTF {htoken list i} {htrue code i} {hfalse code i}
\quark_if_nil:nTF ? Tests if the htoken listi contains only \q_nil (distinct from htoken listi being empty or
\quark_if_nil:(o|V)TF ?
containing \q_nil plus one or more other tokens).

\quark_if_no_value_p:N ? \quark_if_no_value_p:N htoken i

\quark_if_no_value_p:c ? \quark_if_no_value:NTF htoken i {htrue code i} {hfalse code i}
\quark_if_no_value:NTF ? Tests if the htokeni is equal to \q_no_value.
\quark_if_no_value:cTF ?

\quark_if_no_value_p:n ? \quark_if_no_value_p:n {htoken list i}

\quark_if_no_value:nTF ? \quark_if_no_value:nTF {htoken list i} {htrue code i} {hfalse code i}
Tests if the htoken listi contains only \q_no_value (distinct from htoken listi being empty
or containing \q_no_value plus one or more other tokens).

44
 4 Recursion
This module provides a uniform interface to intercepting and terminating loops as when
one is doing tail recursion. The building blocks follow below and an example is shown in
Section 5.

\q_recursion_tail This quark is appended to the data structure in question and appears as a real element
there. This means it gets any list separators around it.

\q_recursion_stop This quark is added after the data structure. Its purpose is to make it possible to
terminate the recursion at any point easily.

\quark_if_recursion_tail_stop:N \quark_if_recursion_tail_stop:N htoken i

Tests if htokeni contains only the marker \q_recursion_tail, and if so terminates the
recursion this is part of using \use_none_delimit_by_q_recursion_stop:w. The recur-
sion input must include the marker tokens \q_recursion_tail and \q_recursion_stop
as the last two items.

\quark_if_recursion_tail_stop:n \quark_if_recursion_tail_stop:n {htoken list i}

\quark_if_recursion_tail_stop:o
Updated: 2011-09-06

Tests if the htoken listi contains only \q_recursion_tail, and if so terminates the recur-
sion this is part of using \use_none_delimit_by_q_recursion_stop:w. The recursion
input must include the marker tokens \q_recursion_tail and \q_recursion_stop as
the last two items.

\quark_if_recursion_tail_stop_do:Nn \quark_if_recursion_tail_stop_do:Nn htoken i {hinsertion i}

Tests if htokeni contains only the marker \q_recursion_tail, and if so terminates the
recursion this is part of using \use_none_delimit_by_q_recursion_stop:w. The recur-
sion input must include the marker tokens \q_recursion_tail and \q_recursion_stop
as the last two items. The hinsertioni code is then added to the input stream after the
recursion has ended.

\quark_if_recursion_tail_stop_do:nn \quark_if_recursion_tail_stop_do:nn {htoken list i} {hinsertion i}

\quark_if_recursion_tail_stop_do:on
Updated: 2011-09-06

Tests if the htoken listi contains only \q_recursion_tail, and if so terminates the recur-
sion this is part of using \use_none_delimit_by_q_recursion_stop:w. The recursion
input must include the marker tokens \q_recursion_tail and \q_recursion_stop as
the last two items. The hinsertioni code is then added to the input stream after the
recursion has ended.

45
 5 An example of recursion with quarks
Quarks are mainly used internally in the expl3 code to define recursion functions such
as \tl_map_inline:nn and so on. Here is a small example to demonstrate how to
use quarks in this fashion. We shall define a command called \my_map_dbl:nn which
takes a token list and applies an operation to every pair of tokens. For example,
\my_map_dbl:nn {abcd} {[--#1--#2--]~} would produce “[–a–b–] [–c–d–] ”. Us-
ing quarks to define such functions simplifies their logic and ensures robustness in many
cases.
Here’s the definition of \my_map_dbl:nn. First of all, define the function that will
do the processing based on the inline function argument #2. Then initiate the recursion
using an internal function. The token list #1 is terminated using \q_recursion_tail,
with delimiters according to the type of recursion (here a pair of \q_recursion_tail),
concluding with \q_recursion_stop. These quarks are used to mark the end of the
token list being operated upon.
1 \cs_new:Npn \my_map_dbl:nn #1#2
2 {
3 \cs_set:Npn \__my_map_dbl_fn:nn ##1 ##2 {#2}
4 \__my_map_dbl:nn #1 \q_recursion_tail \q_recursion_tail \q_recursion_stop
5 }
The definition of the internal recursion function follows. First check if either of the
input tokens are the termination quarks. Then, if not, apply the inline function to the
two arguments.
6 \cs_new:Nn \__my_map_dbl:nn
7 {
8 \quark_if_recursion_tail_stop:n {#1}
9 \quark_if_recursion_tail_stop:n {#2}
10 \__my_map_dbl_fn:nn {#1} {#2}
Finally, recurse:
11 \__my_map_dbl:nn
12 }
Note that contrarily to LATEX3 built-in mapping functions, this mapping function cannot
be nested, since the second map will overwrite the definition of \__my_map_dbl_fn:nn.

6 Internal quark functions

\__quark_if_recursion_tail_break:NN \__quark_if_recursion_tail_break:nN {htoken list i}

\__quark_if_recursion_tail_break:nN \htype i_map_break:

Tests if htoken listi contains only \q_recursion_tail, and if so terminates the recursion
using \htype i_map_break:. The recursion end should be marked by \prg_break_-
point:Nn \htype i_map_break:.

46
 7 Scan marks
Scan marks are control sequences set equal to \scan_stop:, hence will never expand in an
expansion context and will be (largely) invisible if they are encountered in a typesetting
context.
Like quarks, they can be used as delimiters in weird functions and are often safer to
use for this purpose. Since they are harmless when executed by TEX in non-expandable
contexts, they can be used to mark the end of a set of instructions. This allows to skip
to that point if the end of the instructions should not be performed (see l3regex).
The scan marks system is only for internal use by the kernel team in a small number
of very specific places. These functions should not be used more generally.

\__scan_new:N \__scan_new:N hscan mark i

Creates a new hscan marki which is set equal to \scan_stop:. The hscan marki will be
defined globally, and an error message will be raised if the name was already taken by
another scan mark.

\s__stop Used at the end of a set of instructions, as a marker that can be jumped to using \__-
use_none_delimit_by_s__stop:w.

\__use_none_delimit_by_s__stop:w \__use_none_delimit_by_s__stop:w htokens i \s__stop

Removes the htokensi and \s__stop from the input stream. This leads to a low-level
TEX error if \s__stop is absent.

47
Part VIII
The l3token package
Token manipulation
This module deals with tokens. Now this is perhaps not the most precise description so
let’s try with a better description: When programming in TEX, it is often desirable to
know just what a certain token is: is it a control sequence or something else. Similarly
one often needs to know if a control sequence is expandable or not, a macro or a primitive,
how many arguments it takes etc. Another thing of great importance (especially when it
comes to document commands) is looking ahead in the token stream to see if a certain
character is present and maybe even remove it or disregard other tokens while scanning.
This module provides functions for both and as such will have two primary function
categories: \token_ for anything that deals with tokens and \peek_ for looking ahead
in the token stream.
Most of the time we will be using the term “token” but most of the time the function
we’re describing can equally well by used on a control sequence as such one is one token
as well.
We shall refer to list of tokens as tlists and such lists represented by a single control
sequence is a “token list variable” tl var. Functions for these two types are found in
the l3tl module.

1 All possible tokens

Let us start by reviewing every case that a given token can fall into. It is very important
to distinguish two aspects of a token: its meaning, and what it looks like.
For instance, \if:w, \if_charcode:w, and \tex_if:D are three for the same internal
operation of TEX, namely the primitive testing the next two characters for equality of their
character code. They behave identically in many situations. However, TEX distinguishes
them when searching for a delimited argument. Namely, the example function \show_-
until_if:w defined below will take everything until \if:w as an argument, despite the
presence of other copies of \if:w under different names.
\cs_new:Npn \show_until_if:w #1 \if:w { \tl_show:n {#1} }
\show_until_if:w \tex_if:D \if_charcode:w \if:w

48
 2 Character tokens

\char_set_catcode_escape:N \char_set_catcode_letter:N hcharacter i

\char_set_catcode_group_begin:N
\char_set_catcode_group_end:N
\char_set_catcode_math_toggle:N
\char_set_catcode_alignment:N
\char_set_catcode_end_line:N
\char_set_catcode_parameter:N
\char_set_catcode_math_superscript:N
\char_set_catcode_math_subscript:N
\char_set_catcode_ignore:N
\char_set_catcode_space:N
\char_set_catcode_letter:N
\char_set_catcode_other:N
\char_set_catcode_active:N
\char_set_catcode_comment:N
\char_set_catcode_invalid:N

Sets the category code of the hcharacteri to that indicated in the function name. De-
pending on the current category code of the htokeni the escape token may also be needed:
\char_set_catcode_other:N \%
The assignment is local.

\char_set_catcode_escape:n \char_set_catcode_letter:n {hinteger expression i}

\char_set_catcode_group_begin:n
\char_set_catcode_group_end:n
\char_set_catcode_math_toggle:n
\char_set_catcode_alignment:n
\char_set_catcode_end_line:n
\char_set_catcode_parameter:n
\char_set_catcode_math_superscript:n
\char_set_catcode_math_subscript:n
\char_set_catcode_ignore:n
\char_set_catcode_space:n
\char_set_catcode_letter:n
\char_set_catcode_other:n
\char_set_catcode_active:n
\char_set_catcode_comment:n
\char_set_catcode_invalid:n

Sets the category code of the hcharacteri which has character code as given by the hinteger
expressioni. This version can be used to set up characters which cannot otherwise be
given (cf. the N-type variants). The assignment is local.

49
 \char_set_catcode:nn \char_set_catcode:nn {hintexpr1 i} {hintexpr2 i}
These functions set the category code of the hcharacteri which has character code as
given by the hinteger expressioni. The first hinteger expressioni is the character code
and the second is the category code to apply. The setting applies within the current
TEX group. In general, the symbolic functions \char_set_catcode_htype i should be
preferred, but there are cases where these lower-level functions may be useful.

\char_value_catcode:n ? \char_value_catcode:n {hinteger expression i}

Expands to the current category code of the hcharacteri with character code given by
the hinteger expressioni.

\char_show_value_catcode:n \char_show_value_catcode:n {hinteger expression i}

Displays the current category code of the hcharacteri with character code given by the
hinteger expressioni on the terminal.

\char_set_lccode:nn \char_set_lcode:nn {hintexpr1 i} {hintexpr2 i}

This function set up the behaviour of hcharacteri when found inside \tl_to_lowercase:n,
such that hcharacter1 i will be converted into hcharacter2 i. The two hcharactersi may be
specified using an hinteger expressioni for the character code concerned. This may in-
clude the TEX ‘hcharacteri method for converting a single character into its character
code:
\char_set_lccode:nn { ‘\A } { ‘\a } % Standard behaviour
\char_set_lccode:nn { ‘\A } { ‘\A + 32 }
\char_set_lccode:nn { 50 } { 60 }
The setting applies within the current TEX group.

\char_value_lccode:n ? \char_value_lccode:n {hinteger expression i}

Expands to the current lower case code of the hcharacteri with character code given by
the hinteger expressioni.

\char_show_value_lccode:n \char_show_value_lccode:n {hinteger expression i}

Displays the current lower case code of the hcharacteri with character code given by the
hinteger expressioni on the terminal.

50
 \char_set_uccode:nn \char_set_uccode:nn {hintexpr1 i} {hintexpr2 i}
This function set up the behaviour of hcharacteri when found inside \tl_to_uppercase:n,
such that hcharacter1 i will be converted into hcharacter2 i. The two hcharactersi may be
specified using an hinteger expressioni for the character code concerned. This may in-
clude the TEX ‘hcharacteri method for converting a single character into its character
code:

\char_set_uccode:nn { ‘\a } { ‘\A } % Standard behaviour

\char_set_uccode:nn { ‘\A } { ‘\A - 32 }
\char_set_uccode:nn { 60 } { 50 }
The setting applies within the current TEX group.

\char_value_uccode:n ? \char_value_uccode:n {hinteger expression i}

Expands to the current upper case code of the hcharacteri with character code given by
the hinteger expressioni.

\char_show_value_uccode:n \char_show_value_uccode:n {hinteger expression i}

Displays the current upper case code of the hcharacteri with character code given by the
hinteger expressioni on the terminal.

\char_set_mathcode:nn \char_set_mathcode:nn {hintexpr1 i} {hintexpr2 i}

This function sets up the math code of hcharacteri. The hcharacteri is specified as an
hinteger expressioni which will be used as the character code of the relevant character.
The setting applies within the current TEX group.

\char_value_mathcode:n ? \char_value_mathcode:n {hinteger expression i}

Expands to the current math code of the hcharacteri with character code given by the
hinteger expressioni.

\char_show_value_mathcode:n \char_show_value_mathcode:n {hinteger expression i}

Displays the current math code of the hcharacteri with character code given by the
hinteger expressioni on the terminal.

\char_set_sfcode:nn \char_set_sfcode:nn {hintexpr1 i} {hintexpr2 i}

This function sets up the space factor for the hcharacteri. The hcharacteri is specified as
an hinteger expressioni which will be used as the character code of the relevant character.
The setting applies within the current TEX group.

\char_value_sfcode:n ? \char_value_sfcode:n {hinteger expression i}

Expands to the current space factor for the hcharacteri with character code given by the
hinteger expressioni.

51
\char_show_value_sfcode:n \char_show_value_sfcode:n {hinteger expression i}
Displays the current space factor for the hcharacteri with character code given by the
hinteger expressioni on the terminal.

\l_char_active_seq Used to track which tokens will require special handling at the document level as they
New: 2012-01-23 are of category hactivei (catcode 13). Each entry in the sequence consists of a single
active character. Active tokens should be added to the sequence when they are defined
for general document use.

\l_char_special_seq Used to track which tokens will require special handling when working with verbatim-
New: 2012-01-23 like material at the document level as they are not of categories hletteri (catcode 11) or
hotheri (catcode 12). Each entry in the sequence consists of a single escaped token, for
example \\ for the backslash or \{ for an opening brace.Escaped tokens should be added
to the sequence when they are defined for general document use.

3 Generic tokens

\token_new:Nn \token_new:Nn htoken1 i {htoken2 i}

Defines htoken1 i to globally be a snapshot of htoken2 i. This will be an implicit represen-
tation of htoken2 i.

\c_group_begin_token These are implicit tokens which have the category code described by their name. They
\c_group_end_token are used internally for test purposes but are also available to the programmer for other
\c_math_toggle_token uses.
\c_alignment_token
\c_parameter_token
\c_math_superscript_token
\c_math_subscript_token
\c_space_token

\c_catcode_letter_token These are implicit tokens which have the category code described by their name. They
\c_catcode_other_token are used internally for test purposes and should not be used other than for category code
tests.

\c_catcode_active_tl A token list containing an active token. This is used internally for test purposes and
should not be used other than in appropriately-constructed category code tests.

52
 4 Converting tokens

\token_to_meaning:N ? \token_to_meaning:N htoken i

\token_to_meaning:c ?
Inserts the current meaning of the htokeni into the input stream as a series of characters
of category code 12 (other). This will be the primitive TEX description of the htokeni,
thus for example both functions defined by \cs_set_nopar:Npn and token list variables
defined using \tl_new:N will be described as macros.

TEXhackers note: This is the TEX primitive \meaning.

\token_to_str:N ? \token_to_str:N htoken i

\token_to_str:c ?
Converts the given htokeni into a series of characters with category code 12 (other). The
current escape character will be the first character in the sequence, although this will
also have category code 12 (the escape character is part of the htokeni). This function
requires only a single expansion.

TEXhackers note: \token_to_str:N is the TEX primitive \string renamed.

5 Token conditionals

\token_if_group_begin_p:N ? \token_if_group_begin_p:N htoken i

\token_if_group_begin:NTF ? \token_if_group_begin:NTF htoken i {htrue code i} {hfalse code i}

Tests if htokeni has the category code of a begin group token ({ when normal TEX
category codes are in force). Note that an explicit begin group token cannot be tested in
this way, as it is not a valid N-type argument.

\token_if_group_end_p:N ? \token_if_group_end_p:N htoken i

\token_if_group_end:NTF ? \token_if_group_end:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of an end group token (} when normal TEX category
codes are in force). Note that an explicit end group token cannot be tested in this way,
as it is not a valid N-type argument.

\token_if_math_toggle_p:N ? \token_if_math_toggle_p:N htoken i

\token_if_math_toggle:NTF ? \token_if_math_toggle:NTF htoken i {htrue code i} {hfalse code i}

Tests if htokeni has the category code of a math shift token ($ when normal TEX category
codes are in force).

\token_if_alignment_p:N ? \token_if_alignment_p:N htoken i

\token_if_alignment:NTF ? \token_if_alignment:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of an alignment token (& when normal TEX category
codes are in force).

53
\token_if_parameter_p:N ? \token_if_parameter_p:N htoken i
\token_if_parameter:NTF ? \token_if_alignment:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of a macro parameter token (# when normal TEX
category codes are in force).

\token_if_math_superscript_p:N ? \token_if_math_superscript_p:N htoken i

\token_if_math_superscript:NTF ? \token_if_math_superscript:NTF htoken i {htrue code i} {hfalse code i}

Tests if htokeni has the category code of a superscript token (^ when normal TEX category
codes are in force).

\token_if_math_subscript_p:N ? \token_if_math_subscript_p:N htoken i

\token_if_math_subscript:NTF ? \token_if_math_subscript:NTF htoken i {htrue code i} {hfalse code i}

Tests if htokeni has the category code of a subscript token (_ when normal TEX category
codes are in force).

\token_if_space_p:N ? \token_if_space_p:N htoken i

\token_if_space:NTF ? \token_if_space:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of a space token. Note that an explicit space token
with character code 32 cannot be tested in this way, as it is not a valid N-type argument.

\token_if_letter_p:N ? \token_if_letter_p:N htoken i

\token_if_letter:NTF ? \token_if_letter:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of a letter token.

\token_if_other_p:N ? \token_if_other_p:N htoken i

\token_if_other:NTF ? \token_if_other:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of an “other” token.

\token_if_active_p:N ? \token_if_active_p:N htoken i

\token_if_active:NTF ? \token_if_active:NTF htoken i {htrue code i} {hfalse code i}
Tests if htokeni has the category code of an active character.

\token_if_eq_catcode_p:NN ? \token_if_eq_catcode_p:NN htoken1 i htoken2 i

\token_if_eq_catcode:NNTF ? \token_if_eq_catcode:NNTF htoken1 i htoken2 i {htrue code i} {hfalse code i}

Tests if the two htokensi have the same category code.

\token_if_eq_charcode_p:NN ? \token_if_eq_charcode_p:NN htoken1 i htoken2 i

\token_if_eq_charcode:NNTF ? \token_if_eq_charcode:NNTF htoken1 i htoken2 i {htrue code i} {hfalse code i}

Tests if the two htokensi have the same character code.

54
 \token_if_eq_meaning_p:NN ? \token_if_eq_meaning_p:NN htoken1 i htoken2 i
\token_if_eq_meaning:NNTF ? \token_if_eq_meaning:NNTF htoken1 i htoken2 i {htrue code i} {hfalse code i}

Tests if the two htokensi have the same meaning when expanded.

\token_if_macro_p:N ? \token_if_macro_p:N htoken i

\token_if_macro:NTF ? \token_if_macro:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2011-05-23 Tests if the htokeni is a TEX macro.

\token_if_cs_p:N ? \token_if_cs_p:N htoken i

\token_if_cs:NTF ? \token_if_cs:NTF htoken i {htrue code i} {hfalse code i}
Tests if the htokeni is a control sequence.

\token_if_expandable_p:N ? \token_if_expandable_p:N htoken i

\token_if_expandable:NTF ? \token_if_expandable:NTF htoken i {htrue code i} {hfalse code i}
Tests if the htokeni is expandable. This test returns hfalsei for an undefined token.

\token_if_long_macro_p:N ? \token_if_long_macro_p:N htoken i

\token_if_long_macro:NTF ? \token_if_long_macro:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20 Tests if the htokeni is a long macro.

\token_if_protected_macro_p:N ? \token_if_protected_macro_p:N htoken i

\token_if_protected_macro:NTF ? \token_if_protected_macro:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is a protected macro: a macro which is both protected and long will
return logical false.

\token_if_protected_long_macro_p:N ? \token_if_protected_long_macro_p:N htoken i

\token_if_protected_long_macro:NTF ? \token_if_protected_long_macro:NTF htoken i {htrue code i} {hfalse
code i}
Updated: 2012-01-20

Tests if the htokeni is a protected long macro.

\token_if_chardef_p:N ? \token_if_chardef_p:N htoken i

\token_if_chardef:NTF ? \token_if_chardef:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20 Tests if the htokeni is defined to be a chardef.

TEXhackers note: Booleans, boxes and small integer constants are implemented as chard-
efs.

55
 \token_if_mathchardef_p:N ? \token_if_mathchardef_p:N htoken i
\token_if_mathchardef:NTF ? \token_if_mathchardef:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is defined to be a mathchardef.

\token_if_dim_register_p:N ? \token_if_dim_register_p:N htoken i

\token_if_dim_register:NTF ? \token_if_dim_register:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is defined to be a dimension register.

\token_if_int_register_p:N ? \token_if_int_register_p:N htoken i

\token_if_int_register:NTF ? \token_if_int_register:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is defined to be a integer register.

TEXhackers note: Constant integers may be implemented as integer registers, chardefs,

or mathchardefs depending on their value.

\token_if_muskip_register_p:N ? \token_if_muskip_register_p:N htoken i

\token_if_muskip_register:NTF ? \token_if_muskip_register:NTF htoken i {htrue code i} {hfalse code i}
New: 2012-02-15

Tests if the htokeni is defined to be a muskip register.

\token_if_skip_register_p:N ? \token_if_skip_register_p:N htoken i

\token_if_skip_register:NTF ? \token_if_skip_register:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is defined to be a skip register.

\token_if_toks_register_p:N ? \token_if_toks_register_p:N htoken i

\token_if_toks_register:NTF ? \token_if_toks_register:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2012-01-20

Tests if the htokeni is defined to be a toks register (not used byLATEX3).

\token_if_primitive_p:N ? \token_if_primitive_p:N htoken i

\token_if_primitive:NTF ? \token_if_primitive:NTF htoken i {htrue code i} {hfalse code i}
Updated: 2011-05-23 Tests if the htokeni is an engine primitive.

56
 6 Peeking ahead at the next token
There is often a need to look ahead at the next token in the input stream while leaving
it in place. This is handled using the “peek” functions. The generic \peek_after:Nw is
provided along with a family of predefined tests for common cases. As peeking ahead does
not skip spaces the predefined tests include both a space-respecting and space-skipping
version.

\peek_after:Nw \peek_after:Nw hfunction i htoken i

Locally sets the test variable \l_peek_token equal to htokeni (as an implicit token, not
as a token list), and then expands the hfunctioni. The htokeni will remain in the input
stream as the next item after the hfunctioni. The htokeni here may be ␣, { or } (assuming
normal TEX category codes), i.e. it is not necessarily the next argument which would be
grabbed by a normal function.

\peek_gafter:Nw \peek_gafter:Nw hfunction i htoken i

Globally sets the test variable \g_peek_token equal to htokeni (as an implicit token,
not as a token list), and then expands the hfunctioni. The htokeni will remain in the
input stream as the next item after the hfunctioni. The htokeni here may be ␣, { or }
(assuming normal TEX category codes), i.e. it is not necessarily the next argument which
would be grabbed by a normal function.

\l_peek_token Token set by \peek_after:Nw and available for testing as described above.

\g_peek_token Token set by \peek_gafter:Nw and available for testing as described above.

\peek_catcode:NTF \peek_catcode:NTF htest token i {htrue code i} {hfalse code i}

Updated: 2012-12-20 Tests if the next htokeni in the input stream has the same category code as the htest
tokeni (as defined by the test \token_if_eq_catcode:NNTF). Spaces are respected by
the test and the htokeni will be left in the input stream after the htrue codei or hfalse
codei (as appropriate to the result of the test).

\peek_catcode_ignore_spaces:NTF \peek_catcode_ignore_spaces:NTF htest token i {htrue code i} {hfalse

code i}
Updated: 2012-12-20

Tests if the next non-space htokeni in the input stream has the same category code as the
htest tokeni (as defined by the test \token_if_eq_catcode:NNTF). Explicit and implicit
space tokens (with character code 32 and category code 10) are ignored and removed by
the test and the htokeni will be left in the input stream after the htrue codei or hfalse
codei (as appropriate to the result of the test).

57
 \peek_catcode_remove:NTF \peek_catcode_remove:NTF htest token i {htrue code i} {hfalse code i}
Updated: 2012-12-20 Tests if the next htokeni in the input stream has the same category code as the htest
tokeni (as defined by the test \token_if_eq_catcode:NNTF). Spaces are respected by
the test and the htokeni will be removed from the input stream if the test is true. The
function will then place either the htrue codei or hfalse codei in the input stream (as
appropriate to the result of the test).

\peek_catcode_remove_ignore_spaces:NTF \peek_catcode_remove_ignore_spaces:NTF htest token i {htrue

code i} {hfalse code i}
Updated: 2012-12-20

Tests if the next non-space htokeni in the input stream has the same category code as the
htest tokeni (as defined by the test \token_if_eq_catcode:NNTF). Explicit and implicit
space tokens (with character code 32 and category code 10) are ignored and removed
by the test and the htokeni will be removed from the input stream if the test is true.
The function will then place either the htrue codei or hfalse codei in the input stream (as
appropriate to the result of the test).

\peek_charcode:NTF \peek_charcode:NTF htest token i {htrue code i} {hfalse code i}

Updated: 2012-12-20 Tests if the next htokeni in the input stream has the same character code as the htest
tokeni (as defined by the test \token_if_eq_charcode:NNTF). Spaces are respected by
the test and the htokeni will be left in the input stream after the htrue codei or hfalse
codei (as appropriate to the result of the test).

\peek_charcode_ignore_spaces:NTF \peek_charcode_ignore_spaces:NTF htest token i {htrue code i} {hfalse

code i}
Updated: 2012-12-20

Tests if the next non-space htokeni in the input stream has the same character code as the
htest tokeni (as defined by the test \token_if_eq_charcode:NNTF). Explicit and implicit
space tokens (with character code 32 and category code 10) are ignored and removed by
the test and the htokeni will be left in the input stream after the htrue codei or hfalse
codei (as appropriate to the result of the test).

\peek_charcode_remove:NTF \peek_charcode_remove:NTF htest token i {htrue code i} {hfalse code i}

Updated: 2012-12-20 Tests if the next htokeni in the input stream has the same character code as the htest
tokeni (as defined by the test \token_if_eq_charcode:NNTF). Spaces are respected by
the test and the htokeni will be removed from the input stream if the test is true. The
function will then place either the htrue codei or hfalse codei in the input stream (as
appropriate to the result of the test).

58
 \peek_charcode_remove_ignore_spaces:NTF \peek_charcode_remove_ignore_spaces:NTF htest token i
{htrue code i} {hfalse code i}
Updated: 2012-12-20

Tests if the next non-space htokeni in the input stream has the same character code as the
htest tokeni (as defined by the test \token_if_eq_charcode:NNTF). Explicit and implicit
space tokens (with character code 32 and category code 10) are ignored and removed by
the test and the htokeni will be removed from the input stream if the test is true. The
function will then place either the htrue codei or hfalse codei in the input stream (as
appropriate to the result of the test).

\peek_meaning:NTF \peek_meaning:NTF htest token i {htrue code i} {hfalse code i}

Updated: 2011-07-02 Tests if the next htokeni in the input stream has the same meaning as the htest tokeni
(as defined by the test \token_if_eq_meaning:NNTF). Spaces are respected by the test
and the htokeni will be left in the input stream after the htrue codei or hfalse codei (as
appropriate to the result of the test).

\peek_meaning_ignore_spaces:NTF \peek_meaning_ignore_spaces:NTF htest token i {htrue code i} {hfalse

code i}
Updated: 2012-12-05

Tests if the next non-space htokeni in the input stream has the same meaning as the htest
tokeni (as defined by the test \token_if_eq_meaning:NNTF). Explicit and implicit space
tokens (with character code 32 and category code 10) are ignored and removed by the
test and the htokeni will be left in the input stream after the htrue codei or hfalse codei
(as appropriate to the result of the test).

\peek_meaning_remove:NTF \peek_meaning_remove:NTF htest token i {htrue code i} {hfalse code i}

Updated: 2011-07-02 Tests if the next htokeni in the input stream has the same meaning as the htest tokeni
(as defined by the test \token_if_eq_meaning:NNTF). Spaces are respected by the test
and the htokeni will be removed from the input stream if the test is true. The function
will then place either the htrue codei or hfalse codei in the input stream (as appropriate
to the result of the test).

\peek_meaning_remove_ignore_spaces:NTF \peek_meaning_remove_ignore_spaces:NTF htest token i

{htrue code i} {hfalse code i}
Updated: 2012-12-05

Tests if the next non-space htokeni in the input stream has the same meaning as the
htest tokeni (as defined by the test \token_if_eq_meaning:NNTF). Explicit and implicit
space tokens (with character code 32 and category code 10) are ignored and removed
by the test and the htokeni will be removed from the input stream if the test is true.
The function will then place either the htrue codei or hfalse codei in the input stream (as
appropriate to the result of the test).

59
 7 Decomposing a macro definition
These functions decompose TEX macros into their constituent parts: if the htokeni passed
is not a macro then no decomposition can occur. In the later case, all three functions
leave \scan_stop: in the input stream.

\token_get_arg_spec:N ? \token_get_arg_spec:N htoken i

If the htokeni is a macro, this function will leave the primitive TEX argument specification
in input stream as a string of tokens of category code 12 (with spaces having category
code 10). Thus for example for a token \next defined by

\cs_set:Npn \next #1#2 { x #1 y #2 }

will leave #1#2 in the input stream. If the htokeni is not a macro then \scan_stop: will
be left in the input stream

TEXhackers note: If the arg spec. contains the string ->, then the spec function will
produce incorrect results.

\token_get_replacement_spec:N ? \token_get_replacement_spec:N htoken i

If the htokeni is a macro, this function will leave the replacement text in input stream as
a string of tokens of category code 12 (with spaces having category code 10). Thus for
example for a token \next defined by
\cs_set:Npn \next #1#2 { x #1~y #2 }

will leave x#1 y#2 in the input stream. If the htokeni is not a macro then \scan_stop:
will be left in the input stream

\token_get_prefix_spec:N ? \token_get_prefix_spec:N htoken i

If the htokeni is a macro, this function will leave the TEX prefixes applicable in input
stream as a string of tokens of category code 12 (with spaces having category code 10).
Thus for example for a token \next defined by

\cs_set:Npn \next #1#2 { x #1~y #2 }

will leave \long in the input stream. If the htokeni is not a macro then \scan_stop:
will be left in the input stream

60
 Part IX
The l3int package
Integers
Calculation and comparison of integer values can be carried out using literal numbers, int
registers, constants and integers stored in token list variables. The standard operators
+, -, / and * and parentheses can be used within such expressions to carry arithmetic
operations. This module carries out these functions on integer expressions (“intexpr”).

1 Integer expressions

\int_eval:n ? \int_eval:n {hinteger expression i}

Evaluates the hinteger expressioni, expanding any integer and token list variables within
the hexpressioni to their content (without requiring \int_use:N/\tl_use:N) and apply-
ing the standard mathematical rules. For example both
\int_eval:n { 5 + 4 * 3 - ( 3 + 4 * 5 ) }

and
\tl_new:N \l_my_tl
\tl_set:Nn \l_my_tl { 5 }
\int_new:N \l_my_int
\int_set:Nn \l_my_int { 4 }
\int_eval:n { \l_my_tl + \l_my_int * 3 - ( 3 + 4 * 5 ) }
both evaluate to −6. The {hinteger expressioni} may contain the operators +, -, * and
/, along with parenthesis ( and ). After two expansions, \int_eval:n yields an hinteger
denotationi which is left in the input stream. This is not an hinternal integeri, and
therefore requires suitable termination if used in a TEX-style integer assignment.

\int_abs:n ? \int_abs:n {hinteger expression i}

Updated: 2012-09-26 Evaluates the hinteger expressioni as described for \int_eval:n and leaves the absolute
value of the result in the input stream as an hinteger denotationi after two expansions.

\int_div_round:nn ? \int_div_round:nn {hintexpr1 i} {hintexpr2 i}

Updated: 2012-09-26 Evaluates the two hinteger expressionsi as described earlier, then divides the first value
by the second, and rounds the result to the closest integer. Ties are rounded away from
zero. Note that this is identical to using / directly in an hinteger expressioni. The result
is left in the input stream as an hinteger denotationi after two expansions.

61
\int_div_truncate:nn ? \int_div_truncate:nn {hintexpr1 i} {hintexpr2 i}
Updated: 2012-02-09 Evaluates the two hinteger expressionsi as described earlier, then divides the first value
by the second, and rounds the result towards zero. Note that division using / rounds
the result. The result is left in the input stream as an hinteger denotationi after two
expansions.

\int_max:nn ? \int_max:nn {hintexpr1 i} {hintexpr2 i}

\int_min:nn ? \int_min:nn {hintexpr1 i} {hintexpr2 i}
Updated: 2012-09-26 Evaluates the hinteger expressionsi as described for \int_eval:n and leaves either the
larger or smaller value in the input stream as an hinteger denotationi after two expansions.

\int_mod:nn ? \int_mod:nn {hintexpr1 i} {hintexpr2 i}

Updated: 2012-09-26 Evaluates the two hinteger expressionsi as described earlier, then calculates the integer
remainder of dividing the first expression by the second. This is obtained by subtract-
ing \int_div_truncate:nn {hintexpr1 i} {hintexpr2 i} times hintexpr2 i from hintexpr1 i.
Thus, the result has the same sign as hintexpr1 i and its absolute value is strictly less than
that of hintexpr2 i. The result is left in the input stream as an hinteger denotationi after
two expansions.

2 Creating and initialising integers

\int_new:N \int_new:N hinteger i

\int_new:c
Creates a new hintegeri or raises an error if the name is already taken. The declaration
is global. The hintegeri will initially be equal to 0.

\int_const:Nn \int_const:Nn hinteger i {hinteger expression i}

\int_const:cn
Creates a new constant hintegeri or raises an error if the name is already taken. The
Updated: 2011-10-22 value of the hintegeri will be set globally to the hinteger expressioni.

\int_zero:N \int_zero:N hinteger i

\int_zero:c
Sets hintegeri to 0.
\int_gzero:N
\int_gzero:c

\int_zero_new:N \int_zero_new:N hinteger i

\int_zero_new:c
Ensures that the hintegeri exists globally by applying \int_new:N if necessary, then
\int_gzero_new:N
\int_gzero_new:c applies \int_(g)zero:N to leave the hintegeri set to zero.

New: 2011-12-13

62
\int_set_eq:NN \int_set_eq:NN hinteger1 i hinteger2 i
\int_set_eq:(cN|Nc|cc)
Sets the content of hinteger1 i equal to that of hinteger2 i.
\int_gset_eq:NN
\int_gset_eq:(cN|Nc|cc)

\int_if_exist_p:N ? \int_if_exist_p:N hint i

\int_if_exist_p:c ? \int_if_exist:NTF hint i {htrue code i} {hfalse code i}
\int_if_exist:NTF ? Tests whether the hinti is currently defined. This does not check that the hinti really is
\int_if_exist:cTF ?
an integer variable.
New: 2012-03-03

3 Setting and incrementing integers

\int_add:Nn \int_add:Nn hinteger i {hinteger expression i}

\int_add:cn
Adds the result of the hinteger expressioni to the current content of the hintegeri.
\int_gadd:Nn
\int_gadd:cn
Updated: 2011-10-22

\int_decr:N \int_decr:N hinteger i

\int_decr:c
Decreases the value stored in hintegeri by 1.
\int_gdecr:N
\int_gdecr:c

\int_incr:N \int_incr:N hinteger i

\int_incr:c
Increases the value stored in hintegeri by 1.
\int_gincr:N
\int_gincr:c

\int_set:Nn \int_set:Nn hinteger i {hinteger expression i}

\int_set:cn
Sets hintegeri to the value of hinteger expressioni, which must evaluate to an integer (as
\int_gset:Nn
\int_gset:cn described for \int_eval:n).

Updated: 2011-10-22

\int_sub:Nn \int_sub:Nn hinteger i {hinteger expression i}

\int_sub:cn
Subtracts the result of the hinteger expressioni from the current content of the hintegeri.
\int_gsub:Nn
\int_gsub:cn
Updated: 2011-10-22

63
 4 Using integers

\int_use:N ? \int_use:N hinteger i

\int_use:c ?
Recovers the content of an hintegeri and places it directly in the input stream. An
Updated: 2011-10-22 error will be raised if the variable does not exist or if it is invalid. Can be omitted
in places where an hintegeri is required (such as in the first and third arguments of
\int_compare:nNnTF).

TEXhackers note: \int_use:N is the TEX primitive \the: this is one of several LATEX3
names for this primitive.

5 Integer expression conditionals

\int_compare_p:nNn ? \int_compare_p:nNn {hintexpr1 i} hrelation i {hintexpr2 i}

\int_compare:nNnTF ? \int_compare:nNnTF
{hintexpr1 i} hrelation i {hintexpr2 i}
{htrue code i} {hfalse code i}
This function first evaluates each of the hinteger expressionsi as described for \int_-
eval:n. The two results are then compared using the hrelationi:
Equal =
Greater than >
Less than <

64
\int_compare_p:n ? \int_compare_p:n
\int_compare:nTF ? {
hintexpr1 i hrelation1 i
Updated: 2013-01-13
...
hintexprN i hrelationN i
hintexprN +1 i
}
\int_compare:nTF
{
hintexpr1 i hrelation1 i
...
hintexprN i hrelationN i
hintexprN +1 i
}
{htrue code i} {hfalse code i}
This function evaluates the hinteger expressionsi as described for \int_eval:n and com-
pares consecutive result using the corresponding hrelationi, namely it compares hintexpr1 i
and hintexpr2 i using the hrelation1 i, then hintexpr2 i and hintexpr3 i using the hrelation2 i,
until finally comparing hintexprN i and hintexprN +1 i using the hrelationN i. The test yields
true if all comparisons are true. Each hinteger expressioni is evaluated only once, and
the evaluation is lazy, in the sense that if one comparison is false, then no other hinteger
expressioni is evaluated and no other comparison is performed. The hrelationsi can be
any of the following:
Equal = or ==
Greater than or equal to >=
Greater than >
Less than or equal to <=
Less than <
Not equal !=

65
 \int_case:nnTF ? \int_case:nnTF {htest integer expression i}
{
New: 2013-07-24
{hintexpr case1 i} {hcode case1 i}
{hintexpr case2 i} {hcode case2 i}
...
{hintexpr casen i} {hcode casen i}
}
{htrue code i}
{hfalse code i}
This function evaluates the htest integer expressioni and compares this in turn to each
of the hinteger expression casesi. If the two are equal then the associated hcodei is left
in the input stream. If any of the cases are matched, the htrue codei is also inserted into
the input stream (after the code for the appropriate case), while if none match then the
hfalse codei is inserted. The function \int_case:nn, which does nothing if there is no
match, is also available. For example

\int_case:nnF
{ 2 * 5 }
{
{ 5 } { Small }
{ 4 + 6 } { Medium }
{ -2 * 10 } { Negative }
}
{ No idea! }
will leave “Medium” in the input stream.

\int_if_even_p:n ? \int_if_odd_p:n {hinteger expression i}

\int_if_even:nTF ? \int_if_odd:nTF {hinteger expression i}
\int_if_odd_p:n ? {htrue code i} {hfalse code i}
\int_if_odd:nTF ? This function first evaluates the hinteger expressioni as described for \int_eval:n. It
then evaluates if this is odd or even, as appropriate.

6 Integer expression loops

\int_do_until:nNnn I \int_do_until:nNnn {hintexpr1 i} hrelation i {hintexpr2 i} {hcode i}

Places the hcodei in the input stream for TEX to process, and then evaluates the rela-
tionship between the two hinteger expressionsi as described for \int_compare:nNnTF. If
the test is false then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is true.

66
\int_do_while:nNnn I \int_do_while:nNnn {hintexpr1 i} hrelation i {hintexpr2 i} {hcode i}
Places the hcodei in the input stream for TEX to process, and then evaluates the rela-
tionship between the two hinteger expressionsi as described for \int_compare:nNnTF. If
the test is true then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is false.

\int_until_do:nNnn I \int_until_do:nNnn {hintexpr1 i} hrelation i {hintexpr2 i} {hcode i}

Evaluates the relationship between the two hinteger expressionsi as described for \int_-
compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is false.
After the hcodei has been processed by TEX the test will be repeated, and a loop will
occur until the test is true.

\int_while_do:nNnn I \int_while_do:nNnn {hintexpr1 i} hrelation i {hintexpr2 i} {hcode i}

Evaluates the relationship between the two hinteger expressionsi as described for \int_-
compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is true.
After the hcodei has been processed by TEX the test will be repeated, and a loop will
occur until the test is false.

\int_do_until:nn I \int_do_until:nn {hinteger relation i} {hcode i}

Updated: 2013-01-13 Places the hcodei in the input stream for TEX to process, and then evaluates the hinteger
relationi as described for \int_compare:nTF. If the test is false then the hcodei will be
inserted into the input stream again and a loop will occur until the hrelationi is true.

\int_do_while:nn I \int_do_while:nn {hinteger relation i} {hcode i}

Updated: 2013-01-13 Places the hcodei in the input stream for TEX to process, and then evaluates the hinteger
relationi as described for \int_compare:nTF. If the test is true then the hcodei will be
inserted into the input stream again and a loop will occur until the hrelationi is false.

\int_until_do:nn I \int_until_do:nn {hintegerr elation i} {hcode i}

Updated: 2013-01-13 Evaluates the hinteger relationi as described for \int_compare:nTF, and then places the
hcodei in the input stream if the hrelationi is false. After the hcodei has been processed
by TEX the test will be repeated, and a loop will occur until the test is true.

\int_while_do:nn I \int_while_do:nn {hinteger relation i} {hcode i}

Updated: 2013-01-13 Evaluates the hinteger relationi as described for \int_compare:nTF, and then places the
hcodei in the input stream if the hrelationi is true. After the hcodei has been processed
by TEX the test will be repeated, and a loop will occur until the test is false.

67
 7 Integer step functions

\int_step_function:nnnN I \int_step_function:nnnN {hinitial value i} {hstep i} {hfinal value i} hfunction i

New: 2012-06-04 This function first evaluates the hinitial valuei, hstepi and hfinal valuei, all of which should
Updated: 2014-05-30 be integer expressions. The hfunctioni is then placed in front of each hvaluei from the
hinitial valuei to the hfinal valuei in turn (using hstepi between each hvaluei). The hstepi
must be non-zero. If the hstepi is positive, the loop stops when the hvaluei becomes larger
than the hfinal valuei. If the hstepi is negative, the loop stops when the hvaluei becomes
smaller than the hfinal valuei. The hfunctioni should absorb one numerical argument.
For example
\cs_set:Npn \my_func:n #1 { [I~saw~#1] \quad }
\int_step_function:nnnN { 1 } { 1 } { 5 } \my_func:n

would print
[I saw 1] [I saw 2] [I saw 3] [I saw 4] [I saw 5]

\int_step_inline:nnnn \int_step_inline:nnnn {hinitial value i} {hstep i} {hfinal value i} {hcode i}

New: 2012-06-04 This function first evaluates the hinitial valuei, hstepi and hfinal valuei, all of which
Updated: 2014-05-30 should be integer expressions. Then for each hvaluei from the hinitial valuei to the hfinal
valuei in turn (using hstepi between each hvaluei), the hcodei is inserted into the input
stream with #1 replaced by the current hvaluei. Thus the hcodei should define a function
of one argument (#1).

\int_step_variable:nnnNn \int_step_variable:nnnNn
{hinitial value i} {hstep i} {hfinal value i} htl var i {hcode i}
New: 2012-06-04
Updated: 2014-05-30 This function first evaluates the hinitial valuei, hstepi and hfinal valuei, all of which
should be integer expressions. Then for each hvaluei from the hinitial valuei to the hfinal
valuei in turn (using hstepi between each hvaluei), the hcodei is inserted into the input
stream, with the htl vari defined as the current hvaluei. Thus the hcodei should make
use of the htl vari.

8 Formatting integers
Integers can be placed into the output stream with formatting. These conversions apply
to any integer expressions.

\int_to_arabic:n ? \int_to_arabic:n {hinteger expression i}

Updated: 2011-10-22 Places the value of the hinteger expressioni in the input stream as digits, with category
code 12 (other).

68
 \int_to_alph:n ? \int_to_alph:n {hinteger expression i}
\int_to_Alph:n ?
Evaluates the hinteger expressioni and converts the result into a series of letters, which
Updated: 2011-09-17 are then left in the input stream. The conversion rule uses the 26 letters of the English
alphabet, in order, adding letters when necessary to increase the total possible range of
representable numbers. Thus
\int_to_alph:n { 1 }

places a in the input stream,

\int_to_alph:n { 26 }
is represented as z and

\int_to_alph:n { 27 }
is converted to aa. For conversions using other alphabets, use \int_to_symbols:nnn to
define an alphabet-specific function. The basic \int_to_alph:n and \int_to_Alph:n
functions should not be modified.

\int_to_symbols:nnn ? \int_to_symbols:nnn
{hinteger expression i} {htotal symbols i}
Updated: 2011-09-17
hvalue to symbol mapping i
This is the low-level function for conversion of an hinteger expressioni into a symbolic
form (which will often be letters). The htotal symbolsi available should be given as an
integer expression. Values are actually converted to symbols according to the hvalue to
symbol mappingi. This should be given as htotal symbolsi pairs of entries, a number and
the appropriate symbol. Thus the \int_to_alph:n function is defined as
\cs_new:Npn \int_to_alph:n #1
{
\int_to_symbols:nnn {#1} { 26 }
{
{ 1 } { a }
{ 2 } { b }
...
{ 26 } { z }
}
}

\int_to_bin:n ? \int_to_bin:n {hinteger expression i}

New: 2014-02-11 Calculates the value of the hinteger expressioni and places the binary representation of
the result in the input stream.

69
 \int_to_hex:n ? \int_to_hex:n {hinteger expression i}
\int_to_Hex:n ?
Calculates the value of the hinteger expressioni and places the hexadecimal (base 16)
New: 2014-02-11 representation of the result in the input stream. Letters are used for digits beyond 9:
lower case letters for \int_to_hex:n and upper case ones for \int_to_Hex:n.

\int_to_oct:n ? \int_to_oct:n {hinteger expression i}

New: 2014-02-11 Calculates the value of the hinteger expressioni and places the octal (base 8) representa-
tion of the result in the input stream.

\int_to_base:nn ? \int_to_base:nn {hinteger expression i} {hbase i}

\int_to_Base:nn ?
Calculates the value of the hinteger expressioni and converts it into the appropriate
Updated: 2014-02-11 representation in the hbasei; the later may be given as an integer expression. For bases
greater than 10 the higher “digits” are represented by letters from the English alphabet:
lower case letters for \int_to_base:n and upper case ones for \int_to_Base:n. The
maximum hbasei value is 36.

TEXhackers note: This is a generic version of \int_to_bin:n, etc.

\int_to_roman:n I \int_to_roman:n {hinteger expression i}

\int_to_Roman:n I
Places the value of the hinteger expressioni in the input stream as Roman numerals,
Updated: 2011-10-22 either lower case (\int_to_roman:n) or upper case (\int_to_Roman:n). The Roman
numerals are letters with category code 11 (letter).

9 Converting from other formats to integers

\int_from_alph:n ? \int_from_alph:n {hletters i}

Converts the hlettersi into the integer (base 10) representation and leaves this in the
input stream. The hlettersi are treated using the English alphabet only, with “a” equal
to 1 through to “z” equal to 26. Either lower or upper case letters may be used. This is
the inverse function of \int_to_alph:n.

\int_from_bin:n ? \int_from_bin:n {hbinary number i}

New: 2014-02-11 Converts the hbinary numberi into the integer (base 10) representation and leaves this in
the input stream.

\int_from_hex:n ? \int_from_hex:n {hhexadecimal number i}

New: 2014-02-11 Converts the hhexadecimal numberi into the integer (base 10) representation and leaves
this in the input stream. Digits greater than 9 may be represented in the hhexadecimal
numberi by upper or lower case letters.

70
 \int_from_oct:n ? \int_from_oct:n {hoctal number i}
New: 2014-02-11 Converts the hoctal numberi into the integer (base 10) representation and leaves this in
the input stream.

\int_from_roman:n ? \int_from_roman:n {hroman numeral i}

Converts the hroman numerali into the integer (base 10) representation and leaves this
in the input stream. The hroman numerali may be in upper or lower case; if the numeral
is not valid then the resulting value will be −1.

\int_from_base:nn ? \int_from_base:nn {hnumber i} {hbase i}

Converts the hnumberi in hbasei into the appropriate value in base 10. The hnumberi
should consist of digits and letters (either lower or upper case), plus optionally a leading
sign. The maximum hbasei value is 36.

10 Viewing integers

\int_show:N \int_show:N hinteger i

\int_show:c
Displays the value of the hintegeri on the terminal.

\int_show:n \int_show:n hinteger expression i

New: 2011-11-22 Displays the result of evaluating the hinteger expressioni on the terminal.
Updated: 2012-05-27

71
 11 Constant integers

\c_minus_one Integer values used with primitive tests and assignments: self-terminating nature makes
\c_zero these more convenient and faster than literal numbers.
\c_one
\c_two
\c_three
\c_four
\c_five
\c_six
\c_seven
\c_eight
\c_nine
\c_ten
\c_eleven
\c_twelve
\c_thirteen
\c_fourteen
\c_fifteen
\c_sixteen
\c_thirty_two
\c_one_hundred
\c_two_hundred_fifty_five
\c_two_hundred_fifty_six
\c_one_thousand
\c_ten_thousand

\c_max_int The maximum value that can be stored as an integer.

\c_max_register_int Maximum number of registers.

12 Scratch integers

\l_tmpa_int Scratch integer for local assignment. These are never used by the kernel code, and so
\l_tmpb_int are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

\g_tmpa_int Scratch integer for global assignment. These are never used by the kernel code, and so
\g_tmpb_int are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

72
 13 Primitive conditionals

\if_int_compare:w ? \if_int_compare:w hinteger1 i hrelation i hinteger2 i

htrue code i
\else:
hfalse code i
\fi:
Compare two integers using hrelationi, which must be one of =, < or > with category code
12. The \else: branch is optional.

TEXhackers note: These are both names for the TEX primitive \ifnum.

\if_case:w ? \if_case:w hinteger i hcase0 i

\or: ? \or: hcase1 i
\or: ...
\else: hdefault i
\fi:
Selects a case to execute based on the value of the hintegeri. The first case (hcase0 i) is
executed if hintegeri is 0, the second (hcase1 i) if the hintegeri is 1, etc. The hintegeri
may be a literal, a constant or an integer expression (e.g. using \int_eval:n).

TEXhackers note: These are the TEX primitives \ifcase and \or.

\if_int_odd:w ? \if_int_odd:w htokens i hoptional space i

htrue code i
\else:
htrue code i
\fi:
Expands htokensi until a non-numeric token or a space is found, and tests whether the
resulting hintegeri is odd. If so, htrue codei is executed. The \else: branch is optional.

TEXhackers note: This is the TEX primitive \ifodd.

14 Internal functions

\__int_to_roman:w ? \__int_to_roman:w hinteger i hspace i or hnon-expandable token i

Converts hintegeri to it lower case Roman representation. Expansion ends when a space
or non-expandable token is found. Note that this function produces a string of letters with
category code 12 and that protected functions are expanded by this process. Negative
hintegeri values result in no output, although the function does not terminate expansion
until a suitable endpoint is found in the same way as for positive numbers.

TEXhackers note: This is the TEX primitive \romannumeral renamed.

73
 \__int_value:w ? \__int_value:w hinteger i
\__int_value:w htokens i hoptional space i
Expands htokensi until an hintegeri is formed. One space may be gobbled in the process.

TEXhackers note: This is the TEX primitive \number.

\__int_eval:w ? \__int_eval:w hintexpr i \__int_eval_end:

\__int_eval_end: ?
Evaluates hinteger expressioni as described for \int_eval:n. The evaluation stops when
an unexpandable token which is not a valid part of an integer is read or when \__int_-
eval_end: is reached. The latter is gobbled by the scanner mechanism: \__int_eval_-
end: itself is unexpandable but used correctly the entire construct is expandable.

TEXhackers note: This is the ε-TEX primitive \numexpr.

\__prg_compare_error: \__prg_compare_error:
\__prg_compare_error:Nw \__prg_compare_error:Nw htoken i
These are used within \int_compare:n(TF), \dim_compare:n(TF) and so on to recover
correctly if the n-type argument does not contain a properly-formed relation.

74
 Part X
The l3skip package
Dimensions and skips
LATEX3 provides two general length variables: dim and skip. Lengths stored as dim
variables have a fixed length, whereas skip lengths have a rubber (stretch/shrink) com-
ponent. In addition, the muskip type is available for use in math mode: this is a special
form of skip where the lengths involved are determined by the current math font (in
mu). There are common features in the creation and setting of length variables, but for
clarity the functions are grouped by variable type.

1 Creating and initialising dim variables

\dim_new:N \dim_new:N hdimension i

\dim_new:c
Creates a new hdimensioni or raises an error if the name is already taken. The declaration
is global. The hdimensioni will initially be equal to 0 pt.

\dim_const:Nn \dim_const:Nn hdimension i {hdimension expression i}

\dim_const:cn
Creates a new constant hdimensioni or raises an error if the name is already taken. The
New: 2012-03-05 value of the hdimensioni will be set globally to the hdimension expressioni.

\dim_zero:N \dim_zero:N hdimension i

\dim_zero:c
Sets hdimensioni to 0 pt.
\dim_gzero:N
\dim_gzero:c

\dim_zero_new:N \dim_zero_new:N hdimension i

\dim_zero_new:c
Ensures that the hdimensioni exists globally by applying \dim_new:N if necessary, then
\dim_gzero_new:N
\dim_gzero_new:c applies \dim_(g)zero:N to leave the hdimensioni set to zero.

New: 2012-01-07

\dim_if_exist_p:N ? \dim_if_exist_p:N hdimension i

\dim_if_exist_p:c ? \dim_if_exist:NTF hdimension i {htrue code i} {hfalse code i}
\dim_if_exist:NTF ? Tests whether the hdimensioni is currently defined. This does not check that the
\dim_if_exist:cTF ?
hdimensioni really is a dimension variable.
New: 2012-03-03

75
 2 Setting dim variables

\dim_add:Nn \dim_add:Nn hdimension i {hdimension expression i}

\dim_add:cn
Adds the result of the hdimension expressioni to the current content of the hdimensioni.
\dim_gadd:Nn
\dim_gadd:cn
Updated: 2011-10-22

\dim_set:Nn \dim_set:Nn hdimension i {hdimension expression i}

\dim_set:cn
Sets hdimensioni to the value of hdimension expressioni, which must evaluate to a length
\dim_gset:Nn
\dim_gset:cn with units.

Updated: 2011-10-22

\dim_set_eq:NN \dim_set_eq:NN hdimension1 i hdimension2 i

\dim_set_eq:(cN|Nc|cc)
Sets the content of hdimension1 i equal to that of hdimension2 i.
\dim_gset_eq:NN
\dim_gset_eq:(cN|Nc|cc)

\dim_sub:Nn \dim_sub:Nn hdimension i {hdimension expression i}

\dim_sub:cn
Subtracts the result of the hdimension expressioni from the current content of the
\dim_gsub:Nn
\dim_gsub:cn hdimensioni.

Updated: 2011-10-22

3 Utilities for dimension calculations

\dim_abs:n ? \dim_abs:n {hdimexpr i}

Updated: 2012-09-26 Converts the hdimexpri to its absolute value, leaving the result in the input stream as a
hdimension denotationi.

\dim_max:nn ? \dim_max:nn {hdimexpr1 i} {hdimexpr2 i}

\dim_min:nn ? \dim_min:nn {hdimexpr1 i} {hdimexpr2 i}
New: 2012-09-09 Evaluates the two hdimension expressionsi and leaves either the maximum or minimum
Updated: 2012-09-26 value in the input stream as appropriate, as a hdimension denotationi.

76
 \dim_ratio:nn I \dim_ratio:nn {hdimexpr1 i} {hdimexpr2 i}
Updated: 2011-10-22 Parses the two hdimension expressionsi and converts the ratio of the two to a form
suitable for use inside a hdimension expressioni. This ratio is then left in the input
stream, allowing syntax such as
\dim_set:Nn \l_my_dim
{ 10 pt * \dim_ratio:nn { 5 pt } { 10 pt } }

The output of \dim_ratio:nn on full expansion is a ration expression between two

integers, with all distances converted to scaled points. Thus
\tl_set:Nx \l_my_tl { \dim_ratio:nn { 5 pt } { 10 pt } }
\tl_show:N \l_my_tl

will display 327680/655360 on the terminal.

4 Dimension expression conditionals

\dim_compare_p:nNn ? \dim_compare_p:nNn {hdimexpr1 i} hrelation i {hdimexpr2 i}

\dim_compare:nNnTF ? \dim_compare:nNnTF
{hdimexpr1 i} hrelation i {hdimexpr2 i}
{htrue code i} {hfalse code i}
This function first evaluates each of the hdimension expressionsi as described for \dim_-
eval:n. The two results are then compared using the hrelationi:
Equal =
Greater than >
Less than <

77
\dim_compare_p:n ? \dim_compare_p:n
\dim_compare:nTF ? {
hdimexpr1 i hrelation1 i
Updated: 2013-01-13
...
hdimexprN i hrelationN i
hdimexprN +1 i
}
\dim_compare:nTF
{
hdimexpr1 i hrelation1 i
...
hdimexprN i hrelationN i
hdimexprN +1 i
}
{htrue code i} {hfalse code i}
This function evaluates the hdimension expressionsi as described for \dim_eval:n and
compares consecutive result using the corresponding hrelationi, namely it compares
hdimexpr1 i and hdimexpr2 i using the hrelation1 i, then hdimexpr2 i and hdimexpr3 i us-
ing the hrelation2 i, until finally comparing hdimexprN i and hdimexprN +1 i using the
hrelationN i. The test yields true if all comparisons are true. Each hdimension
expressioni is evaluated only once, and the evaluation is lazy, in the sense that if one
comparison is false, then no other hdimension expressioni is evaluated and no other
comparison is performed. The hrelationsi can be any of the following:
Equal = or ==
Greater than or equal to >=
Greater than >
Less than or equal to <=
Less than <
Not equal !=

78
 \dim_case:nnTF ? \dim_case:nnTF {htest dimension expression i}
{
New: 2013-07-24
{hdimexpr case1 i} {hcode case1 i}
{hdimexpr case2 i} {hcode case2 i}
...
{hdimexpr casen i} {hcode casen i}
}
{htrue code i}
{hfalse code i}
This function evaluates the htest dimension expressioni and compares this in turn to each
of the hdimension expression casesi. If the two are equal then the associated hcodei is
left in the input stream. If any of the cases are matched, the htrue codei is also inserted
into the input stream (after the code for the appropriate case), while if none match then
the hfalse codei is inserted. The function \dim_case:nn, which does nothing if there is
no match, is also available. For example

\dim_set:Nn \l_tmpa_dim { 5 pt }
\dim_case:nnF
{ 2 \l_tmpa_dim }
{
{ 5 pt } { Small }
{ 4 pt + 6 pt } { Medium }
{ - 10 pt } { Negative }
}
{ No idea! }
will leave “Medium” in the input stream.

5 Dimension expression loops

\dim_do_until:nNnn I \dim_do_until:nNnn {hdimexpr1 i} hrelation i {hdimexpr2 i} {hcode i}

Places the hcodei in the input stream for TEX to process, and then evaluates the relation-
ship between the two hdimension expressionsi as described for \dim_compare:nNnTF. If
the test is false then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is true.

\dim_do_while:nNnn I \dim_do_while:nNnn {hdimexpr1 i} hrelation i {hdimexpr2 i} {hcode i}

Places the hcodei in the input stream for TEX to process, and then evaluates the relation-
ship between the two hdimension expressionsi as described for \dim_compare:nNnTF. If
the test is true then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is false.

79
\dim_until_do:nNnn I \dim_until_do:nNnn {hdimexpr1 i} hrelation i {hdimexpr2 i} {hcode i}
Evaluates the relationship between the two hdimension expressionsi as described for
\dim_compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is
false. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is true.

\dim_while_do:nNnn I \dim_while_do:nNnn {hdimexpr1 i} hrelation i {hdimexpr2 i} {hcode i}

Evaluates the relationship between the two hdimension expressionsi as described for
\dim_compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is
true. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is false.

\dim_do_until:nn I \dim_do_until:nn {hdimension relation i} {hcode i}

Updated: 2013-01-13 Places the hcodei in the input stream for TEX to process, and then evaluates the
hdimension relationi as described for \dim_compare:nTF. If the test is false then the
hcodei will be inserted into the input stream again and a loop will occur until the hrelationi
is true.

\dim_do_while:nn I \dim_do_while:nn {hdimension relation i} {hcode i}

Updated: 2013-01-13 Places the hcodei in the input stream for TEX to process, and then evaluates the
hdimension relationi as described for \dim_compare:nTF. If the test is true then the
hcodei will be inserted into the input stream again and a loop will occur until the hrelationi
is false.

\dim_until_do:nn I \dim_until_do:nn {hdimension relation i} {hcode i}

Updated: 2013-01-13 Evaluates the hdimension relationi as described for \dim_compare:nTF, and then places
the hcodei in the input stream if the hrelationi is false. After the hcodei has been
processed by TEX the test will be repeated, and a loop will occur until the test is true.

\dim_while_do:nn I \dim_while_do:nn {hdimension relation i} {hcode i}

Updated: 2013-01-13 Evaluates the hdimension relationi as described for \dim_compare:nTF, and then places
the hcodei in the input stream if the hrelationi is true. After the hcodei has been processed
by TEX the test will be repeated, and a loop will occur until the test is false.

6 Using dim expressions and variables

\dim_eval:n ? \dim_eval:n {hdimension expression i}

Updated: 2011-10-22 Evaluates the hdimension expressioni, expanding any dimensions and token list variables
within the hexpressioni to their content (without requiring \dim_use:N/\tl_use:N) and
applying the standard mathematical rules. The result of the calculation is left in the
input stream as a hdimension denotationi after two expansions. This will be expressed
in points (pt), and will require suitable termination if used in a TEX-style assignment as
it is not an hinternal dimensioni.

80
 \dim_use:N ? \dim_use:N hdimension i
\dim_use:c ?
Recovers the content of a hdimensioni and places it directly in the input stream. An
error will be raised if the variable does not exist or if it is invalid. Can be omitted in
places where a hdimensioni is required (such as in the argument of \dim_eval:n).

TEXhackers note: \dim_use:N is the TEX primitive \the: this is one of several LATEX3
names for this primitive.

\dim_to_decimal:n ? \dim_to_decimal:n {hdimexpr i}

New: 2014-07-15 Evaluates the hdimension expressioni, and leaves the result, expressed in points (pt) in
the input stream, with no units. The result is rounded by TEX to four or five decimal
places. If the decimal part of the result is zero, it is omitted, together with the decimal
marker.
For example

\dim_to_decimal:n { 1bp }
leaves 1.00374 in the input stream, i.e. the magnitude of one “big point” when converted
to (TEX) points.

\dim_to_decimal_in_bp:n ? \dim_to_decimal_in_bp:n {hdimexpr i}

New: 2014-07-15 Evaluates the hdimension expressioni, and leaves the result, expressed in big points (bp)
in the input stream, with no units. The result is rounded by TEX to four or five decimal
places. If the decimal part of the result is zero, it is omitted, together with the decimal
marker.
For example

\dim_to_decimal_in_bp:n { 1pt }
leaves 0.99628 in the input stream, i.e. the magnitude of one (TEX) point when converted
to big points.

\dim_to_decimal_in_unit:nn ? \dim_to_decimal_in_unit:nn {hdimexpr1 i} {hdimexpr2 i}

New: 2014-07-15

Evaluates the hdimension expressionsi, and leaves the value of hdimexpr1 i, expressed in a
unit given by hdimexpr2 i, in the input stream. The result is a decimal number, rounded
by TEX to four or five decimal places. If the decimal part of the result is zero, it is
omitted, together with the decimal marker.
For example
\dim_to_decimal_in_unit:nn { 1bp } { 1mm }
leaves 0.35277 in the input stream, i.e. the magnitude of one big point when converted
to millimetres.

81
\dim_to_fp:n ? \dim_to_fp:n {hdimexpr i}
New: 2012-05-08 Expands to an internal floating point number equal to the value of the hdimexpri in
pt. Since dimension expressions are evaluated much faster than their floating point
equivalent, \dim_to_fp:n can be used to speed up parts of a computation where a low
precision is acceptable.

7 Viewing dim variables

\dim_show:N \dim_show:N hdimension i

\dim_show:c
Displays the value of the hdimensioni on the terminal.

\dim_show:n \dim_show:n hdimension expression i

New: 2011-11-22 Displays the result of evaluating the hdimension expressioni on the terminal.
Updated: 2012-05-27

8 Constant dimensions

\c_max_dim The maximum value that can be stored as a dimension. This can also be used as a
component of a skip.

\c_zero_dim A zero length as a dimension. This can also be used as a component of a skip.

9 Scratch dimensions

\l_tmpa_dim Scratch dimension for local assignment. These are never used by the kernel code, and so
\l_tmpb_dim are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

\g_tmpa_dim Scratch dimension for global assignment. These are never used by the kernel code, and
\g_tmpb_dim so are safe for use with any LATEX3-defined function. However, they may be overwritten
by other non-kernel code and so should only be used for short-term storage.

82
 10 Creating and initialising skip variables

\skip_new:N \skip_new:N hskip i

\skip_new:c
Creates a new hskipi or raises an error if the name is already taken. The declaration is
global. The hskipi will initially be equal to 0 pt.

\skip_const:Nn \skip_const:Nn hskip i {hskip expression i}

\skip_const:cn
Creates a new constant hskipi or raises an error if the name is already taken. The value
New: 2012-03-05 of the hskipi will be set globally to the hskip expressioni.

\skip_zero:N \skip_zero:N hskip i

\skip_zero:c
Sets hskipi to 0 pt.
\skip_gzero:N
\skip_gzero:c

\skip_zero_new:N \skip_zero_new:N hskip i

\skip_zero_new:c
Ensures that the hskipi exists globally by applying \skip_new:N if necessary, then applies
\skip_gzero_new:N
\skip_gzero_new:c \skip_(g)zero:N to leave the hskipi set to zero.

New: 2012-01-07

\skip_if_exist_p:N ? \skip_if_exist_p:N hskip i

\skip_if_exist_p:c ? \skip_if_exist:NTF hskip i {htrue code i} {hfalse code i}
\skip_if_exist:NTF ? Tests whether the hskipi is currently defined. This does not check that the hskipi really
\skip_if_exist:cTF ?
is a skip variable.
New: 2012-03-03

11 Setting skip variables

\skip_add:Nn \skip_add:Nn hskip i {hskip expression i}

\skip_add:cn
Adds the result of the hskip expressioni to the current content of the hskipi.
\skip_gadd:Nn
\skip_gadd:cn
Updated: 2011-10-22

\skip_set:Nn \skip_set:Nn hskip i {hskip expression i}

\skip_set:cn
Sets hskipi to the value of hskip expressioni, which must evaluate to a length with units
\skip_gset:Nn
\skip_gset:cn and may include a rubber component (for example 1 cm plus 0.5 cm.

Updated: 2011-10-22

83
\skip_set_eq:NN \skip_set_eq:NN hskip1 i hskip2 i
\skip_set_eq:(cN|Nc|cc)
Sets the content of hskip1 i equal to that of hskip2 i.
\skip_gset_eq:NN
\skip_gset_eq:(cN|Nc|cc)

\skip_sub:Nn \skip_sub:Nn hskip i {hskip expression i}

\skip_sub:cn
Subtracts the result of the hskip expressioni from the current content of the hskipi.
\skip_gsub:Nn
\skip_gsub:cn
Updated: 2011-10-22

12 Skip expression conditionals

\skip_if_eq_p:nn ? \skip_if_eq_p:nn {hskipexpr1 i} {hskipexpr2 i}

\skip_if_eq:nnTF ? \dim_compare:nTF
{hskipexpr1 i} {hskipexpr2 i}
{htrue code i} {hfalse code i}
This function first evaluates each of the hskip expressionsi as described for \skip_-
eval:n. The two results are then compared for exact equality, i.e. both the fixed and
rubber components must be the same for the test to be true.

\skip_if_finite_p:n ? \skip_if_finite_p:n {hskipexpr i}

\skip_if_finite:nTF ? \skip_if_finite:nTF {hskipexpr i} {htrue code i} {hfalse code i}
New: 2012-03-05 Evaluates the hskip expressioni as described for \skip_eval:n, and then tests if all of
its components are finite.

13 Using skip expressions and variables

\skip_eval:n ? \skip_eval:n {hskip expression i}

Updated: 2011-10-22 Evaluates the hskip expressioni, expanding any skips and token list variables within the
hexpressioni to their content (without requiring \skip_use:N/\tl_use:N) and applying
the standard mathematical rules. The result of the calculation is left in the input stream
as a hglue denotationi after two expansions. This will be expressed in points (pt), and
will require suitable termination if used in a TEX-style assignment as it is not an hinternal
gluei.

84
 \skip_use:N ? \skip_use:N hskip i
\skip_use:c ?
Recovers the content of a hskipi and places it directly in the input stream. An error will
be raised if the variable does not exist or if it is invalid. Can be omitted in places where
a hdimensioni is required (such as in the argument of \skip_eval:n).

TEXhackers note: \skip_use:N is the TEX primitive \the: this is one of several LATEX3
names for this primitive.

14 Viewing skip variables

\skip_show:N \skip_show:N hskip i

\skip_show:c
Displays the value of the hskipi on the terminal.

\skip_show:n \skip_show:n hskip expression i

New: 2011-11-22 Displays the result of evaluating the hskip expressioni on the terminal.
Updated: 2012-05-27

15 Constant skips

\c_max_skip The maximum value that can be stored as a skip (equal to \c_max_dim in length), with
Updated: 2012-11-02 no stretch nor shrink component.

\c_zero_skip A zero length as a skip, with no stretch nor shrink component.

Updated: 2012-11-01

16 Scratch skips

\l_tmpa_skip Scratch skip for local assignment. These are never used by the kernel code, and so are
\l_tmpb_skip safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

\g_tmpa_skip Scratch skip for global assignment. These are never used by the kernel code, and so are
\g_tmpb_skip safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

85
 17 Inserting skips into the output

\skip_horizontal:N \skip_horizontal:N hskip i

\skip_horizontal:(c|n) \skip_horizontal:n {hskipexpr i}
Updated: 2011-10-22 Inserts a horizontal hskipi into the current list.

TEXhackers note: \skip_horizontal:N is the TEX primitive \hskip renamed.

\skip_vertical:N \skip_vertical:N hskip i

\skip_vertical:(c|n) \skip_vertical:n {hskipexpr i}
Updated: 2011-10-22 Inserts a vertical hskipi into the current list.

TEXhackers note: \skip_vertical:N is the TEX primitive \vskip renamed.

18 Creating and initialising muskip variables

\muskip_new:N \muskip_new:N hmuskip i

\muskip_new:c
Creates a new hmuskipi or raises an error if the name is already taken. The declaration
is global. The hmuskipi will initially be equal to 0 mu.

\muskip_const:Nn \muskip_const:Nn hmuskip i {hmuskip expression i}

\muskip_const:cn
Creates a new constant hmuskipi or raises an error if the name is already taken. The
New: 2012-03-05 value of the hmuskipi will be set globally to the hmuskip expressioni.

\muskip_zero:N \skip_zero:N hmuskip i

\muskip_zero:c
Sets hmuskipi to 0 mu.
\muskip_gzero:N
\muskip_gzero:c

\muskip_zero_new:N \muskip_zero_new:N hmuskip i

\muskip_zero_new:c
Ensures that the hmuskipi exists globally by applying \muskip_new:N if necessary, then
\muskip_gzero_new:N
\muskip_gzero_new:c applies \muskip_(g)zero:N to leave the hmuskipi set to zero.

New: 2012-01-07

\muskip_if_exist_p:N ? \muskip_if_exist_p:N hmuskip i

\muskip_if_exist_p:c ? \muskip_if_exist:NTF hmuskip i {htrue code i} {hfalse code i}
\muskip_if_exist:NTF ? Tests whether the hmuskipi is currently defined. This does not check that the hmuskipi
\muskip_if_exist:cTF ?
really is a muskip variable.
New: 2012-03-03

86
 19 Setting muskip variables

\muskip_add:Nn \muskip_add:Nn hmuskip i {hmuskip expression i}

\muskip_add:cn
Adds the result of the hmuskip expressioni to the current content of the hmuskipi.
\muskip_gadd:Nn
\muskip_gadd:cn
Updated: 2011-10-22

\muskip_set:Nn \muskip_set:Nn hmuskip i {hmuskip expression i}

\muskip_set:cn
Sets hmuskipi to the value of hmuskip expressioni, which must evaluate to a math length
\muskip_gset:Nn
\muskip_gset:cn with units and may include a rubber component (for example 1 mu plus 0.5 mu.

Updated: 2011-10-22

\muskip_set_eq:NN \muskip_set_eq:NN hmuskip1 i hmuskip2 i

\muskip_set_eq:(cN|Nc|cc)
Sets the content of hmuskip1 i equal to that of hmuskip2 i.
\muskip_gset_eq:NN
\muskip_gset_eq:(cN|Nc|cc)

\muskip_sub:Nn \muskip_sub:Nn hmuskip i {hmuskip expression i}

\muskip_sub:cn
Subtracts the result of the hmuskip expressioni from the current content of the hskipi.
\muskip_gsub:Nn
\muskip_gsub:cn
Updated: 2011-10-22

20 Using muskip expressions and variables

\muskip_eval:n ? \muskip_eval:n {hmuskip expression i}

Updated: 2011-10-22 Evaluates the hmuskip expressioni, expanding any skips and token list variables within
the hexpressioni to their content (without requiring \muskip_use:N/\tl_use:N) and
applying the standard mathematical rules. The result of the calculation is left in the
input stream as a hmuglue denotationi after two expansions. This will be expressed in
mu, and will require suitable termination if used in a TEX-style assignment as it is not an
hinternal mugluei.

\muskip_use:N ? \muskip_use:N hmuskip i

\muskip_use:c ?
Recovers the content of a hskipi and places it directly in the input stream. An error will
be raised if the variable does not exist or if it is invalid. Can be omitted in places where
a hdimensioni is required (such as in the argument of \muskip_eval:n).

TEXhackers note: \muskip_use:N is the TEX primitive \the: this is one of several LATEX3
names for this primitive.

87
 21 Viewing muskip variables

\muskip_show:N \muskip_show:N hmuskip i

\muskip_show:c
Displays the value of the hmuskipi on the terminal.

\muskip_show:n \muskip_show:n hmuskip expression i

New: 2011-11-22 Displays the result of evaluating the hmuskip expressioni on the terminal.
Updated: 2012-05-27

22 Constant muskips

\c_max_muskip The maximum value that can be stored as a muskip, with no stretch nor shrink compo-
nent.

\c_zero_muskip A zero length as a muskip, with no stretch nor shrink component.

23 Scratch muskips

\l_tmpa_muskip Scratch muskip for local assignment. These are never used by the kernel code, and so
\l_tmpb_muskip are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

\g_tmpa_muskip Scratch muskip for global assignment. These are never used by the kernel code, and so
\g_tmpb_muskip are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

24 Primitive conditional

\if_dim:w \if_dim:w hdimen1 i hrelation i hdimen2 i

htrue code i
\else:
hfalse i
\fi:
Compare two dimensions. The hrelationi is one of <, = or > with category code 12.

TEXhackers note: This is the TEX primitive \ifdim.

88
 25 Internal functions

\__dim_eval:w ? \__dim_eval:w hdimexpr i \__dim_eval_end:

\__dim_eval_end: ?
Evaluates hdimension expressioni as described for \dim_eval:n. The evaluation stops
when an unexpandable token which is not a valid part of a dimension is read or when \_-
_dim_eval_end: is reached. The latter is gobbled by the scanner mechanism: \__dim_-
eval_end: itself is unexpandable but used correctly the entire construct is expandable.

TEXhackers note: This is the ε-TEX primitive \dimexpr.

89
Part XI
The l3tl package
Token lists
TEX works with tokens, and LATEX3 therefore provides a number of functions to deal with
lists of tokens. Token lists may be present directly in the argument to a function:

\foo:n { a collection of \tokens }

or may be stored in a so-called “token list variable”, which have the suffix tl: a token
list variable can also be used as the argument to a function, for example
\foo:N \l_some_tl

In both cases, functions are available to test an manipulate the lists of tokens, and these
have the module prefix tl. In many cases, function which can be applied to token list
variables are paired with similar functions for application to explicit lists of tokens: the
two “views” of a token list are therefore collected together here.
A token list (explicit, or stored in a variable) can be seen either as a list of “items”,
or a list of “tokens”. An item is whatever \use:n would grab as its argument: a single
non-space token or a brace group, with optional leading explicit space characters (each
item is thus itself a token list). A token is either a normal N argument, or ␣, {, or }
(assuming normal TEX category codes). Thus for example
{ Hello } ~ world

contains six items (Hello, w, o, r, l and d), but thirteen tokens ({, H, e, l, l, o, }, ␣, w,
o, r, l and d). Functions which act on items are often faster than their analogue acting
directly on tokens.
TEXhackers note: When TEX fetches an undelimited argument from the input stream,
explicit character tokens with character code 32 (space) and category code 10 (space), which we
here call “explicit space characters”, are ignored. If the following token is an explicit character
token with category code 1 (begin-group) and an arbitrary character code, then TEX scans ahead
to obtain an equal number of explicit character tokens with category code 1 (begin-group) and 2
(end-group), and the resulting list of tokens (with outer braces removed) becomes the argument.
Otherwise, a single token is taken as the argument for the macro: we call such single tokens
“N-type”, as they are suitable to be used as an argument for a function with the signature :N.
When TEX reads a character of category code 10 for the first time, it is converted to an
explicit space character, with character code 32, regardless of the initial character code. “Funny”
spaces with a different category code, can be produced using \tl_to_lowercase:n or \tl_to_-
uppercase:n. Explicit space characters are also produced as a result of \token_to_str:N,
\tl_to_str:n, etc.

90
 1 Creating and initialising token list variables

\tl_new:N \tl_new:N htl var i

\tl_new:c
Creates a new htl vari or raises an error if the name is already taken. The declaration is
global. The htl vari will initially be empty.

\tl_const:Nn \tl_const:Nn htl var i {htoken list i}

\tl_const:(Nx|cn|cx)
Creates a new constant htl vari or raises an error if the name is already taken. The value
of the htl vari will be set globally to the htoken listi.

\tl_clear:N \tl_clear:N htl var i

\tl_clear:c
Clears all entries from the htl vari.
\tl_gclear:N
\tl_gclear:c

\tl_clear_new:N \tl_clear_new:N htl var i

\tl_clear_new:c
Ensures that the htl vari exists globally by applying \tl_new:N if necessary, then applies
\tl_gclear_new:N
\tl_gclear_new:c \tl_(g)clear:N to leave the htl vari empty.

\tl_set_eq:NN \tl_set_eq:NN htl var1 i htl var2 i

\tl_set_eq:(cN|Nc|cc)
Sets the content of htl var1 i equal to that of htl var2 i.
\tl_gset_eq:NN
\tl_gset_eq:(cN|Nc|cc)

\tl_concat:NNN \tl_concat:NNN htl var1 i htl var2 i htl var3 i

\tl_concat:ccc
Concatenates the content of htl var2 i and htl var3 i together and saves the result in
\tl_gconcat:NNN
\tl_gconcat:ccc htl var1 i. The htl var2 i will be placed at the left side of the new token list.

New: 2012-05-18

\tl_if_exist_p:N ? \tl_if_exist_p:N htl var i

\tl_if_exist_p:c ? \tl_if_exist:NTF htl var i {htrue code i} {hfalse code i}
\tl_if_exist:NTF ? Tests whether the htl vari is currently defined. This does not check that the htl vari
\tl_if_exist:cTF ?
really is a token list variable.
New: 2012-03-03

91
 2 Adding data to token list variables

\tl_set:Nn \tl_set:Nn htl var i {htokens i}

\tl_set:(NV|Nv|No|Nf|Nx|cn|cV|cv|co|cf|cx)
\tl_gset:Nn
\tl_gset:(NV|Nv|No|Nf|Nx|cn|cV|cv|co|cf|cx)

Sets htl vari to contain htokensi, removing any previous content from the variable.

\tl_put_left:Nn \tl_put_left:Nn htl var i {htokens i}

\tl_put_left:(NV|No|Nx|cn|cV|co|cx)
\tl_gput_left:Nn
\tl_gput_left:(NV|No|Nx|cn|cV|co|cx)

Appends htokensi to the left side of the current content of htl vari.

\tl_put_right:Nn \tl_put_right:Nn htl var i {htokens i}

\tl_put_right:(NV|No|Nx|cn|cV|co|cx)
\tl_gput_right:Nn
\tl_gput_right:(NV|No|Nx|cn|cV|co|cx)

Appends htokensi to the right side of the current content of htl vari.

3 Modifying token list variables

\tl_replace_once:Nnn \tl_replace_once:Nnn htl var i {hold tokens i} {hnew tokens i}

\tl_replace_once:cnn
Replaces the first (leftmost) occurrence of hold tokensi in the htl vari with hnew tokensi.
\tl_greplace_once:Nnn
\tl_greplace_once:cnn hOld tokensi cannot contain {, } or # (more precisely, explicit character tokens with
category code 1 (begin-group) or 2 (end-group), and tokens with category code 6).
Updated: 2011-08-11

\tl_replace_all:Nnn \tl_replace_all:Nnn htl var i {hold tokens i} {hnew tokens i}

\tl_replace_all:cnn
Replaces all occurrences of hold tokensi in the htl vari with hnew tokensi. hOld tokensi
\tl_greplace_all:Nnn
\tl_greplace_all:cnn cannot contain {, } or # (more precisely, explicit character tokens with category code
1 (begin-group) or 2 (end-group), and tokens with category code 6). As this function
Updated: 2011-08-11
operates from left to right, the pattern hold tokensi may remain after the replacement
(see \tl_remove_all:Nn for an example).

\tl_remove_once:Nn \tl_remove_once:Nn htl var i {htokens i}

\tl_remove_once:cn
Removes the first (leftmost) occurrence of htokensi from the htl vari. hTokensi cannot
\tl_gremove_once:Nn
\tl_gremove_once:cn contain {, } or # (more precisely, explicit character tokens with category code 1 (begin-
group) or 2 (end-group), and tokens with category code 6).
Updated: 2011-08-11

92
 \tl_remove_all:Nn \tl_remove_all:Nn htl var i {htokens i}
\tl_remove_all:cn
Removes all occurrences of htokensi from the htl vari. hTokensi cannot contain {, } or #
\tl_gremove_all:Nn
\tl_gremove_all:cn (more precisely, explicit character tokens with category code 1 (begin-group) or 2 (end-
group), and tokens with category code 6). As this function operates from left to right,
Updated: 2011-08-11
the pattern htokensi may remain after the removal, for instance,
\tl_set:Nn \l_tmpa_tl {abbccd} \tl_remove_all:Nn \l_tmpa_tl {bc}

will result in \l_tmpa_tl containing abcd.

4 Reassigning token list category codes

\tl_set_rescan:Nnn \tl_set_rescan:Nnn htl var i {hsetup i} {htokens i}

\tl_set_rescan:(Nno|Nnx|cnn|cno|cnx)
\tl_gset_rescan:Nnn
\tl_gset_rescan:(Nno|Nnx|cnn|cno|cnx)
Updated: 2011-12-18

Sets htl vari to contain htokensi, applying the category code régime specified in the
hsetupi before carrying out the assignment. This allows the htl vari to contain material
with category codes other than those that apply when htokensi are absorbed. Trailing
spaces at the end of the htokensi are discarded in the rescanning process. The hsetupi
is not limited to changes of category code but may contain any valid input, for example
assignment of the expansion of active tokens. See also \tl_rescan:nn.

\tl_rescan:nn \tl_rescan:nn {hsetup i} {htokens i}

Updated: 2011-12-18 Rescans htokensi applying the category code régime specified in the hsetupi, and leaves
the resulting tokens in the input stream. Trailing spaces at the end of the htokensi are
discarded in the rescanning process. The hsetupi is not limited to changes of category
code but may contain any valid input, for example assignment of the expansion of active
tokens. See also \tl_set_rescan:Nnn.

5 Reassigning token list character codes

\tl_to_lowercase:n \tl_to_lowercase:n {htokens i}

Updated: 2012-09-08 Works through all of the htokensi, replacing each character token with the lower case
equivalent as defined by \char_set_lccode:nn. Characters with no defined lower case
character code are left unchanged. This process does not alter the category code assigned
to the htokensi.

TEXhackers note: This is a wrapper around the TEX primitive \lowercase.

93
 \tl_to_uppercase:n \tl_to_uppercase:n {htokens i}
Updated: 2012-09-08 Works through all of the htokensi, replacing each character token with the upper case
equivalent as defined by \char_set_uccode:nn. Characters with no defined upper case
character code are left unchanged. This process does not alter the category code assigned
to the htokensi.

TEXhackers note: This is a wrapper around the TEX primitive \uppercase.

6 Token list conditionals

\tl_if_blank_p:n ? \tl_if_blank_p:n {htoken list i}

\tl_if_blank_p:(V|o) ? \tl_if_blank:nTF {htoken list i} {htrue code i} {hfalse code i}
\tl_if_blank:nTF ? Tests if the htoken listi consists only of blank spaces (i.e. contains no item). The test is
\tl_if_blank:(V|o)TF ?
true if htoken listi is zero or more explicit space characters (explicit tokens with character
code 32 and category code 10), and is false otherwise.

\tl_if_empty_p:N ? \tl_if_empty_p:N htl var i

\tl_if_empty_p:c ? \tl_if_empty:NTF htl var i {htrue code i} {hfalse code i}
\tl_if_empty:NTF ? Tests if the htoken list variablei is entirely empty (i.e. contains no tokens at all).
\tl_if_empty:cTF ?

\tl_if_empty_p:n ? \tl_if_empty_p:n {htoken list i}

\tl_if_empty_p:(V|o) ? \tl_if_empty:nTF {htoken list i} {htrue code i} {hfalse code i}
\tl_if_empty:nTF ? Tests if the htoken listi is entirely empty (i.e. contains no tokens at all).
\tl_if_empty:(V|o)TF ?
New: 2012-05-24
Updated: 2012-06-05

\tl_if_eq_p:NN ? \tl_if_eq_p:NN {htl var1 i} {htl var2 i}

\tl_if_eq_p:(Nc|cN|cc) ? \tl_if_eq:NNTF {htl var1 i} {htl var2 i} {htrue code i} {hfalse code i}
\tl_if_eq:NNTF ? Compares the content of two htoken list variablesi and is logically true if the two contain
\tl_if_eq:(Nc|cN|cc)TF ?
the same list of tokens (i.e. identical in both the list of characters they contain and the
category codes of those characters). Thus for example
\tl_set:Nn \l_tmpa_tl { abc }
\tl_set:Nx \l_tmpb_tl { \tl_to_str:n { abc } }
\tl_if_eq:NNTF \l_tmpa_tl \l_tmpb_tl { true } { false }

yields false.

\tl_if_eq:nnTF \tl_if_eq:nnTF htoken list1 i {htoken list2 i} {htrue code i} {hfalse code i}
Tests if htoken list1 i and htoken list2 i contain the same list of tokens, both in respect of
character codes and category codes.

94
 \tl_if_in:NnTF \tl_if_in:NnTF htl var i {htoken list i} {htrue code i} {hfalse code i}
\tl_if_in:cnTF
Tests if the htoken listi is found in the content of the htl vari. The htoken listi cannot
contain the tokens {, } or # (more precisely, explicit character tokens with category code
1 (begin-group) or 2 (end-group), and tokens with category code 6).

\tl_if_in:nnTF \tl_if_in:nnTF {htoken list1 i} {htoken list2 i} {htrue code i} {hfalse code i}
\tl_if_in:(Vn|on|no)TF
Tests if htoken list2 i is found inside htoken list1 i. The htoken list2 i cannot contain the
tokens {, } or # (more precisely, explicit character tokens with category code 1 (begin-
group) or 2 (end-group), and tokens with category code 6).

\tl_if_single_p:N ? \tl_if_single_p:N htl var i

\tl_if_single_p:c ? \tl_if_single:NTF htl var i {htrue code i} {hfalse code i}
\tl_if_single:NTF ? Tests if the content of the htl vari consists of a single item, i.e. is a single normal token
\tl_if_single:cTF ?
(neither an explicit space character nor a begin-group character) or a single brace group,
Updated: 2011-08-13 surrounded by optional spaces on both sides. In other words, such a token list has token
count 1 according to \tl_count:N.

\tl_if_single_p:n ? \tl_if_single_p:n {htoken list i}

\tl_if_single:nTF ? \tl_if_single:nTF {htoken list i} {htrue code i} {hfalse code i}
Updated: 2011-08-13 Tests if the htoken listi has exactly one item, i.e. is a single normal token (neither an
explicit space character nor a begin-group character) or a single brace group, surrounded
by optional spaces on both sides. In other words, such a token list has token count 1
according to \tl_count:n.

\tl_case:NnTF ? \tl_case:NnTF htest token list variable i

\tl_case:cnTF ? {
htoken list variable case1 i {hcode case1 i}
New: 2013-07-24
htoken list variable case2 i {hcode case2 i}
...
htoken list variable casen i {hcode casen i}
}
{htrue code i}
{hfalse code i}
This function compares the htest token list variablei in turn with each of the htoken
list variable casesi. If the two are equal (as described for \tl_if_eq:NNTF) then the
associated hcodei is left in the input stream. If any of the cases are matched, the htrue
codei is also inserted into the input stream (after the code for the appropriate case),
while if none match then the hfalse codei is inserted. The function \tl_case:Nn, which
does nothing if there is no match, is also available.

95
 7 Mapping to token lists

\tl_map_function:NN I \tl_map_function:NN htl var i hfunction i

\tl_map_function:cN I
Applies hfunctioni to every hitemi in the htl vari. The hfunctioni will receive one ar-
Updated: 2012-06-29 gument for each iteration. This may be a number of tokens if the hitemi was stored
within braces. Hence the hfunctioni should anticipate receiving n-type arguments. See
also \tl_map_function:nN.

\tl_map_function:nN I \tl_map_function:nN htoken list i hfunction i

Updated: 2012-06-29 Applies hfunctioni to every hitemi in the htoken listi, The hfunctioni will receive one
argument for each iteration. This may be a number of tokens if the hitemi was stored
within braces. Hence the hfunctioni should anticipate receiving n-type arguments. See
also \tl_map_function:NN.

\tl_map_inline:Nn \tl_map_inline:Nn htl var i {hinline function i}

\tl_map_inline:cn
Applies the hinline functioni to every hitemi stored within the htl vari. The hinline
Updated: 2012-06-29 functioni should consist of code which will receive the hitemi as #1. One in line mapping
can be nested inside another. See also \tl_map_function:NN.

\tl_map_inline:nn \tl_map_inline:nn htoken list i {hinline function i}

Updated: 2012-06-29 Applies the hinline functioni to every hitemi stored within the htoken listi. The hinline
functioni should consist of code which will receive the hitemi as #1. One in line mapping
can be nested inside another. See also \tl_map_function:nN.

\tl_map_variable:NNn \tl_map_variable:NNn htl var i hvariable i {hfunction i}

\tl_map_variable:cNn
Applies the hfunctioni to every hitemi stored within the htl vari. The hfunctioni should
Updated: 2012-06-29 consist of code which will receive the hitemi stored in the hvariablei. One variable map-
ping can be nested inside another. See also \tl_map_inline:Nn.

\tl_map_variable:nNn \tl_map_variable:nNn htoken list i hvariable i {hfunction i}

Updated: 2012-06-29 Applies the hfunctioni to every hitemi stored within the htoken listi. The hfunctioni
should consist of code which will receive the hitemi stored in the hvariablei. One variable
mapping can be nested inside another. See also \tl_map_inline:nn.

96
\tl_map_break: I \tl_map_break:
Updated: 2012-06-29 Used to terminate a \tl_map_... function before all entries in the htoken list variablei
have been processed. This will normally take place within a conditional statement, for
example
\tl_map_inline:Nn \l_my_tl
{
\str_if_eq:nnT { #1 } { bingo } { \tl_map_break: }
% Do something useful
}
See also \tl_map_break:n. Use outside of a \tl_map_... scenario will lead to low level
TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before the htokensi are inserted into the input stream.
This will depend on the design of the mapping function.

\tl_map_break:n I \tl_map_break:n {htokens i}

Updated: 2012-06-29 Used to terminate a \tl_map_... function before all entries in the htoken list variablei
have been processed, inserting the htokensi after the mapping has ended. This will
normally take place within a conditional statement, for example
\tl_map_inline:Nn \l_my_tl
{
\str_if_eq:nnT { #1 } { bingo }
{ \tl_map_break:n { <tokens> } }
% Do something useful
}
Use outside of a \tl_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before the htokensi are inserted into the input stream.
This will depend on the design of the mapping function.

97
 8 Using token lists

\tl_to_str:n ? \tl_to_str:n {htoken list i}

Converts the htoken listi to a hstringi, leaving the resulting character tokens in the input
stream. A hstringi is a series of tokens with category code 12 (other) with the exception
of spaces, which retain category code 10 (space).
TEXhackers note: Converting a htoken listi to a hstringi yields a concatenation of the
string representations of every token in the htoken listi. The string representation of a control
sequence is
• an escape character, whose character code is given by the internal parameter \escapechar,
absent if the \escapechar is negative or greater than the largest character code;
• the control sequence name, as defined by \cs_to_str:N;
• a space, unless the control sequence name is a single character whose category at the time
of expansion of \tl_to_str:n is not “letter”.
The string representation of an explicit character token is that character, doubled in the case
of (explicit) macro parameter characters (normally #). In particular, the string representation
of a token list may depend on the category codes in effect when it is evaluated, and the value
of the \escapechar: for instance \tl_to_str:n {\a} normally produces the three character
“backslash”, “lower-case a”, “space”, but it may also produce a single “lower-case a” if the
escape character is negative and a is currently not a letter.

\tl_to_str:N ? \tl_to_str:N htl var i

\tl_to_str:c ?
Converts the content of the htl vari into a series of characters with category code 12
(other) with the exception of spaces, which retain category code 10 (space). This hstringi
is then left in the input stream. For low-level details, see the notes given for \tl_to_-
str:n.

\tl_use:N ? \tl_use:N htl var i

\tl_use:c ?
Recovers the content of a htl vari and places it directly in the input stream. An error
will be raised if the variable does not exist or if it is invalid. Note that it is possible to
use a htl vari directly without an accessor function.

9 Working with the content of token lists

\tl_count:n ? \tl_count:n {htokens i}

\tl_count:(V|o) ?
Counts the number of hitemsi in htokensi and leaves this information in the input stream.
New: 2012-05-13 Unbraced tokens count as one element as do each token group ({. . . }). This process will
ignore any unprotected spaces within htokensi. See also \tl_count:N. This function
requires three expansions, giving an hinteger denotationi.

98
 \tl_count:N ? \tl_count:N htl var i
\tl_count:c ?
Counts the number of token groups in the htl vari and leaves this information in the
New: 2012-05-13 input stream. Unbraced tokens count as one element as do each token group ({. . . }).
This process will ignore any unprotected spaces within the htl vari. See also \tl_count:n.
This function requires three expansions, giving an hinteger denotationi.

\tl_reverse:n ? \tl_reverse:n {htoken list i}

\tl_reverse:(V|o) ?
Reverses the order of the hitemsi in the htoken listi, so that hitem1 ihitem2 ihitem3 i
Updated: 2012-01-08 . . . hitemn i becomes hitemn i. . . hitem3 ihitem2 ihitem1 i. This process will preserve unpro-
tected space within the htoken listi. Tokens are not reversed within braced token groups,
which keep their outer set of braces. In situations where performance is important,
consider \tl_reverse_items:n. See also \tl_reverse:N.

TEXhackers note: The result is returned within \exp_not:n, which means that the token
list will not expand further when appearing in an x-type argument expansion.

\tl_reverse:N \tl_reverse:N htl var i

\tl_reverse:c
Reverses the order of the hitemsi stored in htl vari, so that hitem1 ihitem2 ihitem3 i
\tl_greverse:N
\tl_greverse:c . . . hitemn i becomes hitemn i. . . hitem3 ihitem2 ihitem1 i. This process will preserve unpro-
tected spaces within the htoken list variablei. Braced token groups are copied without
Updated: 2012-01-08
reversing the order of tokens, but keep the outer set of braces. See also \tl_reverse:n,
and, for improved performance, \tl_reverse_items:n.

\tl_reverse_items:n ? \tl_reverse_items:n {htoken list i}

New: 2012-01-08 Reverses the order of the hitemsi stored in htl vari, so that {hitem1 i}{hitem2 i}{hitem3 i}
. . . {hitemn i} becomes {hitemn i} . . . {hitem3 i}{hitem2 i}{hitem1 i}. This process will
remove any unprotected space within the htoken listi. Braced token groups are copied
without reversing the order of tokens, and keep the outer set of braces. Items which are
initially not braced are copied with braces in the result. In cases where preserving spaces
is important, consider the slower function \tl_reverse:n.

TEXhackers note: The result is returned within \exp_not:n, which means that the token
list will not expand further when appearing in an x-type argument expansion.

\tl_trim_spaces:n ? \tl_trim_spaces:n {htoken list i}

New: 2011-07-09 Removes any leading and trailing explicit space characters (explicit tokens with character
Updated: 2012-06-25 code 32 and category code 10) from the htoken listi and leaves the result in the input
stream.

TEXhackers note: The result is returned within \exp_not:n, which means that the token
list will not expand further when appearing in an x-type argument expansion.

99
\tl_trim_spaces:N \tl_trim_spaces:N htl var i
\tl_trim_spaces:c
Removes any leading and trailing explicit space characters (explicit tokens with character
\tl_gtrim_spaces:N
\tl_gtrim_spaces:c code 32 and category code 10) from the content of the htl vari. Note that this therefore
resets the content of the variable.
New: 2011-07-09

10 The first token from a token list

Functions which deal with either only the very first item (balanced text or single normal
token) in a token list, or the remaining tokens.

\tl_head:N ? \tl_head:n {htoken list i}

\tl_head:(n|V|v|f) ?
Leaves in the input stream the first hitemi in the htoken listi, discarding the rest of the
Updated: 2012-09-09 htoken listi. All leading explicit space characters (explicit tokens with character code 32
and category code 10) are discarded; for example

\tl_head:n { abc }
and
\tl_head:n { ~ abc }
will both leave a in the input stream. If the “head” is a brace group, rather than a single
token, the braces will be removed, and so
\tl_head:n { ~ { ~ ab } c }
yields ␣ab. A blank htoken listi (see \tl_if_blank:nTF) will result in \tl_head:n leaving
nothing in the input stream.

TEXhackers note: The result is returned within \exp_not:n, which means that the token
list will not expand further when appearing in an x-type argument expansion.

\tl_head:w ? \tl_head:w htoken list i { } \q_stop

Leaves in the input stream the first hitemi in the htoken listi, discarding the rest of
the htoken listi. All leading explicit space characters (explicit tokens with character
code 32 and category code 10) are discarded. A blank htoken listi (which consists only
of space characters) will result in a low-level TEX error, which may be avoided by the
inclusion of an empty group in the input (as shown), without the need for an explicit
test. Alternatively, \tl_if_blank:nF may be used to avoid using the function with a
“blank” argument. This function requires only a single expansion, and thus is suitable
for use within an o-type expansion. In general, \tl_head:n should be preferred if the
number of expansions is not critical.

100
 \tl_tail:N ? \tl_tail:n {htoken list i}
\tl_tail:(n|V|v|f) ?
Discards all leading explicit space characters (explicit tokens with character code 32 and
Updated: 2012-09-01 category code 10) and the first hitemi in the htoken listi, and leaves the remaining tokens
in the input stream. Thus for example
\tl_tail:n { a ~ {bc} d }

and
\tl_tail:n { ~ a ~ {bc} d }
will both leave ␣{bc}d in the input stream. A blank htoken listi (see \tl_if_blank:nTF)
will result in \tl_tail:n leaving nothing in the input stream.

TEXhackers note: The result is returned within \exp_not:n, which means that the token
list will not expand further when appearing in an x-type argument expansion.

\tl_if_head_eq_catcode_p:nN ? \tl_if_head_eq_catcode_p:nN {htoken list i} htest token i

\tl_if_head_eq_catcode:nNTF ? \tl_if_head_eq_catcode:nNTF {htoken list i} htest token i
{htrue code i} {hfalse code i}
Updated: 2012-07-09

Tests if the first htokeni in the htoken listi has the same category code as the htest tokeni.
In the case where the htoken listi is empty, the test will always be false.

\tl_if_head_eq_charcode_p:nN ? \tl_if_head_eq_charcode_p:nN {htoken list i} htest token i

\tl_if_head_eq_charcode_p:fN ? \tl_if_head_eq_charcode:nNTF {htoken list i} htest token i
\tl_if_head_eq_charcode:nNTF ? {htrue code i} {hfalse code i}
\tl_if_head_eq_charcode:fNTF ?
Updated: 2012-07-09

Tests if the first htokeni in the htoken listi has the same character code as the htest tokeni.
In the case where the htoken listi is empty, the test will always be false.

\tl_if_head_eq_meaning_p:nN ? \tl_if_head_eq_meaning_p:nN {htoken list i} htest token i

\tl_if_head_eq_meaning:nNTF ? \tl_if_head_eq_meaning:nNTF {htoken list i} htest token i
{htrue code i} {hfalse code i}
Updated: 2012-07-09

Tests if the first htokeni in the htoken listi has the same meaning as the htest tokeni. In
the case where htoken listi is empty, the test will always be false.

\tl_if_head_is_group_p:n ? \tl_if_head_is_group_p:n {htoken list i}

\tl_if_head_is_group:nTF ? \tl_if_head_is_group:nTF {htoken list i} {htrue code i} {hfalse code i}
New: 2012-07-08 Tests if the first htokeni in the htoken listi is an explicit begin-group character (with
category code 1 and any character code), in other words, if the htoken listi starts with a
brace group. In particular, the test is false if the htoken listi starts with an implicit token
such as \c_group_begin_token, or if it is empty. This function is useful to implement
actions on token lists on a token by token basis.

101
 \tl_if_head_is_N_type_p:n ? \tl_if_head_is_N_type_p:n {htoken list i}
\tl_if_head_is_N_type:nTF ? \tl_if_head_is_N_type:nTF {htoken list i} {htrue code i} {hfalse code i}
New: 2012-07-08

Tests if the first htokeni in the htoken listi is a normal N-type argument. In other words, it
is neither an explicit space character (explicit token with character code 32 and category
code 10) nor an explicit begin-group character (with category code 1 and any character
code). An empty argument yields false, as it does not have a “normal” first token. This
function is useful to implement actions on token lists on a token by token basis.

\tl_if_head_is_space_p:n ? \tl_if_head_is_space_p:n {htoken list i}

\tl_if_head_is_space:nTF ? \tl_if_head_is_space:nTF {htoken list i} {htrue code i} {hfalse code i}
Updated: 2012-07-08 Tests if the first htokeni in the htoken listi is an explicit space character (explicit token
with character code 12 and category code 10). In particular, the test is false if the
htoken listi starts with an implicit token such as \c_space_token, or if it is empty. This
function is useful to implement actions on token lists on a token by token basis.

11 Using a single item

\tl_item:nn ? \tl_item:nn {htoken list i} {hinteger expression i}

\tl_item:(Nn|cn) ?
Indexing items in the htoken listi from 1 on the left, this function will evaluate the hinteger
New: 2014-07-17 expressioni and leave the appropriate item from the htoken listi in the input stream. If
the hinteger expressioni is negative, indexing occurs from the right of the token list,
starting at −1 for the right-most item. If the index is out of bounds, then thr function
expands to nothing.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemi will not expand further when appearing in an x-type argument
expansion.

12 Viewing token lists

\tl_show:N \tl_show:N htl var i

\tl_show:c
Displays the content of the htl vari on the terminal.
Updated: 2012-09-09
TEXhackers note: This is similar to the TEX primitive \show, wrapped to a fixed number
of characters per line.

102
 \tl_show:n \tl_show:n htoken list i
Updated: 2012-09-09 Displays the htoken listi on the terminal.

TEXhackers note: This is similar to the ε-TEX primitive \showtokens, wrapped to a fixed
number of characters per line.

13 Constant token lists

\c_empty_tl Constant that is always empty.

\c_job_name_tl Constant that gets the “job name” assigned when TEX starts.
Updated: 2011-08-18
TEXhackers note: This copies the contents of the primitive \jobname. It is a constant
that is set by TEX and should not be overwritten by the package.

\c_space_tl An explicit space character contained in a token list (compare this with \c_space_token).
For use where an explicit space is required.

14 Scratch token lists

\l_tmpa_tl Scratch token lists for local assignment. These are never used by the kernel code, and so
\l_tmpb_tl are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

\g_tmpa_tl Scratch token lists for global assignment. These are never used by the kernel code, and
\g_tmpb_tl so are safe for use with any LATEX3-defined function. However, they may be overwritten
by other non-kernel code and so should only be used for short-term storage.

15 Internal functions

\__tl_trim_spaces:nn \__tl_trim_spaces:nn { \q_mark htoken list i } {hcontinuation i}

This function removes all leading and trailing explicit space characters from the htoken
listi, and expands to the hcontinuationi, followed by a brace group containing \use_-
none:n \q_mark htrimmed token listi. For instance, \tl_trim_spaces:n is implemented
by taking the hcontinuationi to be \exp_not:o, and the o-type expansion removes the
\q_mark. This function is also used in l3clist and l3candidates.

103
 Part XII
The l3str package
Strings
TEX associates each character with a category code: as such, there is no concept of
a “string” as commonly understood in many other programming languages. However,
there are places where we wish to manipulate token lists while in some sense “ignoring”
category codes: this is done by treating token lists as strings in a TEX sense.
A TEX string (and thus an expl3 string) is a series of characters which have category
code 12 (“other”) with the exception of space characters which have category code 10
(“space”). Thus at a technical level, a TEX string is a token list with the appropriate
category codes. In this documentation, these will simply be referred to as strings: note
that they can be stored in token lists as normal.
The functions documented here take literal token lists, convert to strings and then
carry out manipulations. Thus they may informally be described as “ignoring” cate-
gory code. Note that the functions \cs_to_str:N, \tl_to_str:n, \tl_to_str:N and
\token_to_str:N (and variants) will generate strings from the appropriate input: these
are documented in l3basics, l3tl and l3token, respectively.

1 The first character from a string

\str_head:n ? \str_head:n {htoken list i}

\str_tail:n ? \str_tail:n {htoken list i}
New: 2011-08-10 Converts the htoken listi into a string, as described for \tl_to_str:n. The \str_-
head:n function then leaves the first character of this string in the input stream. The
\str_tail:n function leaves all characters except the first in the input stream. The first
character may be a space. If the htoken listi argument is entirely empty, nothing is left
in the input stream.

1.1 Tests on strings

\str_if_eq_p:nn ? \str_if_eq_p:nn {htl1 i} {htl2 i}

\str_if_eq_p:(Vn|on|no|nV|VV) ? \str_if_eq:nnTF {htl1 i} {htl2 i} {htrue code i} {hfalse code i}
\str_if_eq:nnTF ?
\str_if_eq:(Vn|on|no|nV|VV)TF ?

Compares the two htoken listsi on a character by character basis, and is true if the two
lists contain the same characters in the same order. Thus for example
\str_if_eq_p:no { abc } { \tl_to_str:n { abc } }
is logically true.

104
\str_if_eq_x_p:nn ? \str_if_eq_x_p:nn {htl1 i} {htl2 i}
\str_if_eq_x:nnTF ? \str_if_eq_x:nnTF {htl1 i} {htl2 i} {htrue code i} {hfalse code i}
New: 2012-06-05 Compares the full expansion of two htoken listsi on a character by character basis, and
is true if the two lists contain the same characters in the same order. Thus for example
\str_if_eq_x_p:nn { abc } { \tl_to_str:n { abc } }

is logically true.

\str_case:nnTF ? \str_case:nnTF {htest string i}

\str_case:onTF ? {
{hstring case1 i} {hcode case1 i}
New: 2013-07-24
{hstring case2 i} {hcode case2 i}
...
{hstring casen i} {hcode casen i}
}
{htrue code i}
{hfalse code i}
This function compares the htest stringi in turn with each of the hstring casesi. If the
two are equal (as described for \str_if_eq:nnTF then the associated hcodei is left in
the input stream. If any of the cases are matched, the htrue codei is also inserted into
the input stream (after the code for the appropriate case), while if none match then the
hfalse codei is inserted. The function \str_case:nn, which does nothing if there is no
match, is also available.

\str_case_x:nnTF ? \str_case_x:nnn {htest string i}

{
New: 2013-07-24
{hstring case1 i} {hcode case1 i}
{hstring case2 i} {hcode case2 i}
...
{hstring casen i} {hcode casen i}
}
{htrue code i}
{hfalse code i}
This function compares the full expansion of the htest stringi in turn with the full ex-
pansion of the hstring casesi. If the two full expansions are equal (as described for
\str_if_eq:nnTF then the associated hcodei is left in the input stream. If any of the
cases are matched, the htrue codei is also inserted into the input stream (after the code
for the appropriate case), while if none match then the hfalse codei is inserted. The
function \str_case_x:nn, which does nothing if there is no match, is also available. The
htest stringi is expanded in each comparison, and must always yield the same result: for
example, random numbers must not be used within this string.

105
 2 String manipulation

\str_fold_case:n I \str_fold_case:n {htokens i}

New: 2014-06-19 Converts the input htokensi to their string representation, as described for \tl_to_str:n,
and then folds the case of the resulting hstringi to remove case information. The result
of this process is left in the input stream.
String folding is a process used for material such as identifiers rather than for “text”.
The folding provided by \str_fold_case:n follows the mappings provided by the Uni-
code Consortium, who state:
Case folding is primarily used for caseless comparison of text, such as iden-
tifiers in a computer program, rather than actual text transformation. Case
folding in Unicode is based on the lowercase mapping, but includes additional
changes to the source text to help make it language-insensitive and consistent.
As a result, case-folded text should be used solely for internal processing and
generally should not be stored or displayed to the end user.
The folding approach implemented by \str_fold_case:n follows the “full” scheme de-
fined by the Unicode Consortium (e.g. ßfolds to SS). As case-folding is a language-
insensitive process, there is no special treatment of Turkic input (i.e. I always folds to i
and not to ı).

TEXhackers note: As with all expl3 functions, the input supported by \str_fold_case:n
is engine-native characters which are or interoperate with utf-8. As such, when used with
pdfTEX only the Latin alphabet characters A–Z will be case-folded (i.e. the ascii range which
coincides with utf-8). Full utf-8 support is available with both XETEX and LuaTEX, subject
only to the fact that XETEX in particular has issues with characters of code above hexadecimal
0xFFF when interacting with \tl_to_str:n.

2.1 Internal string functions

\__str_if_eq_x:nn ? \__str_if_eq_x:nn {htl1 i} {htl2 i}

Compares the full expansion of two htoken listsi on a character by character basis, and
is true if the two lists contain the same characters in the same order. Leaves 0 in the
input stream if the condition is true, and +1 or -1 otherwise.

\@@_if_eq_x_return:nn \@@_if_eq_x_return:nn {htl1 i} {htl2 i}

Compares the full expansion of two htoken listsi on a character by character basis, and
is true if the two lists contain the same characters in the same order. Either \prg_-
return_true: or \prg_return_false: is then left in the input stream. This is a version
of \str_if_eq_x:nn(TF) coded for speed.

106
 Part XIII
The l3seq package
Sequences and stacks
LATEX3 implements a “sequence” data type, which contain an ordered list of entries which
may contain any hbalanced texti. 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.

1 Creating and initialising sequences

\seq_new:N \seq_new:N hsequence i

\seq_new:c
Creates a new hsequencei or raises an error if the name is already taken. The declaration
is global. The hsequencei will initially contain no items.

\seq_clear:N \seq_clear:N hsequence i

\seq_clear:c
Clears all items from the hsequencei.
\seq_gclear:N
\seq_gclear:c

\seq_clear_new:N \seq_clear_new:N hsequence i

\seq_clear_new:c
Ensures that the hsequencei exists globally by applying \seq_new:N if necessary, then
\seq_gclear_new:N
\seq_gclear_new:c applies \seq_(g)clear:N to leave the hsequencei empty.

\seq_set_eq:NN \seq_set_eq:NN hsequence1 i hsequence2 i

\seq_set_eq:(cN|Nc|cc)
Sets the content of hsequence1 i equal to that of hsequence2 i.
\seq_gset_eq:NN
\seq_gset_eq:(cN|Nc|cc)

\seq_set_from_clist:NN \seq_set_from_clist:NN hsequence i hcomma-list i

\seq_set_from_clist:(cN|Nc|cc|Nn|cn)
\seq_gset_from_clist:NN
\seq_gset_from_clist:(cN|Nc|cc|Nn|cn)
New: 2014-07-17

Converts the data in the hcomma listi into a hsequencei: the original hcomma listi is
unchanged.

107
 \seq_set_split:Nnn \seq_set_split:Nnn hsequence i {hdelimiter i} {htoken list i}
\seq_set_split:NnV
Splits the htoken listi into hitemsi separated by hdelimiteri, and assigns the result to the
\seq_gset_split:Nnn
\seq_gset_split:NnV hsequencei. Spaces on both sides of each hitemi are ignored, then one set of outer braces
is removed (if any); this space trimming behaviour is identical to that of l3clist functions.
New: 2011-08-15
Empty hitemsi are preserved by \seq_set_split:Nnn, and can be removed afterwards
Updated: 2012-07-02
using \seq_remove_all:Nn hsequencei {hi}. The hdelimiteri may not contain {, } or #
(assuming TEX’s normal category code régime). If the hdelimiteri is empty, the htoken
listi is split into hitemsi as a htoken listi.

\seq_concat:NNN \seq_concat:NNN hsequence1 i hsequence2 i hsequence3 i

\seq_concat:ccc
Concatenates the content of hsequence2 i and hsequence3 i together and saves the result in
\seq_gconcat:NNN
\seq_gconcat:ccc hsequence1 i. The items in hsequence2 i will be placed at the left side of the new sequence.

\seq_if_exist_p:N ? \seq_if_exist_p:N hsequence i

\seq_if_exist_p:c ? \seq_if_exist:NTF hsequence i {htrue code i} {hfalse code i}
\seq_if_exist:NTF ? Tests whether the hsequencei is currently defined. This does not check that the hsequencei
\seq_if_exist:cTF ?
really is a sequence variable.
New: 2012-03-03

2 Appending data to sequences

\seq_put_left:Nn \seq_put_left:Nn hsequence i {hitem i}

\seq_put_left:(NV|Nv|No|Nx|cn|cV|cv|co|cx)
\seq_gput_left:Nn
\seq_gput_left:(NV|Nv|No|Nx|cn|cV|cv|co|cx)

Appends the hitemi to the left of the hsequencei.

\seq_put_right:Nn \seq_put_right:Nn hsequence i {hitem i}

\seq_put_right:(NV|Nv|No|Nx|cn|cV|cv|co|cx)
\seq_gput_right:Nn
\seq_gput_right:(NV|Nv|No|Nx|cn|cV|cv|co|cx)

Appends the hitemi to the right of the hsequencei.

3 Recovering items from sequences

Items can be recovered from either the left or the right of sequences. For implementa-
tion 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, i.e. setting the htoken list
variablei used with \tl_set:Nn and never \tl_gset:Nn.

108
 \seq_get_left:NN \seq_get_left:NN hsequence i htoken list variable i
\seq_get_left:cN
Stores the left-most item from a hsequencei in the htoken list variablei without removing
Updated: 2012-05-14 it from the hsequencei. The htoken list variablei is assigned locally. If hsequencei is empty
the htoken list variablei will contain the special marker \q_no_value.

\seq_get_right:NN \seq_get_right:NN hsequence i htoken list variable i

\seq_get_right:cN
Stores the right-most item from a hsequencei in the htoken list variablei without removing
Updated: 2012-05-19 it from the hsequencei. The htoken list variablei is assigned locally. If hsequencei is empty
the htoken list variablei will contain the special marker \q_no_value.

\seq_pop_left:NN \seq_pop_left:NN hsequence i htoken list variable i

\seq_pop_left:cN
Pops the left-most item from a hsequencei into the htoken list variablei, i.e. removes the
Updated: 2012-05-14 item from the sequence and stores it in the htoken list variablei. Both of the variables are
assigned locally. If hsequencei is empty the htoken list variablei will contain the special
marker \q_no_value.

\seq_gpop_left:NN \seq_gpop_left:NN hsequence i htoken list variable i

\seq_gpop_left:cN
Pops the left-most item from a hsequencei into the htoken list variablei, i.e. removes
Updated: 2012-05-14 the item from the sequence and stores it in the htoken list variablei. The hsequencei is
modified globally, while the assignment of the htoken list variablei is local. If hsequencei
is empty the htoken list variablei will contain the special marker \q_no_value.

\seq_pop_right:NN \seq_pop_right:NN hsequence i htoken list variable i

\seq_pop_right:cN
Pops the right-most item from a hsequencei into the htoken list variablei, i.e. removes the
Updated: 2012-05-19 item from the sequence and stores it in the htoken list variablei. Both of the variables are
assigned locally. If hsequencei is empty the htoken list variablei will contain the special
marker \q_no_value.

\seq_gpop_right:NN \seq_gpop_right:NN hsequence i htoken list variable i

\seq_gpop_right:cN
Pops the right-most item from a hsequencei into the htoken list variablei, i.e. removes
Updated: 2012-05-19 the item from the sequence and stores it in the htoken list variablei. The hsequencei is
modified globally, while the assignment of the htoken list variablei is local. If hsequencei
is empty the htoken list variablei will contain the special marker \q_no_value.

109
 \seq_item:Nn ? \seq_item:Nn hsequence i {hinteger expression i}
\seq_item:cn ?
Indexing items in the hsequencei from 1 at the top (left), this function will evaluate
New: 2014-07-17 the hinteger expressioni and leave the appropriate item from the sequence in the input
stream. If the hinteger expressioni is negative, indexing occurs from the bottom (right)
of the sequence. When the hinteger expressioni is larger than the number of items in the
hsequencei (as calculated by \seq_count:N) then the function will expand to nothing.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemi will not expand further when appearing in an x-type argument
expansion.

4 Recovering values from sequences with branching

The functions in this section combine tests for non-empty sequences with recovery of an
item from the sequence. They offer increased readability and performance over separate
testing and recovery phases.

\seq_get_left:NNTF \seq_get_left:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_get_left:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-14 htoken list variablei is not defined in this case and should not be relied upon. If the
Updated: 2012-05-19 hsequencei is non-empty, stores the left-most item from a hsequencei in the htoken list
variablei without removing it from a hsequencei. The htoken list variablei is assigned
locally.

\seq_get_right:NNTF \seq_get_right:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_get_right:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-19 htoken list variablei is not defined in this case and should not be relied upon. If the
hsequencei is non-empty, stores the right-most item from a hsequencei in the htoken list
variablei without removing it from a hsequencei. The htoken list variablei is assigned
locally.

\seq_pop_left:NNTF \seq_pop_left:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_pop_left:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-14 htoken list variablei is not defined in this case and should not be relied upon. If the
Updated: 2012-05-19 hsequencei is non-empty, pops the left-most item from a hsequencei in the htoken list
variablei, i.e. removes the item from a hsequencei. Both the hsequencei and the htoken
list variablei are assigned locally.

\seq_gpop_left:NNTF \seq_gpop_left:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_gpop_left:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-14 htoken list variablei is not defined in this case and should not be relied upon. If the
Updated: 2012-05-19 hsequencei is non-empty, pops the left-most item from a hsequencei in the htoken list
variablei, i.e. removes the item from a hsequencei. The hsequencei is modified globally,
while the htoken list variablei is assigned locally.

110
 \seq_pop_right:NNTF \seq_pop_right:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_pop_right:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-19 htoken list variablei is not defined in this case and should not be relied upon. If the
hsequencei is non-empty, pops the right-most item from a hsequencei in the htoken list
variablei, i.e. removes the item from a hsequencei. Both the hsequencei and the htoken
list variablei are assigned locally.

\seq_gpop_right:NNTF \seq_gpop_right:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_gpop_right:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-19 htoken list variablei is not defined in this case and should not be relied upon. If the
hsequencei is non-empty, pops the right-most item from a hsequencei in the htoken list
variablei, i.e. removes the item from a hsequencei. The hsequencei is modified globally,
while the htoken list variablei is assigned locally.

5 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.

\seq_remove_duplicates:N \seq_remove_duplicates:N hsequence i

\seq_remove_duplicates:c
Removes duplicate items from the hsequencei, leaving the left most copy of each item
\seq_gremove_duplicates:N
\seq_gremove_duplicates:c in the hsequencei. The hitemi comparison takes place on a token basis, as for \tl_if_-
eq:nn(TF).

TEXhackers note: This function iterates through every item in the hsequencei and does a
comparison with the hitemsi already checked. It is therefore relatively slow with large sequences.

\seq_remove_all:Nn \seq_remove_all:Nn hsequence i {hitem i}

\seq_remove_all:cn
Removes every occurrence of hitemi from the hsequencei. The hitemi comparison takes
\seq_gremove_all:Nn
\seq_gremove_all:cn place on a token basis, as for \tl_if_eq:nn(TF).

\seq_reverse:N \seq_reverse:N hsequence i

\seq_reverse:c
Reverses the order of the items stored in the hsequencei.
\seq_greverse:N
\seq_greverse:c
New: 2014-07-18

111
 6 Sequence conditionals

\seq_if_empty_p:N ? \seq_if_empty_p:N hsequence i

\seq_if_empty_p:c ? \seq_if_empty:NTF hsequence i {htrue code i} {hfalse code i}
\seq_if_empty:NTF ? Tests if the hsequencei is empty (containing no items).
\seq_if_empty:cTF ?

\seq_if_in:NnTF \seq_if_in:NnTF hsequence i {hitem i} {htrue code i} {hfalse code i}

\seq_if_in:(NV|Nv|No|Nx|cn|cV|cv|co|cx)TF

Tests if the hitemi is present in the hsequencei.

7 Mapping to sequences

\seq_map_function:NN I \seq_map_function:NN hsequence i hfunction i

\seq_map_function:cN I
Applies hfunctioni to every hitemi stored in the hsequencei. The hfunctioni will receive
Updated: 2012-06-29 one argument for each iteration. The hitemsi are returned from left to right. The function
\seq_map_inline:Nn is faster than \seq_map_function:NN for sequences with more
than about 10 items. One mapping may be nested inside another.

\seq_map_inline:Nn \seq_map_inline:Nn hsequence i {hinline function i}

\seq_map_inline:cn
Applies hinline functioni to every hitemi stored within the hsequencei. The hinline
Updated: 2012-06-29 functioni should consist of code which will receive the hitemi as #1. One in line mapping
can be nested inside another. The hitemsi are returned from left to right.

\seq_map_variable:NNn \seq_map_variable:NNn hsequence i htl var. i {hfunction using tl var. i}

\seq_map_variable:(Ncn|cNn|ccn)
Updated: 2012-06-29

Stores each entry in the hsequencei in turn in the htl var.i and applies the hfunction using
tl var.i The hfunctioni will usually consist of code making use of the htl var.i, but this
is not enforced. One variable mapping can be nested inside another. The hitemsi are
returned from left to right.

112
\seq_map_break: I \seq_map_break:
Updated: 2012-06-29 Used to terminate a \seq_map_... function before all entries in the hsequencei have been
processed. This will normally take place within a conditional statement, for example
\seq_map_inline:Nn \l_my_seq
{
\str_if_eq:nnTF { #1 } { bingo }
{ \seq_map_break: }
{
% Do something useful
}
}

Use outside of a \seq_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before further items are taken from the input stream.
This will depend on the design of the mapping function.

\seq_map_break:n I \seq_map_break:n {htokens i}

Updated: 2012-06-29 Used to terminate a \seq_map_... function before all entries in the hsequencei have
been processed, inserting the htokensi after the mapping has ended. This will normally
take place within a conditional statement, for example
\seq_map_inline:Nn \l_my_seq
{
\str_if_eq:nnTF { #1 } { bingo }
{ \seq_map_break:n { <tokens> } }
{
% Do something useful
}
}
Use outside of a \seq_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before the htokensi are inserted into the input stream.
This will depend on the design of the mapping function.

\seq_count:N ? \seq_count:N hsequence i

\seq_count:c ?
Leaves the number of items in the hsequencei in the input stream as an hinteger
New: 2012-07-13 denotationi. The total number of items in a hsequencei will include those which are
empty and duplicates, i.e. every item in a hsequencei is unique.

113
 8 Using the content of sequences directly

\seq_use:Nnnn ? \seq_use:Nnnn hseq var i {hseparator between two i}

\seq_use:cnnn ? {hseparator between more than two i} {hseparator between final two i}
New: 2013-05-26 Places the contents of the hseq vari in the input stream, with the appropriate hseparatori
between the items. Namely, if the sequence has more than two items, the hseparator
between more than twoi is placed between each pair of items except the last, for which
the hseparator between final twoi is used. If the sequence has exactly two items, then they
are placed in the input stream separated by the hseparator between twoi. If the sequence
has a single item, it is placed in the input stream, and an empty sequence produces no
output. An error will be raised if the variable does not exist or if it is invalid.
For example,

\seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }

\seq_use:Nnnn \l_tmpa_seq { ~and~ } { ,~ } { ,~and~ }
will insert “a, b, c, de, and f” in the input stream. The first separator argument is
not used in this case because the sequence has more than 2 items.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemsi will not expand further when appearing in an x-type argument
expansion.

\seq_use:Nn ? \seq_use:Nn hseq var i {hseparator i}

\seq_use:cn ?
Places the contents of the hseq vari in the input stream, with the hseparatori between
New: 2013-05-26 the items. If the sequence has a single item, it is placed in the input stream with no
hseparatori, and an empty sequence produces no output. An error will be raised if the
variable does not exist or if it is invalid.
For example,
\seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }
\seq_use:Nn \l_tmpa_seq { ~and~ }

will insert “a and b and c and de and f” in the input stream.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemsi will not expand further when appearing in an x-type argument
expansion.

9 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

114
 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.

\seq_get:NN \seq_get:NN hsequence i htoken list variable i

\seq_get:cN
Reads the top item from a hsequencei into the htoken list variablei without removing it
Updated: 2012-05-14 from the hsequencei. The htoken list variablei is assigned locally. If hsequencei is empty
the htoken list variablei will contain the special marker \q_no_value.

\seq_pop:NN \seq_pop:NN hsequence i htoken list variable i

\seq_pop:cN
Pops the top item from a hsequencei into the htoken list variablei. Both of the variables
Updated: 2012-05-14 are assigned locally. If hsequencei is empty the htoken list variablei will contain the special
marker \q_no_value.

\seq_gpop:NN \seq_gpop:NN hsequence i htoken list variable i

\seq_gpop:cN
Pops the top item from a hsequencei into the htoken list variablei. The hsequencei is
Updated: 2012-05-14 modified globally, while the htoken list variablei is assigned locally. If hsequencei is empty
the htoken list variablei will contain the special marker \q_no_value.

\seq_get:NNTF \seq_get:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_get:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of the
New: 2012-05-14 htoken list variablei is not defined in this case and should not be relied upon. If the
Updated: 2012-05-19 hsequencei is non-empty, stores the top item from a hsequencei in the htoken list variablei
without removing it from the hsequencei. The htoken list variablei is assigned locally.

\seq_pop:NNTF \seq_pop:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_pop:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of
New: 2012-05-14 the htoken list variablei is not defined in this case and should not be relied upon. If
Updated: 2012-05-19 the hsequencei is non-empty, pops the top item from the hsequencei in the htoken list
variablei, i.e. removes the item from the hsequencei. Both the hsequencei and the htoken
list variablei are assigned locally.

\seq_gpop:NNTF \seq_gpop:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\seq_gpop:cNTF
If the hsequencei is empty, leaves the hfalse codei in the input stream. The value of
New: 2012-05-14 the htoken list variablei is not defined in this case and should not be relied upon. If
Updated: 2012-05-19 the hsequencei is non-empty, pops the top item from the hsequencei in the htoken list
variablei, i.e. removes the item from the hsequencei. The hsequencei is modified globally,
while the htoken list variablei is assigned locally.

\seq_push:Nn \seq_push:Nn hsequence i {hitem i}

\seq_push:(NV|Nv|No|Nx|cn|cV|cv|co|cx)
\seq_gpush:Nn
\seq_gpush:(NV|Nv|No|Nx|cn|cV|cv|co|cx)

Adds the {hitemi} to the top of the hsequencei.

115
 10 Constant and scratch sequences

\c_empty_seq Constant that is always empty.

New: 2012-07-02

\l_tmpa_seq Scratch sequences for local assignment. These are never used by the kernel code, and so
\l_tmpb_seq are safe for use with any LATEX3-defined function. However, they may be overwritten by
New: 2012-04-26 other non-kernel code and so should only be used for short-term storage.

\g_tmpa_seq Scratch sequences for global assignment. These are never used by the kernel code, and
\g_tmpb_seq so are safe for use with any LATEX3-defined function. However, they may be overwritten
New: 2012-04-26 by other non-kernel code and so should only be used for short-term storage.

11 Viewing sequences

\seq_show:N \seq_show:N hsequence i

\seq_show:c
Displays the entries in the hsequencei in the terminal.
Updated: 2012-09-09

12 Internal sequence functions

\s__seq This scan mark (equal to \scan_stop:) marks the beginning of a sequence variable.

\__seq_item:n ? \__seq_item:n {hitem i}

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.

\__seq_push_item_def:n \__seq_push_item_def:n {hcode i}

\__seq_push_item_def:x
Saves the definition of \__seq_item:n and redefines it to accept one parameter and
expand to hcodei. This function should always be balanced by use of \__seq_pop_-
item_def:.

\__seq_pop_item_def: \__seq_pop_item_def:
Restores the definition of \__seq_item:n most recently saved by \__seq_push_item_-
def:n. This function should always be used in a balanced pair with \__seq_push_-
item_def:n.

116
 Part XIV
The l3clist package
Comma separated lists
Comma lists contain ordered data where items can be added to the left or right end of the
list. The resulting ordered list can then be mapped over using \clist_map_function:NN.
Several items can be added at once, and spaces are removed from both sides of each item
on input. Hence,
\clist_new:N \l_my_clist
\clist_put_left:Nn \l_my_clist { ~ a ~ , ~ {b} ~ }
\clist_put_right:Nn \l_my_clist { ~ { c ~ } , d }

results in \l_my_clist containing a,{b},{c~},d. Comma lists cannot contain empty

items, thus
\clist_clear_new:N \l_my_clist
\clist_put_right:Nn \l_my_clist { , ~ , , }
\clist_if_empty:NTF \l_my_clist { true } { false }

will leave true in the input stream. To include an item which contains a comma, or
starts or ends with a space, surround it with braces. The sequence data type should
be preferred to comma lists if items are to contain {, }, or # (assuming the usual TEX
category codes apply).

1 Creating and initialising comma lists

\clist_new:N \clist_new:N hcomma list i

\clist_new:c
Creates a new hcomma listi or raises an error if the name is already taken. The declaration
is global. The hcomma listi will initially contain no items.

\clist_const:Nn \clist_const:Nn hclist var i {hcomma list i}

\clist_const:(Nx|cn|cx)
Creates a new constant hclist vari or raises an error if the name is already taken. The
New: 2014-07-05 value of the hclist vari will be set globally to the hcomma listi.

\clist_clear:N \clist_clear:N hcomma list i

\clist_clear:c
Clears all items from the hcomma listi.
\clist_gclear:N
\clist_gclear:c

117
 \clist_clear_new:N \clist_clear_new:N hcomma list i
\clist_clear_new:c
Ensures that the hcomma listi exists globally by applying \clist_new:N if necessary,
\clist_gclear_new:N
\clist_gclear_new:c then applies \clist_(g)clear:N to leave the list empty.

\clist_set_eq:NN \clist_set_eq:NN hcomma list1 i hcomma list2 i

\clist_set_eq:(cN|Nc|cc)
Sets the content of hcomma list1 i equal to that of hcomma list2 i.
\clist_gset_eq:NN
\clist_gset_eq:(cN|Nc|cc)

\clist_set_from_seq:NN \clist_set_from_seq:NN hcomma list i hsequence i

\clist_set_from_seq:(cN|Nc|cc)
\clist_gset_from_seq:NN
\clist_gset_from_seq:(cN|Nc|cc)
New: 2014-07-17

Converts the data in the hsequencei into a hcomma listi: the original hsequencei is un-
changed. Items which contain either spaces or commas are surrounded by braces.

\clist_concat:NNN \clist_concat:NNN hcomma list1 i hcomma list2 i hcomma list3 i

\clist_concat:ccc
Concatenates the content of hcomma list2 i and hcomma list3 i together and saves the
\clist_gconcat:NNN
\clist_gconcat:ccc result in hcomma list1 i. The items in hcomma list2 i will be placed at the left side of the
new comma list.

\clist_if_exist_p:N ? \clist_if_exist_p:N hcomma list i

\clist_if_exist_p:c ? \clist_if_exist:NTF hcomma list i {htrue code i} {hfalse code i}
\clist_if_exist:NTF ? Tests whether the hcomma listi is currently defined. This does not check that the hcomma
\clist_if_exist:cTF ?
listi really is a comma list.
New: 2012-03-03

2 Adding data to comma lists

\clist_set:Nn \clist_set:Nn hcomma list i {hitem1 i,...,hitemn i}

\clist_set:(NV|No|Nx|cn|cV|co|cx)
\clist_gset:Nn
\clist_gset:(NV|No|Nx|cn|cV|co|cx)
New: 2011-09-06

Sets hcomma listi to contain the hitemsi, removing any previous content from the variable.
Spaces are removed from both sides of each item.

118
\clist_put_left:Nn \clist_put_left:Nn hcomma list i {hitem1 i,...,hitemn i}
\clist_put_left:(NV|No|Nx|cn|cV|co|cx)
\clist_gput_left:Nn
\clist_gput_left:(NV|No|Nx|cn|cV|co|cx)
Updated: 2011-09-05

Appends the hitemsi to the left of the hcomma listi. Spaces are removed from both sides
of each item.

\clist_put_right:Nn \clist_put_right:Nn hcomma list i {hitem1 i,...,hitemn i}

\clist_put_right:(NV|No|Nx|cn|cV|co|cx)
\clist_gput_right:Nn
\clist_gput_right:(NV|No|Nx|cn|cV|co|cx)
Updated: 2011-09-05

Appends the hitemsi to the right of the hcomma listi. Spaces are removed from both
sides of each item.

3 Modifying comma lists

While comma lists are normally used as ordered lists, it may be necessary to modify the
content. The functions here may be used to update comma lists, while retaining the
order of the unaffected entries.

\clist_remove_duplicates:N \clist_remove_duplicates:N hcomma list i

\clist_remove_duplicates:c
\clist_gremove_duplicates:N
\clist_gremove_duplicates:c

Removes duplicate items from the hcomma listi, leaving the left most copy of each item
in the hcomma listi. The hitemi comparison takes place on a token basis, as for \tl_-
if_eq:nn(TF).

TEXhackers note: This function iterates through every item in the hcomma listi and does
a comparison with the hitemsi already checked. It is therefore relatively slow with large comma
lists. Furthermore, it will not work if any of the items in the hcomma listi contains {, }, or #
(assuming the usual TEX category codes apply).

\clist_remove_all:Nn \clist_remove_all:Nn hcomma list i {hitem i}

\clist_remove_all:cn
Removes every occurrence of hitemi from the hcomma listi. The hitemi comparison takes
\clist_gremove_all:Nn
\clist_gremove_all:cn place on a token basis, as for \tl_if_eq:nn(TF).

Updated: 2011-09-06 TEXhackers note: The hitemi may not contain {, }, or # (assuming the usual TEX
category codes apply).

119
 \clist_reverse:N \clist_reverse:N hcomma list i
\clist_reverse:c
Reverses the order of items stored in the hcomma listi.
\clist_greverse:N
\clist_greverse:c
New: 2014-07-18

\clist_reverse:n \clist_reverse:n {hcomma list i}

New: 2014-07-18 Leaves the items in the hcomma listi in the input stream in reverse order. Braces and
spaces are preserved by this process.

TEXhackers note: The result is returned within \exp_not:n, which means that the
comma list will not expand further when appearing in an x-type argument expansion.

4 Comma list conditionals

\clist_if_empty_p:N ? \clist_if_empty_p:N hcomma list i

\clist_if_empty_p:c ? \clist_if_empty:NTF hcomma list i {htrue code i} {hfalse code i}
\clist_if_empty:NTF ? Tests if the hcomma listi is empty (containing no items).
\clist_if_empty:cTF ?

\clist_if_empty_p:n ? \clist_if_empty_p:n {hcomma list i}

\clist_if_empty:nTF ? \clist_if_empty:nTF {hcomma list i} {htrue code i} {hfalse code i}
New: 2014-07-05 Tests if the hcomma listi is empty (containing no items). The rules for space trimming
are as for other n-type comma-list functions, hence the comma list {~,~,,~} (without
outer braces) is empty, while {~,{},} (without outer braces) contains one element, which
happens to be empty: the comma-list is not empty.

\clist_if_in:NnTF \clist_if_in:NnTF hcomma list i {hitem i} {htrue code i} {hfalse

\clist_if_in:(NV|No|cn|cV|co|nn|nV|no)TF code i}
Updated: 2011-09-06

Tests if the hitemi is present in the hcomma listi. In the case of an n-type hcomma listi,
spaces are stripped from each item, but braces are not removed. Hence,
\clist_if_in:nnTF { a , {b}~ , {b} , c } { b } {true} {false}
yields false.

TEXhackers note: The hitemi may not contain {, }, or # (assuming the usual TEX
category codes apply), and should not contain , nor start or end with a space.

120
 5 Mapping to comma lists
The functions described in this section apply a specified function to each item of a comma
list.
When the comma list is given explicitly, as an n-type argument, spaces are trimmed
around each item. If the result of trimming spaces is empty, the item is ignored.
Otherwise, if the item is surrounded by braces, one set is removed, and the result is
passed to the mapped function. Thus, if your comma list that is being mapped is
{a␣,␣{{b}␣},␣,{},␣{c},} then the arguments passed to the mapped function are ‘a’,
‘{b}␣’, an empty argument, and ‘c’.
When the comma list is given as an N-type argument, spaces have already been
trimmed on input, and items are simply stripped of one set of braces if any. This case is
more efficient than using n-type comma lists.

\clist_map_function:NN I \clist_map_function:NN hcomma list i hfunction i

\clist_map_function:(cN|nN) I
Updated: 2012-06-29

Applies hfunctioni to every hitemi stored in the hcomma listi. The hfunctioni will receive
one argument for each iteration. The hitemsi are returned from left to right. The function
\clist_map_inline:Nn is in general more efficient than \clist_map_function:NN. One
mapping may be nested inside another.

\clist_map_inline:Nn \clist_map_inline:Nn hcomma list i {hinline function i}

\clist_map_inline:(cn|nn)
Applies hinline functioni to every hitemi stored within the hcomma listi. The hinline
Updated: 2012-06-29 functioni should consist of code which will receive the hitemi as #1. One in line mapping
can be nested inside another. The hitemsi are returned from left to right.

\clist_map_variable:NNn \clist_map_variable:NNn hcomma list i htl var. i {hfunction using tl var. i}

\clist_map_variable:(cNn|nNn)
Updated: 2012-06-29

Stores each entry in the hcomma listi in turn in the htl var.i and applies the hfunction
using tl var.i The hfunctioni will usually consist of code making use of the htl var.i, but
this is not enforced. One variable mapping can be nested inside another. The hitemsi
are returned from left to right.

121
\clist_map_break: I \clist_map_break:
Updated: 2012-06-29 Used to terminate a \clist_map_... function before all entries in the hcomma listi
have been processed. This will normally take place within a conditional statement, for
example
\clist_map_inline:Nn \l_my_clist
{
\str_if_eq:nnTF { #1 } { bingo }
{ \clist_map_break: }
{
% Do something useful
}
}

Use outside of a \clist_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before further items are taken from the input stream.
This will depend on the design of the mapping function.

\clist_map_break:n I \clist_map_break:n {htokens i}

Updated: 2012-06-29 Used to terminate a \clist_map_... function before all entries in the hcomma listi have
been processed, inserting the htokensi after the mapping has ended. This will normally
take place within a conditional statement, for example
\clist_map_inline:Nn \l_my_clist
{
\str_if_eq:nnTF { #1 } { bingo }
{ \clist_map_break:n { <tokens> } }
{
% Do something useful
}
}

Use outside of a \clist_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before the htokensi are inserted into the input stream.
This will depend on the design of the mapping function.

\clist_count:N ? \clist_count:N hcomma list i

\clist_count:(c|n) ?
Leaves the number of items in the hcomma listi in the input stream as an hinteger
New: 2012-07-13 denotationi. The total number of items in a hcomma listi will include those which are
duplicates, i.e. every item in a hcomma listi is unique.

122
 6 Using the content of comma lists directly

\clist_use:Nnnn ? \clist_use:Nnnn hclist var i {hseparator between two i}

\clist_use:cnnn ? {hseparator between more than two i} {hseparator between final two i}
New: 2013-05-26 Places the contents of the hclist vari in the input stream, with the appropriate hseparatori
between the items. Namely, if the comma list has more than two items, the hseparator
between more than twoi is placed between each pair of items except the last, for which
the hseparator between final twoi is used. If the comma list has exactly two items, then
they are placed in the input stream separated by the hseparator between twoi. If the
comma list has a single item, it is placed in the input stream, and a comma list with no
items produces no output. An error will be raised if the variable does not exist or if it is
invalid.
For example,
\clist_set:Nn \l_tmpa_clist { a , b , , c , {de} , f }
\clist_use:Nnnn \l_tmpa_clist { ~and~ } { ,~ } { ,~and~ }
will insert “a, b, c, de, and f” in the input stream. The first separator argument is
not used in this case because the comma list has more than 2 items.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemsi will not expand further when appearing in an x-type argument
expansion.

\clist_use:Nn ? \clist_use:Nn hclist var i {hseparator i}

\clist_use:cn ?
Places the contents of the hclist vari in the input stream, with the hseparatori between
New: 2013-05-26 the items. If the comma list has a single item, it is placed in the input stream, and a
comma list with no items produces no output. An error will be raised if the variable does
not exist or if it is invalid.
For example,
\clist_set:Nn \l_tmpa_clist { a , b , , c , {de} , f }
\clist_use:Nn \l_tmpa_clist { ~and~ }

will insert “a and b and c and de and f” in the input stream.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemsi will not expand further when appearing in an x-type argument
expansion.

7 Comma lists as stacks

Comma lists can be used as stacks, where data is pushed to and popped from the top
of the comma list. (The left of a comma list is the top, for performance reasons.) The

123
 stack functions for comma lists are not intended to be mixed with the general ordered
data functions detailed in the previous section: a comma list should either be used as an
ordered data type or as a stack, but not in both ways.

\clist_get:NN \clist_get:NN hcomma list i htoken list variable i

\clist_get:cN
Stores the left-most item from a hcomma listi in the htoken list variablei without removing
Updated: 2012-05-14 it from the hcomma listi. The htoken list variablei is assigned locally. If the hcomma listi
is empty the htoken list variablei will contain the marker value \q_no_value.

\clist_get:NNTF \clist_get:NNTF hcomma list i htoken list variable i {htrue code i} {hfalse code i}
\clist_get:cNTF
If the hcomma listi is empty, leaves the hfalse codei in the input stream. The value of
New: 2012-05-14 the htoken list variablei is not defined in this case and should not be relied upon. If the
hcomma listi is non-empty, stores the top item from the hcomma listi in the htoken list
variablei without removing it from the hcomma listi. The htoken list variablei is assigned
locally.

\clist_pop:NN \clist_pop:NN hcomma list i htoken list variable i

\clist_pop:cN
Pops the left-most item from a hcomma listi into the htoken list variablei, i.e. removes the
Updated: 2011-09-06 item from the comma list and stores it in the htoken list variablei. Both of the variables
are assigned locally.

\clist_gpop:NN \clist_gpop:NN hcomma list i htoken list variable i

\clist_gpop:cN
Pops the left-most item from a hcomma listi into the htoken list variablei, i.e. removes
the item from the comma list and stores it in the htoken list variablei. The hcomma listi
is modified globally, while the assignment of the htoken list variablei is local.

\clist_pop:NNTF \clist_pop:NNTF hsequence i htoken list variable i {htrue code i} {hfalse code i}
\clist_pop:cNTF
If the hcomma listi is empty, leaves the hfalse codei in the input stream. The value of
New: 2012-05-14 the htoken list variablei is not defined in this case and should not be relied upon. If the
hcomma listi is non-empty, pops the top item from the hcomma listi in the htoken list
variablei, i.e. removes the item from the hcomma listi. Both the hcomma listi and the
htoken list variablei are assigned locally.

\clist_gpop:NNTF \clist_gpop:NNTF hcomma list i htoken list variable i {htrue code i} {hfalse code i}
\clist_gpop:cNTF
If the hcomma listi is empty, leaves the hfalse codei in the input stream. The value of
New: 2012-05-14 the htoken list variablei is not defined in this case and should not be relied upon. If the
hcomma listi is non-empty, pops the top item from the hcomma listi in the htoken list
variablei, i.e. removes the item from the hcomma listi. The hcomma listi is modified
globally, while the htoken list variablei is assigned locally.

124
\clist_push:Nn \clist_push:Nn hcomma list i {hitems i}
\clist_push:(NV|No|Nx|cn|cV|co|cx)
\clist_gpush:Nn
\clist_gpush:(NV|No|Nx|cn|cV|co|cx)

Adds the {hitemsi} to the top of the hcomma listi. Spaces are removed from both sides
of each item.

8 Using a single item

\clist_item:Nn ? \clist_item:Nn hcomma list i {hinteger expression i}

\clist_item:(cn|nn) ?
Indexing items in the hcomma listi from 1 at the top (left), this function will evaluate
New: 2014-07-17 the hinteger expressioni and leave the appropriate item from the comma list in the input
stream. If the hinteger expressioni is negative, indexing occurs from the bottom (right)
of the comma list. When the hinteger expressioni is larger than the number of items in
the hcomma listi (as calculated by \clist_count:N) then the function will expand to
nothing.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the hitemi will not expand further when appearing in an x-type argument
expansion.

9 Viewing comma lists

\clist_show:N \clist_show:N hcomma list i

\clist_show:c
Displays the entries in the hcomma listi in the terminal.
Updated: 2012-09-09

\clist_show:n \clist_show:n {htokens i}

Updated: 2012-09-09 Displays the entries in the comma list in the terminal.

10 Constant and scratch comma lists

\c_empty_clist Constant that is always empty.

New: 2012-07-02

\l_tmpa_clist Scratch comma lists for local assignment. These are never used by the kernel code, and
\l_tmpb_clist so are safe for use with any LATEX3-defined function. However, they may be overwritten
New: 2011-09-06 by other non-kernel code and so should only be used for short-term storage.

125
\g_tmpa_clist Scratch comma lists for global assignment. These are never used by the kernel code, and
\g_tmpb_clist so are safe for use with any LATEX3-defined function. However, they may be overwritten
New: 2011-09-06 by other non-kernel code and so should only be used for short-term storage.

126
 Part XV
The l3prop package
Property lists
LATEX3 implements a “property list” data type, which contain an unordered list of entries
each of which consists of a hkeyi and an associated hvaluei. The hkeyi and hvaluei may
both be any hbalanced texti. It is possible to map functions to property lists such that
the function is applied to every key–value pair within the list.
Each entry in a property list must have a unique hkeyi: if an entry is added to
a property list which already contains the hkeyi then the new entry will overwrite the
existing one. The hkeysi are compared on a string basis, using the same method as
\str_if_eq:nn.
Property lists are intended for storing key-based information for use within code.
This is in contrast to key–value lists, which are a form of input parsed by the keys
module.

1 Creating and initialising property lists

\prop_new:N \prop_new:N hproperty list i

\prop_new:c
Creates a new hproperty listi or raises an error if the name is already taken. The decla-
ration is global. The hproperty listi will initially contain no entries.

\prop_clear:N \prop_clear:N hproperty list i

\prop_clear:c
Clears all entries from the hproperty listi.
\prop_gclear:N
\prop_gclear:c

\prop_clear_new:N \prop_clear_new:N hproperty list i

\prop_clear_new:c
Ensures that the hproperty listi exists globally by applying \prop_new:N if necessary,
\prop_gclear_new:N
\prop_gclear_new:c then applies \prop_(g)clear:N to leave the list empty.

\prop_set_eq:NN \prop_set_eq:NN hproperty list1 i hproperty list2 i

\prop_set_eq:(cN|Nc|cc)
Sets the content of hproperty list1 i equal to that of hproperty list2 i.
\prop_gset_eq:NN
\prop_gset_eq:(cN|Nc|cc)

127
 2 Adding entries to property lists

\prop_put:Nnn \prop_put:Nnn hproperty list i

\prop_put:(NnV|Nno|Nnx|NVn|NVV|Non|Noo|cnn|cnV|cno|cnx|cVn|cVV|con|coo) {hkey i} {hvalue i}
\prop_gput:Nnn
\prop_gput:(NnV|Nno|Nnx|NVn|NVV|Non|Noo|cnn|cnV|cno|cnx|cVn|cVV|con|coo)
Updated: 2012-07-09

Adds an entry to the hproperty listi which may be accessed using the hkeyi and which
has hvaluei. Both the hkeyi and hvaluei may contain any hbalanced texti. The hkeyi is
stored after processing with \tl_to_str:n, meaning that category codes are ignored. If
the hkeyi is already present in the hproperty listi, the existing entry is overwritten by the
new hvaluei.

\prop_put_if_new:Nnn \prop_put_if_new:Nnn hproperty list i {hkey i} {hvalue i}

\prop_put_if_new:cnn
If the hkeyi is present in the hproperty listi then no action is taken. If the hkeyi is not
\prop_gput_if_new:Nnn
\prop_gput_if_new:cnn present in the hproperty listi then a new entry is added. Both the hkeyi and hvaluei may
contain any hbalanced texti. The hkeyi is stored after processing with \tl_to_str:n,
meaning that category codes are ignored.

3 Recovering values from property lists

\prop_get:NnN \prop_get:NnN hproperty list i {hkey i} htl var i

\prop_get:(NVN|NoN|cnN|cVN|coN)
Updated: 2011-08-28

Recovers the hvaluei stored with hkeyi from the hproperty listi, and places this in the
htoken list variablei. If the hkeyi is not found in the hproperty listi then the htoken list
variablei will contain the special marker \q_no_value. The htoken list variablei is set
within the current TEX group. See also \prop_get:NnNTF.

\prop_pop:NnN \prop_pop:NnN hproperty list i {hkey i} htl var i

\prop_pop:(NoN|cnN|coN)
Recovers the hvaluei stored with hkeyi from the hproperty listi, and places this in the
Updated: 2011-08-18 htoken list variablei. If the hkeyi is not found in the hproperty listi then the htoken list
variablei will contain the special marker \q_no_value. The hkeyi and hvaluei are then
deleted from the property list. Both assignments are local. See also \prop_pop:NnNTF.

\prop_gpop:NnN \prop_gpop:NnN hproperty list i {hkey i} htl var i

\prop_gpop:(NoN|cnN|coN)
Recovers the hvaluei stored with hkeyi from the hproperty listi, and places this in the
Updated: 2011-08-18 htoken list variablei. If the hkeyi is not found in the hproperty listi then the htoken
list variablei will contain the special marker \q_no_value. The hkeyi and hvaluei are
then deleted from the property list. The hproperty listi is modified globally, while the
assignment of the htoken list variablei is local. See also \prop_gpop:NnNTF.

128
 \prop_item:Nn ? \prop_item:Nn hproperty list i {hkey i}
\prop_item:cn ?
Expands to the hvaluei corresponding to the hkeyi in the hproperty listi. If the hkeyi is
New: 2014-07-17 missing, this has an empty expansion.

TEXhackers note: This function is slower than the non-expandable analogue \prop_-
get:NnN. The result is returned within the \unexpanded primitive (\exp_not:n), which means
that the hvaluei will not expand further when appearing in an x-type argument expansion.

4 Modifying property lists

\prop_remove:Nn \prop_remove:Nn hproperty list i {hkey i}

\prop_remove:(NV|cn|cV)
Removes the entry listed under hkeyi from the hproperty listi. If the hkeyi is not found
\prop_gremove:Nn
\prop_gremove:(NV|cn|cV) in the hproperty listi no change occurs, i.e there is no need to test for the existence of a
key before deleting it.
New: 2012-05-12

5 Property list conditionals

\prop_if_exist_p:N ? \prop_if_exist_p:N hproperty list i

\prop_if_exist_p:c ? \prop_if_exist:NTF hproperty list i {htrue code i} {hfalse code i}
\prop_if_exist:NTF ? Tests whether the hproperty listi is currently defined. This does not check that the
\prop_if_exist:cTF ?
hproperty listi really is a property list variable.
New: 2012-03-03

\prop_if_empty_p:N ? \prop_if_empty_p:N hproperty list i

\prop_if_empty_p:c ? \prop_if_empty:NTF hproperty list i {htrue code i} {hfalse code i}
\prop_if_empty:NTF ? Tests if the hproperty listi is empty (containing no entries).
\prop_if_empty:cTF ?

\prop_if_in_p:Nn ? \prop_if_in:NnTF hproperty list i {hkey i} {htrue code i} {hfalse code i}

\prop_if_in_p:(NV|No|cn|cV|co) ?
\prop_if_in:NnTF ?
\prop_if_in:(NV|No|cn|cV|co)TF ?
Updated: 2011-09-15

Tests if the hkeyi is present in the hproperty listi, making the comparison using the
method described by \str_if_eq:nnTF.

TEXhackers note: This function iterates through every key–value pair in the hproperty
listi and is therefore slower than using the non-expandable \prop_get:NnNTF.

129
 6 Recovering values from property lists with branch-
ing
The functions in this section combine tests for the presence of a key in a property list
with recovery of the associated valued. This makes them useful for cases where different
cases follow dependent on the presence or absence of a key in a property list. They offer
increased readability and performance over separate testing and recovery phases.

\prop_get:NnNTF \prop_get:NnNTF hproperty list i {hkey i} htoken list variable i

\prop_get:(NVN|NoN|cnN|cVN|coN)TF {htrue code i} {hfalse code i}
Updated: 2012-05-19

If the hkeyi is not present in the hproperty listi, leaves the hfalse codei in the input stream.
The value of the htoken list variablei is not defined in this case and should not be relied
upon. If the hkeyi is present in the hproperty listi, stores the corresponding hvaluei in the
htoken list variablei without removing it from the hproperty listi, then leaves the htrue
codei in the input stream. The htoken list variablei is assigned locally.

\prop_pop:NnNTF \prop_pop:NnNTF hproperty list i {hkey i} htoken list variable i {htrue code i}
\prop_pop:cnNTF {hfalse code i}
New: 2011-08-18 If the hkeyi is not present in the hproperty listi, leaves the hfalse codei in the input stream.
Updated: 2012-05-19 The value of the htoken list variablei is not defined in this case and should not be relied
upon. If the hkeyi is present in the hproperty listi, pops the corresponding hvaluei in the
htoken list variablei, i.e. removes the item from the hproperty listi. Both the hproperty
listi and the htoken list variablei are assigned locally.

\prop_gpop:NnNTF \prop_gpop:NnNTF hproperty list i {hkey i} htoken list variable i {htrue code i}
\prop_gpop:cnNTF {hfalse code i}
New: 2011-08-18 If the hkeyi is not present in the hproperty listi, leaves the hfalse codei in the input stream.
Updated: 2012-05-19 The value of the htoken list variablei is not defined in this case and should not be relied
upon. If the hkeyi is present in the hproperty listi, pops the corresponding hvaluei in the
htoken list variablei, i.e. removes the item from the hproperty listi. The hproperty listi is
modified globally, while the htoken list variablei is assigned locally.

7 Mapping to property lists

\prop_map_function:NN I \prop_map_function:NN hproperty list i hfunction i

\prop_map_function:cN I
Applies hfunctioni to every hentryi stored in the hproperty listi. The hfunctioni will
Updated: 2013-01-08 receive two argument for each iteration: the hkeyi and associated hvaluei. The order in
which hentriesi are returned is not defined and should not be relied upon.

130
\prop_map_inline:Nn \prop_map_inline:Nn hproperty list i {hinline function i}
\prop_map_inline:cn
Applies hinline functioni to every hentryi stored within the hproperty listi. The hinline
Updated: 2013-01-08 functioni should consist of code which will receive the hkeyi as #1 and the hvaluei as #2.
The order in which hentriesi are returned is not defined and should not be relied upon.

\prop_map_break: I \prop_map_break:
Updated: 2012-06-29 Used to terminate a \prop_map_... function before all entries in the hproperty listi
have been processed. This will normally take place within a conditional statement, for
example
\prop_map_inline:Nn \l_my_prop
{
\str_if_eq:nnTF { #1 } { bingo }
{ \prop_map_break: }
{
% Do something useful
}
}
Use outside of a \prop_map_... scenario will lead to low level TEX errors.

\prop_map_break:n I \prop_map_break:n {htokens i}

Updated: 2012-06-29 Used to terminate a \prop_map_... function before all entries in the hproperty listi have
been processed, inserting the htokensi after the mapping has ended. This will normally
take place within a conditional statement, for example
\prop_map_inline:Nn \l_my_prop
{
\str_if_eq:nnTF { #1 } { bingo }
{ \prop_map_break:n { <tokens> } }
{
% Do something useful
}
}
Use outside of a \prop_map_... scenario will lead to low level TEX errors.

8 Viewing property lists

\prop_show:N \prop_show:N hproperty list i

\prop_show:c
Displays the entries in the hproperty listi in the terminal.
Updated: 2012-09-09

131
 9 Scratch property lists

\l_tmpa_prop Scratch property lists for local assignment. These are never used by the kernel code, and
\l_tmpb_prop so are safe for use with any LATEX3-defined function. However, they may be overwritten
New: 2012-06-23 by other non-kernel code and so should only be used for short-term storage.

\g_tmpa_prop Scratch property lists for global assignment. These are never used by the kernel code, and
\g_tmpb_prop so are safe for use with any LATEX3-defined function. However, they may be overwritten
New: 2012-06-23 by other non-kernel code and so should only be used for short-term storage.

10 Constants

\c_empty_prop A permanently-empty property list used for internal comparisons.

11 Internal property list functions

\s__prop The internal token used at the beginning of property lists. This is also used after each
hkeyi (see \__prop_pair:wn).

\__prop_pair:wn \__prop_pair:wn hkey i \s__prop {hitem i}

The internal token used to begin each key–value pair in the property list. If expanded
outside of a mapping or manipulation function, an error will be raised. The definition
should always be set globally.

\l__prop_internal_tl Token list used to store new key–value pairs to be inserted by functions of the \prop_-
put:Nnn family.

\__prop_split:NnTF \__prop_split:NnTF hproperty list i {hkey i} {htrue code i} {hfalse code i}

Updated: 2013-01-08 Splits the hproperty listi at the hkeyi, giving three token lists: the hextracti of hproperty
listi before the hkeyi, the hvaluei associated with the hkeyi and the hextracti of the
hproperty listi after the hvaluei. Both hextractsi retain the internal structure of a property
list, and the concatenation of the two hextractsi is a property list. If the hkeyi is present
in the hproperty listi then the htrue codei is left in the input stream, with #1, #2, and
#3 replaced by the first hextracti, the hvaluei, and the second extract. If the hkeyi is not
present in the hproperty listi then the hfalse codei is left in the input stream, with no
trailing material. Both htrue codei and hfalse codei are used in the replacement text of
a macro defined internally, hence macro parameter characters should be doubled, except
#1, #2, and #3 which stand in the htrue codei for the three extracts from the property
list. The hkeyi comparison takes place as described for \str_if_eq:nn.

132
 Part XVI
The l3box package
Boxes
There are three kinds of box operations: horizontal mode denoted with prefix \hbox_,
vertical mode with prefix \vbox_, and the generic operations working in both modes with
prefix \box_.

1 Creating and initialising boxes

\box_new:N \box_new:N hbox i

\box_new:c
Creates a new hboxi or raises an error if the name is already taken. The declaration is
global. The hboxi will initially be void.

\box_clear:N \box_clear:N hbox i

\box_clear:c
Clears the content of the hboxi by setting the box equal to \c_void_box.
\box_gclear:N
\box_gclear:c

\box_clear_new:N \box_clear_new:N hbox i

\box_clear_new:c
Ensures that the hboxi exists globally by applying \box_new:N if necessary, then applies
\box_gclear_new:N
\box_gclear_new:c \box_(g)clear:N to leave the hboxi empty.

\box_set_eq:NN \box_set_eq:NN hbox1 i hbox2 i

\box_set_eq:(cN|Nc|cc)
Sets the content of hbox1 i equal to that of hbox2 i.
\box_gset_eq:NN
\box_gset_eq:(cN|Nc|cc)

\box_set_eq_clear:NN \box_set_eq_clear:NN hbox1 i hbox2 i

\box_set_eq_clear:(cN|Nc|cc)
Sets the content of hbox1 i within the current TEX group equal to that of hbox2 i, then
clears hbox2 i globally.

\box_gset_eq_clear:NN \box_gset_eq_clear:NN hbox1 i hbox2 i

\box_gset_eq_clear:(cN|Nc|cc)

Sets the content of hbox1 i equal to that of hbox2 i, then clears hbox2 i. These assignments
are global.

133
\box_if_exist_p:N ? \box_if_exist_p:N hbox i
\box_if_exist_p:c ? \box_if_exist:NTF hbox i {htrue code i} {hfalse code i}
\box_if_exist:NTF ? Tests whether the hboxi is currently defined. This does not check that the hboxi really is
\box_if_exist:cTF ?
a box.
New: 2012-03-03

2 Using boxes

\box_use:N \box_use:N hbox i

\box_use:c
Inserts the current content of the hboxi onto the current list for typesetting.

TEXhackers note: This is the TEX primitive \copy.

\box_use_clear:N \box_use_clear:N hbox i

\box_use_clear:c
Inserts the current content of the hboxi onto the current list for typesetting, then globally
clears the content of the hboxi.

TEXhackers note: This is the TEX primitive \box.

\box_move_right:nn \box_move_right:nn {hdimexpr i} {hbox function i}

\box_move_left:nn
This function operates in vertical mode, and inserts the material specified by the hbox
functioni such that its reference point is displaced horizontally by the given hdimexpri
from the reference point for typesetting, to the right or left as appropriate. The hbox
functioni should be a box operation such as \box_use:N \<box> or a “raw” box specifi-
cation such as \vbox:n { xyz }.

\box_move_up:nn \box_move_up:nn {hdimexpr i} {hbox function i}

\box_move_down:nn
This function operates in horizontal mode, and inserts the material specified by the
hbox functioni such that its reference point is displaced vertical by the given hdimexpri
from the reference point for typesetting, up or down as appropriate. The hbox functioni
should be a box operation such as \box_use:N \<box> or a “raw” box specification such
as \vbox:n { xyz }.

3 Measuring and setting box dimensions

\box_dp:N \box_dp:N hbox i

\box_dp:c
Calculates the depth (below the baseline) of the hboxi in a form suitable for use in a
hdimension expressioni.

TEXhackers note: This is the TEX primitive \dp.

134
 \box_ht:N \box_ht:N hbox i
\box_ht:c
Calculates the height (above the baseline) of the hboxi in a form suitable for use in a
hdimension expressioni.

TEXhackers note: This is the TEX primitive \ht.

\box_wd:N \box_wd:N hbox i

\box_wd:c
Calculates the width of the hboxi in a form suitable for use in a hdimension expressioni.

TEXhackers note: This is the TEX primitive \wd.

\box_set_dp:Nn \box_set_dp:Nn hbox i {hdimension expression i}

\box_set_dp:cn
Set the depth (below the baseline) of the hboxi to the value of the {hdimension
Updated: 2011-10-22 expressioni}. This is a global assignment.

\box_set_ht:Nn \box_set_ht:Nn hbox i {hdimension expression i}

\box_set_ht:cn
Set the height (above the baseline) of the hboxi to the value of the {hdimension
Updated: 2011-10-22 expressioni}. This is a global assignment.

\box_set_wd:Nn \box_set_wd:Nn hbox i {hdimension expression i}

\box_set_wd:cn
Set the width of the hboxi to the value of the {hdimension expressioni}. This is a global
Updated: 2011-10-22 assignment.

4 Box conditionals

\box_if_empty_p:N ? \box_if_empty_p:N hbox i

\box_if_empty_p:c ? \box_if_empty:NTF hbox i {htrue code i} {hfalse code i}
\box_if_empty:NTF ? Tests if hboxi is a empty (equal to \c_empty_box).
\box_if_empty:cTF ?

\box_if_horizontal_p:N ? \box_if_horizontal_p:N hbox i

\box_if_horizontal_p:c ? \box_if_horizontal:NTF hbox i {htrue code i} {hfalse code i}
\box_if_horizontal:NTF ? Tests if hboxi is a horizontal box.
\box_if_horizontal:cTF ?

\box_if_vertical_p:N ? \box_if_vertical_p:N hbox i

\box_if_vertical_p:c ? \box_if_vertical:NTF hbox i {htrue code i} {hfalse code i}
\box_if_vertical:NTF ? Tests if hboxi is a vertical box.
\box_if_vertical:cTF ?

135
 5 The last box inserted

\box_set_to_last:N \box_set_to_last:N hbox i

\box_set_to_last:c
Sets the hboxi equal to the last item (box) added to the current partial list, removing the
\box_gset_to_last:N
\box_gset_to_last:c item from the list at the same time. When applied to the main vertical list, the hboxi
will always be void as it is not possible to recover the last added item.

6 Constant boxes

\c_empty_box This is a permanently empty box, which is neither set as horizontal nor vertical.
Updated: 2012-11-04

7 Scratch boxes

\l_tmpa_box Scratch boxes for local assignment. These are never used by the kernel code, and so are
\l_tmpb_box safe for use with any LATEX3-defined function. However, they may be overwritten by
Updated: 2012-11-04 other non-kernel code and so should only be used for short-term storage.

\g_tmpa_box Scratch boxes for global assignment. These are never used by the kernel code, and so
\g_tmpb_box are safe for use with any LATEX3-defined function. However, they may be overwritten by
other non-kernel code and so should only be used for short-term storage.

8 Viewing box contents

\box_show:N \box_show:N hbox i

\box_show:c
Shows full details of the content of the hboxi in the terminal.
Updated: 2012-05-11

\box_show:Nnn \box_show:Nnn hbox i hintexpr1 i hintexpr2 i

\box_show:cnn
Display the contents of hboxi in the terminal, showing the first hintexpr1 i items of the
New: 2012-05-11 box, and descending into hintexpr2 i group levels.

\box_log:N \box_log:N hbox i

\box_log:c
Writes full details of the content of the hboxi to the log.
New: 2012-05-11

136
 \box_log:Nnn \box_log:Nnn hbox i hintexpr1 i hintexpr2 i
\box_log:cnn
Writes the contents of hboxi to the log, showing the first hintexpr1 i items of the box, and
New: 2012-05-11 descending into hintexpr2 i group levels.

9 Horizontal mode boxes

\hbox:n \hbox:n {hcontents i}

Typesets the hcontentsi into a horizontal box of natural width and then includes this box
in the current list for typesetting.

TEXhackers note: This is the TEX primitive \hbox.

\hbox_to_wd:nn \hbox_to_wd:nn {hdimexpr i} {hcontents i}

Typesets the hcontentsi into a horizontal box of width hdimexpri and then includes this
box in the current list for typesetting.

\hbox_to_zero:n \hbox_to_zero:n {hcontents i}

Typesets the hcontentsi into a horizontal box of zero width and then includes this box in
the current list for typesetting.

\hbox_set:Nn \hbox_set:Nn hbox i {hcontents i}

\hbox_set:cn
Typesets the hcontentsi at natural width and then stores the result inside the hboxi.
\hbox_gset:Nn
\hbox_gset:cn

\hbox_set_to_wd:Nnn \hbox_set_to_wd:Nnn hbox i {hdimexpr i} {hcontents i}

\hbox_set_to_wd:cnn
Typesets the hcontentsi to the width given by the hdimexpri and then stores the result
\hbox_gset_to_wd:Nnn
\hbox_gset_to_wd:cnn inside the hboxi.

\hbox_overlap_right:n \hbox_overlap_right:n {hcontents i}

Typesets the hcontentsi into a horizontal box of zero width such that material will pro-
trude to the right of the insertion point.

\hbox_overlap_left:n \hbox_overlap_left:n {hcontents i}

Typesets the hcontentsi into a horizontal box of zero width such that material will pro-
trude to the left of the insertion point.

137
 \hbox_set:Nw \hbox_set:Nw hbox i hcontents i \hbox_set_end:
\hbox_set:cw
Typesets the hcontentsi at natural width and then stores the result inside the hboxi. In
\hbox_set_end:
\hbox_gset:Nw contrast to \hbox_set:Nn this function does not absorb the argument when finding the
\hbox_gset:cw hcontenti, and so can be used in circumstances where the hcontenti may not be a simple
\hbox_gset_end: argument.

\hbox_unpack:N \hbox_unpack:N hbox i

\hbox_unpack:c
Unpacks the content of the horizontal hboxi, retaining any stretching or shrinking applied
when the hboxi was set.

TEXhackers note: This is the TEX primitive \unhcopy.

\hbox_unpack_clear:N \hbox_unpack_clear:N hbox i

\hbox_unpack_clear:c
Unpacks the content of the horizontal hboxi, retaining any stretching or shrinking applied
when the hboxi was set. The hboxi is then cleared globally.

TEXhackers note: This is the TEX primitive \unhbox.

10 Vertical mode boxes

Vertical boxes inherit their baseline from their contents. The standard case is that the
baseline of the box is at the same position as that of the last item added to the box.
This means that the box will have no depth unless the last item added to it had depth.
As a result most vertical boxes have a large height value and small or zero depth. The
exception are _top boxes, where the reference point is that of the first item added. These
tend to have a large depth and small height, although the latter will typically be non-zero.

\vbox:n \vbox:n {hcontents i}

Updated: 2011-12-18 Typesets the hcontentsi into a vertical box of natural height and includes this box in the
current list for typesetting.

TEXhackers note: This is the TEX primitive \vbox.

\vbox_top:n \vbox_top:n {hcontents i}

Updated: 2011-12-18 Typesets the hcontentsi into a vertical box of natural height and includes this box in the
current list for typesetting. The baseline of the box will be equal to that of the first item
added to the box.

TEXhackers note: This is the TEX primitive \vtop.

138
 \vbox_to_ht:nn \vbox_to_ht:nn {hdimexpr i} {hcontents i}
Updated: 2011-12-18 Typesets the hcontentsi into a vertical box of height hdimexpri and then includes this
box in the current list for typesetting.

\vbox_to_zero:n \vbox_to_zero:n {hcontents i}

Updated: 2011-12-18 Typesets the hcontentsi into a vertical box of zero height and then includes this box in
the current list for typesetting.

\vbox_set:Nn \vbox_set:Nn hbox i {hcontents i}

\vbox_set:cn
Typesets the hcontentsi at natural height and then stores the result inside the hboxi.
\vbox_gset:Nn
\vbox_gset:cn
Updated: 2011-12-18

\vbox_set_top:Nn \vbox_set_top:Nn hbox i {hcontents i}

\vbox_set_top:cn
Typesets the hcontentsi at natural height and then stores the result inside the hboxi. The
\vbox_gset_top:Nn
\vbox_gset_top:cn baseline of the box will be equal to that of the first item added to the box.

Updated: 2011-12-18

\vbox_set_to_ht:Nnn \vbox_set_to_ht:Nnn hbox i {hdimexpr i} {hcontents i}

\vbox_set_to_ht:cnn
Typesets the hcontentsi to the height given by the hdimexpri and then stores the result
\vbox_gset_to_ht:Nnn
\vbox_gset_to_ht:cnn inside the hboxi.

Updated: 2011-12-18

\vbox_set:Nw \vbox_set:Nw hbox i hcontents i \vbox_set_end:

\vbox_set:cw
Typesets the hcontentsi at natural height and then stores the result inside the hboxi. In
\vbox_set_end:
\vbox_gset:Nw contrast to \vbox_set:Nn this function does not absorb the argument when finding the
\vbox_gset:cw hcontenti, and so can be used in circumstances where the hcontenti may not be a simple
\vbox_gset_end: argument.
Updated: 2011-12-18

\vbox_set_split_to_ht:NNn \vbox_set_split_to_ht:NNn hbox1 i hbox2 i {hdimexpr i}

Updated: 2011-10-22 Sets hbox1 i to contain material to the height given by the hdimexpri by removing content
from the top of hbox2 i (which must be a vertical box).

TEXhackers note: This is the TEX primitive \vsplit.

139
 \vbox_unpack:N \vbox_unpack:N hbox i
\vbox_unpack:c
Unpacks the content of the vertical hboxi, retaining any stretching or shrinking applied
when the hboxi was set.

TEXhackers note: This is the TEX primitive \unvcopy.

\vbox_unpack_clear:N \vbox_unpack:N hbox i

\vbox_unpack_clear:c
Unpacks the content of the vertical hboxi, retaining any stretching or shrinking applied
when the hboxi was set. The hboxi is then cleared globally.

TEXhackers note: This is the TEX primitive \unvbox.

11 Primitive box conditionals

\if_hbox:N ? \if_hbox:N hbox i

htrue code i
\else:
hfalse code i
\fi:
Tests is hboxi is a horizontal box.

TEXhackers note: This is the TEX primitive \ifhbox.

\if_vbox:N ? \if_vbox:N hbox i

htrue code i
\else:
hfalse code i
\fi:
Tests is hboxi is a vertical box.

TEXhackers note: This is the TEX primitive \ifvbox.

\if_box_empty:N ? \if_box_empty:N hbox i

htrue code i
\else:
hfalse code i
\fi:
Tests is hboxi is an empty (void) box.

TEXhackers note: This is the TEX primitive \ifvoid.

140
 Part XVII
The l3coffins package
Coffin code layer
The material in this module provides the low-level support system for coffins. For details
about the design concept of a coffin, see the xcoffins module (in the l3experimental bundle).

1 Creating and initialising coffins

\coffin_new:N \coffin_new:N hcoffin i

\coffin_new:c
Creates a new hcoffini or raises an error if the name is already taken. The declaration is
New: 2011-08-17 global. The hcoffini will initially be empty.

\coffin_clear:N \coffin_clear:N hcoffin i

\coffin_clear:c
Clears the content of the hcoffini within the current TEX group level.
New: 2011-08-17

\coffin_set_eq:NN \coffin_set_eq:NN hcoffin1 i hcoffin2 i

\coffin_set_eq:(Nc|cN|cc)
Sets both the content and poles of hcoffin1 i equal to those of hcoffin2 i within the current
New: 2011-08-17 TEX group level.

\coffin_if_exist_p:N ? \coffin_if_exist_p:N hbox i

\coffin_if_exist_p:c ? \coffin_if_exist:NTF hbox i {htrue code i} {hfalse code i}
\coffin_if_exist:NTF ? Tests whether the hcoffini is currently defined.
\coffin_if_exist:cTF ?
New: 2012-06-20

2 Setting coffin content and poles

All coffin functions create and manipulate coffins locally within the current TEX group
level.

\hcoffin_set:Nn \hcoffin_set:Nn hcoffin i {hmaterial i}

\hcoffin_set:cn
Typesets the hmateriali in horizontal mode, storing the result in the hcoffini. The stan-
New: 2011-08-17 dard poles for the hcoffini are then set up based on the size of the typeset material.
Updated: 2011-09-03

141
 \hcoffin_set:Nw \hcoffin_set:Nw hcoffin i hmaterial i \hcoffin_set_end:
\hcoffin_set:cw
Typesets the hmateriali in horizontal mode, storing the result in the hcoffini. The stan-
\hcoffin_set_end:
dard poles for the hcoffini are then set up based on the size of the typeset material. These
New: 2011-09-10 functions are useful for setting the entire contents of an environment in a coffin.

\vcoffin_set:Nnn \vcoffin_set:Nnn hcoffin i {hwidth i} {hmaterial i}

\vcoffin_set:cnn
Typesets the hmateriali in vertical mode constrained to the given hwidthi and stores the
New: 2011-08-17 result in the hcoffini. The standard poles for the hcoffini are then set up based on the
Updated: 2012-05-22 size of the typeset material.

\vcoffin_set:Nnw \vcoffin_set:Nnw hcoffin i {hwidth i} hmaterial i \vcoffin_set_end:

\vcoffin_set:cnw
Typesets the hmateriali in vertical mode constrained to the given hwidthi and stores the
\vcoffin_set_end:
result in the hcoffini. The standard poles for the hcoffini are then set up based on the
New: 2011-09-10 size of the typeset material. These functions are useful for setting the entire contents of
Updated: 2012-05-22
an environment in a coffin.

\coffin_set_horizontal_pole:Nnn \coffin_set_horizontal_pole:Nnn hcoffin i

\coffin_set_horizontal_pole:cnn {hpole i} {hoffset i}
New: 2012-07-20

Sets the hpolei to run horizontally through the hcoffini. The hpolei will be located at the
hoffseti from the bottom edge of the bounding box of the hcoffini. The hoffseti should
be given as a dimension expression.

\coffin_set_vertical_pole:Nnn \coffin_set_vertical_pole:Nnn hcoffin i {hpole i} {hoffset i}

\coffin_set_vertical_pole:cnn
New: 2012-07-20

Sets the hpolei to run vertically through the hcoffini. The hpolei will be located at the
hoffseti from the left-hand edge of the bounding box of the hcoffini. The hoffseti should
be given as a dimension expression.

142
 3 Joining and using coffins

\coffin_attach:NnnNnnnn \coffin_attach:NnnNnnnn
\coffin_attach:(cnnNnnnn|Nnncnnnn|cnncnnnn) hcoffin1 i {hcoffin1 -pole1 i} {hcoffin1 -pole2 i}
hcoffin2 i {hcoffin2 -pole1 i} {hcoffin2 -pole2 i}
{hx-offset i} {hy-offset i}
This function attaches hcoffin2 i to hcoffin1 i such that the bounding box of hcoffin1 i
is not altered, i.e. hcoffin2 i can protrude outside of the bounding box of the cof-
fin. The alignment is carried out by first calculating hhandle1 i, the point of intersec-
tion of hcoffin1 -pole1 i and hcoffin1 -pole2 i, and hhandle2 i, the point of intersection of
hcoffin2 -pole1 i and hcoffin2 -pole2 i. hcoffin2 i is then attached to hcoffin1 i such that the
relationship between hhandle1 i and hhandle2 i is described by the hx-offseti and hy-offseti.
The two offsets should be given as dimension expressions.

\coffin_join:NnnNnnnn \coffin_join:NnnNnnnn
\coffin_join:(cnnNnnnn|Nnncnnnn|cnncnnnn) hcoffin1 i {hcoffin1 -pole1 i} {hcoffin1 -pole2 i}
hcoffin2 i {hcoffin2 -pole1 i} {hcoffin2 -pole2 i}
{hx-offset i} {hy-offset i}
This function joins hcoffin2 i to hcoffin1 i such that the bounding box of hcoffin1 i may
expand. The new bounding box will cover the area containing the bounding boxes of
the two original coffins. The alignment is carried out by first calculating hhandle1 i, the
point of intersection of hcoffin1 -pole1 i and hcoffin1 -pole2 i, and hhandle2 i, the point of
intersection of hcoffin2 -pole1 i and hcoffin2 -pole2 i. hcoffin2 i is then attached to hcoffin1 i
such that the relationship between hhandle1 i and hhandle2 i is described by the hx-offseti
and hy-offseti. The two offsets should be given as dimension expressions.

\coffin_typeset:Nnnnn \coffin_typeset:Nnnnn hcoffin i {hpole1 i} {hpole2 i}

\coffin_typeset:cnnnn {hx-offset i} {hy-offset i}
Updated: 2012-07-20 Typesetting is carried out by first calculating hhandlei, the point of intersection of hpole1 i
and hpole2 i. The coffin is then typeset in horizontal mode such that the relationship be-
tween the current reference point in the document and the hhandlei is described by the
hx-offseti and hy-offseti. The two offsets should be given as dimension expressions. Type-
setting a coffin is therefore analogous to carrying out an alignment where the “parent”
coffin is the current insertion point.

4 Measuring coffins

\coffin_dp:N \coffin_dp:N hcoffin i

\coffin_dp:c
Calculates the depth (below the baseline) of the hcoffini in a form suitable for use in a
hdimension expressioni.

143
 \coffin_ht:N \coffin_ht:N hcoffin i
\coffin_ht:c
Calculates the height (above the baseline) of the hcoffini in a form suitable for use in a
hdimension expressioni.

\coffin_wd:N \coffin_wd:N hcoffin i

\coffin_wd:c
Calculates the width of the hcoffini in a form suitable for use in a hdimension expressioni.

5 Coffin diagnostics

\coffin_display_handles:Nn \coffin_display_handles:Nn hcoffin i {hcolor i}

\coffin_display_handles:cn
This function first calculates the intersections between all of the hpolesi of the hcoffini to
Updated: 2011-09-02 give a set of hhandlesi. It then prints the hcoffini at the current location in the source,
with the position of the hhandlesi marked on the coffin. The hhandlesi will be labelled
as part of this process: the locations of the hhandlesi and the labels are both printed in
the hcolori specified.

\coffin_mark_handle:Nnnn \coffin_mark_handle:Nnnn hcoffin i {hpole1 i} {hpole2 i} {hcolor i}

\coffin_mark_handle:cnnn
This function first calculates the hhandlei for the hcoffini as defined by the intersection
Updated: 2011-09-02 of hpole1 i and hpole2 i. It then marks the position of the hhandlei on the hcoffini. The
hhandlei will be labelled as part of this process: the location of the hhandlei and the
label are both printed in the hcolori specified.

\coffin_show_structure:N \coffin_show_structure:N hcoffin i

\coffin_show_structure:c
This function shows the structural information about the hcoffini in the terminal. The
Updated: 2012-09-09 width, height and depth of the typeset material are given, along with the location of all
of the poles of the coffin.
Notice that the poles of a coffin are defined by four values: the x and y co-ordinates
of a point that the pole passes through and the x- and y-components of a vector denoting
the direction of the pole. It is the ratio between the later, rather than the absolute values,
which determines the direction of the pole.

5.1 Constants and variables

\c_empty_coffin A permanently empty coffin.

\l_tmpa_coffin Scratch coffins for local assignment. These are never used by the kernel code, and so
\l_tmpb_coffin are safe for use with any LATEX3-defined function. However, they may be overwritten by
New: 2012-06-19 other non-kernel code and so should only be used for short-term storage.

144
 Part XVIII
The l3color package
Color support
This module provides support for color in LATEX3. At present, the material here is mainly
intended to support a small number of low-level requirements in other l3kernel modules.

1 Color in boxes
Controlling the color of text in boxes requires a small number of control functions, so
that the boxed material uses the color at the point where it is set, rather than where it
is used.

\color_group_begin: \color_group_begin:
\color_group_end: ...
\color_group_end:
New: 2011-09-03
Creates a color group: one used to “trap” color settings.

\color_ensure_current: \color_ensure_current:
New: 2011-09-03 Ensures that material inside a box will use the foreground color at the point where the
box is set, rather than that in force when the box is used. This function should usually
be used within a \color_group_begin: . . . \color_group_end: group.

145
 Part XIX
The l3msg package
Messages
Messages need to be passed to the user by modules, either when errors occur or to indicate
how the code is proceeding. The l3msg module provides a consistent method for doing
this (as opposed to writing directly to the terminal or log).
The system used by l3msg to create messages divides the process into two distinct
parts. Named messages are created in the first part of the process; at this stage, no
decision is made about the type of output that the message will produce. The second
part of the process is actually producing a message. At this stage a choice of message
class has to be made, for example error, warning or info.
By separating out the creation and use of messages, several benefits are available.
First, the messages can be altered later without needing details of where they are used
in the code. This makes it possible to alter the language used, the detail level and so
on. Secondly, the output which results from a given message can be altered. This can be
done on a message class, module or message name basis. In this way, message behaviour
can be altered and messages can be entirely suppressed.

1 Creating new messages

All messages have to be created before they can be used. The text of messages will
automatically by wrapped to the length available in the console. As a result, formatting
is only needed where it will help to show meaning. In particular, \\ may be used to force
a new line and \␣ forces an explicit space. Additionally, \{, \#, \}, \% and \~ can be
used to produce the corresponding character.
Messages may be subdivided by one level using the / character. This is used within
the message filtering system to allow for example the LATEX kernel messages to belong to
the module LaTeX while still being filterable at a more granular level. Thus for example
\msg_new:nnnn { mymodule } { submodule / message } ...

will allow only those messages from the submodule to be filtered out.

\msg_new:nnnn \msg_new:nnnn {hmodule i} {hmessage i} {htext i} {hmore text i}

\msg_new:nnn
Creates a hmessagei for a given hmodulei. The message will be defined to first give htexti
Updated: 2011-08-16 and then hmore texti if the user requests it. If no hmore texti is available then a standard
text is given instead. Within htexti and hmore texti four parameters (#1 to #4) can be
used: these will be supplied at the time the message is used. An error will be raised if
the hmessagei already exists.

146
 \msg_set:nnnn \msg_set:nnnn {hmodule i} {hmessage i} {htext i} {hmore text i}
\msg_set:nnn
Sets up the text for a hmessagei for a given hmodulei. The message will be defined to
\msg_gset:nnnn
\msg_gset:nnn first give htexti and then hmore texti if the user requests it. If no hmore texti is available
then a standard text is given instead. Within htexti and hmore texti four parameters (#1
to #4) can be used: these will be supplied at the time the message is used.

\msg_if_exist_p:nn ? \msg_if_exist_p:nn {hmodule i} {hmessage i}

\msg_if_exist:nnTF ? \msg_if_exist:nnTF {hmodule i} {hmessage i} {htrue code i} {hfalse code i}
New: 2012-03-03 Tests whether the hmessagei for the hmodulei is currently defined.

2 Contextual information for messages

\msg_line_context: I \msg_line_context:
Prints the current line number when a message is given, and thus suitable for giving
context to messages. The number itself is proceeded by the text on line.

\msg_line_number: ? \msg_line_number:
Prints the current line number when a message is given.

\msg_fatal_text:n ? \msg_fatal_text:n {hmodule i}

Produces the standard text
Fatal hmodule i error
This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

\msg_critical_text:n ? \msg_critical_text:n {hmodule i}

Produces the standard text
Critical hmodule i error

This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

\msg_error_text:n ? \msg_error_text:n {hmodule i}

Produces the standard text

hmodule i error
This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

147
\msg_warning_text:n ? \msg_warning_text:n {hmodule i}
Produces the standard text
hmodule i warning
This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

\msg_info_text:n ? \msg_info_text:n {hmodule i}

Produces the standard text:
hmodule i info

This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

\msg_see_documentation_text:n ? \msg_see_documentation_text:n {hmodule i}

Produces the standard text

See the hmodule i documentation for further information.

This function can be redefined to alter the language in which the message is given, using
#1 as the name of the hmodulei to be included.

3 Issuing messages
Messages behave differently depending on the message class. In all cases, the message
may be issued supplying 0 to 4 arguments. If the number of arguments supplied here does
not match the number in the definition of the message, extra arguments will be ignored,
or empty arguments added (of course the sense of the message may be impaired). The
four arguments will be converted to strings before being added to the message text: the
x-type variants should be used to expand material.

\msg_fatal:nnnnnn \msg_fatal:nnnnnn {hmodule i} {hmessage i} {harg one i}

\msg_fatal:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei error hmessagei, passing harg onei to harg fouri to the text-creating
functions. After issuing a fatal error the TEX run will halt.

148
\msg_critical:nnnnnn \msg_critical:nnnnnn {hmodule i} {hmessage i} {harg
\msg_critical:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) one i} {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei error hmessagei, passing harg onei to harg fouri to the text-creating
functions. After issuing a critical error, TEX will stop reading the current input file. This
may halt the TEX run (if the current file is the main file) or may abort reading a sub-file.

TEXhackers note: The TEX \endinput primitive is used to exit the file. In particular,
the rest of the current line remains in the input stream.

\msg_error:nnnnnn \msg_error:nnnnnn {hmodule i} {hmessage i} {harg one i}

\msg_error:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei error hmessagei, passing harg onei to harg fouri to the text-creating
functions. The error will interrupt processing and issue the text at the terminal. After
user input, the run will continue.

\msg_warning:nnnnnn \msg_warning:nnxxxx {hmodule i} {hmessage i} {harg

\msg_warning:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) one i} {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei warning hmessagei, passing harg onei to harg fouri to the text-creating
functions. The warning text will be added to the log file and the terminal, but the TEX
run will not be interrupted.

\msg_info:nnnnnn \msg_info:nnnnnn {hmodule i} {hmessage i} {harg one i}

\msg_info:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei information hmessagei, passing harg onei to harg fouri to the text-creating
functions. The information text will be added to the log file.

\msg_log:nnnnnn \msg_log:nnnnnn {hmodule i} {hmessage i} {harg one i} {harg

\msg_log:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) two i} {harg three i} {harg four i}
Updated: 2012-08-11

Issues hmodulei information hmessagei, passing harg onei to harg fouri to the text-creating
functions. The information text will be added to the log file: the output is briefer than
\msg_info:nnnnnn.

149
 \msg_none:nnnnnn \msg_none:nnnnnn {hmodule i} {hmessage i} {harg one i}
\msg_none:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {harg two i} {harg three i} {harg four i}
Updated: 2012-08-11

Does nothing: used as a message class to prevent any output at all (see the discussion of
message redirection).

4 Redirecting messages
Each message has a “name”, which can be used to alter the behaviour of the message
when it is given. Thus we might have
\msg_new:nnnn { module } { my-message } { Some~text } { Some~more~text }
to define a message, with

\msg_error:nn { module } { my-message }

when it is used. With no filtering, this will raise an error. However, we could alter the
behaviour with
\msg_redirect_class:nn { error } { warning }

to turn all errors into warnings, or with

\msg_redirect_module:nnn { module } { error } { warning }
to alter only messages from that module, or even

\msg_redirect_name:nnn { module } { my-message } { warning }

to target just one message. Redirection applies first to individual messages, then to
messages from one module and finally to messages of one class. Thus it is possible to
select out an individual message for special treatment even if the entire class is already
redirected.
Multiple redirections are possible. Redirections can be cancelled by providing an
empty argument for the target class. Redirection to a missing class will raise errors
immediately. Infinite loops are prevented by eliminating the redirection starting from
the target of the redirection that caused the loop to appear. Namely, if redirections are
requested as A → B, B → C and C → A in this order, then the A → B redirection is
cancelled.

\msg_redirect_class:nn \msg_redirect_class:nn {hclass one i} {hclass two i}

Updated: 2012-04-27 Changes the behaviour of messages of hclass onei so that they are processed using the
code for those of hclass twoi.

150
\msg_redirect_module:nnn \msg_redirect_module:nnn {hmodule i} {hclass one i} {hclass two i}
Updated: 2012-04-27 Redirects message of hclass onei for hmodulei to act as though they were from hclass
twoi. Messages of hclass onei from sources other than hmodulei are not affected by this
redirection. This function can be used to make some messages “silent” by default. For
example, all of the warning messages of hmodulei could be turned off with:
\msg_redirect_module:nnn { module } { warning } { none }

\msg_redirect_name:nnn \msg_redirect_name:nnn {hmodule i} {hmessage i} {hclass i}

Updated: 2012-04-27 Redirects a specific hmessagei from a specific hmodulei to act as a member of hclassi of
messages. No further redirection is performed. This function can be used to make a
selected message “silent” without changing global parameters:
\msg_redirect_name:nnn { module } { annoying-message } { none }

5 Low-level message functions

The lower-level message functions should usually be accessed from the higher-level system.
However, there are occasions where direct access to these functions is desirable.

\msg_interrupt:nnn \msg_interrupt:nnn {hfirst line i} {htext i} {hextra text i}

New: 2012-06-28 Interrupts the TEX run, issuing a formatted message comprising hfirst linei and htexti
laid out in the format

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! <first line>
!
! <text>
!...............................................
where the htexti will be wrapped to fit within the current line length. The user may then
request more information, at which stage the hextra texti will be shown in the terminal
in the format
|’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’
| <extra text>
|...............................................
where the hextra texti will be wrapped within the current line length. Wrapping of both
htexti and hmore texti takes place using \iow_wrap:nnnN; the documentation for the
latter should be consulted for full details.

151
 \msg_log:n \msg_log:n {htext i}
New: 2012-06-28 Writes to the log file with the htexti laid out in the format
.................................................
. <text>
.................................................

where the htexti will be wrapped to fit within the current line length. Wrapping takes
place using \iow_wrap:nnnN; the documentation for the latter should be consulted for
full details.

\msg_term:n \msg_term:n {htext i}

New: 2012-06-28 Writes to the terminal and log file with the htexti laid out in the format
*************************************************
* <text>
*************************************************
where the htexti will be wrapped to fit within the current line length. Wrapping takes
place using \iow_wrap:nnnN; the documentation for the latter should be consulted for
full details.

6 Kernel-specific functions
Messages from LATEX3 itself are handled by the general message system, but have their
own functions. This allows some text to be pre-defined, and also ensures that serious
errors can be handled properly.

\__msg_kernel_new:nnnn \__msg_kernel_new:nnnn {hmodule i} {hmessage i} {htext i} {hmore text i}

\__msg_kernel_new:nnn
Creates a kernel hmessagei for a given hmodulei. The message will be defined to first give
Updated: 2011-08-16 htexti and then hmore texti if the user requests it. If no hmore texti is available then a
standard text is given instead. Within htexti and hmore texti four parameters (#1 to #4)
can be used: these will be supplied and expanded at the time the message is used. An
error will be raised if the hmessagei already exists.

\__msg_kernel_set:nnnn \__msg_kernel_set:nnnn {hmodule i} {hmessage i} {htext i} {hmore text i}

\__msg_kernel_set:nnn
Sets up the text for a kernel hmessagei for a given hmodulei. The message will be defined
to first give htexti and then hmore texti if the user requests it. If no hmore texti is available
then a standard text is given instead. Within htexti and hmore texti four parameters (#1
to #4) can be used: these will be supplied and expanded at the time the message is used.

152
\__msg_kernel_fatal:nnnnnn \__msg_kernel_fatal:nnnnnn {hmodule i}
\__msg_kernel_fatal:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {hmessage i} {harg one i} {harg two i} {harg
three i} {harg four i}
Updated: 2012-08-11

Issues kernel hmodulei error hmessagei, passing harg onei to harg fouri to the text-creating
functions. After issuing a fatal error the TEX run will halt. Cannot be redirected.

\__msg_kernel_error:nnnnnn \__msg_kernel_error:nnnnnn {hmodule i}

\__msg_kernel_error:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {hmessage i} {harg one i} {harg two i} {harg
three i} {harg four i}
Updated: 2012-08-11

Issues kernel hmodulei error hmessagei, passing harg onei to harg fouri to the text-creating
functions. The error will stop processing and issue the text at the terminal. After user
input, the run will continue. Cannot be redirected.

\__msg_kernel_warning:nnnnnn \__msg_kernel_warning:nnnnnn {hmodule i}

\__msg_kernel_warning:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {hmessage i} {harg one i} {harg two i} {harg
three i} {harg four i}
Updated: 2012-08-11

Issues kernel hmodulei warning hmessagei, passing harg onei to harg fouri to the text-
creating functions. The warning text will be added to the log file, but the TEX run will
not be interrupted.

\__msg_kernel_info:nnnnnn \__msg_kernel_info:nnnnnn {hmodule i}

\__msg_kernel_info:(nnnnn|nnnn|nnn|nn|nnxxxx|nnxxx|nnxx|nnx) {hmessage i} {harg one i} {harg two i} {harg
three i} {harg four i}
Updated: 2012-08-11

Issues kernel hmodulei information hmessagei, passing harg onei to harg fouri to the
text-creating functions. The information text will be added to the log file.

7 Expandable errors
In a few places, the LATEX3 kernel needs to produce errors in an expansion only context.
This must be handled internally very differently from normal error messages, as none of
the tools to print to the terminal or the log file are expandable. However, the interface is
similar, with the important caveat that the message text and arguments are not expanded,
and messages should be very short.

\__msg_kernel_expandable_error:nnnnnn ? \__msg_kernel_expandable_error:nnnnnn {hmodule i}

\__msg_kernel_expandable_error:(nnnnn|nnnn|nnn|nn) ? {hmessage i} {harg one i} {harg two i} {harg three i}
{harg four i}
New: 2011-11-23

Issues an error, passing harg onei to harg fouri to the text-creating functions. The
resulting string must be shorter than a line, otherwise it will be cropped.

153
 \__msg_expandable_error:n ? \__msg_expandable_error:n {herror message i}
New: 2011-08-11
Updated: 2011-08-13

Issues an “Undefined error” message from TEX itself, and prints the herror messagei.
The herror messagei must be short: it is cropped at the end of one line.

TEXhackers note: This function expands to an empty token list after two steps. Tokens
inserted in response to TEX’s prompt are read with the current category code setting, and
inserted just after the place where the error message was issued.

8 Internal l3msg functions

The following functions are used in several kernel modules.

\__msg_term:nnnnnn \__msg_term:nnnnnn {hmodule i} {hmessage i} {harg one i} {harg two i} {harg

\__msg_term:(nnnnnV|nnnnn|nnn|nn) three i} {harg four i}

Prints the hmessagei from hmodulei in the terminal without formatting. Used in messages
which print complex variable contents completely.

\__msg_show_variable:Nnn \__msg_show_variable:Nnn hvariable i {htype i} {hformatted content i}

Updated: 2012-09-09 Displays the hformatted contenti of the hvariablei of htypei in the terminal. The
hformatted contenti will be processed as the first argument in a call to \iow_wrap:nnnN,
hence \\, \␣ and other formatting sequences can be used. Once expanded and processed,
the hformatted contenti must either be empty or contain >; everything until the first >
will be removed.

\__msg_show_variable:n \__msg_show_variable:n {hformatted text i}

Updated: 2012-09-09 Shows the hformatted texti on the terminal. After expansion, unless it is empty, the
hformatted texti must contain >, and the part of hformatted texti before the first > is
removed. Failure to do so causes low-level TEX errors.

\__msg_show_item:n \__msg_show_item:n hitem i

\__msg_show_item:nn \__msg_show_item:nn hitem-key i hitem-value i
\__msg_show_item_unbraced:nn
Updated: 2012-09-09

Auxiliary functions used within the argument of \__msg_show_variable:Nnn to format

variable items correctly for display. The \__msg_show_item:n version is used for simple
lists, the \__msg_show_item:nn and \__msg_show_item_unbraced:nn versions for key–
value like data structures.

154
\c__msg_coding_error_text_tl

The text

This is a coding error.

used by kernel functions when erroneous programming input is encountered.

155
Part XX
The l3keys package
Key–value interfaces
The key–value method is a popular system for creating large numbers of settings for
controlling function or package behaviour. The system normally results in input of the
form
\MyModuleSetup{
key-one = value one,
key-two = value two
}
or
\MyModuleMacro[
key-one = value one,
key-two = value two
]{argument}
for the user.
The high level functions here are intended as a method to create key–value controls.
Keys are themselves created using a key–value interface, minimising the number of func-
tions and arguments required. Each key is created by setting one or more properties of
the key:
\keys_define:nn { mymodule }
{
key-one .code:n = code including parameter #1,
key-two .tl_set:N = \l_mymodule_store_tl
}
These values can then be set as with other key–value approaches:
\keys_set:nn { mymodule }
{
key-one = value one,
key-two = value two
}
At a document level, \keys_set:nn will be used within a document function, for
example
\DeclareDocumentCommand \MyModuleSetup { m }
{ \keys_set:nn { mymodule } { #1 } }
\DeclareDocumentCommand \MyModuleMacro { o m }
{

156
 \group_begin:
\keys_set:nn { mymodule } { #1 }
% Main code for \MyModuleMacro
\group_end:
}

Key names may contain any tokens, as they are handled internally using \tl_to_-
str:n. As will be discussed in section 2, it is suggested that the character / is reserved
for sub-division of keys into logical groups. Functions and variables are not expanded
when creating key names, and so
\tl_set:Nn \l_mymodule_tmp_tl { key }
\keys_define:nn { mymodule }
{
\l_mymodule_tmp_tl .code:n = code
}
will create a key called \l_mymodule_tmp_tl, and not one called key.

1 Creating keys

\keys_define:nn \keys_define:nn {hmodule i} {hkeyval list i}

Parses the hkeyval listi and defines the keys listed there for hmodulei. The hmodulei
name should be a text value, but there are no restrictions on the nature of the text. In
practice the hmodulei should be chosen to be unique to the module in question (unless
deliberately adding keys to an existing module).
The hkeyval listi should consist of one or more key names along with an associated
key property. The properties of a key determine how it acts. The individual properties
are described in the following text; a typical use of \keys_define:nn might read

\keys_define:nn { mymodule }
{
keyname .code:n = Some~code~using~#1,
keyname .value_required:
}

where the properties of the key begin from the . after the key name.
The various properties available take either no arguments at all, or require one
or more arguments. This is indicated in the name of the property using an argument
specification. In the following discussion, each property is illustrated attached to an
arbitrary hkeyi, which when used may be supplied with a hvaluei. All key definitions are
local.

157
 .bool_set:N hkey i .bool_set:N = hboolean i
.bool_set:c
Defines hkeyi to set hbooleani to hvaluei (which must be either true or false). If the
.bool_gset:N
.bool_gset:c variable does not exist, it will be created globally at the point that the key is set up.

Updated: 2013-07-08

.bool_set_inverse:N hkey i .bool_set_inverse:N = hboolean i

.bool_set_inverse:c
Defines hkeyi to set hbooleani to the logical inverse of hvaluei (which must be either true
.bool_gset_inverse:N
.bool_gset_inverse:c or false). If the hbooleani does not exist, it will be created globally at the point that
the key is set up.
New: 2011-08-28
Updated: 2013-07-08

.choice: hkey i .choice:

Sets hkeyi to act as a choice key. Each valid choice for hkeyi must then be created, as
discussed in section 3.

.choices:nn hkey i .choices:nn = {hchoices i} {hcode i}

.choices:Vn
Sets hkeyi to act as a choice key, and defines a series hchoicesi which are implemented
.choices:on
.choices:xn using the hcodei. Inside hcodei, \l_keys_choice_tl will be the name of the choice
made, and \l_keys_choice_int will be the position of the choice in the list of hchoicesi
New: 2011-08-21
(indexed from 1). Choices are discussed in detail in section 3.
Updated: 2013-07-10

.clist_set:N hkey i .clist_set:N = hcomma list variable i

.clist_set:c
Defines hkeyi to set hcomma list variablei to hvaluei. Spaces around commas and empty
.clist_gset:N
.clist_gset:c items will be stripped. If the variable does not exist, it will be created globally at the
point that the key is set up.
New: 2011-09-11

.code:n hkey i .code:n = {hcode i}

Updated: 2013-07-10 Stores the hcodei for execution when hkeyi is used. The The hcodei can include one
parameter (#1), which will be the hvaluei given for the hkeyi. The x-type variant will
expand hcodei at the point where the hkeyi is created.

158
.default:n hkey i .default:n = {hdefault i}
.default:V
Creates a hdefaulti value for hkeyi, which is used if no value is given. This will be used
.default:o
.default:x if only the key name is given, but not if a blank hvaluei is given:

Updated: 2013-07-09 \keys_define:nn { mymodule }

{
key .code:n = Hello~#1,
key .default:n = World
}
\keys_set:nn { mymodule }
{
key = Fred, % Prints ’Hello Fred’
key, % Prints ’Hello World’
key = , % Prints ’Hello ’
}

.dim_set:N hkey i .dim_set:N = hdimension i

.dim_set:c
Defines hkeyi to set hdimensioni to hvaluei (which must a dimension expression). If the
.dim_gset:N
.dim_gset:c variable does not exist, it will be created globally at the point that the key is set up.

.fp_set:N hkey i .fp_set:N = hfloating point i

.fp_set:c
Defines hkeyi to set hfloating pointi to hvaluei (which must a floating point expression).
.fp_gset:N
.fp_gset:c If the variable does not exist, it will be created globally at the point that the key is set
up.

.groups:n hkey i .groups:n = {hgroups i}

New: 2013-07-14 Defines hkeyi as belonging to the hgroupsi declared. Groups provide a “secondary axis”
for selectively setting keys, and are described in Section 6.

.initial:n hkey i .initial:n = {hvalue i}

.initial:V
Initialises the hkeyi with the hvaluei, equivalent to
.initial:o
.initial:x \keys_set:nn {hmodulei} { hkeyi = hvaluei }
Updated: 2013-07-09

.int_set:N hkey i .int_set:N = hinteger i

.int_set:c
Defines hkeyi to set hintegeri to hvaluei (which must be an integer expression). If the
.int_gset:N
.int_gset:c variable does not exist, it will be created globally at the point that the key is set up.

159
 .meta:n hkey i .meta:n = {hkeyval list i}
Updated: 2013-07-10 Makes hkeyi a meta-key, which will set hkeyval listi in one go. If hkeyi is given with a
value at the time the key is used, then the value will be passed through to the subsidiary
hkeysi for processing (as #1).

.meta:nn hkey i .meta:nn = {hpath i} {hkeyval list i}

New: 2013-07-10 Makes hkeyi a meta-key, which will set hkeyval listi in one go using the hpathi in place of
the current one. If hkeyi is given with a value at the time the key is used, then the value
will be passed through to the subsidiary hkeysi for processing (as #1).

.multichoice: hkey i .multichoice:

New: 2011-08-21 Sets hkeyi to act as a multiple choice key. Each valid choice for hkeyi must then be
created, as discussed in section 3.

.multichoices:nn hkey i .multichoices:nn {hchoices i} {hcode i}

.multichoices:Vn
Sets hkeyi to act as a multiple choice key, and defines a series hchoicesi which are im-
.multichoices:on
.multichoices:xn plemented using the hcodei. Inside hcodei, \l_keys_choice_tl will be the name of the
choice made, and \l_keys_choice_int will be the position of the choice in the list of
New: 2011-08-21
hchoicesi (indexed from 1). Choices are discussed in detail in section 3.
Updated: 2013-07-10

.skip_set:N hkey i .skip_set:N = hskip i

.skip_set:c
Defines hkeyi to set hskipi to hvaluei (which must be a skip expression). If the variable
.skip_gset:N
.skip_gset:c does not exist, it will be created globally at the point that the key is set up.

.tl_set:N hkey i .tl_set:N = htoken list variable i

.tl_set:c
Defines hkeyi to set htoken list variablei to hvaluei. If the variable does not exist, it will
.tl_gset:N
.tl_gset:c be created globally at the point that the key is set up.

.tl_set_x:N hkey i .tl_set_x:N = htoken list variable i

.tl_set_x:c
Defines hkeyi to set htoken list variablei to hvaluei, which will be subjected to an x-
.tl_gset_x:N
.tl_gset_x:c type expansion (i.e. using \tl_set:Nx). If the variable does not exist, it will be created
globally at the point that the key is set up.

.value_forbidden: hkey i .value_forbidden:

Specifies that hkeyi cannot receive a hvaluei when used. If a hvaluei is given then an error
will be issued.

.value_required: hkey i .value_required:

Specifies that hkeyi must receive a hvaluei when used. If a hvaluei is not given then an
error will be issued.

160
2 Sub-dividing keys
When creating large numbers of keys, it may be desirable to divide them into several
sub-groups for a given module. This can be achieved either by adding a sub-division to
the module name:
\keys_define:nn { module / subgroup }
{ key .code:n = code }
or to the key name:
\keys_define:nn { mymodule }
{ subgroup / key .code:n = code }
As illustrated, the best choice of token for sub-dividing keys in this way is /. This is
because of the method that is used to represent keys internally. Both of the above code
fragments set the same key, which has full name module/subgroup/key.
As will be illustrated in the next section, this subdivision is particularly relevant to
making multiple choices.

3 Choice and multiple choice keys

The l3keys system supports two types of choice key, in which a series of pre-defined input
values are linked to varying implementations. Choice keys are usually created so that the
various values are mutually-exclusive: only one can apply at any one time. “Multiple”
choice keys are also supported: these allow a selection of values to be chosen at the same
time.
Mutually-exclusive choices are created by setting the .choice: property:
\keys_define:nn { mymodule }
{ key .choice: }
For keys which are set up as choices, the valid choices are generated by creating sub-keys
of the choice key. This can be carried out in two ways.
In many cases, choices execute similar code which is dependant only on the name of
the choice or the position of the choice in the list of all possibilities. Here, the keys can
share the same code, and can be rapidly created using the .choices:nn property.
\keys_define:nn { mymodule }
{
key .choices:nn =
{ choice-a, choice-b, choice-c }
{
You~gave~choice~’\tl_use:N \l_keys_choice_tl’,~
which~is~in~position~\int_use:N \l_keys_choice_int \c_space_tl
in~the~list.
}
}

161
 The index \l_keys_choice_int in the list of choices starts at 1.

\l_keys_choice_int Inside the code block for a choice generated using .choices:nn, the variables \l_keys_-
\l_keys_choice_tl choice_tl and \l_keys_choice_int are available to indicate the name of the current
choice, and its position in the comma list. The position is indexed from 1. Note that,
as with standard key code generated using .code:n, the value passed to the key (i.e. the
choice name) is also available as #1.
On the other hand, it is sometimes useful to create choices which use entirely different
code from one another. This can be achieved by setting the .choice: property of a key,
then manually defining sub-keys.
\keys_define:nn { mymodule }
{
key .choice:,
key / choice-a .code:n = code-a,
key / choice-b .code:n = code-b,
key / choice-c .code:n = code-c,
}

It is possible to mix the two methods, but manually-created choices should not
use \l_keys_choice_tl or \l_keys_choice_int. These variables do not have defined
behaviour when used outside of code created using .choices:nn (i.e. anything might
happen).
It is possible to allow choice keys to take values which have not previously been
defined by adding code for the special unknown choice. The general behavior of the
unknown key is described in Section 5. A typical example in the case of a choice would
be to issue a custom error message:
\keys_define:nn { mymodule }
{
key .choice:,
key / choice-a .code:n = code-a,
key / choice-b .code:n = code-b,
key / choice-c .code:n = code-c,
key / unknown .code:n =
\msg_error:nnxxx { mymodule } { unknown-choice }
{ key } % Name of choice key
{ choice-a , choice-b , choice-c } % Valid choices
{ \exp_not:n {#1} } % Invalid choice given
%
%
}

Multiple choices are created in a very similar manner to mutually-exclusive choices,

using the properties .multichoice: and .multichoices:nn. As with mutually exclusive
choices, multiple choices are define as sub-keys. Thus both

162
 \keys_define:nn { mymodule }
{
key .multichoices:nn =
{ choice-a, choice-b, choice-c }
{
You~gave~choice~’\tl_use:N \l_keys_choice_tl’,~
which~is~in~position~
\int_use:N \l_keys_choice_int \c_space_tl
in~the~list.
}
}
and
\keys_define:nn { mymodule }
{
key .multichoice:,
key / choice-a .code:n = code-a,
key / choice-b .code:n = code-b,
key / choice-c .code:n = code-c,
}
are valid.
When a multiple choice key is set
\keys_set:nn { mymodule }
{
key = { a , b , c } % ’key’ defined as a multiple choice
}
each choice is applied in turn, equivalent to a clist mapping or to applying each value
individually:
\keys_set:nn { mymodule }
{
key = a ,
key = b ,
key = c ,
}
Thus each separate choice will have passed to it the \l_keys_choice_tl and \l_keys_-
choice_int in exactly the same way as described for .choices:nn.

4 Setting keys

\keys_set:nn \keys_set:nn {hmodule i} {hkeyval list i}

\keys_set:(nV|nv|no)
Parses the hkeyval listi, and sets those keys which are defined for hmodulei. The behaviour
on finding an unknown key can be set by defining a special unknown key: this will be
illustrated later.

163
 \l_keys_key_tl For each key processed, information of the full path of the key, the name of the key and
\l_keys_path_tl the value of the key is available within three token list variables. These may be used
\l_keys_value_tl within the code of the key.
The value is everything after the =, which may be empty if no value was given. This
is stored in \l_keys_value_tl, and is not processed in any way by \keys_set:nn.
The path of the key is a “full” description of the key, and is unique for each key. It
consists of the module and full key name, thus for example

\keys_set:nn { mymodule } { key-a = some-value }

has path mymodule/key-a while
\keys_set:nn { mymodule } { subset / key-a = some-value }
has path mymodule/subset/key-a. This information is stored in \l_keys_path_tl, and
will have been processed by \tl_to_str:n.
The name of the key is the part of the path after the last /, and thus is not unique.
In the preceding examples, both keys have name key-a despite having different paths.
This information is stored in \l_keys_key_tl, and will have been processed by \tl_-
to_str:n.

5 Handling of unknown keys

If a key has not previously been defined (is unknown), \keys_set:nn will look for a special
unknown key for the same module, and if this is not defined raises an error indicating that
the key name was unknown. This mechanism can be used for example to issue custom
error texts.
\keys_define:nn { mymodule }
{
unknown .code:n =
You~tried~to~set~key~’\l_keys_key_tl’~to~’#1’.
}

\keys_set_known:nnN \keys_set_known:nnN {hmodule i} {hkeyval list i} htl i

\keys_set_known:(nVN|nvN|noN|nn|nV|nv|no)
New: 2011-08-23
Updated: 2014-04-27

In some cases, the desired behavior is to simply ignore unknown keys, collecting up
information on these for later processing. The \keys_set_known:nnN function parses
the hkeyval listi, and sets those keys which are defined for hmodulei. Any keys which are
unknown are not processed further by the parser. The key–value pairs for each unknown
key name will be stored in the htli in a comma-separated form (i.e. an edited version of
the hkeyval listi). The \keys_set_known:nn version skips this stage.
Use of \keys_set_known:nnN can be nested, with the correct residual hkeyval listi
returned at each stage.

164
 6 Selective key setting
In some cases it may be useful to be able to select only some keys for setting, even though
these keys have the same path. For example, with a set of keys defined using
\keys define:nn { mymodule }
{
key-one .code:n = { \my_func:n {#1} } ,
key-two .tl_set:N = \l_my_a_tl ,
key-three .tl_set:N = \l_my_b_tl ,
key-four .fp_set:N = \l_my_a_fp ,
}
the use of \keys_set:nn will attempt to set all four keys. However, in some contexts it
may only be sensible to set some keys, or to control the order of setting. To do this, keys
may be assigned to groups: arbitrary sets which are independent of the key tree. Thus
modifying the example to read
\keys define:nn { mymodule }
{
key-one .code:n = { \my_func:n {#1} } ,
key-one .groups:n = { first } ,
key-two .tl_set:N = \l_my_a_tl ,
key-two .groups:n = { first } ,
key-three .tl_set:N = \l_my_b_tl ,
key-three .groups:n = { second } ,
key-four .fp_set:N = \l_my_a_fp ,
}
will assign key-one and key-two to group first, key-three to group second, while
key-four is not assigned to a group.
Selective key setting may be achieved either by selecting one or more groups to be
made “active”, or by marking one or more groups to be ignored in key setting.

\keys_set_filter:nnnN \keys_set_filter:nnnN {hmodule i} {hgroups i} {hkeyval

\keys_set_filter:(nnVN|nnvN|nnoN|nnn|nnV|nnv|nno) list i} htl i
New: 2013-07-14
Updated: 2014-04-27

Actives key filtering in an “opt-out” sense: keys assigned to any of the hgroupsi specified
will be ignored. The hgroupsi are given as a comma-separated list. Unknown keys are
not assigned to any group and will thus always be set. The key–value pairs for each key
which is filtered out will be stored in the htli in a comma-separated form (i.e. an edited
version of the hkeyval listi). The \keys_set_filter:nnn version skips this stage.
Use of \keys_set_filter:nnnN can be nested, with the correct residual hkeyval listi
returned at each stage.

165
 \keys_set_groups:nnn \keys_set_groups:nnn {hmodule i} {hgroups i} {hkeyval list i}
\keys_set_groups:(nnV|nnv|nno)
New: 2013-07-14

Actives key filtering in an “opt-in” sense: only keys assigned to one or more of the hgroupsi
specified will be set. The hgroupsi are given as a comma-separated list. Unknown keys
are not assigned to any group and will thus never be set.

7 Utility functions for keys

\keys_if_exist_p:nn ? \keys_if_exist_p:nn {hmodule i} {hkey i}

\keys_if_exist:nnTF ? \keys_if_exist:nnTF {hmodule i} {hkey i} {htrue code i} {hfalse code i}
Tests if the hkeyi exists for hmodulei, i.e. if any code has been defined for hkeyi.

\keys_if_choice_exist_p:nnn ? \keys_if_choice_exist_p:nnn {hmodule i} {hkey i} {hchoice i}

\keys_if_choice_exist:nnnTF ? \keys_if_choice_exist:nnnTF {hmodule i} {hkey i} {hchoice i} {htrue code i}
{hfalse code i}
New: 2011-08-21

Tests if the hchoicei is defined for the hkeyi within the hmodulei, i.e. if any code has been
defined for hkeyi/hchoicei. The test is false if the hkeyi itself is not defined.

\keys_show:nn \keys_show:nn {hmodule i} {hkey i}

Shows the function which is used to actually implement a hkeyi for a hmodulei.

8 Low-level interface for parsing key–val lists

To re-cap from earlier, a key–value list is input of the form
KeyOne = ValueOne ,
KeyTwo = ValueTwo ,
KeyThree
where each key–value pair is separated by a comma from the rest of the list, and each
key–value pair does not necessarily contain an equals sign or a value! Processing this
type of input correctly requires a number of careful steps, to correctly account for braces,
spaces and the category codes of separators.
While the functions described earlier are used as a high-level interface for processing
such input, in special circumstances you may wish to use a lower-level approach. The
low-level parsing system converts a hkey–value listi into hkeysi and associated hvaluesi.
After the parsing phase is completed, the resulting keys and values (or keys alone) are
available for further processing. This processing is not carried out by the low-level parser
itself, and so the parser requires the names of two functions along with the key–value
list. One function is needed to process key–value pairs (it receives two arguments), and

166
 a second function is required for keys given without any value (it is called with a single
argument).
The parser does not double # tokens or expand any input. Active tokens = and ,
appearing at the outer level of braces are converted to category “other” (12) so that the
parser does not “miss” any due to category code changes. Spaces are removed from the
ends of the keys and values. Keys and values which are given in braces will have exactly
one set removed (after space trimming), thus
key = {value here},
and

key = value here,

are treated identically.

\keyval_parse:NNn \keyval_parse:NNn hfunction1 i hfunction2 i {hkey–value list i}

Updated: 2011-09-08 Parses the hkey–value listi into a series of hkeysi and associated hvaluesi, or keys alone
(if no hvaluei was given). hfunction1 i should take one argument, while hfunction2 i
should absorb two arguments. After \keyval_parse:NNn has parsed the hkey–value listi,
hfunction1 i will be used to process keys given with no value and hfunction2 i will be used
to process keys given with a value. The order of the hkeysi in the hkey–value listi will be
preserved. Thus
\keyval_parse:NNn \function:n \function:nn
{ key1 = value1 , key2 = value2, key3 = , key4 }

will be converted into an input stream

\function:nn { key1 } { value1 }
\function:nn { key2 } { value2 }
\function:nn { key3 } { }
\function:n { key4 }
Note that there is a difference between an empty value (an equals sign followed by noth-
ing) and a missing value (no equals sign at all). Spaces are trimmed from the ends of the
hkeyi and hvaluei, then one outer set of braces is removed from the hkeyi and hvaluei as
part of the processing.

167
 Part XXI
The l3file package
File and I/O operations
This module provides functions for working with external files. Some of these functions
apply to an entire file, and have prefix \file_..., while others are used to work with
files on a line by line basis and have prefix \ior_... (reading) or \iow_... (writing).
It is important to remember that when reading external files TEX will attempt to
locate them both the operating system path and entries in the TEX file database (most
TEX systems use such a database). Thus the “current path” for TEX is somewhat broader
than that for other programs.
For functions which expect a hfile namei argument, this argument may contain both
literal items and expandable content, which should on full expansion be the desired file
name. Any active characters (as declared in \l_char_active_seq) will not be expanded,
allowing the direct use of these in file names. File names will be quoted using " tokens
if they contain spaces: as a result, " tokens are not permitted in file names.

1 File operation functions

\g_file_current_name_tl Contains the name of the current LATEX file. This variable should not be modified: it
is intended for information only. It will be equal to \c_job_name_tl at the start of a
LATEX run and will be modified each time a file is read using \file_input:n.

\file_if_exist:nTF \file_if_exist:nTF {hfile name i} {htrue code i} {hfalse code i}

Updated: 2012-02-10 Searches for hfile namei using the current TEX search path and the additional paths
controlled by \file_path_include:n).

\file_add_path:nN \file_add_path:nN {hfile name i} htl var i

Updated: 2012-02-10 Searches for hfile namei in the path as detailed for \file_if_exist:nTF, and if found
sets the htl vari the fully-qualified name of the file, i.e. the path and file name. If the file
is not found then the htl vari will contain the marker \q_no_value.

\file_input:n \file_input:n {hfile name i}

Updated: 2012-02-17 Searches for hfile namei in the path as detailed for \file_if_exist:nTF, and if found
reads in the file as additional LATEX source. All files read are recorded for information
and the file name stack is updated by this function. An error will be raised if the file is
not found.

168
\file_path_include:n \file_path_include:n {hpath i}
Updated: 2012-07-04 Adds hpathi to the list of those used to search when reading files. The assignment is local.
The hpathi is processed in the same way as a hfile namei, i.e., with x-type expansion
except active characters. Spaces are not allowed in the hpathi.

\file_path_remove:n \file_path_remove:n {hpath i}

Updated: 2012-07-04 Removes hpathi from the list of those used to search when reading files. The assignment
is local. The hpathi is processed in the same way as a hfile namei, i.e., with x-type
expansion except active characters. Spaces are not allowed in the hpathi.

\file_list: \file_list:
This function will list all files loaded using \file_input:n in the log file.

1.1 Input–output stream management

As TEX is limited to 16 input streams and 16 output streams, direct use of the streams
by the programmer is not supported in LATEX3. Instead, an internal pool of streams is
maintained, and these are allocated and deallocated as needed by other modules. As a
result, the programmer should close streams when they are no longer needed, to release
them for other processes.
Note that I/O operations are global: streams should all be declared with global
names and treated accordingly.

\ior_new:N \ior_new:N hstream i

\ior_new:c \iow_new:N hstream i
\iow_new:N Globally reserves the name of the hstreami, either for reading or for writing as appropri-
\iow_new:c
ate. The hstreami is not opened until the appropriate \..._open:Nn function is used.
New: 2011-09-26 Attempting to use a hstreami which has not been opened is an error, and the hstreami
Updated: 2011-12-27 will behave as the corresponding \c_term_....

\ior_open:Nn \ior_open:Nn hstream i {hfile name i}

\ior_open:cn
Opens hfile namei for reading using hstreami as the control sequence for file access. If the
Updated: 2012-02-10 hstreami was already open it is closed before the new operation begins. The hstreami is
available for access immediately and will remain allocated to hfile namei until a \ior_-
close:N instruction is given or the TEX run ends.

\ior_open:NnTF \ior_open:NnTF hstream i {hfile name i} {htrue code i} {hfalse code i}

\ior_open:cnTF
Opens hfile namei for reading using hstreami as the control sequence for file access. If the
New: 2013-01-12 hstreami was already open it is closed before the new operation begins. The hstreami is
available for access immediately and will remain allocated to hfile namei until a \ior_-
close:N instruction is given or the TEX run ends. The htrue codei is then inserted into
the input stream. If the file is not found, no error is raised and the hfalse codei is inserted
into the input stream.

169
 \iow_open:Nn \iow_open:Nn hstream i {hfile name i}
\iow_open:cn
Opens hfile namei for writing using hstreami as the control sequence for file access. If the
Updated: 2012-02-09 hstreami was already open it is closed before the new operation begins. The hstreami is
available for access immediately and will remain allocated to hfile namei until a \iow_-
close:N instruction is given or the TEX run ends. Opening a file for writing will clear
any existing content in the file (i.e. writing is not additive).

\ior_close:N \ior_close:N hstream i

\ior_close:c \iow_close:N hstream i
\iow_close:N Closes the hstreami. Streams should always be closed when they are finished with as this
\iow_close:c
ensures that they remain available to other programmers.
Updated: 2012-07-31

\ior_list_streams: \ior_list_streams:
\iow_list_streams: \iow_list_streams:
Updated: 2012-09-09 Displays a list of the file names associated with each open stream: intended for tracking
down problems.

1.2 Reading from files

\ior_get:NN \ior_get:NN hstream i htoken list variable i

New: 2012-06-24 Function that reads one or more lines (until an equal number of left and right braces are
found) from the input hstreami and stores the result locally in the htoken listi variable.
If the hstreami is not open, input is requested from the terminal. The material read from
the hstreami will be tokenized by TEX according to the category codes in force when
the function is used. Note that any blank lines will be converted to the token \par.
Therefore, if skipping blank lines is requires a test such as
\ior_get:NN \l_my_stream \l_tmpa_tl
\tl_set:Nn \l_tmpb_tl { \par }
\tl_if_eq:NNF \l_tmpa_tl \l_tmpb_tl
...
may be used. Also notice that if multiple lines are read to match braces then the resulting
token list will contain \par tokens. As normal TEX tokenization is in force, any lines
which do not end in a comment character (usually %) will have the line ending converted
to a space, so for example input

a b c
will result in a token list a b c .

TEXhackers note: This protected macro expands to the TEX primitive \read along with
the to keyword.

170
 \ior_get_str:NN \ior_get_str:NN hstream i htoken list variable i
New: 2012-06-24 Function that reads one line from the input hstreami and stores the result locally in the
Updated: 2012-07-31 htoken listi variable. If the hstreami is not open, input is requested from the terminal.
The material is read from the hstreami as a series of tokens with category code 12 (other),
with the exception of space characters which are given category code 10 (space). Multiple
whitespace characters are retained by this process. It will always only read one line and
any blank lines in the input will result in the htoken list variablei being empty. Unlike
\ior_get:NN, line ends do not receive any special treatment. Thus input
a b c
will result in a token list a b c with the letters a, b, and c having category code 12.

TEXhackers note: This protected macro is a wrapper around the ε-TEX primitive
\readline. However, the end-line character normally added by this primitive is not included in
the result of \ior_get_str:NN.

\ior_if_eof_p:N ? \ior_if_eof_p:N hstream i

\ior_if_eof:NTF ? \ior_if_eof:NTF hstream i {htrue code i} {hfalse code i}
Updated: 2012-02-10 Tests if the end of a hstreami has been reached during a reading operation. The test will
also return a true value if the hstreami is not open.

2 Writing to files

\iow_now:Nn \iow_now:Nn hstream i {htokens i}

\iow_now:(Nx|cn|cx)
This functions writes htokensi to the specified hstreami immediately (i.e. the write oper-
Updated: 2012-06-05 ation is called on expansion of \iow_now:Nn).

\iow_log:n \iow_log:n {htokens i}

\iow_log:x
This function writes the given htokensi to the log (transcript) file immediately: it is a
dedicated version of \iow_now:Nn.

\iow_term:n \iow_term:n {htokens i}

\iow_term:x
This function writes the given htokensi to the terminal file immediately: it is a dedicated
version of \iow_now:Nn.

\iow_shipout:Nn \iow_shipout:Nn hstream i {htokens i}

\iow_shipout:(Nx|cn|cx)
This functions writes htokensi to the specified hstreami when the current page is finalised
(i.e. at shipout). The x-type variants expand the htokensi at the point where the function
is used but not when the resulting tokens are written to the hstreami (cf. \iow_shipout_-
x:Nn).

171
\iow_shipout_x:Nn \iow_shipout_x:Nn hstream i {htokens i}
\iow_shipout_x:(Nx|cn|cx)
This functions writes htokensi to the specified hstreami when the current page is finalised
Updated: 2012-09-08 (i.e. at shipout). The htokensi are expanded at the time of writing in addition to any
expansion when the function is used. This makes these functions suitable for including
material finalised during the page building process (such as the page number integer).

TEXhackers note: This is a wrapper around the TEX primitive \write.

\iow_char:N ? \iow_char:N \hchar i

Inserts hchari into the output stream. Useful when trying to write difficult characters
such as %, {, }, etc. in messages, for example:
\iow_now:Nx \g_my_iow { \iow_char:N \{ text \iow_char:N \} }
The function has no effect if writing is taking place without expansion (e.g. in the second
argument of \iow_now:Nn).

\iow_newline: ? \iow_newline:
Function to add a new line within the htokensi written to a file. The function has no
effect if writing is taking place without expansion (e.g. in the second argument of \iow_-
now:Nn).

172
 2.1 Wrapping lines in output

\iow_wrap:nnnN \iow_wrap:nnnN {htext i} {hrun-on text i} {hset up i} hfunction i

New: 2012-06-28 This function will wrap the htexti to a fixed number of characters per line. At the start of
each line which is wrapped, the hrun-on texti will be inserted. The line character count
targeted will be the value of \l_iow_line_count_int minus the number of characters
in the hrun-on texti. The htexti and hrun-on texti are exhaustively expanded by the
function, with the following substitutions:
• \\ may be used to force a new line,
• \␣ may be used to represent a forced space (for example after a control sequence),

• \#, \%, \{, \}, \~ may be used to represent the corresponding character,
• \iow_indent:n may be used to indent a part of the message.
Additional functions may be added to the wrapping by using the hset upi, which is
executed before the wrapping takes place: this may include overriding the substitutions
listed.
Any expandable material in the htexti which is not to be expanded on wrapping
should be converted to a string using \token_to_str:N, \tl_to_str:n, \tl_to_str:N,
etc.
The result of the wrapping operation is passed as a braced argument to the
hfunctioni, which will typically be a wrapper around a write operation. The output
of \iow_wrap:nnnN (i.e. the argument passed to the hfunctioni) will consist of charac-
ters of category “other” (category code 12), with the exception of spaces which will have
category “space” (category code 10). This means that the output will not expand further
when written to a file.

TEXhackers note: Internally, \iow_wrap:nnnN carries out an x-type expansion on the

htexti to expand it. This is done in such a way that \exp_not:N or \exp_not:n could be used
to prevent expansion of material. However, this is less conceptually clear than conversion to a
string, which is therefore the supported method for handling expandable material in the htexti.

\iow_indent:n \iow_indent:n {htext i}

New: 2011-09-21 In the context of \iow_wrap:nnnN (for instance in messages), indents htexti by four
spaces. This function will not cause a line break, and only affects lines which start
within the scope of the htexti. In case the indented htexti should appear on separate lines
from the surrounding text, use \\ to force line breaks.

\l_iow_line_count_int The maximum number of characters in a line to be written by the \iow_wrap:nnnN

New: 2012-06-24 function. This value depends on the TEX system in use: the standard value is 78, which
is typically correct for unmodified TEXlive and MiKTEX systems.

173
\c_catcode_other_space_tl Token list containing one character with category code 12, (“other”), and character code
New: 2011-09-05 32 (space).

2.2 Constant input–output streams

\c_term_ior Constant input stream for reading from the terminal. Reading from this stream using
\ior_get:NN or similar will result in a prompt from TEX of the form

<tl>=

\c_log_iow Constant output streams for writing to the log and to the terminal (plus the log), respec-
\c_term_iow tively.

2.3 Primitive conditionals

\if_eof:w ? \if_eof:w hstream i

htrue code i
\else:
hfalse code i
\fi:
Tests if the hstreami returns “end of file”, which is true for non-existent files. The \else:
branch is optional.

TEXhackers note: This is the TEX primitive \ifeof.

2.4 Internal file functions and variables

\g__file_internal_ior Used to test for the existence of files when opening.

\l__file_internal_name_tl Used to return the full name of a file for internal use. This is set by \file_if_-
exist:n(TF) and \__file_if_exist:nT, and the value may then be used to load a
file directly provided no further operations intervene.

\__file_name_sanitize:nn \__file_name_sanitize:nn {hname i} {htokens i}

New: 2012-02-09 Exhaustively-expands the hnamei with the exception of any category hactivei (catcode 13)
tokens, which are not expanded. The list of hactivei tokens is taken from \l_char_-
active_seq. The hsanitized namei is then inserted (in braces) after the htokensi, which
should further process the file name. If any spaces are found in the name after expansion,
an error is raised.

174
 2.5 Internal input–output functions

\__ior_open:Nn \__ior_open:Nn hstream i {hfile name i}

\__ior_open:No
This function has identical syntax to the public version. However, is does not take
New: 2012-01-23 precautions against active characters in the hfile namei, and it does not attempt to add
a hpathi to the hfile namei: it is therefore intended to be used by higher-level functions
which have already fully expanded the hfile namei and which need to perform multiple
open or close operations. See for example the implementation of \file_add_path:nN,

175
 Part XXII
The l3fp package: floating points
A decimal floating point number is one which is stored as a significand and a separate
exponent. The module implements expandably a wide set of arithmetic, trigonometric,
and other operations on decimal floating point numbers, to be used within floating point
expressions. Floating point expressions support the following operations with their usual
precedence.
• Basic arithmetic:√addition x + y, subtraction x − y, multiplication x ∗ y, division
x/y, square root x, and parentheses.
• Comparison operators: x < y, x <= y, x >? y, x ! = y etc.
• Boolean logic: negation ! x, conjunction x && y, disjunction x || y, ternary operator
x ? y : z.
• Exponentials: exp x, ln x, xy .
• Trigonometry: sin x, cos x, tan x, cot x, sec x, csc x expecting their arguments in
radians, and sind x, cosd x, tand x, cotd x, secd x, cscd x expecting their arguments
in degrees.
• Inverse trigonometric functions: asin x, acos x, atan x, acot x, asec x, acsc x giving
a result in radians, and asind x, acosd x, atand x, acotd x, asecd x, acscd x giving a
result in degrees.
(not yet) Hyperbolic functions and their inverse functions: sinh x, cosh x, tanh x, coth x,
sech x, csch, and asinh x, acosh x, atanh x, acoth x, asech x, acsch x.
• Extrema: max(x, y, . . .), min(x, y, . . .), abs(x).
• Rounding functions: round(x, n) rounds to closest, trunc(x, n) rounds towards zero,
floor(x, n) rounds towards −∞, ceil(x, n) rounds towards +∞. And (not yet) mod-
ulo, and “quantize”.
• Constants: pi, deg (one degree in radians).
• Dimensions, automatically expressed in points, e.g., pc is 12.
• Automatic conversion (no need for \htype i_use:N) of integer, dimension, and skip
variables to floating points, expressing dimensions in points and ignoring the stretch
and shrink components of skips.
Floating point numbers can be given either explicitly (in a form such as 1.234e-34, or
-.0001), or as a stored floating point variable, which is automatically replaced by its
current value. See section 9.1 for a description of what a floating point is, section 9.2
for details about how an expression is parsed, and section 9.3 to know what the various
operations do. Some operations may raise exceptions (error messages), described in
section 7.
An example of use could be the following.

176
 \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
= \ExplSyntaxOn \fp_to_decimal:n {sin 3.5 /2 + 2e-3} $.
But in all fairness, this module is mostly meant as an underlying tool for higher-level
commands. For example, one could provide a function to typeset nicely the result of
floating point computations.
\usepackage{xparse, siunitx}
\ExplSyntaxOn
\NewDocumentCommand { \calcnum } { m }
{ \num { \fp_to_scientific:n {#1} } }
\ExplSyntaxOff
\calcnum { 2 pi * sin ( 2.3 ^ 5 ) }

1 Creating and initialising floating point variables

\fp_new:N \fp_new:N hfp var i

\fp_new:c
Creates a new hfp vari or raises an error if the name is already taken. The declaration is
Updated: 2012-05-08 global. The hfp vari will initially be +0.

\fp_const:Nn \fp_const:Nn hfp var i {hfloating point expression i}

\fp_const:cn
Creates a new constant hfp vari or raises an error if the name is already taken. The
Updated: 2012-05-08 hfp vari will be set globally equal to the result of evaluating the hfloating point expressioni.

\fp_zero:N \fp_zero:N hfp var i

\fp_zero:c
Sets the hfp vari to +0.
\fp_gzero:N
\fp_gzero:c
Updated: 2012-05-08

\fp_zero_new:N \fp_zero_new:N hfp var i

\fp_zero_new:c
Ensures that the hfp vari exists globally by applying \fp_new:N if necessary, then applies
\fp_gzero_new:N
\fp_gzero_new:c \fp_(g)zero:N to leave the hfp vari set to +0.

Updated: 2012-05-08

2 Setting floating point variables

\fp_set:Nn \fp_set:Nn hfp var i {hfloating point expression i}

\fp_set:cn
Sets hfp vari equal to the result of computing the hfloating point expressioni.
\fp_gset:Nn
\fp_gset:cn
Updated: 2012-05-08

177
\fp_set_eq:NN \fp_set_eq:NN hfp var1 i hfp var2 i
\fp_set_eq:(cN|Nc|cc)
Sets the floating point variable hfp var1 i equal to the current value of hfp var2 i.
\fp_gset_eq:NN
\fp_gset_eq:(cN|Nc|cc)
Updated: 2012-05-08

\fp_add:Nn \fp_add:Nn hfp var i {hfloating point expression i}

\fp_add:cn
Adds the result of computing the hfloating point expressioni to the hfp vari.
\fp_gadd:Nn
\fp_gadd:cn
Updated: 2012-05-08

\fp_sub:Nn \fp_sub:Nn hfp var i {hfloating point expression i}

\fp_sub:cn
Subtracts the result of computing the hfloating point expressioni from the hfp vari.
\fp_gsub:Nn
\fp_gsub:cn
Updated: 2012-05-08

3 Using floating point numbers

\fp_eval:n ? \fp_eval:n {hfloating point expression i}

New: 2012-05-08 Evaluates the hfloating point expressioni and expresses the result as a decimal number
Updated: 2012-07-08 with no exponent. Leading or trailing zeros may be inserted to compensate for the
exponent. Non-significant trailing zeros are trimmed, and integers are expressed without
a decimal separator. The values ±∞ and NaN trigger an “invalid operation” exception.
This function is identical to \fp_to_decimal:n.

\fp_to_decimal:N ? \fp_to_decimal:N hfp var i

\fp_to_decimal:(c|n) ? \fp_to_decimal:n {hfloating point expression i}
New: 2012-05-08 Evaluates the hfloating point expressioni and expresses the result as a decimal number
Updated: 2012-07-08 with no exponent. Leading or trailing zeros may be inserted to compensate for the
exponent. Non-significant trailing zeros are trimmed, and integers are expressed without
a decimal separator. The values ±∞ and NaN trigger an “invalid operation” exception.

\fp_to_dim:N ? \fp_to_dim:N hfp var i

\fp_to_dim:(c|n) ? \fp_to_dim:n {hfloating point expression i}
Updated: 2012-07-08 Evaluates the hfloating point expressioni and expresses the result as a dimension (in pt)
suitable for use in dimension expressions. The output is identical to \fp_to_decimal:n,
with an additional trailing pt. In particular, the result may be outside the range [−214 +
2−17 , 214 −2−17 ] of valid TEX dimensions, leading to overflow errors if used as a dimension.
The values ±∞ and NaN trigger an “invalid operation” exception.

178
 \fp_to_int:N ? \fp_to_int:N hfp var i
\fp_to_int:(c|n) ? \fp_to_int:n {hfloating point expression i}
Updated: 2012-07-08 Evaluates the hfloating point expressioni, and rounds the result to the closest integer,
rounding exact ties to an even integer. The result may be outside the range [−231 +
1, 231 −1] of valid TEX integers, leading to overflow errors if used in an integer expression.
The values ±∞ and NaN trigger an “invalid operation” exception.

\fp_to_scientific:N ? \fp_to_scientific:N hfp var i

\fp_to_scientific:(c|n) ? \fp_to_scientific:n {hfloating point expression i}
New: 2012-05-08 Evaluates the hfloating point expressioni and expresses the result in scientific notation:
Updated: 2012-07-08
hoptional - ihdigiti.h15 digitsiehoptional signihexponenti

The leading hdigiti is non-zero except in the case of ±0. The values ±∞ and NaN trigger
an “invalid operation” exception.

\fp_to_tl:N ? \fp_to_tl:N hfp var i

\fp_to_tl:(c|n) ? \fp_to_tl:n {hfloating point expression i}
Updated: 2012-07-08 Evaluates the hfloating point expressioni and expresses the result in (almost) the shortest
possible form. Numbers in the ranges (0, 10−3 ) and [1016 , ∞) are expressed in scientific
notation with trailing zeros trimmed and no decimal separator when there is a single
significant digit (see \fp_to_scientific:n). Numbers in the range [10−3 , 1016 ) are
expressed in a decimal notation without exponent, with trailing zeros trimmed, and no
decimal separator for integer values (see \fp_to_decimal:n. Negative numbers start
with -. The special values ±0, ±∞ and NaN are rendered as 0, -0, inf, -inf, and nan
respectively.

\fp_use:N ? \fp_use:N hfp var i

\fp_use:c ?
Inserts the value of the hfp vari into the input stream as a decimal number with no
Updated: 2012-07-08 exponent. Leading or trailing zeros may be inserted to compensate for the exponent.
Non-significant trailing zeros are trimmed. Integers are expressed without a decimal sep-
arator. The values ±∞ and NaN trigger an “invalid operation” exception. This function
is identical to \fp_to_decimal:N.

4 Floating point conditionals

\fp_if_exist_p:N ? \fp_if_exist_p:N hfp var i

\fp_if_exist_p:c ? \fp_if_exist:NTF hfp var i {htrue code i} {hfalse code i}
\fp_if_exist:NTF ? Tests whether the hfp vari is currently defined. This does not check that the hfp vari
\fp_if_exist:cTF ?
really is a floating point variable.
Updated: 2012-05-08

179
\fp_compare_p:nNn ? \fp_compare_p:nNn {hfpexpr1 i} hrelation i {hfpexpr2 i}
\fp_compare:nNnTF ? \fp_compare:nNnTF {hfpexpr1 i} hrelation i {hfpexpr2 i} {htrue code i} {hfalse code i}
Updated: 2012-05-08 Compares the hfpexpr1 i and the hfpexpr2 i, and returns true if the hrelationi is obeyed.
Two floating point numbers x and y may obey four mutually exclusive relations:
xhy,x=y,xiy, or x and y are not ordered. The latter case occurs exactly when either
operand is NaN, and this relation is denoted by the symbol ?. Note that a NaN is distinct
from any value, even another NaN, hence x = x is not true for a NaN. To test if a value
is NaN, compare it to an arbitrary number with the “not ordered” relation.
\fp_compare:nNnTF { <value> } ? { 0 }
{ } % <value> is nan
{ } % <value> is not nan

\fp_compare_p:n ? \fp_compare_p:n
\fp_compare:nTF ? {
hfpexpr1 i hrelation1 i
Updated: 2012-12-14
...
hfpexprN i hrelationN i
hfpexprN +1 i
}
\fp_compare:nTF
{
hfpexpr1 i hrelation1 i
...
hfpexprN i hrelationN i
hfpexprN +1 i
}
{htrue code i} {hfalse code i}
Evaluates the hfloating point expressionsi as described for \fp_eval:n and compares
consecutive result using the corresponding hrelationi, namely it compares hintexpr1 i and
hintexpr2 i using the hrelation1 i, then hintexpr2 i and hintexpr3 i using the hrelation2 i, until
finally comparing hintexprN i and hintexprN +1 i using the hrelationN i. The test yields
true if all comparisons are true. Each hfloating point expressioni is evaluated only once.
Contrarily to \int_compare:nTF, all hfloating point expressionsi are computed, even if
one comparison is false. Two floating point numbers x and y may obey four mutually
exclusive relations: xhy,x=y,xiy, or x and y are not ordered. The latter case occurs
exactly when one of the operands is NaN, and this relation is denoted by the symbol ?.
Each hrelationi can be any (non-empty) combination of <, =, >, and ?, plus an optional
leading ! (which negates the hrelationi), with the restriction that the hrelationi may
not start with ?, as this symbol has a different meaning (in combination with :) within
floatin point expressions. The comparison x hrelationi y is then true if the hrelationi
does not start with ! and the actual relation (<, =, >, or ?) between x and y appears
within the hrelationi, or on the contrary if the hrelationi starts with ! and the relation
between x and y does not appear within the hrelationi. Common choices of hrelationi
include >= (greater or equal), != (not equal), !? or <=> (comparable).

180
 5 Floating point expression loops

\fp_do_until:nNnn I \fp_do_until:nNnn {hfpexpr1 i} hrelation i {hfpexpr2 i} {hcode i}

New: 2012-08-16 Places the hcodei in the input stream for TEX to process, and then evaluates the relation-
ship between the two hfloating point expressionsi as described for \fp_compare:nNnTF.
If the test is false then the hcodei will be inserted into the input stream again and a
loop will occur until the hrelationi is true.

\fp_do_while:nNnn I \fp_do_while:nNnn {hfpexpr1 i} hrelation i {hfpexpr2 i} {hcode i}

New: 2012-08-16 Places the hcodei in the input stream for TEX to process, and then evaluates the relation-
ship between the two hfloating point expressionsi as described for \fp_compare:nNnTF.
If the test is true then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is false.

\fp_until_do:nNnn I \fp_until_do:nNnn {hfpexpr1 i} hrelation i {hfpexpr2 i} {hcode i}

New: 2012-08-16 Evaluates the relationship between the two hfloating point expressionsi as described for
\fp_compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is
false. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is true.

\fp_while_do:nNnn I \fp_while_do:nNnn {hfpexpr1 i} hrelation i {hfpexpr2 i} {hcode i}

New: 2012-08-16 Evaluates the relationship between the two hfloating point expressionsi as described for
\fp_compare:nNnTF, and then places the hcodei in the input stream if the hrelationi is
true. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is false.

\fp_do_until:nn I \fp_do_until:nn { hfpexpr1 i hrelation i hfpexpr2 i } {hcode i}

New: 2012-08-16 Places the hcodei in the input stream for TEX to process, and then evaluates the rela-
tionship between the two hfloating point expressionsi as described for \fp_compare:nTF.
If the test is false then the hcodei will be inserted into the input stream again and a
loop will occur until the hrelationi is true.

\fp_do_while:nn I \fp_do_while:nn { hfpexpr1 i hrelation i hfpexpr2 i } {hcode i}

New: 2012-08-16 Places the hcodei in the input stream for TEX to process, and then evaluates the rela-
tionship between the two hfloating point expressionsi as described for \fp_compare:nTF.
If the test is true then the hcodei will be inserted into the input stream again and a loop
will occur until the hrelationi is false.

\fp_until_do:nn I \fp_until_do:nn { hfpexpr1 i hrelation i hfpexpr2 i } {hcode i}

New: 2012-08-16 Evaluates the relationship between the two hfloating point expressionsi as described for
\fp_compare:nTF, and then places the hcodei in the input stream if the hrelationi is
false. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is true.

181
\fp_while_do:nn I \fp_while_do:nn { hfpexpr1 i hrelation i hfpexpr2 i } {hcode i}
New: 2012-08-16 Evaluates the relationship between the two hfloating point expressionsi as described for
\fp_compare:nTF, and then places the hcodei in the input stream if the hrelationi is
true. After the hcodei has been processed by TEX the test will be repeated, and a loop
will occur until the test is false.

6 Some useful constants, and scratch variables

\c_zero_fp Zero, with either sign.

\c_minus_zero_fp
New: 2012-05-08

\c_one_fp One as an fp: useful for comparisons in some places.

New: 2012-05-08

\c_inf_fp Infinity, with either sign. These can be input directly in a floating point expression as
\c_minus_inf_fp inf and -inf.
New: 2012-05-08

\c_e_fp The value of the base of the natural logarithm, e = exp(1).

Updated: 2012-05-08

\c_pi_fp The value of π. This can be input directly in a floating point expression as pi.
Updated: 2013-11-17

\c_one_degree_fp The value of 1◦ in radians. Multiply an angle given in degrees by this value to obtain a
New: 2012-05-08 result in radians. Note that trigonometric functions expecting an argument in radians or
Updated: 2013-11-17 in degrees are both available. Within floating point expressions, this can be accessed as
deg.

\l_tmpa_fp Scratch floating points for local assignment. These are never used by the kernel code, and
\l_tmpb_fp so are safe for use with any LATEX3-defined function. However, they may be overwritten
by other non-kernel code and so should only be used for short-term storage.

\g_tmpa_fp Scratch floating points for global assignment. These are never used by the kernel code,
\g_tmpb_fp and so are safe for use with any LATEX3-defined function. However, they may be over-
written by other non-kernel code and so should only be used for short-term storage.

182
 7 Floating point exceptions
The functions defined in this section are experimental, and their functionality may be
altered or removed altogether.
“Exceptions” may occur when performing some floating point operations, such as 0
/ 0, or 10 ** 1e9999. The IEEE standard defines 5 types of exceptions.
• Overflow occurs whenever the result of an operation is too large to be represented
as a normal floating point number. This results in ±∞.

• Underflow occurs whenever the result of an operation is too close to 0 to be repre-

sented as a normal floating point number. This results in ±0.
• Invalid operation occurs for operations with no defined outcome, for instance 0/0,
or sin(∞), and almost any operation involving a NaN. This normally results in a
NaN, except for conversion functions whose target type does not have a notion of
NaN (e.g., \fp_to_dim:n).
• Division by zero occurs when dividing a non-zero number by 0, or when evaluating
e.g., ln(0) or cot(0). This results in ±∞.
• Inexact occurs whenever the result of a computation is not exact, in other words,
almost always. At the moment, this exception is entirely ignored in LATEX3.
To each exception is associated a “flag”, which can be either on or off. By default, the
“invalid operation” exception triggers an (expandable) error, and raises the corresponding
flag. Other exceptions only raise the corresponding flag. The state of the flag can be
tested and modified. The behaviour when an exception occurs can be modified (using
\fp_trap:nn) to either produce an error and turn the flag on, or only turn the flag on,
or do nothing at all.

\fp_if_flag_on_p:n ? \fp_if_flag_on_p:n {hexception i}

\fp_if_flag_on:nTF ? \fp_if_flag_on:nTF {hexception i} {htrue code i} {hfalse code i}
New: 2012-08-08 Tests if the flag for the hexceptioni is on, which normally means the given hexceptioni
has occurred. This function is experimental, and may be altered or removed.

\fp_flag_off:n \fp_flag_off:n {hexception i}

New: 2012-08-08 Locally turns off the flag which indicates whether the hexceptioni has occurred. This
function is experimental, and may be altered or removed.

\fp_flag_on:n ? \fp_flag_on:n {hexception i}

New: 2012-08-08 Locally turns on the flag to indicate (or pretend) that the hexceptioni has occurred. Note
that this function is expandable: it is used internally by l3fp to signal when exceptions
do occur. This function is experimental, and may be altered or removed.

183
\fp_trap:nn \fp_trap:nn {hexception i} {htrap type i}
New: 2012-07-19 All occurrences of the hexceptioni (invalid_operation, division_by_zero, overflow,
Updated: 2012-08-08 or underflow) within the current group are treated as htrap typei, which can be
• none: the hexceptioni will be entirely ignored, and leave no trace;
• flag: the hexceptioni will turn the corresponding flag on when it occurs;

• error: additionally, the hexceptioni will halt the TEX run and display some infor-
mation about the current operation in the terminal.
This function is experimental, and may be altered or removed.

8 Viewing floating points

\fp_show:N \fp_show:N hfp var i

\fp_show:(c|n) \fp_show:n {hfloating point expression i}
New: 2012-05-08 Evaluates the hfloating point expressioni and displays the result in the terminal.
Updated: 2012-08-14

9 Floating point expressions

9.1 Input of floating point numbers
We support four types of floating point numbers:
• ±0.d1 d2 . . . d16 · 10n , a normal floating point number, with di ∈ [0, 9], d1 6= 0, and
|n| ≤ 10000;
• ±0, zero, with a given sign;

• ±∞, infinity, with a given sign;

• NaN, is “not a number”, and can be either quiet or signalling (not yet: this distinc-
tion is currently unsupported);
(not yet) subnormal numbers ±0.d1 d2 . . . d16 · 10−10000 with d1 = 0.

Normal floating point numbers are stored in base 10, with 16 significant figures.
On input, a normal floating point number consists of:
• hsigni: a possibly empty string of + and - characters;
• hsignificandi: a non-empty string of digits together with zero or one dot;

• hexponenti optionally: the character e, followed by a possibly empty string of

+ and - tokens, and a non-empty string of digits.

184
The sign of the resulting number is + if hsigni contains an even number of -, and -
otherwise, hence, an empty hsigni denotes a non-negative input. The stored significand
is obtained from hsignificandi by omitting the decimal separator and leading zeros, and
rounding to 16 significant digits, filling with trailing zeros if necessary. In particular, the
value stored is exact if the input hsignificandi has at most 16 digits. The stored hexponenti
is obtained by combining the input hexponenti (0 if absent) with a shift depending on
the position of the significand and the number of leading zeros.
A special case arises if the resulting hexponenti is either too large or too small for the
floating point number to be represented. This results either in an overflow (the number
is then replaced by ±∞), or an underflow (resulting in ±0).
The result is thus ±0 if and only if hsignificandi contains no non-zero digit (i.e.,
consists only in 0 characters, and an optional . character), or if there is an underflow.
Note that a single dot is currently a valid floating point number, equal to +0, but that
is not guaranteed to remain true.
Special numbers are input as follows:
• inf represents +∞, and can be preceded by any hsigni, yielding ±∞ as appropriate.
• nan represents a (quiet) non-number. It can be preceded by any sign, but that will
be ignored.
• Any unrecognizable string triggers an error, and produces a NaN.
Note that e-1 is not a representation of 10−1 , because it could be mistaken with the
difference of “e” and 1. This is consistent with several other programming languages.
However, in order to avoid confusions, e-1 is not considered to be this difference either.
To input the base of natural logarithms, use exp(1) or \c_e_fp.

9.2 Precedence of operators

We list here all the operations supported in floating point expressions, in order of de-
creasing precedence: operations listed earlier bind more tightly than operations listed
below them.
• Function calls (sin, ln, etc).
• Binary ** and ^ (right associative).
• Unary +, -, !.
• Binary *, /, and implicit multiplication by juxtaposition (2pi, 3(4+5), etc).
• Binary + and -.
• Comparisons >=, !=, <?, etc.
• Logical and, denoted by &&.
• Logical or, denoted by ||.
• Ternary operator ?: (right associative).

185
 The precedence of operations can be overridden using parentheses. In particular, those
precedences imply that

sin2pi = sin(2π) = 0,
2ˆ2max(3, 4) = 22 max(3,4) = 256.

Functions are called on the value of their argument, contrarily to TEX macros.

9.3 Operations
We now present the various operations allowed in floating point expressions, from the
lowest precedence to the highest. When used as a truth value, a floating point expression
is false if it is ±0, and true otherwise, including when it is NaN.

?: \fp_eval:n { hoperand1 i ? hoperand2 i : hoperand3 i }

The ternary operator ?: results in hoperand2 i if hoperand1 i is true, and hoperand3 i if it is
false (equal to ±0). All three hoperandsi are evaluated in all cases. The operator is right
associative, hence

\fp_eval:n
{
1 + 3 > 4 ? 1 :
2 + 4 > 5 ? 2 :
3 + 5 > 6 ? 3 : 4
}
first tests whether 1 + 3 > 4; since this isn’t true, the branch following : is taken, and
2 + 4 > 5 is compared; since this is true, the branch before : is taken, and everything else
is (evaluated then) ignored. That allows testing for various cases in a concise manner,
with the drawback that all computations are made in all cases.

TWOBARS \fp_eval:n { hoperand1 i || hoperand2 i }

If hoperand1 i is true (non-zero), use that value, otherwise the value of hoperand2 i. Both
hoperandsi are evaluated in all cases.

&& \fp_eval:n { hoperand1 i && hoperand2 i }

If hoperand1 i is false (equal to ±0), use that value, otherwise the value of hoperand2 i.
Both hoperandsi are evaluated in all cases.

186
< \fp_eval:n
= {
> hoperand1 i hrelation1 i
? ...
hoperandN i hrelationN i
Updated: 2013-12-14
hoperandN +1 i
}
Each hrelationi consists of a non-empty string of <, =, >, and ?, optionally preceded by !,
and may not start with ?. This evaluates to +1 if all comparisons hoperandi i hrelationj i
hoperandi+1 i are true, and +0 otherwise. All hoperandsi are evaluated in all cases. See
\fp_compare:nTF for details.

+ \fp_eval:n { hoperand1 i + hoperand2 i }

- \fp_eval:n { hoperand1 i - hoperand2 i }
Computes the sum or the difference of its two hoperandsi. The “invalid operation” ex-
ception occurs for ∞ − ∞. “Underflow” and “overflow” occur when appropriate.

* \fp_eval:n { hoperand1 i * hoperand2 i }

/ \fp_eval:n { hoperand1 i / hoperand2 i }
Computes the product or the ratio of its two hoperandsi. The “invalid operation” excep-
tion occurs for ∞/∞, 0/0, or 0 ∗ ∞. “Division by zero” occurs when dividing a finite
non-zero number by ±0. “Underflow” and “overflow” occur when appropriate.

+ \fp_eval:n { + hoperand i }
- \fp_eval:n { - hoperand i }
! \fp_eval:n { ! hoperand i }
The unary + does nothing, the unary - changes the sign of the hoperandi, and ! hoperandi
evaluates to 1 if hoperandi is false and 0 otherwise (this is the not boolean function).
Those operations never raise exceptions.

** \fp_eval:n { hoperand1 i ** hoperand2 i }

^ \fp_eval:n { hoperand1 i ^ hoperand2 i }
Raises hoperand1 i to the power hoperand2 i. This operation is right associative, hence 2
** 2 ** 3 equals 2ˆ2ˆ3 = 256. The “invalid operation” exception occurs if hoperand1 i
is negative or −0, and hoperand2 i is not an integer, unless the result is zero (in that case,
the sign is chosen arbitrarily to be +0). “Division by zero” occurs when raising ±0 to a
strictly negative power. “Underflow” and “overflow” occur when appropriate.

abs \fp_eval:n { abs( hfpexpr i ) }

Computes the absolute value of the hfpexpri. This function does not raise any exception
beyond those raised when computing its operand hfpexpri. See also \fp_abs:n.

exp \fp_eval:n { exp( hfpexpr i ) }

Computes the exponential of the hfpexpri. “Underflow” and “overflow” occur when ap-
propriate.

187
 ln \fp_eval:n { ln( hfpexpr i ) }
Computes the natural logarithm of the hfpexpri. Negative numbers have no (real) loga-
rithm, hence the “invalid operation” is raised in that case, including for ln(−0). “Division
by zero” occurs when evaluating ln(+0) = −∞. “Underflow” and “overflow” occur when
appropriate.

max \fp_eval:n { max( hfpexpr1 i , hfpexpr2 i , ... ) }

min \fp_eval:n { min( hfpexpr1 i , hfpexpr2 i , ... ) }
Evaluates each hfpexpri and computes the largest (smallest) of those. If any of the
hfpexpri is a NaN, the result is NaN. Those operations do not raise exceptions.

round \fp_eval:n { round ( hfpexpr i ) }

trunc \fp_eval:n { round ( hfpexpr1 i , hfpexpr2 i ) }
ceil Evaluates hfpexpr1 i = x and hfpexpr2 i = n, then rounds x to n places. If n is an integer,
floor
this rounds x to a multiple of 10−n ; if n = +∞, this always yields x; if n = −∞, this yields
New: 2013-12-14 one of ±0, ±∞, or NaN; if n is neither ±∞ nor an integer, then an “invalid operation”
exception is raised. When hfpexpr2 i is omitted, n = 0, i.e., hfpexpr1 i is rounded to an
integer. The rounding direction depends on the function:
• round yields the multiple of 10−n closest to x, and if x is half-way between two
such multiples, the even multiple is chosen (“ties to even”);
• floor, or the deprecated round-, yields the largest multiple of 10−n smaller or
equal to x (“round towards negative infinity”);

• ceil, or the deprecated round+, yields the smallest multiple of 10−n greater or
equal to x (“round towards positive infinity”);
• trunc, or the deprecated round0, yields a multiple of 10−n with the same sign as x
and with the largest absolute value less that that of x (“round towards zero”).

“Overflow” occurs if x is finite and the result is infinite (this can only happen if hfpexpr2 i <
−9984).

sin \fp_eval:n { sin( hfpexpr i ) }

cos \fp_eval:n { cos( hfpexpr i ) }
tan \fp_eval:n { tan( hfpexpr i ) }
cot \fp_eval:n { cot( hfpexpr i ) }
csc \fp_eval:n { csc( hfpexpr i ) }
sec \fp_eval:n { sec( hfpexpr i ) }
Updated: 2013-11-17 Computes the sine, cosine, tangent, cotangent, cosecant, or secant of the hfpexpri given
in radians. For arguments given in degrees, see sind, cosd, etc. Note that since π is
irrational, sin(8pi) is not quite zero, while its analog sind(8 × 180) is exactly zero. The
trigonometric functions are undefined for an argument of ±∞, leading to the “invalid
operation” exception. Additionally, evaluating tangent, cotangent, cosecant, or secant at
one of their poles leads to a “division by zero” exception. “Underflow” and “overflow”
occur when appropriate.

188
sind \fp_eval:n { sind( hfpexpr i ) }
cosd \fp_eval:n { cosd( hfpexpr i ) }
tand \fp_eval:n { tand( hfpexpr i ) }
cotd \fp_eval:n { cotd( hfpexpr i ) }
cscd \fp_eval:n { cscd( hfpexpr i ) }
secd \fp_eval:n { secd( hfpexpr i ) }
New: 2013-11-02 Computes the sine, cosine, tangent, cotangent, cosecant, or secant of the hfpexpri given
in degrees. For arguments given in radians, see sin, cos, etc. Note that since π is
irrational, sin(8pi) is not quite zero, while its analog sind(8 × 180) is exactly zero. The
trigonometric functions are undefined for an argument of ±∞, leading to the “invalid
operation” exception. Additionally, evaluating tangent, cotangent, cosecant, or secant at
one of their poles leads to a “division by zero” exception. “Underflow” and “overflow”
occur when appropriate.

asin \fp_eval:n { asin( hfpexpr i ) }

acos \fp_eval:n { acos( hfpexpr i ) }
acsc \fp_eval:n { acsc( hfpexpr i ) }
asec \fp_eval:n { asec( hfpexpr i ) }
New: 2013-11-02 Computes the arcsine, arccosine, arccosecant, or arcsecant of the hfpexpri and returns
the result in radians, in the range [−π/2, π/2] for asin and acsc and [0, π] for acos and
asec. For a result in degrees, use asind, etc. If the argument of asin or acos lies outside
the range [−1, 1], or the argument of acsc or asec inside the range (−1, 1), an “invalid
operation” exception is raised. “Underflow” and “overflow” occur when appropriate.

asind \fp_eval:n { asind( hfpexpr i ) }

acosd \fp_eval:n { acosd( hfpexpr i ) }
acscd \fp_eval:n { acscd( hfpexpr i ) }
asecd \fp_eval:n { asecd( hfpexpr i ) }
New: 2013-11-02 Computes the arcsine, arccosine, arccosecant, or arcsecant of the hfpexpri and returns
the result in degrees, in the range [−90, 90] for asin and acsc and [0, 180] for acos and
asec. For a result in radians, use asin, etc. If the argument of asin or acos lies outside
the range [−1, 1], or the argument of acsc or asec inside the range (−1, 1), an “invalid
operation” exception is raised. “Underflow” and “overflow” occur when appropriate.

189
atan \fp_eval:n { atan( hfpexpr i ) }
acot \fp_eval:n { atan( hfpexpr1 i , hfpexpr2 i ) }
\fp_eval:n { acot( hfpexpr i ) }
New: 2013-11-02
\fp_eval:n { acot( hfpexpr1 i , hfpexpr2 i ) }
Those functions yield an angle in radians: atand and acotd are their analogs in degrees.
The one-argument versions compute the arctangent or arccotangent of the hfpexpri: arc-
tangent takes values in the range [−π/2, π/2], and arccotangent in the range [0, π]. The
two-argument arctangent computes the angle in polar coordinates of the point with Carte-
sian coordinates (hfpexpr2 i, hfpexpr1 i): this is the arctangent of hfpexpr1 i/hfpexpr2 i, pos-
sibly shifted by π depending on the signs of hfpexpr1 i and hfpexpr2 i. The two-argument
arccotangent computes the angle in polar coordinates of the point (hfpexpr1 i, hfpexpr2 i),
equal to the arccotangent of hfpexpr1 i/hfpexpr2 i, possibly shifted by π. Both two-
argument functions take values in the wider range [−π, π]. The ratio hfpexpr1 i/hfpexpr2 i
need not be defined for the two-argument arctangent: when both expressions yield ±0,
or when both yield ±∞, the resulting angle is one of {±π/4, ±3π/4} depending on signs.
Only the “underflow” exception can occur.

atand \fp_eval:n { atand( hfpexpr i ) }

acotd \fp_eval:n { atand( hfpexpr1 i , hfpexpr2 i ) }
\fp_eval:n { acotd( hfpexpr i ) }
New: 2013-11-02
\fp_eval:n { acotd( hfpexpr1 i , hfpexpr2 i ) }
Those functions yield an angle in degrees: atand and acotd are their analogs in ra-
dians. The one-argument versions compute the arctangent or arccotangent of the
hfpexpri: arctangent takes values in the range [−90, 90], and arccotangent in the range
[0, 180]. The two-argument arctangent computes the angle in polar coordinates of
the point with Cartesian coordinates (hfpexpr2 i, hfpexpr1 i): this is the arctangent of
hfpexpr1 i/hfpexpr2 i, possibly shifted by 180 depending on the signs of hfpexpr1 i and
hfpexpr2 i. The two-argument arccotangent computes the angle in polar coordinates of
the point (hfpexpr1 i, hfpexpr2 i), equal to the arccotangent of hfpexpr1 i/hfpexpr2 i, possibly
shifted by 180. Both two-argument functions take values in the wider range [−180, 180].
The ratio hfpexpr1 i/hfpexpr2 i need not be defined for the two-argument arctangent:
when both expressions yield ±0, or when both yield ±∞, the resulting angle is one
of {±45, ±135} depending on signs. Only the “underflow” exception can occur.

sqrt \fp_eval:n { sqrt( hfpexpr i ) }

New: 2013-12-14 Computes the square root of the hfpexpri. The “invalid operation” is raised
√ when the
hfpexpri
√ is negative;
√ no other √exception can occur. Special values yield −0 = −0,
+0 = +0, +∞ = +∞ and NaN = NaN.

inf The special values +∞, −∞, and NaN are represented as inf, -inf and nan (see \c_-
nan inf_fp, \c_minus_inf_fp and \c_nan_fp).

pi The value of π (see \c_pi_fp).

deg The value of 1◦ in radians (see \c_one_degree_fp).

190
 em Those units of measurement are equal to their values in pt, namely
ex
in 1in = 72.27pt
pt
1pt = 1pt
pc
cm 1pc = 12pt
mm 1
dd 1cm = in = 28.45275590551181pt
2.54
cc 1
nd 1mm = in = 2.845275590551181pt
nc
25.4
bp 1dd = 0.376065mm = 1.07000856496063pt
sp 1cc = 12dd = 12.84010277952756pt
1nd = 0.375mm = 1.066978346456693pt
1nc = 12nd = 12.80374015748031pt
1
1bp = in = 1.00375pt
72
−16
1sp = 2 pt = 1.52587890625e − 5pt.

The values of the (font-dependent) units em and ex are gathered from TEX when the
surrounding floating point expression is evaluated.

true Other names for 1 and +0.

false

\fp_abs:n ? \fp_abs:n {hfloating point expression i}

New: 2012-05-14 Evaluates the hfloating point expressioni as described for \fp_eval:n and leaves the
Updated: 2012-07-08 absolute value of the result in the input stream. This function does not raise any exception
beyond those raised when evaluating its argument. Within floating point expressions,
abs() can be used.

\fp_max:nn ? \fp_max:nn {hfp expression 1i} {hfp expression 2i}

\fp_min:nn ?
Evaluates the hfloating point expressionsi as described for \fp_eval:n and leaves the
New: 2012-09-26 resulting larger (max) or smaller (min) value in the input stream. This function does not
raise any exception beyond those raised when evaluating its argument. Within floating
point expressions, max() and min() can be used.

10 Disclaimer and roadmap

The package may break down if the escape character is among 0123456789_+; if it receives
a TEX primitive conditional affected by \exp_not:N.
The following need to be done. I’ll try to time-order the items.

• Decide what exponent range to consider.

191
 • Support signalling nan.
• Modulo and remainder, and rounding functions quantize, quantize0, quantize+,
quantize-, quantize=, round=. Should the modulo also be provided as (catcode
12) %?

• \fp_format:nn {hfpexpri} {hformati}, but what should hformati be? More general
pretty printing?
• Add and, or, xor? Perhaps under the names all, any, and xor?
• Add log(x, b) for logarithm of x in base b.

• hypot (Euclidean length). Cartesian-to-polar transform.

• Hyperbolic functions cosh, sinh, tanh.
• Inverse hyperbolics.
• Base conversion, input such as 0xAB.CDEF.

• Random numbers (pgfmath provides rnd, rand, random), with seed reset at every
\fp_set:Nn.
• Factorial (not with !), gamma function.
• Improve coefficients of the sin and tan series.

• Treat upper and lower case letters identically in identifiers, and ignore underscores.
• Add an array(1,2,3) and i=complex(0,1).
• Provide an experimental map function? Perhaps easier to implement if it is a single
character, @sin(1,2)?

• Provide \fp_if_nan:nTF, and an isnan function?

• Support keyword arguments?
Pgfmath also provides box-measurements (depth, height, width), but boxes are not pos-
sible expandably.
Bugs. (Exclamation points mark important bugs.)
• Check that functions are monotonic when they should.
• Add exceptions to ?:, !<=>?, &&, ||, and !.
• Logarithms of numbers very close to 1 are inaccurate.

• When rounding towards −∞, \dim_to_fp:n {0pt} should return −0, not +0.
• The result of (±0) + (±0), of x + (−x), and of (−x) + x should depend on the
rounding mode.

192
• 0e9999999999 gives a TEX “number too large” error.
• Subnormals are not implemented.
• The overflow trap receives the wrong argument in l3fp-expo (see exp(1e5678) in
m3fp-traps001).

Possible optimizations/improvements.
• Document that l3trial/l3fp-types introduces tools for adding new types.
• In subsection 9.1, write a grammar.

• Fix the TWO BARS business with the index.

• It would be nice if the parse auxiliaries for each operation were set up in the
corresponding module, rather than centralizing in l3fp-parse.
• Some functions should get an _o ending to indicate that they expand after their
result.

• More care should be given to distinguish expandable/restricted expandable (auxil-

iary and internal) functions.
• The code for the ternary set of functions is ugly.
• There are many ~ missing in the doc to avoid bad line-breaks.

• The algorithm for computing the logarithm of the significand could be made to use
a 5 terms Taylor series instead of 10 terms by taking c = 2000/(b200xc+1) ∈ [10, 95]
instead of c ∈ [1, 10]. Also, it would then be possible to simplify the computation
of t. However, we would then have to hard-code the logarithms of 44 small integers
instead of 9.

• Improve notations in the explanations of the division algorithm (l3fp-basics).

• Understand and document \__fp_basics_pack_weird_low:NNNNw and \__fp_-
basics_pack_weird_high:NNNNNNNNw better. Move the other basics_pack auxil-
iaries to l3fp-aux under a better name.

• Find out if underflow can really occur for trigonometric functions, and redoc as
appropriate.
• Add bibliography. Some of Kahan’s articles, some previous TEX fp packages, the
international standards,. . .

• Also take into account the “inexact” exception?

• Support multi-character prefix operators (e.g., @/ or whatever)? Perhaps for in-
cluding comments inside the computation itself??

193
Part XXIII
The l3candidates package
Experimental additions to l3kernel
1 Important notice
This module provides a space in which functions can be added to l3kernel (expl3) while
still being experimental.
As such, the functions here may not remain in their current form,
or indeed at all, in l3kernel in the future.

In contrast to the material in l3experimental, the functions here are all small additions to
the kernel. We encourage programmers to test them out and report back on the LaTeX-L
mailing list.
Thus, if you intend to use any of these functions from the candidate module in a
public package offered to others for productive use (e.g., being placed on CTAN) please
consider the following points carefully:
• Be prepared that your public packages might require updating when such functions
are being finalized.
• Consider informing us that you use a particular function in your public package,
e.g., by discussing this on the LaTeX-L mailing list. This way it becomes easier to
coordinate any updates necessary without a issues for the users of your package.
• Discussing and understanding use cases for a particular addition or concept also
helps to ensure that we provide the right interfaces in the final version so please
give us feedback if you consider a certain candidate function useful (or not).
We only add functions in this space if we consider them being serious candidates for
a final inclusion into the kernel. However, real use sometimes leads to better ideas, so
functions from this module are not necessarily stable and we may have to adjust them!

2 Additions to l3box
2.1 Affine transformations
Affine transformations are changes which (informally) preserve straight lines. Simple
translations are affine transformations, but are better handled in TEX by doing the trans-
lation first, then inserting an unmodified box. On the other hand, rotation and resizing
of boxed material can best be handled by modifying boxes. These transformations are
described here.

194
 \box_resize:Nnn \box_resize:Nnn hbox i {hx-size i} {hy-size i}
\box_resize:cnn
Resize the hboxi to hx-sizei horizontally and hy-sizei vertically (both of the sizes are
dimension expressions). The hy-sizei is the vertical size (height plus depth) of the box.
The updated hboxi will be an hbox, irrespective of the nature of the hboxi before the
resizing is applied. Negative sizes will cause the material in the hboxi to be reversed in
direction, but the reference point of the hboxi will be unchanged. Thus negative y-sizes
will result in a box a depth dependent on the height of the original box a height dependent
on the depth. The resizing applies within the current TEX group level.

\box_resize_to_ht_plus_dp:Nn \box_resize_to_ht_plus_dp:Nn hbox i {hy-size i}

\box_resize_to_ht_plus_dp:cn

Resize the hboxi to hy-sizei vertically, scaling the horizontal size by the same amount
(hy-sizei is a dimension expression). The hy-sizei is the vertical size (height plus depth)
of the box. The updated hboxi will be an hbox, irrespective of the nature of the hboxi
before the resizing is applied. A negative size will cause the material in the hboxi to
be reversed in direction, but the reference point of the hboxi will be unchanged. Thus
negative y-sizes will result in a box with depth dependent on the height of the original
box and height dependent on the depth of the original. The resizing applies within the
current TEX group level.

\box_resize_to_ht:Nn \box_resize_to_ht:Nn hbox i {hy-size i}

\box_resize_to_ht:cn
Resize the hboxi to hy-sizei vertically, scaling the horizontal size by the same amount
(hy-sizei is a dimension expression). The hy-sizei is the height only, not including depth,
of the box. The updated hboxi will be an hbox, irrespective of the nature of the hboxi
before the resizing is applied. A negative size will cause the material in the hboxi to
be reversed in direction, but the reference point of the hboxi will be unchanged. Thus
negative y-sizes will result in a box with depth dependent on the height of the original
box and height dependent on the depth of the original. The resizing applies within the
current TEX group level.

\box_resize_to_wd:Nn \box_resize_to_wd:Nn hbox i {hx-size i}

\box_resize_to_wd:cn
Resize the hboxi to hx-sizei horizontally, scaling the vertical size by the same amount
(hx-sizei is a dimension expression). The updated hboxi will be an hbox, irrespective
of the nature of the hboxi before the resizing is applied. A negative size will cause the
material in the hboxi to be reversed in direction, but the reference point of the hboxi
will be unchanged. Thus negative y-sizes will result in a box a depth dependent on the
height of the original box a height dependent on the depth. The resizing applies within
the current TEX group level.

195
\box_resize_to_wd_and_ht:Nnn \box_resize_to_wd_and_ht:Nnn hbox i {hx-size i} {hy-size i}
\box_resize_to_wd_and_ht:cnn
New: 2014-07-03

Resize the hboxi to a height of hx-sizei horizontally and hy-sizei vertically (both of the
sizes are dimension expressions). The hy-sizei is the height of the box, ignoring any
depth. The updated hboxi will be an hbox, irrespective of the nature of the hboxi before
the resizing is applied. Negative sizes will cause the material in the hboxi to be reversed
in direction, but the reference point of the hboxi will be unchanged.

\box_rotate:Nn \box_rotate:Nn hbox i {hangle i}

\box_rotate:cn
Rotates the hboxi by hanglei (in degrees) anti-clockwise about its reference point. The
reference point of the updated box will be moved horizontally such that it is at the left
side of the smallest rectangle enclosing the rotated material. The updated hboxi will
be an hbox, irrespective of the nature of the hboxi before the rotation is applied. The
rotation applies within the current TEX group level.

\box_scale:Nnn \box_scale:Nnn hbox i {hx-scale i} {hy-scale i}

\box_scale:cnn
Scales the hboxi by factors hx-scalei and hy-scalei in the horizontal and vertical directions,
respectively (both scales are integer expressions). The updated hboxi will be an hbox,
irrespective of the nature of the hboxi before the scaling is applied. Negative scalings will
cause the material in the hboxi to be reversed in direction, but the reference point of the
hboxi will be unchanged. Thus negative y-scales will result in a box a depth dependent
on the height of the original box a height dependent on the depth. The resizing applies
within the current TEX group level.

2.2 Viewing part of a box

\box_clip:N \box_clip:N hbox i

\box_clip:c
Clips the hboxi in the output so that only material inside the bounding box is displayed
in the output. The updated hboxi will be an hbox, irrespective of the nature of the hboxi
before the clipping is applied. The clipping applies within the current TEX group level.
These functions require the LATEX3 native drivers: they will not work
with the LATEX 2ε graphics drivers!

TEXhackers note: Clipping is implemented by the driver, and as such the full content of
the box is placed in the output file. Thus clipping does not remove any information from the
raw output, and hidden material can therefore be viewed by direct examination of the file.

196
 \box_trim:Nnnnn \box_trim:Nnnnn hbox i {hleft i} {hbottom i} {hright i} {htop i}
\box_trim:cnnnn
Adjusts the bounding box of the hboxi hlefti is removed from the left-hand edge of the
bounding box, hrighti from the right-hand edge and so fourth. All adjustments are
hdimension expressionsi. Material output of the bounding box will still be displayed in
the output unless \box_clip:N is subsequently applied. The updated hboxi will be an
hbox, irrespective of the nature of the hboxi before the trim operation is applied. The
adjustment applies within the current TEX group level. The behavior of the operation
where the trims requested is greater than the size of the box is undefined.

\box_viewport:Nnnnn \box_viewport:Nnnnn hbox i {hllx i} {hlly i} {hurx i} {hury i}

\box_viewport:cnnnn
Adjusts the bounding box of the hboxi such that it has lower-left co-ordinates (hllxi,
hllyi) and upper-right co-ordinates (hurxi, huryi). All four co-ordinate positions are
hdimension expressionsi. Material output of the bounding box will still be displayed in
the output unless \box_clip:N is subsequently applied. The updated hboxi will be an
hbox, irrespective of the nature of the hboxi before the viewport operation is applied.
The adjustment applies within the current TEX group level.

2.3 Internal variables

\l__box_angle_fp The angle through which a box is rotated by \box_rotate:Nn, given in degrees counter-
clockwise. This value is required by the underlying driver code in l3driver to carry out
the driver-dependent part of box rotation.

\l__box_cos_fp The sine and cosine of the angle through which a box is rotated by \box_rotate:Nn: the
\l__box_sin_fp values refer to the angle counter-clockwise. These values are required by the underlying
driver code in l3driver to carry out the driver-dependent part of box rotation.

\l__box_scale_x_fp The scaling factors by which a box is scaled by \box_scale:Nnn or \box_resize:Nnn.

\l__box_scale_y_fp These values are required by the underlying driver code in l3driver to carry out the
driver-dependent part of box rotation.

\l__box_internal_box Box used for affine transformations, which is used to contain rotated material when ap-
plying \box_rotate:Nn. This box must be correctly constructed for the driver-dependent
code in l3driver to function correctly.

3 Additions to l3coffins

\coffin_resize:Nnn \coffin_resize:Nnn hcoffin i {hwidth i} {htotal-height i}

\coffin_resize:cnn
Resized the hcoffini to hwidthi and htotal-heighti, both of which should be given as di-
mension expressions.

197
 \coffin_rotate:Nn \coffin_rotate:Nn hcoffin i {hangle i}
\coffin_rotate:cn
Rotates the hcoffini by the given hanglei (given in degrees counter-clockwise). This
process will rotate both the coffin content and poles. Multiple rotations will not result
in the bounding box of the coffin growing unnecessarily.

\coffin_scale:Nnn \coffin_scale:Nnn hcoffin i {hx-scale i} {hy-scale i}

\coffin_scale:cnn
Scales the hcoffini by a factors hx-scalei and hy-scalei in the horizontal and vertical
directions, respectively. The two scale factors should be given as real numbers.

4 Additions to l3file

\file_if_exist_input:nTF \file_if_exist_input:n {hfile name i}

\file_if_exist_input:nTF {hfile name i} {htrue code i} {hfalse code i}
New: 2014-07-02
Searches for hfile namei using the current TEX search path and the additional paths
controlled by \file_path_include:n). If found, inserts the htrue codei then reads in
the file as additional LATEX source as described for \file_input:n. Note that \file_-
if_exist_input:n does not raise an error if the file is not found, in contrast to \file_-
input:n.

\ior_map_inline:Nn \ior_map_inline:Nn hstream i {hinline function i}

New: 2012-02-11 Applies the hinline functioni to hlinesi obtained by reading one or more lines (until an
equal number of left and right braces are found) from the hstreami. The hinline functioni
should consist of code which will receive the hlinei as #1. Note that TEX removes trailing
space and tab characters (character codes 32 and 9) from every line upon input. TEX
also ignores any trailing new-line marker from the file it reads.

\ior_str_map_inline:Nn \ior_str_map_inline:Nn {hstream i} {hinline function i}

New: 2012-02-11 Applies the hinline functioni to every hlinei in the hstreami. The material is read from
the hstreami as a series of tokens with category code 12 (other), with the exception of
space characters which are given category code 10 (space). The hinline functioni should
consist of code which will receive the hlinei as #1. Note that TEX removes trailing space
and tab characters (character codes 32 and 9) from every line upon input. TEX also
ignores any trailing new-line marker from the file it reads.

198
 \ior_map_break: \ior_map_break:
New: 2012-06-29 Used to terminate a \ior_map_... function before all lines from the hstreami have been
processed. This will normally take place within a conditional statement, for example
\ior_map_inline:Nn \l_my_ior
{
\str_if_eq:nnTF { #1 } { bingo }
{ \ior_map_break: }
{
% Do something useful
}
}

Use outside of a \ior_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before further items are taken from the input stream.
This will depend on the design of the mapping function.

\ior_map_break:n \ior_map_break:n {htokens i}

New: 2012-06-29 Used to terminate a \ior_map_... function before all lines in the hstreami have been
processed, inserting the htokensi after the mapping has ended. This will normally take
place within a conditional statement, for example
\ior_map_inline:Nn \l_my_ior
{
\str_if_eq:nnTF { #1 } { bingo }
{ \ior_map_break:n { <tokens> } }
{
% Do something useful
}
}
Use outside of a \ior_map_... scenario will lead to low level TEX errors.

TEXhackers note: When the mapping is broken, additional tokens may be inserted by the
internal macro \__prg_break_point:Nn before the htokensi are inserted into the input stream.
This will depend on the design of the mapping function.

199
 5 Additions to l3prop

\prop_map_tokens:Nn I \prop_map_tokens:Nn hproperty list i {hcode i}

\prop_map_tokens:cn I
Analogue of \prop_map_function:NN which maps several tokens instead of a single func-
tion. The hcodei receives each key–value pair in the hproperty listi as two trailing brace
groups. For instance,
\prop_map_tokens:Nn \l_my_prop { \str_if_eq:nnT { mykey } }
will expand to the value corresponding to mykey: for each pair in \l_my_prop the function
\str_if_eq:nnT receives mykey, the hkeyi and the hvaluei as its three arguments. For
that specific task, \prop_item:Nn is faster.

6 Additions to l3seq

\seq_mapthread_function:NNN I \seq_mapthread_function:NNN hseq1 i hseq2 i hfunction i

\seq_mapthread_function:(NcN|cNN|ccN) I

Applies hfunctioni to every pair of items hseq1 -itemi–hseq2 -itemi from the two sequences,
returning items from both sequences from left to right. The hfunctioni will receive two
n-type arguments for each iteration. The mapping will terminate when the end of ei-
ther sequence is reached (i.e. whichever sequence has fewer items determines how many
iterations occur).

\seq_set_filter:NNn \seq_set_filter:NNn hsequence1 i hsequence2 i {hinline boolexpr i}

\seq_gset_filter:NNn
Evaluates the hinline boolexpri for every hitemi stored within the hsequence2 i. The hinline
boolexpri will receive the hitemi as #1. The sequence of all hitemsi for which the hinline
boolexpri evaluated to true is assigned to hsequence1 i.

TEXhackers note: Contrarily to other mapping functions, \seq_map_break: cannot be

used in this function, and will lead to low-level TEX errors.

\seq_set_map:NNn \seq_set_map:NNn hsequence1 i hsequence2 i {hinline function i}

\seq_gset_map:NNn
Applies hinline functioni to every hitemi stored within the hsequence2 i. The hinline
New: 2011-12-22 functioni should consist of code which will receive the hitemi as #1. The sequence result-
ing from x-expanding hinline functioni applied to each hitemi is assigned to hsequence1 i.
As such, the code in hinline functioni should be expandable.

TEXhackers note: Contrarily to other mapping functions, \seq_map_break: cannot be

used in this function, and will lead to low-level TEX errors.

200
 7 Additions to l3skip

\skip_split_finite_else_action:nnNN \skip_split_finite_else_action:nnNN {hskipexpr i} {haction i}

hdimen1 i hdimen2 i
Checks if the hskipexpri contains finite glue. If it does then it assigns hdimen1 i the stretch
component and hdimen2 i the shrink component. If it contains infinite glue set hdimen1 i
and hdimen2 i to 0 pt and place #2 into the input stream: this is usually an error or
warning message of some sort.

8 Additions to l3tl

\tl_if_single_token_p:n ? \tl_if_single_token_p:n {htoken list i}

\tl_if_single_token:nTF ? \tl_if_single_token:nTF {htoken list i} {htrue code i} {hfalse code i}
Tests if the token list consists of exactly one token, i.e. is either a single space character
or a single “normal” token. Token groups ({. . . }) are not single tokens.

\tl_reverse_tokens:n ? \tl_reverse_tokens:n {htokens i}

This function, which works directly on TEX tokens, reverses the order of the htokensi:
the first will be the last and the last will become first. Spaces are preserved. The reversal
also operates within brace groups, but the braces themselves are not exchanged, as this
would lead to an unbalanced token list. For instance, \tl_reverse_tokens:n {a~{b()}}
leaves {)(b}~a in the input stream. This function requires two steps of expansion.

TEXhackers note: The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the token list will not expand further when appearing in an x-type argument
expansion.

\tl_count_tokens:n ? \tl_count_tokens:n {htokens i}

Counts the number of TEX tokens in the htokensi and leaves this information in the input
stream. Every token, including spaces and braces, contributes one to the total; thus for
instance, the token count of a~{bc} is 6. This function requires three expansions, giving
an hinteger denotationi.

201
\tl_expandable_uppercase:n ? \tl_expandable_uppercase:n {htokens i}
\tl_expandable_lowercase:n ? \tl_expandable_lowercase:n {htokens i}

The \tl_expandable_uppercase:n function works through all of the htokensi, replacing

characters in the range a–z (with arbitrary category code) by the corresponding letter in
the range A–Z, with category code 11 (letter). Similarly, \tl_expandable_lowercase:n
replaces characters in the range A–Z by letters in the range a–z, and leaves other tokens
unchanged. This function requires two steps of expansion.

TEXhackers note: Begin-group and end-group characters are normalized and become
{ and }, respectively. The result is returned within the \unexpanded primitive (\exp_not:n),
which means that the token list will not expand further when appearing in an x-type argument
expansion.

\tl_lower_case:n I \tl_upper_case:n {htokens i}

\tl_lower_case:nn I \tl_upper_case:nn {hlanguage i} {htokens i}
\tl_upper_case:n I These functions are intended to be applied to input which may be regarded broadly
\tl_upper_case:nn I as “text”. They traverse the htokensi and change the case of characters as discussed
\tl_mixed_case:n I
below. The character code of the characters replaced may be arbitrary: the replacement
\tl_mixed_case:nn I
characters will have stand document-level category codes (11 for letters, 12 for letter-like
New: 2014-06-30 characters which can also be case-changed).
The functions are x-type expandable: tokens are returned protected from further
expansion where appropriate. Begin-group and end-group characters in the htokensi are
normalized and become { and }, respectively. Any tokens within such a group will not
be case-changed, and thus for example

\tl_upper_case:n { Some~text~{$y = mx + c$}~with~{Protection} }

will become
SOME~TEXT~{$y = mx + c$}~WITH~{Protection}

‘Mixed’ case conversion may be regarded informally as converting the first character
of the htokensi to upper case and the rest to lower case. However, the process is more
complex than this as there are some cases where a single lower case character maps
to a special form, for example ij in Dutch which becomes IJ. As such, \tl_mixed_-
case:n(n) implement a more sophisticated mapping which accounts for this and for
modifying accents on the first letter. Spaces at the start of the htokensi are ignored when
finding the first “letter” for conversion, while a brace group will terminate this search.
For example
\tl_mixed_case:n { hello~WORLD } % => "Hello world"
\tl_mixed_case:n { ~hello~WORLD } % => " Hello world"
\tl_mixed_case:n { {hello}~WORLD } % => "{hello} world"

where the brace group is retained. (Note that the Unicode Consortium describe this as
‘title case’, but that in English title case applies on a word-by-word basis. The ‘mixed’

202
 case implemented here is a lower level concept needed for both ‘title’ and ‘sentence’ casing
of text.)
As is generally true for expl3, these functions are designed to work with engine-native
input only. As such, when used with pdfTEX only the characters a–zA–Z are modified.
When used with XETEX or LuaTEX a full range of Unicode transformations are enabled.
Specifically, the standard mappings here follow those defined by the Unicode Consortium
in UnicodeData.txt and SpecialCasing.txt. Note that in some cases, pdfTEX can
interpret the input to a case change but not generate the correct output (for example in
the mapping i to I-dot in Turkish): in these cases the input is left unchanged.
Context-sensitive mappings are enabled: language-dependent cases are discussed
below. The “final sigma” rule for Greek letters is enabled and active for all inputs. It
is implemented here in a modified form which takes account of the requirements of the
likely real use cases, performance and expandability. Thus a capital sigma will map to a
final-sigma if it is followed by a space or one of the characters: !’),.:;?]}. (Feedback
on this area is very welcome.)
Language-sensitive conversions are enabled using the hlanguagei argument, and fol-
low Unicode Consortium guidelines. Currently, the languages recognised for special han-
dling are as follows.
• Azeri and Turkish (az and tr). The case pairs I/i-dotless and I-dot/i are activated
for these languages. The combining dot mark is removed when lower casing I-dot
and introduced when upper casing i-dotless.
• Lithuanian (lt). The lower case letters i and j should retain a dot above when the
accents grave, acute or tilde are present. This is implemented for lower casing of
the relevant upper case letters both when input as single Unicode codepoints and
when using combining accents. The combining dot is removed when upper casing
in these cases. Note that only the accents used in Lithuanian are covered: the
behaviour of other accents are not modified.

• Dutch (nl). Capitalisation of ij at the beginning of mixed cased input produces IJ

rather than Ij. The output retains two separate letters, thus this transformation
is available using pdfTEX.
Creating additional context-sensitive mappings requires knowledge of the underlying
mapping implementation used here. The team are happy to add these to the kernel
where they are well-documented (e.g. in Unicode Consortium or relevant government
publications).

\tl_set_from_file:Nnn \tl_set_from_file:Nnn htl i {hsetup i} {hfilename i}

\tl_set_from_file:cnn
Defines htli to the contents of hfilenamei. Category codes may need to be set appropri-
\tl_gset_from_file:Nnn
\tl_gset_from_file:cnn ately via the hsetupi argument.

New: 2014-06-25

203
\tl_set_from_file_x:Nnn \tl_set_from_file_x:Nnn htl i {hsetup i} {hfilename i}
\tl_set_from_file_x:cnn
Defines htli to the contents of hfilenamei, expanding the contents of the file as it is read.
\tl_gset_from_file_x:Nnn
\tl_gset_from_file_x:cnn Category codes and other definitions may need to be set appropriately via the hsetupi
argument.
New: 2014-06-25

9 Additions to l3tokens

\char_set_active:Npn \char_set_active:Npn hchar i hparameters i {hcode i}

\char_set_active:Npx
Makes hchari an active character to expand to hcodei as replacement text. Within the
hcodei, the hparametersi (#1, #2, etc.) will be replaced by those absorbed. The hchari is
made active within the current TEX group level, and the definition is also local.

\char_gset_active:Npn \char_gset_active:Npn hchar i hparameters i {hcode i}

\char_gset_active:Npx
Makes hchari an active character to expand to hcodei as replacement text. Within the
hcodei, the hparametersi (#1, #2, etc.) will be replaced by those absorbed. The hchari is
made active within the current TEX group level, but the definition is global. This function
is therefore suited to cases where an active character definition should be applied only in
some context (where the hchari is again made active).

\char_set_active_eq:NN \char_set_active_eq:NN hchar i hfunction i

Makes hchari an active character equivalent in meaning to the hfunctioni (which may
itself be an active character). The hchari is made active within the current TEX group
level, and the definition is also local.

\char_gset_active_eq:NN \char_gset_active_eq:NN hchar i hfunction i

Makes hchari an active character equivalent in meaning to the hfunctioni (which may
itself be an active character). The hchari is made active within the current TEX group
level, but the definition is global. This function is therefore suited to cases where an
active character definition should be applied only in some context (where the hchari is
again made active).

\peek_N_type:TF \peek_N_type:TF {htrue code i} {hfalse code i}

Updated: 2012-12-20 Tests if the next htokeni in the input stream can be safely grabbed as an N-type argument.
The test will be hfalsei if the next htokeni is either an explicit or implicit begin-group
or end-group token (with any character code), or an explicit or implicit space character
(with character code 32 and category code 10), or an outer token (never used in LATEX3)
and htruei in all other cases. Note that a htruei result ensures that the next htokeni is a
valid N-type argument. However, if the next htokeni is for instance \c_space_token, the
test will take the hfalsei branch, even though the next htokeni is in fact a valid N-type
argument. The htokeni will be left in the input stream after the htrue codei or hfalse
codei (as appropriate to the result of the test).

204
 Part XXIV
The l3drivers package
Drivers
TEX relies on drivers in order to carry out a number of tasks, such as using color, including
graphics and setting up hyper-links. The nature of the code required depends on the exact
driver in use. Currently, LATEX3 is aware of the following drivers:
• pdfmode: The “driver” for direct PDF output by both pdfTEX and LuaTEX (no
separate driver is used in this case: the engine deals with PDF creation itself).
• dvips: The dvips program, which works in conjugation with pdfTEX or LuaTEX
in DVI mode.
• dvipdfmx: The dvipdfmx program, which works in conjugation with pdfTEX or
LuaTEX in DVI mode.
• xdvipdfmx: The driver used by XETEX.
The code here is all very low-level, and should not in general be used outside of the
kernel. It is also important to note that many of the functions here are closely tied to
the immediate level “up”: several variable values must be in the correct locations for the
driver code to function.

1 Box clipping

\__driver_box_use_clip:N \__driver_box_use_clip:N hbox i

New: 2011-11-11 Inserts the content of the hboxi at the current insertion point such that any material
outside of the bounding box will not be displayed by the driver. The material in the
hboxi is still placed in the output stream: the clipping takes place at a driver level.
This function should only be used within a surrounding horizontal box construct.

205
 2 Box rotation and scaling

\__driver_box_rotate_begin: \__driver_box_rotate_begin:
\__driver_box_rotate_end: \box_use:N \l__box_internal_box
\__driver_box_rotate_end:
New: 2011-09-01
Updated: 2013-12-27

Rotates the hbox materiali anti-clockwise around the current insertion point. The angle
of rotation (in degrees counter-clockwise) and the sine and cosine of this angle should
be stored in \l__box_angle_fp, \l__box_sin_fp and \l__box_cos_fp, respectively.
Typically, the box material inserted between the beginning and end markers will be
stored in \l__box_internal_box: this fact is required by some drivers to obtain the
correct output.

\__driver_box_scale_begin: \__driver_box_scale_begin:
\__driver_box_scale_end: hbox material i
\__driver_box_scale_end:
New: 2011-09-02
Updated: 2013-12-27 Scales the hbox materiali (which should be either a \box_use:N or \hbox:n construct).
The hbox materiali is scaled by the values stored in \l__box_scale_x_fp and \l__-
box_scale_y_fp in the horizontal and vertical directions, respectively. This function is
also reused when resizing boxes: at a driver level, only scalings are supported and so the
higher-level code must convert the absolute sizes to scale factors.

3 Color support

\__driver_color_ensure_current: \__driver_color_ensure_current:
New: 2011-09-03
Updated: 2012-05-18

Ensures that the color used to typeset material is that which was set when the material
was placed in a box. This function is therefore required inside any “color safe” box to
ensure that the box may be inserted in a location where the foreground color has been
altered, while preserving the color used in the box.

206
Index
The italic numbers denote the pages where the corresponding entry is described, numbers
underlined point to the definition, all others indicate the places where it is used.

Symbols \__msg_kernel_new:nnnn . . . . . . . . . . 152

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 \__msg_kernel_set:nnnn . . . . . . . . . . 152
** . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 \__msg_kernel_warning:nnnnnn . . . . . 153
?: . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 \__msg_show_item:n . . . . . . . . . . . . . . 154
\::: . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__msg_show_item_unbraced:nn . . . . . 154
\::N . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__msg_show_variable:Nnn . . . . . . . . . 154
\::V . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__msg_show_variable:n . . . . . . . . . . 154
\::c . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__msg_term:nnnnnn . . . . . . . . . . . . . . 154
\::f . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__my_map_dbl:nn . . . . . . . . . . . . 4, 6, 11
\::n . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__my_map_dbl_fn:nn . . . . . . . . . . . . 3, 10
\::o . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__prg_break: . . . . . . . . . . . . . . . . . . . 42
\::p . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__prg_break_point: . . . . . . . . . . . . . . 42
\::v . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__prg_break_point:Nn . . . . . . . . . . . . 42
\::x . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 \__prg_case_end:nw . . . . . . . . . . . . . . . 25
\@@_if_eq_x_return:nn . . . . . . . . . . . 106 \__prg_compare_error: . . . . . . . . . . . . 74
\__chk_if_exist_cs:N . . . . . . . . . . . . . 24 \__prg_map_break:Nn . . . . . . . . . . . . . . 42
\__chk_if_exist_var:N . . . . . . . . . . . . 24 \__prg_variable_get_scope:N . . . . . . . 41
\__chk_if_free_cs:N . . . . . . . . . . . . . . 24 \__prg_variable_get_type:N . . . . . . . . 41
\__cs_count_signature:N . . . . . . . . . . 25 \__prop_pair:wn . . . . . . . . . . . . . . . . 132
\__cs_get_function_name:N . . . . . . . . . 25 \__prop_split:NnTF . . . . . . . . . . . . . . 132
\__cs_get_function_signature:N . . . . 25 \__quark_if_recursion_tail_break:NN 46
\__cs_split_function:NN . . . . . . . . . . 25 \__scan_new:N . . . . . . . . . . . . . . . . . . . 47
\__cs_tmp:w . . . . . . . . . . . . . . . . . . . . . 25 \__seq_item:n . . . . . . . . . . . . . . . . . . 116
\__dim_eval:w . . . . . . . . . . . . . . . . . . . 89 \__seq_pop_item_def: . . . . . . . . . . . . 116
\__dim_eval_end: . . . . . . . . . . . . . . . . 89 \__seq_push_item_def:n . . . . . . . . . . 116
\__driver_box_rotate_begin: . . . . . . 206 \__str_if_eq_x:nn . . . . . . . . . . . . . . 106
\__driver_box_rotate_end: . . . . . . . . 206 \__tl_trim_spaces:nn . . . . . . . . . . . . 103
\__driver_box_scale_begin: . . . . . . . 206 \__use_none_delimit_by_s__stop:w . . . 47
\__driver_box_scale_end: . . . . . . . . . 206
\__driver_box_use_clip:N . . . . . . . . . 205 A
\__driver_color_ensure_current: . . . 206 false . . . . . . . . . . . .. . . . . . . . . . . . . 191
\__file_name_sanitize:nn . . . . . . . . . 174 nan . . . . . . . . . . . . .. . . . . . . . . . . . . 190
\__int_eval:w . . . . . . . . . . . . . . . . . . . 74 tan . . . . . . . . . . . . .. . . . . . . . . . . . . 188
\__int_eval_end: . . . . . . . . . . . . . . . . 74 tand . . . . . . . . . . . . .. . . . . . . . . . . . . 189
\__int_to_roman:w . . . . . . . . . . . . . . . 73 max . . . . . . . . . . . . .. . . . . . . . . . . . . 188
\__int_value:w . . . . . . . . . . . . . . . . . . 74
\__ior_open:Nn . . . . . . . . . . . . . . . . . 175 B
\__kernel_register_show:N . . . . . . . . . 25 \bool_do_until:Nn .. . . . . . . . . . . . . . 39
\__msg_expandable_error:n . . . . . . . . 154 \bool_do_until:nn .. . . . . . . . . . . . . . 39
\__msg_kernel_error:nnnnnn . . . . . . . 153 \bool_do_while:Nn .. . . . . . . . . . . . . . 39
\__msg_kernel_expandable_error:nnnnnn \bool_do_while:nn .. . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . . . . . . . 153 .bool_gset:c . . . . ... . . . . . . . . . . . . 158
\__msg_kernel_fatal:nnnnnn . . . . . . . 153 .bool_gset:N . . . . ... . . . . . . . . . . . . 158
\__msg_kernel_info:nnnnnn . . . . . . . . 153 \bool_gset:Nn . . . ... . . . . . . . . . . . . . 37

207
\bool_gset_eq:NN . . . . . . . . . . . . . . . . 37 \box_move_right:nn . . . . . . . . . . . . . . 134
\bool_gset_false:N . . . . . . . . . . . . . . . 36 \box_move_up:nn . . . . . . . . . . . . . . . . 134
.bool_gset_inverse:c . . . . . . . . . . . . 158 \box_new:N . . . . . . . . . . . . . . . . . . . . 133
.bool_gset_inverse:N . . . . . . . . . . . . 158 \box_resize:Nnn . . . . . . . . . . . . . . . . 195
\bool_gset_true:N . . . . . . . . . . . . . . . 37 \box_resize_to_ht:Nn . . . . . . . . . . . . 195
\bool_if:NTF . . . . . . . . . . . . . . . . . . . . 37 \box_resize_to_ht_plus_dp:Nn . . . . . 195
\bool_if:nTF . . . . . . . . . . . . . . . . . . . . 38 \box_resize_to_wd:Nn . . . . . . . . . . . . 195
\bool_if_exist:NTF . . . . . . . . . . . . . . . 37 \box_resize_to_wd_and_ht:Nnn . . . . . 196
\bool_if_exist_p:N . . . . . . . . . . . . . . . 37 \box_rotate:Nn . . . . . . . . . . . . . . . . . 196
\bool_if_p:N . . . . . . . . . . . . . . . . . . . . 37 \box_scale:Nnn . . . . . . . . . . . . . . . . . 196
\bool_if_p:n . . . . . . . . . . . . . . . . . . . . 38 \box_set_dp:Nn . . . . . . . . . . . . . . . . . 135
\bool_new:N . . . . . . . . . . . . . . . . . . . . . 36 \box_set_eq:NN . . . . . . . . . . . . . . . . . 133
\bool_not_p:n . . . . . . . . . . . . . . . . . . . 39 \box_set_eq_clear:NN . . . . . . . . . . . . 133
.bool_set:c . . . . . . . . . . . . . . . . . . . . 158 \box_set_ht:Nn . . . . . . . . . . . . . . . . . 135
.bool_set:N . . . . . . . . . . . . . . . . . . . . 158 \box_set_to_last:N . . . . . . . . . . . . . . 136
\bool_set:Nn . . . . . . . . . . . . . . . . . . . . 37 \box_set_wd:Nn . . . . . . . . . . . . . . . . . 135
\bool_set_eq:NN . . . . . . . . . . . . . . . . . 37 \box_show:N . . . . . . . . . . . . . . . . . . . . 136
\bool_set_false:N . . . . . . . . . . . . . . . 36 \box_show:Nnn . . . . . . . . . . . . . . . . . . 136
.bool_set_inverse:c . . . . . . . . . . . . . 158 \box_trim:Nnnnn . . . . . . . . . . . . . . . . 197
.bool_set_inverse:N . . . . . . . . . . . . . 158 \box_use:N . . . . . . . . . . . . . . . . . . . . 134
\bool_set_true:N . . . . . . . . . . . . . . . . 37 \box_use_clear:N . . . . . . . . . . . . . . . 134
\bool_show:N . . . . . . . . . . . . . . . . . . . . 37 \box_viewport:Nnnnn . . . . . . . . . . . . . 197
\bool_show:n . . . . . . . . . . . . . . . . . . . . 37 \box_wd:N . . . . . . . . . . . . . . . . . . . . . 135
\bool_until_do:Nn . . . . . . . . . . . . . . . 39 abs . . . . . . . . . . . . . . . . . . . . . . . . . . 187
\bool_until_do:nn . . . . . . . . . . . . . . . 40
\bool_while_do:Nn . . . . . . . . . . . . . . . 39 C
\bool_while_do:nn . . . . . . . . . . . . . . . 40 cc . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\bool_xor_p:nn . . . . . . . . . . . . . . . . . . 39 nc . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\box_clear:N . . . . . . . . . . . . . . . . . . . 133 pc . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\box_clear_new:N . . . . . . . . . . . . . . . 133 \c__msg_coding_error_text_tl . . . . . 155
\box_clip:N . . . . . . . . . . . . . . . . . . . . 196 \c_alignment_token . . . . . . . . . . . . . . . 52
\box_dp:N . . . . . . . . . . . . . . . . . . . . . 134 \c_catcode_active_tl . . . . . . . . . . . . . 52
\box_gclear:N . . . . . . . . . . . . . . . . . . 133 \c_catcode_letter_token . . . . . . . . . . 52
\box_gclear_new:N . . . . . . . . . . . . . . 133 \c_catcode_other_space_tl . . . . . . . . 174
\box_gset_eq:NN . . . . . . . . . . . . . . . . 133 \c_catcode_other_token . . . . . . . . . . . 52
\box_gset_eq_clear:NN . . . . . . . . . . . 133 \c_e_fp . . . . . . . . . . . . . . . . . . . . . . . 182
\box_gset_to_last:N . . . . . . . . . . . . . 136 \c_eight . . . . . . . . . . . . . . . . . . . . . . . 72
\box_ht:N . . . . . . . . . . . . . . . . . . . . . 135 \c_eleven . . . . . . . . . . . . . . . . . . . . . . 72
\box_if_empty:NTF . . . . . . . . . . . . . . 135 \c_empty_box . . . . . . . . . . . . . . . . . . . 136
\box_if_empty_p:N . . . . . . . . . . . . . . 135 \c_empty_clist . . . . . . . . . . . . . . . . . 125
\box_if_exist:NTF . . . . . . . . . . . . . . 134 \c_empty_coffin . . . . . . . . . . . . . . . . 144
\box_if_exist_p:N . . . . . . . . . . . . . . 134 \c_empty_prop . . . . . . . . . . . . . . . . . . 132
\box_if_horizontal:NTF . . . . . . . . . . 135 \c_empty_seq . . . . . . . . . . . . . . . . . . . 116
\box_if_horizontal_p:N . . . . . . . . . . 135 \c_empty_tl . . . . . . . . . . . . . . . . . . . . 103
\box_if_vertical:NTF . . . . . . . . . . . . 135 \c_false_bool . . . . . . . . . . . . . . . . . . . 22
\box_if_vertical_p:N . . . . . . . . . . . . 135 \c_fifteen . . . . . . . . . . . . . . . . . . . . . 72
\box_log:N . . . . . . . . . . . . . . . . . . . . 136 \c_five . . . . . . . . . . . . . . . . . . . . . . . . 72
\box_log:Nnn . . . . . . . . . . . . . . . . . . . 137 \c_four . . . . . . . . . . . . . . . . . . . . . . . . 72
\box_move_down:nn . . . . . . . . . . . . . . 134 \c_fourteen . . . . . . . . . . . . . . . . . . . . . 72
\box_move_left:nn . . . . . . . . . . . . . . 134 \c_group_begin_token . . . . . . . . . . . . . 52

208
\c_group_end_token . . . . . . . . . . . . . . . 52 \char_set_catcode_active:N . . . . . . . . 49
\c_inf_fp . . . . . . . . . . . . . . . . . . . . . 182 \char_set_catcode_active:n . . . . . . . . 49
\c_job_name_tl . . . . . . . . . . . . . . . . . 103 \char_set_catcode_alignment:N . . . . . 49
\c_log_iow . . . . . . . . . . . . . . . . . . . . 174 \char_set_catcode_alignment:n . . . . . 49
\c_math_subscript_token . . . . . . . . . . 52 \char_set_catcode_comment:N . . . . . . . 49
\c_math_superscript_token . . . . . . . . . 52 \char_set_catcode_comment:n . . . . . . . 49
\c_math_toggle_token . . . . . . . . . . . . . 52 \char_set_catcode_end_line:N . . . . . . 49
\c_max_dim . . . . . . . . . . . . . . . . . . . . . 82 \char_set_catcode_end_line:n . . . . . . 49
\c_max_int . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_escape:N . . . . . . . . 49
\c_max_muskip . . . . . . . . . . . . . . . . . . . 88 \char_set_catcode_escape:n . . . . . . . . 49
\c_max_register_int . . . . . . . . . . . . . . 72 \char_set_catcode_group_begin:N . . . . 49
\c_max_skip . . . . . . . . . . . . . . . . . . . . . 85 \char_set_catcode_group_begin:n . . . . 49
\c_minus_inf_fp . . . . . . . . . . . . . . . . 182 \char_set_catcode_group_end:N . . . . . 49
\c_minus_one . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_group_end:n . . . . . 49
\c_minus_zero_fp . . . . . . . . . . . . . . . 182 \char_set_catcode_ignore:N . . . . . . . . 49
\c_nine . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_ignore:n . . . . . . . . 49
\c_one . . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_invalid:N . . . . . . . 49
\c_one_degree_fp . . . . . . . . . . . . . . . 182 \char_set_catcode_invalid:n . . . . . . . 49
\c_one_fp . . . . . . . . . . . . . . . . . . . . . 182 \char_set_catcode_letter:N . . . . . . . . 49
\c_one_hundred . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_letter:n . . . . . . . . 49
\c_one_thousand . . . . . . . . . . . . . . . . . 72 \char_set_catcode_math_subscript:N . 49
\c_parameter_token . . . . . . . . . . . . . . . 52 \char_set_catcode_math_subscript:n . 49
\c_pi_fp . . . . . . . . . . . . . . . . . . . . . . 182 \char_set_catcode_math_superscript:N 49
\c_seven . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_math_superscript:n 49
\c_six . . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_math_toggle:N . . . . 49
\c_sixteen . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_math_toggle:n . . . . 49
\c_space_tl . . . . . . . . . . . . . . . . . . . . 103 \char_set_catcode_other:N . . . . . . . . . 49
\c_space_token . . . . . . . . . . . . . . . . . . 52 \char_set_catcode_other:n . . . . . . . . . 49
\c_ten . . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_catcode_parameter:N . . . . . 49
\c_ten_thousand . . . . . . . . . . . . . . . . . 72 \char_set_catcode_parameter:n . . . . . 49
\c_term_ior . . . . . . . . . . . . . . . . . . . . 174 \char_set_catcode_space:N . . . . . . . . . 49
\c_term_iow . . . . . . . . . . . . . . . . . . . . 174 \char_set_catcode_space:n . . . . . . . . . 49
\c_thirteen . . . . . . . . . . . . . . . . . . . . . 72 \char_set_lccode:nn . . . . . . . . . . . . . . 50
\c_thirty_two . . . . . . . . . . . . . . . . . . . 72 \char_set_mathcode:nn . . . . . . . . . . . . 51
\c_three . . . . . . . . . . . . . . . . . . . . . . . 72 \char_set_sfcode:nn . . . . . . . . . . . . . . 51
\c_true_bool . . . . . . . . . . . . . . . . . . . . 22 \char_set_uccode:nn . . . . . . . . . . . . . . 51
\c_twelve . . . . . . . . . . . . . . . . . . . . . . 72 \char_show_value_catcode:n . . . . . . . . 50
\c_two . . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_show_value_lccode:n . . . . . . . . . 50
\c_two_hundred_fifty_five . . . . . . . . . 72 \char_show_value_mathcode:n . . . . . . . 51
\c_two_hundred_fifty_six . . . . . . . . . . 72 \char_show_value_sfcode:n . . . . . . . . . 52
\c_zero . . . . . . . . . . . . . . . . . . . . . . . . 72 \char_show_value_uccode:n . . . . . . . . . 51
\c_zero_dim . . . . . . . . . . . . . . . . . . . . . 82 \char_value_catcode:n . . . . . . . . . . . . 50
\c_zero_fp . . . . . . . . . . . . . . . . . . . . 182 \char_value_lccode:n . . . . . . . . . . . . . 50
\c_zero_muskip . . . . . . . . . . . . . . . . . . 88 \char_value_mathcode:n . . . . . . . . . . . 51
\c_zero_skip . . . . . . . . . . . . . . . . . . . . 85 \char_value_sfcode:n . . . . . . . . . . . . . 51
\char_gset_active:Npn . . . . . . . . . . . 204 \char_value_uccode:n . . . . . . . . . . . . . 51
\char_gset_active_eq:NN . . . . . . . . . 204 .choice: . . . . . . . . . . . . . . . . . . . . . . 158
\char_set_active:Npn . . . . . . . . . . . . 204 .choices:nn . . . . . . . . . . . . . . . . . . . . 158
\char_set_active_eq:NN . . . . . . . . . . 204 .choices:on . . . . . . . . . . . . . . . . . . . . 158
\char_set_catcode:nn . . . . . . . . . . . . . 50 .choices:Vn . . . . . . . . . . . . . . . . . . . . 158

209
.choices:xn . . . . . . . . . . . . . . . . . . . . 158 \clist_set_eq:NN . . . . . . . . . . . . . . . 118
\clist_clear:N . . . . . . . . . . . . . . . . . 117 \clist_set_from_seq:NN . . . . . . . . . . 118
\clist_clear_new:N . . . . . . . . . . . . . . 118 \clist_show:N . . . . . . . . . . . . . . . . . . 125
\clist_concat:NNN . . . . . . . . . . . . . . 118 \clist_show:n . . . . . . . . . . . . . . . . . . 125
\clist_const:Nn . . . . . . . . . . . . . . . . 117 \clist_use:Nn . . . . . . . . . . . . . . . . . . 123
\clist_count:N . . . . . . . . . . . . . . . . . 122 \clist_use:Nnnn . . . . . . . . . . . . . . . . 123
\clist_gclear:N . . . . . . . . . . . . . . . . 117 .code:n . . . . . . . . . . . . . . . . . . . . . . . 158
\clist_gclear_new:N . . . . . . . . . . . . . 118 \coffin_attach:NnnNnnnn . . . . . . . . . 143
\clist_gconcat:NNN . . . . . . . . . . . . . . 118 \coffin_clear:N . . . . . . . . . . . . . . . . 141
\clist_get:NN . . . . . . . . . . . . . . . . . . 124 \coffin_display_handles:Nn . . . . . . . 144
\clist_get:NNTF . . . . . . . . . . . . . . . . 124 \coffin_dp:N . . . . . . . . . . . . . . . . . . . 143
\clist_gpop:NN . . . . . . . . . . . . . . . . . 124 \coffin_ht:N . . . . . . . . . . . . . . . . . . . 144
\clist_gpop:NNTF . . . . . . . . . . . . . . . 124 \coffin_if_exist:NTF . . . . . . . . . . . . 141
\clist_gpush:Nn . . . . . . . . . . . . . . . . 125 \coffin_if_exist_p:N . . . . . . . . . . . . 141
\clist_gput_left:Nn . . . . . . . . . . . . . 119 \coffin_join:NnnNnnnn . . . . . . . . . . . 143
\clist_gput_right:Nn . . . . . . . . . . . . 119 \coffin_mark_handle:Nnnn . . . . . . . . . 144
\clist_gremove_all:Nn . . . . . . . . . . . 119 \coffin_new:N . . . . . . . . . . . . . . . . . . 141
\clist_gremove_duplicates:N . . . . . . 119 \coffin_resize:Nnn . . . . . . . . . . . . . . 197
\clist_greverse:N . . . . . . . . . . . . . . 120 \coffin_rotate:Nn . . . . . . . . . . . . . . 198
.clist_gset:c . . . . . . . . . . . . . . . . . . 158 \coffin_scale:Nnn . . . . . . . . . . . . . . 198
.clist_gset:N . . . . . . . . . . . . . . . . . . 158 \coffin_set_eq:NN . . . . . . . . . . . . . . 141
\clist_gset:Nn . . . . . . . . . . . . . . . . . 118 \coffin_set_horizontal_pole:Nnn . . . 142
\clist_gset_eq:NN . . . . . . . . . . . . . . 118 \coffin_set_vertical_pole:Nnn . . . . 142
\clist_gset_from_seq:NN . . . . . . . . . 118 \coffin_show_structure:N . . . . . . . . . 144
\clist_if_empty:NTF . . . . . . . . . . . . . 120 \coffin_typeset:Nnnnn . . . . . . . . . . . 143
\clist_if_empty:nTF . . . . . . . . . . . . . 120 \coffin_wd:N . . . . . . . . . . . . . . . . . . . 144
\clist_if_empty_p:N . . . . . . . . . . . . . 120 \color_ensure_current: . . . . . . . . . . 145
\clist_if_empty_p:n . . . . . . . . . . . . . 120 \color_group_begin: . . . . . . . . . . . . . 145
\clist_if_exist:NTF . . . . . . . . . . . . . 118 \color_group_end: . . . . . . . . . . . . . . 145
\clist_if_exist_p:N . . . . . . . . . . . . . 118 acos . . . . . . . . . . . . . . . . . . . . . . . . . . 189
\clist_if_in:NnTF . . . . . . . . . . . . . . 120 acosd . . . . . . . . . . . . . . . . . . . . . . . . . 189
\clist_item:Nn . . . . . . . . . . . . . . . . . 125 acot . . . . . . . . . . . . . . . . . . . . . . . . . . 190
\clist_map_break: . . . . . . . . . . . . . . 122 acotd . . . . . . . . . . . . . . . . . . . . . . . . . 190
\clist_map_break:n . . . . . . . . . . . . . . 122 \cs:w . . . . . . . . . . . . . . . . . . . . . . . . . . 18
\clist_map_function:NN . . . . . . . . . . 121 \cs_end: . . . . . . . . . . . . . . . . . . . . . . . 18
\clist_map_inline:Nn . . . . . . . . . . . . 121 \cs_generate_from_arg_count:NNnn . . . 16
\clist_map_variable:NNn . . . . . . . . . 121 \cs_generate_variant:Nn . . . . . . . . . . 27
\clist_new:N . . . . . . . . . . . . . . . . . . . 117 \cs_gset:Nn . . . . . . . . . . . . . . . . . . . . . 15
\clist_pop:NN . . . . . . . . . . . . . . . . . . 124 \cs_gset:Npn . . . . . . . . . . . . . . . . . . . . 13
\clist_pop:NNTF . . . . . . . . . . . . . . . . 124 \cs_gset_eq:NN . . . . . . . . . . . . . . . . . . 17
\clist_push:Nn . . . . . . . . . . . . . . . . . 125 \cs_gset_nopar:Nn . . . . . . . . . . . . . . . 15
\clist_put_left:Nn . . . . . . . . . . . . . . 119 \cs_gset_nopar:Npn . . . . . . . . . . . . . . . 13
\clist_put_right:Nn . . . . . . . . . . . . . 119 \cs_gset_protected:Nn . . . . . . . . . . . . 16
\clist_remove_all:Nn . . . . . . . . . . . . 119 \cs_gset_protected:Npn . . . . . . . . . . . 13
\clist_remove_duplicates:N . . . . . . . 119 \cs_gset_protected_nopar:Nn . . . . . . . 16
\clist_reverse:N . . . . . . . . . . . . . . . 120 \cs_gset_protected_nopar:Npn . . . . . . 14
\clist_reverse:n . . . . . . . . . . . . . . . 120 \cs_if_eq:NNTF . . . . . . . . . . . . . . . . . . 22
.clist_set:c . . . . . . . . . . . . . . . . . . . 158 \cs_if_eq_p:NN . . . . . . . . . . . . . . . . . . 22
.clist_set:N . . . . . . . . . . . . . . . . . . . 158 \cs_if_exist:NTF . . . . . . . . . . . . . . . . 22
\clist_set:Nn . . . . . . . . . . . . . . . . . . 118 \cs_if_exist_p:N . . . . . . . . . . . . . . . . 22

210
\cs_if_exist_use:N . . . . . . . . . . . . . . . 18 .dim_gset:c . . . . . . . . . . . . . . . . . . . . 159
\cs_if_exist_use:NTF . . . . . . . . . . . . . 18 .dim_gset:N . . . . . . . . . . . . . . . . . . . . 159
\cs_if_free:NTF . . . . . . . . . . . . . . . . . 23 \dim_gset:Nn . . . . . . . . . . . . . . . . . . . . 76
\cs_if_free_p:N . . . . . . . . . . . . . . . . . 23 \dim_gset_eq:NN . . . . . . . . . . . . . . . . . 76
\cs_meaning:N . . . . . . . . . . . . . . . . . . . 17 \dim_gsub:Nn . . . . . . . . . . . . . . . . . . . . 76
\cs_new:Nn . . . . . . . . . . . . . . . . . . . 6, 14 \dim_gzero:N . . . . . . . . . . . . . . . . . . . . 75
\cs_new:Npn . . . . . . . . . . . . . . . . . . . 1, 12 \dim_gzero_new:N . . . . . . . . . . . . . . . . 75
\cs_new_eq:NN . . . . . . . . . . . . . . . . . . . 16 \dim_if_exist:NTF . . . . . . . . . . . . . . . 75
\cs_new_nopar:Nn . . . . . . . . . . . . . . . . 14 \dim_if_exist_p:N . . . . . . . . . . . . . . . 75
\cs_new_nopar:Npn . . . . . . . . . . . . . . . 12 \dim_max:nn . . . . . . . . . . . . . . . . . . . . . 76
\cs_new_protected:Nn . . . . . . . . . . . . . 14 \dim_min:nn . . . . . . . . . . . . . . . . . . . . . 76
\cs_new_protected:Npn . . . . . . . . . . . . 12 \dim_new:N . . . . . . . . . . . . . . . . . . . . . 75
\cs_new_protected_nopar:Nn . . . . . . . . 14 \dim_ratio:nn . . . . . . . . . . . . . . . . . . . 77
\cs_new_protected_nopar:Npn . . . . . . . 12 .dim_set:c . . . . . . . . . . . . . . . . . . . . 159
\cs_set:Nn . . . . . . . . . . . . . . . . . . . . . 15 .dim_set:N . . . . . . . . . . . . . . . . . . . . 159
\cs_set:Npn . . . . . . . . . . . . . . . . . . . 3, 12 \dim_set:Nn . . . . . . . . . . . . . . . . . . . . . 76
\cs_set_eq:NN . . . . . . . . . . . . . . . . . . . 17 \dim_set_eq:NN . . . . . . . . . . . . . . . . . . 76
\cs_set_nopar:Nn . . . . . . . . . . . . . . . . 15 \dim_show:N . . . . . . . . . . . . . . . . . . . . . 82
\cs_set_nopar:Npn . . . . . . . . . . . . . . . 13 \dim_show:n . . . . . . . . . . . . . . . . . . . . . 82
\cs_set_protected:Nn . . . . . . . . . . . . . 15 \dim_sub:Nn . . . . . . . . . . . . . . . . . . . . . 76
\cs_set_protected:Npn . . . . . . . . . . . . 13 \dim_to_decimal:n . . . . . . . . . . . . . . . 81
\cs_set_protected_nopar:Nn . . . . . . . . 15 \dim_to_decimal_in_bp:n . . . . . . . . . . 81
\cs_set_protected_nopar:Npn . . . . . . . 13 \dim_to_decimal_in_unit:nn . . . . . . . . 81
\cs_show:N . . . . . . . . . . . . . . . . . . . . . 17 \dim_to_fp:n . . . . . . . . . . . . . . . . . . . . 82
\cs_to_str:N . . . . . . . . . . . . . . . . . . 4, 19 \dim_until_do:nn . . . . . . . . . . . . . . . . 80
\cs_undefine:N . . . . . . . . . . . . . . . . . . 17 \dim_until_do:nNnn . . . . . . . . . . . . . . . 80
acsc . . . . . . . . . . . . . . . . . . . . . . . . . . 189 \dim_use:N . . . . . . . . . . . . . . . . . . . . . 81
acscd . . . . . . . . . . . . . . . . . . . . . . . . . 189 \dim_while_do:nn . . . . . . . . . . . . . . . . 80
\dim_while_do:nNnn . . . . . . . . . . . . . . . 80
D \dim_zero:N . . . . . . . . . . . . . . . . . . . . . 75
dd . . . . . . . . . . . . . .. . . . . . . . . . . . . 191 \dim_zero_new:N . . . . . . . . . . . . . . . . . 75
nd . . . . . . . . . . . . . .. . . . . . . . . . . . . 191
.default:n . . . . . . .. . . . . . . . . . . . . 159 E
.default:o . . . . . . .. . . . . . . . . . . . . 159 sec . . . . . . . . . . . . .. . . . . . . . . . . . . 188
.default:V . . . . . . .. . . . . . . . . . . . . 159 secd . . . . . . . . . . . . .. . . . . . . . . . . . . 189
.default:x . . . . . . .. . . . . . . . . . . . . 159 deg . . . . . . . . . . . . .. . . . . . . . . . . . . 190
\dim_abs:n . . . . . . .. . . . . . . . . . . . . . 76 ceil . . . . . . . . . . . . .. . . . . . . . . . . . . 188
\dim_add:Nn . . . . . . .. . . . . . . . . . . . . . 76 \else: . . . . . . . . . . .. . . . . . . . . . . . . . 23
\dim_case:nnTF . . . .. . . . . . . . . . . . . . 79 \exp_after:wN . . . . .. . . . . . . . . . . . . . 31
\dim_compare:nNnTF .. . . . . . . . . . . . . . 77 \exp_args:Nc . . . . . .. . . . . . . . . . . . . . 28
\dim_compare:nTF . .. . . . . . . . . . . . . . 78 \exp_args:Nf . . . . . .. . . . . . . . . . . . . . 29
\dim_compare_p:n . .. . . . . . . . . . . . . . 78 \exp_args:NNNo . . . .. . . . . . . . . . . . . . 30
\dim_compare_p:nNn .. . . . . . . . . . . . . . 77 \exp_args:NNnx . . . .. . . . . . . . . . . . . . 30
\dim_const:Nn . . . . .. . . . . . . . . . . . . . 75 \exp_args:NNo . . . . .. . . . . . . . . . . . . . 29
\dim_do_until:nn . .. . . . . . . . . . . . . . 80 \exp_args:Nno . . . . .. . . . . . . . . . . . . . 29
\dim_do_until:nNnn .. . . . . . . . . . . . . . 79 \exp_args:NNoo . . . .. . . . . . . . . . . . . . 30
\dim_do_while:nn . .. . . . . . . . . . . . . . 80 \exp_args:NNx . . . . .. . . . . . . . . . . . . . 30
\dim_do_while:nNnn .. . . . . . . . . . . . . . 79 \exp_args:No . . . . . .. . . . . . . . . . . . . . 28
\dim_eval:n . . . . . . .. . . . . . . . . . . . . . 80 \exp_args:NV . . . . . .. . . . . . . . . . . . . . 29
\dim_gadd:Nn . . . . . .. . . . . . . . . . . . . . 76 \exp_args:Nv . . . . . .. . . . . . . . . . . . . . 29

211
\exp_args:Nx . . . . . . . . . . . . . . . . . . . . 29 \fp_max:nn . . . . . . . . . . . . . . . . . . . . 191
\exp_last_two_unbraced:Noo . . . . . . . . 31 \fp_min:nn . . . . . . . . . . . . . . . . . . . . 191
\exp_last_unbraced:Nf . . . . . . . . . . . . 31 \fp_new:N . . . . . . . . . . . . . . . . . . . . . 177
\exp_last_unbraced:Nx . . . . . . . . . . . . 31 .fp_set:c . . . . . . . . . . . . . . . . . . . . . 159
\exp_not:c . . . . . . . . . . . . . . . . . . . . . 32 .fp_set:N . . . . . . . . . . . . . . . . . . . . . 159
\exp_not:f . . . . . . . . . . . . . . . . . . . . . 32 \fp_set:Nn . . . . . . . . . . . . . . . . . . . . 177
\exp_not:N . . . . . . . . . . . . . . . . . . . . . 32 \fp_set_eq:NN . . . . . . . . . . . . . . . . . . 178
\exp_not:n . . . . . . . . . . . . . . . . . . . . . 32 \fp_show:N . . . . . . . . . . . . . . . . . . . . 184
\exp_not:o . . . . . . . . . . . . . . . . . . . . . 32 \fp_sub:Nn . . . . . . . . . . . . . . . . . . . . 178
\exp_not:V . . . . . . . . . . . . . . . . . . . . . 32 \fp_to_decimal:N . . . . . . . . . . . . . . . 178
\exp_not:v . . . . . . . . . . . . . . . . . . . . . 32 \fp_to_dim:N . . . . . . . . . . . . . . . . . . . 178
\exp_stop_f: . . . . . . . . . . . . . . . . . . . . 32 \fp_to_int:N . . . . . . . . . . . . . . . . . . . 179
\ExplSyntaxOff . . . . . . . . . . . . . . . . . 4, 7 \fp_to_scientific:N . . . . . . . . . . . . . 179
\ExplSyntaxOn . . . . . . . . . . . . . . . . . . 4, 7 \fp_to_tl:N . . . . . . . . . . . . . . . . . . . . 179
\fp_trap:nn . . . . . . . . . . . . . . . . . . . . 184
F \fp_until_do:nn . . . . . . . . . . . . . . . . 181
\fi: . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 \fp_until_do:nNnn . . . . . . . . . . . . . . 181
\file_add_path:nN . . . . . . . . . . . . . . 168 \fp_use:N . . . . . . . . . . . . . . . . . . . . . 179
\file_if_exist:nTF . . . . . . . . . . . . . . 168 \fp_while_do:nn . . . . . . . . . . . . . . . . 182
\file_if_exist_input:nTF . . . . . . . . . 198 \fp_while_do:nNnn . . . . . . . . . . . . . . 181
\file_input:n . . . . . . . . . . . . . . . . . . 168 \fp_zero:N . . . . . . . . . . . . . . . . . . . . 177
\file_list: . . . . . . . . . . . . . . . . . . . . 169 \fp_zero_new:N . . . . . . . . . . . . . . . . . 177
\file_path_include:n . . . . . . . . . . . . 169
\file_path_remove:n . . . . . . . . . . . . . 169 G
\fp_abs:n . . . . . . . . . . . . . . . . . . . . . 191 \g__file_internal_ior . ... . . . . . . . 174
\fp_add:Nn . . . . . . . . . . . . . . . . . . . . 178 \g__prg_map_int . . . . . . ... . . . . . . . . 42
\fp_compare:nNnTF . . . . . . . . . . . . . . 180 \g_file_current_name_tl .. . . . . . . . 168
\fp_compare:nTF . . . . . . . . . . . . . . . . 180 \g_peek_token . . . . . . . . ... . . . . . . . . 57
\fp_compare_p:n . . . . . . . . . . . . . . . . 180 \g_tmpa_bool . . . . . . . . . ... . . . . . . . . 37
\fp_compare_p:nNn . . . . . . . . . . . . . . 180 \g_tmpa_box . . . . . . . . . . ... . . . . . . . 136
\fp_const:Nn . . . . . . . . . . . . . . . . . . . 177 \g_tmpa_clist . . . . . . . . ... . . . . . . . 126
\fp_do_until:nn . . . . . . . . . . . . . . . . 181 \g_tmpa_dim . . . . . . . . . . ... . . . . . . . . 82
\fp_do_until:nNnn . . . . . . . . . . . . . . 181 \g_tmpa_fp . . . . . . . . . . ... . . . . . . . 182
\fp_do_while:nn . . . . . . . . . . . . . . . . 181 \g_tmpa_int . . . . . . . . . . ... . . . . . . . . 72
\fp_do_while:nNnn . . . . . . . . . . . . . . 181 \g_tmpa_muskip . . . . . . . ... . . . . . . . . 88
\fp_eval:n . . . . . . . . . . . . . . . . . . . . 178 \g_tmpa_prop . . . . . . . . . ... . . . . . . . 132
\fp_flag_off:n . . . . . . . . . . . . . . . . . 183 \g_tmpa_seq . . . . . . . . . . ... . . . . . . . 116
\fp_flag_on:n . . . . . . . . . . . . . . . . . . 183 \g_tmpa_skip . . . . . . . . . ... . . . . . . . . 85
\fp_gadd:Nn . . . . . . . . . . . . . . . . . . . . 178 \g_tmpa_tl . . . . . . . . . . ... . . . . . . . 103
.fp_gset:c . . . . . . . . . . . . . . . . . . . . 159 \g_tmpb_bool . . . . . . . . . ... . . . . . . . . 37
.fp_gset:N . . . . . . . . . . . . . . . . . . . . 159 \g_tmpb_box . . . . . . . . . . ... . . . . . . . 136
\fp_gset:Nn . . . . . . . . . . . . . . . . . . . . 177 \g_tmpb_clist . . . . . . . . ... . . . . . . . 126
\fp_gset_eq:NN . . . . . . . . . . . . . . . . . 178 \g_tmpb_dim . . . . . . . . . . ... . . . . . . . . 82
\fp_gsub:Nn . . . . . . . . . . . . . . . . . . . . 178 \g_tmpb_fp . . . . . . . . . . ... . . . . . . . 182
\fp_gzero:N . . . . . . . . . . . . . . . . . . . . 177 \g_tmpb_int . . . . . . . . . . ... . . . . . . . . 72
\fp_gzero_new:N . . . . . . . . . . . . . . . . 177 \g_tmpb_muskip . . . . . . . ... . . . . . . . . 88
\fp_if_exist:NTF . . . . . . . . . . . . . . . 179 \g_tmpb_prop . . . . . . . . . ... . . . . . . . 132
\fp_if_exist_p:N . . . . . . . . . . . . . . . 179 \g_tmpb_seq . . . . . . . . . . ... . . . . . . . 116
\fp_if_flag_on:nTF . . . . . . . . . . . . . . 183 \g_tmpb_skip . . . . . . . . . ... . . . . . . . . 85
\fp_if_flag_on_p:n . . . . . . . . . . . . . . 183 \g_tmpb_tl . . . . . . . . . . ... . . . . . . . 103

212
\GetIdInfo . . . . . . . . . . . . . . . . . . . . . . 7 \if_vbox:N . . . . . . . . . . . . . . . . . . . . 140
\group_align_safe_begin: . . . . . . . . . . 41 min . . . . . . . . . . . . . . . . . . . . . . . . . . 188
\group_align_safe_end: . . . . . . . . . . . 41 sin . . . . . . . . . . . . . . . . . . . . . . . . . . 188
\group_begin: . . . . . . . . . . . . . . . . . . . 10 sind . . . . . . . . . . . . . . . . . . . . . . . . . . 189
\group_end: . . . . . . . . . . . . . . . . . . . . . 10 .initial:n . . . . . . . . . . . . . . . . . . . . 159
\group_insert_after:N . . . . . . . . . . . . 10 .initial:o . . . . . . . . . . . . . . . . . . . . 159
.groups:n . . . . . . . . . . . . . . . . . . . . . 159 .initial:V . . . . . . . . . . . . . . . . . . . . 159
.initial:x . . . . . . . . . . . . . . . . . . . . 159
H \int_abs:n . . . . . . . . . . . . . . . . . . . . . 61
\hbox:n . . . . . . . . . . . . . . . . . . . . . . . 137 \int_add:Nn . . . . . . . . . . . . . . . . . . . . . 63
\hbox_gset:Nn . . . . . . . . . . . . . . . . . . 137 \int_case:nnTF . . . . . . . . . . . . . . . . . . 66
\hbox_gset:Nw . . . . . . . . . . . . . . . . . . 138 \int_compare:nNnTF . . . . . . . . . . . . . . . 64
\hbox_gset_end: . . . . . . . . . . . . . . . . 138 \int_compare:nTF . . . . . . . . . . . . . . . . 65
\hbox_gset_to_wd:Nnn . . . . . . . . . . . . 137 \int_compare_p:n . . . . . . . . . . . . . . . . 65
\hbox_overlap_left:n . . . . . . . . . . . . 137 \int_compare_p:nNn . . . . . . . . . . . . . . . 64
\hbox_overlap_right:n . . . . . . . . . . . 137 \int_const:Nn . . . . . . . . . . . . . . . . . . . 62
\hbox_set:Nn . . . . . . . . . . . . . . . . . . . 137 \int_decr:N . . . . . . . . . . . . . . . . . . . . . 63
\hbox_set:Nw . . . . . . . . . . . . . . . . . . . 138 \int_div_round:nn . . . . . . . . . . . . . . . 61
\hbox_set_end: . . . . . . . . . . . . . . . . . 138 \int_div_truncate:nn . . . . . . . . . . . . . 62
\hbox_set_to_wd:Nnn . . . . . . . . . . . . . 137 \int_do_until:nn . . . . . . . . . . . . . . . . 67
\hbox_to_wd:nn . . . . . . . . . . . . . . . . . 137 \int_do_until:nNnn . . . . . . . . . . . . . . . 66
\hbox_to_zero:n . . . . . . . . . . . . . . . . 137 \int_do_while:nn . . . . . . . . . . . . . . . . 67
\hbox_unpack:N . . . . . . . . . . . . . . . . . 138 \int_do_while:nNnn . . . . . . . . . . . . . . . 67
\hbox_unpack_clear:N . . . . . . . . . . . . 138 \int_eval:n . . . . . . . . . . . . . . . . . . . . . 61
\hcoffin_set:Nn . . . . . . . . . . . . . . . . 141 \int_from_alph:n . . . . . . . . . . . . . . . . 70
\hcoffin_set:Nw . . . . . . . . . . . . . . . . 142 \int_from_base:nn . . . . . . . . . . . . . . . 71
\hcoffin_set_end: . . . . . . . . . . . . . . 142 \int_from_bin:n . . . . . . . . . . . . . . . . . 70
\int_from_hex:n . . . . . . . . . . . . . . . . . 70
I \int_from_oct:n . . . . . . . . . . . . . . . . . 71
pi . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 \int_from_roman:n . . . . . . . . . . . . . . . 71
\if:w . . . . . . . . . . . . . . . . . . . . . . . . . . 24 \int_gadd:Nn . . . . . . . . . . . . . . . . . . . . 63
\if_bool:N . . . . . . . . . . . . . . . . . . . . . 41 \int_gdecr:N . . . . . . . . . . . . . . . . . . . . 63
\if_box_empty:N . . . . . . . . . . . . . . . . 140 \int_gincr:N . . . . . . . . . . . . . . . . . . . . 63
\if_case:w . . . . . . . . . . . . . . . . . . . . . 73 .int_gset:c . . . . . . . . . . . . . . . . . . . . 159
\if_catcode:w . . . . . . . . . . . . . . . . . . . 24 .int_gset:N . . . . . . . . . . . . . . . . . . . . 159
\if_charcode:w . . . . . . . . . . . . . . . . . . 24 \int_gset:Nn . . . . . . . . . . . . . . . . . . . . 63
\if_cs_exist:N . . . . . . . . . . . . . . . . . . 24 \int_gset_eq:NN . . . . . . . . . . . . . . . . . 63
\if_dim:w . . . . . . . . . . . . . . . . . . . . . . 88 \int_gsub:Nn . . . . . . . . . . . . . . . . . . . . 63
\if_eof:w . . . . . . . . . . . . . . . . . . . . . 174 \int_gzero:N . . . . . . . . . . . . . . . . . . . . 62
\if_false: . . . . . . . . . . . . . . . . . . . . . 23 \int_gzero_new:N . . . . . . . . . . . . . . . . 62
\if_hbox:N . . . . . . . . . . . . . . . . . . . . 140 \int_if_even:nTF . . . . . . . . . . . . . . . . 66
\if_int_compare:w . . . . . . . . . . . . . . . 73 \int_if_even_p:n . . . . . . . . . . . . . . . . 66
\if_int_odd:w . . . . . . . . . . . . . . . . . . . 73 \int_if_exist:NTF . . . . . . . . . . . . . . . 63
\if_meaning:w . . . . . . . . . . . . . . . . . . . 24 \int_if_exist_p:N . . . . . . . . . . . . . . . 63
\if_mode_horizontal: . . . . . . . . . . . . . 24 \int_if_odd:nTF . . . . . . . . . . . . . . . . . 66
\if_mode_inner: . . . . . . . . . . . . . . . . . 24 \int_if_odd_p:n . . . . . . . . . . . . . . . . . 66
\if_mode_math: . . . . . . . . . . . . . . . . . . 24 \int_incr:N . . . . . . . . . . . . . . . . . . . . . 63
\if_mode_vertical: . . . . . . . . . . . . . . . 24 \int_max:nn . . . . . . . . . . . . . . . . . . . . . 62
\if_predicate:w . . . . . . . . . . . . . . . . . 41 \int_min:nn . . . . . . . . . . . . . . . . . . . . . 62
\if_true: . . . . . . . . . . . . . . . . . . . . . . 23 \int_mod:nn . . . . . . . . . . . . . . . . . . . . . 62

213
\int_new:N . . . . . . . . . . . . . . . . . . . . . 62 \iow_now:Nn . . . . . .... . . . . . . . . . . . 171
.int_set:c . . . . . . . . . . . . . . . . . . . . 159 \iow_open:Nn . . . . .... . . . . . . . . . . . 170
.int_set:N . . . . . . . . . . . . . . . . . . . . 159 \iow_shipout:Nn . .... . . . . . . . . . . . 171
\int_set:Nn . . . . . . . . . . . . . . . . . . . . . 63 \iow_shipout_x:Nn ... . . . . . . . . . . . 172
\int_set_eq:NN . . . . . . . . . . . . . . . . . . 63 \iow_term:n . . . . . .... . . . . . . . . . . . 171
\int_show:N . . . . . . . . . . . . . . . . . . . . . 71 \iow_wrap:nnnN . . .... . . . . . . . . . . . 173
\int_show:n . . . . . . . . . . . . . . . . . . . . . 71
\int_step_function:nnnN . . . . . . . . . . 68 K
\int_step_inline:nnnn . . . . . . . . . . . . 68 \keys_define:nn . . . . . . . . . . . . . . . . 157
\int_step_variable:nnnNn . . . . . . . . . . 68 \keys_if_choice_exist:nnnTF . . . . . . 166
\int_sub:Nn . . . . . . . . . . . . . . . . . . . . . 63 \keys_if_choice_exist_p:nnn . . . . . . 166
\int_to_Alph:n . . . . . . . . . . . . . . . . . . 69 \keys_if_exist:nnTF . . . . . . . . . . . . . 166
\int_to_alph:n . . . . . . . . . . . . . . . . . . 69 \keys_if_exist_p:nn . . . . . . . . . . . . . 166
\int_to_arabic:n . . . . . . . . . . . . . . . . 68 \keys_set:nn . . . . . . . . . . . . . . . . . . . 163
\int_to_Base:nn . . . . . . . . . . . . . . . . . 70 \keys_set_filter:nnnN . . . . . . . . . . . 165
\int_to_base:nn . . . . . . . . . . . . . . . . . 70 \keys_set_groups:nnn . . . . . . . . . . . . 166
\int_to_bin:n . . . . . . . . . . . . . . . . . . . 69 \keys_set_known:nnN . . . . . . . . . . . . . 164
\int_to_Hex:n . . . . . . . . . . . . . . . . . . . 70 \keys_show:nn . . . . . . . . . . . . . . . . . . 166
\int_to_hex:n . . . . . . . . . . . . . . . . . . . 70 \keyval_parse:NNn . . . . . . . . . . . . . . 167
\int_to_oct:n . . . . . . . . . . . . . . . . . . . 70
\int_to_Roman:n . . . . . . . . . . . . . . . . . 70 L
\int_to_roman:n . . . . . . . . . . . . . . . . . 70 \l__box_angle_fp . . . . . . . . . . . . . . . 197
\int_to_symbols:nnn . . . . . . . . . . . . . . 69 \l__box_cos_fp . . . . . . . . . . . . . . . . . 197
\int_until_do:nn . . . . . . . . . . . . . . . . 67 \l__box_internal_box . . . . . . . . . . . . 197
\int_until_do:nNnn . . . . . . . . . . . . . . . 67 \l__box_scale_x_fp . . . . . . . . . . . . . . 197
\int_use:N . . . . . . . . . . . . . . . . . . . . . 64 \l__box_scale_y_fp . . . . . . . . . . . . . . 197
\int_while_do:nn . . . . . . . . . . . . . . . . 67 \l__box_sin_fp . . . . . . . . . . . . . . . . . 197
\int_while_do:nNnn . . . . . . . . . . . . . . . 67 \l__exp_internal_tl . . . . . . . . . . . . . . 33
\int_zero:N . . . . . . . . . . . . . . . . . . . . . 62 \l__file_internal_name_tl . . . . . . . . 174
\int_zero_new:N . . . . . . . . . . . . . . . . . 62 \l__kernel_expl_bool . . . . . . . . . . . . . . 8
\ior_close:N . . . . . . . . . . . . . . . . . . . 170 \l__prop_internal_tl . . . . . . . . . . . . 132
\ior_get:NN . . . . . . . . . . . . . . . . . . . . 170 \l_char_active_seq . . . . . . . . . . . . . . . 52
\ior_get_str:NN . . . . . . . . . . . . . . . . 171 \l_char_special_seq . . . . . . . . . . . . . . 52
\ior_if_eof:NTF . . . . . . . . . . . . . . . . 171 \l_iow_line_count_int . . . . . . . . . . . 173
\ior_if_eof_p:N . . . . . . . . . . . . . . . . 171 \l_keys_choice_int . . . . . . . . . . . . . . 162
\ior_list_streams: . . . . . . . . . . . . . . 170 \l_keys_choice_tl . . . . . . . . . . . . . . 162
\ior_map_break: . . . . . . . . . . . . . . . . 199 \l_keys_key_tl . . . . . . . . . . . . . . . . . 164
\ior_map_break:n . . . . . . . . . . . . . . . 199 \l_keys_path_tl . . . . . . . . . . . . . . . . 164
\ior_map_inline:Nn . . . . . . . . . . . . . . 198 \l_keys_value_tl . . . . . . . . . . . . . . . 164
\ior_new:N . . . . . . . . . . . . . . . . . . . . 169 \l_peek_token . . . . . . . . . . . . . . . . . . . 57
\ior_open:Nn . . . . . . . . . . . . . . . . . . . 169 \l_tmpa_bool . . . . . . . . . . . . . . . . . . . . 37
\ior_open:NnTF . . . . . . . . . . . . . . . . . 169 \l_tmpa_box . . . . . . . . . . . . . . . . . . . . 136
\ior_str_map_inline:Nn . . . . . . . . . . 198 \l_tmpa_clist . . . . . . . . . . . . . . . . . . 125
\iow_char:N . . . . . . . . . . . . . . . . . . . . 172 \l_tmpa_coffin . . . . . . . . . . . . . . . . . 144
\iow_close:N . . . . . . . . . . . . . . . . . . . 170 \l_tmpa_dim . . . . . . . . . . . . . . . . . . . . . 82
\iow_indent:n . . . . . . . . . . . . . . . . . . 173 \l_tmpa_fp . . . . . . . . . . . . . . . . . . . . 182
\iow_list_streams: . . . . . . . . . . . . . . 170 \l_tmpa_int . . . . . . . . . . . . . . . . . . . . . 72
\iow_log:n . . . . . . . . . . . . . . . . . . . . 171 \l_tmpa_muskip . . . . . . . . . . . . . . . . . . 88
\iow_new:N . . . . . . . . . . . . . . . . . . . . 169 \l_tmpa_prop . . . . . . . . . . . . . . . . . . . 132
\iow_newline: . . . . . . . . . . . . . . . . . . 172 \l_tmpa_seq . . . . . . . . . . . . . . . . . . . . 116

214
\l_tmpa_skip . . . . . . . . . . . . . . . . . ... 85 \msg_redirect_class:nn . . . . . .... . 150
\l_tmpa_tl . . . . . . . . . . . . . . . . . . 5, 103 \msg_redirect_module:nnn . . . . .... . 151
\l_tmpb_bool . . . . . . . . . . . . . . . . . ... 37 \msg_redirect_name:nnn . . . . . .... . 151
\l_tmpb_box . . . . . . . . . . . . . . . . . . .. 136 \msg_see_documentation_text:n ... . 148
\l_tmpb_clist . . . . . . . . . . . . . . . . .. 125 \msg_set:nnnn . . . . . . . . . . . . . .... . 147
\l_tmpb_coffin . . . . . . . . . . . . . . . .. 144 \msg_term:n . . . . . . . . . . . . . . . .... . 152
\l_tmpb_dim . . . . . . . . . . . . . . . . . . ... 82 \msg_warning:nnnnnn . . . . . . . . .... . 149
\l_tmpb_fp . . . . . . . . . . . . . . . . . . .. 182 \msg_warning_text:n . . . . . . . . .... . 148
\l_tmpb_int . . . . . . . . . . . . . . . . . . ... 72 .multichoice: . . . . . . . . . . . . . .... . 160
\l_tmpb_muskip . . . . . . . . . . . . . . . ... 88 .multichoices:nn . . . . . . . . . . .... . 160
\l_tmpb_prop . . . . . . . . . . . . . . . . . .. 132 .multichoices:on . . . . . . . . . . .... . 160
\l_tmpb_seq . . . . . . . . . . . . . . . . . . .. 116 .multichoices:Vn . . . . . . . . . . .... . 160
\l_tmpb_skip . . . . . . . . . . . . . . . . . ... 85 .multichoices:xn . . . . . . . . . . .... . 160
\l_tmpb_tl . . . . . . . . . . . . . . . . . . .. 103 \muskip_add:Nn . . . . . . . . . . . . .... . . 87
floor . . . . . . . . . . . . . . . . . . . . . . . .. 188 \muskip_const:Nn . . . . . . . . . . .... . . 86
\luatex_if_engine:TF . . . . . . . . . . ... 23 \muskip_eval:n . . . . . . . . . . . . .... . . 87
\luatex_if_engine_p: . . . . . . . . . . ... 23 \muskip_gadd:Nn . . . . . . . . . . . .... . . 87
\muskip_gset:Nn . . . . . . . . . . . .... . . 87
M \muskip_gset_eq:NN . . . . . . . . . .... . . 87
cm . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 \muskip_gsub:Nn . . . . . . . . . . . .... . . 87
em . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 \muskip_gzero:N . . . . . . . . . . . .... . . 86
mm . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 \muskip_gzero_new:N . . . . . . . . .... . . 86
.meta:n . . . . . . . . . . . . . . . . . . . . . . . 160 \muskip_if_exist:NTF . . . . . . . .... . . 86
.meta:nn . . . . . . . . . . . . . . . . . . . . . . 160 \muskip_if_exist_p:N . . . . . . . .... . . 86
\mode_if_horizontal:TF . . . . . . . . . . . 40 \muskip_new:N . . . . . . . . . . . . . .... . . 86
\mode_if_horizontal_p: . . . . . . . . . . . 40 \muskip_set:Nn . . . . . . . . . . . . .... . . 87
\mode_if_inner:TF . . . . . . . . . . . . . . . 40 \muskip_set_eq:NN . . . . . . . . . .... . . 87
\mode_if_inner_p: . . . . . . . . . . . . . . . 40 \muskip_show:N . . . . . . . . . . . . .... . . 88
\mode_if_math:TF . . . . . . . . . . . . . . . . 40 \muskip_show:n . . . . . . . . . . . . .... . . 88
\mode_if_math_p: . . . . . . . . . . . . . . . . 40 \muskip_sub:Nn . . . . . . . . . . . . .... . . 87
\mode_if_vertical:TF . . . . . . . . . . . . . 40 \muskip_use:N . . . . . . . . . . . . . .... . . 87
\mode_if_vertical_p: . . . . . . . . . . . . . 40 \muskip_zero:N . . . . . . . . . . . . .... . . 86
\msg_critical:nnnnnn . . . . . . . . . . . . 149 \muskip_zero_new:N . . . . . . . . . .... . . 86
\msg_critical_text:n . . . . . . . . . . . . 147 \my_map_dbl:nn . . . . . . . . . . . . .... . . . 1
\msg_error:nnnnnn . . . . . . . . . . . . . . 149
\msg_error_text:n . . . . . . . . . . . . . . 147 N
\msg_fatal:nnnnnn . . . . . . . . . . . . . . 148 in . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\msg_fatal_text:n . . . . . . . . . . . . . . 147 ln . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
\msg_gset:nnnn . . . . . . . . . . . . . . . . . 147 inf . . . . . . . . . . . . . . . . . . . . . . . . . . 190
\msg_if_exist:nnTF . . . . . . . . . . . . . . 147
\msg_if_exist_p:nn . . . . . . . . . . . . . . 147 O
\msg_info:nnnnnn . . . . . . . . . . . . . . . 149 \or: . . . . . . . . . . . . .. . . . . . . . . . . 23, 73
\msg_info_text:n . . . . . . . . . . . . . . . 148 cos . . . . . . . . . . . . .. . . . . . . . . . . . . 188
\msg_interrupt:nnn . . . . . . . . . . . . . . 151 cosd . . . . . . . . . . . . .. . . . . . . . . . . . . 189
\msg_line_context: . . . . . . . . . . . . . . 147 cot . . . . . . . . . . . . .. . . . . . . . . . . . . 188
\msg_line_number: . . . . . . . . . . . . . . 147 cotd . . . . . . . . . . . . .. . . . . . . . . . . . . 189
\msg_log:n . . . . . . . . . . . . . . . . . . . . 152 round . . . . . . . . . . . .. . . . . . . . . . . . . 188
\msg_log:nnnnnn . . . . . . . . . . . . . . . . 149
\msg_new:nnnn . . . . . . . . . . . . . . . . . . 146 P
\msg_none:nnnnnn . . . . . . . . . . . . . . . 150 bp . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

215
sp . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 \prop_map_break: . . . . . . . . . . . . . . . 131
\pdftex_if_engine:TF . . . . . . . . . . . . . 23 \prop_map_break:n . . . . . . . . . . . . . . 131
\pdftex_if_engine_p: . . . . . . . . . . . . . 23 \prop_map_function:NN . . . . . . . . . . . 130
\peek_after:Nw . . . . . . . . . . . . . . . . . . 57 \prop_map_inline:Nn . . . . . . . . . . . . . 131
\peek_catcode:NTF . . . . . . . . . . . . . . . 57 \prop_map_tokens:Nn . . . . . . . . . . . . . 200
\peek_catcode_ignore_spaces:NTF . . . . 57 \prop_new:N . . . . . . . . . . . . . . . . . . . . 127
\peek_catcode_remove:NTF . . . . . . . . . . 58 \prop_pop:NnN . . . . . . . . . . . . . . . . . . 128
\peek_catcode_remove_ignore_spaces:NTF \prop_pop:NnNTF . . . . . . . . . . . . . . . . 130
. . . . . . . . . . . . . . . . . . . . . . . . . . 58 \prop_put:Nnn . . . . . . . . . . . . . . . . . . 128
\peek_charcode:NTF . . . . . . . . . . . . . . . 58 \prop_put_if_new:Nnn . . . . . . . . . . . . 128
\peek_charcode_ignore_spaces:NTF . . . 58 \prop_remove:Nn . . . . . . . . . . . . . . . . 129
\peek_charcode_remove:NTF . . . . . . . . . 58 \prop_set_eq:NN . . . . . . . . . . . . . . . . 127
\peek_charcode_remove_ignore_spaces:NTF \prop_show:N . . . . . . . . . . . . . . . . . . . 131
. . . . . . . . . . . . . . . . . . . . . . . . . . 59 \ProvidesExplClass . . . . . . . . . . . . . . .. 7
\peek_gafter:Nw . . . . . . . . . . . . . . . . . 57 \ProvidesExplFile . . . . . . . . . . . . . . .. 7
\peek_meaning:NTF . . . . . . . . . . . . . . . 59 \ProvidesExplPackage . . . . . . . . . . . . .. 7
\peek_meaning_ignore_spaces:NTF . . . . 59
\peek_meaning_remove:NTF . . . . . . . . . . 59 Q
\peek_meaning_remove_ignore_spaces:NTF \q_mark . . . . . . . . . . . . . . . . . . . . . . . . 44
. . . . . . . . . . . . . . . . . . . . . . . . . . 59 \q_no_value . . . . . . . . . . . . . . . . . . . . . 44
\peek_N_type:TF . . . . . . . . . . . . . . . . 204 \q_recursion_stop . . . . . . . . . . . . . 4, 45
\prg_do_nothing: . . . . . . . . . . . . . . . . 10 \q_recursion_tail . . . . . . . . . . . . . 4, 45
\prg_new_conditional:Npnn . . . . . . . . . 34 \q_stop . . . . . . . . . . . . . . . . . . . . . . . . 44
\prg_new_eq_conditional:NNn . . . . . . . 36 sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . 190
\prg_new_protected_conditional:Npnn 34 \quark_if_nil:NTF . . . . . . . . . . . . . . . 44
\prg_replicate:nn . . . . . . . . . . . . . . . 40 \quark_if_nil:nTF . . . . . . . . . . . . . . . 44
\prg_return_false: . . . . . . . . . . . . . . . 36 \quark_if_nil_p:N . . . . . . . . . . . . . . . 44
\prg_return_true: . . . . . . . . . . . . . . . 36 \quark_if_nil_p:n . . . . . . . . . . . . . . . 44
\prg_set_conditional:Npnn . . . . . . . . . 34 \quark_if_no_value:NTF . . . . . . . . . . . 44
\prg_set_eq_conditional:NNn . . . . . . . 36 \quark_if_no_value:nTF . . . . . . . . . . . 44
\prg_set_protected_conditional:Npnn 34 \quark_if_no_value_p:N . . . . . . . . . . . 44
\prop_clear:N . . . . . . . . . . . . . . . . . . 127 \quark_if_no_value_p:n . . . . . . . . . . . 44
\prop_clear_new:N . . . . . . . . . . . . . . 127 \quark_if_recursion_tail_stop:N . . . . 45
\prop_gclear:N . . . . . . . . . . . . . . . . . 127 \quark_if_recursion_tail_stop:n 8, 9, 45
\prop_gclear_new:N . . . . . . . . . . . . . . 127 \quark_if_recursion_tail_stop_do:Nn 45
\prop_get:NnN . . . . . . . . . . . . . . . . . . 128 \quark_if_recursion_tail_stop_do:nn 45
\prop_get:NnNTF . . . . . . . . . . . . . . . . 130 \quark_new:N . . . . . . . . . . . . . . . . . . . . 44
\prop_gpop:NnN . . . . . . . . . . . . . . . . . 128
\prop_gpop:NnNTF . . . . . . . . . . . . . . . 130 R
\prop_gput:Nnn . . . . . . . . . . . . . . . . . 128 \reverse_if:N . . . . . . . . . . . . . . . . . . . 23
\prop_gput_if_new:Nnn . . . . . . . . . . . 128 true . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\prop_gremove:Nn . . . . . . . . . . . . . . . 129 trunc . . . . . . . . . . . . . . . . . . . . . . . . . 188
\prop_gset_eq:NN . . . . . . . . . . . . . . . 127
\prop_if_empty:NTF . . . . . . . . . . . . . . 129 S
\prop_if_empty_p:N . . . . . . . . . . . . . . 129 \s__prop . . . . . . . . . . . .. . . . . . . . . . 132
\prop_if_exist:NTF . . . . . . . . . . . . . . 129 \s__seq . . . . . . . . . . . . .. . . . . . . . . . 116
\prop_if_exist_p:N . . . . . . . . . . . . . . 129 \s__stop . . . . . . . . . . . .. . . . . . . . . . . 47
\prop_if_in:NnTF . . . . . . . . . . . . . . . 129 csc . . . . . . . . . . . . . . . .. . . . . . . . . . 188
\prop_if_in_p:Nn . . . . . . . . . . . . . . . 129 \scan_align_safe_stop: . . . . . . . . . . . 41
\prop_item:Nn . . . . . . . . . . . . . . . . . . 129 \scan_stop: . . . . . . . . . .. . . . . . . . . . . 10

216
cscd . . . . . . . . . . . . . . . . . . . . . . . . . . 189 \seq_pop_right:NN . . . . . . . . . . . . . . 109
asec . . . . . . . . . . . . . . . . . . . . . . . . . . 189 \seq_pop_right:NNTF . . . . . . . . . . . . . 111
asecd . . . . . . . . . . . . . . . . . . . . . . . . . 189 \seq_push:Nn . . . . . . . . . . . . . . . . . . . 115
\seq_clear:N . . . . . . . . . . . . . . . . . . . 107 \seq_put_left:Nn . . . . . . . . . . . . . . . 108
\seq_clear_new:N . . . . . . . . . . . . . . . 107 \seq_put_right:Nn . . . . . . . . . . . . . . 108
\seq_concat:NNN . . . . . . . . . . . . . . . . 108 \seq_remove_all:Nn . . . . . . . . . . . . . . 111
\seq_count:N . . . . . . . . . . . . . . . . . . . 113 \seq_remove_duplicates:N . . . . . . . . . 111
\seq_gclear:N . . . . . . . . . . . . . . . . . . 107 \seq_reverse:N . . . . . . . . . . . . . . . . . 111
\seq_gclear_new:N . . . . . . . . . . . . . . 107 \seq_set_eq:NN . . . . . . . . . . . . . . . . . 107
\seq_gconcat:NNN . . . . . . . . . . . . . . . 108 \seq_set_filter:NNn . . . . . . . . . . . . . 200
\seq_get:NN . . . . . . . . . . . . . . . . . . . . 115 \seq_set_from_clist:NN . . . . . . . . . . 107
\seq_get:NNTF . . . . . . . . . . . . . . . . . . 115 \seq_set_map:NNn . . . . . . . . . . . . . . . 200
\seq_get_left:NN . . . . . . . . . . . . . . . 109 \seq_set_split:Nnn . . . . . . . . . . . . . . 108
\seq_get_left:NNTF . . . . . . . . . . . . . . 110 \seq_show:N . . . . . . . . . . . . . . . . . . . . 116
\seq_get_right:NN . . . . . . . . . . . . . . 109 \seq_use:Nn . . . . . . . . . . . . . . . . . . . . 114
\seq_get_right:NNTF . . . . . . . . . . . . . 110 \seq_use:Nnnn . . . . . . . . . . . . . . . . . . 114
\seq_gpop:NN . . . . . . . . . . . . . . . . . . . 115 asin . . . . . . . . . . . . . . . . . . . . . . . . . . 189
\seq_gpop:NNTF . . . . . . . . . . . . . . . . . 115 asind . . . . . . . . . . . . . . . . . . . . . . . . . 189
\seq_gpop_left:NN . . . . . . . . . . . . . . 109 \skip_add:Nn . . . . . . . . . . . . . . . . . . . . 83
\seq_gpop_left:NNTF . . . . . . . . . . . . . 110 \skip_const:Nn . . . . . . . . . . . . . . . . . . 83
\seq_gpop_right:NN . . . . . . . . . . . . . . 109 \skip_eval:n . . . . . . . . . . . . . . . . . . . . 84
\seq_gpop_right:NNTF . . . . . . . . . . . . 111 \skip_gadd:Nn . . . . . . . . . . . . . . . . . . . 83
\seq_gpush:Nn . . . . . . . . . . . . . . . . . . 115 .skip_gset:c . . . . . . . . . . . . . . . . . . . 160
\seq_gput_left:Nn . . . . . . . . . . . . . . 108 .skip_gset:N . . . . . . . . . . . . . . . . . . . 160
\seq_gput_right:Nn . . . . . . . . . . . . . . 108 \skip_gset:Nn . . . . . . . . . . . . . . . . . . . 83
\seq_gremove_all:Nn . . . . . . . . . . . . . 111 \skip_gset_eq:NN . . . . . . . . . . . . . . . . 84
\seq_gremove_duplicates:N . . . . . . . . 111 \skip_gsub:Nn . . . . . . . . . . . . . . . . . . . 84
\seq_greverse:N . . . . . . . . . . . . . . . . 111 \skip_gzero:N . . . . . . . . . . . . . . . . . . . 83
\seq_gset_eq:NN . . . . . . . . . . . . . . . . 107 \skip_gzero_new:N . . . . . . . . . . . . . . . 83
\seq_gset_filter:NNn . . . . . . . . . . . . 200 \skip_horizontal:N . . . . . . . . . . . . . . . 86
\seq_gset_from_clist:NN . . . . . . . . . 107 \skip_if_eq:nnTF . . . . . . . . . . . . . . . . 84
\seq_gset_map:NNn . . . . . . . . . . . . . . 200 \skip_if_eq_p:nn . . . . . . . . . . . . . . . . 84
\seq_gset_split:Nnn . . . . . . . . . . . . . 108 \skip_if_exist:NTF . . . . . . . . . . . . . . . 83
\seq_if_empty:NTF . . . . . . . . . . . . . . 112 \skip_if_exist_p:N . . . . . . . . . . . . . . . 83
\seq_if_empty_p:N . . . . . . . . . . . . . . 112 \skip_if_finite:nTF . . . . . . . . . . . . . . 84
\seq_if_exist:NTF . . . . . . . . . . . . . . 108 \skip_if_finite_p:n . . . . . . . . . . . . . . 84
\seq_if_exist_p:N . . . . . . . . . . . . . . 108 \skip_new:N . . . . . . . . . . . . . . . . . . . . . 83
\seq_if_in:NnTF . . . . . . . . . . . . . . . . 112 .skip_set:c . . . . . . . . . . . . . . . . . . . . 160
\seq_item:Nn . . . . . . . . . . . . . . . . . . . 110 .skip_set:N . . . . . . . . . . . . . . . . . . . . 160
\seq_map_break: . . . . . . . . . . . . . . . . 113 \skip_set:Nn . . . . . . . . . . . . . . . . . . . . 83
\seq_map_break:n . . . . . . . . . . . . . . . 113 \skip_set_eq:NN . . . . . . . . . . . . . . . . . 84
\seq_map_function:NN . . . . . . . . . . 4, 112 \skip_show:N . . . . . . . . . . . . . . . . . . . . 85
\seq_map_inline:Nn . . . . . . . . . . . . . . 112 \skip_show:n . . . . . . . . . . . . . . . . . . . . 85
\seq_map_variable:NNn . . . . . . . . . . . 112 \skip_split_finite_else_action:nnNN 201
\seq_mapthread_function:NNN . . . . . . 200 \skip_sub:Nn . . . . . . . . . . . . . . . . . . . . 84
\seq_new:N . . . . . . . . . . . . . . . . . . 4, 107 \skip_use:N . . . . . . . . . . . . . . . . . . . . . 85
\seq_pop:NN . . . . . . . . . . . . . . . . . . . . 115 \skip_vertical:N . . . . . . . . . . . . . . . . 86
\seq_pop:NNTF . . . . . . . . . . . . . . . . . . 115 \skip_zero:N . . . . . . . . . . . . . . . . . . . . 83
\seq_pop_left:NN . . . . . . . . . . . . . . . 109 \skip_zero_new:N . . . . . . . . . . . . . . . . 83
\seq_pop_left:NNTF . . . . . . . . . . . . . . 110 \str_case:nnTF . . . . . . . . . . . . . . . . . 105

217
\str_case_x:nnTF .. . . . . . . . . . . . . . 105 \romannumeral . . . . . . . . . . . . . . . . 73
\str_fold_case:n .. . . . . . . . . . . . . . 106 \show . . . . . . . . . . . . . . . . . . . . 17, 102
\str_head:n . . . . . .. . . . . . . . . . . . . . 104 \showtokens . . . . . . . . . . . . . . . . . 103
\str_if_eq:nnTF . .. . . . . . . . . . . . . . 104 \string . . . . . . . . . . . . . . . . . . . . . 53
\str_if_eq_p:nn . .. . . . . . . . . . . . . . 104 \the . . . . . . . . . . . . . . . . 64, 81, 85, 87
\str_if_eq_x:nnTF . . . . . . . . . . . . . . 105 \unexpanded . . . . . . . . . . . . . . . 32,
\str_if_eq_x_p:nn . . . . . . . . . . . . . . 105 102, 110, 114, 123, 125, 129, 201, 202
\str_tail:n . . . . . .. . . . . . . . . . . . . . 104 \unhbox . . . . . . . . . . . . . . . . . . . . 138
\unhcopy . . . . . . . . . . . . . . . . . . . 138
T \unless . . . . . . . . . . . . . . . . . . . . . 23
pt . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 \unvbox . . . . . . . . . . . . . . . . . . . . 140
atan . . . . . . . . . . . . . . . . . . . . . . . . . . 190 \unvcopy . . . . . . . . . . . . . . . . . . . 140
atand . . . . . . . . . . . . . . . . . . . . . . . . . 190 \uppercase . . . . . . . . . . . . . . . . . . . 94
TEX and LATEX 2ε commands: \vbox . . . . . . . . . . . . . . . . . . . . . . 138
\box . . . . . . . . . . . . . . . . . . . . . . . 134 \vskip . . . . . . . . . . . . . . . . . . . . . . 86
\copy . . . . . . . . . . . . . . . . . . . . . . 134 \vsplit . . . . . . . . . . . . . . . . . . . . 139
\csname . . . . . . . . . . . . . . . . . . . . . 18 \vtop . . . . . . . . . . . . . . . . . . . . . . 138
\dimexpr . . . . . . . . . . . . . . . . . . . . 89 \wd . . . . . . . . . . . . . . . . . . . . . . . . 135
\dp . . . . . . . . . . . . . . . . . . . . . . . . 134 \write . . . . . . . . . . . . . . . . . . . . . 172
\edef . . . . . . . . . . . . . . . . . . . . .... 2 \tl_case:NnTF . . . . . . . . . . . . . . . . . . . 95
\endcsname . . . . . . . . . . . . . . . . . . . 18 \tl_clear:N . . . . . . . . . . . . . . . . . . . . . 91
\endinput . . . . . . . . . . . . . . . . . . . 149 \tl_clear_new:N . . . . . . . . . . . . . . . . . 91
\endtemplate . . . . . . . . . . . . . . . . . 41 \tl_concat:NNN . . . . . . . . . . . . . . . . . . 91
\escapechar . . . . . . . . . . . . . . . . . . 98 \tl_const:Nn . . . . . . . . . . . . . . . . . . . . 91
\exp_not:n . . . . . . . . . . . . . . . . 99, 120 \tl_count:N . . . . . . . . . . . . . . . . . . . . . 99
\expandafter . . . . . . . . . . . . . . . . . 31 \tl_count:n . . . . . . . . . . . . . . . . . . . . . 98
\halign . . . . . . . . . . . . . . . . . . . . . 41 \tl_count_tokens:n . . . . . . . . . . . . . . 201
\hbox . . . . . . . . . . . . . . . . . . . . . . 137 \tl_expandable_lowercase:n . . . . . . . 202
\hskip . . . . . . . . . . . . . . . . . . . . . . 86 \tl_expandable_uppercase:n . . . . . . . 202
\ht . . . . . . . . . . . . . . . . . . . . . . . . 135 \tl_gclear:N . . . . . . . . . . . . . . . . . . . . 91
\ifcase . . . . . . . . . . . . . . . . . . . . . 73 \tl_gclear_new:N . . . . . . . . . . . . . . . . 91
\ifdim . . . . . . . . . . . . . . . . . . . . . . 88 \tl_gconcat:NNN . . . . . . . . . . . . . . . . . 91
\ifeof . . . . . . . . . . . . . . . . . . . . . 174 \tl_gput_left:Nn . . . . . . . . . . . . . . . . 92
\ifhbox . . . . . . . . . . . . . . . . . . . . 140 \tl_gput_right:Nn . . . . . . . . . . . . . . . 92
\ifnum . . . . . . . . . . . . . . . . . . . . . . 73 \tl_gremove_all:Nn . . . . . . . . . . . . . . . 93
\ifodd . . . . . . . . . . . . . . . . . . . . . . 73 \tl_gremove_once:Nn . . . . . . . . . . . . . . 92
\ifvbox . . . . . . . . . . . . . . . . . . . . 140 \tl_greplace_all:Nnn . . . . . . . . . . . . . 92
\ifvoid . . . . . . . . . . . . . . . . . . . . 140 \tl_greplace_once:Nnn . . . . . . . . . . . . 92
\ifx . . . . . . . . . . . . . . . . . . . . . . . . 24 \tl_greverse:N . . . . . . . . . . . . . . . . . . 99
\jobname . . . . . . . . . . . . . . . . . . . 103 .tl_gset:c . . . . . . . . . . . . . . . . . . . . 160
\lowercase . . . . . . . . . . . . . . . . . . . 93 .tl_gset:N . . . . . . . . . . . . . . . . . . . . 160
\makeatletter . . . . . . . . . . . . . .... 7 \tl_gset:Nn . . . . . . . . . . . . . . . . . . . . . 92
\meaning . . . . . . . . . . . . . . . . . 17, 53 \tl_gset_eq:NN . . . . . . . . . . . . . . . . . . 91
\noexpand . . . . . . . . . . . . . . . . . . . . 32 \tl_gset_from_file:Nnn . . . . . . . . . . 203
\number . . . . . . . . . . . . . . . . . . . . . 74 \tl_gset_from_file_x:Nnn . . . . . . . . . 204
\numexpr . . . . . . . . . . . . . . . . . . . . 74 \tl_gset_rescan:Nnn . . . . . . . . . . . . . . 93
\or . . . . . . . . . . . . . . . . . . . . . . . . . 73 .tl_gset_x:c . . . . . . . . . . . . . . . . . . . 160
\read . . . . . . . . . . . . . . . . . . . . . . 170 .tl_gset_x:N . . . . . . . . . . . . . . . . . . . 160
\readline . . . . . . . . . . . . . . . . . . . 171 \tl_gtrim_spaces:N . . . . . . . . . . . . . . 100
\RequirePackage . . . . . . . . . . . .... 7 \tl_head:N . . . . . . . . . . . . . . . . . . . . 100

218
\tl_head:w . . . . . . . . . . . . . . . . . . . . 100 \tl_rescan:nn . . . . . . . . . . . . . . . . . . . 93
\tl_if_blank:nTF . . . . . . . . . . . . . . . . 94 \tl_reverse:N . . . . . . . . . . . . . . . . . . . 99
\tl_if_blank_p:n . . . . . . . . . . . . . . . . 94 \tl_reverse:n . . . . . . . . . . . . . . . . . . . 99
\tl_if_empty:NTF . . . . . . . . . . . . . . . . 94 \tl_reverse_items:n . . . . . . . . . . . . . . 99
\tl_if_empty:nTF . . . . . . . . . . . . . . . . 94 \tl_reverse_tokens:n . . . . . . . . . . . . 201
\tl_if_empty_p:N . . . . . . . . . . . . . . . . 94 .tl_set:c . . . . . . . . . . . . . . . . . . . . . 160
\tl_if_empty_p:n . . . . . . . . . . . . . . . . 94 .tl_set:N . . . . . . . . . . . . . . . . . . . . . 160
\tl_if_eq:NNTF . . . . . . . . . . . . . . . . . . 94 \tl_set:Nn . . . . . . . . . . . . . . . . . . . . . 92
\tl_if_eq:nnTF . . . . . . . . . . . . . . . . . . 94 \tl_set_eq:NN . . . . . . . . . . . . . . . . . . . 91
\tl_if_eq_p:NN . . . . . . . . . . . . . . . . . . 94 \tl_set_from_file:Nnn . . . . . . . . . . . 203
\tl_if_exist:NTF . . . . . . . . . . . . . . . . 91 \tl_set_from_file_x:Nnn . . . . . . . . . 204
\tl_if_exist_p:N . . . . . . . . . . . . . . . . 91 \tl_set_rescan:Nnn . . . . . . . . . . . . . . . 93
\tl_if_head_eq_catcode:nNTF . . . . . . 101 .tl_set_x:c . . . . . . . . . . . . . . . . . . . . 160
\tl_if_head_eq_catcode_p:nN . . . . . . 101 .tl_set_x:N . . . . . . . . . . . . . . . . . . . . 160
\tl_if_head_eq_charcode:nNTF . . . . . 101 \tl_show:N . . . . . . . . . . . . . . . . . . . . 102
\tl_if_head_eq_charcode_p:nN . . . . . 101 \tl_show:n . . . . . . . . . . . . . . . . . . . . 103
\tl_if_head_eq_meaning:nNTF . . . . . . 101 \tl_tail:N . . . . . . . . . . . . . . . . . . . . 101
\tl_if_head_eq_meaning_p:nN . . . . . . 101 \tl_to_lowercase:n . . . . . . . . . . . . . . . 93
\tl_if_head_is_group:nTF . . . . . . . . . 101 \tl_to_str:N . . . . . . . . . . . . . . . . . . . . 98
\tl_if_head_is_group_p:n . . . . . . . . . 101 \tl_to_str:n . . . . . . . . . . . . . . . . . . . . 98
\tl_if_head_is_N_type:nTF . . . . . . . . 102 \tl_to_uppercase:n . . . . . . . . . . . . . . . 94
\tl_if_head_is_N_type_p:n . . . . . . . . 102 \tl_trim_spaces:N . . . . . . . . . . . . . . 100
\tl_if_head_is_space:nTF . . . . . . . . . 102 \tl_trim_spaces:n . . . . . . . . . . . . . . . 99
\tl_if_head_is_space_p:n . . . . . . . . . 102 \tl_upper_case:n . . . . . . . . . . . . . . . 202
\tl_if_in:NnTF . . . . . . . . . . . . . . . . . . 95 \tl_use:N . . . . . . . . . . . . . . . . . . . . . . 98
\tl_if_in:nnTF . . . . . . . . . . . . . . . . . . 95 \token_get_arg_spec:N . . . . . . . . . . . . 60
\tl_if_single:NTF . . . . . . . . . . . . . . . 95 \token_get_prefix_spec:N . . . . . . . . . . 60
\tl_if_single:nTF . . . . . . . . . . . . . . . 95 \token_get_replacement_spec:N . . . . . 60
\tl_if_single_p:N . . . . . . . . . . . . . . . 95 \token_if_active:NTF . . . . . . . . . . . . . 54
\tl_if_single_p:n . . . . . . . . . . . . . . . 95 \token_if_active_p:N . . . . . . . . . . . . . 54
\tl_if_single_token:nTF . . . . . . . . . 201 \token_if_alignment:NTF . . . . . . . . . . 53
\tl_if_single_token_p:n . . . . . . . . . 201 \token_if_alignment_p:N . . . . . . . . . . 53
\tl_item:nn . . . . . . . . . . . . . . . . . . . . 102 \token_if_chardef:NTF . . . . . . . . . . . . 55
\tl_lower_case:n . . . . . . . . . . . . . . . 202 \token_if_chardef_p:N . . . . . . . . . . . . 55
\tl_map_break: . . . . . . . . . . . . . . . . . . 97 \token_if_cs:NTF . . . . . . . . . . . . . . . . 55
\tl_map_break:n . . . . . . . . . . . . . . . . . 97 \token_if_cs_p:N . . . . . . . . . . . . . . . . 55
\tl_map_function:NN . . . . . . . . . . . . . . 96 \token_if_dim_register:NTF . . . . . . . . 56
\tl_map_function:nN . . . . . . . . . . . . . . 96 \token_if_dim_register_p:N . . . . . . . . 56
\tl_map_inline:Nn . . . . . . . . . . . . . . . 96 \token_if_eq_catcode:NNTF . . . . . . . . . 54
\tl_map_inline:nn . . . . . . . . . . . . . . . 96 \token_if_eq_catcode_p:NN . . . . . . . . . 54
\tl_map_variable:NNn . . . . . . . . . . . . . 96 \token_if_eq_charcode:NNTF . . . . . . . . 54
\tl_map_variable:nNn . . . . . . . . . . . . . 96 \token_if_eq_charcode_p:NN . . . . . . . . 54
\tl_mixed_case:n . . . . . . . . . . . . . . . 202 \token_if_eq_meaning:NNTF . . . . . . . . . 55
\tl_new:N . . . . . . . . . . . . . . . . . . . . . . 91 \token_if_eq_meaning_p:NN . . . . . . . . . 55
\tl_put_left:Nn . . . . . . . . . . . . . . . . . 92 \token_if_expandable:NTF . . . . . . . . . . 55
\tl_put_right:Nn . . . . . . . . . . . . . . . . 92 \token_if_expandable_p:N . . . . . . . . . . 55
\tl_remove_all:Nn . . . . . . . . . . . . . . . 93 \token_if_group_begin:NTF . . . . . . . . . 53
\tl_remove_once:Nn . . . . . . . . . . . . . . . 92 \token_if_group_begin_p:N . . . . . . . . . 53
\tl_replace_all:Nnn . . . . . . . . . . . . . . 92 \token_if_group_end:NTF . . . . . . . . . . 53
\tl_replace_once:Nnn . . . . . . . . . . . . . 92 \token_if_group_end_p:N . . . . . . . . . . 53

219
\token_if_int_register:NTF . . . . . . . . 56 \use_i_delimit_by_q_recursion_stop:nw
\token_if_int_register_p:N . . . . . . . . 56 . . . . . . . . . . . . . . . . . . . . . . . . . . 21
\token_if_letter:NTF . . . . . . . . . . . . . 54 \use_i_delimit_by_q_stop:nw . . . . . . . 21
\token_if_letter_p:N . . . . . . . . . . . . . 54 \use_i_ii:nnn . . . . . . . . . . . . . . . . . . . 20
\token_if_long_macro:NTF . . . . . . . . . . 55 \use_ii:nn . . . . . . . . . . . . . . . . . . . . . 20
\token_if_long_macro_p:N . . . . . . . . . . 55 \use_ii:nnn . . . . . . . . . . . . . . . . . . . . . 20
\token_if_macro:NTF . . . . . . . . . . . . . . 55 \use_ii:nnnn . . . . . . . . . . . . . . . . . . . . 20
\token_if_macro_p:N . . . . . . . . . . . . . . 55 \use_iii:nnn . . . . . . . . . . . . . . . . . . . . 20
\token_if_math_subscript:NTF . . . . . . 54 \use_iii:nnnn . . . . . . . . . . . . . . . . . . . 20
\token_if_math_subscript_p:N . . . . . . 54 \use_iv:nnnn . . . . . . . . . . . . . . . . . . . . 20
\token_if_math_superscript:NTF . . . . 54 \use_none:n . . . . . . . . . . . . . . . . . . . . . 20
\use_none_delimit_by_q_nil:w . . . . . . 21
\token_if_math_superscript_p:N . . . . 54
\use_none_delimit_by_q_recursion_stop:w
\token_if_math_toggle:NTF . . . . . . . . . 53
. . . . . . . . . . . . . . . . . . . . . . . . . . 21
\token_if_math_toggle_p:N . . . . . . . . . 53
\use_none_delimit_by_q_stop:w . . . . . 21
\token_if_mathchardef:NTF . . . . . . . . . 56
\token_if_mathchardef_p:N . . . . . . . . . 56 V
\token_if_muskip_register:NTF . . . . . 56 .value_forbidden: . . . . . . . . . . . . . . 160
\token_if_muskip_register_p:N . . . . . 56 .value_required: . . . . . . . . . . . . . . . 160
\token_if_other:NTF . . . . . . . . . . . . . . 54 \vbox:n . . . . . . . . . . . . . . . . . . . . . . . 138
\token_if_other_p:N . . . . . . . . . . . . . . 54 \vbox_gset:Nn . . . . . . . . . . . . . . . . . . 139
\token_if_parameter:NTF . . . . . . . . . . 54 \vbox_gset:Nw . . . . . . . . . . . . . . . . . . 139
\token_if_parameter_p:N . . . . . . . . . . 54 \vbox_gset_end: . . . . . . . . . . . . . . . . 139
\token_if_primitive:NTF . . . . . . . . . . 56 \vbox_gset_to_ht:Nnn . . . . . . . . . . . . 139
\token_if_primitive_p:N . . . . . . . . . . 56 \vbox_gset_top:Nn . . . . . . . . . . . . . . 139
\token_if_protected_long_macro:NTF . 55 \vbox_set:Nn . . . . . . . . . . . . . . . . . . . 139
\token_if_protected_long_macro_p:N . 55 \vbox_set:Nw . . . . . . . . . . . . . . . . . . . 139
\token_if_protected_macro:NTF . . . . . 55 \vbox_set_end: . . . . . . . . . . . . . . . . . 139
\token_if_protected_macro_p:N . . . . . 55 \vbox_set_split_to_ht:NNn . . . . . . . . 139
\token_if_skip_register:NTF . . . . . . . 56 \vbox_set_to_ht:Nnn . . . . . . . . . . . . . 139
\token_if_skip_register_p:N . . . . . . . 56 \vbox_set_top:Nn . . . . . . . . . . . . . . . 139
\token_if_space:NTF . . . . . . . . . . . . . . 54 \vbox_to_ht:nn . . . . . . . . . . . . . . . . . 139
\token_if_space_p:N . . . . . . . . . . . . . . 54 \vbox_to_zero:n . . . . . . . . . . . . . . . . 139
\token_if_toks_register:NTF . . . . . . . 56 \vbox_top:n . . . . . . . . . . . . . . . . . . . . 138
\token_if_toks_register_p:N . . . . . . . 56 \vbox_unpack:N . . . . . . . . . . . . . . . . . 140
\vbox_unpack_clear:N . . . . . . . . . . . . 140
\token_new:Nn . . . . . . . . . . . . . . . . . . . 52
\vcoffin_set:Nnn . . . . . . . . . . . . . . . 142
\token_to_meaning:N . . . . . . . . . . . . . . 53
\vcoffin_set:Nnw . . . . . . . . . . . . . . . 142
\token_to_str:N . . . . . . . . . . . . . . . 5, 53
\vcoffin_set_end: . . . . . . . . . . . . . . 142
U W
\use:c . . . . . . . . . . . . . . . . . . . . . . . . . 18 TWOBARS . . . . . . . . . . . . . . . . . . . . . . . 186
\use:n . . . . . . . . . . . . . . . . . . . . . . . . . 19
\use:x . . . . . . . . . . . . . . . . . . . . . . . . . 21 X
\use_i:nn . . . . . . . . . . . . . . . . . . . . . . 20 ex . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
\use_i:nnn . . . . . . . . . . . . . . . . . . . . . 20 \xetex_if_engine:TF . . . . . . . . . . . . 5, 23
\use_i:nnnn . . . . . . . . . . . . . . . . . . . . . 20 \xetex_if_engine_p: . . . . . . . . . . . . . . 23
\use_i_delimit_by_q_nil:nw . . . . . . . . 21 exp . . . . . . . . . . . . . . . . . . . . . . . . . . 187

220