Debian Codegraph @

texmf-dist/source/latex/siunitx/siunitx-unit.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: siunitx-unit.dtx Copyright (C) 2014-2026 Joseph Wright
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 % This file is part of the "siunitx bundle" (The Work in LPPL)
13 % and all files in that bundle must be distributed together.
14 %
15 % The released version of this bundle is available from CTAN.
16 %
17 % -----------------------------------------------------------------------
18 %
19 % The development version of the bundle can be found at
20 %
21 % https://github.com/josephwright/siunitx
22 %
23 % for those people who are interested.
24 %
25 % -----------------------------------------------------------------------
26 %
27 %<*driver>
28 \documentclass{l3doc}
29 % Additional commands needed in this source
30 \ExplSyntaxOn
31 \makeatletter
32 \NewDocumentCommand \acro { m }
33 {
34 \textsc
35 {
36 \exp_args:NV \tl_if_head_eq_charcode:nNTF \f@series { m }
37 { \text_lowercase:n }
38 { \use:n }
39 {#1}
40 }
41 }
42 \makeatother
43 \ExplSyntaxOff
44 \ProvideDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
45 \ProvideDocumentCommand\foreign{m}{\textit{#1}}
46 % The next line is needed so that \GetFileInfo will be able to pick up
47 % version data
48 \usepackage{siunitx}
49 \begin{document}
50 \DocInput{\jobname.dtx}
51 \end{document}
52 %</driver>
53 % \fi
54 %
55 % \GetFileInfo{siunitx.sty}
56 %
57 % \title{^^A
58 % \pkg{siunitx-unit} -- Parsing and formatting units^^A
59 % \thanks{This file describes \fileversion,
60 % last revised \filedate.}^^A
61 % }
62 %
63 % \author{^^A
64 % Joseph Wright^^A
65 % \thanks{^^A
66 % E-mail:
67 % \email{[email protected]}^^A
68 % }^^A
69 % }
70 %
71 % \date{Released \filedate}
72 %
73 % \maketitle
74 %
75 % \begin{documentation}
76 %
77 % \section{Parsing and formatting units}
78 %
79 % This submodule is dedicated to formatting physical units. The main function,
80 % \cs{siunitx_unit_format:nN}, takes user input specifying physical units and
81 % converts it into a formatted token list suitable for typesetting in math
82 % mode. While the formatter will deal correctly with \enquote{literal} user
83 % input, the key strength of the module is providing a method to describe
84 % physical units in a \enquote{symbolic} manner. The output format of these
85 % symbolic units can then be controlled by a number of key--value options
86 % made available by the module.
87 %
88 % A small number of \LaTeXe{} math mode commands are assumed to be available
89 % as part of the formatted output. The \cs{mathchoice} command
90 % (normally the \TeX{} primitive) is needed when using different settings
91 % for inline and display |per-mode|. The commands \cs{frac}, \cs{mathrm},
92 % \cs{mbox}, \verb*|\ | and \cs{,} are used by the standard module settings.
93 % For the display of colored (highlighted) and cancelled units, the commands
94 % \cs{textcolor} and \cs{cancel} are assumed to be available.
95 %
96 % \subsection{Formatting units}
97 %
98 % \begin{function}{\siunitx_unit_format:nN, \siunitx_unit_format:VN}
99 % \begin{syntax}
100 % \cs{siunitx_unit_format:nN} \Arg{units} \meta{tl~var}
101 % \end{syntax}
102 % This function converts the input \meta{units} into a processed
103 % \meta{tl~var} which can then be inserted in math mode to typeset the
104 % material. Where the \meta{units} are given in symbolic form, described
105 % elsewhere, this formatting process takes place in two stages: the
106 % \meta{units} are parsed into a structured form before the generation
107 % of the appropriate output form based on the active settings. When the
108 % \meta{units} are given as literals, processing is minimal: the
109 % characters |.| and |~| are converted to unit products (boundaries).
110 % In both cases, the result is a series of tokens intended to be typeset
111 % in math mode with appropriate choice of font for typesetting of the
112 % textual parts.
113 %
114 % For example,
115 % \begin{verbatim}
116 % \siunitx_unit_format:nN { \kilo \metre \per \second } \l_tmpa_tl
117 % \end{verbatim}
118 % will, with standard settings, result in \cs{l_tmpa_tl} being set to
119 % \begin{verbatim}
120 % \mathrm{km}\,\mathrm{s}^{-1}
121 % \end{verbatim}
122 % \end{function}
123 %
124 % \begin{function}{\siunitx_unit_format_extract_prefixes:nNN}
125 % \begin{syntax}
126 % \cs{siunitx_unit_format_extract_prefixes:nNN} \Arg{units} \meta{tl~var} \meta{fp~var}
127 % \end{syntax}
128 % This function formats the \meta{units} in the same way as described for
129 % \cs{siunitx_unit_format:nN}. When the input is given in symbolic form,
130 % any decimal unit prefixes will be extracted and the overall power of
131 % ten that these represent will be stored in the \meta{fp~var}.
132 %
133 % For example,
134 % \begin{verbatim}
135 % \siunitx_unit_format_extract_prefixes:nNN { \kilo \metre \per \second }
136 % \l_tmpa_tl \l_tmpa_fp
137 % \end{verbatim}
138 % will, with standard settings, result in \cs{l_tmpa_tl} being set to
139 % \begin{verbatim}
140 % \mathrm{m}\,\mathrm{s}^{-1}
141 % \end{verbatim}
142 % with \cs{l_tmpa_fp} taking value~$3$. Note that the latter is a floating
143 % point variable: it is possible for non-integer values to be obtained here.
144 % \end{function}
145 %
146 % \begin{function}{\siunitx_unit_format_combine_exponent:nnN}
147 % \begin{syntax}
148 % \cs{siunitx_unit_format_combine_exponent:nnN} \Arg{units} \Arg{exponent} \meta{tl~var}
149 % \end{syntax}
150 % This function formats the \meta{units} in the same way as described for
151 % \cs{siunitx_unit_format:nN}. The \meta{exponent} is combined with any
152 % prefix for the \emph{first} unit of the \meta{units}, and an updated
153 % prefix is introduced.
154 %
155 % For example,
156 % \begin{verbatim}
157 % \siunitx_unit_format_combine_exponent:nnN { \metre \per \second }
158 % { 3 } \l_tmpa_tl
159 % \end{verbatim}
160 % will, with standard settings, result in \cs{l_tmpa_tl} being set to
161 % \begin{verbatim}
162 % \mathrm{km}\,\mathrm{s}^{-1}
163 % \end{verbatim}
164 % \end{function}
165 %
166 % \begin{function}
167 % {
168 % \siunitx_unit_format_multiply:nnN ,
169 % \siunitx_unit_format_multiply_extract_prefixes:nnNN ,
170 % \siunitx_unit_format_multiply_combine_exponent:nnnN
171 % }
172 % \begin{syntax}
173 % \cs{siunitx_unit_format_multiply:nnN} \Arg{units} \Arg{factor} \meta{tl~var}
174 % \cs{siunitx_unit_format_multiply_extract_prefixes:nnNN}
175 % \Arg{units} \Arg{factor} \meta{tl~var} \meta{fp~var}
176 % \cs{siunitx_unit_format_multiply_combine_exponent:nnnN}
177 % \Arg{units} \Arg{factor} \Arg{exponent} \meta{tl~var}
178 % \end{syntax}
179 % These function formats the \meta{units} in the same way as described for
180 % \cs{siunitx_unit_format:nN}. The units are multiplied by the \meta{factor},
181 % and further processing takes place as previously described.
182 %
183 % For example,
184 % \begin{verbatim}
185 % \siunitx_unit_format_multiply:nnN { \metre \per \second }
186 % { 3 } \l_tmpa_tl
187 % \end{verbatim}
188 % will, with standard settings, result in \cs{l_tmpa_tl} being set to
189 % \begin{verbatim}
190 % \mathrm{km}^{3}\,\mathrm{s}^{-3}
191 % \end{verbatim}
192 % \end{function}
193 %
194 % \subsection{Defining symbolic units}
195 %
196 % \begin{function}{\siunitx_declare_prefix:Nnn, \siunitx_declare_prefix:Nne}
197 % \begin{syntax}
198 % \cs{siunitx_declare_prefix:Nnn} \meta{prefix} \Arg{power} \Arg{symbol}
199 % \end{syntax}
200 % Defines a symbolic \meta{prefix} (which should be a control sequence
201 % such as |\kilo|) to be converted by the parser to the \meta{symbol}.
202 % The latter should consist of literal content (\foreign{e.g.}~|k|).
203 % In literal mode the \meta{symbol} will be typeset directly. The prefix
204 % should represent an integer \meta{power} of $10$, and this information
205 % may be used to convert from one or more \meta{prefix} symbols to an
206 % overall power applying to a unit. See also
207 % \cs{siunitx_declare_prefix:Nn}.
208 % \end{function}
209 %
210 % \begin{function}{\siunitx_declare_prefix:Nn}
211 % \begin{syntax}
212 % \cs{siunitx_declare_prefix:Nn} \meta{prefix} \Arg{symbol}
213 % \end{syntax}
214 % Defines a symbolic \meta{prefix} (which should be a control sequence
215 % such as |\kilo|) to be converted by the parser to the \meta{symbol}.
216 % The latter should consist of literal content (\foreign{e.g.}~|k|).
217 % In literal mode the \meta{symbol} will be typeset directly. In contrast
218 % to \cs{siunitx_declare_prefix:Nnn}, there is no assumption about the
219 % mathematical nature of the \meta{prefix}, \foreign{i.e.}~the prefix may
220 % represent a power of any base. As a result, no conversion of the
221 % \meta{prefix} to a numerical power will be possible.
222 % \end{function}
223 %
224 % \begin{function}{\siunitx_declare_power:NNn}
225 % \begin{syntax}
226 % \cs{siunitx_declare_power:NNn} \meta{pre-power} \meta{post-power} \Arg{value}
227 % \end{syntax}
228 % Defines \emph{two} symbolic \meta{powers} (which should be control
229 % sequences such as |\squared|) to be converted by the parser to the
230 % \meta{value}. The latter should be an integer or floating point number in
231 % the format defined for \pkg{l3fp}. Powers may precede a unit or be give
232 % after it: both forms are declared at once, as indicated by the argument
233 % naming. In literal mode, the \meta{value} will be applied as
234 % a superscript to either the next token in the input (for the
235 % \meta{pre-power}) or appended to the previously-typeset material
236 % (for the \meta{post-power}).
237 % \end{function}
238 %
239 % \begin{function}{\siunitx_declare_qualifier:Nn}
240 % \begin{syntax}
241 % \cs{siunitx_declare_qualifier:Nn} \meta{qualifier} \Arg{meaning}
242 % \end{syntax}
243 % Defines a symbolic \meta{qualifier} (which should be a control sequence
244 % such as |\catalyst|) to be converted by the parser to the \meta{meaning}.
245 % The latter should consist of literal content (\foreign{e.g.}~|cat|). In
246 % literal mode the \meta{meaning} will be typeset following a space after
247 % the unit to which it applies.
248 % \end{function}
249 %
250 % \begin{function}
251 % {
252 % \siunitx_declare_unit:Nn,
253 % \siunitx_declare_unit:Ne,
254 % \siunitx_declare_unit:Nnn,
255 % \siunitx_declare_unit:Nen
256 % }
257 % \begin{syntax}
258 % \cs{siunitx_declare_unit:Nn} \meta{unit} \Arg{meaning}
259 % \cs{siunitx_declare_unit:Nnn} \meta{unit} \Arg{meaning} \Arg{options}
260 % \end{syntax}
261 % Defines a symbolic \meta{unit} (which should be a control sequence
262 % such as |\kilogram|) to be converted by the parser to the \meta{meaning}.
263 % The latter may consist of literal content (\foreign{e.g.}~|kg|), other
264 % symbolic unit commands (\foreign{e.g.}~|\kilo\gram|) or a mixture of the
265 % two. In literal mode the \meta{meaning} will be typeset directly. The
266 % version taking an \meta{options} argument may be used to support per-unit
267 % options: these are applied at the top level or using
268 % \cs{siunitx_unit_options_apply:n}.
269 % \end{function}
270 %
271 % \begin{variable}{\l_siunitx_unit_font_tl}
272 % The font function which is applied to the text of units when constructing
273 % formatted units: set by |font-command|.
274 % \end{variable}
275 %
276 % \begin{variable}{\l_siunitx_unit_fraction_tl}
277 % The fraction function which is applied when constructing fractional units:
278 % set by |fraction-command|.
279 % \end{variable}
280 %
281 % \begin{variable}{\l_siunitx_unit_symbolic_seq}
282 % This sequence contains all of the symbolic names defined:
283 % these will be in the form of control sequences such as |\kilogram|.
284 % The order of the sequence is unimportant. This includes prefixes and
285 % powers as well as units themselves.
286 % \end{variable}
287 %
288 % \begin{variable}{\l_siunitx_unit_seq}
289 % This sequence contains all of the symbolic \emph{unit} names defined:
290 % these will be in the form of control sequences such as |\kilogram|.
291 % In contrast to \cs{l_siunitx_unit_symbolic_seq}, it \emph{only} holds
292 % units themselves
293 % \end{variable}
294 %
295 % \subsection{Per-unit options}
296 %
297 % \begin{function}{\siunitx_unit_options_declare:Nn}
298 % \begin{syntax}
299 % \cs{siunitx_unit_options_declare:Nn} \meta{unit} \Arg{options}
300 % \end{syntax}
301 % Declares that the \meta{options} should be applied with the \meta{unit}
302 % is used. The \meta{options} stored override any saved when the unit was
303 % declared. This function is intended for adjusting options when the unit
304 % command is otherwise unchanged.
305 % \end{function}
306 %
307 % \begin{function}{\siunitx_unit_options_apply:n}
308 % \begin{syntax}
309 % \cs{siunitx_unit_options_apply:n} \Arg{unit(s)}
310 % \end{syntax}
311 % Applies any unit-specific options set up using
312 % \cs{siunitx_declare_unit:Nnn}. This allows there use outside of unit
313 % formatting, for example to influence spacing in quantities. The options
314 % are applied only once at a given group level, which allows for user
315 % override \foreign{via} |\keys_set:nn { siunitx } { ... }|.
316 % \end{function}
317 %
318 % \subsection{Units in (PDF) strings}
319 %
320 % \begin{function}{\siunitx_unit_pdfstring_context:}
321 % \begin{syntax}
322 % \cs{group_begin:}
323 % \cs{siunitx_unit_pdfstring_context:}
324 % \meta{Expansion context} \meta{units}
325 % \cs{group_end:}
326 % \end{syntax}
327 % Sets symbol unit macros to generate text directly. This is needed in
328 % expansion contexts where units must be converted to simple text. This
329 % function is itself not expandable, so must be using within a
330 % surrounding group as show in the example.
331 % \end{function}
332 %
333 % \subsection{Pre-defined symbolic unit components}
334 %
335 % The unit parser is defined to recognise a number of pre-defined units,
336 % prefixes and powers, and also interpret a small selection of
337 % \enquote{generic} symbolic parts.
338 %
339 % Broadly, the pre-defined units are those defined by the \textsc{bipm} in the
340 % documentation for the \emph{International System of Units}
341 % (\acro{SI})~\cite{BIPM}. As far as possible, the names given to the command
342 % names for units are those used by the \acro{bipm}, omitting spaces and using
343 % only \acro{ASCII} characters. The standard symbols are also taken from the
344 % same documentation. In the following documentation, the order of the
345 % description of units broadly follows the \acro{SI}~Brochure.
346 %
347 % \begin{function}
348 % {
349 % \kilogram ,
350 % \metre ,
351 % \meter ,
352 % \mole ,
353 % \kelvin ,
354 % \candela ,
355 % \second ,
356 % \ampere
357 % }
358 % The base units as defined in the \acro{SI} Brochure~\cite{base-units}.
359 % Notice that \cs{meter} is defined as an alias for \cs{metre} as the former
360 % spelling is common in the US (although the latter is the official spelling).
361 % \end{function}
362 %
363 % \begin{function}{\gram}
364 % The base unit \cs{kilogram} is defined using an \acro{SI} prefix: as such
365 % the (derived) unit \cs{gram} is required by the module to correctly produce
366 % output for the \cs{kilogram}.
367 % \end{function}
368 %
369 % \begin{function}
370 % {
371 % \quecto ,
372 % \ronto ,
373 % \yocto ,
374 % \zepto ,
375 % \atto ,
376 % \femto ,
377 % \pico ,
378 % \nano ,
379 % \micro ,
380 % \milli ,
381 % \centi ,
382 % \deci ,
383 % \deca ,
384 % \deka ,
385 % \hecto ,
386 % \kilo ,
387 % \mega ,
388 % \giga ,
389 % \tera ,
390 % \peta ,
391 % \exa ,
392 % \zetta ,
393 % \yotta ,
394 % \ronna ,
395 % \quetta
396 % }
397 % Prefixes, all of which are integer powers of $10$: the powers are stored
398 % internally by the module and can be used for conversion from prefixes to
399 % their numerical equivalent. These prefixes are documented in Section~3.1
400 % of the \acro{SI}~Brochure.
401 %
402 % Note that the \cs{kilo} prefix is required to
403 % define the base \cs{kilogram} unit. Also note the two spellings available
404 % for \cs{deca}/\cs{deka}.
405 % \end{function}
406 %
407 % \begin{function}
408 % {
409 % \becquerel ,
410 % \degreeCelsius ,
411 % \coulomb ,
412 % \farad ,
413 % \gray ,
414 % \hertz ,
415 % \henry ,
416 % \joule ,
417 % \katal ,
418 % \lumen ,
419 % \lux ,
420 % \newton ,
421 % \ohm ,
422 % \pascal ,
423 % \radian ,
424 % \siemens ,
425 % \sievert ,
426 % \steradian ,
427 % \tesla ,
428 % \volt ,
429 % \watt ,
430 % \weber
431 % }
432 % The defined \acro{SI}~units with defined names and symbols, as given in
433 % Table~4 of the \acro{SI}~Brochure. Notice that the names
434 % of the units are lower case with the exception of \cs{degreeCelsius}, and
435 % that this unit name includes \enquote{degree}.
436 % \end{function}
437 %
438 % \begin{function}
439 % {
440 % \astronomicalunit ,
441 % \bel ,
442 % \dalton ,
443 % \day ,
444 % \decibel ,
445 % \electronvolt ,
446 % \hectare ,
447 % \hour ,
448 % \litre ,
449 % \liter ,
450 % \neper ,
451 % \minute ,
452 % \tonne
453 % }
454 % Units accepted for use with the \acro{SI}: here \cs{minute} is a unit of
455 % time not of plane angle. These units are taken from Table~8 of the
456 % \acro{SI}~Brochure.
457 %
458 % For the unit \cs{litre}, both |l| and |L| are listed
459 % as acceptable symbols: the latter is the standard setting of the module.
460 % The alternative spelling \cs{liter} is also given for this unit for US
461 % users (as with \cs{metre}, the official spelling is \enquote{re}).
462 % \end{function}
463 %
464 % \begin{function}
465 % {
466 % \arcminute ,
467 % \arcsecond ,
468 % \degree
469 % }
470 % Units for plane angles accepted for use with the \acro{SI}: to avoid a
471 % clash with units for time, here \cs{arcminute} and \cs{arcsecond} are
472 % used in place of \cs{minute} and \cs{second}. These units are taken from
473 % Table~8 of the \acro{SI}~Brochure.
474 % \end{function}
475 %
476 % \begin{function}{\percent}
477 % The mathematical concept of percent, usable with the \acro{SI} as detailed
478 % in Section~5.4.7 of the \acro{SI}~Brochure.
479 % \end{function}
480 %
481 % \begin{function}{\square, \cubic}
482 % \begin{syntax}
483 % \cs{square} \meta{prefix} \meta{unit}
484 % \cs{cubic} \meta{prefix} \meta{unit}
485 % \end{syntax}
486 % Pre-defined unit powers which apply to the next \meta{prefix}/\meta{unit}
487 % combination.
488 % \end{function}
489 %
490 % \begin{function}{\squared, \cubed}
491 % \begin{syntax}
492 % \meta{prefix} \meta{unit} \cs{squared}
493 % \meta{prefix} \meta{unit} \cs{cubed}
494 % \end{syntax}
495 % Pre-defined unit powers which apply to the preceding
496 % \meta{prefix}/\meta{unit} combination.
497 % \end{function}
498 %
499 % \begin{function}{\per}
500 % \begin{syntax}
501 % \cs{per} \meta{prefix} \meta{unit} \meta{power}
502 % \end{syntax}
503 % Indicates that the next \meta{prefix}/\meta{unit}/\meta{power} combination
504 % is reciprocal, \foreign{i.e.}~raises it to the power $-1$. This symbolic
505 % representation may be applied in addition to a \cs{power}, and will work
506 % correctly if the \cs{power} itself is negative. In literal mode \cs{per}
507 % will print a slash (\enquote{$/$}).
508 % \end{function}
509 %
510 % \begin{function}{\cancel}
511 % \begin{syntax}
512 % \cs{cancel} \meta{prefix} \meta{unit} \meta{power}
513 % \end{syntax}
514 % Indicates that the next \meta{prefix}/\meta{unit}/\meta{power} combination
515 % should be \enquote{cancelled out}. In the parsed output, the entire unit
516 % combination will be given as the argument to a function \cs{cancel}, which
517 % is assumed to be available at a higher level. In literal mode, the same
518 % higher-level \cs{cancel} will be applied to the next token. It is the
519 % responsibility of the calling code to provide an appropriate definition
520 % for \cs{cancel} outside of the scope of the unit parser.
521 % \end{function}
522 %
523 % \begin{function}{\highlight}
524 % \begin{syntax}
525 % \cs{highlight} \Arg{color} \meta{prefix} \meta{unit} \meta{power}
526 % \end{syntax}
527 % Indicates that the next \meta{prefix}/\meta{unit}/\meta{power} combination
528 % should be highlighted in the specified \meta{color}. In the parsed output,
529 % the entire unit combination will be given as the argument to a function
530 % \cs{textcolor}, which is assumed to be available at a higher level. In
531 % literal mode, the same higher-level \cs{textcolor} will be applied to the
532 % next token. It is the responsibility of the calling code to provide an
533 % appropriate definition for \cs{textcolor} outside of the scope of the unit
534 % parser.
535 % \end{function}
536 %
537 % \begin{function}{\of}
538 % \begin{syntax}
539 % \meta{prefix} \meta{unit} \meta{power} \cs{of} \Arg{qualifier}
540 % \end{syntax}
541 % Indicates that the \meta{qualifier} applies to the current
542 % \meta{prefix}/\meta{unit}/\meta{power} combination. In parsed mode, the
543 % display of the result will depend upon module options. In literal mode,
544 % the \meta{qualifier} will be printed in parentheses following the preceding
545 % \meta{unit} and a full-width space.
546 % \end{function}
547 %
548 % \begin{function}{\raiseto, \tothe}
549 % \begin{syntax}
550 % \cs{raiseto} \Arg{power} \meta{prefix} \meta{unit}
551 % \meta{prefix} \meta{unit} \cs{tothe} \Arg{power}
552 % \end{syntax}
553 % Indicates that the \meta{power} applies to the current
554 % \meta{prefix}/\meta{unit} combination. As shown, \cs{raiseto} applies to
555 % the next \meta{unit} whereas \cs{tothe} applies to the preceding unit. In
556 % literal mode the \cs{power} will be printed as a superscript attached to
557 % the next token (\cs{raiseto}) or preceding token (\cs{tothe}) as
558 % appropriate.
559 % \end{function}
560 %
561 % \subsection{Key--value options for units}
562 %
563 % \begin{function}{bracket-unit-denominator}
564 % \begin{syntax}
565 % |bracket-unit-denominator| = |true|\verb"|"|false|
566 % \end{syntax}
567 % Switch to determine whether brackets are added to the denominator part of
568 % a unit when printed using inline fractional form (with |per-mode| as
569 % |repeated-symbol| or |symbol|). The standard setting is |true|.
570 % \end{function}
571 %
572 % \begin{function}{extract-mass-in-kilograms}
573 % \begin{syntax}
574 % |extract-mass-in-kilograms| = |true|\verb"|"|false|
575 % \end{syntax}
576 % Determines whether prefix extraction treats kilograms as a base unit; when
577 % set |false|, grams are used. The standard setting is |true|.
578 % \end{function}
579 %
580 % \begin{function}{forbid-literal-units}
581 % \begin{syntax}
582 % |forbid-literal-units| = |true|\verb"|"|false|
583 % \end{syntax}
584 % Switch which determines if literal units are allowed when parsing is
585 % active; does not apply when |parse-units| is |false|.
586 % \end{function}
587 %
588 % \begin{function}{fraction-command}
589 % \begin{syntax}
590 % |fraction-command| = \meta{command}
591 % \end{syntax}
592 % Command used to create fractional output when |per-mode| is set to
593 % |fraction|. The standard setting is |\frac|.
594 % \end{function}
595 %
596 % \begin{function}{inter-unit-product}
597 % \begin{syntax}
598 % |inter-unit-product| = \meta{separator}
599 % \end{syntax}
600 % Inserted between unit combinations in parsed mode, and used to replace
601 % |.| and |~| in literal mode. The standard setting is |\,|.
602 % \end{function}
603 %
604 % \begin{function}{parse-units}
605 % \begin{syntax}
606 % |parse-units| = |true|\verb"|"|false|
607 % \end{syntax}
608 % Determines whether parsing of unit symbols is attempted or literal
609 % mode is used directly. The standard setting is |true|.
610 % \end{function}
611 %
612 % \begin{function}{per-mode, inline-per-mode, display-per-mode}
613 % \begin{syntax}
614 % |per-mode| = |fraction|\verb"|"|power|\verb"|"|power-positive-first|\verb"|"|repeated-symbol|\verb"|"|single-symbol|\verb"|"|symbol|
615 % \end{syntax}
616 % Selects how the negative powers (\cs{per}) are formatted: a choice from
617 % the options |fraction|, |power|, |power-positive-first|, |repeated-symbol|,
618 % |single-symbol| and |symbol|. The option |fraction|
619 % generates fractional output when appropriate using the command specified by
620 % the |fraction-command| option. The setting |power| uses reciprocal powers
621 % leaving the units in the order of input, while |power-positive-first| uses
622 % the same display format but sorts units such that the positive powers
623 % come before negative ones. The |symbol| setting uses a symbol (specified
624 % by |per-symbol|) between positive and negative powers, while
625 % |repeated-symbol| uses the same symbol but places it before \emph{every}
626 % unit with a negative power (this is mathematically \enquote{wrong} but
627 % often seen in real work). The option |single-symbol| will use a symbol if
628 % exactly one is required (\foreign{i.e.}~with a single negative power), and
629 % will otherwise use powers. The standard setting is |power|.
630 %
631 % The |inline-...| and |display-...| settings take the same options and work
632 % in exactly the same way, but are restricted in where they apply. The
633 % |display| version only applies in display math contexts, and the |inline|
634 % version applies in all others.
635 % \end{function}
636 %
637 % \begin{function}{per-symbol}
638 % \begin{syntax}
639 % |per-symbol| = \meta{symbol}
640 % \end{syntax}
641 % Specifies the symbol to be used to denote negative powers when the option
642 % |per-mode| is set to |repeated-symbol| or |symbol|. The standard setting
643 % is |/|.
644 % \end{function}
645 %
646 % \begin{function}{per-symbol-script-correction}
647 % \begin{syntax}
648 % |per-symbol-script-correction| = \meta{insert}
649 % \end{syntax}
650 % Specifies the tokens used to correct spacing when the symbol set by
651 % |per-symbol| is immediately preceded by a superscript power. The
652 % standard setting is |\!|.
653 % \end{function}
654 %
655 % \begin{function}{power-half-as-sqrt}
656 % \begin{syntax}
657 % |power-half-as-sqrt| = |true|\verb"|"|false|
658 % \end{syntax}
659 % Used to determine whether a power of exactly half is converted to
660 % \cs{sqrt} in the output. The standard setting is |false|.
661 % \end{function}
662 %
663 % \begin{function}{qualifier-mode}
664 % \begin{syntax}
665 % |qualifier-mode| = |bracket|\verb"|"|combine|\verb"|"|phrase|\verb"|"|subscript|
666 % \end{syntax}
667 % Selects how qualifiers are formatted: a choice from the options |bracket|,
668 % |combine|, |phrase| and |subscript|. The option |bracket| wraps the
669 % qualifier in parenthesis, |combine| joins the qualifier with the unit
670 % directly, |phrase| joins the material using |qualifier-phrase| as a link,
671 % and |subscript| formats the qualifier as a subscript. The standard setting
672 % is |subscript|.
673 % \end{function}
674 %
675 % \begin{function}{qualifier-phrase}
676 % \begin{syntax}
677 % |qualifier-phrase| = \meta{phrase}
678 % \end{syntax}
679 % Defines the \meta{phrase} used when |qualifier-mode| is set to |phrase|.
680 % \end{function}
681 %
682 % \begin{function}{sticky-per}
683 % \begin{syntax}
684 % |sticky-per| = |true|\verb"|"|false|
685 % \end{syntax}
686 % Used to determine whether \cs{per} should be applied one a unit-by-unit
687 % basis (when |false|) or should apply to all following units
688 % (when |true|). The latter mode is somewhat akin conceptually to the
689 % \TeX{} \cs{over} primitive. The standard setting is |false|.
690 % \end{function}
691 %
692 % \begin{function}{unit-font-command}
693 % \begin{syntax}
694 % |unit-font-command| = \meta{command}
695 % \end{syntax}
696 % Command applied to text during output of units: should be command usable
697 % in math mode for font selection. Notice that in a typical unit this does
698 % not (necessarily) apply to all output, for example powers or brackets.
699 % The standard setting is |\mathrm|.
700 % \end{function}
701 %
702 % \end{documentation}
703 %
704 % \begin{implementation}
705 %
706 % \section{\pkg{siunitx-unit} implementation}
707 %
708 % Start the \pkg{DocStrip} guards.
709 % \begin{macrocode}
710 %<*package>
711 % \end{macrocode}
712 %
713 % Identify the internal prefix.
714 % \begin{macrocode}
715 %<@@=siunitx_unit>
716 % \end{macrocode}
717 %
718 % \subsection{Initial set up}
719 %
720 % The mechanisms defined here need a few variables to exist and to be
721 % correctly set: these don't belong to one subsection and so are created
722 % in a small general block.
723 %
724 % \begin{variable}{\l_@@_tmp_bool}
725 % \begin{variable}{\l_@@_tmp_fp}
726 % \begin{variable}{\l_@@_tmp_int}
727 % \begin{variable}{\l_@@_tmp_tl}
728 % Scratch space.
729 % \begin{macrocode}
730 \bool_new:N \l_@@_tmp_bool
731 \fp_new:N \l_@@_tmp_fp
732 \int_new:N \l_@@_tmp_int
733 \tl_new:N \l_@@_tmp_tl
734 % \end{macrocode}
735 % \end{variable}
736 % \end{variable}
737 % \end{variable}
738 % \end{variable}
739 %
740 % \begin{variable}{\c_@@_math_subscript_tl}
741 % Useful tokens with awkward category codes.
742 % \begin{macrocode}
743 \tl_const:Ne \c_@@_math_subscript_tl
744 { \char_generate:nn { `\_ } { 8 } }
745 % \end{macrocode}
746 % \end{variable}
747 %
748 % \begin{variable}{\l_@@_parsing_bool}
749 % A boolean is used to indicate when the symbolic unit functions should
750 % produce symbolic or literal output. This is used when the symbolic names
751 % are used along with literal input, and ensures that there is a sensible
752 % fall-back for these cases.
753 % \begin{macrocode}
754 \bool_new:N \l_@@_parsing_bool
755 % \end{macrocode}
756 % \end{variable}
757 %
758 % \begin{variable}{\l_@@_test_bool}
759 % A switch used to indicate that the code is testing the input to find
760 % if there is any typeset output from individual unit macros. This is needed
761 % to allow the \enquote{base} macros to be found, and also to pick up the
762 % difference between symbolic and literal unit input.
763 % \begin{macrocode}
764 \bool_new:N \l_@@_test_bool
765 % \end{macrocode}
766 % \end{variable}
767 %
768 % \begin{macro}{\@@_if_symbolic:nTF}
769 % The test for symbolic units is needed in two places. First, there is the
770 % case of \enquote{pre-parsing} input to check if it can be parsed. Second,
771 % when parsing there is a need to check if the current unit is built up
772 % from others (symbolic) or is defined in terms of some literals. To do this,
773 % the approach used is to set all of the symbolic unit commands expandable
774 % and to do nothing, with the few special cases handled manually. We expand
775 % the input here twice: this handles the case where there is a mapping or
776 % similar in |#1| which returns its result in \cs{exp_not:n}. In the second
777 % \tn{protected@edef}, changing the meaning of \tn{@unexpandable@protect}
778 % allows removal of a literal \cs{protect} at the top level before
779 % known symbolic entries: this deals with the case where the user has
780 % put in a \cs{protect} for some edge cases.
781 % \begin{macrocode}
782 \prg_new_protected_conditional:Npnn \@@_if_symbolic:n #1 { TF }
783 {
784 \group_begin:
785 \bool_set_true:N \l_@@_test_bool
786 \protected@edef \l_@@_tmp_tl {#1}
787 \cs_set_eq:NN \@@_saved_@unexpandable@protect: \@unexpandable@protect
788 \cs_set_nopar:Npn \@unexpandable@protect ##1
789 {
790 \cs_if_exist:cF { @@_ \token_to_str:N ##1 :w }
791 { \@@_saved_@unexpandable@protect: }
792 ##1
793 }
794 \protected@edef \l_@@_tmp_tl { \l_@@_tmp_tl }
795 \exp_args:NNV \group_end:
796 \tl_if_blank:nTF \l_@@_tmp_tl
797 { \prg_return_true: }
798 { \prg_return_false: }
799 }
800 % \end{macrocode}
801 % \end{macro}
802 %
803 % \subsection{Defining symbolic unit}
804 %
805 % Unit macros and related support are created here. These exist only within
806 % the scope of the unit processor code, thus not polluting document-level
807 % namespace and allowing overlap with other areas in the case of useful short
808 % names (for example \cs{pm}). Setting up the mechanisms to allow this requires
809 % a few additional steps on top of simply saving the data given by the user
810 % in creating the unit.
811 %
812 % \begin{variable}{\l_siunitx_unit_symbolic_seq}
813 % A list of all of the symbolic units, \foreign{etc.}, set up. This is needed
814 % to allow the symbolic names to be defined within the scope of the unit
815 % parser but not elsewhere using simple mappings.
816 % \begin{macrocode}
817 \seq_new:N \l_siunitx_unit_symbolic_seq
818 % \end{macrocode}
819 % \end{variable}
820 %
821 % \begin{variable}{\l_siunitx_unit_seq}
822 % A second list featuring only the units themselves.
823 % \begin{macrocode}
824 \seq_new:N \l_siunitx_unit_seq
825 % \end{macrocode}
826 % \end{variable}
827 %
828 % \begin{macro}{\@@_set_symbolic:Nnn}
829 % \begin{macro}{\@@_set_symbolic:Npnn}
830 % \begin{macro}{\@@_set_symbolic:Nnnn}
831 % The majority of the work for saving each symbolic definition is the same
832 % irrespective of the item being defined (unit, prefix, power, qualifier).
833 % This is therefore all carried out in a single internal function which
834 % does the common tasks. The three arguments here are the symbolic macro
835 % name, the literal output and the code to insert when doing full unit
836 % parsing. To allow for the \enquote{special cases} (where arguments are
837 % required) the entire mechanism is set up in a two-part fashion allowing
838 % for flexibility at the slight cost of additional functions.
839 %
840 % Importantly, notice that the unit macros are declared as expandable. This
841 % is required so that literals can be correctly converted into a token list
842 % of material which does not depend on local redefinitions for the unit
843 % macros. That is required so that the unit formatting system can be grouped.
844 % \begin{macrocode}
845 \cs_new_protected:Npn \@@_set_symbolic:Nnn #1
846 { \@@_set_symbolic:Nnnn #1 { } }
847 \cs_new_protected:Npn \@@_set_symbolic:Npnn #1#2#
848 { \@@_set_symbolic:Nnnn #1 {#2} }
849 \cs_new_protected:Npn \@@_set_symbolic:Nnnn #1#2#3#4
850 {
851 \seq_put_right:Nn \l_siunitx_unit_symbolic_seq {#1}
852 \cs_set:cpn { @@_ \token_to_str:N #1 :w } #2
853 {
854 \bool_if:NF \l_@@_test_bool
855 {
856 \bool_if:NTF \l_@@_parsing_bool
857 {#4}
858 {#3}
859 }
860 }
861 }
862 % \end{macrocode}
863 % \end{macro}
864 % \end{macro}
865 % \end{macro}
866 %
867 % \begin{macro}{\siunitx_declare_power:NNn}
868 % Powers can come either before or after the unit. As they always come
869 % (logically) in matching, we handle this by declaring two commands,
870 % and setting each up separately.
871 % \begin{macrocode}
872 \cs_new_protected:Npn \siunitx_declare_power:NNn #1#2#3
873 {
874 \@@_set_symbolic:Nnn #1
875 { \@@_literal_power:nn {#3} }
876 { \@@_parse_power:nnN {#1} {#3} \c_true_bool }
877 \@@_set_symbolic:Nnn #2
878 { ^ {#3} }
879 { \@@_parse_power:nnN {#2} {#3} \c_false_bool }
880 }
881 % \end{macrocode}
882 % \end{macro}
883 %
884 % \begin{macro}{\siunitx_declare_prefix:Nn}
885 % \begin{macro}{\siunitx_declare_prefix:Nnn, \siunitx_declare_prefix:Nne}
886 % \begin{variable}
887 % {\l_@@_prefixes_forward_prop, \l_@@_prefixes_reverse_prop}
888 % For prefixes there are a couple of options. In all cases, the basic
889 % requirement is to set up to parse the prefix using the appropriate
890 % internal function. For prefixes which are powers of $10$, there is also
891 % the need to be able to do conversion to/from the numerical equivalent.
892 % That is handled using two properly lists which can be used to supply
893 % the conversion data later.
894 % \begin{macrocode}
895 \cs_new_protected:Npn \siunitx_declare_prefix:Nn #1#2
896 {
897 \@@_set_symbolic:Nnn #1
898 {#2}
899 { \@@_parse_prefix:Nn #1 {#2} }
900 }
901 \cs_new_protected:Npn \siunitx_declare_prefix:Nnn #1#2#3
902 {
903 \siunitx_declare_prefix:Nn #1 {#3}
904 \prop_put:Nnn \l_@@_prefixes_forward_prop {#3} {#2}
905 \prop_put:Nnn \l_@@_prefixes_reverse_prop {#2} {#3}
906 }
907 \cs_generate_variant:Nn \siunitx_declare_prefix:Nnn { Nne , Nnx }
908 \prop_new:N \l_@@_prefixes_forward_prop
909 \prop_new:N \l_@@_prefixes_reverse_prop
910 % \end{macrocode}
911 % \end{variable}
912 % \end{macro}
913 % \end{macro}
914 %
915 % \begin{macro}{\siunitx_declare_qualifier:Nn}
916 % Qualifiers are relatively easy to handle: nothing to do other than save
917 % the input appropriately.
918 % \begin{macrocode}
919 \cs_new_protected:Npn \siunitx_declare_qualifier:Nn #1#2
920 {
921 \@@_set_symbolic:Nnn #1
922 { ~ ( #2 ) }
923 { \@@_parse_qualifier:nn {#1} {#2} }
924 }
925 % \end{macrocode}
926 % \end{macro}
927 %
928 % \begin{macro}{\siunitx_declare_unit:Nn, \siunitx_declare_unit:Ne}
929 % \begin{macro}{\siunitx_declare_unit:Nnn, \siunitx_declare_unit:Nen}
930 % For the unit parsing, allowing for variations in definition order requires
931 % that a test is made for the output of each unit at point of use.
932 % \begin{macrocode}
933 \cs_new_protected:Npn \siunitx_declare_unit:Nn #1#2
934 { \siunitx_declare_unit:Nnn #1 {#2} { } }
935 \cs_generate_variant:Nn \siunitx_declare_unit:Nn { Ne , Nx }
936 \cs_new_protected:Npn \siunitx_declare_unit:Nnn #1#2#3
937 {
938 \seq_put_right:Nn \l_siunitx_unit_seq {#1}
939 \@@_set_symbolic:Nnn #1
940 {#2}
941 {
942 \@@_if_symbolic:nTF {#2}
943 {#2}
944 { \@@_parse_unit:Nn #1 {#2} }
945 }
946 \siunitx_unit_options_declare:Nn #1 {#3}
947 }
948 \cs_generate_variant:Nn \siunitx_declare_unit:Nnn { Ne , Nx }
949 % \end{macrocode}
950 % \end{macro}
951 % \end{macro}
952 %
953 % \subsection{Applying unit options}
954 %
955 % \begin{macro}{\siunitx_unit_options_declare:Nn}
956 % For setting options for existing units without needing to alter the
957 % symbol.
958 % \begin{macrocode}
959 \cs_new_protected:Npn \siunitx_unit_options_declare:Nn #1#2
960 {
961 \tl_clear_new:c { l_@@_options_ \token_to_str:N #1 _tl }
962 \tl_set:cn { l_@@_options_ \token_to_str:N #1 _tl } {#2}
963 }
964 % \end{macrocode}
965 % \end{macro}
966 %
967 % \begin{variable}{\l_@@_active_opts_str}
968 % Tracks which unit, if any, is currently \enquote{live} for applied
969 % options.
970 % \begin{macrocode}
971 \str_new:N \l_@@_active_opts_str
972 % \end{macrocode}
973 % \end{variable}
974 %
975 % \begin{macro}{\siunitx_unit_options_apply:n}
976 % Options apply only if they have not already been set at this group
977 % level.
978 % \begin{macrocode}
979 \cs_new_protected:Npn \siunitx_unit_options_apply:n #1
980 {
981 \tl_if_single_token:nT {#1}
982 {
983 \tl_if_exist:cT { l_@@_options_ \token_to_str:N #1 _tl }
984 {
985 \str_if_eq:VnF \l_@@_active_opts_str {#1}
986 {
987 \keys_set:nv { siunitx }
988 { l_@@_options_ \token_to_str:N #1 _tl }
989 \str_set:Nn \l_@@_active_opts_str {#1}
990 }
991 }
992 }
993 }
994 % \end{macrocode}
995 % \end{macro}
996 %
997 % \subsection{Non-standard symbolic units}
998 %
999 % A few of the symbolic units require non-standard definitions: these are
1000 % created here. They all use parts of the more general code but have particular
1001 % requirements which can only be addressed by hand. Some of these could in
1002 % principle be used in place of the dedicated definitions above, but at point
1003 % of use that would then require additional expansions for each unit parsed:
1004 % as the macro names would still be needed, this does not offer any real
1005 % benefits.
1006 %
1007 % \begin{macro}{\per}
1008 % The \cs{per} symbolic unit is a bit special: it has a mechanism entirely
1009 % different from everything else, so has to be set up by hand. In literal
1010 % mode it is represented by a very simple symbol!
1011 % \begin{macrocode}
1012 \@@_set_symbolic:Nnn \per
1013 { / }
1014 { \@@_parse_per: }
1015 % \end{macrocode}
1016 % \end{macro}
1017 %
1018 % \begin{macro}{\cancel}
1019 % \begin{macro}{\highlight}
1020 % The two special cases, \cs{cancel} and \cs{highlight}, are easy to deal
1021 % with when parsing. When not parsing, a precaution is taken to ensure that
1022 % the user level equivalents always get a braced argument.
1023 % \begin{macrocode}
1024 \@@_set_symbolic:Npnn \cancel
1025 { }
1026 { \@@_parse_special:n { \cancel } }
1027 \@@_set_symbolic:Npnn \highlight #1
1028 { \@@_literal_special:nN { \textcolor {#1} } }
1029 { \@@_parse_special:n { \textcolor {#1} } }
1030 % \end{macrocode}
1031 % \end{macro}
1032 % \end{macro}
1033 %
1034 % \begin{macro}{\of}
1035 % The generic qualifier is simply the same as the dedicated ones except for
1036 % needing to grab an argument.
1037 % \begin{macrocode}
1038 \@@_set_symbolic:Npnn \of #1
1039 { \ ( #1 ) }
1040 { \@@_parse_qualifier:nn { \of {#1} } {#1} }
1041 % \end{macrocode}
1042 % \end{macro}
1043 %
1044 % \begin{macro}{\raiseto, \tothe}
1045 % Generic versions of the pre-defined power macros. These require an
1046 % argument and so cannot be handled using the general approach. Other than
1047 % that, the code here is very similar to that in
1048 % \cs{siunitx_unit_power_set:NnN}.
1049 % \begin{macrocode}
1050 \@@_set_symbolic:Npnn \raiseto #1
1051 { \@@_literal_power:nn {#1} }
1052 { \@@_parse_power:nnN { \raiseto {#1} } {#1} \c_true_bool }
1053 \@@_set_symbolic:Npnn \tothe #1
1054 { ^ {#1} }
1055 { \@@_parse_power:nnN { \tothe {#1} } {#1} \c_false_bool }
1056 % \end{macrocode}
1057 % \end{macro}
1058 %
1059 % \subsection{Main formatting routine}
1060 %
1061 % Unit input can take two forms, \enquote{literal} units (material to be
1062 % typeset directly) or \enquote{symbolic} units (macro-based). Before any
1063 % parsing or typesetting is carried out, a small amount of pre-parsing has to
1064 % be carried out to decide which of these cases applies.
1065 %
1066 % \begin{variable}
1067 % {\l_siunitx_unit_font_tl, \l_@@_product_tl, \l_@@_mass_kilogram_bool}
1068 % Options which apply to the main formatting routine, and so are not tied
1069 % to either symbolic or literal input.
1070 % \begin{macrocode}
1071 \keys_define:nn { siunitx }
1072 {
1073 extract-mass-in-kilograms .bool_set:N =
1074 \l_@@_mass_kilogram_bool ,
1075 inter-unit-product .tl_set:N =
1076 \l_@@_product_tl ,
1077 unit-font-command .tl_set:N =
1078 \l_siunitx_unit_font_tl
1079 }
1080 % \end{macrocode}
1081 % \end{variable}
1082 %
1083 % \begin{variable}{\l_@@_formatted_tl}
1084 % A token list for the final formatted result: may or may not be generated
1085 % by the parser, depending on the nature of the input.
1086 % \begin{macrocode}
1087 \tl_new:N \l_@@_formatted_tl
1088 % \end{macrocode}
1089 % \end{variable}
1090 %
1091 % \begin{macro}{\siunitx_unit_format:nN, \siunitx_unit_format:VN}
1092 % \begin{macro}{\siunitx_unit_format_extract_prefixes:nNN}
1093 % \begin{macro}{\siunitx_unit_format_combine_exponent:nnN}
1094 % \begin{macro}{\siunitx_unit_format_multiply:nnN}
1095 % \begin{macro}{\siunitx_unit_format_multiply_extract_prefixes:nnNN}
1096 % \begin{macro}{\siunitx_unit_format_multiply_combine_exponent:nnnN}
1097 % \begin{macro}{\@@_format:nNN}
1098 % \begin{macro}{\@@_format_aux:}
1099 % Formatting parsed units can take place either with the prefixes printed or
1100 % separated out into a power of ten. This variation is handled using two
1101 % separate functions: as this submodule does not really deal with numbers,
1102 % formatting the numeral part here would be tricky and it is better therefore
1103 % to have a mechanism to return a simple numerical power. At the same time,
1104 % most uses will no want this more complex return format and so a version of
1105 % the code which does not do this is also provided.
1106 %
1107 % The main unit formatting routine groups all of the parsing/formatting, so
1108 % that the only value altered will be the return token list. As definitions
1109 % for the various unit macros are not globally created, the first step is to
1110 % map over the list of names and active the unit definitions: these do
1111 % different things depending on the switches set. There is then a decision to
1112 % be made: is the unit input one that can be parsed (\enquote{symbolic}), or
1113 % is one containing one or more literals. In the latter case, there is a
1114 % still the need to convert the input into an expanded token list as some
1115 % parts of the input could still be using unit macros.
1116 %
1117 % Notice that for \cs{siunitx_unit_format:nN} a second return value from the
1118 % auxiliary has to be allowed for, but is simply discarded.
1119 % \begin{macrocode}
1120 \cs_new_protected:Npn \siunitx_unit_format:nN #1#2
1121 {
1122 \bool_set_false:N \l_@@_prefix_exp_bool
1123 \fp_zero:N \l_@@_combine_exp_fp
1124 \fp_set:Nn \l_@@_multiple_fp { \c_one_fp }
1125 \@@_format:nNN {#1} #2 \l_@@_tmp_fp
1126 }
1127 \cs_generate_variant:Nn \siunitx_unit_format:nN { V }
1128 \cs_new_protected:Npn \siunitx_unit_format_extract_prefixes:nNN #1#2#3
1129 {
1130 \bool_set_true:N \l_@@_prefix_exp_bool
1131 \fp_zero:N \l_@@_combine_exp_fp
1132 \fp_set:Nn \l_@@_multiple_fp { \c_one_fp }
1133 \@@_format:nNN {#1} #2 #3
1134 }
1135 \cs_new_protected:Npn \siunitx_unit_format_combine_exponent:nnN #1#2#3
1136 {
1137 \bool_set_false:N \l_@@_prefix_exp_bool
1138 \fp_set:Nn \l_@@_combine_exp_fp {#2}
1139 \fp_set:Nn \l_@@_multiple_fp { \c_one_fp }
1140 \@@_format:nNN {#1} #3 \l_@@_tmp_fp
1141 }
1142 \cs_new_protected:Npn \siunitx_unit_format_multiply:nnN #1#2#3
1143 {
1144 \bool_set_false:N \l_@@_prefix_exp_bool
1145 \fp_zero:N \l_@@_combine_exp_fp
1146 \fp_set:Nn \l_@@_multiple_fp {#2}
1147 \@@_format:nNN {#1} #3 \l_@@_tmp_fp
1148 }
1149 \cs_new_protected:Npn \siunitx_unit_format_multiply_extract_prefixes:nnNN
1150 #1#2#3#4
1151 {
1152 \bool_set_true:N \l_@@_prefix_exp_bool
1153 \fp_zero:N \l_@@_combine_exp_fp
1154 \fp_set:Nn \l_@@_multiple_fp {#2}
1155 \@@_format:nNN {#1} #3 #4
1156 }
1157 \cs_new_protected:Npn \siunitx_unit_format_multiply_combine_exponent:nnnN
1158 #1#2#3#4
1159 {
1160 \bool_set_false:N \l_@@_prefix_exp_bool
1161 \fp_set:Nn \l_@@_combine_exp_fp {#3}
1162 \fp_set:Nn \l_@@_multiple_fp {#2}
1163 \@@_format:nNN {#1} #4 \l_@@_tmp_fp
1164 }
1165 \cs_new_protected:Npn \@@_format:nNN #1#2#3
1166 {
1167 \group_begin:
1168 \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
1169 { \cs_set_eq:Nc ##1 { @@_ \token_to_str:N ##1 :w } }
1170 \tl_clear:N \l_@@_formatted_tl
1171 \fp_zero:N \l_@@_prefix_fp
1172 \bool_if:NTF \l_@@_parse_bool
1173 {
1174 \@@_if_symbolic:nTF {#1}
1175 {
1176 \@@_parse:n {#1}
1177 \prop_if_empty:NF \l_@@_parsed_prop
1178 { \@@_format_parsed: }
1179 }
1180 {
1181 \bool_if:NTF \l_@@_forbid_literal_bool
1182 { \msg_error:nnn { siunitx } { literal-unit } {#1} }
1183 { \@@_format_literal:n {#1} }
1184 }
1185 }
1186 { \@@_format_literal:n {#1} }
1187 \cs_set_protected:Npe \@@_format_aux:
1188 {
1189 \tl_set:Nn \exp_not:N #2
1190 { \exp_not:V \l_@@_formatted_tl }
1191 \fp_set:Nn \exp_not:N #3
1192 { \fp_use:N \l_@@_prefix_fp }
1193 }
1194 \exp_after:wN \group_end:
1195 \@@_format_aux:
1196 }
1197 \cs_new_protected:Npn \@@_format_aux: { }
1198 % \end{macrocode}
1199 % \end{macro}
1200 % \end{macro}
1201 % \end{macro}
1202 % \end{macro}
1203 % \end{macro}
1204 % \end{macro}
1205 % \end{macro}
1206 % \end{macro}
1207 %
1208 % \subsection{Formatting literal units}
1209 %
1210 % While in literal mode no parsing occurs, there is a need to provide a few
1211 % auxiliary functions to handle one or two special cases.
1212 %
1213 % \begin{macro}[EXP]{\@@_literal_power:nn}
1214 % For printing literal units which are given before the unit they apply to,
1215 % there is a slight rearrangement. This is ex[EXP]pandable to cover the case
1216 % of creation of a PDF string.
1217 % \begin{macrocode}
1218 \cs_new:Npn \@@_literal_power:nn #1#2 { #2 ^ {#1} }
1219 % \end{macrocode}
1220 % \end{macro}
1221 %
1222 % \begin{macro}{\@@_literal_special:nN}
1223 % When dealing with the special cases, there is an argument to absorb. This
1224 % should be braced to be passed up to the user level, which is dealt with
1225 % here.
1226 % \begin{macrocode}
1227 \cs_new:Npn \@@_literal_special:nN #1#2 { #1 {#2} }
1228 % \end{macrocode}
1229 % \end{macro}
1230 %
1231 % \begin{macro}{\@@_format_literal:n}
1232 % \begin{macro}
1233 % {
1234 % \@@_format_literal_tilde: ,
1235 % \@@_format_literal_subscript: ,
1236 % \@@_format_literal_superscript:
1237 % }
1238 % \begin{macro}{\@@_format_literal_auxi:w}
1239 % \begin{macro}{\@@_format_literal_auxii:w}
1240 % \begin{macro}{\@@_format_literal_auxiii:w}
1241 % \begin{macro}{\@@_format_literal_auxiv:n}
1242 % \begin{macro}{\@@_format_literal_auxv:nw}
1243 % \begin{macro}
1244 % {
1245 % \@@_format_literal_auxvi:nN ,
1246 % \@@_format_literal_auxvii:nN ,
1247 % \@@_format_literal_auxviii:nN
1248 % }
1249 % \begin{macro}{\@@_format_literal_super:nn, \@@_format_literal_sub:nn}
1250 % \begin{macro}{\@@_format_literal_add:n}
1251 % \begin{macro}{\@@_format_literal_auxix:nn}
1252 % \begin{macro}{\@@_format_literal_auxx:nw}
1253 % \begin{variable}{\l_@@_separator_tl}
1254 % To format literal units, there are two tasks to do. The input is
1255 % \texttt{x}-type expanded to force any symbolic units to be converted into
1256 % their literal representation: this requires setting the appropriate
1257 % switch. In the resulting token list, all |.| and |~| tokens are then
1258 % replaced by the current unit product token list. To enable this to happen
1259 % correctly with a normal (active) |~|, a small amount of
1260 % \enquote{protection} is needed first. To cover active sub- and superscript
1261 % tokens, appropriate definitions are provided at this stage. Those have
1262 % to be expandable macros rather than implicit character tokens.
1263 %
1264 % As with other code dealing with user input, \cs{protected@edef} is used
1265 % here rather than \cs{tl_set:Ne} as \LaTeXe{} robust commands may be
1266 % present.
1267 % \begin{macrocode}
1268 \group_begin:
1269 \char_set_catcode_active:n { `\~ }
1270 \cs_new_protected:Npe \@@_format_literal:n #1
1271 {
1272 \group_begin:
1273 \exp_not:n { \bool_set_false:N \l_@@_parsing_bool }
1274 \tl_set:Nn \exp_not:N \l_@@_tmp_tl {#1}
1275 \tl_replace_all:Nnn \exp_not:N \l_@@_tmp_tl
1276 { \token_to_str:N ^ } { ^ }
1277 \tl_replace_all:Nnn \exp_not:N \l_@@_tmp_tl
1278 { \token_to_str:N _ } { \c_@@_math_subscript_tl }
1279 \cs_set_eq:NN \exp_not:N \text \scan_stop:
1280 \char_set_active_eq:NN ^
1281 \exp_not:N \@@_format_literal_superscript:
1282 \char_set_active_eq:NN _
1283 \exp_not:N \@@_format_literal_subscript:
1284 \char_set_active_eq:NN \exp_not:N ~
1285 \exp_not:N \@@_format_literal_tilde:
1286 \exp_not:n
1287 {
1288 \protected@edef \l_@@_tmp_tl
1289 { \l_@@_tmp_tl }
1290 \tl_clear:N \l_@@_formatted_tl
1291 \tl_if_empty:NF \l_@@_tmp_tl
1292 {
1293 \exp_after:wN \@@_format_literal_auxi:w
1294 \l_@@_tmp_tl .
1295 \q_recursion_tail . \q_recursion_stop
1296 }
1297 \exp_args:NNNV \group_end:
1298 \tl_set:Nn \l_@@_formatted_tl
1299 \l_@@_formatted_tl
1300 }
1301 }
1302 \group_end:
1303 \cs_new:Npe \@@_format_literal_subscript: { \c_@@_math_subscript_tl }
1304 \cs_new:Npn \@@_format_literal_superscript: { ^ }
1305 \cs_new:Npn \@@_format_literal_tilde: { . }
1306 % \end{macrocode}
1307 % To introduce the font changing commands while still allowing for line
1308 % breaks in literal units, a loop is needed to replace one |.| at a time.
1309 % To also allow for division, a second loop is used within that to handle
1310 % |/|: as a result, the separator between parts has to be tracked.
1311 % \begin{macrocode}
1312 \cs_new_protected:Npn \@@_format_literal_auxi:w #1 .
1313 {
1314 \quark_if_recursion_tail_stop:n {#1}
1315 \@@_format_literal_auxii:n {#1}
1316 \tl_set_eq:NN \l_@@_separator_tl \l_@@_product_tl
1317 \@@_format_literal_auxi:w
1318 }
1319 \cs_set_protected:Npn \@@_format_literal_auxii:n #1
1320 {
1321 \@@_format_literal_auxiii:w
1322 #1 / \q_recursion_tail / \q_recursion_stop
1323 }
1324 \cs_new_protected:Npn \@@_format_literal_auxiii:w #1 /
1325 {
1326 \quark_if_recursion_tail_stop:n {#1}
1327 \@@_format_literal_auxiv:n {#1}
1328 \tl_set:Nn \l_@@_separator_tl { / }
1329 \@@_format_literal_auxiii:w
1330 }
1331 \cs_new_protected:Npn \@@_format_literal_auxiv:n #1
1332 {
1333 \@@_format_literal_auxv:nw { }
1334 #1 \q_recursion_tail \q_recursion_stop
1335 }
1336 % \end{macrocode}
1337 % To deal properly with literal formatting, we have to worry about super-
1338 % and subscript markers. That can be complicated as they could come anywhere
1339 % in the input: we handle that by iterating through the input and picking
1340 % them out. This avoids any issue with losing braces for mid-input scripts.
1341 % We also have to deal with fractions, hence needing a series of nested
1342 % loops and a change of separator.
1343 % \begin{macrocode}
1344 \cs_new_protected:Npn \@@_format_literal_auxv:nw
1345 #1#2 \q_recursion_stop
1346 {
1347 \tl_if_head_is_N_type:nTF {#2}
1348 { \@@_format_literal_auxvi:nN }
1349 {
1350 \tl_if_head_is_group:nTF {#2}
1351 { \@@_format_literal_auxix:nn }
1352 { \@@_format_literal_auxx:nw }
1353 }
1354 {#1} #2 \q_recursion_stop
1355 }
1356 \cs_new_protected:Npe \@@_format_literal_auxvi:nN #1#2
1357 {
1358 \exp_not:N \quark_if_recursion_tail_stop_do:Nn #2
1359 { \exp_not:N \@@_format_literal_add:n {#1} }
1360 \exp_not:N \token_if_eq_meaning:NNTF #2 ^
1361 { \exp_not:N \@@_format_literal_super:nn {#1} }
1362 {
1363 \exp_not:N \token_if_eq_meaning:NNTF
1364 #2 \c_@@_math_subscript_tl
1365 { \exp_not:N \@@_format_literal_sub:nn {#1} }
1366 { \exp_not:N \@@_format_literal_auxvii:nN {#1} #2 }
1367 }
1368 }
1369 % \end{macrocode}
1370 % We need to make sure |\protect| sticks with the next token.
1371 % \begin{macrocode}
1372 \cs_new_protected:Npn \@@_format_literal_auxvii:nN #1#2
1373 {
1374 \str_if_eq:nnTF {#2} { \protect }
1375 { \@@_format_literal_auxviii:nN {#1} }
1376 { \@@_format_literal_auxv:nw {#1#2} }
1377 }
1378 \cs_new_protected:Npn \@@_format_literal_auxviii:nN #1#2
1379 { \@@_format_literal_auxv:nw { #1 \protect #2 } }
1380 \cs_new_protected:Npn \@@_format_literal_super:nn #1#2
1381 {
1382 \quark_if_recursion_tail_stop:n {#2}
1383 \@@_format_literal_add:n {#1}
1384 \tl_put_right:Nn \l_@@_formatted_tl { ^ {#2} }
1385 \@@_format_literal_auxvi:nN { }
1386 }
1387 \cs_new_protected:Npe \@@_format_literal_sub:nn #1#2
1388 {
1389 \exp_not:N \quark_if_recursion_tail_stop:n {#2}
1390 \exp_not:N \@@_format_literal_add:n {#1}
1391 \tl_put_right:Ne \exp_not:N \l_@@_formatted_tl
1392 {
1393 \c_@@_math_subscript_tl
1394 {
1395 \exp_not:N \exp_not:V
1396 \exp_not:N \l_siunitx_unit_font_tl
1397 { \exp_not:N \exp_not:n {#2} }
1398 }
1399 }
1400 \exp_not:N \@@_format_literal_auxvi:nN { }
1401 }
1402 \cs_new_protected:Npn \@@_format_literal_add:n #1
1403 {
1404 \tl_put_right:Ne \l_@@_formatted_tl
1405 {
1406 \tl_if_empty:NF \l_@@_formatted_tl
1407 { \exp_not:V \l_@@_separator_tl }
1408 \tl_if_empty:nF {#1}
1409 { \exp_not:V \l_siunitx_unit_font_tl { \exp_not:n {#1} } }
1410 }
1411 \tl_clear:N \l_@@_separator_tl
1412 }
1413 \cs_new_protected:Npn \@@_format_literal_auxix:nn #1#2
1414 { \@@_format_literal_auxv:nw { #1 {#2} } }
1415 \use:e
1416 {
1417 \cs_new_protected:Npn \exp_not:N \@@_format_literal_auxx:nw
1418 #1 \c_space_tl
1419 }
1420 { \@@_format_literal_auxv:nw {#1} }
1421 \tl_new:N \l_@@_separator_tl
1422 % \end{macrocode}
1423 % \end{variable}
1424 % \end{macro}
1425 % \end{macro}
1426 % \end{macro}
1427 % \end{macro}
1428 % \end{macro}
1429 % \end{macro}
1430 % \end{macro}
1431 % \end{macro}
1432 % \end{macro}
1433 % \end{macro}
1434 % \end{macro}
1435 % \end{macro}
1436 %
1437 % \subsection{(PDF) String creation}
1438 %
1439 % \begin{macro}{\siunitx_unit_pdfstring_context:}
1440 % A simple function that sets up to make units equal to their text
1441 % representation.
1442 % \begin{macrocode}
1443 \cs_new_protected:Npn \siunitx_unit_pdfstring_context:
1444 {
1445 \bool_set_false:N \l_@@_parsing_bool
1446 \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
1447 { \cs_set_eq:Nc ##1 { @@_ \token_to_str:N ##1 :w } }
1448 }
1449 % \end{macrocode}
1450 % \end{macro}
1451 %
1452 % \subsection{Parsing symbolic units}
1453 %
1454 % Parsing units takes place by storing information about each unit in a
1455 % \texttt{prop}. As well as the unit itself, there are various other optional
1456 % data points, for example a prefix or a power. Some of these can come before
1457 % the unit, others only after. The parser therefore tracks the number of units
1458 % read and uses the current position to allocate data to individual units.
1459 %
1460 % The result of parsing is a property list (\cs{l_@@_parsed_prop}) which
1461 % contains one or more entries for each unit:
1462 % \begin{itemize}
1463 % \item \texttt{prefix-$n$} The symbol for the prefix which applies to this
1464 % unit, \foreign{e.g.} for \cs{kilo} with (almost certainly) would be
1465 % |k|.
1466 % \item \texttt{unit-$n$} The symbol for the unit itself, \foreign{e.g.}~for
1467 % \cs{metre} with (almost certainly) would be |m|.
1468 % \item \texttt{power-$n$} The power which a unit is raised to. During
1469 % initial parsing this will (almost certainly) be positive, but is combined
1470 % with \texttt{per-$n$} to give a \enquote{fully qualified} power before
1471 % any formatting takes place
1472 % \item \texttt{per-$n$} Indicates that \texttt{per} applies to the current
1473 % unit: stored during initial parsing then combined with \texttt{power-$n$}
1474 % (and removed from the list) before further work.
1475 % \item \texttt{qualifier-$n$} Any qualifier which applies to the current
1476 % unit.
1477 % \item \texttt{special-$n$} Any \enquote{special effect} to apply to the
1478 % current unit.
1479 % \item \texttt{command-$1$} The command corresponding to \texttt{unit-$n$}:
1480 % needed to track base units; used for \cs{gram} only.
1481 % \end{itemize}
1482 %
1483 % \begin{variable}{\l_@@_sticky_per_bool}
1484 % There is one option when \emph{parsing} the input (as opposed to
1485 % \emph{formatting} for output): how to deal with \cs{per}.
1486 % \begin{macrocode}
1487 \keys_define:nn { siunitx }
1488 {
1489 sticky-per .bool_set:N = \l_@@_sticky_per_bool
1490 }
1491 % \end{macrocode}
1492 % \end{variable}
1493 %
1494 % \begin{variable}{\l_@@_parsed_prop}
1495 % \begin{variable}{\l_@@_per_bool}
1496 % \begin{variable}{\l_@@_position_int}
1497 % Parsing units requires a small number of variables are available: a
1498 % \texttt{prop} for the parsed units themselves, a \texttt{bool} to
1499 % indicate if \cs{per} is active and an \texttt{int} to track how many units
1500 % have be parsed.
1501 % \begin{macrocode}
1502 \prop_new:N \l_@@_parsed_prop
1503 \bool_new:N \l_@@_per_bool
1504 \int_new:N \l_@@_position_int
1505 % \end{macrocode}
1506 % \end{variable}
1507 % \end{variable}
1508 % \end{variable}
1509 %
1510 % \begin{macro}{\@@_parse:n}
1511 % The main parsing function is quite simple. After initialising the variables,
1512 % each symbolic unit is set up. The input is then simply inserted into the
1513 % input stream: the symbolic units themselves then do the real work of
1514 % placing data into the parsing system. There is then a bit of tidying up to
1515 % ensure that later stages can rely on the nature of the data here.
1516 % \begin{macrocode}
1517 \cs_new_protected:Npn \@@_parse:n #1
1518 {
1519 \prop_clear:N \l_@@_parsed_prop
1520 \bool_set_true:N \l_@@_parsing_bool
1521 \bool_set_false:N \l_@@_per_bool
1522 \bool_set_false:N \l_@@_test_bool
1523 \int_zero:N \l_@@_position_int
1524 \siunitx_unit_options_apply:n {#1}
1525 #1
1526 \int_step_inline:nn \l_@@_position_int
1527 { \@@_parse_finalise:n {##1} }
1528 \@@_parse_finalise:
1529 }
1530 % \end{macrocode}
1531 % \end{macro}
1532 %
1533 % \begin{macro}{\@@_parse_add:nnnn}
1534 % In all cases, storing a data item requires setting a temporary \texttt{tl}
1535 % which will be used as the key, then using this to store the value. The
1536 % \texttt{tl} is set using \texttt{x}-type expansion as this will expand the
1537 % unit index and any additional calculations made for this.
1538 % \begin{macrocode}
1539 \cs_new_protected:Npn \@@_parse_add:nnnn #1#2#3#4
1540 {
1541 \tl_set:Ne \l_@@_tmp_tl { #1 - #2 }
1542 \prop_if_in:NVTF \l_@@_parsed_prop
1543 \l_@@_tmp_tl
1544 {
1545 \msg_error:nnee { siunitx } { duplicate-part }
1546 { \exp_not:n {#1} } { \token_to_str:N #3 }
1547 }
1548 {
1549 \prop_put:NVn \l_@@_parsed_prop
1550 \l_@@_tmp_tl {#4}
1551 }
1552 }
1553 % \end{macrocode}
1554 % \end{macro}
1555 %
1556 % \begin{macro}{\@@_parse_prefix:Nn}
1557 % \begin{macro}{\@@_parse_power:nnN}
1558 % \begin{macro}{\@@_parse_qualifier:nn}
1559 % \begin{macro}{\@@_parse_special:n}
1560 % Storage of the various optional items follows broadly the same pattern
1561 % in each case. The data to be stored is passed along with an appropriate
1562 % key name to the underlying storage system. The details for each type of
1563 % item should be relatively clear. For example, prefixes have to come before
1564 % their \enquote{parent} unit and so there is some adjustment to do to add
1565 % them to the correct unit.
1566 % \begin{macrocode}
1567 \cs_new_protected:Npn \@@_parse_prefix:Nn #1#2
1568 {
1569 \int_set:Nn \l_@@_tmp_int { \l_@@_position_int + 1 }
1570 \@@_parse_add:nnnn { prefix }
1571 { \int_use:N \l_@@_tmp_int } {#1} {#2}
1572 }
1573 \cs_new_protected:Npn \@@_parse_power:nnN #1#2#3
1574 {
1575 \tl_set:Ne \l_@@_tmp_tl
1576 { unit- \int_use:N \l_@@_position_int }
1577 \bool_lazy_or:nnTF
1578 {#3}
1579 {
1580 \prop_if_in_p:NV
1581 \l_@@_parsed_prop \l_@@_tmp_tl
1582 }
1583 {
1584 \@@_parse_add:nnnn { power }
1585 {
1586 \int_eval:n
1587 { \l_@@_position_int \bool_if:NT #3 { + 1 } }
1588 }
1589 {#1} {#2}
1590 }
1591 {
1592 \msg_error:nnee { siunitx }
1593 { part-before-unit } { power } { \token_to_str:N #1 }
1594 }
1595 }
1596 \cs_new_protected:Npn \@@_parse_qualifier:nn #1#2
1597 {
1598 \tl_set:Ne \l_@@_tmp_tl
1599 { unit- \int_use:N \l_@@_position_int }
1600 \prop_if_in:NVTF \l_@@_parsed_prop \l_@@_tmp_tl
1601 {
1602 \@@_parse_add:nnnn { qualifier }
1603 { \int_use:N \l_@@_position_int } {#1} {#2}
1604 }
1605 {
1606 \msg_error:nnnn { siunitx }
1607 { part-before-unit } { qualifier } { \token_to_str:N #1 }
1608 }
1609 }
1610 % \end{macrocode}
1611 % Special (exceptional) items should always come before the relevant units.
1612 % \begin{macrocode}
1613 \cs_new_protected:Npn \@@_parse_special:n #1
1614 {
1615 \@@_parse_add:nnnn { special }
1616 { \int_eval:n { \l_@@_position_int + 1 } }
1617 {#1} {#1}
1618 }
1619 % \end{macrocode}
1620 % \end{macro}
1621 % \end{macro}
1622 % \end{macro}
1623 % \end{macro}
1624 %
1625 % \begin{macro}{\@@_parse_unit:Nn}
1626 % Parsing units is slightly more involved than the other cases: this is the
1627 % one place where the tracking value is incremented. If the switch
1628 % \cs{l_@@_per_bool} is set true then the current unit is also
1629 % reciprocal: this can only happen if \cs{l_@@_sticky_per_bool} is also
1630 % true, so only one test is required.
1631 % \begin{macrocode}
1632 \cs_new_protected:Npn \@@_parse_unit:Nn #1#2
1633 {
1634 \int_incr:N \l_@@_position_int
1635 \tl_if_eq:nnT {#1} { \gram }
1636 {
1637 \@@_parse_add:nnnn { command }
1638 { \int_use:N \l_@@_position_int }
1639 {#1} {#1}
1640 }
1641 \@@_parse_add:nnnn { unit }
1642 { \int_use:N \l_@@_position_int }
1643 {#1} {#2}
1644 \bool_if:NT \l_@@_per_bool
1645 {
1646 \@@_parse_add:nnnn { per }
1647 { \int_use:N \l_@@_position_int }
1648 { \per } { true }
1649 }
1650 }
1651 % \end{macrocode}
1652 % \end{macro}
1653 %
1654 % \begin{macro}{\@@_parse_per:}
1655 % Storing the \cs{per} command requires adding a data item separate from
1656 % the power which applies: this makes later formatting much more
1657 % straight-forward. This data could in principle be combined with the
1658 % \texttt{power}, but depending on the output format required that may make
1659 % life more complex. Thus this information is stored separately for later
1660 % retrieval. If \cs{per} is set to be \enquote{sticky} then after parsing
1661 % the first occurrence, any further uses are in error.
1662 % \begin{macrocode}
1663 \cs_new_protected:Npn \@@_parse_per:
1664 {
1665 \bool_if:NTF \l_@@_sticky_per_bool
1666 {
1667 \bool_set_true:N \l_@@_per_bool
1668 \cs_set_protected:Npn \per
1669 { \msg_error:nn { siunitx } { duplicate-sticky-per } }
1670 }
1671 {
1672 \@@_parse_add:nnnn
1673 { per } { \int_eval:n { \l_@@_position_int + 1 } }
1674 { \per } { true }
1675 }
1676 }
1677 % \end{macrocode}
1678 % \end{macro}
1679 %
1680 % \begin{macro}{\@@_parse_finalise:n}
1681 % If \cs{per} applies to the current unit, the power needs to be multiplied
1682 % by $-1$. That is done using an \texttt{fp} operation so that non-integer
1683 % powers are supported. The flag for \cs{per} is also removed as this means
1684 % we don't have to check that the original power was positive. To be on
1685 % the safe side, there is a check for a trivial power at this stage.
1686 % \begin{macrocode}
1687 \cs_new_protected:Npn \@@_parse_finalise:n #1
1688 {
1689 \tl_set:Ne \l_@@_tmp_tl { per- #1 }
1690 \prop_if_in:NVT \l_@@_parsed_prop \l_@@_tmp_tl
1691 {
1692 \prop_remove:NV \l_@@_parsed_prop
1693 \l_@@_tmp_tl
1694 \tl_set:Ne \l_@@_tmp_tl { power- #1 }
1695 \prop_get:NVNTF
1696 \l_@@_parsed_prop
1697 \l_@@_tmp_tl
1698 \l_@@_part_tl
1699 {
1700 \tl_set:Ne \l_@@_part_tl
1701 { \fp_eval:n { \l_@@_part_tl * -1 } }
1702 \fp_compare:nNnTF \l_@@_part_tl = 1
1703 {
1704 \prop_remove:NV \l_@@_parsed_prop
1705 \l_@@_tmp_tl
1706 }
1707 {
1708 \prop_put:NVV \l_@@_parsed_prop
1709 \l_@@_tmp_tl \l_@@_part_tl
1710 }
1711 }
1712 {
1713 \prop_put:NVn \l_@@_parsed_prop
1714 \l_@@_tmp_tl { -1 }
1715 }
1716 }
1717 }
1718 % \end{macrocode}
1719 % \end{macro}
1720 %
1721 % \begin{macro}{\@@_parse_finalise:}
1722 % The final task is to check that there is not a \enquote{dangling} power
1723 % or prefix: these are added to the \enquote{next} unit so are easy to
1724 % test for.
1725 % \begin{macrocode}
1726 \cs_new_protected:Npn \@@_parse_finalise:
1727 {
1728 \clist_map_inline:nn { per , power , prefix }
1729 {
1730 \tl_set:Ne \l_@@_tmp_tl
1731 { ##1 - \int_eval:n { \l_@@_position_int + 1 } }
1732 \prop_if_in:NVT \l_@@_parsed_prop \l_@@_tmp_tl
1733 { \msg_error:nnn { siunitx } { dangling-part } { ##1 } }
1734 }
1735 }
1736 % \end{macrocode}
1737 % \end{macro}
1738 %
1739 % \subsection{Formatting parsed units}
1740 %
1741 % \begin{variable}
1742 % {
1743 % \l_siunitx_unit_fraction_tl ,
1744 % \l_@@_denominator_bracket_bool ,
1745 % \l_@@_forbid_literal_bool ,
1746 % \l_@@_parse_bool ,
1747 % \l_@@_per_symbol_tl ,
1748 % \l_@@_per_script_tl ,
1749 % \l_@@_half_sqrt_bool ,
1750 % \l_@@_qualifier_mode_str ,
1751 % \l_@@_qualifier_phrase_tl
1752 % }
1753 % Set up the options which apply to formatting.
1754 % \begin{macrocode}
1755 \keys_define:nn { siunitx }
1756 {
1757 bracket-unit-denominator .bool_set:N =
1758 \l_@@_denominator_bracket_bool ,
1759 display-per-mode .choices:nn =
1760 {
1761 fraction ,
1762 power ,
1763 power-positive-first ,
1764 repeated-symbol ,
1765 symbol ,
1766 single-symbol
1767 }
1768 { \str_set:Nn \l_@@_per_display_str {#1} } ,
1769 forbid-literal-units .bool_set:N =
1770 \l_@@_forbid_literal_bool ,
1771 fraction-command .tl_set:N =
1772 \l_siunitx_unit_fraction_tl ,
1773 parse-units .bool_set:N =
1774 \l_@@_parse_bool ,
1775 inline-per-mode .choices:nn =
1776 {
1777 fraction ,
1778 power ,
1779 power-positive-first ,
1780 repeated-symbol ,
1781 symbol ,
1782 single-symbol
1783 }
1784 { \str_set:Nn \l_@@_per_inline_str {#1} } ,
1785 per-mode .meta:n =
1786 { display-per-mode = {#1} , inline-per-mode = {#1} } ,
1787 per-symbol .tl_set:N =
1788 \l_@@_per_symbol_tl ,
1789 per-symbol-script-correction .tl_set:N =
1790 \l_@@_per_script_tl ,
1791 power-half-as-sqrt .bool_set:N =
1792 \l_@@_half_sqrt_bool ,
1793 qualifier-mode .choices:nn =
1794 { bracket , combine , phrase , subscript }
1795 { \str_set_eq:NN \l_@@_qualifier_mode_str \l_keys_choice_str } ,
1796 qualifier-phrase .tl_set:N =
1797 \l_@@_qualifier_phrase_tl
1798 }
1799 % \end{macrocode}
1800 % \end{variable}
1801 %
1802 % \begin{variable}{\l_@@_bracket_bool}
1803 % A flag to indicate that the unit currently under construction will require
1804 % brackets if a power is added.
1805 % \begin{macrocode}
1806 \bool_new:N \l_@@_bracket_bool
1807 % \end{macrocode}
1808 % \end{variable}
1809 %
1810 % \begin{variable}{\l_@@_bracket_open_tl, \l_@@_bracket_close_tl}
1811 % Abstracted out but currently purely internal.
1812 % \begin{macrocode}
1813 \tl_new:N \l_@@_bracket_open_tl
1814 \tl_new:N \l_@@_bracket_close_tl
1815 \tl_set:Nn \l_@@_bracket_open_tl { ( }
1816 \tl_set:Nn \l_@@_bracket_close_tl { ) }
1817 % \end{macrocode}
1818 % \end{variable}
1819 %
1820 % \begin{variable}{\l_@@_font_bool}
1821 % A flag to control when font wrapping is applied to the output.
1822 % \begin{macrocode}
1823 \bool_new:N \l_@@_font_bool
1824 % \end{macrocode}
1825 % \end{variable}
1826 %
1827 % \begin{variable}{\l_@@_per_display_str, \l_@@_per_inline_str}
1828 % The data storage for |per-mode| settings.
1829 % \begin{macrocode}
1830 \str_new:N \l_@@_per_display_str
1831 \str_new:N \l_@@_per_inline_str
1832 % \end{macrocode}
1833 % \end{variable}
1834 %
1835 % \begin{variable}
1836 % {
1837 % \l_@@_powers_positive_bool ,
1838 % \l_@@_per_symbol_bool ,
1839 % \l_@@_two_part_bool
1840 % }
1841 % Dealing with the various ways that reciprocal (\cs{per}) can be handled
1842 % requires a few different switches.
1843 % \begin{macrocode}
1844 \bool_new:N \l_@@_per_symbol_bool
1845 \bool_new:N \l_@@_powers_positive_bool
1846 \bool_new:N \l_@@_two_part_bool
1847 % \end{macrocode}
1848 % \end{variable}
1849 %
1850 % \begin{variable}{\l_@@_numerator_bool}
1851 % Indicates that the current unit should go into the numerator when splitting
1852 % into two parts (fractions or other \enquote{sorted} styles).
1853 % \begin{macrocode}
1854 \bool_new:N \l_@@_numerator_bool
1855 % \end{macrocode}
1856 % \end{variable}
1857 %
1858 % \begin{variable}{\l_@@_qualifier_mode_str}
1859 % For storing the text of options which are best handled by picking
1860 % function names.
1861 % \begin{macrocode}
1862 \str_new:N \l_@@_qualifier_mode_str
1863 % \end{macrocode}
1864 % \end{variable}
1865 %
1866 % \begin{variable}{\l_@@_combine_exp_fp}
1867 % For combining an exponent with the first unit.
1868 % \begin{macrocode}
1869 \fp_new:N \l_@@_combine_exp_fp
1870 % \end{macrocode}
1871 % \end{variable}
1872 %
1873 % \begin{variable}{\l_@@_prefix_exp_bool}
1874 % Used to determine if prefixes are converted into powers. Note that
1875 % while this may be set as an option \enquote{higher up}, at this point it
1876 % is handled as an internal switch (see the two formatting interfaces for
1877 % reasons).
1878 % \begin{macrocode}
1879 \bool_new:N \l_@@_prefix_exp_bool
1880 % \end{macrocode}
1881 % \end{variable}
1882 %
1883 % \begin{variable}{\l_@@_prefix_fp}
1884 % When converting prefixes to powers, the calculations are done as an
1885 % \texttt{fp}.
1886 % \begin{macrocode}
1887 \fp_new:N \l_@@_prefix_fp
1888 % \end{macrocode}
1889 % \end{variable}
1890 %
1891 % \begin{variable}{\l_@@_multiple_fp}
1892 % For multiplying units.
1893 % \begin{macrocode}
1894 \fp_new:N \l_@@_multiple_fp
1895 % \end{macrocode}
1896 % \end{variable}
1897 %
1898 % \begin{variable}{\l_@@_current_script_bool, \l_@@_script_bool}
1899 % A pair of flags to track whether the last entry in the numerator has a
1900 % superscript. This is tracked to deal with spacing immediately before
1901 % a slash (symbol), if required. Two flags are needed as otherwise the
1902 % denominator interferes.
1903 % \begin{macrocode}
1904 \bool_new:N \l_@@_current_script_bool
1905 \bool_new:N \l_@@_script_bool
1906 % \end{macrocode}
1907 % \end{variable}
1908 %
1909 % \begin{variable}{\l_@@_current_tl, \l_@@_part_tl}
1910 % Building up the (partial) formatted unit requires some token list storage.
1911 % Each part of the unit combination that is recovered also has to be
1912 % placed in a token list: this is a dedicated one to leave the scratch
1913 % variables available.
1914 % \begin{macrocode}
1915 \tl_new:N \l_@@_current_tl
1916 \tl_new:N \l_@@_part_tl
1917 % \end{macrocode}
1918 % \end{variable}
1919 %
1920 % \begin{variable}{\l_@@_denominator_tl}
1921 % For fraction-like units, space is needed for the denominator as well as
1922 % the numerator (which is handled using \cs{l_@@_formatted_tl}).
1923 % \begin{macrocode}
1924 \tl_new:N \l_@@_denominator_tl
1925 % \end{macrocode}
1926 % \end{variable}
1927 %
1928 % \begin{variable}{\l_@@_total_int}
1929 % The formatting routine needs to know both the total number of units and
1930 % the current unit. Thus an \texttt{int} is required in addition to
1931 % \cs{l_@@_position_int}.
1932 % \begin{macrocode}
1933 \int_new:N \l_@@_total_int
1934 % \end{macrocode}
1935 % \end{variable}
1936 %
1937 % \begin{macro}{\@@_format_parsed:}
1938 % \begin{macro}
1939 % {\@@_format_parsed:n, \@@_format_parsed:V, \@@_format_parsed_aux:n}
1940 % The main formatting routine is essentially a loop over each position,
1941 % reading the various parts of the unit to build up complete unit
1942 % combination. When the two types of output need to be different, the
1943 % formatter has to be run twice.
1944 % \begin{macrocode}
1945 \cs_new_protected:Npn \@@_format_parsed:
1946 {
1947 \str_if_eq:NNTF
1948 \l_@@_per_inline_str
1949 \l_@@_per_display_str
1950 { \@@_format_parsed:V \l_@@_per_inline_str }
1951 {
1952 \group_begin:
1953 \@@_format_parsed:V \l_@@_per_inline_str
1954 \exp_args:NNNV \group_end:
1955 \tl_set:Nn \l_@@_tmp_tl \l_@@_formatted_tl
1956 \group_begin:
1957 \@@_format_parsed:V \l_@@_per_display_str
1958 \exp_args:NNNV \group_end:
1959 \tl_set:Nn \l_@@_formatted_tl \l_@@_formatted_tl
1960 \tl_set:Ne \l_@@_formatted_tl
1961 {
1962 \mathchoice
1963 { \exp_not:V \l_@@_formatted_tl }
1964 { \exp_not:V \l_@@_tmp_tl }
1965 { \exp_not:V \l_@@_tmp_tl }
1966 { \exp_not:V \l_@@_tmp_tl }
1967 }
1968 }
1969 }
1970 \cs_new_protected:Npn \@@_format_parsed:n #1
1971 {
1972 \int_set_eq:NN \l_@@_total_int \l_@@_position_int
1973 \use:c { @@_format_init_ #1 : }
1974 \tl_clear:N \l_@@_denominator_tl
1975 \tl_clear:N \l_@@_formatted_tl
1976 \fp_zero:N \l_@@_prefix_fp
1977 \int_zero:N \l_@@_position_int
1978 \fp_compare:nNnF \l_@@_combine_exp_fp = \c_zero_fp
1979 { \@@_format_combine_exp: }
1980 \fp_compare:nNnF \l_@@_multiple_fp = \c_one_fp
1981 { \@@_format_multiply: }
1982 \bool_lazy_and:nnT
1983 { \l_@@_prefix_exp_bool }
1984 { \l_@@_mass_kilogram_bool }
1985 { \@@_format_mass_to_kilogram: }
1986 \int_do_while:nNnn
1987 \l_@@_position_int < \l_@@_total_int
1988 {
1989 \bool_set_false:N \l_@@_bracket_bool
1990 \bool_set_false:N \l_@@_current_script_bool
1991 \tl_clear:N \l_@@_current_tl
1992 \bool_set_false:N \l_@@_font_bool
1993 \bool_set_true:N \l_@@_numerator_bool
1994 \int_incr:N \l_@@_position_int
1995 \clist_map_inline:nn { prefix , unit , qualifier , power , special }
1996 { \@@_format_parsed_aux:n {##1} }
1997 \@@_format_output:
1998 }
1999 \@@_format_finalise:
2000 }
2001 \cs_generate_variant:Nn \@@_format_parsed:n { V }
2002 \cs_new_protected:Npn \@@_format_parsed_aux:n #1
2003 {
2004 \tl_set:Ne \l_@@_tmp_tl
2005 { #1 - \int_use:N \l_@@_position_int }
2006 \prop_get:NVNT \l_@@_parsed_prop
2007 \l_@@_tmp_tl \l_@@_part_tl
2008 { \use:c { @@_format_ #1 : } }
2009 }
2010 % \end{macrocode}
2011 % \end{macro}
2012 % \end{macro}
2013 %
2014 % \begin{macro}
2015 % {
2016 % \@@_format_init_fraction: ,
2017 % \@@_format_init_power: ,
2018 % \@@_format_init_power-positive-first: ,
2019 % \@@_format_init_repeated-symbol: ,
2020 % \@@_format_init_symbol: ,
2021 % \@@_format_init_single-symbol: ,
2022 % }
2023 % To set up the various versions of |per-mode|.
2024 % \begin{macrocode}
2025 \cs_new_protected:Npn \@@_format_init_fraction:
2026 {
2027 \bool_set_false:N \l_@@_per_symbol_bool
2028 \bool_set_true:N \l_@@_powers_positive_bool
2029 \bool_set_true:N \l_@@_two_part_bool
2030 }
2031 \cs_new_protected:Npn \@@_format_init_power:
2032 {
2033 \bool_set_false:N \l_@@_per_symbol_bool
2034 \bool_set_false:N \l_@@_powers_positive_bool
2035 \bool_set_false:N \l_@@_two_part_bool
2036 }
2037 \cs_new_protected:cpn { @@_format_init_power-positive-first: }
2038 {
2039 \bool_set_false:N \l_@@_per_symbol_bool
2040 \bool_set_false:N \l_@@_powers_positive_bool
2041 \bool_set_true:N \l_@@_two_part_bool
2042 }
2043 \cs_new_protected:cpn { @@_format_init_repeated-symbol: }
2044 {
2045 \bool_set_true:N \l_@@_per_symbol_bool
2046 \bool_set_true:N \l_@@_powers_positive_bool
2047 \bool_set_false:N \l_@@_two_part_bool
2048 }
2049 \cs_new_protected:Npn \@@_format_init_symbol:
2050 {
2051 \bool_set_true:N \l_@@_per_symbol_bool
2052 \bool_set_true:N \l_@@_powers_positive_bool
2053 \bool_set_true:N \l_@@_two_part_bool
2054 }
2055 \cs_new_protected:cpn { @@_format_init_single-symbol: }
2056 {
2057 \@@_format_init_power:
2058 \@@_format_symbol_or_power:
2059 }
2060 % \end{macrocode}
2061 % \end{macro}
2062 %
2063 % \begin{macro}{\@@_format_combine_exp:}
2064 % To combine an exponent into the first prefix, we first adjust for any
2065 % power, then deal with any existing prefix, before looking up the
2066 % final result.
2067 % \begin{macrocode}
2068 \cs_new_protected:Npn \@@_format_combine_exp:
2069 {
2070 \prop_get:NnNF \l_@@_parsed_prop { power-1 } \l_@@_tmp_tl
2071 { \tl_set:Nn \l_@@_tmp_tl { 1 } }
2072 \fp_set:Nn \l_@@_tmp_fp
2073 { \l_@@_combine_exp_fp / \l_@@_tmp_tl }
2074 \prop_get:NnNTF \l_@@_parsed_prop { prefix-1 } \l_@@_tmp_tl
2075 {
2076 \prop_get:NVNF \l_@@_prefixes_forward_prop
2077 \l_@@_tmp_tl \l_@@_tmp_tl
2078 {
2079 \prop_get:NnN \l_@@_parsed_prop { prefix-1 } \l_@@_tmp_tl
2080 \msg_error:nne { siunitx } { non-numeric-exponent }
2081 { \l_@@_tmp_tl }
2082 \tl_set:Nn \l_@@_tmp_tl { 0 }
2083 }
2084 }
2085 { \tl_set:Nn \l_@@_tmp_tl { 0 } }
2086 \tl_set:Ne \l_@@_tmp_tl
2087 { \fp_eval:n { \l_@@_tmp_fp + \l_@@_tmp_tl } }
2088 \fp_compare:nNnTF \l_@@_tmp_tl = \c_zero_fp
2089 { \prop_remove:Nn \l_@@_parsed_prop { prefix-1 } }
2090 {
2091 \prop_get:NVNTF \l_@@_prefixes_reverse_prop
2092 \l_@@_tmp_tl \l_@@_tmp_tl
2093 { \prop_put:NnV \l_@@_parsed_prop { prefix-1 } \l_@@_tmp_tl }
2094 {
2095 \msg_error:nne { siunitx } { non-convertible-exponent }
2096 { \l_@@_tmp_tl }
2097 }
2098 }
2099 }
2100 % \end{macrocode}
2101 % \end{macro}
2102 %
2103 % \begin{macro}{\@@_format_multiply:}
2104 % A simple mapping.
2105 % \begin{macrocode}
2106 \cs_new_protected:Npn \@@_format_multiply:
2107 {
2108 \int_step_inline:nn { \prop_count:N \l_@@_parsed_prop }
2109 {
2110 \prop_get:NnNF \l_@@_parsed_prop { power- ##1 } \l_@@_tmp_tl
2111 { \tl_set:Nn \l_@@_tmp_tl { 1 } }
2112 \fp_set:Nn \l_@@_tmp_fp
2113 { \l_@@_tmp_tl * \l_@@_multiple_fp }
2114 \fp_compare:nNnTF \l_@@_tmp_fp = \c_one_fp
2115 { \prop_remove:N \l_@@_parsed_prop { power- ##1 } }
2116 {
2117 \prop_put:Nne \l_@@_parsed_prop { power- ##1 }
2118 { \fp_use:N \l_@@_tmp_fp }
2119 }
2120 }
2121 }
2122 % \end{macrocode}
2123 % \end{macro}
2124 %
2125 % \begin{macro}{\@@_format_mass_to_kilogram:}
2126 % To deal correctly with prefix extraction in combination with kilograms, we
2127 % need to coerce the prefix for grams. Currently, only this one special case
2128 % is recorded in the property list, so we do not actually need to check the
2129 % value. If there is then no prefix we do a bit of gymnastics to create one
2130 % and then shift the starting point for the prefix extraction.
2131 % \begin{macrocode}
2132 \cs_new_protected:Npn \@@_format_mass_to_kilogram:
2133 {
2134 \int_step_inline:nn \l_@@_total_int
2135 {
2136 \prop_if_in:NnT \l_@@_parsed_prop { command- ##1 }
2137 {
2138 \prop_if_in:NnF \l_@@_parsed_prop { prefix- ##1 }
2139 {
2140 \group_begin:
2141 \bool_set_false:N \l_@@_parsing_bool
2142 \tl_set:Ne \l_@@_tmp_tl { \kilo }
2143 \exp_args:NNNV \group_end:
2144 \tl_set:Nn \l_@@_tmp_tl \l_@@_tmp_tl
2145 \prop_put:NnV \l_@@_parsed_prop { prefix- ##1 }
2146 \l_@@_tmp_tl
2147 \prop_get:NnNF \l_@@_parsed_prop { power- ##1 }
2148 \l_@@_tmp_tl
2149 { \tl_set:Nn \l_@@_tmp_tl { 1 } }
2150 \fp_set:Nn \l_@@_prefix_fp
2151 { \l_@@_prefix_fp - 3 * \l_@@_tmp_tl }
2152 }
2153 }
2154 }
2155 }
2156 % \end{macrocode}
2157 % \end{macro}
2158 %
2159 % \begin{macro}{\@@_format_symbol_or_power:}
2160 % Check if there is exactly one negative power align with at least one
2161 % positive one. Assuming there is, flip from (effectively) |power| to
2162 % |symbol|.
2163 % \begin{macrocode}
2164 \cs_new_protected:Npn \@@_format_symbol_or_power:
2165 {
2166 \int_compare:nNnT \l_@@_total_int > 1
2167 {
2168 \bool_set_false:N \l_@@_tmp_bool
2169 \int_step_inline:nn \l_@@_total_int
2170 {
2171 \prop_get:NnNT \l_@@_parsed_prop { power- ##1 }
2172 \l_@@_tmp_tl
2173 {
2174 \int_compare:nNnT \l_@@_tmp_tl < 0
2175 {
2176 \bool_if:NTF \l_@@_tmp_bool
2177 { \bool_set_false:N \l_@@_tmp_bool }
2178 { \bool_set_true:N \l_@@_tmp_bool }
2179 }
2180 }
2181 }
2182 \bool_if:NT \l_@@_tmp_bool
2183 { \@@_format_init_symbol: }
2184 }
2185 }
2186 % \end{macrocode}
2187 % \end{macro}
2188 %
2189 % \begin{macro}[EXP]{\@@_format_bracket:N}
2190 % A quick utility function which wraps up a token list variable in brackets
2191 % if they are required.
2192 % \begin{macrocode}
2193 \cs_new:Npn \@@_format_bracket:N #1
2194 {
2195 \bool_if:NTF \l_@@_bracket_bool
2196 {
2197 \exp_not:V \l_@@_bracket_open_tl
2198 \exp_not:V #1
2199 \exp_not:V \l_@@_bracket_close_tl
2200 }
2201 { \exp_not:V #1 }
2202 }
2203 % \end{macrocode}
2204 % \end{macro}
2205 %
2206 % \begin{macro}{\@@_format_power:}
2207 % \begin{macro}[EXP]{\@@_format_power_aux:w}
2208 % \begin{macro}
2209 % {
2210 % \@@_format_power_positive: ,
2211 % \@@_format_power_negative:
2212 % }
2213 % \begin{macro}[EXP]{\@@_format_power_negative_aux:w}
2214 % \begin{macro}{\@@_format_power_superscript:}
2215 % Formatting powers requires a test for negative numbers and depending on
2216 % output format requests some adjustment to the stored value. This could be
2217 % done using an \texttt{fp} function, but that would be slow compared to
2218 % a dedicated if lower-level approach based on delimited arguments.
2219 % \begin{macrocode}
2220 \cs_new_protected:Npn \@@_format_power:
2221 {
2222 \@@_format_font:
2223 \exp_after:wN \@@_format_power_aux:w
2224 \l_@@_part_tl - \q_stop
2225 { \@@_format_power_negative: }
2226 { \@@_format_power_positive: }
2227 }
2228 \cs_new:Npn \@@_format_power_aux:w #1 - #2 \q_stop
2229 { \tl_if_empty:nTF {#1} }
2230 % \end{macrocode}
2231 % In the case of positive powers, there is little to do: add the power
2232 % as a superscript (the parser ensures that this is $\neq 1$, so we do not
2233 % need a test here).
2234 % \begin{macrocode}
2235 \cs_new_protected:Npn \@@_format_power_positive:
2236 { \@@_format_power_superscript: }
2237 % \end{macrocode}
2238 % Dealing with negative powers starts by flipping the switch used to track
2239 % where in the final output the current part should get added to. For the
2240 % case where the output is fraction-like, strip off the |~| then ensure that
2241 % the result is not the trivial power~$1$. Assuming all is well, addition
2242 % to the current unit combination goes ahead.
2243 % \begin{macrocode}
2244 \cs_new_protected:Npn \@@_format_power_negative:
2245 {
2246 \bool_set_false:N \l_@@_numerator_bool
2247 \bool_if:NTF \l_@@_powers_positive_bool
2248 {
2249 \tl_set:Ne \l_@@_part_tl
2250 {
2251 \exp_after:wN \@@_format_power_negative_aux:w
2252 \l_@@_part_tl \q_stop
2253 }
2254 \str_if_eq:VnF \l_@@_part_tl { 1 }
2255 { \@@_format_power_superscript: }
2256 }
2257 { \@@_format_power_superscript: }
2258 }
2259 \cs_new:Npn \@@_format_power_negative_aux:w - #1 \q_stop
2260 { \exp_not:n {#1} }
2261 % \end{macrocode}
2262 % Adding the power as a superscript has the slight complication that there
2263 % is the possibility of needing some brackets.
2264 % \begin{macrocode}
2265 \cs_new_protected:Npn \@@_format_power_superscript:
2266 {
2267 \bool_lazy_and:nnTF
2268 { \l_@@_half_sqrt_bool }
2269 { \str_if_eq_p:Vn \l_@@_part_tl { 0.5 } }
2270 {
2271 \tl_set:Ne \l_@@_current_tl
2272 {
2273 \exp_not:N \sqrt
2274 { \exp_not:V \l_@@_current_tl }
2275 }
2276 }
2277 {
2278 \exp_after:wN \@@_format_power_superscipt:w
2279 \l_@@_part_tl . . \q_stop
2280 }
2281 }
2282 \cs_new_protected:Npn \@@_format_power_superscipt:w #1 . #2 . #3 \q_stop
2283 {
2284 \tl_if_blank:nTF {#2}
2285 {
2286 \tl_set:Ne \l_@@_current_tl
2287 {
2288 \@@_format_bracket:N \l_@@_current_tl
2289 ^ { \exp_not:n {#1} }
2290 }
2291 }
2292 {
2293 \tl_set:Ne \l_@@_tmp_tl
2294 {
2295 { }
2296 \tl_if_head_eq_charcode:nNTF {#1} -
2297 { { - } { \exp_not:o { \use_none:n #1 } } }
2298 { { } { \exp_not:n {#1} } }
2299 {#2}
2300 { }
2301 { }
2302 { 0 }
2303 }
2304 \tl_set:Ne \l_@@_current_tl
2305 {
2306 \@@_format_bracket:N \l_@@_current_tl
2307 ^ { \siunitx_number_output:N \l_@@_tmp_tl }
2308 }
2309 }
2310 \bool_set_true:N \l_@@_current_script_bool
2311 \bool_set_false:N \l_@@_bracket_bool
2312 }
2313 % \end{macrocode}
2314 % \end{macro}
2315 % \end{macro}
2316 % \end{macro}
2317 % \end{macro}
2318 % \end{macro}
2319 %
2320 % \begin{macro}{\@@_format_prefix:}
2321 % \begin{macro}
2322 % {
2323 % \@@_format_prefix_exp: ,
2324 % \@@_format_prefix_gram: ,
2325 % \@@_format_prefix_symbol:
2326 % }
2327 % Formatting for prefixes depends on whether they are to be expressed as
2328 % symbols or collected up to be returned as a power of $10$. The latter
2329 % case requires a bit of processing, which includes checking that the
2330 % conversion is possible and allowing for any power that applies to the
2331 % current unit.
2332 % \begin{macrocode}
2333 \cs_new_protected:Npn \@@_format_prefix:
2334 {
2335 \bool_if:NTF \l_@@_prefix_exp_bool
2336 { \@@_format_prefix_exp: }
2337 { \@@_format_prefix_symbol: }
2338 }
2339 \cs_new_protected:Npn \@@_format_prefix_exp:
2340 {
2341 \prop_get:NVNTF \l_@@_prefixes_forward_prop
2342 \l_@@_part_tl \l_@@_part_tl
2343 {
2344 \bool_if:NT \l_@@_mass_kilogram_bool
2345 {
2346 \tl_set:Ne \l_@@_tmp_tl
2347 { command- \int_use:N \l_@@_position_int }
2348 \prop_if_in:NVT \l_@@_parsed_prop \l_@@_tmp_tl
2349 { \@@_format_prefix_gram: }
2350 }
2351 \tl_set:Ne \l_@@_tmp_tl
2352 { power- \int_use:N \l_@@_position_int }
2353 \prop_get:NVNF \l_@@_parsed_prop
2354 \l_@@_tmp_tl \l_@@_tmp_tl
2355 { \tl_set:Nn \l_@@_tmp_tl { 1 } }
2356 \fp_add:Nn \l_@@_prefix_fp
2357 { \l_@@_tmp_tl * \l_@@_part_tl }
2358 }
2359 { \@@_format_prefix_symbol: }
2360 }
2361 % \end{macrocode}
2362 % When the units in use are grams, we may need to deal with conversion to
2363 % kilograms.
2364 % \begin{macrocode}
2365 \cs_new_protected:Npn \@@_format_prefix_gram:
2366 {
2367 \tl_set:Ne \l_@@_part_tl
2368 { \int_eval:n { \l_@@_part_tl - 3 } }
2369 \group_begin:
2370 \bool_set_false:N \l_@@_parsing_bool
2371 \tl_set:Ne \l_@@_current_tl { \kilo }
2372 \exp_args:NNNV \group_end:
2373 \tl_set:Nn \l_@@_current_tl \l_@@_current_tl
2374 }
2375 \cs_new_protected:Npn \@@_format_prefix_symbol:
2376 { \tl_set_eq:NN \l_@@_current_tl \l_@@_part_tl }
2377 % \end{macrocode}
2378 % \end{macro}
2379 % \end{macro}
2380 %
2381 % \begin{macro}{\@@_format_qualifier:}
2382 % \begin{macro}
2383 % {
2384 % \@@_format_qualifier_bracket: ,
2385 % \@@_format_qualifier_combine: ,
2386 % \@@_format_qualifier_phrase: ,
2387 % \@@_format_qualifier_subscript:
2388 % }
2389 % There are various ways that a qualifier can be added to the output. The
2390 % idea here is to modify the \enquote{base} text appropriately and then add
2391 % to the current unit. Notice that when the qualifier is just treated as
2392 % \enquote{text}, the auxiliary is actually a no-op.
2393 % \begin{macrocode}
2394 \cs_new_protected:Npn \@@_format_qualifier:
2395 {
2396 \bool_set_false:N \l_@@_current_script_bool
2397 \bool_set_false:N \l_@@_bracket_bool
2398 \use:c
2399 {
2400 @@_format_qualifier_
2401 \l_@@_qualifier_mode_str :
2402 }
2403 \tl_put_right:NV \l_@@_current_tl \l_@@_part_tl
2404 }
2405 \cs_new_protected:Npn \@@_format_qualifier_bracket:
2406 {
2407 \@@_format_font:
2408 \tl_set:Ne \l_@@_part_tl
2409 {
2410 \exp_not:V \l_@@_bracket_open_tl
2411 \exp_not:V \l_siunitx_unit_font_tl
2412 { \exp_not:V \l_@@_part_tl }
2413 \exp_not:V \l_@@_bracket_close_tl
2414 }
2415 }
2416 \cs_new_protected:Npn \@@_format_qualifier_combine: { }
2417 % \end{macrocode}
2418 % Extra work is needed here to see if we need to add brackets.
2419 % \begin{macrocode}
2420 \cs_new_protected:Npn \@@_format_qualifier_phrase:
2421 {
2422 \@@_format_font:
2423 \tl_set:Ne \l_@@_part_tl
2424 {
2425 \exp_not:V \l_@@_qualifier_phrase_tl
2426 \exp_not:V \l_siunitx_unit_font_tl
2427 { \exp_not:V \l_@@_part_tl }
2428 }
2429 \tl_set:Ne \l_@@_tmp_tl
2430 { power - \int_use:N \l_@@_position_int }
2431 \prop_get:NVNT \l_@@_parsed_prop \l_@@_tmp_tl
2432 \l_@@_tmp_tl
2433 {
2434 \int_compare:nNnF \l_@@_tmp_tl = 1
2435 { \bool_set_true:N \l_@@_bracket_bool }
2436 }
2437 }
2438 \cs_new_protected:Npn \@@_format_qualifier_subscript:
2439 {
2440 \@@_format_font:
2441 \tl_set:Ne \l_@@_part_tl
2442 {
2443 \c_@@_math_subscript_tl
2444 {
2445 \exp_not:V \l_siunitx_unit_font_tl
2446 { \exp_not:V \l_@@_part_tl }
2447 }
2448 }
2449 }
2450 % \end{macrocode}
2451 % \end{macro}
2452 % \end{macro}
2453 %
2454 % \begin{macro}{\@@_format_special:}
2455 % Any special odds and ends are handled by simply making the current
2456 % combination into an argument for the recovered code. Font control
2457 % needs to be \emph{inside} the special formatting here.
2458 % \begin{macrocode}
2459 \cs_new_protected:Npn \@@_format_special:
2460 {
2461 \tl_set:Ne \l_@@_current_tl
2462 {
2463 \exp_not:V \l_@@_part_tl
2464 {
2465 \bool_if:NTF \l_@@_font_bool
2466 { \use:n }
2467 { \exp_not:V \l_siunitx_unit_font_tl }
2468 { \exp_not:V \l_@@_current_tl }
2469 }
2470 }
2471 \bool_set_true:N \l_@@_font_bool
2472 }
2473 % \end{macrocode}
2474 % \end{macro}
2475 %
2476 % \begin{macro}{\@@_format_unit:}
2477 % A very simple task: add the unit to the output currently being
2478 % constructed.
2479 % \begin{macrocode}
2480 \cs_new_protected:Npn \@@_format_unit:
2481 {
2482 \tl_put_right:NV
2483 \l_@@_current_tl \l_@@_part_tl
2484 }
2485 % \end{macrocode}
2486 % \end{macro}
2487 %
2488 % \begin{macro}{\@@_format_output:}
2489 % \begin{macro}
2490 % {\@@_format_output_aux:, \@@_format_output_denominator:}
2491 % \begin{macro}
2492 % {
2493 % \@@_format_output_aux:nn ,
2494 % \@@_format_output_aux:nV ,
2495 % \@@_format_output_aux:nv
2496 % }
2497 % The first step here is to make a choice based on whether the current
2498 % part should be stored as part of the numerator or denominator of a
2499 % fraction. In all cases, if the switch \cs{l_@@_numerator_bool} is
2500 % true then life is simple: add the current part to the numerator with
2501 % a standard separator
2502 % \begin{macrocode}
2503 \cs_new_protected:Npn \@@_format_output:
2504 {
2505 \@@_format_font:
2506 \bool_set_false:N \l_@@_bracket_bool
2507 \use:c
2508 {
2509 @@_format_output_
2510 \bool_if:NTF \l_@@_numerator_bool
2511 { aux: }
2512 { denominator: }
2513 }
2514 }
2515 \cs_new_protected:Npn \@@_format_output_aux:
2516 {
2517 \bool_set_eq:NN \l_@@_script_bool
2518 \l_@@_current_script_bool
2519 \@@_format_output_aux:nV { formatted }
2520 \l_@@_product_tl
2521 }
2522 % \end{macrocode}
2523 % There are a few things to worry about at this stage if the current part
2524 % is in the denominator. Powers have already been dealt with and some
2525 % formatting outcomes only need a branch at the final point of building
2526 % the entire unit. That means that there are three possible outcomes here:
2527 % if collecting two separate parts, add to the denominator with a product
2528 % separator, or if only building one token list there may be a need to use
2529 % a symbol separator. When the |repeated-symbol| option is in use there may
2530 % be a need to add a leading |1| to the output in the case where the
2531 % first unit is in the denominator: that can be picked up by looking for
2532 % empty output in combination with the flag for using a symbol in the output
2533 % but not a two-part strategy.
2534 % \begin{macrocode}
2535 \cs_new_protected:Npn \@@_format_output_denominator:
2536 {
2537 \bool_if:NTF \l_@@_two_part_bool
2538 {
2539 \bool_lazy_and:nnT
2540 { \l_@@_denominator_bracket_bool }
2541 { ! \tl_if_empty_p:N \l_@@_denominator_tl }
2542 { \bool_set_true:N \l_@@_bracket_bool }
2543 \@@_format_output_aux:nV { denominator }
2544 \l_@@_product_tl
2545 }
2546 {
2547 \bool_lazy_and:nnT
2548 { \l_@@_per_symbol_bool }
2549 { \tl_if_empty_p:N \l_@@_formatted_tl }
2550 { \tl_set:Nn \l_@@_formatted_tl { 1 } }
2551 \@@_format_output_aux:nv { formatted }
2552 {
2553 l_@@_
2554 \bool_if:NTF \l_@@_per_symbol_bool
2555 { per_symbol }
2556 { product }
2557 _tl
2558 }
2559 }
2560 }
2561 \cs_new_protected:Npn \@@_format_output_aux:nn #1#2
2562 {
2563 \tl_set:ce { l_@@_ #1 _tl }
2564 {
2565 \exp_not:v { l_@@_ #1 _tl }
2566 \tl_if_empty:cF { l_@@_ #1 _tl }
2567 { \exp_not:n {#2} }
2568 \exp_not:V \l_@@_current_tl
2569 }
2570 }
2571 \cs_generate_variant:Nn \@@_format_output_aux:nn { nV , nv }
2572 % \end{macrocode}
2573 % \end{macro}
2574 % \end{macro}
2575 % \end{macro}
2576 %
2577 % \begin{macro}{\@@_format_font:}
2578 % A short auxiliary which checks if the font has been applied to the
2579 % main part of the output: if not, add it and set the flag.
2580 % \begin{macrocode}
2581 \cs_new_protected:Npn \@@_format_font:
2582 {
2583 \bool_if:NF \l_@@_font_bool
2584 {
2585 \tl_set:Ne \l_@@_current_tl
2586 {
2587 \exp_not:V \l_siunitx_unit_font_tl
2588 { \exp_not:V \l_@@_current_tl }
2589 }
2590 \bool_set_true:N \l_@@_font_bool
2591 }
2592 }
2593 % \end{macrocode}
2594 % \end{macro}
2595 %
2596 % \begin{macro}{\@@_format_finalise:}
2597 % \begin{macro}
2598 % {
2599 % \@@_format_finalise_autofrac: ,
2600 % \@@_format_finalise_fractional: ,
2601 % \@@_format_finalise_power:
2602 % }
2603 % Finalising the unit format is really about picking up the cases involving
2604 % fractions: these require assembly of the parts with the need to add
2605 % additional material in some cases
2606 % \begin{macrocode}
2607 \cs_new_protected:Npn \@@_format_finalise:
2608 {
2609 \tl_if_empty:NF \l_@@_denominator_tl
2610 {
2611 \bool_if:NTF \l_@@_powers_positive_bool
2612 { \@@_format_finalise_fractional: }
2613 { \@@_format_finalise_power: }
2614 }
2615 }
2616 % \end{macrocode}
2617 % For fraction-like output, there are three possible choices and two
2618 % actual styles. In all cases, if the numerator is empty then it is set
2619 % here to |1|. To deal with the \enquote{auto-format} case, the two
2620 % styles (fraction and symbol) are handled in auxiliaries: this allows both
2621 % to be used at the same time! Beyond that, the key here is to use a
2622 % single \cs{tl_set:Ne} to keep down the number of assignments.
2623 % \begin{macrocode}
2624 \cs_new_protected:Npn \@@_format_finalise_fractional:
2625 {
2626 \tl_if_empty:NT \l_@@_formatted_tl
2627 { \tl_set:Nn \l_@@_formatted_tl { 1 } }
2628 \bool_if:NTF \l_@@_per_symbol_bool
2629 { \@@_format_finalise_symbol: }
2630 { \@@_format_finalise_fraction: }
2631 }
2632 % \end{macrocode}
2633 % When using a fraction function the two parts are now assembled.
2634 % \begin{macrocode}
2635 \cs_new_protected:Npn \@@_format_finalise_fraction:
2636 {
2637 \tl_set:Ne \l_@@_formatted_tl
2638 {
2639 \exp_not:V \l_siunitx_unit_fraction_tl
2640 { \exp_not:V \l_@@_formatted_tl }
2641 { \exp_not:V \l_@@_denominator_tl }
2642 }
2643 }
2644 % \end{macrocode}
2645 % Add the correction if required: no \cs{relax} needed as we know there is a
2646 % non-expandable token following.
2647 % \begin{macrocode}
2648 \cs_new_protected:Npn \@@_format_finalise_symbol:
2649 {
2650 \tl_set:Ne \l_@@_formatted_tl
2651 {
2652 \exp_not:V \l_@@_formatted_tl
2653 \bool_if:NT \l_@@_script_bool
2654 { \exp_not:V \l_@@_per_script_tl }
2655 \exp_not:V \l_@@_per_symbol_tl
2656 \@@_format_bracket:N \l_@@_denominator_tl
2657 }
2658 }
2659 % \end{macrocode}
2660 % In the case of sorted powers, there is a test to make sure there was
2661 % at least one positive power, and if so a simple join of the two parts
2662 % with the appropriate product.
2663 % \begin{macrocode}
2664 \cs_new_protected:Npn \@@_format_finalise_power:
2665 {
2666 \tl_if_empty:NTF \l_@@_formatted_tl
2667 {
2668 \tl_set_eq:NN
2669 \l_@@_formatted_tl
2670 \l_@@_denominator_tl
2671 }
2672 {
2673 \tl_set:Ne \l_@@_formatted_tl
2674 {
2675 \exp_not:V \l_@@_formatted_tl
2676 \exp_not:V \l_@@_product_tl
2677 \exp_not:V \l_@@_denominator_tl
2678 }
2679 }
2680 }
2681 % \end{macrocode}
2682 % \end{macro}
2683 % \end{macro}
2684 %
2685 % \subsection{Non-Latin character support}
2686 %
2687 % \begin{macro}{\@@_non_latin:n}
2688 % A shortcut.
2689 % \begin{macrocode}
2690 \cs_new:Npn \@@_non_latin:n #1
2691 { \codepoint_generate:nn {#1} { \char_value_catcode:n {#1} } }
2692 % \end{macrocode}
2693 % \end{macro}
2694 %
2695 % \subsection{Pre-defined unit components}
2696 %
2697 % Quite a number of units can be predefined: while this is a code-level module,
2698 % there is little point having a unit parser which does not start off able to
2699 % parse any units!
2700 %
2701 % \begin{macro}
2702 % {
2703 % \kilogram ,
2704 % \metre ,
2705 % \meter ,
2706 % \mole ,
2707 % \kelvin ,
2708 % \candela ,
2709 % \second ,
2710 % \ampere
2711 % }
2712 % The basic \acro{SI} units: technically the correct spelling is \cs{metre}
2713 % but US users tend to use \cs{meter}.
2714 % \begin{macrocode}
2715 \siunitx_declare_unit:Nn \kilogram { \kilo \gram }
2716 \siunitx_declare_unit:Nn \metre { m }
2717 \siunitx_declare_unit:Nn \meter { \metre }
2718 \siunitx_declare_unit:Nn \mole { mol }
2719 \siunitx_declare_unit:Nn \second { s }
2720 \siunitx_declare_unit:Nn \ampere { A }
2721 \siunitx_declare_unit:Nn \kelvin { K }
2722 \siunitx_declare_unit:Nn \candela { cd }
2723 % \end{macrocode}
2724 % \end{macro}
2725 %
2726 % \begin{macro}{\gram}
2727 % The gram is an odd unit as it is needed for the base unit kilogram.
2728 % \begin{macrocode}
2729 \siunitx_declare_unit:Nn \gram { g }
2730 % \end{macrocode}
2731 % \end{macro}
2732 %
2733 % \begin{macro}
2734 % {
2735 % \quecto ,
2736 % \ronto ,
2737 % \yocto ,
2738 % \zepto ,
2739 % \atto ,
2740 % \femto ,
2741 % \pico ,
2742 % \nano ,
2743 % \micro ,
2744 % \milli ,
2745 % \centi ,
2746 % \deci
2747 % }
2748 % The various \acro{SI} multiple prefixes are defined here: first the small
2749 % ones.
2750 % \begin{macrocode}
2751 \siunitx_declare_prefix:Nnn \quecto { -30 } { q }
2752 \siunitx_declare_prefix:Nnn \ronto { -27 } { r }
2753 \siunitx_declare_prefix:Nnn \yocto { -24 } { y }
2754 \siunitx_declare_prefix:Nnn \zepto { -21 } { z }
2755 \siunitx_declare_prefix:Nnn \atto { -18 } { a }
2756 \siunitx_declare_prefix:Nnn \femto { -15 } { f }
2757 \siunitx_declare_prefix:Nnn \pico { -12 } { p }
2758 \siunitx_declare_prefix:Nnn \nano { -9 } { n }
2759 \siunitx_declare_prefix:Nne \micro { -6 } { \@@_non_latin:n { "03BC } }
2760 \siunitx_declare_prefix:Nnn \milli { -3 } { m }
2761 \siunitx_declare_prefix:Nnn \centi { -2 } { c }
2762 \siunitx_declare_prefix:Nnn \deci { -1 } { d }
2763 % \end{macrocode}
2764 % \end{macro}
2765 % \begin{macro}
2766 % {
2767 % \deca ,
2768 % \deka ,
2769 % \hecto ,
2770 % \kilo ,
2771 % \mega ,
2772 % \giga ,
2773 % \tera ,
2774 % \peta ,
2775 % \exa ,
2776 % \zetta ,
2777 % \yotta ,
2778 % \ronna ,
2779 % \quetta
2780 % }
2781 % Now the large ones.
2782 % \begin{macrocode}
2783 \siunitx_declare_prefix:Nnn \deca { 1 } { da }
2784 \siunitx_declare_prefix:Nnn \deka { 1 } { da }
2785 \siunitx_declare_prefix:Nnn \hecto { 2 } { h }
2786 \siunitx_declare_prefix:Nnn \kilo { 3 } { k }
2787 \siunitx_declare_prefix:Nnn \mega { 6 } { M }
2788 \siunitx_declare_prefix:Nnn \giga { 9 } { G }
2789 \siunitx_declare_prefix:Nnn \tera { 12 } { T }
2790 \siunitx_declare_prefix:Nnn \peta { 15 } { P }
2791 \siunitx_declare_prefix:Nnn \exa { 18 } { E }
2792 \siunitx_declare_prefix:Nnn \zetta { 21 } { Z }
2793 \siunitx_declare_prefix:Nnn \yotta { 24 } { Y }
2794 \siunitx_declare_prefix:Nnn \ronna { 27 } { R }
2795 \siunitx_declare_prefix:Nnn \quetta { 30 } { Q }
2796 % \end{macrocode}
2797 % \end{macro}
2798 %
2799 % \begin{macro}
2800 % {
2801 % \becquerel ,
2802 % \degreeCelsius ,
2803 % \coulomb ,
2804 % \farad ,
2805 % \gray ,
2806 % \hertz ,
2807 % \henry ,
2808 % \joule ,
2809 % \katal ,
2810 % \lumen ,
2811 % \lux
2812 % }
2813 % Named derived units: first half of alphabet.
2814 % \begin{macrocode}
2815 \siunitx_declare_unit:Nn \becquerel { Bq }
2816 \siunitx_declare_unit:Ne \degreeCelsius { \@@_non_latin:n { "00B0 } C }
2817 \siunitx_declare_unit:Nn \coulomb { C }
2818 \siunitx_declare_unit:Nn \farad { F }
2819 \siunitx_declare_unit:Nn \gray { Gy }
2820 \siunitx_declare_unit:Nn \hertz { Hz }
2821 \siunitx_declare_unit:Nn \henry { H }
2822 \siunitx_declare_unit:Nn \joule { J }
2823 \siunitx_declare_unit:Nn \katal { kat }
2824 \siunitx_declare_unit:Nn \lumen { lm }
2825 \siunitx_declare_unit:Nn \lux { lx }
2826 % \end{macrocode}
2827 % \end{macro}
2828 % \begin{macro}
2829 % {
2830 % \newton ,
2831 % \ohm ,
2832 % \pascal ,
2833 % \radian ,
2834 % \siemens ,
2835 % \sievert ,
2836 % \steradian ,
2837 % \tesla ,
2838 % \volt ,
2839 % \watt ,
2840 % \weber
2841 % }
2842 % Named derived units: second half of alphabet.
2843 % \begin{macrocode}
2844 \siunitx_declare_unit:Nn \newton { N }
2845 \siunitx_declare_unit:Ne \ohm { \@@_non_latin:n { "2126 } }
2846 \siunitx_declare_unit:Nn \pascal { Pa }
2847 \siunitx_declare_unit:Nn \radian { rad }
2848 \siunitx_declare_unit:Nn \siemens { S }
2849 \siunitx_declare_unit:Nn \sievert { Sv }
2850 \siunitx_declare_unit:Nn \steradian { sr }
2851 \siunitx_declare_unit:Nn \tesla { T }
2852 \siunitx_declare_unit:Nn \volt { V }
2853 \siunitx_declare_unit:Nn \watt { W }
2854 \siunitx_declare_unit:Nn \weber { Wb }
2855 % \end{macrocode}
2856 % \end{macro}
2857 %
2858 % \begin{macro}
2859 % {
2860 % \astronomicalunit ,
2861 % \bel ,
2862 % \dalton ,
2863 % \day ,
2864 % \decibel ,
2865 % \electronvolt ,
2866 % \hectare ,
2867 % \hour ,
2868 % \litre ,
2869 % \liter ,
2870 % \minute ,
2871 % \neper ,
2872 % \tonne
2873 % }
2874 % Non-\acro{SI}, but accepted for general use. Once again there are two
2875 % spellings, here for litre and with different output in this case.
2876 % \begin{macrocode}
2877 \siunitx_declare_unit:Nn \astronomicalunit { au }
2878 \siunitx_declare_unit:Nn \bel { B }
2879 \siunitx_declare_unit:Nn \decibel { \deci \bel }
2880 \siunitx_declare_unit:Nn \dalton { Da }
2881 \siunitx_declare_unit:Nn \day { d }
2882 \siunitx_declare_unit:Nn \electronvolt { eV }
2883 \siunitx_declare_unit:Nn \hectare { ha }
2884 \siunitx_declare_unit:Nn \hour { h }
2885 \siunitx_declare_unit:Nn \litre { L }
2886 \siunitx_declare_unit:Nn \liter { \litre }
2887 \siunitx_declare_unit:Nn \minute { min }
2888 \siunitx_declare_unit:Nn \neper { Np }
2889 \siunitx_declare_unit:Nn \tonne { t }
2890 % \end{macrocode}
2891 % \end{macro}
2892 % \begin{macro}
2893 % {
2894 % \arcminute ,
2895 % \arcsecond ,
2896 % \degree
2897 % }
2898 % Arc units: again, non-\acro{SI}, but accepted for general use.
2899 % \begin{macrocode}
2900 \siunitx_declare_unit:Ne \arcminute { \@@_non_latin:n { "02B9 } }
2901 \siunitx_declare_unit:Ne \arcsecond { \@@_non_latin:n { "02BA } }
2902 \siunitx_declare_unit:Ne \degree { \@@_non_latin:n { "00B0 } }
2903 % \end{macrocode}
2904 % \end{macro}
2905 %
2906 % \begin{macro}{\percent}
2907 % For percent, the raw character is the most flexible way of handling output.
2908 % \begin{macrocode}
2909 \siunitx_declare_unit:Ne \percent { \cs_to_str:N \% }
2910 % \end{macrocode}
2911 % \end{macro}
2912 %
2913 % \begin{macro}{\square, \squared, \cubic, \cubed}
2914 % Basic powers.
2915 % \begin{macrocode}
2916 \siunitx_declare_power:NNn \square \squared { 2 }
2917 \siunitx_declare_power:NNn \cubic \cubed { 3 }
2918 % \end{macrocode}
2919 % \end{macro}
2920 %
2921 % \subsection{Messages}
2922 %
2923 % \begin{macrocode}
2924 \msg_new:nnnn { siunitx } { dangling-part }
2925 { Found~#1~part~with~no~unit. }
2926 {
2927 Each~#1~part~must~be~associated~with~a~unit:~a~#1~part~was~found~
2928 but~no~following~unit~was~given.
2929 }
2930 \msg_new:nnnn { siunitx } { duplicate-part }
2931 { Duplicate~#1~part:~#2. }
2932 {
2933 Each~unit~may~have~only~one~#1:\\
2934 the~additional~#1~part~'#2'~will~be~ignored.
2935 }
2936 \msg_new:nnnn { siunitx } { duplicate-sticky-per }
2937 { Duplicate~\token_to_str:N \per. }
2938 {
2939 When~the~'sticky-per'~option~is~active,~only~one~
2940 \token_to_str:N \per \ may~appear~in~a~unit.
2941 }
2942 \msg_new:nnnn { siunitx } { literal-unit }
2943 { Literal~units~disabled. }
2944 {
2945 You~gave~the~literal~input~'#1'~
2946 but~literal~unit~output~is~disabled.
2947 }
2948 \msg_new:nnnn { siunitx } { non-convertible-exponent }
2949 { Exponent~'#1'~cannot~be~converted~into~a~symbolic~prefix. }
2950 {
2951 The~exponent~'#1'~does~not~match~with~any~of~the~symbolic~prefixes~
2952 set~up.
2953 }
2954 \msg_new:nnnn { siunitx } { non-numeric-exponent }
2955 { Prefix~'#1'~does~not~have~a~numerical~value. }
2956 {
2957 The~prefix~'#1'~needs~to~be~combined~with~a~number,~but~it~has~no
2958 numerical~value.
2959 }
2960 \msg_new:nnnn { siunitx } { part-before-unit }
2961 { Found~#1~part~before~first~unit:~#2. }
2962 {
2963 The~#1~part~'#2'~must~follow~after~a~unit:~
2964 it~cannot~appear~before~any~units~and~will~therefore~be~ignored.
2965 }
2966 % \end{macrocode}
2967 %
2968 % \subsection{Deprecated options}
2969 %
2970 % To handle |per-mode = symbol-or-fraction|, there needs to be allowance for
2971 % the fact that it is set up as a meta-option. That is done with appropriate
2972 % code here for the two newer options.
2973 % \begin{macrocode}
2974 \keys_define:nn { siunitx }
2975 {
2976 display-per-mode / symbol-or-fraction .code:n =
2977 {
2978 \msg_info:nnnn { siunitx } { option-deprecated }
2979 { per-mode~=~symbol-or-fraction }
2980 { display-per-mode~=~fraction,~inline-per-mode~=~symbol }
2981 \str_set:Nn \l_@@_per_display_str { fraction }
2982 } ,
2983 inline-per-mode / symbol-or-fraction .code:n =
2984 {
2985 \msg_info:nnnn { siunitx } { option-deprecated }
2986 { per-mode~=~symbol-or-fraction }
2987 { display-per-mode~=~fraction,~inline-per-mode~=~symbol }
2988 \str_set:Nn \l_@@_per_inline_str { symbol }
2989 }
2990 }
2991 % \end{macrocode}
2992 %
2993 % \subsection{Standard settings for module options}
2994 %
2995 % Some of these follow naturally from the point of definition
2996 % (\foreign{e.g.}~boolean variables are always |false| to begin with),
2997 % but for clarity everything is set here.
2998 % \begin{macrocode}
2999 \keys_set:nn { siunitx }
3000 {
3001 bracket-unit-denominator = true ,
3002 forbid-literal-units = false ,
3003 fraction-command = \frac ,
3004 inter-unit-product = \, ,
3005 extract-mass-in-kilograms = true ,
3006 parse-units = true ,
3007 per-mode = power ,
3008 per-symbol = / ,
3009 per-symbol-script-correction = \! ,
3010 power-half-as-sqrt = false ,
3011 qualifier-mode = subscript ,
3012 qualifier-phrase = ,
3013 sticky-per = false ,
3014 unit-font-command = \mathrm
3015 }
3016 % \end{macrocode}
3017 %
3018 % Cover the case where the default font is sanserif with \pkg{beamer}.
3019 % \begin{macrocode}
3020 \AtBeginDocument
3021 {
3022 \@ifclassloaded { beamer }
3023 {
3024 \str_if_eq:eeT
3025 { \exp_not:o { \familydefault } }
3026 { \exp_not:n { \sfdefault } }
3027 {
3028 \tl_if_eq:VnT \l_siunitx_unit_font_tl { \mathrm }
3029 { \keys_set:nn { siunitx } { unit-font-command = \mathsf } }
3030 }
3031 }
3032 { }
3033 }
3034 % \end{macrocode}
3035 %
3036 % \begin{macrocode}
3037 %</package>
3038 % \end{macrocode}
3039 %
3040 % \end{implementation}
3041 %
3042 % \begin{thebibliography}{1}
3043 % \bibitem{BIPM}
3044 % \emph{The International System of Units (\acro{SI})},
3045 % \url{https://www.bipm.org/en/measurement-units/}.
3046 % \bibitem{base-units}
3047 % \emph{SI base units},
3048 % \url{https://www.bipm.org/en/measurement-units/si-base-units}.
3049 % \end{thebibliography}
3050 %
3051 % \PrintIndex