Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % File: siunitx-quantity.dtx Copyright (C) 2018-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 \ProvideDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
31 \ProvideDocumentCommand\foreign{m}{\textit{#1}}
32 % The next line is needed so that \GetFileInfo will be able to pick up
33 % version data
34 \usepackage{siunitx}
35 \begin{document}
36 \DocInput{\jobname.dtx}
37 \end{document}
38 %</driver>
39 % \fi
40 %
41 % \GetFileInfo{siunitx.sty}
42 %
43 % \title{^^A
44 % \pkg{siunitx-quantity} -- Quantities^^A
45 % \thanks{This file describes \fileversion,
46 % last revised \filedate.}^^A
47 % }
48 %
49 % \author{^^A
50 % Joseph Wright^^A
51 % \thanks{^^A
52 % E-mail:
53 % \email{[email protected]}^^A
54 % }^^A
55 % }
56 %
57 % \date{Released \filedate}
58 %
59 % \maketitle
60 %
61 % \begin{documentation}
62 %
63 % \section{Quantities}
64 %
65 % This submodule is focussed on providing controlled printing for quantities:
66 % the combination of a number and a unit. It largely builds on the submodules
67 % \pkg{siunitx-number} and \pkg{siunitx-unit}. A small number of adjustments
68 % are made to standard set up in the latter to reflect additional functionality
69 % added here.
70 %
71 % \begin{function}{\siunitx_quantity:nn}
72 % \begin{syntax}
73 % \cs{siunitx_quantity:nn} \Arg{number} \Arg{unit}
74 % \end{syntax}
75 % Parses the \meta{number} and the \meta{unit} as detailed for
76 % \cs{siunitx_number_parse:nN} and \cs{siunitx_unit_format:nN},
77 % the prints the results using \cs{siunitx_print_unit:n}.
78 % \end{function}
79 %
80 % \begin{function}
81 % {
82 % \siunitx_quantity_print:nn, \siunitx_quantity_print:nV,
83 % \siunitx_quantity_print:VV, \siunitx_quantity_print:eV
84 % }
85 % \begin{syntax}
86 % \cs{siunitx_quantity_print:nn} \Arg{number} \Arg{unit}
87 % \end{syntax}
88 % A low-level function which prints the quantity directly: there is
89 % no processing applied to either the \meta{number} or \meta{unit}. The
90 % two parts are printed using \cs{siunitx_print_unit:n} and appropriate
91 % spacing and break-prevention is applied.
92 % \end{function}
93 %
94 % \begin{variable}{\l_siunitx_quantity_prefix_mode_str}
95 % The active mode for prefix handling: one of |combine-exponent|,
96 % |extract-exponent| or |input|.
97 % \end{variable}
98 %
99 % \begin{function}{allow-quantity-breaks}
100 % \begin{syntax}
101 % |allow-quantity-breaks| = |true|\verb"|"|false|
102 % \end{syntax}
103 % Specifies whether breaks are permitted between units. The standard setting
104 % is |false|.
105 % \end{function}
106 %
107 % \begin{function}{prefix-mode}
108 % \begin{syntax}
109 % |prefix-mode| = |combine-exponent|\verb"|"|extract-exponent|\verb"|"|input|
110 % \end{syntax}
111 % Selects the method used for producing prefixes: a choice from the options
112 % |combine-exponent|, |extract-exponent| and |input|. The option
113 % |combine-exponent| combines any exponent from the number with the prefix
114 % of the first unit, and prints the updated prefix. The option
115 % |extract-exponent| removes all prefixes from the unit, and combines them
116 % with the exponent of number. The option |input| prints prefixes and
117 % exponent as given in the source. The standard setting is |input|.
118 % \end{function}
119 %
120 % \begin{function}{quantity-product}
121 % \begin{syntax}
122 % |quantity-product| = \meta{tokens}
123 % \end{syntax}
124 % The product marker used between a number and the unit. The standard setting
125 % is~\cs{,}.
126 % \end{function}
127 %
128 % \begin{function}{separate-uncertainty-units}
129 % \begin{syntax}
130 % |separate-uncertainty-units| = |bracket|\verb"|"|repeat|\verb"|"|single|
131 % \end{syntax}
132 % Specifies how units are applied when a separated uncertainty is present:
133 % a choice from |bracket|, |repeat| and |single|. The option |bracket| places
134 % brackets around the number, with the unit given after these. The option
135 % |repeat| means that the unit it printed with the main value and with the
136 % uncertainty. When |single| is set, the unit is printed only once and no
137 % brackets are applied. The standard setting is |bracket|.
138 % \end{function}
139 %
140 % \end{documentation}
141 %
142 % \begin{implementation}
143 %
144 % \section{\pkg{siunitx-quantity} implementation}
145 %
146 % Start the \pkg{DocStrip} guards.
147 % \begin{macrocode}
148 %<*package>
149 % \end{macrocode}
150 %
151 % Identify the internal prefix.
152 % \begin{macrocode}
153 %<@@=siunitx_quantity>
154 % \end{macrocode}
155 %
156 % \subsection{Initial set-up}
157 %
158 % \begin{variable}{\l_@@_tmp_fp, \l_@@_tmp_tl}
159 % Scratch space.
160 % \begin{macrocode}
161 \fp_new:N \l_@@_tmp_fp
162 \tl_new:N \l_@@_tmp_tl
163 % \end{macrocode}
164 % \end{variable}
165 %
166 % \subsection{Main formatting routine}
167 %
168 % \begin{variable}{\l_@@_bracket_close_tl, \l_@@_bracket_open_tl}
169 % Purely internal for the present.
170 % \begin{macrocode}
171 \tl_new:N \l_@@_bracket_close_tl
172 \tl_new:N \l_@@_bracket_open_tl
173 \tl_set:Nn \l_@@_bracket_open_tl { ( }
174 \tl_set:Nn \l_@@_bracket_close_tl { ) }
175 % \end{macrocode}
176 % \end{variable}
177 %
178 % \begin{variable}
179 % {
180 % \l_siunitx_quantity_prefix_mode_str ,
181 % \l_@@_break_bool ,
182 % \l_@@_product_tl ,
183 % \l_@@_uncert_bracket_bool ,
184 % \l_@@_uncert_repeat_bool
185 % }
186 % \begin{macrocode}
187 \str_new:N \l_siunitx_quantity_prefix_mode_str
188 \tl_new:N \l_siunitx_quantity_prefix_mode_tl
189 \bool_new:N \l_@@_uncert_bracket_bool
190 \bool_new:N \l_@@_uncert_repeat_bool
191 \keys_define:nn { siunitx }
192 {
193 allow-quantity-breaks .bool_set:N =
194 \l_@@_break_bool ,
195 prefix-mode .choices:nn =
196 { combine-exponent , extract-exponent , input }
197 { \str_set_eq:NN \l_siunitx_quantity_prefix_mode_str \l_keys_choice_str } ,
198 quantity-product .tl_set:N =
199 \l_@@_product_tl ,
200 separate-uncertainty-units .choice: ,
201 separate-uncertainty-units / bracket .code:n =
202 {
203 \bool_set_true:N \l_@@_uncert_bracket_bool
204 \bool_set_false:N \l_@@_uncert_repeat_bool
205 } ,
206 separate-uncertainty-units / repeat .code:n =
207 {
208 \bool_set_false:N \l_@@_uncert_bracket_bool
209 \bool_set_true:N \l_@@_uncert_repeat_bool
210 } ,
211 separate-uncertainty-units / single .code:n =
212 {
213 \bool_set_false:N \l_@@_uncert_bracket_bool
214 \bool_set_false:N \l_@@_uncert_repeat_bool
215 }
216 }
217 % \end{macrocode}
218 % \end{variable}
219 %
220 % \begin{variable}{\l_@@_number_tl, \l_@@_unit_tl}
221 % \begin{macrocode}
222 \tl_new:N \l_@@_number_tl
223 \tl_new:N \l_@@_unit_tl
224 % \end{macrocode}
225 % \end{variable}
226 %
227 % \begin{macro}{\siunitx_quantity:nn, \@@_parsed:nn}
228 % \begin{macro}
229 % {
230 % \@@_parsed_combine-exponent:n,
231 % \@@_parsed_combine-exponent:n,
232 % \@@_parsed_input:n
233 % }
234 % \begin{macro}{\@@_parsed_aux:w}
235 % \begin{macro}{\@@_parsed_aux:nnnw}
236 % \begin{macro}{\@@_parsed_aux:nnnnw}
237 % \begin{macro}{\@@_parsed_aux:nnnn, \@@_parsed_aux:onnn}
238 % \begin{macro}{\@@_parsed_aux:nnn}
239 % For quantities, there is bit to do to combine things. The first question is
240 % whether we are parsing at all: if not, things are quite short. Notice that
241 % within this group we turn off bracketing in the number formatter: we
242 % have to deal with quantity-based brackets instead.
243 % \begin{macrocode}
244 \cs_new_protected:Npn \siunitx_quantity:nn #1#2
245 {
246 \group_begin:
247 \siunitx_unit_options_apply:n {#2}
248 \tl_if_blank:nTF {#1}
249 {
250 \siunitx_unit_format:nN {#2} \l_@@_unit_tl
251 \siunitx_print_unit:V \l_@@_unit_tl
252 }
253 {
254 \bool_if:NTF \l_siunitx_number_parse_bool
255 { \@@_parsed:nn {#1} {#2} }
256 {
257 \tl_set:Nn \l_@@_number_tl { \ensuremath {#1} }
258 \siunitx_unit_format:nN {#2} \l_@@_unit_tl
259 \siunitx_quantity_print:VV
260 \l_@@_number_tl \l_@@_unit_tl
261 }
262 }
263 \group_end:
264 }
265 % \end{macrocode}
266 % For parsed numbers, we have two major questions to think about: whether we
267 % are combining prefixes, and whether we have a multi-part numbers to handle.
268 % Number processing has to be delayed it needs to come after any extracted
269 % exponent is combined.
270 % \begin{macrocode}
271 \cs_new_protected:Npn \@@_parsed:nn #1#2
272 {
273 \bool_set_false:N \l_siunitx_number_bracket_ambiguous_bool
274 \siunitx_number_parse:nN {#1} \l_@@_number_tl
275 \use:c { @@_parsed_ \l_siunitx_quantity_prefix_mode_str :n } {#2}
276 \tl_set:Ne \l_@@_number_tl
277 { \siunitx_number_output:NN \l_@@_number_tl \q_nil }
278 \exp_after:wN \@@_parsed_aux:w \l_@@_number_tl \q_stop
279 }
280 \cs_new_protected:cpn { @@_parsed_combine-exponent:n } #1
281 {
282 \siunitx_number_process:NN \l_@@_number_tl \l_@@_number_tl
283 \@@_extract_exp:VNN
284 \l_@@_number_tl \l_@@_tmp_fp \l_@@_number_tl
285 \siunitx_unit_format_combine_exponent:nnN {#1}
286 \l_@@_tmp_fp \l_@@_unit_tl
287 }
288 \cs_new_protected:cpn { @@_parsed_extract-exponent:n } #1
289 {
290 \siunitx_unit_format_extract_prefixes:nNN {#1}
291 \l_@@_unit_tl \l_@@_tmp_fp
292 \tl_set:Ne \l_@@_number_tl
293 {
294 \siunitx_number_adjust_exponent:Nn
295 \l_@@_number_tl \l_@@_tmp_fp
296 }
297 \siunitx_number_process:NN \l_@@_number_tl \l_@@_number_tl
298 }
299 \cs_new_protected:Npn \@@_parsed_input:n #1
300 {
301 \siunitx_number_process:NN \l_@@_number_tl \l_@@_number_tl
302 \siunitx_unit_format:nN {#1} \l_@@_unit_tl
303 }
304 % \end{macrocode}
305 % To find out if we need to work harder, we first need to split the formatted
306 % number into the constituent parts. That is done using the table-like
307 % approach: that avoids needing to both check the settings and break down
308 % the input separately.
309 % \begin{macrocode}
310 \cs_new_protected:Npn \@@_parsed_aux:w
311 #1 \q_nil #2 \q_nil #3 \q_nil #4 \q_nil #5 \q_nil #6 \q_nil #7 \q_nil
312 #8 \q_nil #9 \q_stop
313 { \@@_parsed_aux:nnnw {#1} {#2#3#4#5} {#6#7#8} #9 \q_stop }
314 \cs_new_protected:Npn \@@_parsed_aux:nnnw #1#2#3 #4 \q_nil
315 { \@@_parsed_aux:nnnnw {#1} {#2} {#3} {#4} ? }
316 \cs_new_protected:Npn \@@_parsed_aux:nnnnw
317 #1#2#3#4 #5 \q_nil #6 \q_stop
318 { \@@_parsed_aux:onnn { \use_none:n #5#6 } {#1} {#2} {#3#4} }
319 \cs_new_protected:Npn \@@_parsed_aux:nnnn #1#2#3#4
320 {
321 \tl_if_blank:nTF {#4}
322 { \siunitx_quantity_print:nV {#2#3#1} \l_@@_unit_tl }
323 {
324 \bool_if:NTF \l_@@_uncert_bracket_bool
325 {
326 \siunitx_quantity_print:eV
327 {
328 \exp_not:n {#2}
329 \exp_not:V \l_@@_bracket_open_tl
330 \exp_not:n {#3#4}
331 \exp_not:V \l_@@_bracket_close_tl
332 \exp_not:n {#1}
333 }
334 \l_@@_unit_tl
335 }
336 {
337 \bool_if:NTF \l_@@_uncert_repeat_bool
338 {
339 \tl_if_blank:nTF {#1}
340 { \@@_parsed_aux:nnn {#2#3} {#4} { } }
341 { \@@_parsed_aux:nnn {#2#3} {#4} { { } #1 } }
342 }
343 { \siunitx_quantity_print:nV {#2#3#4#1} \l_@@_unit_tl }
344 }
345 }
346 }
347 \cs_generate_variant:Nn \@@_parsed_aux:nnnn { o }
348 % \end{macrocode}
349 % For the case of a separated uncertainty with repeated units, we print the
350 % two parts independently. The third argument here is the exponent if there
351 % is one, with the spacing correct in either case as we only pass the empty
352 % group if one is required.
353 % \begin{macrocode}
354 \cs_new_protected:Npn \@@_parsed_aux:nnn #1#2#3
355 {
356 \siunitx_quantity_print:nV {#1#3} \l_@@_unit_tl
357 \tl_if_blank:nF {#2}
358 { \siunitx_quantity_print:nV { { } #2#3 } \l_@@_unit_tl }
359 }
360 % \end{macrocode}
361 % \end{macro}
362 % \end{macro}
363 % \end{macro}
364 % \end{macro}
365 % \end{macro}
366 % \end{macro}
367 % \end{macro}
368 %
369 % \begin{macro}{\@@_extract_exp:nNN, \@@_extract_exp:VNN}
370 % \begin{macro}{\@@_extract_exp:nnnnnnnNN}
371 % To extract the exponent part for a combined prefix, we decompose the value
372 % and remove it. As the exponent part may be entirely empty, we add a filler
373 % zero.
374 % \begin{macrocode}
375 \cs_new_protected:Npn \@@_extract_exp:nNN #1#2#3
376 { \@@_extract_exp:nnnnnnnNN #1 #2 #3 }
377 \cs_generate_variant:Nn \@@_extract_exp:nNN { V }
378 \cs_new_protected:Npn \@@_extract_exp:nnnnnnnNN #1#2#3#4#5#6#7#8#9
379 {
380 \fp_set:Nn #8 { #6 0#7 }
381 \tl_set:Ne #9
382 { {#1} {#2} {#3} {#4} {#5} { } { } }
383 }
384 % \end{macrocode}
385 % \end{macro}
386 % \end{macro}
387 %
388 % \begin{macro}
389 % {
390 % \siunitx_quantity_print:nn, \siunitx_quantity_print:nV,
391 % \siunitx_quantity_print:VV, \siunitx_quantity_print:eV
392 % }
393 % \begin{macro}{\@@_print_unit:n}
394 % \begin{macro}{\@@_print_mathchoice:Nnnnn}
395 % \begin{macro}{\@@_print_mathchoice:nnN}
396 % For printing a single part of a quantity. This is needed for compound
397 % quantities and so is public: that's also the reason for passing both
398 % argument explicitly. The semantics here require that the penalty and
399 % spacing are always applied: the number argument may be empty. The lazy test
400 % here is looking for the case where a |1| has been inserted at the start of
401 % a format unit \emph{and} we have some other number to print: the |1| is
402 % then removed and there is no space inserted.
403 % \begin{macrocode}
404 \cs_new_protected:Npn \siunitx_quantity_print:nn #1#2
405 {
406 \siunitx_print_number:n {#1}
407 \tl_if_blank:nF {#2}
408 {
409 \tl_if_blank:nTF {#1}
410 { \@@_print_unit:n {#2} }
411 {
412 \tl_if_head_eq_charcode:nNTF {#2} 1
413 { \siunitx_print_unit:o { \use_none:n #2 } }
414 {
415 \tl_if_head_eq_meaning:nNTF {#2} \mathchoice
416 { \@@_print_mathchoice:Nnnnn #2 }
417 { \@@_print_unit:n {#2} }
418 }
419 }
420 }
421 }
422 \cs_generate_variant:Nn \siunitx_quantity_print:nn { nV , VV , eV , xV }
423 \cs_new_protected:Npn \@@_print_unit:n #1
424 {
425 \bool_if:NTF \l_@@_break_bool
426 { \penalty \binoppenalty }
427 { \nobreak }
428 \tl_use:N \l_@@_product_tl
429 \siunitx_print_unit:n {#1}
430 }
431 % \end{macrocode}
432 % If the first token of the unit is |\mathchoice|, we are looking at
433 % formatting differently in display and inline math modes. If we then have a
434 % leading |1|, then it needs to be lopped off. We also need to remember here
435 % that the spacing also needs to be inside the |\mathchoice|, as it only
436 % applies in display mode. To get all of this to work, there is then some
437 % nesting of print functions: unavoidable. As |#3|, |#4| and |#5| are
438 % identical, expansion can take place just once to pass the trimmed tokens.
439 % \begin{macrocode}
440 \cs_new_protected:Npn \@@_print_mathchoice:Nnnnn #1#2#3#4#5
441 {
442 \tl_if_head_eq_charcode:nNTF {#3} 1
443 {
444 \exp_args:No \@@_print_mathchoice:nnN
445 { \use_none:n #3 } {#2} #1
446 }
447 { \@@_print_unit:n { #1 {#2} {#3} {#4} {#5} } }
448 }
449 \cs_new_protected:Npn \@@_print_mathchoice:nnN #1#2#3
450 {
451 \siunitx_print_unit:n
452 { #3 { \@@_print_unit:n {#2} } {#1} {#1} {#1} }
453 }
454 % \end{macrocode}
455 % \end{macro}
456 % \end{macro}
457 % \end{macro}
458 % \end{macro}
459 %
460 % \subsection{Standard settings for module options}
461 %
462 % Some of these follow naturally from the point of definition
463 % (\foreign{e.g.}~boolean variables are always |false| to begin with),
464 % but for clarity everything is set here.
465 % \begin{macrocode}
466 \keys_set:nn { siunitx }
467 {
468 allow-quantity-breaks = false ,
469 prefix-mode = input ,
470 quantity-product = \, ,
471 separate-uncertainty-units = bracket
472 }
473 % \end{macrocode}
474 %
475 % \subsection{Adjustments to units}
476 %
477 % \begin{macro}{\arcminute, \arcsecond, \degree}
478 % The angles units are adjusted here: this is needed for using it
479 % in quantities. This is done here as it avoids a dependency in
480 % \pkg{siunitx-unit} on options it does not contain.
481 % \begin{macrocode}
482 \siunitx_unit_options_declare:Nn \arcminute
483 { prefix-mode = input , quantity-product = { } }
484 \siunitx_unit_options_declare:Nn \arcsecond
485 { prefix-mode = input , quantity-product = { } }
486 \siunitx_unit_options_declare:Nn \degree
487 { prefix-mode = input , quantity-product = { } }
488 \siunitx_unit_options_declare:Nn \percent
489 { prefix-mode = input }
490 % \end{macrocode}
491 % \end{macro}
492 %
493 % \begin{macrocode}
494 %</package>
495 % \end{macrocode}
496 %
497 % \end{implementation}
498 %
499 % \PrintIndex