| 1 |
\iffalse meta-comment |
| 2 |
|
| 3 |
File: siunitx.tex Copyright (C) 2014-2025 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 |
\fi |
| 28 |
|
| 29 |
\DocumentMetadata{lang = en, pdfversion = 2.0} |
| 30 |
|
| 31 |
\documentclass[a4paper]{l3doc} |
| 32 |
|
| 33 |
% The next line is needed so that \GetFileInfo will be able to pick up |
| 34 |
% version data (quite apart from making the demos work). |
| 35 |
\usepackage{siunitx} |
| 36 |
% So we can have 'sensible' demos for \arcsecond |
| 37 |
\DeclareSIUnit\arcsecond{as} |
| 38 |
\DeclareSIUnit[quantity-product = {}]\stdarcsecond{\ensuremath {{}''}} |
| 39 |
\sisetup{angle-symbol-second = \stdarcsecond} |
| 40 |
\DeclareSIUnit\noop{\relax} % For printing prefixes |
| 41 |
\DeclareSIPower\quartic\tothefourth{4} % For demos |
| 42 |
\DeclareSIUnit\KWH{kWh} |
| 43 |
\DeclareSIQualifier\polymer{pol} |
| 44 |
\DeclareSIQualifier\catalyst{cat} |
| 45 |
\DeclareSIUnit\millimetremercury{mmHg} |
| 46 |
|
| 47 |
% Commands for this document |
| 48 |
\ExplSyntaxOn |
| 49 |
\makeatletter |
| 50 |
\NewDocumentCommand \acro { m } |
| 51 |
{ |
| 52 |
\textsc |
| 53 |
{ |
| 54 |
\exp_args:NV \tl_if_head_eq_charcode:nNTF \f@series { m } |
| 55 |
{ \text_lowercase:n } |
| 56 |
{ \use:n } |
| 57 |
{#1} |
| 58 |
} |
| 59 |
} |
| 60 |
\makeatother |
| 61 |
\ExplSyntaxOff |
| 62 |
\NewDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}} |
| 63 |
\NewDocumentCommand\ext{m}{\texttt{.#1}} |
| 64 |
\NewDocumentCommand\foreign{m}{\textit{#1}} |
| 65 |
\NewDocumentCommand\opt{m}{\texttt{#1}} |
| 66 |
\NewDocumentCommand\version{m}{\ensuremath{#1}} |
| 67 |
% Tidy up the above in bookmarks |
| 68 |
\makeatletter |
| 69 |
\pdfstringdefDisableCommands{% |
| 70 |
\let\acro\@firstofone |
| 71 |
\let\ext\@firstofone |
| 72 |
\let\foreign\@firstofone |
| 73 |
\let\opt\@firstofone |
| 74 |
\let\version\@firstofone |
| 75 |
} |
| 76 |
\makeatother |
| 77 |
|
| 78 |
\NewDocumentCommand\DescribePrefix{m}{% |
| 79 |
#1 & |
| 80 |
\cs{#1} & |
| 81 |
\unit{\csname #1\endcsname\noop} |
| 82 |
} |
| 83 |
\NewDocumentCommand\DescribeUnit{O{#2}m}{% |
| 84 |
#1 & |
| 85 |
\cs{#2} & |
| 86 |
\unit{\csname #2\endcsname} |
| 87 |
} |
| 88 |
|
| 89 |
% For demos |
| 90 |
\usepackage[portuguese,brazilian,catalan,french,german,italian,polish,spanish,UKenglish]{babel} |
| 91 |
\AtBeginDocument{\shorthandoff{<>}} |
| 92 |
\usepackage{translations} |
| 93 |
\usepackage{cancel} |
| 94 |
\usepackage{collcell} |
| 95 |
\usepackage{sansmath} |
| 96 |
\usepackage{steinmetz} |
| 97 |
\newlength{\mylength} |
| 98 |
|
| 99 |
% For creating code demonstrations |
| 100 |
% This needs access to some code-level interfaces in listings |
| 101 |
\usepackage{listings} |
| 102 |
\makeatletter |
| 103 |
\lst@RequireAspects{writefile} |
| 104 |
\newsavebox\LaTeXdemo@box |
| 105 |
\lstnewenvironment{LaTeXdemo}[1][code and example] |
| 106 |
{% |
| 107 |
\global\let\lst@intname\@empty |
| 108 |
\edef\LaTeXdemo@end{% |
| 109 |
\expandafter\noexpand\csname LaTeXdemo@@#1@end\endcsname |
| 110 |
}% |
| 111 |
\@nameuse{LaTeXdemo@@#1}% |
| 112 |
} |
| 113 |
{\LaTeXdemo@end} |
| 114 |
\newcommand\LaTeXdemo@new[3]{% |
| 115 |
\@namedef{LaTeXdemo@@#1}{#2}% |
| 116 |
\@namedef{LaTeXdemo@@#1@end}{#3}% |
| 117 |
} |
| 118 |
\newcommand*\LaTeXdemo@common{% |
| 119 |
\setkeys{lst} |
| 120 |
{% |
| 121 |
basicstyle = \small\ttfamily, |
| 122 |
basewidth = 0.51em, |
| 123 |
gobble = 2, |
| 124 |
language = [LaTeX]{TeX}, |
| 125 |
}% |
| 126 |
} |
| 127 |
\newcount\LaTeXdemo@count |
| 128 |
\newcommand*\LaTeXdemo@input{% |
| 129 |
\catcode`\^^M = 10\relax |
| 130 |
\input{\jobname-\number\[email protected]}% |
| 131 |
} |
| 132 |
\LaTeXdemo@new{code and example}{% |
| 133 |
\setbox\LaTeXdemo@box=\hbox\bgroup |
| 134 |
\global\advance\LaTeXdemo@count by 1 % |
| 135 |
\lst@BeginAlsoWriteFile{\jobname-\number\[email protected]}% |
| 136 |
\LaTeXdemo@common |
| 137 |
}{% |
| 138 |
\lst@EndWriteFile |
| 139 |
\egroup |
| 140 |
\begin{center} |
| 141 |
\ifdim\wd\LaTeXdemo@box > 0.48\linewidth |
| 142 |
\begin{minipage}{\linewidth} |
| 143 |
\usebox\LaTeXdemo@box |
| 144 |
\end{minipage}% |
| 145 |
\par |
| 146 |
\begin{minipage}{\linewidth} |
| 147 |
\LaTeXdemo@input |
| 148 |
\end{minipage} |
| 149 |
\else |
| 150 |
\begin{minipage}{0.48\linewidth} |
| 151 |
\LaTeXdemo@input |
| 152 |
\end{minipage}% |
| 153 |
\hspace{\fill}% |
| 154 |
\begin{minipage}{0.48\linewidth} |
| 155 |
\usebox\LaTeXdemo@box |
| 156 |
\end{minipage}% |
| 157 |
\fi |
| 158 |
\end{center} |
| 159 |
} |
| 160 |
\LaTeXdemo@new{code and float}{% |
| 161 |
\global\advance\LaTeXdemo@count by 1 % |
| 162 |
\lst@BeginAlsoWriteFile{\jobname-\number\[email protected]}% |
| 163 |
\LaTeXdemo@common |
| 164 |
}{% |
| 165 |
\lst@EndWriteFile |
| 166 |
\LaTeXdemo@input |
| 167 |
} |
| 168 |
\LaTeXdemo@new{code only}{\LaTeXdemo@common}{} |
| 169 |
\makeatother |
| 170 |
|
| 171 |
% For table demos |
| 172 |
\usepackage{datatool} |
| 173 |
\usepackage{multirow} |
| 174 |
\usepackage[table]{xcolor} |
| 175 |
% Has to come after xcolor |
| 176 |
\usepackage{pgfplots} |
| 177 |
\pgfplotsset{compat = 1.18, compat/show suggested version = false} |
| 178 |
|
| 179 |
% For the extra-long tables |
| 180 |
\usepackage{xtab} |
| 181 |
|
| 182 |
% For the table notes |
| 183 |
\usepackage{threeparttable} |
| 184 |
|
| 185 |
% Design changes |
| 186 |
\usepackage{caption} |
| 187 |
\makeatletter |
| 188 |
\edef\@floatboxreset{% |
| 189 |
\unexpanded\expandafter{\@floatboxreset}% |
| 190 |
\noexpand\centering |
| 191 |
} |
| 192 |
\makeatother |
| 193 |
%\usepackage[osf]{mathpazo} |
| 194 |
\usepackage{fontspec} |
| 195 |
\setmainfont[Numbers = OldStyle]{TeX Gyre Pagella} |
| 196 |
\usepackage{unicode-math} |
| 197 |
\setmathfont{TeX Gyre Pagella Math} |
| 198 |
|
| 199 |
\hypersetup{hidelinks} |
| 200 |
|
| 201 |
\begin{document} |
| 202 |
|
| 203 |
\GetFileInfo{siunitx.sty} |
| 204 |
|
| 205 |
\title{% |
| 206 |
\pkg{siunitx} -- A comprehensive (\acro{SI}) units package% |
| 207 |
\thanks{This file describes \fileversion, |
| 208 |
last revised \filedate.}% |
| 209 |
} |
| 210 |
|
| 211 |
\author{% |
| 212 |
Joseph Wright% |
| 213 |
\thanks{% |
| 214 |
E-mail: |
| 215 |
\email{[email protected]}% |
| 216 |
}% |
| 217 |
} |
| 218 |
|
| 219 |
\date{Released \filedate} |
| 220 |
|
| 221 |
\maketitle |
| 222 |
|
| 223 |
\tableofcontents |
| 224 |
|
| 225 |
\begin{abstract} |
| 226 |
Physical quantities have both numbers and units, and each physical quantity |
| 227 |
should be expressed as the product of a number and a unit. Typesetting |
| 228 |
physical quantities requires care to ensure that the combined mathematical |
| 229 |
meaning of the number--unit combination is clear. In particular, the |
| 230 |
\acro{SI} units system lays down a consistent set of units with rules on how |
| 231 |
these are to be used. However, different countries and publishers have |
| 232 |
differing conventions on the exact appearance of numbers (and units). The |
| 233 |
\pkg{siunitx} package provides a set of tools for authors to typeset |
| 234 |
quantities in a consistent way. The package has an extended set of |
| 235 |
configuration options which make it possible to follow varying typographic |
| 236 |
conventions with the same input syntax. The package includes automated |
| 237 |
processing of numbers and units, and the ability to control tabular alignment |
| 238 |
of numbers. |
| 239 |
\end{abstract} |
| 240 |
|
| 241 |
\begin{documentation} |
| 242 |
|
| 243 |
\section{Introduction} |
| 244 |
|
| 245 |
The correct application of units of measurement is very important in technical |
| 246 |
applications. For this reason, carefully-crafted definitions of a coherent |
| 247 |
units system have been laid down by the \foreign{Conférence Génrale des Poids |
| 248 |
et Mesures} (\acro{CGPM}): this has resulted in the \foreign{Système |
| 249 |
International d'Unités}~(\acro{SI}). At the same time, typographic conventions |
| 250 |
for correctly displaying both numbers and units exist to ensure that no loss of |
| 251 |
meaning occurs in printed matter. |
| 252 |
|
| 253 |
The \pkg{siunitx} package aims to provide a unified method for \LaTeX{} users |
| 254 |
to typeset numbers and units correctly and easily. The design philosophy of |
| 255 |
\pkg{siunitx} is to follow the agreed rules by default, but to allow variation |
| 256 |
through option settings. In this way, users can use \pkg{siunitx} to follow the |
| 257 |
requirements of publishers, co-authors, universities, \foreign{etc}.\ without |
| 258 |
needing to alter the input at all. |
| 259 |
|
| 260 |
\section{\pkg{siunitx} for the impatient} |
| 261 |
|
| 262 |
The package provides the user macros: |
| 263 |
\begin{itemize} |
| 264 |
\item \cs{ang}\oarg{options}\marg{angle} |
| 265 |
\item \cs{duration}\oarg{options}\marg{duration} |
| 266 |
\item \cs{num}\oarg{options}\marg{number} |
| 267 |
\item \cs{unit}\oarg{options}\marg{unit} |
| 268 |
\item \cs{qty}\oarg{options}\marg{number}\marg{unit} |
| 269 |
\item \cs{numlist}\oarg{options}\marg{numbers} |
| 270 |
\item \cs{numproduct}\oarg{options}\marg{numbers} |
| 271 |
\item \cs{numrange}\oarg{options}\marg{numbers}\marg{number2} |
| 272 |
\item \cs{qtylist}\oarg{options}\marg{numbers}\marg{unit} |
| 273 |
\item \cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit} |
| 274 |
\item \cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit} |
| 275 |
\item \cs{complexnum}\oarg{options}\marg{number} |
| 276 |
\item \cs{complexqty}\oarg{options}\marg{number}\marg{unit} |
| 277 |
\item \cs{sisetup}\marg{options} |
| 278 |
\item \cs{tablenum}\oarg{options}\marg{number} |
| 279 |
\end{itemize} |
| 280 |
plus the \texttt{S} column type for decimal alignments and units in tabular |
| 281 |
environments. These user macros and column types are designed for typesetting |
| 282 |
numbers and units with control of appearance and with intelligent processing. |
| 283 |
|
| 284 |
Numbers are processed with understanding of exponents, or using additional |
| 285 |
commands for products and complex numbers. |
| 286 |
\begin{LaTeXdemo} |
| 287 |
\num{12345,67890} \\ |
| 288 |
\num{.3e45} \\ |
| 289 |
\complexnum{1+-2i} \\ |
| 290 |
\numproduct{1.654 x 2.34 x 3.430} |
| 291 |
\end{LaTeXdemo} |
| 292 |
|
| 293 |
The unit system can interpret units given as text to be used directly or as |
| 294 |
macro-based units. In the latter case, different formatting is possible. |
| 295 |
\begin{LaTeXdemo} |
| 296 |
\unit{kg.m.s^{-1}} \\ |
| 297 |
\unit{\kilogram\metre\per\second} \\ |
| 298 |
\unit[per-mode = symbol] |
| 299 |
{\kilogram\metre\per\second} \\ |
| 300 |
\unit[per-mode = symbol] |
| 301 |
{\kilogram\metre\per\ampere\per\second} |
| 302 |
\end{LaTeXdemo} |
| 303 |
|
| 304 |
Simple lists and ranges of numbers can be handled. |
| 305 |
\begin{LaTeXdemo} |
| 306 |
\numlist{10;20;30} \\ |
| 307 |
\qtylist{0.13;0.67;0.80}{\milli\metre} \\ |
| 308 |
\numrange{10}{20} \\ |
| 309 |
\qtyrange{0.13}{0.67}{\milli\metre} |
| 310 |
\end{LaTeXdemo} |
| 311 |
|
| 312 |
A wide range of options are available to control the behavior of the package. |
| 313 |
For example, with the standard settings all text is typeset in the current |
| 314 |
upright math font. This can be adjusted to use text mode, follow various |
| 315 |
aspects of the surrounding formatting, \foreign{etc}. Similarly, the standard |
| 316 |
settings are based around an English-speaking locale, but can be adjusted |
| 317 |
to follow the traditions of other areas. |
| 318 |
|
| 319 |
\section{Using the \pkg{siunitx} package} |
| 320 |
|
| 321 |
\subsection{Numbers} |
| 322 |
|
| 323 |
\begin{function}{\num} |
| 324 |
\begin{syntax} |
| 325 |
\cs{num}\oarg{options}\marg{number} |
| 326 |
\end{syntax} |
| 327 |
\end{function} |
| 328 |
Numbers are automatically formatted by the \cs{num} macro. This takes one |
| 329 |
optional argument, \meta{options}, and one mandatory one, \meta{number}. The |
| 330 |
contents of \meta{number} are automatically formatted. The formatter removes |
| 331 |
both \enquote{soft} (\verb*| |) and \enquote{hard} spaces (|\,| and |~|), |
| 332 |
automatically identifies exponents (as standard marked using |e|, |E|, |d| or |
| 333 |
|D|) and adds the appropriate spacing of large numbers. If required, |
| 334 |
a leading zero is added before a decimal marker: both |.| |
| 335 |
and "," are recognised as decimal markers. |
| 336 |
\begin{LaTeXdemo} |
| 337 |
\num{123} \\ |
| 338 |
\num{1234} \\ |
| 339 |
\num{12345} \\ |
| 340 |
\num{0.123} \\ |
| 341 |
\num{0,1234} \\ |
| 342 |
\num{.12345} \\ |
| 343 |
\num{3.45d-4} \\ |
| 344 |
\num{-e10} |
| 345 |
\end{LaTeXdemo} |
| 346 |
|
| 347 |
Note that numbers are parsed before typesetting, which does have a performance |
| 348 |
overhead (only obvious with very large amounts of numerical input). The parser |
| 349 |
understands a range of input syntaxes, as demonstrated above. |
| 350 |
|
| 351 |
\begin{function}{\numlist} |
| 352 |
\begin{syntax} |
| 353 |
\cs{numlist}\oarg{options}\marg{numbers} |
| 354 |
\end{syntax} |
| 355 |
\end{function} |
| 356 |
Lists of numbers may be processed using the \cs{numlist} function. Each |
| 357 |
\meta{number} is given within the list of \meta{numbers} within a brace pair, |
| 358 |
as the list can have a flexible length. |
| 359 |
\begin{LaTeXdemo} |
| 360 |
\numlist{10;30;50;70} |
| 361 |
\end{LaTeXdemo} |
| 362 |
|
| 363 |
\begin{function}{\numproduct} |
| 364 |
\begin{syntax} |
| 365 |
\cs{numproduct}\oarg{options}\marg{numbers} |
| 366 |
\end{syntax} |
| 367 |
\end{function} |
| 368 |
Runs of products of numbers may be inserted using the \cs{numproduct} function. |
| 369 |
This acts in the same way as \cs{num}, but inserts either a symbol or phrase |
| 370 |
between the entries. The latter should be separated by |x| tokens. |
| 371 |
\begin{LaTeXdemo} |
| 372 |
\numproduct{10 x 30} |
| 373 |
\end{LaTeXdemo} |
| 374 |
|
| 375 |
\begin{function}{\numrange} |
| 376 |
\begin{syntax} |
| 377 |
\cs{numrange}\oarg{options}\marg{number1}\marg{number2} |
| 378 |
\end{syntax} |
| 379 |
\end{function} |
| 380 |
Simple ranges of numbers can be handled using the \cs{numrange} function. This |
| 381 |
acts in the same way as \cs{num}, but inserts a phrase or other text between |
| 382 |
the two entries. |
| 383 |
\begin{LaTeXdemo} |
| 384 |
\numrange{10}{30} |
| 385 |
\end{LaTeXdemo} |
| 386 |
|
| 387 |
\subsection{Angles} |
| 388 |
|
| 389 |
\begin{function}{\ang} |
| 390 |
\begin{syntax} |
| 391 |
\cs{ang}\oarg{options}\marg{angle} |
| 392 |
\end{syntax} |
| 393 |
\end{function} |
| 394 |
Angles can be typeset using the \cs{ang} command. The \meta{angle} can be given |
| 395 |
either as a decimal number or as a semi-colon separated list of degrees, |
| 396 |
minutes and seconds, which is called \enquote{arc format} in this document. The |
| 397 |
numbers which make up an angle are processed using the same system as other |
| 398 |
numbers. However, no unit prefixes are applied here: as such, conversion from |
| 399 |
exponent form to unit prefixes does not apply. |
| 400 |
\begin{LaTeXdemo} |
| 401 |
\ang{10} \\ |
| 402 |
\ang{12.3} \\ |
| 403 |
\ang{4,5} \\ |
| 404 |
\ang{1;2;3} \\ |
| 405 |
\ang{;;1} \\ |
| 406 |
\ang{+10;;} \\ |
| 407 |
\ang{-0;1;} |
| 408 |
\end{LaTeXdemo} |
| 409 |
|
| 410 |
\subsection{Durations} |
| 411 |
|
| 412 |
\begin{function}{\duration} |
| 413 |
\begin{syntax} |
| 414 |
\cs{duration}\oarg{options}\marg{angle} |
| 415 |
\end{syntax} |
| 416 |
\end{function} |
| 417 |
Durations (of hours, minutes and seconds) can be typeset using the |
| 418 |
\cs{duration} command. The \meta{duration} can be given either as a decimal |
| 419 |
number or as a semi-colon separated list of hours, minutes and seconds, which |
| 420 |
is called \enquote{component format} in this document. The numbers which make |
| 421 |
up a duration are processed using the same system as other numbers. However, no |
| 422 |
unit prefixes are applied here: as such, conversion from exponent form to unit |
| 423 |
prefixes does not apply. |
| 424 |
\begin{LaTeXdemo} |
| 425 |
\duration{10} \\ |
| 426 |
\duration{12.3} \\ |
| 427 |
\duration{4,5} \\ |
| 428 |
\duration{1;2;3} \\ |
| 429 |
\duration{;;1} \\ |
| 430 |
\duration{+10;;} \\ |
| 431 |
\duration{-0;1;} |
| 432 |
\end{LaTeXdemo} |
| 433 |
|
| 434 |
\subsection{Units} |
| 435 |
|
| 436 |
\begin{function}{\unit} |
| 437 |
\begin{syntax} |
| 438 |
\cs{unit}\oarg{options}\marg{unit} |
| 439 |
\end{syntax} |
| 440 |
\end{function} |
| 441 |
The symbol for a unit can be typeset using the \cs{unit} macro: this provides |
| 442 |
full control over output format for the unit. Like the \cs{num} macro, |
| 443 |
\cs{unit} takes one optional and one mandatory argument. The unit formatting |
| 444 |
system can accept two types of input. When the \meta{unit} contains literal |
| 445 |
items (for example letters or numbers) then \pkg{siunitx} converts |.| and |~| |
| 446 |
into inter-unit product and correctly positions sub- and superscripts specified |
| 447 |
using |_| and |^|. The formatting methods will work with both math and text |
| 448 |
mode. |
| 449 |
\begin{LaTeXdemo} |
| 450 |
\unit{kg.m/s^2} \\ |
| 451 |
\unit{g_{polymer}~mol_{cat}.s^{-1}} |
| 452 |
\end{LaTeXdemo} |
| 453 |
|
| 454 |
The second operation mode for the \cs{unit} macro is an \enquote{interpreted} |
| 455 |
system. Here each unit, \acro{SI} multiple prefix and power is given a macro |
| 456 |
name. These are entered in a method very similar to the reading of the unit |
| 457 |
name in English. |
| 458 |
\begin{LaTeXdemo} |
| 459 |
\unit{\kilo\gram\metre\per\square\second} \\ |
| 460 |
\unit{\gram\per\cubic\centi\metre} \\ |
| 461 |
\unit{\square\volt\cubic\lumen\per\farad} \\ |
| 462 |
\unit{\metre\squared\per\gray\cubic\lux} \\ |
| 463 |
\unit{\henry\second} |
| 464 |
\end{LaTeXdemo} |
| 465 |
|
| 466 |
On its own, this is less convenient than the direct method, although it does |
| 467 |
use meaning rather than appearance for input. However, the package allows you |
| 468 |
to define new unit macros; a large number of pre-defined abbreviations are also |
| 469 |
supplied. More importantly, by defining macros for units, instead of literal |
| 470 |
input, new functionality is made available. By altering the settings used by |
| 471 |
the package, the same input can yield a variety of different output formats. |
| 472 |
For example, the \cs{per} macro can give reciprocal powers, slashes or be used |
| 473 |
to construct units as fractions. |
| 474 |
|
| 475 |
\begin{function}{\qty} |
| 476 |
\begin{syntax} |
| 477 |
\cs{qty}\oarg{options}\marg{number}\marg{unit} |
| 478 |
\end{syntax} |
| 479 |
\end{function} |
| 480 |
Very often, numbers and units are given together. Formally, the value of a |
| 481 |
quantity is the product of the number and the unit, the space being regarded as |
| 482 |
a multiplication sign. The \cs{qty} macro combines the |
| 483 |
functionality of \cs{num} and \cs{unit}, and makes this both possible and easy. |
| 484 |
The \meta{number} and \meta{unit} arguments work exactly like those for the |
| 485 |
\cs{num} and \cs{unit} macros, respectively. |
| 486 |
\begin{LaTeXdemo} |
| 487 |
\qty[mode = text]{1.23}{J.mol^{-1}.K^{-1}} \\ |
| 488 |
\qty{.23e7}{\candela} \\ |
| 489 |
\qty[per-mode = symbol]{1.99}{\per\kilogram} \\ |
| 490 |
\qty[per-mode = fraction]{1,345}{\coulomb\per\mole} |
| 491 |
\end{LaTeXdemo} |
| 492 |
|
| 493 |
It is possible to set up the unit macros to be available outside of the |
| 494 |
\cs{qty} and \cs{unit} functions. This is not the standard behavior as there is |
| 495 |
the risk of name clashes (for example, \cs{day} is a \TeX{} primitive and |
| 496 |
several packages define \cs{degree}). Full details of using \enquote{stand |
| 497 |
alone} units are found in \ref{sec:units:creating}. |
| 498 |
|
| 499 |
\begin{function}{\qtylist} |
| 500 |
\begin{syntax} |
| 501 |
\cs{qtylist}\oarg{options}\marg{numbers}\marg{unit} |
| 502 |
\end{syntax} |
| 503 |
\end{function} |
| 504 |
Lists of numbers with units can be handled using the \cs{qtylist} function. The |
| 505 |
behavior of this function is similar to \cs{numlist}, but with the addition of |
| 506 |
the unit to each number. |
| 507 |
\begin{LaTeXdemo} |
| 508 |
\qtylist{10;30;45}{\metre} |
| 509 |
\end{LaTeXdemo} |
| 510 |
|
| 511 |
\begin{function}{\qtyproduct} |
| 512 |
\begin{syntax} |
| 513 |
\cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit} |
| 514 |
\end{syntax} |
| 515 |
\end{function} |
| 516 |
Runs of products of numbers with units can be handled using the \cs{qtyproduct} |
| 517 |
function. The behavior of this function is similar to \cs{numproduct}, but with |
| 518 |
the addition of a unit to each number. |
| 519 |
\begin{LaTeXdemo} |
| 520 |
\qtyproduct{10 x 30 x 45}{\metre} |
| 521 |
\end{LaTeXdemo} |
| 522 |
|
| 523 |
\begin{function}{\qtyrange} |
| 524 |
\begin{syntax} |
| 525 |
\cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit} |
| 526 |
\end{syntax} |
| 527 |
\end{function} |
| 528 |
Ranges of numbers with units can be handled using the \cs{qtyrange} function. |
| 529 |
The behavior of this function is similar to \cs{numrange}, but with the |
| 530 |
addition of a unit to each number. |
| 531 |
\begin{LaTeXdemo} |
| 532 |
\qtyrange{10}{30}{\metre} |
| 533 |
\end{LaTeXdemo} |
| 534 |
|
| 535 |
The input of lists, products and ranges of quantities using a single command |
| 536 |
allows them to be adjusted together. These commands are intended to allow |
| 537 |
consistent formatting of related values: as such, they apply a single |
| 538 |
unit to all of the values. This is particularly notable when using |
| 539 |
adjustment of the numerical values. |
| 540 |
|
| 541 |
\subsection{Complex numbers and quantities} |
| 542 |
|
| 543 |
\begin{function}{\complexnum} |
| 544 |
\begin{syntax} |
| 545 |
\cs{complexnum}\oarg{options}\marg{number} |
| 546 |
\end{syntax} |
| 547 |
\end{function} |
| 548 |
Typesets the complex number, which can be given in the Cartesian form $a + |
| 549 |
b\mathrm{i}$ or $a + \mathrm{i}b$, or in the polar form $r$\texttt{:}$\theta$. |
| 550 |
Processing of the numerical parts is otherwise identical to the standard |
| 551 |
\cs{num} command. |
| 552 |
|
| 553 |
\begin{function}{\complexqty} |
| 554 |
\begin{syntax} |
| 555 |
\cs{complexqty}\oarg{options}\marg{number}\marg{unit} |
| 556 |
\end{syntax} |
| 557 |
\end{function} |
| 558 |
Typesets the complex number, which can be given in the Cartesian form $a + |
| 559 |
b\mathrm{i}$ or $a + \mathrm{i}b$, or in the polar form $r$\texttt{:}$\theta$. |
| 560 |
Processing of the numerical parts is otherwise identical to the standard |
| 561 |
\cs{qty} command. |
| 562 |
|
| 563 |
\subsection{The unit macros} |
| 564 |
|
| 565 |
The package always defines the basic set of \acro{SI} units with macro names. |
| 566 |
This includes the base \acro{SI} units, the derived units with special names |
| 567 |
and the prefixes. A small number of powers are also given pre-defined names. |
| 568 |
Full details of units in the \acro{SI} are available on-line~\cite{BIPM}. |
| 569 |
|
| 570 |
The seven base \acro{SI} units are always defined (Table~\ref{tab:unit:base}). |
| 571 |
In addition, the macro \cs{meter} is available as an alias for \cs{metre}, for |
| 572 |
users of US spellings. The full details of the base units are given in the |
| 573 |
\acro{SI} Brochure. |
| 574 |
\begin{table} |
| 575 |
\caption{\acro{SI} base units.% |
| 576 |
\label{tab:unit:base}} |
| 577 |
\begin{tabular}{@{}lll@{}} |
| 578 |
\toprule |
| 579 |
Unit & Command & Symbol \\ |
| 580 |
\midrule |
| 581 |
\DescribeUnit{ampere} \\ |
| 582 |
\DescribeUnit{candela} \\ |
| 583 |
\DescribeUnit{kelvin} \\ |
| 584 |
\DescribeUnit{kilogram} \\ |
| 585 |
\DescribeUnit{metre} \\ |
| 586 |
\DescribeUnit{mole} \\ |
| 587 |
\DescribeUnit{second} \\ |
| 588 |
\bottomrule |
| 589 |
\end{tabular} |
| 590 |
\end{table} |
| 591 |
|
| 592 |
The \acro{SI} also lists a number of units which have special names and |
| 593 |
symbols: these are listed in Table~\ref{tab:unit:derived}. |
| 594 |
\begin{table} |
| 595 |
\caption{Coherent derived units in the \acro{SI} with special names and |
| 596 |
symbols.% |
| 597 |
\label{tab:unit:derived}} |
| 598 |
\begin{tabular}{@{}lll>{\qquad}lll@{}} |
| 599 |
\toprule |
| 600 |
Unit & Command & Symbol & Unit & Command & Symbol \\ |
| 601 |
\midrule |
| 602 |
\DescribeUnit{becquerel} & |
| 603 |
\DescribeUnit{newton} \\ |
| 604 |
\DescribeUnit[degree Celsius]{degreeCelsius} & |
| 605 |
\DescribeUnit{ohm} \\ |
| 606 |
\DescribeUnit{coulomb} & |
| 607 |
\DescribeUnit{pascal} \\ |
| 608 |
\DescribeUnit{farad} & |
| 609 |
\DescribeUnit{radian} \\ |
| 610 |
\DescribeUnit{gray} & |
| 611 |
\DescribeUnit{siemens} \\ |
| 612 |
\DescribeUnit{hertz} & |
| 613 |
\DescribeUnit{sievert} \\ |
| 614 |
\DescribeUnit{henry} & |
| 615 |
\DescribeUnit{steradian} \\ |
| 616 |
\DescribeUnit{joule} & |
| 617 |
\DescribeUnit{tesla} \\ |
| 618 |
\DescribeUnit{lumen} & |
| 619 |
\DescribeUnit{volt} \\ |
| 620 |
\DescribeUnit{katal} & |
| 621 |
\DescribeUnit{watt} \\ |
| 622 |
\DescribeUnit{lux} & |
| 623 |
\DescribeUnit{weber} \\ |
| 624 |
\bottomrule |
| 625 |
\end{tabular} |
| 626 |
\end{table} |
| 627 |
|
| 628 |
In addition to the official \acro{SI} units, \pkg{siunitx} also provides macros |
| 629 |
for a number of units which are accepted for use in the \acro{SI} although they |
| 630 |
are not \acro{SI} units. Table~\ref{tab:unit:accepted} lists the |
| 631 |
\enquote{accepted} units. The command \cs{percent} is also provided for use in |
| 632 |
units: this is accepted with the \acro{SI} as detailed in Section~5.4.7 of the |
| 633 |
Brochure. |
| 634 |
\begin{table} |
| 635 |
\caption{Non-\acro{SI} units accepted for use with the International System of |
| 636 |
Units.% |
| 637 |
\label{tab:unit:accepted}} |
| 638 |
\begin{tabular}{@{}lll@{}} |
| 639 |
\toprule |
| 640 |
Unit & Command & Symbol \\ |
| 641 |
\midrule |
| 642 |
\DescribeUnit[astronomical unit]{astronomicalunit} \\ |
| 643 |
\DescribeUnit{bel} \\ |
| 644 |
\DescribeUnit{dalton} \\ |
| 645 |
\DescribeUnit{day} \\ |
| 646 |
\DescribeUnit{decibel} \\ |
| 647 |
\DescribeUnit{degree} \\ |
| 648 |
\DescribeUnit{electronvolt} \\ |
| 649 |
\DescribeUnit{hectare} \\ |
| 650 |
\DescribeUnit{hour} \\ |
| 651 |
\DescribeUnit{litre} \\ |
| 652 |
& \cs{liter} & \unit{\liter} \\ |
| 653 |
\DescribeUnit[minute (plane angle)]{arcminute} \\ |
| 654 |
\DescribeUnit[minute (time)]{minute} \\ |
| 655 |
second (plane angle) & \cs{arcsecond} & \unit{\stdarcsecond} \\ |
| 656 |
\DescribeUnit{neper} \\ |
| 657 |
\DescribeUnit{tonne} \\ |
| 658 |
\bottomrule |
| 659 |
\end{tabular} |
| 660 |
\end{table} |
| 661 |
|
| 662 |
In addition to the units themselves, \pkg{siunitx} provides pre-defined macros |
| 663 |
for all of the \acro{SI} prefixes (Table~\ref{tab:unit:prefix}). |
| 664 |
The spelling \enquote{\cs{deka}} is provided for US users as an alternative to |
| 665 |
\cs{deca}. |
| 666 |
\begin{table} |
| 667 |
\caption{SI prefixes.% |
| 668 |
\label{tab:unit:prefix}} |
| 669 |
\sisetup{table-number-alignment = right, table-format = 2} |
| 670 |
\begin{tabular}{@{}llcS[table-format = -2]>{\qquad}llcS@{}} |
| 671 |
\toprule |
| 672 |
Prefix & Command & Symbol & \multicolumn{1}{l}{Power} & |
| 673 |
Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\ |
| 674 |
\midrule |
| 675 |
\DescribePrefix{quecto} & -30 & |
| 676 |
\DescribePrefix{deca} & 1 \\ |
| 677 |
\DescribePrefix{ronto} & -27 & |
| 678 |
\DescribePrefix{hecto} & 2 \\ |
| 679 |
\DescribePrefix{yocto} & -24 & |
| 680 |
\DescribePrefix{kilo} & 3 \\ |
| 681 |
\DescribePrefix{zepto} & -21 & |
| 682 |
\DescribePrefix{mega} & 6 \\ |
| 683 |
\DescribePrefix{atto} & -18 & |
| 684 |
\DescribePrefix{giga} & 9 \\ |
| 685 |
\DescribePrefix{femto} & -15 & |
| 686 |
\DescribePrefix{tera} & 12 \\ |
| 687 |
\DescribePrefix{pico} & -12 & |
| 688 |
\DescribePrefix{peta} & 15 \\ |
| 689 |
\DescribePrefix{nano} & -9 & |
| 690 |
\DescribePrefix{exa} & 18 \\ |
| 691 |
\DescribePrefix{micro} & -6 & |
| 692 |
\DescribePrefix{zetta} & 21 \\ |
| 693 |
\DescribePrefix{milli} & -3 & |
| 694 |
\DescribePrefix{yotta} & 24 \\ |
| 695 |
\DescribePrefix{centi} & -2 & |
| 696 |
\DescribePrefix{ronna} & 27 \\ |
| 697 |
\DescribePrefix{deci} & -1 & |
| 698 |
\DescribePrefix{quetta} & 30 \\ |
| 699 |
\bottomrule |
| 700 |
\end{tabular} |
| 701 |
\end{table} |
| 702 |
|
| 703 |
A small number of pre-defined powers are provided as macros. \cs{square} and |
| 704 |
\cs{cubic} are intended for use before units, with \cs{squared} and \cs{cubed} |
| 705 |
going after the unit. |
| 706 |
\begin{LaTeXdemo} |
| 707 |
\unit{\square\becquerel} \\ |
| 708 |
\unit{\joule\squared\per\lumen} \\ |
| 709 |
\unit{\cubic\lux\volt\tesla\cubed} |
| 710 |
\end{LaTeXdemo} |
| 711 |
Generic powers can be inserted on a one-off basis using the \cs{tothe} and |
| 712 |
\cs{raiseto} macros. These are the only macros for units which take an |
| 713 |
argument: |
| 714 |
\begin{LaTeXdemo} |
| 715 |
\unit{\henry\tothe{5}} \\ |
| 716 |
\unit{\raiseto{4.5}\radian} |
| 717 |
\end{LaTeXdemo} |
| 718 |
Reciprocal powers are indicated using the \cs{per} macro. This applies to the |
| 719 |
next unit only, unless the \opt{sticky-per} option is turned on. |
| 720 |
\begin{LaTeXdemo} |
| 721 |
\unit{\joule\per\mole\per\kelvin} \\ |
| 722 |
\unit{\joule\per\mole\kelvin} \\ |
| 723 |
\unit{\per\henry\tothe{5}} \\ |
| 724 |
\unit{\per\square\becquerel} |
| 725 |
\end{LaTeXdemo} |
| 726 |
As for generic powers, generic qualifiers are also available using the \cs{of} |
| 727 |
function: |
| 728 |
\begin{LaTeXdemo} |
| 729 |
\unit{\kilogram\of{metal}} \\ |
| 730 |
\qty[qualifier-mode = bracket] |
| 731 |
{0.1}{\milli\mole\of{cat}\per\kilogram\of{prod}} |
| 732 |
\end{LaTeXdemo} |
| 733 |
|
| 734 |
When the \pkg{cancel} package is loaded, it is possible to \enquote{cancel out} |
| 735 |
units using the \cs{cancel} macro. This applies to the next unit, in a similar |
| 736 |
manner to a prefix. The \cs{highlight} macro is also available to selectively |
| 737 |
color units. Both \cs{cancel} and \cs{highlight} are outside of the normal |
| 738 |
semantic meaning of units, but are provided as they may be useful in some |
| 739 |
cases. |
| 740 |
\begin{LaTeXdemo} |
| 741 |
\unit[per-mode = fraction] |
| 742 |
{\cancel\kilogram\metre\per\cancel\kilogram\per\second} \\ |
| 743 |
\unit{\highlight{red}\kilogram\metre\per\second} \\ |
| 744 |
\unit[unit-color = purple] |
| 745 |
{\highlight{blue}\kilogram\metre\per\second} |
| 746 |
\end{LaTeXdemo} |
| 747 |
|
| 748 |
\subsection{Unit abbreviations} |
| 749 |
|
| 750 |
In addition to the \enquote{full} names, \pkg{siunitx} loads a set of |
| 751 |
abbreviated versions of the \acro{SI} units (Table~\ref{tab:unit:abbr}). The |
| 752 |
standard \pkg{siunitx} settings only create these abbreviations within the |
| 753 |
scope of the \cs{unit} and \cs{qty} functions, meaning that no clashes should |
| 754 |
occur (for example with the standard \cs{pm} symbol). |
| 755 |
\begin{center} |
| 756 |
\tablecaption{Unit abbreviations} |
| 757 |
\label{tab:unit:abbr} |
| 758 |
\tablefirsthead{% |
| 759 |
\toprule |
| 760 |
\multicolumn{1}{@{}l}{Unit} & |
| 761 |
\multicolumn{1}{l}{Abbreviation} & |
| 762 |
\multicolumn{1}{l@{}}{Symbol} \\ |
| 763 |
\midrule |
| 764 |
} |
| 765 |
\tablehead{% |
| 766 |
\multicolumn{3}{@{}l@{}}{\emph{Continued from previous page}} \\ |
| 767 |
\toprule |
| 768 |
\multicolumn{1}{@{}l}{Unit} & |
| 769 |
\multicolumn{1}{l}{Abbreviation} & |
| 770 |
\multicolumn{1}{l@{}}{Symbol} \\ |
| 771 |
\midrule |
| 772 |
} |
| 773 |
\tabletail{% |
| 774 |
\bottomrule |
| 775 |
\multicolumn{3}{@{}r@{}}{\emph{Continued on next page}} \\ |
| 776 |
} |
| 777 |
\tablelasttail{\bottomrule} |
| 778 |
\begin{xtabular}{@{}lcc@{}} |
| 779 |
\DescribeUnit[femtogram]{fg} \\ |
| 780 |
\DescribeUnit[picogram]{pg} \\ |
| 781 |
\DescribeUnit[nanogram]{ng} \\ |
| 782 |
\DescribeUnit[microgram]{ug} \\ |
| 783 |
\DescribeUnit[milligram]{mg} \\ |
| 784 |
\DescribeUnit[gram]{g} \\ |
| 785 |
\DescribeUnit[kilogram]{kg} \\ |
| 786 |
|
| 787 |
\midrule |
| 788 |
|
| 789 |
\DescribeUnit[picometre]{pm} \\ |
| 790 |
\DescribeUnit[nanometre]{nm} \\ |
| 791 |
\DescribeUnit[micrometre]{um} \\ |
| 792 |
\DescribeUnit[millimetre]{mm} \\ |
| 793 |
\DescribeUnit[centimetre]{cm} \\ |
| 794 |
\DescribeUnit[decimetre]{dm} \\ |
| 795 |
\DescribeUnit[metre]{m} \\ |
| 796 |
\DescribeUnit[kilometre]{km} \\ |
| 797 |
|
| 798 |
\midrule |
| 799 |
|
| 800 |
\DescribeUnit[attosecond]{as} \\ |
| 801 |
\DescribeUnit[femtosecond]{fs} \\ |
| 802 |
\DescribeUnit[picosecond]{ps} \\ |
| 803 |
\DescribeUnit[nanosecond]{ns} \\ |
| 804 |
\DescribeUnit[microsecond]{us} \\ |
| 805 |
\DescribeUnit[millisecond]{ms} \\ |
| 806 |
\DescribeUnit[second]{s} \\ |
| 807 |
|
| 808 |
\midrule |
| 809 |
|
| 810 |
\DescribeUnit[femtomole]{fmol} \\ |
| 811 |
\DescribeUnit[picomole]{pmol} \\ |
| 812 |
\DescribeUnit[nanomole]{nmol} \\ |
| 813 |
\DescribeUnit[micromole]{umol} \\ |
| 814 |
\DescribeUnit[millimole]{mmol} \\ |
| 815 |
\DescribeUnit[mole]{mol} \\ |
| 816 |
\DescribeUnit[kilomole]{kmol} \\ |
| 817 |
|
| 818 |
\midrule |
| 819 |
|
| 820 |
\DescribeUnit[picoampere]{pA} \\ |
| 821 |
\DescribeUnit[nanoampere]{nA} \\ |
| 822 |
\DescribeUnit[microampere]{uA} \\ |
| 823 |
\DescribeUnit[milliampere]{mA} \\ |
| 824 |
\DescribeUnit[ampere]{A} \\ |
| 825 |
\DescribeUnit[kiloampere]{kA} \\ |
| 826 |
|
| 827 |
\midrule |
| 828 |
|
| 829 |
\DescribeUnit[microlitre]{ul} \\ |
| 830 |
\DescribeUnit[millilitre]{ml} \\ |
| 831 |
\DescribeUnit[litre]{l} \\ |
| 832 |
\DescribeUnit[hectolitre]{hl} \\ |
| 833 |
\DescribeUnit[microliter]{uL} \\ |
| 834 |
\DescribeUnit[milliliter]{mL} \\ |
| 835 |
\DescribeUnit[liter]{L} \\ |
| 836 |
\DescribeUnit[hectoliter]{hL} \\ |
| 837 |
|
| 838 |
\midrule |
| 839 |
|
| 840 |
\DescribeUnit[millihertz]{mHz} \\ |
| 841 |
\DescribeUnit[hertz]{Hz} \\ |
| 842 |
\DescribeUnit[kilohertz]{kHz} \\ |
| 843 |
\DescribeUnit[megahertz]{MHz} \\ |
| 844 |
\DescribeUnit[gigahertz]{GHz} \\ |
| 845 |
\DescribeUnit[terahertz]{THz} \\ |
| 846 |
|
| 847 |
\midrule |
| 848 |
|
| 849 |
\DescribeUnit[millinewton]{mN} \\ |
| 850 |
\DescribeUnit[newton]{N} \\ |
| 851 |
\DescribeUnit[kilonewton]{kN} \\ |
| 852 |
\DescribeUnit[meganewton]{MN} \\ |
| 853 |
|
| 854 |
\midrule |
| 855 |
|
| 856 |
\DescribeUnit[pascal]{Pa} \\ |
| 857 |
\DescribeUnit[kilopascal]{kPa} \\ |
| 858 |
\DescribeUnit[megapacal]{MPa} \\ |
| 859 |
\DescribeUnit[gigapascal]{GPa} \\ |
| 860 |
|
| 861 |
\midrule |
| 862 |
|
| 863 |
\DescribeUnit[milliohm]{mohm} \\ |
| 864 |
\DescribeUnit[kilohm]{kohm} \\ |
| 865 |
\DescribeUnit[megohm]{Mohm} \\ |
| 866 |
|
| 867 |
\midrule |
| 868 |
|
| 869 |
\DescribeUnit[picovolt]{pV} \\ |
| 870 |
\DescribeUnit[nanovolt]{nV} \\ |
| 871 |
\DescribeUnit[microvolt]{uV} \\ |
| 872 |
\DescribeUnit[millivolt]{mV} \\ |
| 873 |
\DescribeUnit[volt]{V} \\ |
| 874 |
\DescribeUnit[kilovolt]{kV} \\ |
| 875 |
|
| 876 |
\midrule |
| 877 |
|
| 878 |
\DescribeUnit[watt]{W} \\ |
| 879 |
\DescribeUnit[nanowatt]{nW} \\ |
| 880 |
\DescribeUnit[microwatt]{uW} \\ |
| 881 |
\DescribeUnit[milliwatt]{mW} \\ |
| 882 |
\DescribeUnit[kilowatt]{kW} \\ |
| 883 |
\DescribeUnit[megawatt]{MW} \\ |
| 884 |
\DescribeUnit[gigawatt]{GW} \\ |
| 885 |
\DescribeUnit[joule]{J} \\ |
| 886 |
\DescribeUnit[microjoule]{uJ} \\ |
| 887 |
\DescribeUnit[millijoule]{mJ} \\ |
| 888 |
\DescribeUnit[kilojoule]{kJ} \\ |
| 889 |
\DescribeUnit[electronvolt]{eV} \\ |
| 890 |
\DescribeUnit[millielectronvolt]{meV} \\ |
| 891 |
\DescribeUnit[kiloelectronvolt]{keV} \\ |
| 892 |
\DescribeUnit[megaelectronvolt]{MeV} \\ |
| 893 |
\DescribeUnit[gigaelectronvolt]{GeV} \\ |
| 894 |
\DescribeUnit[teraelectronvolt]{TeV} \\ |
| 895 |
\DescribeUnit[kilowatt hour]{kWh} \\ |
| 896 |
|
| 897 |
\midrule |
| 898 |
|
| 899 |
\DescribeUnit[farad]{F} \\ |
| 900 |
\DescribeUnit[femtofarad]{fF} \\ |
| 901 |
\DescribeUnit[picofarad]{pF} \\ |
| 902 |
\DescribeUnit[nanofarad]{nF} \\ |
| 903 |
\DescribeUnit[microfarad]{uF} \\ |
| 904 |
\DescribeUnit[millifarad]{mF} \\ |
| 905 |
|
| 906 |
\midrule |
| 907 |
|
| 908 |
\DescribeUnit[henry]{H} \\ |
| 909 |
\DescribeUnit[femtohenry]{fH} \\ |
| 910 |
\DescribeUnit[picohenry]{pH} \\ |
| 911 |
\DescribeUnit[nanohenry]{nH} \\ |
| 912 |
\DescribeUnit[millihenry]{mH} \\ |
| 913 |
\DescribeUnit[microhenry]{uH} \\ |
| 914 |
|
| 915 |
\midrule |
| 916 |
|
| 917 |
\DescribeUnit[coulomb]{C} \\ |
| 918 |
\DescribeUnit[nanocoulomb]{nC} \\ |
| 919 |
\DescribeUnit[millicoulomb]{mC} \\ |
| 920 |
\DescribeUnit[microcoulomb]{uC} \\ |
| 921 |
|
| 922 |
\midrule |
| 923 |
|
| 924 |
\DescribeUnit[tesla]{T} \\ |
| 925 |
\DescribeUnit[millitesla]{mT} \\ |
| 926 |
\DescribeUnit[microtesla]{uT} \\ |
| 927 |
|
| 928 |
\midrule |
| 929 |
|
| 930 |
\DescribeUnit[kelvin]{K} \\ |
| 931 |
|
| 932 |
\midrule |
| 933 |
|
| 934 |
\DescribeUnit[decibel]{dB} \\ |
| 935 |
|
| 936 |
\end{xtabular} |
| 937 |
\end{center} |
| 938 |
|
| 939 |
\DescribeMacro{bit} |
| 940 |
\DescribeMacro{byte} |
| 941 |
Binary data is expressed in units of bits and bytes. These are normally given |
| 942 |
prefixes which use powers of two, rather than the powers of ten used by the |
| 943 |
\acro{SI} prefixes. As these binary prefixes are closely related to the |
| 944 |
\acro{SI} prefixes, they are defined by \pkg{siunitx}. |
| 945 |
\begin{table} |
| 946 |
\caption{Binary prefixes.% |
| 947 |
\label{tab:unit:binary}} |
| 948 |
\sisetup{table-number-alignment = right, table-format = 2} |
| 949 |
\begin{tabular}{@{}llcS@{}} |
| 950 |
\toprule |
| 951 |
Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\ \\ |
| 952 |
\midrule |
| 953 |
\DescribePrefix{kibi} & 10 \\ |
| 954 |
\DescribePrefix{mebi} & 20 \\ |
| 955 |
\DescribePrefix{gibi} & 30 \\ |
| 956 |
\DescribePrefix{tebi} & 40 \\ |
| 957 |
\DescribePrefix{pebi} & 50 \\ |
| 958 |
\DescribePrefix{exbi} & 60 \\ |
| 959 |
\DescribePrefix{zebi} & 70 \\ |
| 960 |
\DescribePrefix{yobi} & 80 \\ |
| 961 |
\bottomrule |
| 962 |
\end{tabular} |
| 963 |
\end{table} |
| 964 |
|
| 965 |
\subsection{Creating new macros} |
| 966 |
|
| 967 |
The various macro components of a unit have to be defined before they can be |
| 968 |
used. The package supplies a number of common definitions, but new definitions |
| 969 |
are also possible. As the definition of a logical unit should remain the same |
| 970 |
in a single document, these creation functions are all preamble-only. |
| 971 |
|
| 972 |
\begin{function}{\DeclareSIUnit} |
| 973 |
\begin{syntax} |
| 974 |
\cs{DeclareSIUnit}\oarg{options}\marg{unit}\marg{symbol} |
| 975 |
\end{syntax} |
| 976 |
\end{function} |
| 977 |
New units are produced using the \cs{DeclareSIUnit} macro. The \meta{symbol} |
| 978 |
can contain literal input, other units, multiple prefixes, powers and \cs{per}, |
| 979 |
although literal text should not be intermixed with unit macros. Units can be |
| 980 |
created with \meta{options} from the usual list understood by \pkg{siunitx}, |
| 981 |
and apply the specific unit macro only. The (first) optional argument to |
| 982 |
\cs{qty} and \cs{unit} can be used to override the settings for the unit: an |
| 983 |
example is the \cs{degree} unit. |
| 984 |
\begin{LaTeXdemo} |
| 985 |
\qty{3.1415}{\degree} |
| 986 |
\end{LaTeXdemo} |
| 987 |
This is declared in the package (effectively) as |
| 988 |
\begin{LaTeXdemo}[code only] |
| 989 |
\DeclareSIUnit[quantity-product = {}] |
| 990 |
\degree{\text{\textdegree}} |
| 991 |
\end{LaTeXdemo} |
| 992 |
The spacing can still be altered at point of use: |
| 993 |
\begin{LaTeXdemo} |
| 994 |
\qty{67890}{\degree} \\ |
| 995 |
\qty[quantity-product = \,]{67890}{\degree} |
| 996 |
\end{LaTeXdemo} |
| 997 |
The meaning of a pre-defined unit can be altered by using \cs{DeclareSIUnit} |
| 998 |
after loading \pkg{siunitx}. This will overwrite the original definition with |
| 999 |
the newer version. |
| 1000 |
|
| 1001 |
\begin{function}{\DeclareSIPrefix} |
| 1002 |
\begin{syntax} |
| 1003 |
\cs{DeclareSIPrefix}\marg{prefix}\marg{symbol}\marg{powers-ten} |
| 1004 |
\end{syntax} |
| 1005 |
\end{function} |
| 1006 |
The standard \acro{SI} powers of ten are defined by the package, and are |
| 1007 |
described above. However, the user can define new prefixes with |
| 1008 |
\cs{DeclareSIPrefix}. For example, \cs{kilo} is defined |
| 1009 |
\begin{LaTeXdemo}[code only] |
| 1010 |
\DeclareSIPrefix\kilo{k}{3} |
| 1011 |
\end{LaTeXdemo} |
| 1012 |
|
| 1013 |
\begin{function}{\DeclareSIPower} |
| 1014 |
\begin{syntax} |
| 1015 |
\cs{DeclareSIPower}\marg{symbol-before}\marg{symbol-after}\marg{power} |
| 1016 |
\end{syntax} |
| 1017 |
\end{function} |
| 1018 |
This function creates two symbols, one for use before a unit, the second |
| 1019 |
for use after a unit, both of which are equivalent to the \meta{power}. |
| 1020 |
For example, one might use |
| 1021 |
\begin{LaTeXdemo}[code only] |
| 1022 |
\DeclareSIPower\quartic\tothefourth{4} |
| 1023 |
\end{LaTeXdemo} |
| 1024 |
with the functions then used in the document as |
| 1025 |
\begin{LaTeXdemo} |
| 1026 |
\unit{\kilogram\tothefourth}\\ |
| 1027 |
\unit{\quartic\metre} |
| 1028 |
\end{LaTeXdemo} |
| 1029 |
|
| 1030 |
\begin{function}{\DeclareSIQualifier} |
| 1031 |
\begin{syntax} |
| 1032 |
\cs{DeclareSIQualifier}\marg{qualifier}\marg{symbol} |
| 1033 |
\end{syntax} |
| 1034 |
\end{function} |
| 1035 |
Following the syntax of the other macros, qualifiers may be created using the |
| 1036 |
\cs{DeclareSIQualifier} command. In contrast to the other parts of a unit, |
| 1037 |
there are no pre-defined qualifiers. It is therefore entirely up to the user to |
| 1038 |
create these. For example, to identify the mass of a product created when using |
| 1039 |
a particular catalyst, the preamble could contain: |
| 1040 |
\begin{LaTeXdemo}[code only] |
| 1041 |
\DeclareSIQualifier\polymer{pol} |
| 1042 |
\DeclareSIQualifier\catalyst{cat} |
| 1043 |
\end{LaTeXdemo} |
| 1044 |
and then in the body the document could read |
| 1045 |
\begin{LaTeXdemo} |
| 1046 |
\qty{1.234}{\gram\polymer\per\mole\catalyst\per\hour} |
| 1047 |
\end{LaTeXdemo} |
| 1048 |
|
| 1049 |
\subsection{Tabular material} |
| 1050 |
|
| 1051 |
Aligning numbers in tabular content is handled by a new column type, the |
| 1052 |
\texttt{S} column. This new column type can align material using a number of |
| 1053 |
different strategies, with the aim of flexibility of output without needing to |
| 1054 |
alter the input. The method used as standard is to place the decimal marker in |
| 1055 |
the number at the center of the cell and to align the material appropriately |
| 1056 |
(Table~\ref{tab:S:standard}). |
| 1057 |
\begin{LaTeXdemo}[code and float] |
| 1058 |
\begin{table} |
| 1059 |
\caption{Standard behavior of the \texttt{S} column type.% |
| 1060 |
\label{tab:S:standard}} |
| 1061 |
\begin{tabular}{@{}S@{}} |
| 1062 |
\toprule |
| 1063 |
{Some Values} \\ |
| 1064 |
\midrule |
| 1065 |
2.3456 \\ |
| 1066 |
34.2345 \\ |
| 1067 |
-6.7835 \\ |
| 1068 |
90.473 \\ |
| 1069 |
5642.5 \\ |
| 1070 |
1.2e3 \\ |
| 1071 |
e4 \\ |
| 1072 |
\bottomrule |
| 1073 |
\end{tabular} |
| 1074 |
\end{table} |
| 1075 |
\end{LaTeXdemo} |
| 1076 |
|
| 1077 |
The \texttt{S} column will attempt to automatically detect material which |
| 1078 |
should be placed before or after a number, and will maintain the alignment of |
| 1079 |
the numerical data (Table~\ref{tab:S:extras}). If the material could be |
| 1080 |
mistaken for part of a number, it should be protected by braces. The use of |
| 1081 |
\cs{color} in a table cell will also be detected and will override any general |
| 1082 |
color applied by \pkg{siunitx}. |
| 1083 |
\begin{LaTeXdemo}[code and float] |
| 1084 |
\begin{table} |
| 1085 |
\caption{Detection of surrounding material in an \texttt{S} column.% |
| 1086 |
\label{tab:S:extras}} |
| 1087 |
\begin{tabular}{@{}S@{}} |
| 1088 |
\toprule |
| 1089 |
{Some Values} \\ |
| 1090 |
\midrule |
| 1091 |
12.34 \\ |
| 1092 |
\color{purple} 975,31 \\ |
| 1093 |
44.268 \textsuperscript{\emph{a}} \\ |
| 1094 |
\bottomrule |
| 1095 |
\end{tabular} |
| 1096 |
\end{table} |
| 1097 |
\end{LaTeXdemo} |
| 1098 |
|
| 1099 |
\begin{function}{\tablenum} |
| 1100 |
\begin{syntax} |
| 1101 |
\cs{tablenum}\oarg{options}\marg{number} |
| 1102 |
\end{syntax} |
| 1103 |
\end{function} |
| 1104 |
Within more complex tables, aligned numbers may be desirable within the |
| 1105 |
argument of \cs{multicolumn} or \cs{multirow}.\footnote{Provided by the |
| 1106 |
\pkg{multirow} package} The \cs{tablenum} function is available to achieve |
| 1107 |
alignment in these situations: this is, in effect, a macro version of the |
| 1108 |
\texttt{S} column (Table~\ref{tab:tablenum}). |
| 1109 |
\begin{LaTeXdemo}[code and float] |
| 1110 |
\begin{table} |
| 1111 |
\caption{Controlling complex alignment with the \cs{tablenum} macro.% |
| 1112 |
\label{tab:tablenum}} |
| 1113 |
\begin{tabular}{@{}lr@{}} |
| 1114 |
\toprule |
| 1115 |
Heading & Heading \\ |
| 1116 |
\midrule |
| 1117 |
Info & More info \\ |
| 1118 |
Info & More info \\ |
| 1119 |
\multicolumn{2}{c}{\tablenum[table-format = 4.4]{12,34}} \\ |
| 1120 |
\multicolumn{2}{c}{\tablenum[table-format = 4.4]{333.5567}} \\ |
| 1121 |
\multicolumn{2}{c}{\tablenum[table-format = 4.4]{4563.21}} \\ |
| 1122 |
\bottomrule |
| 1123 |
\end{tabular} |
| 1124 |
\hspace{\fill}% |
| 1125 |
\begin{tabular}{@{}lr@{}} |
| 1126 |
\toprule |
| 1127 |
Heading & Heading \\ |
| 1128 |
\midrule |
| 1129 |
\multirow{2}*{\tablenum{88,999}} & aaa \\ |
| 1130 |
& bbb \\ |
| 1131 |
\multirow{2}*{\tablenum{33,435}} & ccc \\ |
| 1132 |
& ddd \\ |
| 1133 |
\bottomrule |
| 1134 |
\end{tabular} |
| 1135 |
\end{table} |
| 1136 |
\end{LaTeXdemo} |
| 1137 |
|
| 1138 |
\section{Package control options} |
| 1139 |
|
| 1140 |
\subsection{The key--value control system} |
| 1141 |
|
| 1142 |
The package uses a range of different key types: |
| 1143 |
\begin{description} |
| 1144 |
\item[\texttt{Choice}] Takes a limited number of choices, which are described |
| 1145 |
separately for each key. |
| 1146 |
\item[\texttt{Integer}] Requires a number as the argument. |
| 1147 |
\item[\texttt{Length}] Requires a length, either as a literal |
| 1148 |
value such as \texttt{2.0cm}, or stored as a \LaTeX{} length. |
| 1149 |
\item[\texttt{Literal}] A key which uses the value(s) given directly, |
| 1150 |
either to check input or in output. |
| 1151 |
\item[\texttt{Macro}] Requires a macro, which may need a single argument. |
| 1152 |
\item[\texttt{Math}] Similar to a \texttt{literal} option, but the input is |
| 1153 |
always used in math mode, irrespective of other \pkg{siunitx} settings. |
| 1154 |
Thus to text-mode only input must be placed inside the argument of a |
| 1155 |
\cs{text} macro. |
| 1156 |
\item[\texttt{Meta}] These are options which actually apply a number of |
| 1157 |
other options. |
| 1158 |
\item[\texttt{Switch}] These are on--off switches, and recognise \opt{true} |
| 1159 |
and \opt{false}. Giving just the key name also turns the key on. |
| 1160 |
\end{description} |
| 1161 |
The tables of option names use these descriptions to indicate how the keys |
| 1162 |
should be used. |
| 1163 |
|
| 1164 |
\subsection{Printing% |
| 1165 |
\label{sec:print}} |
| 1166 |
|
| 1167 |
The \pkg{siunitx} package can control the font used to print output |
| 1168 |
independently of the surrounding material. Which aspects of the font follow |
| 1169 |
those of the surroundings is influenced by a range of setting as detailed in |
| 1170 |
Table~\ref{tab:opt:print}. |
| 1171 |
\begin{table} |
| 1172 |
\caption{Print options.% |
| 1173 |
\label{tab:opt:print}} |
| 1174 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 1175 |
\toprule |
| 1176 |
\multicolumn{1}{@{}l}{Option name} & |
| 1177 |
Type & |
| 1178 |
\multicolumn{1}{l@{}}{Default} \\ |
| 1179 |
\midrule |
| 1180 |
color & Literal & \meta{none} \\ |
| 1181 |
mode & Choice & math \\ |
| 1182 |
number-color & Literal & \meta{none} \\ |
| 1183 |
number-mode & Choice & math \\ |
| 1184 |
propagate-math-font & Switch & false \\ |
| 1185 |
reset-math-version & Switch & true \\ |
| 1186 |
reset-text-family & Switch & true \\ |
| 1187 |
reset-text-series & Switch & true \\ |
| 1188 |
reset-text-shape & Switch & true \\ |
| 1189 |
text-family-to-math & Switch & false \\ |
| 1190 |
text-font-command & Literal & \meta{none} \\ |
| 1191 |
text-subscript-command & Literal & \cs{textsubscript} \\ |
| 1192 |
text-superscript-command & Literal & \cs{textsuperscript} \\ |
| 1193 |
text-series-to-math & Switch & false \\ |
| 1194 |
unit-color & Literal & \meta{none} \\ |
| 1195 |
unit-mode & Choice & math \\ |
| 1196 |
\bottomrule |
| 1197 |
\end{tabular} |
| 1198 |
\end{table} |
| 1199 |
|
| 1200 |
\DescribeOption{mode} |
| 1201 |
\DescribeOption{number-mode} |
| 1202 |
\DescribeOption{unit-mode} |
| 1203 |
The \opt{mode} option determines whether \pkg{siunitx} uses math or text mode |
| 1204 |
when printing output. The choices are \opt{match}, \opt{math}, \opt{text}. The |
| 1205 |
\opt{match} setting means that printing uses the prevailing mode unchanged |
| 1206 |
whereas \opt{math} and \opt{text} select the appropriate \TeX{} mode. It is |
| 1207 |
possible to have different fonts in math and text modes, which will highlight |
| 1208 |
the difference. The font settings which apply are also different depending on |
| 1209 |
the mode. As well as the overall setting, it is possible to apply mode |
| 1210 |
to numbers and units separately using the \opt{number-mode} and \opt{unit-mode} |
| 1211 |
options. |
| 1212 |
|
| 1213 |
\DescribeOption{reset-text-family} |
| 1214 |
\DescribeOption{reset-text-series} |
| 1215 |
\DescribeOption{reset-text-shape} |
| 1216 |
When printing in text mode, the options \opt{reset-text-family}, |
| 1217 |
\opt{reset-text-series} and \opt{reset-text-shape} apply. When these are |
| 1218 |
active, \pkg{siunitx} resets the relevant font selection axis property |
| 1219 |
when printing: the standard font setting is upright mid-weight roman |
| 1220 |
(|\upshape| |\mdseries| |\rmfamily|). |
| 1221 |
\begin{LaTeXdemo} |
| 1222 |
\sisetup{mode = text} |
| 1223 |
{\itshape \num{1234}}\\ |
| 1224 |
{\bfseries \num{1234}}\\ |
| 1225 |
{\sffamily \num{1234}}\\ |
| 1226 |
\sisetup{ |
| 1227 |
reset-text-family = false , |
| 1228 |
reset-text-series = false , |
| 1229 |
reset-text-shape = false |
| 1230 |
} |
| 1231 |
{\itshape \num{1234}}\\ |
| 1232 |
{\bfseries \num{1234}}\\ |
| 1233 |
{\sffamily \num{1234}}\\ |
| 1234 |
\end{LaTeXdemo} |
| 1235 |
|
| 1236 |
\DescribeOption{propagate-math-font} |
| 1237 |
\DescribeOption{reset-math-version} |
| 1238 |
In math mode, the font used by \LaTeX{} is \enquote{invariant}, and this is |
| 1239 |
reflected in the options available. With the standard settings, in math mode |
| 1240 |
printing uses the standard math font and version (weight). The option |
| 1241 |
\opt{propagate-math-font} may be used to apply the prevailing math font |
| 1242 |
to the printed material. The setting \opt{reset-math-version} controls |
| 1243 |
whether the math version is reset or not. Note that math version is typically |
| 1244 |
used to set \enquote{bold math} but may also be used for other effects, for |
| 1245 |
example all sanserif math. |
| 1246 |
\begin{LaTeXdemo} |
| 1247 |
{\boldmath \unit{\kilogram}}\\ |
| 1248 |
{\sansmath $\unit{\kilogram}$}\\ |
| 1249 |
{$\mathsf{\unit{\kilogram}}$}\\ |
| 1250 |
\sisetup{ |
| 1251 |
propagate-math-font = true , |
| 1252 |
reset-math-version = false |
| 1253 |
} |
| 1254 |
{\boldmath \unit{\kilogram}}\\ |
| 1255 |
{\sansmath $\unit{\kilogram}$}\\ |
| 1256 |
{$\mathsf{\unit{\kilogram}}$} |
| 1257 |
\end{LaTeXdemo} |
| 1258 |
|
| 1259 |
\DescribeOption{text-family-to-math} |
| 1260 |
\DescribeOption{text-series-to-math} |
| 1261 |
The options \opt{text-family-to-math} and \opt{text-series-to-math} can be |
| 1262 |
used to match (as far as possible) math mode output to the surrounding text. |
| 1263 |
These options work by detecting the current text settings and making the |
| 1264 |
appropriate choice in math mode. |
| 1265 |
\begin{LaTeXdemo} |
| 1266 |
{\sffamily \unit{\kilogram}}\\ |
| 1267 |
{\bfseries $\unit{\kilogram}$}\\ |
| 1268 |
\sisetup{ |
| 1269 |
text-family-to-math = true , |
| 1270 |
text-series-to-math = true |
| 1271 |
} |
| 1272 |
{\sffamily \unit{\kilogram}}\\ |
| 1273 |
{\bfseries $\unit{\kilogram}$} |
| 1274 |
\end{LaTeXdemo} |
| 1275 |
|
| 1276 |
\DescribeOption{text-font-command} |
| 1277 |
In some circumstances, it may be desirable to use a non-standard font command |
| 1278 |
when printing in text mode. This might be used for example to switch from |
| 1279 |
old-style to lining numbers whilst still using text mode. This may be achieved |
| 1280 |
by setting \opt{text-font-command}. For example, this document uses old-style |
| 1281 |
numbers in text mode as-standard, which can be over-ridden by selecting the |
| 1282 |
font variant which does not feature them. |
| 1283 |
\begin{LaTeXdemo} |
| 1284 |
\sisetup{number-mode = text} |
| 1285 |
\qty{123456789}{\kilo\volt\per\centi\metre} \\ |
| 1286 |
\sisetup{text-font-command = \fontfamily{pplx}\selectfont} |
| 1287 |
\qty{123456789}{\kilo\volt\per\centi\metre} |
| 1288 |
\end{LaTeXdemo} |
| 1289 |
|
| 1290 |
\DescribeOption{text-subscript-command} |
| 1291 |
\DescribeOption{text-superscript-command} |
| 1292 |
In most cases, the commands \cs{textsubscript} and \cs{textsuperscript} are |
| 1293 |
appropriate for creating sub- and superscript material in text mode. However, |
| 1294 |
when the \pkg{realscripts} package is loaded, it is possible that the output is |
| 1295 |
not as desired. These two commands are therefore available to allow tuning of |
| 1296 |
the results. They can also be used for non-standard effects, for example as |
| 1297 |
here adding color to subscripts. |
| 1298 |
\begin{LaTeXdemo} |
| 1299 |
\sisetup{unit-mode = text} |
| 1300 |
\unit{\kg\of{polymer}} \\ |
| 1301 |
\newcommand*\mysubscript[1]{% |
| 1302 |
\textsubscript{\textcolor{blue}{#1}}% |
| 1303 |
} |
| 1304 |
\sisetup{text-subscript-command = \mysubscript} |
| 1305 |
\unit{\kg\of{polymer}} |
| 1306 |
\end{LaTeXdemo} |
| 1307 |
|
| 1308 |
\DescribeOption{color} |
| 1309 |
\DescribeOption{number-color} |
| 1310 |
\DescribeOption{unit-color} |
| 1311 |
The color of printed output can be set using the \opt{color} option. When no |
| 1312 |
color is given, printing follows the surrounding text. In contrast, when a |
| 1313 |
specific color is given, it is used irrespective of the surroundings. As with |
| 1314 |
\opt{mode}, the \opt{color} setting may also be applied to numbers and units |
| 1315 |
independently. |
| 1316 |
\begin{LaTeXdemo} |
| 1317 |
\color{red}% |
| 1318 |
Some text \\ |
| 1319 |
\qty{4}{\kilogram} \\ |
| 1320 |
More text \\ |
| 1321 |
\qty[color = blue]{4}{\kilogram} \\ |
| 1322 |
Still red here! |
| 1323 |
\end{LaTeXdemo} |
| 1324 |
Note that the color does \emph{not} apply to text inserted by the package |
| 1325 |
between numbers, units or quantities. For example, in |
| 1326 |
\begin{LaTeXdemo} |
| 1327 |
\numproduct[color = blue, product-mode = phrase]{1x2} |
| 1328 |
\end{LaTeXdemo} |
| 1329 |
only the numerals are colored; coloring all output should be done using the |
| 1330 |
standard \LaTeX{} interfaces. |
| 1331 |
|
| 1332 |
\subsection{Parsing numbers} |
| 1333 |
|
| 1334 |
The package uses a sophisticated parsing system to understand numbers. This |
| 1335 |
allows \pkg{siunitx} to carry out a range of formatting, as described later. |
| 1336 |
All of the input options take lists of literal tokens, and are summarised in |
| 1337 |
Table~\ref{tab:opt:num:in}. |
| 1338 |
\begin{table} |
| 1339 |
\caption{Options for number parsing.% |
| 1340 |
\label{tab:opt:num:in}} |
| 1341 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 1342 |
\toprule |
| 1343 |
\multicolumn{1}{@{}l}{Option name} & |
| 1344 |
Type & |
| 1345 |
\multicolumn{1}{l@{}}{Default} \\ |
| 1346 |
\midrule |
| 1347 |
evaluate-expression & Switch & false \\ |
| 1348 |
expression & Literal & |#1| \\^^A ( |
| 1349 |
input-close-uncertainty & Literal & ) \\ |
| 1350 |
input-comparators & Literal & |
| 1351 |
<=>\cs{approx}\cs{ge}\cs{geq} \\ |
| 1352 |
& & \cs{gg}\cs{le}\cs{leq}\cs{ll}\cs{sim} \\ |
| 1353 |
input-decimal-markers & Literal & ., \\ |
| 1354 |
input-digits & Literal & 0123456789 \\ |
| 1355 |
input-exponent-markers & Literal & dDeE \\ |
| 1356 |
input-ignore & Literal & \meta{none} \\ |
| 1357 |
input-open-uncertainty & Literal & ( \\ ^^A ) |
| 1358 |
input-signs & Literal & +-\cs{pm}\cs{mp} \\ |
| 1359 |
input-uncertainty-divider & Literal & : \\ |
| 1360 |
input-uncertainty-signs & Literal & \cs{pm} \\ |
| 1361 |
parse-numbers & Switch & true \\ |
| 1362 |
retain-explicit-decimal-marker & Switch & false \\ |
| 1363 |
retain-explicit-plus & Switch & false \\ |
| 1364 |
retain-negative-zero & Switch & false \\ |
| 1365 |
retain-zero-uncertainty & Switch & false \\ |
| 1366 |
\bottomrule |
| 1367 |
\end{tabular} |
| 1368 |
\end{table} |
| 1369 |
|
| 1370 |
\DescribeOption{input-digits} |
| 1371 |
\DescribeOption{input-decimal-markers} |
| 1372 |
\DescribeOption{input-signs} |
| 1373 |
\DescribeOption{input-exponent-markers} |
| 1374 |
The basic parts of a number are the digits, any sign and a separator between |
| 1375 |
the integer and decimal parts. These are stored in the input options |
| 1376 |
\opt{input-digits}, \opt{input-decimal-markers} and \opt{input-signs}, |
| 1377 |
respectively. More than one input decimal marker can be used: it will be |
| 1378 |
converted by the package to the appropriate output marker. Numbers which |
| 1379 |
include an exponent part also require a marker for the exponent: this again is |
| 1380 |
taken from the range of tokens in the \opt{input-exponent-markers} option. |
| 1381 |
|
| 1382 |
\DescribeOption{input-ignore} |
| 1383 |
Tokens given in the \opt{input-ignore} list are totally passed over by |
| 1384 |
\pkg{siunitx}: they will be removed from the input with no further processing. |
| 1385 |
|
| 1386 |
\DescribeOption{input-comparators} |
| 1387 |
In addition to signs, \pkg{siunitx} can recognise comparators, such as |<|. The |
| 1388 |
package will automatically carry out conversions for |<<|, |>>|, |<=|, |>=| and |
| 1389 |
|~| to |\ll|, |\gg|, |\le|, |\ge| and |\sim|, respectively. |
| 1390 |
\begin{LaTeXdemo} |
| 1391 |
\num{< 10} \\ |
| 1392 |
\qty{>> 5}{\metre} \\ |
| 1393 |
\num{\le 0.12} |
| 1394 |
\end{LaTeXdemo} |
| 1395 |
|
| 1396 |
\DescribeOption{input-open-uncertainty} |
| 1397 |
\DescribeOption{input-close-uncertainty} |
| 1398 |
\DescribeOption{input-uncertainty-signs} |
| 1399 |
In some fields, it is common to give the uncertainty in a number in brackets |
| 1400 |
after the main part of the number, for example \enquote{\num{1.234(5)}}. The |
| 1401 |
opening and closing symbols used for this type of input are set as |
| 1402 |
\opt{input-open-uncertainty} and \opt{input-close-uncertainty}. Alternatively, |
| 1403 |
the uncertainty may be given as a separate part following a sign. Which signs |
| 1404 |
are valid for this operation is determined by the \opt{input-uncertainty-signs} |
| 1405 |
option. As with other signs, the combination |+-| will automatically be |
| 1406 |
converted to |\pm| internally. |
| 1407 |
\begin{LaTeXdemo} |
| 1408 |
\num{9.99(9)} \\ |
| 1409 |
\num{9.99 +- 0.09} \\ |
| 1410 |
\num{9.99 \pm 0.09} \\ |
| 1411 |
\num{123 +- 4.5} \\ |
| 1412 |
\num{12.3 +- 6} |
| 1413 |
\end{LaTeXdemo} |
| 1414 |
|
| 1415 |
Uncertainties which cross the decimal marker may be given with or without a |
| 1416 |
decimal marker in \enquote{compact} form. These are treated as equivalent by |
| 1417 |
the code.\footnote{The package author favors the form without a decimal marker, |
| 1418 |
and formal guidance is ambiguous on which is correct. The form with a decimal |
| 1419 |
marker is seen in for example some \acro{NIST} publications.} Where multiple |
| 1420 |
uncertainty values cross the decimal marker, they should all have the same |
| 1421 |
number of digits. |
| 1422 |
\begin{LaTeXdemo} |
| 1423 |
\num{123.4(12)} \\ |
| 1424 |
\num{123.4(1.2)} |
| 1425 |
\end{LaTeXdemo} |
| 1426 |
Multiple symmetrical uncertainties may also be given: these must all either be |
| 1427 |
in the short or the long form. |
| 1428 |
\begin{LaTeXdemo} |
| 1429 |
\num{123.4(12)(45)} \\ |
| 1430 |
\num{123.4 \pm 1.2 \pm 4.5} |
| 1431 |
\end{LaTeXdemo} |
| 1432 |
|
| 1433 |
\DescribeOption{input-uncertainty-divider} |
| 1434 |
In some areas, uncertainties (or tolerances) are given in an asymmetric format. |
| 1435 |
This is supported in the \enquote{compact} input form in \pkg{siunitx}, with |
| 1436 |
the positive and negative parts of the uncertainty divided by a symbol listed |
| 1437 |
in \opt{input-uncertainty-divider}. When given in this divided form, the |
| 1438 |
two parts are interpreted as first the positive and then the negative |
| 1439 |
component. Asymmetric uncertainties which cross the decimal marker are |
| 1440 |
supported provided both components have the same number of digits. |
| 1441 |
\begin{LaTeXdemo} |
| 1442 |
\num{10.56(12:34)} \\ |
| 1443 |
\num{123.4(4.6:7.8)} |
| 1444 |
\end{LaTeXdemo} |
| 1445 |
Symmetrical and asymmetrical uncertainties may be intermixed. |
| 1446 |
\begin{LaTeXdemo} |
| 1447 |
\num{10.56(1:2)(3)} \\ |
| 1448 |
\num{6.45(2)(3:4)} |
| 1449 |
\end{LaTeXdemo} |
| 1450 |
|
| 1451 |
\DescribeOption{parse-numbers} |
| 1452 |
The \opt{parse-numbers} option turns the entire parsing system on and off. The |
| 1453 |
option is made available for two reasons. First, if all of the numbers in a |
| 1454 |
document are to be reproduced \enquote{as given}, turning off the parser will |
| 1455 |
represent a significant saving in processing required. Second, it allows the |
| 1456 |
use of arbitrary \TeX{} code in numbers. If the parser is turned off, the input |
| 1457 |
will be printed in math mode (requiring |\text| to protect any text in the |
| 1458 |
number). |
| 1459 |
\begin{LaTeXdemo} |
| 1460 |
\num[parse-numbers = false]{\sqrt{2}} \\ |
| 1461 |
\qty[parse-numbers = false]{\sqrt{3}}{\metre} |
| 1462 |
\end{LaTeXdemo} |
| 1463 |
|
| 1464 |
\DescribeOption{evaluate-expression} |
| 1465 |
\DescribeOption{expression} |
| 1466 |
With the standard settings, numerical input is parsed \enquote{as is} with no |
| 1467 |
attempt to interpret it mathematically. By enabling the |
| 1468 |
\opt{evaluate-expression} option, the input can be processed by the standard |
| 1469 |
\LaTeX3 \acro{FPU} (see package \pkg{xfp} for more). The nature of the |
| 1470 |
expression itself can be adjusted using the \opt{expression} setting: as |
| 1471 |
standard, the entire input is simply parsed with no change, but this setting |
| 1472 |
may be used to add additional steps. The \emph{input} in such an expression is |
| 1473 |
represented by |#1|. Note that the \acro{FPU} uses its own syntax for numbers, |
| 1474 |
most notably in that a decimal marker must be |.|. |
| 1475 |
\begin{LaTeXdemo} |
| 1476 |
\sisetup{evaluate-expression}% |
| 1477 |
\qty{2 + 4 * 3}{\joule} \\ |
| 1478 |
\qty[expression = 10 * (#1)]{2 + 4 * 3}{\joule} |
| 1479 |
\end{LaTeXdemo} |
| 1480 |
|
| 1481 |
\DescribeOption{retain-explicit-decimal-marker} |
| 1482 |
\DescribeOption{retain-explicit-plus} |
| 1483 |
\DescribeOption{retain-negative-zero} |
| 1484 |
\DescribeOption{retain-zero-uncertainty} |
| 1485 |
In some areas, a trailing decimal marker with no decimal part present is used |
| 1486 |
to show that zeros in the integer part are significant. This can be enabled |
| 1487 |
using the \opt{retain-explicit-decimal-marker} option. The inclusion of a |
| 1488 |
leading plus sign is usually unnecessary for positive numbers, and so they are |
| 1489 |
not retained as-standard when parsing. The \opt{retain-explicit-plus} option is |
| 1490 |
available to control this behavior. Similarly, an uncertainty of zero is |
| 1491 |
normally not meaningful, and so is ignored by the parser. This can be |
| 1492 |
controlled using the \opt{retain-zero-uncertainty} option. Finally, a negative |
| 1493 |
sign for an entirely zero value may or may not have significance: this is |
| 1494 |
controlled by the \opt{retain-negative-zero} option. |
| 1495 |
\begin{LaTeXdemo} |
| 1496 |
\num{10.} \\ |
| 1497 |
\num[retain-explicit-decimal-marker]{10.} \\ |
| 1498 |
\num{+345} \\ |
| 1499 |
\num[retain-explicit-plus]{+345} \\ |
| 1500 |
\num{-0} \\ |
| 1501 |
\num[retain-negative-zero]{-0} \\ |
| 1502 |
\num{12.3(0)} \\ |
| 1503 |
\num[retain-zero-uncertainty]{12.3(0)} |
| 1504 |
\end{LaTeXdemo} |
| 1505 |
|
| 1506 |
\subsection{Post-processing numbers} |
| 1507 |
|
| 1508 |
Before typesetting numbers, various post-processing steps can be carried out. |
| 1509 |
These involve adding or removing information from the number in a systematic |
| 1510 |
way; the options are summarised in Table~\ref{tab:opt:num:post}. |
| 1511 |
\begin{table} |
| 1512 |
\caption{Number post-processing options.% |
| 1513 |
\label{tab:opt:num:post}} |
| 1514 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 1515 |
\toprule |
| 1516 |
\multicolumn{1}{@{}l}{Option name} & |
| 1517 |
Type & |
| 1518 |
\multicolumn{1}{l@{}}{Default} \\ |
| 1519 |
\midrule |
| 1520 |
drop-exponent & Switch & false \\ |
| 1521 |
drop-uncertainty & Switch & false \\ |
| 1522 |
drop-zero-decimal & Switch & false \\ |
| 1523 |
exponent-mode & Switch & input \\ |
| 1524 |
exponent-thresholds & Literal & -3:3 \\ |
| 1525 |
fixed-exponent & Integer & 0 \\ |
| 1526 |
minimum-integer-digits & Integer & 0 \\ |
| 1527 |
minimum-decimal-digits & Integer & 0 \\ |
| 1528 |
round-direction & Choice & nearest \\ |
| 1529 |
round-half & Choice & up \\ |
| 1530 |
round-minimum & Literal & 0 \\ |
| 1531 |
round-mode & Choice & none \\ |
| 1532 |
round-pad & Switch & true \\ |
| 1533 |
round-precision & Integer & 2 \\ |
| 1534 |
round-zero-positive & Switch & true \\ |
| 1535 |
uncertainty-round-direction & Choice & nearest \\ |
| 1536 |
\bottomrule |
| 1537 |
\end{tabular} |
| 1538 |
\end{table} |
| 1539 |
|
| 1540 |
\DescribeOption{exponent-mode} |
| 1541 |
\DescribeOption{fixed-exponent} |
| 1542 |
Numbers can be converted to scientific notation by the package. This is |
| 1543 |
controlled by the \opt{exponent-mode} option, which takes choices \opt{input}, |
| 1544 |
\opt{fixed}, \opt{engineering}, \opt{scientific} and \opt{threshold}. The |
| 1545 |
\opt{fixed} setting will use the exponent value by the \opt{fixed-exponent} |
| 1546 |
option. When \opt{engineering} is set, the exponent is always a power of three. |
| 1547 |
\begin{LaTeXdemo} |
| 1548 |
\num{0.001} \\ |
| 1549 |
\num{0.0100} \\ |
| 1550 |
\num{1200} \\ |
| 1551 |
\sisetup{exponent-mode = scientific}% |
| 1552 |
\num{0.001} \\ |
| 1553 |
\num{0.0100} \\ |
| 1554 |
\num{1200} \\ |
| 1555 |
\sisetup{exponent-mode = engineering}% |
| 1556 |
\num{0.001} \\ |
| 1557 |
\num{0.0100} \\ |
| 1558 |
\num{1200} \\ |
| 1559 |
\sisetup{ |
| 1560 |
exponent-mode = fixed, |
| 1561 |
fixed-exponent = 2, |
| 1562 |
}% |
| 1563 |
\num{0.001} \\ |
| 1564 |
\num{0.0100} \\ |
| 1565 |
\num{1200} |
| 1566 |
\end{LaTeXdemo} |
| 1567 |
When used with a \opt{fixed-exponent} of zero, this may be used to remove |
| 1568 |
scientific notation from the input |
| 1569 |
\begin{LaTeXdemo} |
| 1570 |
\num{1.23e4} \\ |
| 1571 |
\num[exponent-mode = fixed, fixed-exponent = 0]{1.23e4} |
| 1572 |
\end{LaTeXdemo} |
| 1573 |
\DescribeOption{exponent-thresholds} |
| 1574 |
When the \opt{exponent-mode} is set to \opt{threshold}, values outside of a |
| 1575 |
threshold range for the exponent are always printed in scientific form. The |
| 1576 |
threshold range itself is controlled by \opt{exponent-thresholds}, which is |
| 1577 |
given as \texttt{\meta{min}:\meta{max}} (Table~\ref{tab:threshold}). |
| 1578 |
\begin{LaTeXdemo}[code and float] |
| 1579 |
\begin{table} |
| 1580 |
\caption{Thresholds for exponents.% |
| 1581 |
\label{tab:threshold}} |
| 1582 |
\begin{tabular} |
| 1583 |
{ |
| 1584 |
@{} |
| 1585 |
S |
| 1586 |
S[exponent-mode = threshold] |
| 1587 |
S[exponent-mode = threshold, exponent-thresholds = -2:2] |
| 1588 |
@{} |
| 1589 |
} |
| 1590 |
\toprule |
| 1591 |
{Input} & {Threshold $-3:3$} & {Threshold $-2:2$} \\ |
| 1592 |
\midrule |
| 1593 |
0.001 & 0.001 & 0.001 \\ |
| 1594 |
0.012 & 0.012 & 0.012 \\ |
| 1595 |
0.123 & 0.123 & 0.123 \\ |
| 1596 |
1 & 1 & 1 \\ |
| 1597 |
12 & 12 & 12 \\ |
| 1598 |
123 & 123 & 123 \\ |
| 1599 |
1234 & 1234 & 1234 \\ |
| 1600 |
\bottomrule |
| 1601 |
\end{tabular} |
| 1602 |
\end{table} |
| 1603 |
\end{LaTeXdemo} |
| 1604 |
|
| 1605 |
Exponent mode applies \emph{after} rounding, such that the number of decimal |
| 1606 |
places for rounding is those which appear in the output. |
| 1607 |
|
| 1608 |
\DescribeOption{drop-exponent} |
| 1609 |
\DescribeOption{drop-uncertainty} |
| 1610 |
The use of an uncertainty can be suppressed entirely using the |
| 1611 |
\opt{drop-uncertainty} option: this applies \emph{before} rounding is |
| 1612 |
attempted. Similarly, exponents can be dropped using \opt{drop-exponent} can be |
| 1613 |
used to suppress the exponent part (\emph{after} conversion to a fixed |
| 1614 |
exponent). |
| 1615 |
\begin{LaTeXdemo} |
| 1616 |
\num{0.01(2)} \\ |
| 1617 |
\num[drop-uncertainty]{0.01(2)} \\ |
| 1618 |
\num{0.01e3} \\ |
| 1619 |
\num[drop-exponent]{0.01e3} |
| 1620 |
\end{LaTeXdemo} |
| 1621 |
|
| 1622 |
\DescribeOption{round-mode} |
| 1623 |
\DescribeOption{round-precision} |
| 1624 |
\DescribeOption{round-pad} |
| 1625 |
The package can round numerical input to a fixed number of significant figures |
| 1626 |
or decimal places. This is controlled by the \opt{round-mode} option, which |
| 1627 |
takes the choices \opt{none}, \opt{figures}, \opt{places} and |
| 1628 |
\opt{uncertainty}. When rounding is turned on, the number of digits used |
| 1629 |
(either decimal places or significant figures in the mantissa) is set using the |
| 1630 |
\opt{round-precision} option. Rounding numbers with uncertainties may be |
| 1631 |
carried out using the \opt{uncertainty} setting to \opt{round-mode}. In this |
| 1632 |
case the precision is used first to round the uncertainty itself (to a number |
| 1633 |
of figures), before rounding the main value to follow. |
| 1634 |
\begin{LaTeXdemo} |
| 1635 |
\num{1.23456} \\ |
| 1636 |
\num{14.23} \\ |
| 1637 |
\num{0.12345(9)} \\ |
| 1638 |
\sisetup{ |
| 1639 |
round-mode = places, |
| 1640 |
round-precision = 3 |
| 1641 |
}% |
| 1642 |
\num{1.23456} \\ |
| 1643 |
\num{14.23} \\ |
| 1644 |
\num{0.12345(9)} \\ |
| 1645 |
\sisetup{ |
| 1646 |
round-mode = figures, |
| 1647 |
round-precision = 3 |
| 1648 |
}% |
| 1649 |
\num{1.23456} \\ |
| 1650 |
\num{14.23} \\ |
| 1651 |
\num{0.12345(9)} \\ |
| 1652 |
\sisetup{ |
| 1653 |
round-mode = uncertainty, |
| 1654 |
round-precision = 1 |
| 1655 |
}% |
| 1656 |
\num{0.12345(9)} \\ |
| 1657 |
\num{0.12345(23)} \\ |
| 1658 |
\num{0.12345(234)} |
| 1659 |
\end{LaTeXdemo} |
| 1660 |
Rounding may \enquote{extend} a short number to more digits (or figures): this |
| 1661 |
is controlled by the switch \opt{round-pad}, which is \opt{true} as standard. |
| 1662 |
\begin{LaTeXdemo} |
| 1663 |
\sisetup{round-mode = figures, round-precision = 4}% |
| 1664 |
\num{12.3} \\ |
| 1665 |
\num[round-pad = false]{12.3} |
| 1666 |
\end{LaTeXdemo} |
| 1667 |
|
| 1668 |
\DescribeOption{round-direction} |
| 1669 |
\DescribeOption{round-half} |
| 1670 |
The detail of which approach to use for rounding may be adjusted using the |
| 1671 |
options \opt{round-direction} and \opt{round-half}. The option |
| 1672 |
\opt{round-direction} determines which direction a value is rounded toward: a |
| 1673 |
choice of \opt{nearest}, \opt{up} or \opt{down}. The standard setting, |
| 1674 |
\opt{nearest}, gives the common outcome that values round depending on whether |
| 1675 |
the preceding digit is greater or less than \num{5}. The options \opt{up} and |
| 1676 |
\opt{down} mean that values are always rounded in one direction: the \opt{down} |
| 1677 |
option may be thought of as \enquote{truncation}. |
| 1678 |
\begin{LaTeXdemo} |
| 1679 |
\sisetup{round-mode = places} |
| 1680 |
\num{0.054} \\ |
| 1681 |
\num{0.046} \\ |
| 1682 |
\sisetup{round-direction = down}% |
| 1683 |
\num{0.054} \\ |
| 1684 |
\num{0.046} \\ |
| 1685 |
\sisetup{round-direction = up}% |
| 1686 |
\num{0.054} \\ |
| 1687 |
\num{0.046} |
| 1688 |
\end{LaTeXdemo} |
| 1689 |
For rounding to \opt{nearest}, where the rounded part of a number is exactly |
| 1690 |
half, there are two common methods for \enquote{breaking the tie}. The choice |
| 1691 |
of method is determined by the option \opt{round-half}, which recognises the |
| 1692 |
choices \opt{up} and \opt{even}. |
| 1693 |
\begin{LaTeXdemo} |
| 1694 |
\sisetup{ |
| 1695 |
round-mode = figures, |
| 1696 |
round-precision = 1, |
| 1697 |
round-half = up |
| 1698 |
}% |
| 1699 |
\num{0.055} \\ |
| 1700 |
\num{0.045} \\ |
| 1701 |
\sisetup{round-half = even}% |
| 1702 |
\num{0.055} \\ |
| 1703 |
\num{0.045} |
| 1704 |
\end{LaTeXdemo} |
| 1705 |
|
| 1706 |
\DescribeOption{uncertainty-round-direction} |
| 1707 |
When rounding with uncertainties, the direction to round the uncertainty part |
| 1708 |
may be set independently of the main number: this is typically used to round |
| 1709 |
the uncertainty strictly upward. |
| 1710 |
\begin{LaTeXdemo} |
| 1711 |
\sisetup{round-mode = uncertainty} |
| 1712 |
\num{0.123(141)} \\ |
| 1713 |
\sisetup{uncertainty-round-direction = up}% |
| 1714 |
\num{0.123(141)} |
| 1715 |
\end{LaTeXdemo} |
| 1716 |
|
| 1717 |
\DescribeOption{round-minimum} |
| 1718 |
There are cases in which rounding will result in the number reaching zero. It |
| 1719 |
may be desirable to show such results as below a threshold value. This can be |
| 1720 |
achieved by setting \opt{round-minimum} to the threshold value. There will be |
| 1721 |
no effect when rounding to a number of significant figures as it is not |
| 1722 |
possible to obtain the value zero in these cases. |
| 1723 |
\begin{LaTeXdemo} |
| 1724 |
\sisetup{round-mode = places}% |
| 1725 |
\num{0.0055} \\ |
| 1726 |
\num{0.0045} \\ |
| 1727 |
\sisetup{round-minimum = 0.01}% |
| 1728 |
\num{0.0055} \\ |
| 1729 |
\num{0.0045} |
| 1730 |
\end{LaTeXdemo} |
| 1731 |
|
| 1732 |
\DescribeOption{round-zero-positive} |
| 1733 |
When rounding negative numbers to a fixed number of places, a zero value may |
| 1734 |
result. Usually this is expressed as an unsigned value, but in some cases |
| 1735 |
retaining the negative sign may be desirable. This behavior can be controlled |
| 1736 |
using the \opt{round-zero-positive} switch. |
| 1737 |
\begin{LaTeXdemo} |
| 1738 |
\sisetup{round-mode = places}% |
| 1739 |
\num{-0.001} \\ |
| 1740 |
\sisetup{round-zero-positive = false}% |
| 1741 |
\num{-0.001} |
| 1742 |
\end{LaTeXdemo} |
| 1743 |
|
| 1744 |
\DescribeOption{drop-zero-decimal} |
| 1745 |
It may be desirable to convert decimals to integers when the decimal part is |
| 1746 |
zero. This is set up using the \opt{drop-zero-decimal} option, which applies |
| 1747 |
after rounding but before setting minimum numbers of digits. |
| 1748 |
\begin{LaTeXdemo} |
| 1749 |
\num{2.0} \\ |
| 1750 |
\num{2.1} \\ |
| 1751 |
\sisetup{drop-zero-decimal}% |
| 1752 |
\num{2.0} \\ |
| 1753 |
\num{2.1} |
| 1754 |
\end{LaTeXdemo} |
| 1755 |
|
| 1756 |
\DescribeOption{minimum-decimal-digits} |
| 1757 |
\DescribeOption{minimum-integer-digits} |
| 1758 |
The \opt{minimum-decimal-digits} and \opt{minimum-integer-digits} option may be |
| 1759 |
used to pad numbers to a given size. This applies independent of any rounding. |
| 1760 |
\begin{LaTeXdemo} |
| 1761 |
\num{123} \\ |
| 1762 |
\num[minimum-integer-digits = 2]{123} \\ |
| 1763 |
\num[minimum-integer-digits = 4]{123} \\ |
| 1764 |
\num{0.123} \\ |
| 1765 |
\num[minimum-decimal-digits = 2]{0.123} \\ |
| 1766 |
\num[minimum-decimal-digits = 4]{0.123} \\ |
| 1767 |
\end{LaTeXdemo} |
| 1768 |
|
| 1769 |
\subsection{Printing numbers} |
| 1770 |
|
| 1771 |
Actually printing numbers is controlled by a number of settings, which apply |
| 1772 |
ideas such as differing decimal markers, digit grouping and so on. All of these |
| 1773 |
options are concerned with the appearance of output, rather than the data it |
| 1774 |
conveys. The options are summarised in Table~\ref{tab:opt:num:out}. |
| 1775 |
\begin{table} |
| 1776 |
\caption{Output options for numbers.% |
| 1777 |
\label{tab:opt:num:out}} |
| 1778 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 1779 |
\toprule |
| 1780 |
\multicolumn{1}{l}{Option name} & |
| 1781 |
Type & |
| 1782 |
\multicolumn{1}{l}{Default} \\ |
| 1783 |
\midrule |
| 1784 |
bracket-ambiguous-numbers & Switch & true \\ |
| 1785 |
bracket-negative-numbers & Switch & false \\ |
| 1786 |
digit-group-size & Integer & 3 \\ |
| 1787 |
digit-group-first-size & Integer & 3 \\ |
| 1788 |
digit-group-other-size & Integer & 3 \\ |
| 1789 |
exponent-base & Literal & 10 \\ |
| 1790 |
exponent-product & Math & \verb=\times= \\ |
| 1791 |
group-allow-singleton & Switch & true \\ |
| 1792 |
group-digits & Choice & all \\ |
| 1793 |
group-minimum-digits & Integer & 5 \\ |
| 1794 |
group-separator & Literal & \cs{,} \\ |
| 1795 |
negative-color & Literal & \meta{none} \\ ^^A ( |
| 1796 |
output-close-uncertainty & Literal & ) \\ |
| 1797 |
output-decimal-marker & Literal & . \\ |
| 1798 |
output-exponent-marker & Literal & \meta{none} \\ |
| 1799 |
output-open-uncertainty & Literal & ( \\ ^^A ) |
| 1800 |
print-exponent-implicit-plus & Switch & false \\ |
| 1801 |
print-implicit-plus & Switch & false \\ |
| 1802 |
print-mantissa-implicit-plus & Switch & false \\ |
| 1803 |
print-unity-mantissa & Switch & true \\ |
| 1804 |
print-zero-exponent & Switch & false \\ |
| 1805 |
print-zero-integer & Switch & true \\ |
| 1806 |
simplify-uncertainty & Switch & false \\ |
| 1807 |
tight-spacing & Switch & false \\ |
| 1808 |
uncertainty-descriptor-mode & Choice & bracket-separator \\ |
| 1809 |
uncertainty-descriptor-separator & Literal & \cs{ } \\ |
| 1810 |
uncertainty-descriptors & Literal & \meta{none} \\ |
| 1811 |
uncertainty-mode & Choice & compact \\ |
| 1812 |
uncertainty-separator & Literal & \meta{none} \\ |
| 1813 |
zero-decimal-as-symbol & Switch & false \\ |
| 1814 |
zero-symbol & Literal & \verb=\mbox{---}= \\ |
| 1815 |
\bottomrule |
| 1816 |
\end{tabular} |
| 1817 |
\end{table} |
| 1818 |
|
| 1819 |
\DescribeOption{group-digits} |
| 1820 |
\DescribeOption{group-separator} |
| 1821 |
Grouping digits into blocks of three is a common method to increase the ease of |
| 1822 |
reading of numbers. The \opt{group-digits} choice controls whether this |
| 1823 |
behavior applies, and takes the values \opt{all}, \opt{none}, \opt{decimal} and |
| 1824 |
\opt{integer}. Grouping can be activated separately for the integer and decimal |
| 1825 |
parts of a number using the appropriately-named values. |
| 1826 |
\begin{LaTeXdemo} |
| 1827 |
\num{12345.67890} \\ |
| 1828 |
\num[group-digits = none]{12345.67890} \\ |
| 1829 |
\num[group-digits = decimal]{12345.67890} \\ |
| 1830 |
\num[group-digits = integer]{12345.67890} |
| 1831 |
\end{LaTeXdemo} |
| 1832 |
The separator used between groups of digits is stored by the |
| 1833 |
\opt{group-separator} option. This takes literal input and may be used in math |
| 1834 |
mode: for a text-mode full space use \verb*|\ |. |
| 1835 |
\begin{LaTeXdemo} |
| 1836 |
\num{12345} \\ |
| 1837 |
\num[group-separator = {,}]{12345} \\ |
| 1838 |
\num[group-separator = \ ]{12345} |
| 1839 |
\end{LaTeXdemo} |
| 1840 |
|
| 1841 |
\DescribeOption{group-minimum-digits} |
| 1842 |
Grouping is not always applied to smaller numbers; this can be controlled using |
| 1843 |
the option \opt{group-minimum-digits}, which specifies how many digits must be |
| 1844 |
present before grouping is applied. The number of digits is considered |
| 1845 |
separately for the integer and decimal parts of the number: grouping does not |
| 1846 |
\enquote{cross the boundary}. |
| 1847 |
\begin{LaTeXdemo} |
| 1848 |
\num{1234} \\ |
| 1849 |
\num{12345} \\ |
| 1850 |
\num[group-minimum-digits = 5]{1234} \\ |
| 1851 |
\num[group-minimum-digits = 5]{12345} \\ |
| 1852 |
\num{1234.5678} \\ |
| 1853 |
\num{12345.67890} \\ |
| 1854 |
\num[group-minimum-digits = 5]{1234.5678} \\ |
| 1855 |
\num[group-minimum-digits = 5]{12345.67890} |
| 1856 |
\end{LaTeXdemo} |
| 1857 |
|
| 1858 |
\DescribeOption{digit-group-size} |
| 1859 |
\DescribeOption{digit-group-first-size} |
| 1860 |
\DescribeOption{digit-group-other-size} |
| 1861 |
The number of digits in each group can be controlled by the setting |
| 1862 |
\opt{digit-group-size}, which has standard value $3$. Finer control can be |
| 1863 |
achieved using \opt{digit-group-first-size} and \opt{digit-group-other-size}: |
| 1864 |
the first group is that immediately by the decimal point, the other value |
| 1865 |
applies to the second and subsequent groupings. These can be used for |
| 1866 |
example to achieve the grouping typically used in India (lakh). |
| 1867 |
\begin{LaTeXdemo} |
| 1868 |
\num{1234567890} \\ |
| 1869 |
\num[digit-group-size = 5]{1234567890} \\ |
| 1870 |
\num[digit-group-other-size = 2]{1234567890} |
| 1871 |
\end{LaTeXdemo} |
| 1872 |
|
| 1873 |
\DescribeOption{final-digit-group-min-size} |
| 1874 |
Grouping can result in a \enquote{dangling} digit, for example if there are |
| 1875 |
seven digits in the decimal part with the standard group-of-three approach. To |
| 1876 |
allow these to be avoided automatically, the setting |
| 1877 |
\opt{final-digit-group-min-size} is available. Setting this to for example |
| 1878 |
\opt{2} will mean that the final group is enlarged to respect the minimum size |
| 1879 |
where this is required to avoid a group size of~1. |
| 1880 |
\begin{LaTeXdemo} |
| 1881 |
\num{0.1234567} \\ |
| 1882 |
\num[final-digit-group-min-size = 2]{0.1234567} |
| 1883 |
\end{LaTeXdemo} |
| 1884 |
|
| 1885 |
\DescribeOption{output-decimal-marker} |
| 1886 |
The decimal marker used in output is set using the \opt{output-decimal-marker} |
| 1887 |
option; this can differ from the input marker. |
| 1888 |
\begin{LaTeXdemo} |
| 1889 |
\num{1.23} \\ |
| 1890 |
\num[output-decimal-marker = {,}]{1.23} \\ |
| 1891 |
\end{LaTeXdemo} |
| 1892 |
|
| 1893 |
\DescribeOption{exponent-base} |
| 1894 |
\DescribeOption{exponent-product} |
| 1895 |
When exponents are present in the input, the \opt{exponent-base} and |
| 1896 |
\opt{exponent-product} options set the obvious parts of the output. |
| 1897 |
\begin{LaTeXdemo} |
| 1898 |
\num[exponent-product = \times]{1e2} \\ |
| 1899 |
\num[exponent-product = \cdot]{1e2} \\ |
| 1900 |
\num[exponent-base = 2]{1e2} |
| 1901 |
\end{LaTeXdemo} |
| 1902 |
\DescribeOption{output-exponent-marker} |
| 1903 |
Alternatively, if the \opt{output-exponent-marker} option is set then the value |
| 1904 |
stored will be used in place of the normal product and base combination. |
| 1905 |
\begin{LaTeXdemo} |
| 1906 |
\num[output-exponent-marker = e]{1e2} \\ |
| 1907 |
\num[output-exponent-marker = \mathrm{E}]{1e2} |
| 1908 |
\end{LaTeXdemo} |
| 1909 |
|
| 1910 |
\DescribeOption{uncertainty-mode} |
| 1911 |
\DescribeOption{output-open-uncertainty} |
| 1912 |
\DescribeOption{output-close-uncertainty} |
| 1913 |
\DescribeOption{uncertainty-separator} |
| 1914 |
\DescribeOption{allow-uncertainty-breaks} |
| 1915 |
When input is given including a single uncertainty, it can be printed either |
| 1916 |
with the uncertainty in brackets or as a separate number. This behavior is |
| 1917 |
controlled by the \opt{uncertainty-mode} choice. When this is set to |
| 1918 |
\opt{separate}, the uncertainty is printed as an entirely separate number |
| 1919 |
preceded by \cs{pm}. Other settings all place the uncertainty in brackets |
| 1920 |
directly attached to the main value. The standard setting of \opt{compact} |
| 1921 |
prints digits of uncertainty in the least-significant digits. It does |
| 1922 |
\emph{not} print a decimal marker if the uncertainty crosses the decimal. The |
| 1923 |
setting \opt{full} prints the full value of the uncertainty. Finally, |
| 1924 |
\opt{compact-marker} is available to print in the \opt{compact} style except |
| 1925 |
where the uncertainty crosses the decimal, in which case the \opt{full} style |
| 1926 |
is used. When the uncertainty is given in brackets, a space may be added |
| 1927 |
between the main number and the uncertainty: this is stored using the |
| 1928 |
\opt{uncertainty-separator} option. The opening and closing brackets used are |
| 1929 |
stored in \opt{output-open-uncertainty} and \opt{output-close-uncertainty}, |
| 1930 |
respectively. Tokens may be inserted before the opening bracket using |
| 1931 |
\opt{uncertainty-separator}. As standard, a break is allowed before a separated |
| 1932 |
uncertainty: this can be suppressed by setting \opt{allow-uncertainty-breaks} |
| 1933 |
to \opt{false}. |
| 1934 |
\begin{LaTeXdemo} |
| 1935 |
\num{123.45(120)} \\ |
| 1936 |
\num{0.035(14)} \\ |
| 1937 |
\sisetup{uncertainty-mode = full} |
| 1938 |
\num{123.45(120)} \\ |
| 1939 |
\num{0.035(14)} \\ |
| 1940 |
\sisetup{uncertainty-mode = compact-marker} |
| 1941 |
\num{123.45(120)} \\ |
| 1942 |
\num{0.035(14)} \\ |
| 1943 |
\sisetup{ |
| 1944 |
output-open-uncertainty = [, |
| 1945 |
output-close-uncertainty = ], |
| 1946 |
uncertainty-separator = \, |
| 1947 |
}% |
| 1948 |
\num{1.234(5)} |
| 1949 |
\end{LaTeXdemo} |
| 1950 |
|
| 1951 |
\DescribeOption{uncertainty-descriptors} |
| 1952 |
\DescribeOption{uncertainty-descriptor-mode} |
| 1953 |
\DescribeOption{uncertainty-descriptor-separator} |
| 1954 |
Multiple uncertainties can be given for a number. These are always printed in a |
| 1955 |
separated form. When there is more than one uncertainty part, it may be useful |
| 1956 |
to describe the nature of this value. This can be achieved using the |
| 1957 |
\opt{uncertainty-descriptors} option, which take a comma-separated list of |
| 1958 |
descriptions. The formatting of the descriptors can be adjusted using the |
| 1959 |
settings \opt{uncertainty-descriptor-mode} and |
| 1960 |
\opt{uncertainty-descriptor-separator}. The choices for the \opt{mode} are |
| 1961 |
\opt{bracket}, \opt{bracket-separator}, \opt{separator} and \opt{subscript}. |
| 1962 |
\begin{LaTeXdemo} |
| 1963 |
\num{1.2(3)(4)} \\ |
| 1964 |
\sisetup{uncertainty-descriptors = {sys, stat}} |
| 1965 |
\num{1.2(3)(4)} \\ |
| 1966 |
\num[uncertainty-descriptor-mode = subscript]{1.2(3)(4)} |
| 1967 |
\end{LaTeXdemo} |
| 1968 |
|
| 1969 |
\DescribeOption{simplify-uncertainty} |
| 1970 |
Where the upper and lower parts of an asymmetrical uncertainty are identical, |
| 1971 |
it may be desirable to print as in symmetrical format. This can be enabled |
| 1972 |
using the \opt{simplify-uncertainty} option. |
| 1973 |
\begin{LaTeXdemo} |
| 1974 |
\num{10.56(2:2)} \\ |
| 1975 |
\num[simplify-uncertainty]{10.56(2:2)} |
| 1976 |
\end{LaTeXdemo} |
| 1977 |
|
| 1978 |
\DescribeOption{bracket-ambiguous-numbers} |
| 1979 |
There are certain combinations of numerical input which can be ambiguous. This |
| 1980 |
can be corrected by adding brackets in the appropriate place, and is controlled |
| 1981 |
by the \opt{bracket-ambiguous-numbers} switch. This option only applies to pure |
| 1982 |
numbers: when formatting quantities, the need for brackets also depends on the |
| 1983 |
placement of units, so is controlled by \opt{separate-uncertainty-units}. |
| 1984 |
\begin{LaTeXdemo} |
| 1985 |
\sisetup{uncertainty-mode = separate} |
| 1986 |
\num{1.2(3)e4} \\ |
| 1987 |
\num[bracket-ambiguous-numbers = false]{1.2(3)e4} |
| 1988 |
\end{LaTeXdemo} |
| 1989 |
|
| 1990 |
\DescribeOption{negative-color} |
| 1991 |
The package can detect negative mantissa values and alter print color |
| 1992 |
accordingly. This is disabled by setting the option to an empty value. |
| 1993 |
This option does \emph{not} apply to complex numbers. |
| 1994 |
\begin{LaTeXdemo} |
| 1995 |
\num{-15673} \\ |
| 1996 |
\num[negative-color = red]{-15673} |
| 1997 |
\end{LaTeXdemo} |
| 1998 |
|
| 1999 |
\DescribeOption{bracket-negative-numbers} |
| 2000 |
A common means to display negative numbers in financial situations is to place |
| 2001 |
them in brackets. This can be carried out automatically using the |
| 2002 |
\opt{bracket-negative-numbers} option. This option does \emph{not} apply to |
| 2003 |
complex numbers. |
| 2004 |
\begin{LaTeXdemo} |
| 2005 |
\num{-15673} \\ |
| 2006 |
\num[bracket-negative-numbers]{-15673} \\ |
| 2007 |
\qty{-10}{\metre} \\ |
| 2008 |
\qty[bracket-negative-numbers]{-10}{\metre} |
| 2009 |
\end{LaTeXdemo} |
| 2010 |
|
| 2011 |
\DescribeOption{tight-spacing} |
| 2012 |
Under some circumstances is may be desirable to \enquote{squeeze} the output |
| 2013 |
spacing. This is turned on using the \opt{tight-spacing} switch, which |
| 2014 |
compresses spacing where possible. |
| 2015 |
\begin{LaTeXdemo} |
| 2016 |
\num{2e3} \\ |
| 2017 |
\num[tight-spacing = true]{2e3} |
| 2018 |
\end{LaTeXdemo} |
| 2019 |
|
| 2020 |
\DescribeOption{print-implicit-plus} |
| 2021 |
\DescribeOption{print-mantissa-implicit-plus} |
| 2022 |
\DescribeOption{print-exponent-implicit-plus} |
| 2023 |
It may be useful to force all numbers to have a sign. This behavior is |
| 2024 |
controlled by the \opt{print-implicit-plus} option: this is used if given and |
| 2025 |
if no sign was present in the input. It is possible to set this behavior for |
| 2026 |
the exponent and mantissa independently. |
| 2027 |
\begin{LaTeXdemo} |
| 2028 |
\num{345} \\ |
| 2029 |
\num[print-implicit-plus]{345} |
| 2030 |
\end{LaTeXdemo} |
| 2031 |
|
| 2032 |
\DescribeOption{print-unity-mantissa} |
| 2033 |
\DescribeOption{print-zero-exponent} |
| 2034 |
\DescribeOption{print-zero-integer} |
| 2035 |
Printing of a mantissa of $1$, an exponent of $0$ and an integer component of |
| 2036 |
$0$ is controllable by the options \opt{print-unity-mantissa}, |
| 2037 |
\opt{print-zero-exponent} and \opt{print-zero-integer}. The standard settings |
| 2038 |
print a mantissa of $1$ and an integer part of $0$, but omit an exponent of |
| 2039 |
$0$. Notice that where both \opt{print-unity-mantissa} and |
| 2040 |
\opt{print-zero-exponent} are set to \opt{false}, the value $1$ will still be |
| 2041 |
printed (\foreign{i.e.}~\opt{print-zero-exponent} has a higher priority). |
| 2042 |
\begin{LaTeXdemo} |
| 2043 |
\num{1e4} \\ |
| 2044 |
\num[print-unity-mantissa = false]{1e4} \\ |
| 2045 |
\num{444e0} \\ |
| 2046 |
\num[print-zero-exponent = true]{444e0} \\ |
| 2047 |
\num{0.123} \\ |
| 2048 |
\num[print-zero-integer = false]{0.123} |
| 2049 |
\end{LaTeXdemo} |
| 2050 |
|
| 2051 |
\DescribeOption{zero-decimal-as-symbol} |
| 2052 |
\DescribeOption{zero-symbol} |
| 2053 |
In some areas, particularly financial, entirely zero decimal parts are |
| 2054 |
replaced by a dash. This is supported by option \opt{zero-decimal-as-symbol}, |
| 2055 |
which then uses the material stored using \opt{zero-symbol} as the replacement. |
| 2056 |
\begin{LaTeXdemo} |
| 2057 |
\num{123.00} \\ |
| 2058 |
\sisetup{zero-decimal-as-symbol} |
| 2059 |
\num{123.00} \\ |
| 2060 |
\num[zero-symbol = \text{[{---}]}]{123.00} |
| 2061 |
\end{LaTeXdemo} |
| 2062 |
|
| 2063 |
\subsection{Lists, products and ranges} |
| 2064 |
|
| 2065 |
Lists, products and ranges of numbers and quantities have a small number of |
| 2066 |
specialised options, which apply to these more unusual input forms |
| 2067 |
(Table~\ref{tab:opt:num:list}). |
| 2068 |
\begin{table} |
| 2069 |
\begin{threeparttable} |
| 2070 |
\caption{Output options for lists, products and ranges of numbers and |
| 2071 |
quantities.% |
| 2072 |
\label{tab:opt:num:list}} |
| 2073 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2074 |
\toprule |
| 2075 |
\multicolumn{1}{l}{Option name} & |
| 2076 |
Type & |
| 2077 |
\multicolumn{1}{l}{Default\tnote{*}} \\ |
| 2078 |
\midrule % ( |
| 2079 |
list-close-bracket & Literal & ) \\ |
| 2080 |
list-exponents & Choice & individual \\ |
| 2081 |
list-final-separator & Literal & \verb*= \text{and} = \\ |
| 2082 |
list-independent-prefix & Switch & false \\ |
| 2083 |
list-open-bracket & Literal & ( \\ % ) |
| 2084 |
list-pair-separator & Literal & \verb*= \text{and} = \\ |
| 2085 |
list-separator & Literal & \verb*=\text{,} = \\ |
| 2086 |
list-units & Choice & repeat \\ % ( |
| 2087 |
product-close-bracket & Literal & ) \\ |
| 2088 |
product-exponents & Choice & individual \\ |
| 2089 |
product-independent-prefix & Switch & false \\ |
| 2090 |
product-mode & Choice & symbol \\ |
| 2091 |
product-open-bracket & Literal & ( \\ % ) |
| 2092 |
product-phrase & Literal & \verb*= \text{by} = \\ |
| 2093 |
product-symbol & Literal & \cs{times} \\ |
| 2094 |
product-units & Choice & repeat \\ % ( |
| 2095 |
range-close-bracket & Literal & ) \\ |
| 2096 |
range-exponents & Choice & individual \\ |
| 2097 |
range-independent-prefix & Switch & false \\ |
| 2098 |
range-open-bracket & Literal & ( \\ % ) |
| 2099 |
range-open-phrase & Literal & \meta{empty} \\ |
| 2100 |
range-phrase & Literal & \verb*= \text{to} = \\ |
| 2101 |
range-units & Choice & repeat \\ |
| 2102 |
\bottomrule |
| 2103 |
\end{tabular} |
| 2104 |
\footnotesize |
| 2105 |
\begin{tablenotes} |
| 2106 |
\item[*] The default values are actually more complex for two |
| 2107 |
reasons: allowing spaces to work in both math and text modes, |
| 2108 |
and localization of strings. |
| 2109 |
\end{tablenotes} |
| 2110 |
\end{threeparttable} |
| 2111 |
\end{table} |
| 2112 |
|
| 2113 |
\DescribeOption{list-final-separator} |
| 2114 |
\DescribeOption{list-pair-separator} |
| 2115 |
\DescribeOption{list-separator} |
| 2116 |
Lists of numbers are printed with a separator between each item, which is |
| 2117 |
stored using the \opt{list-separator} option. The separator before the last |
| 2118 |
item of a list may be different, and is therefore set using the |
| 2119 |
\opt{list-final-separator} option. The separator used for exactly two items is |
| 2120 |
set using the \opt{list-pair-separator} option. Any spaces needed should be |
| 2121 |
included in the option settings: none are added within the code. The separators |
| 2122 |
are always printed in text mode. |
| 2123 |
\begin{LaTeXdemo} |
| 2124 |
\numlist{0.1;0.2;0.3} \\ |
| 2125 |
\numlist[list-separator = {; }]{0.1;0.2;0.3} \\ |
| 2126 |
\numlist[list-final-separator = {, }]{0.1;0.2;0.3} \\ |
| 2127 |
\numlist[ |
| 2128 |
list-separator = { and }, |
| 2129 |
list-final-separator = { and finally } |
| 2130 |
]{0.1;0.2;0.3} \\ |
| 2131 |
\numlist{0.1;0.2} \\ |
| 2132 |
\numlist[list-pair-separator = {, and }]{0.1;0.2} |
| 2133 |
\end{LaTeXdemo} |
| 2134 |
|
| 2135 |
\DescribeOption{product-mode} |
| 2136 |
\DescribeOption{product-phrase} |
| 2137 |
\DescribeOption{product-symbol} |
| 2138 |
Products of numbers can be output using either a product symbol or phrase: |
| 2139 |
this is controlled by the \opt{product-mode} setting. When \opt{symbol} is |
| 2140 |
set, the appropriate symbol is stored in \opt{product-symbol}. When using |
| 2141 |
\opt{phrase-mode}, the information is stored in \opt{product-phrase}. Phrases |
| 2142 |
are always printed in text mode; symbols are printed using the same routine |
| 2143 |
as for numbers. |
| 2144 |
\begin{LaTeXdemo} |
| 2145 |
\numproduct{5 x 100 x 2} \\ |
| 2146 |
\numproduct[product-symbol = \ensuremath{\cdot}]{5 x 100 x 2} \\ |
| 2147 |
\sisetup{product-mode = phrase}% |
| 2148 |
\numproduct{5 x 100 x 2}\\ |
| 2149 |
\numproduct[product-phrase = { BY }]{5 x 100 x 2} \\ |
| 2150 |
\end{LaTeXdemo} |
| 2151 |
|
| 2152 |
\DescribeOption{range-open-phrase} |
| 2153 |
\DescribeOption{range-phrase} |
| 2154 |
Ranges of numbers can be given as input. These will have an appropriate word or |
| 2155 |
symbol inserted between the two entries: this is stored using the |
| 2156 |
\opt{range-phrase} option. The phrase should include any necessary spaces: no |
| 2157 |
extra space is added. The phrase is always printed in text mode. |
| 2158 |
\begin{LaTeXdemo} |
| 2159 |
\numrange{5}{100} \\ |
| 2160 |
\numrange[range-phrase = --]{5}{100} |
| 2161 |
\end{LaTeXdemo} |
| 2162 |
In some languages, an opening phrase is \emph{required}; this is supported |
| 2163 |
using the \opt{range-open-phrase} key. |
| 2164 |
\begin{LaTeXdemo} |
| 2165 |
\numrange{10}{12} \\ |
| 2166 |
\numrange[range-open-phrase = {\text{from} }]{5}{100} |
| 2167 |
\end{LaTeXdemo} |
| 2168 |
|
| 2169 |
\DescribeOption{list-exponents} |
| 2170 |
\DescribeOption{product-exponents} |
| 2171 |
\DescribeOption{range-exponents} |
| 2172 |
Lists, products and ranges can be \enquote{compressed} by combining the |
| 2173 |
exponent parts. This is controlled by the options \opt{list-exponents}, |
| 2174 |
\opt{product-exponents} and \opt{range-exponents}, all of which take the |
| 2175 |
choices \opt{individual}, \opt{combine-bracket} and \opt{combine}. The standard |
| 2176 |
setting, \opt{individual}, leaves the exponent with the matching value. Both |
| 2177 |
\opt{combine} and \opt{combine-bracket} take the exponent of the first entry |
| 2178 |
and apply to all other entries, with the exponent itself places at the end. |
| 2179 |
\begin{LaTeXdemo} |
| 2180 |
\numlist{5e3;7e3;9e3;1e4} \\ |
| 2181 |
\numproduct{5e3 x 7e3 x 9e3 x 1e4} \\ |
| 2182 |
\numrange{5e3}{7e3} \\ |
| 2183 |
\sisetup |
| 2184 |
{ |
| 2185 |
list-exponents = combine-bracket , |
| 2186 |
product-exponents = combine-bracket , |
| 2187 |
range-exponents = combine-bracket |
| 2188 |
} |
| 2189 |
\numlist{5e3;7e3;9e3;1e4} \\ |
| 2190 |
\numproduct{5e3 x 7e3 x 9e3 x 1e4} \\ |
| 2191 |
\numrange{5e3}{7e3} \\ |
| 2192 |
\sisetup |
| 2193 |
{ |
| 2194 |
list-exponents = combine , |
| 2195 |
product-exponents = combine , |
| 2196 |
range-exponents = combine |
| 2197 |
} |
| 2198 |
\numlist{5e3;7e3;9e3;1e4} \\ |
| 2199 |
\numproduct{5e3 x 7e3 x 9e3 x 1e4} \\ |
| 2200 |
\numrange{5e3}{7e3} |
| 2201 |
\end{LaTeXdemo} |
| 2202 |
|
| 2203 |
\DescribeOption{list-units} |
| 2204 |
\DescribeOption{product-units} |
| 2205 |
\DescribeOption{range-units} |
| 2206 |
The \opt{list-units}, \opt{product-units} and \opt{range-units} options |
| 2207 |
determine how \cs{qtylist}, \cs{qtyproduct} and \cs{qtyrange} command print |
| 2208 |
units, respectively. The standard setting for these is \opt{repeat}, where each |
| 2209 |
number will be printed with a unit. Alternatives are \opt{bracket} and |
| 2210 |
\opt{single}. If set to \opt{single}, this will override collection of |
| 2211 |
exponents. |
| 2212 |
\begin{LaTeXdemo} |
| 2213 |
\qtylist{2;4;6;8}{\tesla} \\ |
| 2214 |
\qtylist[list-units = bracket]{2;4;6;8}{\tesla} \\ |
| 2215 |
\qtylist[list-units = repeat]{2;4;6;8}{\tesla} \\ |
| 2216 |
\qtylist[list-units = single]{2;4;6;8}{\tesla} \\ |
| 2217 |
\qtyrange{2}{4}{\degreeCelsius} \\ |
| 2218 |
\qtyrange[range-units = bracket]{2}{4}{\degreeCelsius} \\ |
| 2219 |
\qtyrange[range-units = repeat]{2}{4}{\degreeCelsius} \\ |
| 2220 |
\qtyrange[range-units = single]{2}{4}{\degreeCelsius} |
| 2221 |
\end{LaTeXdemo} |
| 2222 |
The option \opt{product-units} also offers the settings \opt{bracket-power} and |
| 2223 |
\opt{power}. |
| 2224 |
\begin{LaTeXdemo} |
| 2225 |
\qtyproduct{2 x 4}{\metre} \\ |
| 2226 |
\qtyproduct[product-units = bracket-power]{2 x 4}{\metre} \\ |
| 2227 |
\qtyproduct[product-units = power]{2 x 4}{\metre} |
| 2228 |
\end{LaTeXdemo} |
| 2229 |
\DescribeOption{list-close-bracket} |
| 2230 |
\DescribeOption{list-open-bracket} |
| 2231 |
\DescribeOption{product-close-bracket} |
| 2232 |
\DescribeOption{product-open-bracket} |
| 2233 |
\DescribeOption{range-close-bracket} |
| 2234 |
\DescribeOption{range-open-bracket} |
| 2235 |
The brackets used can be customised using the relevant \texttt{\dots-open-bracket} |
| 2236 |
and \texttt{\dots-close-bracket} options. |
| 2237 |
\begin{LaTeXdemo} |
| 2238 |
\sisetup{ |
| 2239 |
list-units = bracket , |
| 2240 |
list-open-bracket = [ , |
| 2241 |
list-close-bracket = ] |
| 2242 |
} |
| 2243 |
\qtylist{5e3;7e3;9e3;1e4}{\second} \\ |
| 2244 |
\sisetup{ |
| 2245 |
product-units = bracket , |
| 2246 |
product-open-bracket = \{ , |
| 2247 |
product-close-bracket = \} |
| 2248 |
} |
| 2249 |
\qtyproduct{5e3 x 7e3 x 9e3 x 1e4}{\metre} \\ |
| 2250 |
\sisetup{ |
| 2251 |
range-units = bracket , |
| 2252 |
range-open-bracket = \langle , |
| 2253 |
range-close-bracket = \rangle |
| 2254 |
} |
| 2255 |
\qtyrange{2}{4}{\degreeCelsius} |
| 2256 |
\end{LaTeXdemo} |
| 2257 |
|
| 2258 |
\DescribeOption{list-independent-prefix} |
| 2259 |
\DescribeOption{product-independent-prefix} |
| 2260 |
\DescribeOption{range-independent-prefix} |
| 2261 |
When converting exponents to prefixes, there are two possible approaches to the |
| 2262 |
case where units are repeated. They can all be converted to use the same |
| 2263 |
(initial) prefix, or they can be processed separately. The |
| 2264 |
\texttt{\dots-independent-prefix} options are used to control this outcome. |
| 2265 |
\begin{LaTeXdemo} |
| 2266 |
\sisetup{exponent-to-prefix = true}% |
| 2267 |
\qtyrange{1e3}{1e9}{\watt}\\ |
| 2268 |
\sisetup{range-independent-prefix = true}% |
| 2269 |
\qtyrange{1e3}{1e9}{\watt} |
| 2270 |
\end{LaTeXdemo} |
| 2271 |
|
| 2272 |
\subsection{Complex numbers} |
| 2273 |
|
| 2274 |
A small number of options apply specifically to the handling of complex |
| 2275 |
numbers; these are summarised in Table~\ref{tab:opt:num:complex}. |
| 2276 |
\begin{table} |
| 2277 |
\caption{Options for complex numbers.% |
| 2278 |
\label{tab:opt:num:complex}} |
| 2279 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2280 |
\toprule |
| 2281 |
\multicolumn{1}{@{}l}{Option name} & |
| 2282 |
Type & |
| 2283 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2284 |
\midrule |
| 2285 |
complex-angle-unit & Choice & degrees \\ |
| 2286 |
complex-mode & Choice & input \\ |
| 2287 |
complex-phase-command & Literal & \cs{angle} \\ |
| 2288 |
complex-root-position & Choice & after-number \\ |
| 2289 |
complex-symbol-degree & Literal & \cs{degree} \\ |
| 2290 |
input-complex-root & Literal & ij \\ |
| 2291 |
output-complex-root & Literal & \verb=\mathrm{i}= \\ |
| 2292 |
print-complex-unity & Switch & false \\ |
| 2293 |
\bottomrule |
| 2294 |
\end{tabular} |
| 2295 |
\end{table} |
| 2296 |
|
| 2297 |
\DescribeOption{complex-mode} |
| 2298 |
The format in which complex values are printed can be set using the |
| 2299 |
\opt{complex-mode} option. With the standard setting (\opt{input}), the complex |
| 2300 |
value is printed as-given. By setting the option to \opt{cartesian} or |
| 2301 |
\opt{polar}, the output format can be set to an Cartesian or polar form. |
| 2302 |
Conversion uses the \LaTeX3 floating-point unit, so is limited to $16$ decimal |
| 2303 |
places. When converting from Cartesian to polar form, the complex root symbol |
| 2304 |
must come at the \emph{end} of the imaginary part. It must also be specified |
| 2305 |
using \texttt{i}. |
| 2306 |
\begin{LaTeXdemo} |
| 2307 |
\complexnum{1 + i} \\ |
| 2308 |
\complexnum{1:45} \\ |
| 2309 |
\complexnum[complex-mode = cartesian]{1 + i} \\ |
| 2310 |
\complexnum[complex-mode = cartesian, round-mode = places]{1:45} \\ |
| 2311 |
\complexnum[complex-mode = polar]{1 + i} \\ |
| 2312 |
\complexnum[complex-mode = polar]{1:45} |
| 2313 |
\end{LaTeXdemo} |
| 2314 |
|
| 2315 |
\DescribeOption{input-complex-root} |
| 2316 |
When using complex numbers in input, the complex root $(\mathrm{i} = |
| 2317 |
\sqrt{-1}\,)$ is indicated by one of the tokens stored in |
| 2318 |
\opt{input-complex-roots}. The parser understands complex root symbols given |
| 2319 |
either before or after the associated number (but will detect any invalid |
| 2320 |
arrangement): |
| 2321 |
\begin{LaTeXdemo} |
| 2322 |
\complexnum{9.99 + 88.8i} \\ |
| 2323 |
\complexnum{9.99 + i88.8} |
| 2324 |
\end{LaTeXdemo} |
| 2325 |
|
| 2326 |
\DescribeOption{output-complex-root} |
| 2327 |
The output complex root symbol is independent of the input and can be changed |
| 2328 |
using the \opt{output-complex-root} setting. |
| 2329 |
\begin{LaTeXdemo} |
| 2330 |
\complexnum[output-complex-root = i]{1+2i} \\ |
| 2331 |
\complexnum[output-complex-root = j]{1+2i} |
| 2332 |
\end{LaTeXdemo} |
| 2333 |
|
| 2334 |
\DescribeOption{complex-root-position} |
| 2335 |
The position of the complex root can be adjusted to place it |
| 2336 |
either before or after the associated numeral in a complex number |
| 2337 |
using the \opt{complex-root-position} option. |
| 2338 |
\begin{LaTeXdemo} |
| 2339 |
\complexnum{67-0.9i} \\ |
| 2340 |
\complexnum[complex-root-position = before-number]{67-0.9i} \\ |
| 2341 |
\complexnum[complex-root-position = after-number]{67-0.9i} |
| 2342 |
\end{LaTeXdemo} |
| 2343 |
|
| 2344 |
\DescribeOption{complex-angle-unit} |
| 2345 |
\DescribeOption{complex-symbol-degree} |
| 2346 |
\DescribeOption{complex-phase-command} |
| 2347 |
When printing or converting to polar form, the angle may be interpreted in |
| 2348 |
units set by \opt{complex-angle-unit}: one of \opt{degrees} or \opt{radians}. |
| 2349 |
The unit symbol used for degrees is controlled by \opt{complex-symbol-degree}. |
| 2350 |
To allow control of the surrounding of the entire phase part, the option |
| 2351 |
\opt{complex-phase-command} is available. This can be used for example to |
| 2352 |
print using Steinmetz notation (which requires the \pkg{steinmetz} package). |
| 2353 |
\begin{LaTeXdemo} |
| 2354 |
\complexqty{1:1}{\ohm} \\ |
| 2355 |
\complexqty[complex-angle-unit = radians]{1:1}{\ohm} \\ |
| 2356 |
\complexqty[complex-symbol-degree = d]{1:1}{\ohm} \\ |
| 2357 |
\complexqty[complex-phase-command = \phase]{1:1}{\ohm} |
| 2358 |
\end{LaTeXdemo} |
| 2359 |
|
| 2360 |
\DescribeOption{print-complex-unity} |
| 2361 |
When the complex part of a number is exactly \num{1}, it is possible to either |
| 2362 |
print or suppress the value. This is controlled by the switch |
| 2363 |
\opt{print-complex-unity}. |
| 2364 |
\begin{LaTeXdemo} |
| 2365 |
\complexqty{1i}{\ohm} \\ |
| 2366 |
\complexqty[print-complex-unity]{1i}{\ohm} |
| 2367 |
\end{LaTeXdemo} |
| 2368 |
|
| 2369 |
\subsection{Angles} |
| 2370 |
|
| 2371 |
Angle processing provided by the \cs{ang} function has a set of options which |
| 2372 |
apply in addition to the general ones set up for number processing. |
| 2373 |
\begin{table} |
| 2374 |
\caption{Angle options.% |
| 2375 |
\label{tab:opt:ang}} |
| 2376 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2377 |
\toprule |
| 2378 |
\multicolumn{1}{@{}l}{Option name} & |
| 2379 |
Type & |
| 2380 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2381 |
\midrule |
| 2382 |
angle-mode & Choice & input \\ |
| 2383 |
angle-symbol-degree & Literal & \cs{degree} \\ |
| 2384 |
angle-symbol-minute & Literal & \cs{arcminute} \\ |
| 2385 |
angle-symbol-over-decimal & Switch & false \\ |
| 2386 |
angle-symbol-second & Literal & \cs{arcsecond} \\ |
| 2387 |
angle-separator & Literal & \meta{empty} \\ |
| 2388 |
fill-angle-degrees & Switch & false \\ |
| 2389 |
fill-angle-minutes & Switch & false \\ |
| 2390 |
fill-angle-seconds & Switch & false \\ |
| 2391 |
\bottomrule |
| 2392 |
\end{tabular} |
| 2393 |
\end{table} |
| 2394 |
|
| 2395 |
\DescribeOption{angle-mode} |
| 2396 |
The format in which angles are printed can be set using the \opt{angle-mode} |
| 2397 |
option. With the standard setting (\opt{input}), the angle is printed as-given. |
| 2398 |
By setting the option to \opt{arc} or \opt{decimal}, the output format can |
| 2399 |
be set to an arc (degrees/minutes/seconds) or decimal value. Conversion uses |
| 2400 |
the \LaTeX3 floating-point unit, so is limited to $16$ decimal places. |
| 2401 |
\begin{LaTeXdemo} |
| 2402 |
\ang{2.67} \\ |
| 2403 |
\ang{2;3;4} \\ |
| 2404 |
\ang[angle-mode = arc]{2.67} \\ |
| 2405 |
\ang[angle-mode = arc]{2;3;4} \\ |
| 2406 |
\ang[angle-mode = decimal]{2.67} \\ |
| 2407 |
\ang[angle-mode = decimal]{2;3;4} \\ |
| 2408 |
\end{LaTeXdemo} |
| 2409 |
When integer angles are converted to arc format, the presence of minute and |
| 2410 |
second components is controlled by the options \opt{fill-angle-minutes} and |
| 2411 |
\opt{fill-angle-seconds} (see below). |
| 2412 |
|
| 2413 |
\DescribeOption{angle-separator} |
| 2414 |
When angles are printed in arc format, the separation of the different parts is |
| 2415 |
set up using the \opt{arc-separator} option. |
| 2416 |
\begin{LaTeXdemo} |
| 2417 |
\ang{6;7;6.5} \\ |
| 2418 |
\ang[angle-separator = \,]{6;7;6.5} |
| 2419 |
\end{LaTeXdemo} |
| 2420 |
|
| 2421 |
\DescribeOption{fill-angle-degrees} |
| 2422 |
\DescribeOption{fill-angle-minutes} |
| 2423 |
\DescribeOption{fill-angle-seconds} |
| 2424 |
Zero-filling for the degree, minute or second parts of an arc is controlled |
| 2425 |
using the \opt{fill-angle-degrees}, \opt{fill-angle-minutes} and |
| 2426 |
\opt{fill-angle-seconds} options. All are off as standard. |
| 2427 |
\begin{LaTeXdemo} |
| 2428 |
\ang{-1;;} \\ |
| 2429 |
\ang{;-2;} \\ |
| 2430 |
\ang{;;-3} \\ |
| 2431 |
{ |
| 2432 |
\sisetup{fill-angle-degrees} |
| 2433 |
\ang{-1;;} \\ |
| 2434 |
\ang{;-2;} \\ |
| 2435 |
\ang{;;-3} \\ |
| 2436 |
} |
| 2437 |
{ |
| 2438 |
\sisetup{fill-angle-minutes} |
| 2439 |
\ang{-1;;} \\ |
| 2440 |
\ang{;-2;} \\ |
| 2441 |
\ang{;;-3} \\ |
| 2442 |
} |
| 2443 |
{ |
| 2444 |
\sisetup{fill-angle-seconds} |
| 2445 |
\ang{-1;;} \\ |
| 2446 |
\ang{;-2;} \\ |
| 2447 |
\ang{;;-3} |
| 2448 |
} |
| 2449 |
\end{LaTeXdemo} |
| 2450 |
|
| 2451 |
\DescribeOption{angle-symbol-degree} |
| 2452 |
\DescribeOption{angle-symbol-minute} |
| 2453 |
\DescribeOption{angle-symbol-second} |
| 2454 |
With the standard settings, the symbols used for arc angles are the unit |
| 2455 |
commands \cs{degree}, \cs{arcminute} and \cs{arcsecond}. These can be altered |
| 2456 |
using \opt{angle-symbol-degree}, \opt{angle-symbol-minute} and |
| 2457 |
\opt{angle-symbol-second}. This is most likely to be used when the definition |
| 2458 |
of the unit macros is altered, for example to set \cs{arcsecond} as |
| 2459 |
\texttt{as} (see also Section~\ref{sec:hint:prefixangle}). |
| 2460 |
\begin{LaTeXdemo} |
| 2461 |
\ang{6;7;6.5} \\ |
| 2462 |
\sisetup{ |
| 2463 |
angle-symbol-degree = d , |
| 2464 |
angle-symbol-minute = m , |
| 2465 |
angle-symbol-second = s |
| 2466 |
} |
| 2467 |
\ang{6;7;6.5} |
| 2468 |
\end{LaTeXdemo} |
| 2469 |
|
| 2470 |
\DescribeOption{angle-symbol-over-decimal} |
| 2471 |
In some subject areas, most notably astronomy, the angle symbols are given over |
| 2472 |
the decimal marker, rather than at the end of the number. This behavior is |
| 2473 |
available using the \opt{angle-symbol-over-decimal} option. |
| 2474 |
\begin{LaTeXdemo} |
| 2475 |
\ang{45.697} \\ |
| 2476 |
\ang{6;7;6.5} \\ |
| 2477 |
\ang[angle-symbol-over-decimal]{45.697} \\ |
| 2478 |
\ang[angle-symbol-over-decimal]{6;7;6.5} |
| 2479 |
\end{LaTeXdemo} |
| 2480 |
|
| 2481 |
\subsection{Durations} |
| 2482 |
|
| 2483 |
Duration processing provided by the \cs{duration} function has a set of options |
| 2484 |
which apply in addition to the general ones set up for number processing. |
| 2485 |
\begin{table} |
| 2486 |
\caption{Angle options.% |
| 2487 |
\label{tab:opt:duration}} |
| 2488 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2489 |
\toprule |
| 2490 |
\multicolumn{1}{@{}l}{Option name} & |
| 2491 |
Type & |
| 2492 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2493 |
\midrule |
| 2494 |
duration-mode & Choice & input \\ |
| 2495 |
duration-symbol-hour & Literal & \cs{hour} \\ |
| 2496 |
duration-symbol-minute & Literal & \cs{minute} \\ |
| 2497 |
duration-symbol-second & Literal & \cs{second} \\ |
| 2498 |
duration-separator & Literal & \verb*"\ " \\ |
| 2499 |
fill-duration-hours & Switch & false \\ |
| 2500 |
fill-duration-minutes & Switch & false \\ |
| 2501 |
fill-duration-seconds & Switch & false \\ |
| 2502 |
\bottomrule |
| 2503 |
\end{tabular} |
| 2504 |
\end{table} |
| 2505 |
|
| 2506 |
\DescribeOption{duration-mode} |
| 2507 |
The format in which durations are printed can be set using the \opt{duration-mode} |
| 2508 |
option. With the standard setting (\opt{input}), the duration is printed as-given. |
| 2509 |
By setting the option to \opt{component} or \opt{decimal}, the output format can |
| 2510 |
be set to a component (hours/minutes/seconds) or decimal value. Conversion uses |
| 2511 |
the \LaTeX3 floating-point unit, so is limited to $16$ decimal places. |
| 2512 |
\begin{LaTeXdemo} |
| 2513 |
\duration{8.56} \\ |
| 2514 |
\duration{8;33;36} \\ |
| 2515 |
\duration[duration-mode = component]{8.56} \\ |
| 2516 |
\duration[duration-mode = component]{8;33;36} \\ |
| 2517 |
\duration[duration-mode = decimal]{8.56} \\ |
| 2518 |
\duration[duration-mode = decimal]{8;33;36} \\ |
| 2519 |
\end{LaTeXdemo} |
| 2520 |
When integer durations are converted to component format, the presence of minute |
| 2521 |
and second components is controlled by the options \opt{fill-duration-minutes} |
| 2522 |
and \opt{fill-duration-seconds} (see below). |
| 2523 |
|
| 2524 |
\DescribeOption{duration-separator} |
| 2525 |
When durations are printed in component format, the separation of the different |
| 2526 |
parts is set up using the \opt{duration-separator} option. |
| 2527 |
\begin{LaTeXdemo} |
| 2528 |
\duration{6;7;6.5} \\ |
| 2529 |
\duration[duration-separator = {, }]{6;7;6.5} |
| 2530 |
\end{LaTeXdemo} |
| 2531 |
|
| 2532 |
\DescribeOption{fill-duration-hours} |
| 2533 |
\DescribeOption{fill-duration-minutes} |
| 2534 |
\DescribeOption{fill-duration-seconds} |
| 2535 |
Zero-filling for the hour, minute or second components of durations is controlled |
| 2536 |
using the \opt{fill-duration-hours}, \opt{fill-duration-minutes} and |
| 2537 |
\opt{fill-duration-seconds} options. All are off as standard. |
| 2538 |
\begin{LaTeXdemo} |
| 2539 |
\duration{1;;} \\ |
| 2540 |
\duration{;2;} \\ |
| 2541 |
\duration{;;3} \\ |
| 2542 |
{ |
| 2543 |
\sisetup{fill-duration-hours} |
| 2544 |
\duration{1;;} \\ |
| 2545 |
\duration{;2;} \\ |
| 2546 |
\duration{;;3} \\ |
| 2547 |
} |
| 2548 |
{ |
| 2549 |
\sisetup{fill-duration-minutes} |
| 2550 |
\duration{1;;} \\ |
| 2551 |
\duration{;2;} \\ |
| 2552 |
\duration{;;3} \\ |
| 2553 |
} |
| 2554 |
{ |
| 2555 |
\sisetup{fill-duration-seconds} |
| 2556 |
\duration{1;;} \\ |
| 2557 |
\duration{;2;} \\ |
| 2558 |
\duration{;;3} |
| 2559 |
} |
| 2560 |
\end{LaTeXdemo} |
| 2561 |
|
| 2562 |
\DescribeOption{duration-unit-hour} |
| 2563 |
\DescribeOption{duration-unit-minute} |
| 2564 |
\DescribeOption{duration-unit-second} |
| 2565 |
With the standard settings, the units used for durations are the commands |
| 2566 |
\cs{hour}, \cs{minute} and \cs{second}. These can be altered using |
| 2567 |
\opt{duration-unit-hour}, \opt{duration-unit-minute} and |
| 2568 |
\opt{duration-unit-second}. |
| 2569 |
\begin{LaTeXdemo} |
| 2570 |
\duration{1;3;4.5} \\ |
| 2571 |
\sisetup{ |
| 2572 |
duration-unit-hour = d , |
| 2573 |
duration-unit-minute = m , |
| 2574 |
duration-unit-second = s |
| 2575 |
} |
| 2576 |
\duration{1;3;4.5} |
| 2577 |
\end{LaTeXdemo} |
| 2578 |
|
| 2579 |
\subsection{Creating units% |
| 2580 |
\label{sec:units:creating}} |
| 2581 |
|
| 2582 |
The various macro units are created at the start of the document. \pkg{siunitx} |
| 2583 |
can define these such that they are only available for use within the \cs{unit} |
| 2584 |
and \cs{qty} functions, or can make the unit macros available throughout the |
| 2585 |
document body. There are a number of settings which control this creation |
| 2586 |
process (Table~\ref{tab:opt:units:def}). As a result, these options all apply |
| 2587 |
in the preamble only. |
| 2588 |
\begin{table} |
| 2589 |
\caption{Unit creation options.% |
| 2590 |
\label{tab:opt:units:def}} |
| 2591 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2592 |
\toprule |
| 2593 |
\multicolumn{1}{@{}l}{Option name} & |
| 2594 |
Type & |
| 2595 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2596 |
\midrule |
| 2597 |
free-standing-units & Switch & false \\ |
| 2598 |
overwrite-command & Switch & false \\ |
| 2599 |
space-before-unit & Switch & false \\ |
| 2600 |
unit-optional-argument & Switch & false \\ |
| 2601 |
use-xspace & Switch & false \\ |
| 2602 |
\bottomrule |
| 2603 |
\end{tabular} |
| 2604 |
\end{table} |
| 2605 |
|
| 2606 |
\DescribeOption{free-standing-units} |
| 2607 |
\DescribeOption{overwrite-functions} |
| 2608 |
The \opt{free-standing-units} option controls whether the unit macros are |
| 2609 |
usable outside of the \cs{unit} and \cs{qty} arguments. When this option is |
| 2610 |
\opt{true}, \pkg{siunitx} creates the macros for general use. The standard |
| 2611 |
method to achieve this does not overwrite any existing macros: this behavior |
| 2612 |
can be altered using the \opt{overwrite-commands} switch. For technical |
| 2613 |
reasons, when \opt{free-standing-units} is set \opt{false}, the names of unit |
| 2614 |
macros still have to be defined: as such, they will be created if they do not |
| 2615 |
exist, but will raise an error if used outside of the \cs{unit} and \cs{qty} |
| 2616 |
arguments. |
| 2617 |
|
| 2618 |
When using the approach of \enquote{free-standing} unit commands, only macros |
| 2619 |
created using \cs{DeclareSIUnit} are defined generally. Thus prefixes and |
| 2620 |
powers should be combined with the desired unit into a single free-standing |
| 2621 |
command, for example |
| 2622 |
\begin{LaTeXdemo}[code only] |
| 2623 |
\DeclareSIUnit\kilometre{\kilo\metre} |
| 2624 |
\end{LaTeXdemo} |
| 2625 |
|
| 2626 |
\DescribeOption{space-before-unit} |
| 2627 |
\DescribeOption{unit-optional-argument} |
| 2628 |
\DescribeOption{use-xspace} |
| 2629 |
When \enquote{free standing} unit macros are created, their behavior can be |
| 2630 |
adjusted by a number of options. These are mainly intended for emulating the |
| 2631 |
input syntax of older packages. The option \opt{unit-optional-argument} gives |
| 2632 |
the same behavior for the inputs |
| 2633 |
\begin{LaTeXdemo}[code only] |
| 2634 |
\qty{10}{\metre} |
| 2635 |
\end{LaTeXdemo} |
| 2636 |
and |
| 2637 |
\begin{LaTeXdemo}[code only] |
| 2638 |
\metre[10]. |
| 2639 |
\end{LaTeXdemo} |
| 2640 |
The \opt{space-before-unit} and \opt{use-xspace} options control the behavior |
| 2641 |
at the \enquote{ends} of the unit macros. Activating \opt{space-before-unit} |
| 2642 |
inserts the number--unit space before the unit is printed. This is suitable for |
| 2643 |
the input syntax |
| 2644 |
\begin{LaTeXdemo}[code only] |
| 2645 |
30\metre |
| 2646 |
\end{LaTeXdemo} |
| 2647 |
but does mean that the unit macros are incorrectly spaced in running text. On |
| 2648 |
the other hand, the \opt{use-xspace} option attempts to correctly space input |
| 2649 |
such as |
| 2650 |
\begin{LaTeXdemo}[code only] |
| 2651 |
\metre is the symbol for metres. |
| 2652 |
\end{LaTeXdemo} |
| 2653 |
|
| 2654 |
\subsection{Using units} |
| 2655 |
|
| 2656 |
Part of the power of \pkg{siunitx} is the ability to alter the output format |
| 2657 |
for units without changing the input. The behavior of units is therefore |
| 2658 |
controlled by a number of options which alter either the processing of units or |
| 2659 |
the output directly (Table~\ref{tab:opt:units:out}). |
| 2660 |
\begin{table} |
| 2661 |
\centering |
| 2662 |
\caption{Unit output options.% |
| 2663 |
\label{tab:opt:units:out}} |
| 2664 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2665 |
\toprule |
| 2666 |
\multicolumn{1}{@{}l}{Option name} & |
| 2667 |
Type & |
| 2668 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2669 |
\midrule |
| 2670 |
bracket-unit-denominator & Switch & true \\ |
| 2671 |
forbid-literal-units & Switch & false \\ |
| 2672 |
fraction-command & Literal & \cs{frac} \\ |
| 2673 |
inter-unit-product & Literal & \cs{,} \\ |
| 2674 |
parse-units & Switch & true \\ |
| 2675 |
per-mode & Choice & power \\ |
| 2676 |
per-symbol-script-correction & Literal & \cs{!} \\ |
| 2677 |
per-symbol & Literal & / \\ |
| 2678 |
power-half-as-sqrt & Switch & false \\ |
| 2679 |
qualifier-mode & Choice & subscript \\ |
| 2680 |
qualifier-phrase & Literal & \meta{empty} \\ |
| 2681 |
sticky-per & Switch & false \\ |
| 2682 |
unit-font-command & Literal & \cs{mathrm} \\ |
| 2683 |
\bottomrule |
| 2684 |
\end{tabular} |
| 2685 |
\end{table} |
| 2686 |
|
| 2687 |
\DescribeOption{inter-unit-product} |
| 2688 |
The separator between each unit is stored using the \opt{inter-unit-product} |
| 2689 |
option. The standard setting is a thin space: another common choice is a |
| 2690 |
centered dot. To get the correct spacing it is necessary to use |
| 2691 |
|\ensuremath{{}\cdot{}}| in the latter case. |
| 2692 |
\begin{LaTeXdemo} |
| 2693 |
\unit{\farad\squared\lumen\candela} \\ |
| 2694 |
\unit[inter-unit-product = \ensuremath{{}\cdot{}}] |
| 2695 |
{\farad\squared\lumen\candela} |
| 2696 |
\end{LaTeXdemo} |
| 2697 |
|
| 2698 |
\DescribeOption{per-mode} |
| 2699 |
\DescribeOption{display-per-mode} |
| 2700 |
\DescribeOption{inline-per-mode} |
| 2701 |
\DescribeOption{per-symbol} |
| 2702 |
\DescribeOption{fraction-command} |
| 2703 |
\DescribeOption{bracket-unit-denominator} |
| 2704 |
The handling of \cs{per} is altered using the \opt{per-mode} choice option. The |
| 2705 |
standard setting is \opt{power}, meaning that \cs{per} generates reciprocal |
| 2706 |
powers for units. Setting the option to \opt{fraction} uses the |\frac| |
| 2707 |
function to typeset the positive and negative powers of a unit separately. |
| 2708 |
The exact function can be adjusted using the \opt{fraction-command} option. |
| 2709 |
\begin{LaTeXdemo} |
| 2710 |
\unit{\joule\per\mole\per\kelvin} \\ |
| 2711 |
\unit{\metre\per\second\squared} \\ |
| 2712 |
\unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\ |
| 2713 |
\unit[per-mode = fraction]{\metre\per\second\squared} |
| 2714 |
\end{LaTeXdemo} |
| 2715 |
The closely-related \opt{power-positive-first} setting acts in the same way but |
| 2716 |
places all of the positive powers before any negative ones. |
| 2717 |
\begin{LaTeXdemo} |
| 2718 |
\unit{\ampere\per\mole\second} \\ |
| 2719 |
\unit[per-mode = power-positive-first] |
| 2720 |
{\ampere\per\mole\second} |
| 2721 |
\end{LaTeXdemo} |
| 2722 |
It is possible to use a symbol (usually |/|) to separate the two parts of a |
| 2723 |
unit by setting \opt{per-mode} to \opt{symbol}; the symbol used is stored using |
| 2724 |
the setting \opt{per-symbol}. This method for displaying units can be |
| 2725 |
ambiguous, and so brackets are added unless \opt{bracket-unit-denominator} is |
| 2726 |
set to \opt{false}. Notice that \opt{bracket-unit-denominator} only applies |
| 2727 |
when \opt{per-mode} is set to \opt{symbol}. |
| 2728 |
\begin{LaTeXdemo} |
| 2729 |
\sisetup{per-mode = symbol}% |
| 2730 |
\unit{\joule\per\mole\per\kelvin} \\ |
| 2731 |
\unit{\metre\per\second\squared} \\ |
| 2732 |
\unit[per-symbol = \ \text{div}\ ]{\joule\per\mole\per\kelvin} \\ |
| 2733 |
\unit[bracket-unit-denominator = false]{\joule\per\mole\per\kelvin} |
| 2734 |
\end{LaTeXdemo} |
| 2735 |
The often-requested (but mathematically invalid) \opt{repeated-symbol} option |
| 2736 |
is also available to repeat the symbol for each \cs{per}. |
| 2737 |
\begin{LaTeXdemo} |
| 2738 |
\unit[per-mode = repeated-symbol]{\joule\per\mole\per\kelvin} |
| 2739 |
\end{LaTeXdemo} |
| 2740 |
The use of a symbol can be restricted to the case where exactly one is |
| 2741 |
required: the setting \opt{single-symbol} will use a symbol if and only |
| 2742 |
if there are one or more positive powers and exactly one negative power. |
| 2743 |
In other cases, powers are used. |
| 2744 |
\begin{LaTeXdemo} |
| 2745 |
\sisetup{per-mode = single-symbol} |
| 2746 |
\qty{10}{\per\metre} \\ |
| 2747 |
\qty{20}{\metre\per\second} \\ |
| 2748 |
\qty{30}{\joule\per\mole\per\kelvin} |
| 2749 |
\end{LaTeXdemo} |
| 2750 |
It is possible for the behavior of the \cs{per} function to depend on the |
| 2751 |
prevailing math style. Setting either \opt{display-per-mode} or |
| 2752 |
\opt{inline-per-mode} independently can be used to achieve this. For example, |
| 2753 |
the following example will use the \opt{symbol} setting for in line math, |
| 2754 |
and the \opt{fraction} setting when used in display math. |
| 2755 |
\begin{LaTeXdemo} |
| 2756 |
\sisetup{ |
| 2757 |
display-per-mode = fraction , |
| 2758 |
inline-per-mode = symbol |
| 2759 |
}% |
| 2760 |
$ \unit{\joule\per\mole\per\kelvin} $ |
| 2761 |
\[ \unit{\joule\per\mole\per\kelvin} \] |
| 2762 |
\unit{\joule\per\mole\per\kelvin} \\ |
| 2763 |
$ |
| 2764 |
\displaystyle |
| 2765 |
\unit{\joule\per\mole\per\kelvin} |
| 2766 |
$ |
| 2767 |
\[ |
| 2768 |
\textstyle |
| 2769 |
\unit{\joule\per\mole\per\kelvin} |
| 2770 |
\] |
| 2771 |
\end{LaTeXdemo} |
| 2772 |
|
| 2773 |
\DescribeOption{per-symbol-script-correction} |
| 2774 |
When using the \opt{symbol} setting for \opt{per-mode}, there may the need to |
| 2775 |
adjust spacing between a superscript power and the symbol. This is provided as |
| 2776 |
a command to be inserted between the two items: the standard value is a thin |
| 2777 |
negative space, \cs{!}. |
| 2778 |
\begin{LaTeXdemo} |
| 2779 |
\sisetup{per-mode = symbol}% |
| 2780 |
\unit{\cm\cubed\per\gram} \\ |
| 2781 |
\unit[per-symbol-script-correction = ]{\cm\cubed\per\gram} |
| 2782 |
\end{LaTeXdemo} |
| 2783 |
|
| 2784 |
\DescribeOption{sticky-per} |
| 2785 |
By default, \cs{per} applies only to the next unit given.\footnote{This is the |
| 2786 |
standard method of reading units in English: for example, |
| 2787 |
\unit{\joule\per\mole\per\kelvin} is pronounced \enquote{joules per mole per |
| 2788 |
kelvin}.} By setting the \opt{sticky-per} flag, this behavior is changed so |
| 2789 |
that \cs{per} applies to all subsequent units. |
| 2790 |
\begin{LaTeXdemo} |
| 2791 |
\unit{\pascal\per\gray\henry} \\ |
| 2792 |
\unit[sticky-per]{\pascal\per\gray\henry} |
| 2793 |
\end{LaTeXdemo} |
| 2794 |
|
| 2795 |
\DescribeOption{qualifier-mode} |
| 2796 |
\DescribeOption{qualifier-phrase} |
| 2797 |
Unit qualifiers can be printed in three different formats, set by the |
| 2798 |
\opt{qualifier-mode} option. The standard setting is \opt{subscript}, while the |
| 2799 |
options \opt{bracket}, \opt{combine} and \opt{phrase} are also possible. With |
| 2800 |
the last settings, powers can lead to ambiguity and are automatically detected |
| 2801 |
and brackets added as appropriate. |
| 2802 |
\begin{LaTeXdemo} |
| 2803 |
\unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\ |
| 2804 |
\unit[qualifier-mode = bracket] |
| 2805 |
{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\ |
| 2806 |
\unit[qualifier-mode = combine] |
| 2807 |
{\deci\bel\of{i}} |
| 2808 |
\end{LaTeXdemo} |
| 2809 |
The \opt{phrase} option is used with \opt{qualifier-phrase}, which allows for |
| 2810 |
example a space or other linking text to be inserted. |
| 2811 |
\begin{LaTeXdemo} |
| 2812 |
\sisetup{qualifier-mode = phrase, qualifier-phrase = \ }% |
| 2813 |
\unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\ |
| 2814 |
\sisetup{qualifier-phrase = \ \mbox{of}\ }% |
| 2815 |
\unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} |
| 2816 |
\end{LaTeXdemo} |
| 2817 |
|
| 2818 |
\DescribeOption{power-half-as-sqrt} |
| 2819 |
In some cases, the power of $0.5$ is shown by giving the unit symbol as a |
| 2820 |
square root. This can be enabled by setting \opt{power-half-as-sqrt} to |
| 2821 |
\opt{true} |
| 2822 |
\begin{LaTeXdemo} |
| 2823 |
\unit{\Hz\tothe{0.5}} \\ |
| 2824 |
\unit[power-half-as-sqrt]{\Hz\tothe{0.5}} |
| 2825 |
\end{LaTeXdemo} |
| 2826 |
|
| 2827 |
\DescribeOption{parse-units} |
| 2828 |
Normally, \pkg{siunitx} is used with the unit parse enabled, and only prints |
| 2829 |
units directly if there is literal input. However, if the input is known to be |
| 2830 |
essentially consistent and high performance is desired, then the parser can be |
| 2831 |
turned off using the \opt{parse-units} switch. |
| 2832 |
\begin{LaTeXdemo} |
| 2833 |
\qty{300}{\MHz} \\ |
| 2834 |
\qty[parse-units = false]{300}{\MHz} |
| 2835 |
\end{LaTeXdemo} |
| 2836 |
|
| 2837 |
\DescribeOption{forbid-literal-units} |
| 2838 |
Some users may prefer to completely disable the use of literal input in units, |
| 2839 |
for example to enforce consistency. This can be accomplished by setting the |
| 2840 |
\opt{forbid-literal-units} switch. With this option enabled, only macro-based |
| 2841 |
units can be used in a document. This only applies when \opt{parse-units} is |
| 2842 |
\opt{true}. |
| 2843 |
|
| 2844 |
\DescribeOption{unit-font-command} |
| 2845 |
The command used to set unit themselves may be adjusted using the |
| 2846 |
\opt{unit-font-command} option. This is typically set to |\mathrm|. |
| 2847 |
\begin{LaTeXdemo} |
| 2848 |
\unit{\lumen} \\ |
| 2849 |
\unit[unit-font-command = \mathit]{\lumen} |
| 2850 |
\end{LaTeXdemo} |
| 2851 |
|
| 2852 |
\subsection{Quantities} |
| 2853 |
|
| 2854 |
Some options apply to quantities (the combination of a number and a unit), |
| 2855 |
rather than to the numbers or units alone (Table~\ref{tab:opt:quantities}). |
| 2856 |
\begin{table} |
| 2857 |
\centering |
| 2858 |
\caption{Options for quantities.% |
| 2859 |
\label{tab:opt:quantities}} |
| 2860 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2861 |
\toprule |
| 2862 |
\multicolumn{1}{@{}l}{Option name} & |
| 2863 |
Type & |
| 2864 |
\multicolumn{1}{@{}l}{Default} \\ |
| 2865 |
\midrule |
| 2866 |
allow-quantity-breaks & Switch & false \\ |
| 2867 |
extract-mass-in-kilograms & Switch & true \\ |
| 2868 |
prefix-mode & Choice & input \\ |
| 2869 |
quantity-product & Literal & \cs{,} \\ |
| 2870 |
separate-uncertainty-units & Choice & bracket \\ |
| 2871 |
\bottomrule |
| 2872 |
\end{tabular} |
| 2873 |
\end{table} |
| 2874 |
|
| 2875 |
\DescribeOption{allow-quantity-breaks} |
| 2876 |
Usually, the combination of a number and unit is regarded as a single |
| 2877 |
mathematical entity which should not be split across lines. However, there are |
| 2878 |
cases (very long units, narrow columns, \foreign{etc}.) where breaks may be |
| 2879 |
needed. This can be turned on using the \opt{allow-quantity-breaks} option. |
| 2880 |
\begin{LaTeXdemo} |
| 2881 |
\begin{minipage}{3cm} |
| 2882 |
% Gives an underfull hbox |
| 2883 |
X\hspace{2.4cm}\qty{10}{\metre} \\ |
| 2884 |
\sisetup{allow-quantity-breaks} |
| 2885 |
X\hspace{2.4cm}\qty{10}{\metre} |
| 2886 |
\end{minipage} |
| 2887 |
\end{LaTeXdemo} |
| 2888 |
|
| 2889 |
\DescribeOption{quantity-product} |
| 2890 |
The product symbol between the number and unit is set using the |
| 2891 |
\opt{quantity-product} option. |
| 2892 |
\begin{LaTeXdemo} |
| 2893 |
\qty{2.67}{\farad} \\ |
| 2894 |
\qty[quantity-product = \ ]{2.67}{\farad} \\ |
| 2895 |
\qty[quantity-product = ]{2.67}{\farad} |
| 2896 |
\end{LaTeXdemo} |
| 2897 |
|
| 2898 |
\DescribeOption{prefix-mode} |
| 2899 |
\DescribeOption{extract-mass-in-kilograms} |
| 2900 |
The unit prefixes (\cs{kilo}, \foreign{etc}.) are normally given as letters. |
| 2901 |
However, the package can convert these into numerical powers. This is |
| 2902 |
controlled by the \opt{prefix-mode} option, which takes the values \opt{input}, |
| 2903 |
\opt{combine-exponent} and \opt{extract-exponent}. The \opt{input} setting |
| 2904 |
leaves the prefixes unchanged. Using \opt{combine-exponent} will add any |
| 2905 |
exponent amount from the number to the first unit: this will modify any |
| 2906 |
existing prefix. Finally, using \opt{extract-exponent} will remove all prefixes |
| 2907 |
and express them as an exponent. The treatment of kilograms in this case can be |
| 2908 |
set using \opt{extract-mass-in-kilograms}: when \opt{true}, the \emph{kilo} |
| 2909 |
prefix is retained as part of the unit. This will mean that all grams are |
| 2910 |
converted to kilograms. |
| 2911 |
\begin{LaTeXdemo} |
| 2912 |
\qty{1e3}{\metre\second} \\ |
| 2913 |
\qty[prefix-mode = combine-exponent]{1e3}{\metre\second} \\ |
| 2914 |
\qty{10}{\kilo\gram\squared\deci\second} \\ |
| 2915 |
\qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second}\\ |
| 2916 |
\qty[prefix-mode = extract-exponent]{7.5}{\gram} \\ |
| 2917 |
\sisetup{extract-mass-in-kilograms = false} |
| 2918 |
\qty{10}{\kilo\gram\squared\deci\second} \\ |
| 2919 |
\qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second} \\ |
| 2920 |
\qty[prefix-mode = extract-exponent]{7.5}{\gram} \\ |
| 2921 |
\end{LaTeXdemo} |
| 2922 |
This option does not apply to units \cs{degree}, \cs{arcminute}, \cs{arcsecond} |
| 2923 |
and \cs{percent}. |
| 2924 |
|
| 2925 |
\DescribeOption{separate-uncertainty-units} |
| 2926 |
When a number has multiple parts (such as a separate uncertainty) then the unit |
| 2927 |
must apply to all parts of the number. How this is shown is controlled using |
| 2928 |
the \opt{separate-uncertainty-units} options. The standard setting is |
| 2929 |
\opt{brackets}, which will place the entire numerical part in brackets and use |
| 2930 |
a single unit symbol. Alternative options are \opt{repeat} (print the unit for |
| 2931 |
each part of the number) and \opt{single} (print only one unit symbol: |
| 2932 |
mathematically incorrect). |
| 2933 |
\begin{LaTeXdemo} |
| 2934 |
\sisetup{uncertainty-mode = separate} |
| 2935 |
\qty{12.3(4)}{\kilo\gram} \\ |
| 2936 |
\qty[separate-uncertainty-units = bracket]{12.3(4)}{\kilo\gram} \\ |
| 2937 |
\qty[separate-uncertainty-units = repeat]{12.3(4)}{\kilo\gram} \\ |
| 2938 |
\qty[separate-uncertainty-units = single]{12.3(4)}{\kilo\gram} |
| 2939 |
\end{LaTeXdemo} |
| 2940 |
|
| 2941 |
\subsection{Tabular material} |
| 2942 |
|
| 2943 |
Processing of material in tables obeys the same settings as described for the |
| 2944 |
functions already described. However, there are some settings which apply only |
| 2945 |
to the layout of tabular material (Table~\ref{tab:opt:tables}). |
| 2946 |
\begin{table} |
| 2947 |
\caption{Options for tabular material.% |
| 2948 |
\label{tab:opt:tables}} |
| 2949 |
\begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}} |
| 2950 |
\toprule |
| 2951 |
\multicolumn{1}{@{}l}{Option name} & |
| 2952 |
Type & |
| 2953 |
\multicolumn{1}{l@{}}{Default} \\ |
| 2954 |
\midrule |
| 2955 |
table-align-comparator & Switch & true \\ |
| 2956 |
table-align-exponent & Switch & true \\ |
| 2957 |
table-align-text-after & Switch & true \\ |
| 2958 |
table-align-text-before & Switch & true \\ |
| 2959 |
table-align-uncertainty & Switch & true \\ |
| 2960 |
table-alignment & Meta & center \\ |
| 2961 |
table-alignment-mode & Choice & marker \\ |
| 2962 |
table-auto-round & Switch & false \\ |
| 2963 |
table-column-width & Length & 0pt \\ |
| 2964 |
table-fixed-width & Switch & false \\ |
| 2965 |
table-format & Special & 2.2 \\ |
| 2966 |
table-model-setup & Literal & \meta{empty} \\ |
| 2967 |
table-number-alignment & Choice & center \\ |
| 2968 |
table-text-alignment & Choice & center \\ |
| 2969 |
\bottomrule |
| 2970 |
\end{tabular} |
| 2971 |
\end{table} |
| 2972 |
|
| 2973 |
\DescribeOption{table-alignment-mode} |
| 2974 |
The method used by \pkg{siunitx} to align numbers is selected using the |
| 2975 |
\opt{table-alignment-mode} option, which may be one of \opt{marker}, |
| 2976 |
\opt{format} or \meta{none}. With the standard setting, \opt{marker}, the |
| 2977 |
package centers the decimal marker in a tabular column, potentially leaving |
| 2978 |
white space at the shorter end of a number. The \opt{format} mode uses |
| 2979 |
information from the \opt{table-format} key to construct a model: this is then |
| 2980 |
used to define the space available to a number. For asymmetrical numbers, this |
| 2981 |
method is strongly preferable. Finally, \opt{none} disables alignment entirely: |
| 2982 |
numbers are simply parsed. |
| 2983 |
|
| 2984 |
\DescribeOption{table-number-alignment} |
| 2985 |
When \opt{table-alignment-mode} is set to \opt{format} or \opt{none}, the |
| 2986 |
placement of the number \enquote{block} within the cell as a whole is set by |
| 2987 |
the \opt{table-number-alignment} option, which may be one of \opt{left}, |
| 2988 |
\opt{center} or \opt{right}. (When \opt{table-alignment-mode} is set to |
| 2989 |
\opt{marker}, the decimal marker is always centered in the cell.) The |
| 2990 |
different alignment choices are illustrated in Table~\ref{tab:S:align}, which |
| 2991 |
uses somewhat exaggerated column headings to show the relative position of the |
| 2992 |
cell contents. |
| 2993 |
\begin{LaTeXdemo}[code and float] |
| 2994 |
\begin{table} |
| 2995 |
\caption{Aligning the \texttt{S} column.% |
| 2996 |
\label{tab:S:align}} |
| 2997 |
\centering |
| 2998 |
\sisetup{table-format = 2.4, table-alignment-mode = format} |
| 2999 |
\begin{tabular}{@{} |
| 3000 |
S[table-alignment-mode = marker] |
| 3001 |
S[table-number-alignment = center] |
| 3002 |
S[table-number-alignment = left] |
| 3003 |
S[table-number-alignment = right] |
| 3004 |
@{}} |
| 3005 |
\toprule |
| 3006 |
{Some Values} & {Some Values} & {Some Values} & {Some Values} \\ |
| 3007 |
\midrule |
| 3008 |
2.3456 & 2.3456 & 2.3456 & 2.3456 \\ |
| 3009 |
34.2345 & 34.2345 & 34.2345 & 34.2345 \\ |
| 3010 |
56.7835 & 56.7835 & 56.7835 & 56.7835 \\ |
| 3011 |
90.473 & 90.473 & 90.473 & 90.473 \\ |
| 3012 |
\bottomrule |
| 3013 |
\end{tabular} |
| 3014 |
\end{table} |
| 3015 |
\end{LaTeXdemo} |
| 3016 |
When the alignment mode is set to \opt{none}, number are simply collected and |
| 3017 |
parsed without any further processing, as illustrated in |
| 3018 |
Table~\ref{tab:S:parse}. |
| 3019 |
\begin{LaTeXdemo}[code and float] |
| 3020 |
\begin{table} |
| 3021 |
\caption{Parsing without aligning in an \texttt{S} column.% |
| 3022 |
\label{tab:S:parse}} |
| 3023 |
\begin{tabular} |
| 3024 |
{@{} |
| 3025 |
S |
| 3026 |
S[table-alignment-mode = none] |
| 3027 |
@{}} |
| 3028 |
\toprule |
| 3029 |
{Decimal-centered} & |
| 3030 |
{Simple centering} \\ |
| 3031 |
\midrule |
| 3032 |
12.345 & 12.345 \\ |
| 3033 |
6,78 & 6,78 \\ |
| 3034 |
-88.8(9) & -88.8(9) \\ |
| 3035 |
4.5e3 & 4.5e3 \\ |
| 3036 |
\bottomrule |
| 3037 |
\end{tabular} |
| 3038 |
\end{table} |
| 3039 |
\end{LaTeXdemo} |
| 3040 |
|
| 3041 |
\DescribeOption{table-format} |
| 3042 |
When the \opt{table-alignment-mode} is set to \opt{format}, \pkg{siunitx} uses |
| 3043 |
the information set in \opt{table-format} to construct a \enquote{model} which |
| 3044 |
defines the space to reserve for a number. The \opt{table-format} key is |
| 3045 |
interpreted in much the same way as a table cell. The numerical part should |
| 3046 |
consist of a number showing how many figures to reserve in each part of the |
| 3047 |
input, plus any comparators, signs, \foreign{etc.} A variety of examples are |
| 3048 |
given in Table~\ref{tab:S:format}. |
| 3049 |
\begin{LaTeXdemo}[code and float] |
| 3050 |
\begin{table} |
| 3051 |
\caption{Reserving space in \texttt{S} columns.% |
| 3052 |
\label{tab:S:format}} |
| 3053 |
\sisetup{ |
| 3054 |
table-alignment-mode = format, |
| 3055 |
table-number-alignment = center, |
| 3056 |
} |
| 3057 |
\begin{tabular}{@{} |
| 3058 |
S[table-format = 2.2] |
| 3059 |
S[table-format = 2.2, table-number-alignment = right] |
| 3060 |
S[table-format = 2.2(1)] |
| 3061 |
S[table-format = 2.2(1), uncertainty-mode = separate] |
| 3062 |
S[table-format = +2.2] |
| 3063 |
S[table-format = 2.2e1] |
| 3064 |
@{}} |
| 3065 |
\toprule |
| 3066 |
{Values} |
| 3067 |
& {Values} |
| 3068 |
& {Values} |
| 3069 |
& {Values} |
| 3070 |
& {Values} |
| 3071 |
& {Values} \\ |
| 3072 |
\midrule |
| 3073 |
2.3 & 2.3 & 2.3(5) & 2.3(5) & 2.3 & 2.3e8 \\ |
| 3074 |
34.23 & 34.23 & 34.23(4) & 34.23(4) & 34.23 & 34.23 \\ |
| 3075 |
56.78 & 56.78 & 56.78(3) & 56.78(3) & -56.78 & 56.78e3 \\ |
| 3076 |
3,76 & 3,76 & 3,76(2) & 3.76(2) & +-3.76 & e6 \\ |
| 3077 |
\bottomrule |
| 3078 |
\end{tabular} |
| 3079 |
\end{table} |
| 3080 |
\end{LaTeXdemo} |
| 3081 |
It is important to note that any parts of a number \emph{not} specified in the |
| 3082 |
table format argument are set to be absent (the number of figures is set to |
| 3083 |
zero). Setting the \opt{table-format} option also resets |
| 3084 |
\opt{table-alignment-mode} to \opt{format}. |
| 3085 |
|
| 3086 |
\DescribeOption{table-model-setup} |
| 3087 |
In some tables (particularly those using bold extended fonts), it may be |
| 3088 |
necessary to insert additional information when creating the \enquote{model}. |
| 3089 |
This is handled using the \opt{table-model-setup} key. An example of the use of |
| 3090 |
this key is given in Section~\ref{sec:hint:heading}. |
| 3091 |
|
| 3092 |
Space for material before and after the \texttt{S} column can be reserved by |
| 3093 |
giving model text as part of the \opt{table-format} key. This is then used to |
| 3094 |
provide the necessary gap while maintaining alignment (Table~\ref{tab:S:ends}). |
| 3095 |
\begin{LaTeXdemo}[code and float] |
| 3096 |
\begin{table} |
| 3097 |
\caption{Text before and after numbers.% |
| 3098 |
\label{tab:S:ends}} |
| 3099 |
\sisetup{table-format = {now }2.4{\textsuperscript{\emph{a}}}} |
| 3100 |
\begin{tabular}{@{}S@{}} |
| 3101 |
\toprule |
| 3102 |
{Values} \\ |
| 3103 |
\midrule |
| 3104 |
2.3456 \\ |
| 3105 |
34.2345 \textsuperscript{\emph{a}}\\ |
| 3106 |
56.7835 \\ |
| 3107 |
now~ 90.473 \\ |
| 3108 |
\bottomrule |
| 3109 |
\end{tabular} |
| 3110 |
\end{table} |
| 3111 |
\end{LaTeXdemo} |
| 3112 |
|
| 3113 |
\DescribeOption{table-align-exponent} |
| 3114 |
\DescribeOption{table-align-uncertainty} |
| 3115 |
\DescribeOption{table-align-comparator} |
| 3116 |
When printing exponents in tables, there is a choice of aligning the exponent |
| 3117 |
parts or having these close up to the mantissa. This is controlled by the |
| 3118 |
\opt{table-align-exponent} option (Table~\ref{tab:align:exp}). Similarly, |
| 3119 |
uncertainty parts which are printed separately from the mantissa can be aligned |
| 3120 |
or closed up. This is set by the \opt{table-align-uncertainty} option |
| 3121 |
(Table~\ref{tab:align:uncert}). Finally, the same approach is available for the |
| 3122 |
comparator with the \opt{table-align-comparator} option |
| 3123 |
(Table~\ref{tab:align:comp}). |
| 3124 |
\begin{LaTeXdemo}[code and float] |
| 3125 |
\begin{table} |
| 3126 |
\caption{The \opt{table-align-exponent} option.% |
| 3127 |
\label{tab:align:exp}} |
| 3128 |
\sisetup{table-format = 1.3e2} |
| 3129 |
\begin{tabular}{@{}SS[table-align-exponent = false]@{}} |
| 3130 |
\toprule |
| 3131 |
{Header} & {Header} \\ |
| 3132 |
\midrule |
| 3133 |
1.2e3 & 1.2e3 \\ |
| 3134 |
1.234e56 & 1.234e56 \\ |
| 3135 |
\bottomrule |
| 3136 |
\end{tabular} |
| 3137 |
\end{table} |
| 3138 |
\end{LaTeXdemo} |
| 3139 |
\begin{LaTeXdemo}[code and float] |
| 3140 |
\begin{table} |
| 3141 |
\caption{The \opt{table-align-uncertainty} option.% |
| 3142 |
\label{tab:align:uncert}} |
| 3143 |
\sisetup{ |
| 3144 |
uncertainty-mode = separate, |
| 3145 |
table-format = 1.3(1), |
| 3146 |
} |
| 3147 |
\begin{tabular}{@{}SS[table-align-uncertainty = false]@{}} |
| 3148 |
\toprule |
| 3149 |
{Header} & {Header} \\ |
| 3150 |
\midrule |
| 3151 |
1.2(1) & 1.2(3) \\ |
| 3152 |
1.234(5) & 1.234(5) \\ |
| 3153 |
\bottomrule |
| 3154 |
\end{tabular} |
| 3155 |
\end{table} |
| 3156 |
\end{LaTeXdemo} |
| 3157 |
\begin{LaTeXdemo}[code and float] |
| 3158 |
\begin{table} |
| 3159 |
\caption{The \opt{table-align-comparator} option.% |
| 3160 |
\label{tab:align:comp}} |
| 3161 |
\sisetup{table-format = >2.2} |
| 3162 |
\begin{tabular}{@{}SS[table-align-comparator = false]@{}} |
| 3163 |
\toprule |
| 3164 |
{Header} & {Header} \\ |
| 3165 |
\midrule |
| 3166 |
> 1.2 & > 1.2 \\ |
| 3167 |
< 12.34 & < 12.34 \\ |
| 3168 |
\bottomrule |
| 3169 |
\end{tabular} |
| 3170 |
\end{table} |
| 3171 |
\end{LaTeXdemo} |
| 3172 |
|
| 3173 |
\DescribeOption{table-align-text-before} |
| 3174 |
\DescribeOption{table-align-text-after} |
| 3175 |
Note markers are often given in tables after the numerical content. It may be |
| 3176 |
desirable for these to close up to the numbers. Whether this takes place is |
| 3177 |
controlled by the \opt{table-align-text-before} and \opt{\ldots-after} |
| 3178 |
option (Table~\ref{tab:S:notes}). |
| 3179 |
\begin{LaTeXdemo}[code and float] |
| 3180 |
\begin{table} |
| 3181 |
\caption{Closing notes up to text.% |
| 3182 |
\label{tab:S:notes}} |
| 3183 |
\newrobustcmd\NoteMark[1]{% |
| 3184 |
\textsuperscript{\emph{#1}}% |
| 3185 |
} |
| 3186 |
\sisetup{table-format = {\NoteMark{a}}2.4} |
| 3187 |
\begin{tabular}{@{} |
| 3188 |
S |
| 3189 |
S[table-align-text-before = false] |
| 3190 |
@{}} |
| 3191 |
\toprule |
| 3192 |
{Values} & {Values} \\ |
| 3193 |
\midrule |
| 3194 |
2.3456 & 2.3456 \\ |
| 3195 |
\NoteMark{a} 4.234 & \NoteMark{a} 4.234 \\ |
| 3196 |
\NoteMark{b} .78 & \NoteMark{b} .78 \\ |
| 3197 |
\NoteMark{d} 88 & \NoteMark{d} 88 \\ |
| 3198 |
\bottomrule |
| 3199 |
\end{tabular} |
| 3200 |
\hspace{\fill}% |
| 3201 |
\sisetup{table-format = 2.4\NoteMark{a}} |
| 3202 |
\begin{tabular}{@{} |
| 3203 |
S |
| 3204 |
S[table-align-text-after = false] |
| 3205 |
@{}} |
| 3206 |
\toprule |
| 3207 |
{Values} & {Values} \\ |
| 3208 |
\midrule |
| 3209 |
2.3456 & 2.3456 \\ |
| 3210 |
34.234 \NoteMark{a} & 34.234 \NoteMark{a} \\ |
| 3211 |
56.78 \NoteMark{b} & 56.78 \NoteMark{b} \\ |
| 3212 |
90.4 \NoteMark{c} & 90.4 \NoteMark{c} \\ |
| 3213 |
88 \NoteMark{d} & 88 \NoteMark{d} \\ |
| 3214 |
\bottomrule |
| 3215 |
\end{tabular} |
| 3216 |
\end{table} |
| 3217 |
\end{LaTeXdemo} |
| 3218 |
|
| 3219 |
\DescribeOption{table-auto-round} |
| 3220 |
The contents of table cells can automatically be rounded or zero-filled to the |
| 3221 |
number of decimal digits given for the decimal part of the \opt{table-format} |
| 3222 |
option. This mode is activated using the \opt{table-auto-round} switch, as |
| 3223 |
illustrated in Table~\ref{tab:S:auto}. |
| 3224 |
\begin{LaTeXdemo}[code and float] |
| 3225 |
\begin{table} |
| 3226 |
\centering |
| 3227 |
\caption{The \opt{table-auto-round} option.% |
| 3228 |
\label{tab:S:auto}} |
| 3229 |
\sisetup{table-format = 1.3} |
| 3230 |
\begin{tabular}{@{}SS[table-auto-round]@{}} |
| 3231 |
\toprule |
| 3232 |
{Header} & {Header} \\ |
| 3233 |
\midrule |
| 3234 |
1.2 & 1.2 \\ |
| 3235 |
1.2345 & 1.2345 \\ |
| 3236 |
\bottomrule |
| 3237 |
\end{tabular} |
| 3238 |
\end{table} |
| 3239 |
\end{LaTeXdemo} |
| 3240 |
|
| 3241 |
\DescribeOption{parse-numbers} |
| 3242 |
When the \opt{parse-numbers} option is set to \opt{false}, then the alignment |
| 3243 |
code for tables takes a different approach. The output is always set in math |
| 3244 |
mode, and alignment takes place at the first decimal marker. This is achieved |
| 3245 |
by making it active in math mode. When reserving space for content only the |
| 3246 |
integer and decimal values for the mantissa are considered |
| 3247 |
(Table~\ref{tab:S:nonparsed}). |
| 3248 |
\begin{LaTeXdemo}[code and float] |
| 3249 |
\begin{table} |
| 3250 |
\caption{Aligning without parsing.% |
| 3251 |
\label{tab:S:nonparsed}} |
| 3252 |
\sisetup{ |
| 3253 |
parse-numbers = false, |
| 3254 |
table-format = 3.3 |
| 3255 |
} |
| 3256 |
\centering |
| 3257 |
\begin{tabular}{@{} |
| 3258 |
S |
| 3259 |
S[table-number-alignment = center] |
| 3260 |
S[table-number-alignment = right] |
| 3261 |
S[table-number-alignment = left] |
| 3262 |
@{}} |
| 3263 |
\toprule |
| 3264 |
{Some values} |
| 3265 |
& {Some values} |
| 3266 |
& {Some values} |
| 3267 |
& {Some values} \\ |
| 3268 |
\midrule |
| 3269 |
2.35 & 2.35 & 2.35 & 2.35 \\ |
| 3270 |
34.234 & 34.234 & 34.234 & 34.234 \\ |
| 3271 |
56.783 & 56.783 & 56.783 & 56.783 \\ |
| 3272 |
3,762 & 3,762 & 3,762 & 3.762 \\ |
| 3273 |
\sqrt{2} & \sqrt{2} & \sqrt{2} & \sqrt{2} \\ |
| 3274 |
\bottomrule |
| 3275 |
\end{tabular} |
| 3276 |
\end{table} |
| 3277 |
\end{LaTeXdemo} |
| 3278 |
|
| 3279 |
\DescribeOption{drop-exponent} |
| 3280 |
In cases where data cover a range of values, printing using a fixed exponent in |
| 3281 |
a table may make presentation clearer. In these cases, dropping the exponent |
| 3282 |
value from the table is useful. The general numerical options \opt{drop-exponent} |
| 3283 |
combined with \opt{exponent-mode = fixed} can be used to achieve this |
| 3284 |
(Table~\ref{tab:exp:omit}). |
| 3285 |
\begin{LaTeXdemo}[code and float] |
| 3286 |
\begin{table} |
| 3287 |
\caption{The \opt{drop-exponent} option.% |
| 3288 |
\label{tab:exp:omit}} |
| 3289 |
\begin{tabular}{@{} |
| 3290 |
S[table-format = 1.1e1] |
| 3291 |
S[ |
| 3292 |
drop-exponent = true, |
| 3293 |
exponent-mode = fixed, |
| 3294 |
fixed-exponent = 3, |
| 3295 |
table-format = 2.1, |
| 3296 |
] |
| 3297 |
@{}} |
| 3298 |
\toprule |
| 3299 |
{Header} & |
| 3300 |
\multicolumn{1}{c@{}}{Header / \num[print-unity-mantissa = false]{e3}} \\ |
| 3301 |
\midrule |
| 3302 |
1.2e3 & 1.2e3 \\ |
| 3303 |
3e2 & 3e2 \\ |
| 3304 |
1.0e4 & 1.0e4 \\ |
| 3305 |
\bottomrule |
| 3306 |
\end{tabular} |
| 3307 |
\end{table} |
| 3308 |
\end{LaTeXdemo} |
| 3309 |
|
| 3310 |
\DescribeOption{table-column-width} |
| 3311 |
\DescribeOption{table-fixed-width} |
| 3312 |
Usually, the width of the numerical column is allowed to vary depending on the |
| 3313 |
content. However, there are cases where a strictly fixed width is desirable. |
| 3314 |
For these cases, the \opt{table-fixed-width} and \opt{table-column-width} |
| 3315 |
options are available. The \opt{table-fixed-width} option activates fixed-width |
| 3316 |
columns, whilst \opt{table-column-width} defines the target width |
| 3317 |
(Table~\ref{tab:width:fixed}). Setting \opt{table-column-width} to a positive |
| 3318 |
value automatically enables \opt{table-fixed-width}. |
| 3319 |
\begin{LaTeXdemo}[code and float] |
| 3320 |
\begin{table} |
| 3321 |
\caption{Fixed-width columns.% |
| 3322 |
\label{tab:width:fixed}} |
| 3323 |
\begin{tabular} |
| 3324 |
{@{} |
| 3325 |
S |
| 3326 |
S[table-column-width = 2cm] |
| 3327 |
@{}} |
| 3328 |
\toprule |
| 3329 |
{Flexible} & |
| 3330 |
{Fixed} \\ |
| 3331 |
\midrule |
| 3332 |
1.23 & 1.23 \\ |
| 3333 |
45.6 & 45.6 \\ |
| 3334 |
\bottomrule |
| 3335 |
\end{tabular} |
| 3336 |
\end{table} |
| 3337 |
\end{LaTeXdemo} |
| 3338 |
|
| 3339 |
The \opt{table-column-width} option can also be used to achieve special |
| 3340 |
effects. One example is centring a column of numbers under a wide heading, with |
| 3341 |
the numbers themselves right-aligned (Table~\ref{tab:width:special}). |
| 3342 |
\begin{LaTeXdemo}[code and float] |
| 3343 |
\begin{table} |
| 3344 |
\centering |
| 3345 |
\caption{Right-aligning under a heading.% |
| 3346 |
\label{tab:width:special}} |
| 3347 |
\settowidth{\mylength}{Long header} |
| 3348 |
\sisetup{ |
| 3349 |
table-alignment-mode = none , |
| 3350 |
table-column-width = \mylength , |
| 3351 |
table-number-alignment = right |
| 3352 |
} |
| 3353 |
\begin{tabular}{@{}S@{}} |
| 3354 |
\toprule |
| 3355 |
{Long header} \\ |
| 3356 |
\midrule |
| 3357 |
12.33 \\ |
| 3358 |
2 \\ |
| 3359 |
1234 \\ |
| 3360 |
\bottomrule |
| 3361 |
\end{tabular} |
| 3362 |
\end{table} |
| 3363 |
\end{LaTeXdemo} |
| 3364 |
|
| 3365 |
\DescribeOption{table-text-alignment} |
| 3366 |
\DescribeOption{table-alignment} |
| 3367 |
Cell contents which are not part of a number can be protected using braces, as |
| 3368 |
illustrated. Cells which contain no numerical data at all are aligned using the |
| 3369 |
setting specified by the \opt{table-text-alignment} option, which recognises |
| 3370 |
the values \opt{center}, \opt{left}, \opt{none} and \opt{right} |
| 3371 |
(Table~\ref{tab:S:text}). The setting \opt{none} is intended for use with |
| 3372 |
the package \pkg{tabularray}, which carries out its own alignment of textual |
| 3373 |
values. |
| 3374 |
\begin{LaTeXdemo}[code and float] |
| 3375 |
\begin{table} |
| 3376 |
\caption{Aligning text in \texttt{S} columns.% |
| 3377 |
\label{tab:S:text}} |
| 3378 |
\sisetup{table-format = 4.4} |
| 3379 |
\centering |
| 3380 |
\begin{tabular}{@{} |
| 3381 |
S |
| 3382 |
S[table-text-alignment = left] |
| 3383 |
S[table-text-alignment = right] |
| 3384 |
@{}} |
| 3385 |
\toprule |
| 3386 |
{Values} |
| 3387 |
& {Values} |
| 3388 |
& {Values} \\ |
| 3389 |
\midrule |
| 3390 |
992.435 & 992.435 & 992.435 \\ |
| 3391 |
7734.2344 & 7734.2344 & 7734.2344 \\ |
| 3392 |
56.7834 & 56.7834 & 56.7834 \\ |
| 3393 |
3,7462 & 3,7462 & 3,7462 \\ |
| 3394 |
\bottomrule |
| 3395 |
\end{tabular} |
| 3396 |
\end{table} |
| 3397 |
\end{LaTeXdemo} |
| 3398 |
|
| 3399 |
\DescribeOption{table-alignment} |
| 3400 |
The table alignment options \opt{table-number-alignment} and |
| 3401 |
\opt{table-text-alignment} can be set to the same value using the |
| 3402 |
\opt{table-alignment} option. This will set all three alignment options to the |
| 3403 |
same value (one of \opt{center}, \opt{right} or \opt{left}). |
| 3404 |
|
| 3405 |
\subsection{Locale options} |
| 3406 |
|
| 3407 |
\DescribeOption{locale} |
| 3408 |
\pkg{siunitx} allows the user to switch between the typographic conventions of |
| 3409 |
different (geographical) areas by using locales. Currently, the package is |
| 3410 |
supplied with configurations for locales \opt{UK}, \opt{US}, \opt{DE} |
| 3411 |
(Germany), \opt{IT} (Italian), \opt{PL} (Poland), \opt{FR} (French), \opt{SI} |
| 3412 |
(Slovene) and \opt{ZA} (South Africa). The \opt{locale} option is used to |
| 3413 |
switch to a particular locale. |
| 3414 |
\begin{LaTeXdemo} |
| 3415 |
\qty{1.234}{\metre}\\ |
| 3416 |
\qty[locale = DE]{6.789}{\metre} |
| 3417 |
\end{LaTeXdemo} |
| 3418 |
|
| 3419 |
\subsection{Preamble-only options} |
| 3420 |
|
| 3421 |
\DescribeOption{list-input-separator} |
| 3422 |
\DescribeOption{product-input-separator} |
| 3423 |
The separator between \emph{input} elements of lists (\cs{numlist}, |
| 3424 |
\cs{qtylist}) and products (\cs{numproduct}, \cs{qtyproduct}) can be adjusted |
| 3425 |
using the options \opt{list-input-separator} and \opt{product-input-separator}, |
| 3426 |
respectively. These are load-time only options as the separator here is part of |
| 3427 |
the \enquote{document interface} rather than part of the individual number(s). |
| 3428 |
The supplied value should be a \emph{single} marker. |
| 3429 |
|
| 3430 |
\DescribeOption{table-column-type} |
| 3431 |
The letter(s) used to create table columns can be adjusted using the |
| 3432 |
\opt{table-column-type} option. The standard setting is |S|, but one or more |
| 3433 |
letters may be used: these must be single tokens. For example, provided the |
| 3434 |
\pkg{numprint} package has not been loaded, the letter |n| could be used as |
| 3435 |
this would suggest a numerical column. |
| 3436 |
|
| 3437 |
\DescribeOption{disable-deprecated-commands} |
| 3438 |
\DescribeOption{disable-deprecated-options} |
| 3439 |
To allow users to require only interfaces from the current release, the options |
| 3440 |
\opt{disable-deprecated-options} and \opt{disable-deprecated-commands} are |
| 3441 |
available. Settings these to \opt{false} will disable options and document |
| 3442 |
commands that have been removed from version~\version{3}, respectively. |
| 3443 |
|
| 3444 |
\section{Significant new features updates} |
| 3445 |
|
| 3446 |
Here, a short reminder for users of new features added since the release of |
| 3447 |
version~\version{3} of the package is given. |
| 3448 |
|
| 3449 |
\subsection{Version~\version{3.1}} |
| 3450 |
|
| 3451 |
\begin{itemize} |
| 3452 |
\item Extend support for complex numbers to cover polar form including |
| 3453 |
new options to control output |
| 3454 |
\item Parse and format multiple uncertainties; new options added |
| 3455 |
to allow descriptions of each uncertainty |
| 3456 |
\item Customisation of text sub/superscript output |
| 3457 |
\item Selectable group size when dividing digits |
| 3458 |
\item Finer controls for \enquote{per mode} output |
| 3459 |
\item Support for negative zero values and controlled output for zero |
| 3460 |
values |
| 3461 |
\item Allow negative values to round to zero |
| 3462 |
\item Addition unit abbreviations for capacitance, power and magnetic |
| 3463 |
flux |
| 3464 |
\item Portuguese locale |
| 3465 |
\end{itemize} |
| 3466 |
|
| 3467 |
\subsection{Version~\version{3.2}} |
| 3468 |
|
| 3469 |
\begin{itemize} |
| 3470 |
\item \enquote{Threshold} approach to producing exponent notation: |
| 3471 |
similar to a calculator |
| 3472 |
\item Finer control of printing plus signs using new options to split |
| 3473 |
mantissa and exponent |
| 3474 |
\item Support for updated prefixes introduced by \acro{bipm} |
| 3475 |
\item Revised alignment of uncertainties in tabulars |
| 3476 |
\end{itemize} |
| 3477 |
|
| 3478 |
\subsection{Version~\version{3.3}} |
| 3479 |
|
| 3480 |
\begin{itemize} |
| 3481 |
\item Support for languages which need a begin as well as end phrase in |
| 3482 |
ranges, \foreign{e.g.}~Italian, was added; this includes appropriate |
| 3483 |
supporting options |
| 3484 |
\item Support for asymmetric uncertainties (tolerances) |
| 3485 |
\item Rounding extended to allow truncation (rounding down) for both |
| 3486 |
main values and when using the uncertainty part |
| 3487 |
\item Finer control of the appearance of brackets in ambiguous |
| 3488 |
output introduced by adding options for different contexts |
| 3489 |
\item Control of list and product input and output extended |
| 3490 |
\item Finer control of table alignment setup for bold values |
| 3491 |
\item New unit abbreviations for magnetic fields |
| 3492 |
\end{itemize} |
| 3493 |
|
| 3494 |
\subsection{Version~\version{3.4}} |
| 3495 |
|
| 3496 |
\begin{itemize} |
| 3497 |
\item Support uncertainties in seconds part of arc angles |
| 3498 |
\item Control creation of minute and second components on conversion of |
| 3499 |
integer angles to arc format |
| 3500 |
\item Ability to simplify \enquote{asymmetric} uncertainties with |
| 3501 |
equal components in both directions |
| 3502 |
\item Combination of all control for angle unit formatting into |
| 3503 |
\cs{degree}, \cs{arcminute} and \cs{arcsecond} unit macros, |
| 3504 |
with \opt{number-angle-product} deprecated |
| 3505 |
\item Support for more varied printing of complex numbers phases |
| 3506 |
\end{itemize} |
| 3507 |
|
| 3508 |
\subsection{Version~\version{3.5}} |
| 3509 |
|
| 3510 |
\begin{itemize} |
| 3511 |
\item New \cs{duration} command and supporting options |
| 3512 |
\item Support for extending the last group of numbers to avoid a dangling |
| 3513 |
digit |
| 3514 |
\item Options to suppress interfaces from version~\version{2} |
| 3515 |
\end{itemize} |
| 3516 |
|
| 3517 |
\section{Upgrading from version~\version{2}% |
| 3518 |
\label{sec:upgrading}} |
| 3519 |
|
| 3520 |
The package has been largely re-written internally between versions \version{2} |
| 3521 |
and \version{3}. A significant number of key--value settings have new, more |
| 3522 |
descriptive, names. Where possible, older names are mapped to newer ones |
| 3523 |
internally: you will be warned in the log if this is the case. |
| 3524 |
|
| 3525 |
It is possible to use the \LaTeXe{} kernel mechanism to load the last |
| 3526 |
version~\version{2} release for documents that cannot be successfully processed |
| 3527 |
using version~\version{3}. This can be achieved using |
| 3528 |
\begin{LaTeXdemo}[code only] |
| 3529 |
\usepackage{siunitx}[=2021-04-09] |
| 3530 |
\end{LaTeXdemo} |
| 3531 |
or |
| 3532 |
\begin{LaTeXdemo}[code only] |
| 3533 |
\usepackage{siunitx}[=v2] |
| 3534 |
\end{LaTeXdemo} |
| 3535 |
This approach will work with older systems which still have version~\version{2} |
| 3536 |
installed, meaning that you can reliably use it to work between systems with |
| 3537 |
different versions of \pkg{siunitx}. |
| 3538 |
|
| 3539 |
\begin{function}{\SI, \SIlist, \SIrange, \si} |
| 3540 |
In version~\version{3}, the document commands have been revised to be more |
| 3541 |
descriptive. As such, the commands \cs{SI}, \cs{SIlist}, \cs{SIrange} and |
| 3542 |
\cs{si} remain available but are not recommended for use in new documents. |
| 3543 |
Use the new \cs{qty\ldots} commands instead: they are clearer and in some |
| 3544 |
cases very slightly faster. |
| 3545 |
\end{function} |
| 3546 |
|
| 3547 |
Some changes have been made to the semantics of commands or options. Most |
| 3548 |
notably |
| 3549 |
\begin{itemize} |
| 3550 |
\item prefixes cannot now be given without units; |
| 3551 |
\item prefixes can only be interconverted with numbers as part |
| 3552 |
of a quantity, not as stand-alone units. |
| 3553 |
\end{itemize} |
| 3554 |
See Section~\ref{sec:hint:prefixes} for how to work with the new approach |
| 3555 |
if you want to print prefix information. |
| 3556 |
|
| 3557 |
The font control system has been completely re-written for version~\version{3}. |
| 3558 |
The method used is entirely different from version~\version{2}. Emulation is |
| 3559 |
therefore not provided for all outcomes: if you need non-standard font |
| 3560 |
settings, you will need to adjust your source. See Section~\ref{sec:print} for |
| 3561 |
more details on the options available in this area. |
| 3562 |
|
| 3563 |
The input approach for version~\version{3} is slightly more structured and |
| 3564 |
restricted than for version~\version{2}. As well as the updated names for |
| 3565 |
document commands, this means that |
| 3566 |
\begin{itemize} |
| 3567 |
\item Products of numbers must now be given using the dedicated |
| 3568 |
\cs{numproduct} and \cs{qtyproduct} commands; |
| 3569 |
\item Quotients of numbers are only supported as literals; |
| 3570 |
\item Complex values need to be given using the dedicated command |
| 3571 |
\cs{complexnum}. |
| 3572 |
\end{itemize} |
| 3573 |
The option \opt{round-integer-to-decimal = false} has been removed, and whilst |
| 3574 |
there is not a direct replacement, users are likely to find that \opt{round-pad |
| 3575 |
= false} offers the desired outcome. |
| 3576 |
|
| 3577 |
A new approach has been taken to providing non-Latin symbols for use in |
| 3578 |
units: these are now handled directly where needed, for example in the |
| 3579 |
definition of the \cs{micro} prefix. |
| 3580 |
|
| 3581 |
Translation of fixed strings is now carried out using the \pkg{translations} |
| 3582 |
package. If you have manually set up translations in version~\version{2} using |
| 3583 |
\pkg{translator}, you will need to load it manually. |
| 3584 |
|
| 3585 |
The letter used for a numerical tabular column can now be selected by the |
| 3586 |
user: the letter |S| has been retained as the standard interface. The unit |
| 3587 |
column (|s|) has been removed from this release. It can be emulated using |
| 3588 |
the \pkg{collcell} package, for example |
| 3589 |
\begin{LaTeXdemo}[code only] |
| 3590 |
\usepackage{collcell} |
| 3591 |
\newcolumntype{s}{>{\collectcell\unit}c<{\endcollectcell}} |
| 3592 |
\end{LaTeXdemo} |
| 3593 |
or |
| 3594 |
\begin{LaTeXdemo}[code only] |
| 3595 |
\usepackage{collcell} |
| 3596 |
\newcolumntype{s}{>{\collectcell\si}c<{\endcollectcell}} |
| 3597 |
\end{LaTeXdemo} |
| 3598 |
|
| 3599 |
If you are using \opt{table-column-width} to have fixed-width columns, you |
| 3600 |
also now need \opt{table-fixed-width} to set this option active. |
| 3601 |
|
| 3602 |
Direct support for loading a local configuration file, \texttt{siunitx.cfg}, |
| 3603 |
has been removed. However, the approach described in |
| 3604 |
Section~\ref{sec:hint:config} may be used to achieve the same effect with the |
| 3605 |
additions more clearly shown in document sources. |
| 3606 |
|
| 3607 |
The command \cs{SendSettingsToPgf} is deprecated, and should be replaced |
| 3608 |
simply by setting the appropriate \cs{pgfkeys} in parallel to \cs{sisetup}. |
| 3609 |
|
| 3610 |
\section{Unit changes made by \acro{BIPM}% |
| 3611 |
\label{sec:BIPM8}} |
| 3612 |
|
| 3613 |
In addition to the changes in the \pkg{siunitx} package described in |
| 3614 |
Section~\ref{sec:upgrading}, there are changes in the units defined by the |
| 3615 |
\acro{BIPM} in the 9th Edition of the \acro{SI} Brochure which are reflected |
| 3616 |
here. There are two major areas of change. |
| 3617 |
|
| 3618 |
The first is in respect of units accepted for use with \acro{SI} units. In the |
| 3619 |
8th Edition of the \acro{SI} Brochure, the following units were listed as |
| 3620 |
accepted for use in specialist fields |
| 3621 |
\begin{itemize} |
| 3622 |
\item ångström (\cs{angstrom}) |
| 3623 |
\item bar (\cs{bar}) |
| 3624 |
\item barn (\cs{barn}) |
| 3625 |
\item knot (\cs{knot}) |
| 3626 |
\item millimetre of mercury (\cs{mmHg}) |
| 3627 |
\item nautical mile (\cs{nauticalmile}) |
| 3628 |
\end{itemize} |
| 3629 |
These are no longer listed in the 9th Edition, and so are deprecated as |
| 3630 |
pre-defined units by \pkg{siunitx}. These units will issue a warning on first |
| 3631 |
use, and users should add their own definitions to the start of their sources |
| 3632 |
to avoid this. |
| 3633 |
|
| 3634 |
Secondly, the move to a new definition of base units means that the table of |
| 3635 |
units determined experimentally has been removed from the \acro{SI} Brochure. |
| 3636 |
This covers the following units defined by \pkg{siunitx} in previous releases |
| 3637 |
\begin{itemize} |
| 3638 |
\item \cs{bohr} |
| 3639 |
\item \cs{clight} |
| 3640 |
\item \cs{electronmass} |
| 3641 |
\item \cs{elementarycharge} |
| 3642 |
\item \cs{hartree} |
| 3643 |
\item \cs{planckbar} |
| 3644 |
\end{itemize} |
| 3645 |
These are also deprecated in \pkg{siunitx} and users should provide their own |
| 3646 |
definitions. |
| 3647 |
|
| 3648 |
In addition to these two major blocks, the unit \cs{atomicmassunit} has similar |
| 3649 |
deprecated status: this was listed as with experimentally-determined units in |
| 3650 |
the 8th Edition of the \acro{SI} Brochure but is equivalent to the dalton, a |
| 3651 |
unit which remains accepted. |
| 3652 |
|
| 3653 |
\section{Localisation} |
| 3654 |
|
| 3655 |
The \pkg{translations} package provides a structured framework for |
| 3656 |
localisation of words and phrases. In particular, it offers the |
| 3657 |
\cs{GetTranslation} macro, which will provide appropriate translations based |
| 3658 |
on the current \pkg{babel} or \pkg{polyglossia} language setting. |
| 3659 |
|
| 3660 |
If \pkg{translations} is available, \pkg{siunitx} will load it and alter the |
| 3661 |
standard settings for the \opt{list-final-separator} and \opt{range-phrase} |
| 3662 |
options to read: |
| 3663 |
\begin{LaTeXdemo}[code only] |
| 3664 |
\sisetup{ |
| 3665 |
list-final-separator = { \GetTranslation{and} }, |
| 3666 |
list-pair-separator = { \GetTranslation{and} }, |
| 3667 |
range-phrase = { \GetTranslation{to (numerical range)} }, |
| 3668 |
} |
| 3669 |
\end{LaTeXdemo} |
| 3670 |
The setting for \opt{range-open-phrase} is also adjusted to support a setting |
| 3671 |
for \opt{range-open-phrase}: this requires some conditionals so is more |
| 3672 |
complex. |
| 3673 |
|
| 3674 |
If the current language is known to the \pkg{translations} package then the |
| 3675 |
result will be localised text. The preamble for this manual loads English, |
| 3676 |
French, German, Italian, Polish, Spanish, Catalan, Portuguese and Brazilian as |
| 3677 |
options, and also loads the \pkg{babel} package: |
| 3678 |
\begin{LaTeXdemo} |
| 3679 |
% In English by default |
| 3680 |
\numlist{1;2;3} \\ |
| 3681 |
\numrange{1}{10} \\ |
| 3682 |
\selectlanguage{french}% |
| 3683 |
\numlist{1;2;3} \\ |
| 3684 |
\numrange{1}{10} \\ |
| 3685 |
\selectlanguage{german}% |
| 3686 |
\numlist{1;2;3} \\ |
| 3687 |
\numrange{1}{10} \\ |
| 3688 |
\selectlanguage{italian}% |
| 3689 |
\numlist{1;2;3} \\ |
| 3690 |
\numrange{1}{10} \\ |
| 3691 |
\selectlanguage{polish}% |
| 3692 |
\numlist{1;2;3} \\ |
| 3693 |
\numrange{1}{10} \\ |
| 3694 |
\selectlanguage{spanish}% |
| 3695 |
\numlist{1;2;3} \\ |
| 3696 |
\numrange{1}{10} \\ |
| 3697 |
\selectlanguage{catalan}% |
| 3698 |
\numlist{1;2;3} \\ |
| 3699 |
\numrange{1}{10} \\ |
| 3700 |
\selectlanguage{portuguese}% |
| 3701 |
\numlist{1;2;3} \\ |
| 3702 |
\numrange{1}{10} \\ |
| 3703 |
\selectlanguage{brazilian}% |
| 3704 |
\numlist{1;2;3} \\ |
| 3705 |
\numrange{1}{10} |
| 3706 |
\end{LaTeXdemo} |
| 3707 |
|
| 3708 |
\section{Compatibility with other packages} |
| 3709 |
|
| 3710 |
In general, \pkg{siunitx} should be usable with other packages without |
| 3711 |
interference. |
| 3712 |
|
| 3713 |
When the \pkg{physics} package is loaded before \pkg{siunitx}, the command |
| 3714 |
\cs{qty} is not defined. Users may use the version~\version{2} command \cs{SI}, |
| 3715 |
which can be used as a drop-in replacement for \cs{qty}. Alternatively, if the |
| 3716 |
\pkg{siunitx} definition is preferred, you may use |
| 3717 |
\begin{LaTeXdemo}[code only] |
| 3718 |
\AtBeginDocument{\RenewCommandCopy\qty\SI} |
| 3719 |
\end{LaTeXdemo} |
| 3720 |
and use the longer name \cs{quantity} to access the functionality of the |
| 3721 |
\pkg{physics} package. |
| 3722 |
|
| 3723 |
\section{Hints for using \pkg{siunitx}} |
| 3724 |
|
| 3725 |
\subsection{Problematic font encodings% |
| 3726 |
\label{sec:hint:encoding}} |
| 3727 |
|
| 3728 |
The standard settings in \pkg{siunitx} assume that \enquote{sensible} input and |
| 3729 |
font encoding values prevail. The input encoding is assumed to be \acro{UTF-8} |
| 3730 |
in all cases. With pdf\LaTeX{}, the font encoding should be \texttt{T1}, |
| 3731 |
whereas for Xe\LaTeX{} and Lua\LaTeX{}, \texttt{TU} (Unicode font encoding) is |
| 3732 |
expected. |
| 3733 |
|
| 3734 |
Some packages, for example \pkg{newtxtext} or \pkg{stix2}, either force |
| 3735 |
\texttt{T1} or do not anticipate \texttt{TU} correctly with Xe\LaTeX{} and |
| 3736 |
Lua\LaTeX{}. In these cases, the symbols used by \pkg{siunitx} may be |
| 3737 |
incorrect. If correcting the font encoding is not possible, you will need to |
| 3738 |
re-declare the relevant units using symbol definitions which account for this |
| 3739 |
non-standard setup. |
| 3740 |
|
| 3741 |
\subsection{Adjusting \cs{litre} and \cs{liter}% |
| 3742 |
\label{sec:hint:litre}} |
| 3743 |
|
| 3744 |
As detailed earlier, the unit macros \cs{litre} and \cs{liter} are both |
| 3745 |
available for litres. With the standard settings, \cs{liter} is defined as |
| 3746 |
\begin{LaTeXdemo}[code only] |
| 3747 |
\DeclareSIUnit\liter{\litre} |
| 3748 |
\end{LaTeXdemo} |
| 3749 |
meaning that \cs{litre} is the \enquote{canonical} unit. This follows the same |
| 3750 |
relationship as exists between \cs{metre} and \cs{meter}. |
| 3751 |
|
| 3752 |
In contrast to metres, however, there is more likelihood of users wishing to |
| 3753 |
adjust the appearance of litres: both \enquote{\unit{l}} and \enquote{\unit{L}} |
| 3754 |
are commonly used. The recommended approach to adjustment is to re-declare |
| 3755 |
the \cs{litre} macro, as \cs{liter} will follow automatically. |
| 3756 |
\begin{LaTeXdemo}[code only] |
| 3757 |
\DeclareSIUnit\litre{l} |
| 3758 |
\end{LaTeXdemo} |
| 3759 |
|
| 3760 |
\subsection{Ensuring text or math output% |
| 3761 |
\label{sec:hint:text-math}} |
| 3762 |
|
| 3763 |
The macros \cs{ensuremath} and \cs{text} should be used to ensure that a |
| 3764 |
particular item is always printed in the desired mode. Some mathematical output |
| 3765 |
does not work well in \cs{mathrm} (the font setting used by \pkg{siunitx} for |
| 3766 |
printing units). The easiest way to solve this is to use the construction |
| 3767 |
"\text{\ensuremath{...}}", which will print the material in the standard |
| 3768 |
mathematics font without affecting the rest of the output. In some cases, |
| 3769 |
simply forcing \cs{mathnormal} will suffice, but this is less reliable with |
| 3770 |
non-Latin characters. |
| 3771 |
|
| 3772 |
\subsection{Including a literal hyphen inside \cs{text}% |
| 3773 |
\label{sec:hint:hyphen-minus}} |
| 3774 |
|
| 3775 |
In most cases, a "-" character inside \cs{text} will represent a minus. The |
| 3776 |
package will therefore replace it with \cs{textminus}. However, this may be |
| 3777 |
problematic if you want a hyphen, or if you are using "-" in a piece of \TeX{} |
| 3778 |
syntax. You can prevent this by using a second set of braces |
| 3779 |
\begin{LaTeXdemo}[code only] |
| 3780 |
\DeclareSIUnit\electronvolt{\text{{e\kern -0.1em V}}} |
| 3781 |
\end{LaTeXdemo} |
| 3782 |
or by defining a protected command that will yield a hyphen on typesetting |
| 3783 |
\begin{LaTeXdemo}[code only] |
| 3784 |
\usepackage{etoolbox} |
| 3785 |
\newrobustcmd*\hyphenminus{-} |
| 3786 |
\DeclareSIUnit\electronvolt{\text{e\kern \hyphenminus0.1em V}} |
| 3787 |
\end{LaTeXdemo} |
| 3788 |
|
| 3789 |
\subsection{Expanding content in tables% |
| 3790 |
\label{sec:hint:expanding}} |
| 3791 |
|
| 3792 |
When processing tables, \pkg{siunitx} will expand anything stored inside a |
| 3793 |
macro, unless it is long or protected. \LaTeXe{} robust commands are also |
| 3794 |
detected and are not expanded (Table~\ref{tab:xmpl:macro}). Values which would |
| 3795 |
otherwise be expanded can be protected by wrapping them in a set of braces. As |
| 3796 |
\TeX{} itself will expand the first token in a table cell before \pkg{siunitx} |
| 3797 |
can act on it, using the \eTeX{} protected mechanism is the recommended course |
| 3798 |
of action to prevent expansion of macros in table cells. (As is shown in the |
| 3799 |
table, \TeX's expansion of \LaTeXe{} robust commands can lead to unexpected |
| 3800 |
results.) |
| 3801 |
\begin{LaTeXdemo}[code and float] |
| 3802 |
\begin{table} |
| 3803 |
\caption{Values as macros in \texttt{S} columns.% |
| 3804 |
\label{tab:xmpl:macro}} |
| 3805 |
\newcommand*\myvaluea{1234} |
| 3806 |
\newcommand\myvalueb{1234} |
| 3807 |
\DeclareRobustCommand*\myvaluec{1234} |
| 3808 |
\protected\def\myvalued{1234} |
| 3809 |
\begin{tabular}{@{}S@{}} |
| 3810 |
\toprule |
| 3811 |
{Some Values} \\ |
| 3812 |
\midrule |
| 3813 |
\myvaluea 8.8 \myvaluea \\ % Both expanded |
| 3814 |
\myvalueb 8.8 \myvalueb \\ % First expanded by TeX |
| 3815 |
% to numbers |
| 3816 |
\myvaluec 8.8 \myvaluec \\ % First expanded by TeX |
| 3817 |
% but not to numbers! |
| 3818 |
\myvalued 8.8 \myvalued \\ % Neither expanded |
| 3819 |
{\myvaluea\ 8.8 \myvaluea} \\ % Neither expanded |
| 3820 |
\bottomrule |
| 3821 |
\end{tabular} |
| 3822 |
\end{table} |
| 3823 |
\end{LaTeXdemo} |
| 3824 |
|
| 3825 |
It is possible to use calculated values in tables. For this to work, the |
| 3826 |
calculation must take place before attempting to parse the number (the parser |
| 3827 |
cannot \enquote{know} all of the possible values inside an expression). This is |
| 3828 |
most conveniently handled using the \pkg{xfp} package, which is distributed as |
| 3829 |
part of the required support for \pkg{siunitx}. The general approach is |
| 3830 |
illustrated in Table~\ref{tab:xmpl:calc} |
| 3831 |
\begin{LaTeXdemo}[code and float] |
| 3832 |
\begin{table} |
| 3833 |
\caption{Calculated values.% |
| 3834 |
\label{tab:xmpl:calc}} |
| 3835 |
\newcommand{\valuea}{66.7012} |
| 3836 |
\newcommand{\valueb}{66.0212} |
| 3837 |
\newcommand{\valuec}{64.9026} |
| 3838 |
\begin{tabular}{ |
| 3839 |
@{} |
| 3840 |
S[table-format = 2.4] |
| 3841 |
S[table-format = 3.4] |
| 3842 |
@{} |
| 3843 |
} |
| 3844 |
\toprule |
| 3845 |
{Value} & {Doubled} \\ |
| 3846 |
\midrule |
| 3847 |
\valuea & \fpeval{\valuea * 2} \\ |
| 3848 |
\valueb & \fpeval{\valueb * 2} \\ |
| 3849 |
\valuec & \fpeval{\valuec * 2} \\ |
| 3850 |
\bottomrule |
| 3851 |
\end{tabular} |
| 3852 |
\end{table} |
| 3853 |
\end{LaTeXdemo} |
| 3854 |
|
| 3855 |
A more sophisticated approach is to generate the rows themselves from a |
| 3856 |
database: this is illustrated in Section~\ref{sec:hint:datatool}. |
| 3857 |
|
| 3858 |
\subsection{Using \pkg{siunitx} with \pkg{datatool}% |
| 3859 |
\label{sec:hint:datatool}} |
| 3860 |
|
| 3861 |
As illustrated in Table~\ref{tab:xmpl:calc}, \pkg{siunitx} can be used to |
| 3862 |
typeset data stored using \pkg{datatool}. For quickly displaying the contents |
| 3863 |
of tables, \pkg{datatool} offers the \cs{DTLshowtable} macro. This will only |
| 3864 |
work with \texttt{S} columns if number parsing is turned off |
| 3865 |
(Table~\ref{tab:xmpl:datatool}). |
| 3866 |
\begin{LaTeXdemo}[code and float] |
| 3867 |
\DTLnewdb{moredata} |
| 3868 |
\DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{ 6.7012} |
| 3869 |
\DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{66.0212} |
| 3870 |
\DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{64.902 } |
| 3871 |
\begin{table} |
| 3872 |
\caption{Displaying a \textsf{datatool} table.% |
| 3873 |
\label{tab:xmpl:datatool}} |
| 3874 |
\sisetup{parse-numbers= false, table-format = 2.4} |
| 3875 |
\renewcommand*\dtlrealalign{S} |
| 3876 |
\DTLdisplaydb{moredata} |
| 3877 |
\end{table} |
| 3878 |
\end{LaTeXdemo} |
| 3879 |
|
| 3880 |
The \pkg{datatool} package may also be used to create on-the-fly tables using |
| 3881 |
calculations. For example, the demonstration in Table~\ref{tab:xmpl:calc} may |
| 3882 |
be achieved without needing to write out each row, as shown in |
| 3883 |
Table~\ref{tab:xmpl:datatool-calc}. An extra column is used to contain the |
| 3884 |
calculations in this case. |
| 3885 |
\begin{LaTeXdemo}[code and float] |
| 3886 |
\begin{table} |
| 3887 |
\caption{Calculated values using \pkg{datatool}.% |
| 3888 |
\label{tab:xmpl:datatool-calc}} |
| 3889 |
\DTLnewdb{data} |
| 3890 |
\DTLnewrow{data}\DTLnewdbentry{data}{value}{66.7012} |
| 3891 |
\DTLnewrow{data}\DTLnewdbentry{data}{value}{66.0212} |
| 3892 |
\DTLnewrow{data}\DTLnewdbentry{data}{value}{64.9026} |
| 3893 |
\begin{tabular}{ |
| 3894 |
@{} |
| 3895 |
S[table-format = 2.4] |
| 3896 |
S[table-format = 3.4] |
| 3897 |
@{}l |
| 3898 |
@{} |
| 3899 |
} |
| 3900 |
\toprule |
| 3901 |
{Value} & {Doubled} & |
| 3902 |
\DTLforeach{data}{\myvalue=value}{% |
| 3903 |
\DTLiffirstrow {\\ \midrule}{\\}% |
| 3904 |
\myvalue & % First column |
| 3905 |
\fpeval{\myvalue * 2} % second column |
| 3906 |
& }\\ |
| 3907 |
\bottomrule |
| 3908 |
\end{tabular} |
| 3909 |
\end{table} |
| 3910 |
\end{LaTeXdemo} |
| 3911 |
|
| 3912 |
\subsection{Using units in section headings and bookmarks% |
| 3913 |
\label{sec:hint:bookmarks}} |
| 3914 |
|
| 3915 |
The \pkg{siunitx} code is designed to work correctly with functions in |
| 3916 |
headings. They will print correctly in headings and in the table of contents. |
| 3917 |
As illustrated here, the standard behavior is to ignore font changes. When the |
| 3918 |
\pkg{hyperref} package is loaded, the functions automatically \enquote{degrade |
| 3919 |
gracefully} to produce useful information in \acro{pdf} bookmarks. If you want |
| 3920 |
more control over the bookmark text, use the \cs{texorpdfstring} function from |
| 3921 |
\pkg{hyperref}, for example: |
| 3922 |
\begin{LaTeXdemo}[code only] |
| 3923 |
\section{Some text |
| 3924 |
\texorpdfstring |
| 3925 |
{\unit{\joule\per\mole\per\kelvin}} |
| 3926 |
{J mol-1 K-1}% |
| 3927 |
} |
| 3928 |
\end{LaTeXdemo} |
| 3929 |
|
| 3930 |
You may find it useful to load \pkg{hyperref} with the \opt{unicode} option, |
| 3931 |
as this will allow \unit{\ohm} to appear in bookmarks. Without the option, |
| 3932 |
the encoding used by \pkg{hyperref} does not support this symbol. |
| 3933 |
|
| 3934 |
\subsection{A left-aligned column visually centered under a heading% |
| 3935 |
\label{sec:hint:left-column}} |
| 3936 |
|
| 3937 |
When you have a column of non-related numbers, the usual advice is to make |
| 3938 |
these left-aligned and then center the resulting column under the heading. With |
| 3939 |
the \pkg{dcolumn} package, that would be done with something like |
| 3940 |
|D{x}{}{5.0}|. This is something of an abuse of the nature of a number, but can |
| 3941 |
also be done using \pkg{siunitx} (Table~\ref{tbl:xmpl:unrel}). |
| 3942 |
\begin{LaTeXdemo}[code and float] |
| 3943 |
\begin{table} |
| 3944 |
\caption{Formatting unrelated numbers.% |
| 3945 |
\label{tbl:xmpl:unrel}} |
| 3946 |
\centering |
| 3947 |
\begin{tabular} |
| 3948 |
{ |
| 3949 |
@{} |
| 3950 |
S[ |
| 3951 |
table-format = 5.0, |
| 3952 |
parse-numbers = false, |
| 3953 |
input-decimal-markers = x |
| 3954 |
] |
| 3955 |
@{} |
| 3956 |
} |
| 3957 |
\toprule |
| 3958 |
\multicolumn{1}{@{}c@{}}{Header} \\ |
| 3959 |
\midrule |
| 3960 |
120 \\ |
| 3961 |
12.3 \\ |
| 3962 |
12340 \\ |
| 3963 |
12.02 \\ |
| 3964 |
123 \\ |
| 3965 |
1 \\ |
| 3966 |
\bottomrule |
| 3967 |
\end{tabular} |
| 3968 |
\end{table} |
| 3969 |
\end{LaTeXdemo} |
| 3970 |
|
| 3971 |
\subsection{Regression tables% |
| 3972 |
\label{sec:hint:regression}} |
| 3973 |
|
| 3974 |
In some subject areas, it is common to present regression values or similar, |
| 3975 |
which feature an uncertainty value in parenthesis on the line below the main |
| 3976 |
value. As these are separate cells, they cannot be entered using \pkg{siunitx} |
| 3977 |
in one value. There are a couple of ways of formatting them using the package, |
| 3978 |
depending on whether the values also need to be parsed. |
| 3979 |
|
| 3980 |
Where parsing is not required, the most straight-forward method is available: |
| 3981 |
provide a model format allowing space for an extra \enquote{digit} at each end, |
| 3982 |
which will then allow for the parenthesis. If a sign is applied to the number, |
| 3983 |
it may not be necessary to add a \enquote{digit} for the leading bracket. If |
| 3984 |
parsing is also required, this approach cannot be employed. Instead, the |
| 3985 |
parsing needs to be adjusted such that |(| and |)| are not treated as part of |
| 3986 |
the number, and \opt{table-align-text-before} is set to |false| such that these |
| 3987 |
will be placed next to the numerical part. These methods are illustrated in |
| 3988 |
Table~\ref{tab:regression}. |
| 3989 |
|
| 3990 |
\begin{LaTeXdemo}[code and float] |
| 3991 |
\begin{table} |
| 3992 |
\caption{Regression tables% |
| 3993 |
\label{tab:regression} |
| 3994 |
} |
| 3995 |
\begin{tabular} |
| 3996 |
{ |
| 3997 |
@{} |
| 3998 |
S[table-format = 2.4, parse-numbers = false] |
| 3999 |
S[table-format = +1.4, parse-numbers = false] |
| 4000 |
S[ |
| 4001 |
input-open-uncertainty = , |
| 4002 |
input-close-uncertainty = , |
| 4003 |
minimum-decimal-digits = 3, % ( |
| 4004 |
table-format = +1.3), |
| 4005 |
table-align-text-before = false |
| 4006 |
] |
| 4007 |
@{} |
| 4008 |
} |
| 4009 |
\toprule |
| 4010 |
{Header} &{Header} & {Header} \\ |
| 4011 |
\midrule |
| 4012 |
1.234 & -1.234 & -1.23 \\ |
| 4013 |
(0.053) & (0.053) & (0.053) \\ |
| 4014 |
\bottomrule |
| 4015 |
\end{tabular} |
| 4016 |
\end{table} |
| 4017 |
\end{LaTeXdemo} |
| 4018 |
|
| 4019 |
\subsection{Maximising performance% |
| 4020 |
\label{sec:hint:performance}} |
| 4021 |
|
| 4022 |
Both the number and unit parsers require significant effort in terms of \TeX{} |
| 4023 |
programming. For input that does not require such processing, the maximum |
| 4024 |
performance for \pkg{siunitx} can therefore be obtained by turning off both |
| 4025 |
systems: |
| 4026 |
\begin{LaTeXdemo} |
| 4027 |
\qty{7.3}{\Hz} \\ |
| 4028 |
\qty[parse-units = false]{7.3}{\Hz} \\ |
| 4029 |
\qty[ |
| 4030 |
parse-numbers = false, |
| 4031 |
parse-units = false |
| 4032 |
]{7.3}{\Hz} |
| 4033 |
\end{LaTeXdemo} |
| 4034 |
|
| 4035 |
For tables, any settings that can be given before the table are only parsed once, |
| 4036 |
whereas given in the optional argument to |S| they are read in every cell. As such, |
| 4037 |
you should favour |
| 4038 |
\begin{LaTeXdemo}[code only] |
| 4039 |
\begin{table} |
| 4040 |
\sisetup{...} |
| 4041 |
\begin{tabular}{S} |
| 4042 |
... |
| 4043 |
\end{LaTeXdemo} |
| 4044 |
for common settings. |
| 4045 |
|
| 4046 |
\subsection{Special considerations for the \cs{kWh} unit% |
| 4047 |
\label{sec:hint:kWh}} |
| 4048 |
|
| 4049 |
The standard settings provide the \cs{kWh} unit set up with no spacing between |
| 4050 |
the \enquote{\unit{\kilo\watt}} and the \enquote{\unit{\hour}} unit to give |
| 4051 |
\enquote{\unit{\kWh}}. However, this only applies when the unit is given on its |
| 4052 |
own: combinations will follow the normal rules |
| 4053 |
\begin{LaTeXdemo} |
| 4054 |
\unit{\kWh} \\ |
| 4055 |
\unit{\kWh\per\metre} |
| 4056 |
\end{LaTeXdemo} |
| 4057 |
This is because the unit \cs{kWh} is defined so that it can still be varied by |
| 4058 |
altering \cs{kilo}, \cs{watt} and \cs{hour}, and so that the prefix can still |
| 4059 |
be turned into a number. However, some users may prefer to have a non-flexible |
| 4060 |
macro which never adds a space. This can be achieved by redefining \cs{kWh} |
| 4061 |
with \cs{DeclareSIUnit}, by added an alternative definition |
| 4062 |
\begin{LaTeXdemo}[code only] |
| 4063 |
\DeclareSIUnit\kWh{kWh} |
| 4064 |
\DeclareSIUnit\KWH{kWh} |
| 4065 |
\end{LaTeXdemo} |
| 4066 |
or of course by using literal unit input. |
| 4067 |
\begin{LaTeXdemo} |
| 4068 |
\unit{\KWH\per\metre}\\ |
| 4069 |
\unit{kWh.m^{-1}} |
| 4070 |
\end{LaTeXdemo} |
| 4071 |
|
| 4072 |
Another point to notice is that the \cs{per} macro applies to the next unit, |
| 4073 |
and not an entire unit combination. Thus in |
| 4074 |
\begin{LaTeXdemo} |
| 4075 |
\unit{\candela\per\kWh} |
| 4076 |
\end{LaTeXdemo} |
| 4077 |
\cs{per} applies to the watts but not to the hours. In this case, the units |
| 4078 |
need to be written out in full or the \opt{sticky-per} option should be used. |
| 4079 |
\begin{LaTeXdemo} |
| 4080 |
\unit{\candela\per\kilo\watt\per\hour} \\ |
| 4081 |
\unit[sticky-per]{\candela\per\kWh} |
| 4082 |
\end{LaTeXdemo} |
| 4083 |
|
| 4084 |
\subsection{Prefixes and small angles% |
| 4085 |
\label{sec:hint:prefixangle}} |
| 4086 |
|
| 4087 |
Typically, prefixes are not applied to the standard symbols for angles: as |
| 4088 |
such, the \cs{ang} command is not subject to the \opt{prefix-mode} option. In |
| 4089 |
some areas, very small angles are given in arcseconds using the symbol |
| 4090 |
\unit{as}. To apply prefixes in this case, use the \cs{qty} command rather than |
| 4091 |
\cs{ang}. |
| 4092 |
\begin{LaTeXdemo} |
| 4093 |
% In the preamble |
| 4094 |
% \DeclareSIUnit\arcsecond{as} |
| 4095 |
\qty{1e-3}{\arcsecond} \\ |
| 4096 |
\qty[prefix-mode = combine-exponent]{1e-3}{\arcsecond} |
| 4097 |
\end{LaTeXdemo} |
| 4098 |
|
| 4099 |
\subsection{Creating a column with numbers and units% |
| 4100 |
\label{sec:hint:mixed}} |
| 4101 |
|
| 4102 |
Usually, numbers in a table should be given with the units in the column |
| 4103 |
heading. However, there are cases where a series of data are best presented in |
| 4104 |
a table but have different units. There are two ways to do this |
| 4105 |
(Table~\ref{tab:xmpl:mixed}). The first is to place the units in the first |
| 4106 |
column of the table, which makes sense if there are several related items in |
| 4107 |
the table. The second method is to generate two columns, one for numbers and a |
| 4108 |
second for units, and then to format these to give the visual effect of a |
| 4109 |
single column. The later effect is most appropriate when only one set of |
| 4110 |
numbers are presented in a table. This method requires cell content is |
| 4111 |
collected, easiest to do using the \pkg{collcell} package. |
| 4112 |
\begin{LaTeXdemo}[code and float] |
| 4113 |
\begin{table} |
| 4114 |
\caption{Tables where numbers have different units.% |
| 4115 |
\label{tab:xmpl:mixed}} |
| 4116 |
\hspace{\fill}% |
| 4117 |
\begin{tabular} |
| 4118 |
{ |
| 4119 |
@{} |
| 4120 |
>{$}l<{$} |
| 4121 |
S[table-format = 3.3(1)] |
| 4122 |
S[table-format = 3.3(1)] |
| 4123 |
@{} |
| 4124 |
} |
| 4125 |
\toprule |
| 4126 |
& {One} & {Two} \\ |
| 4127 |
\midrule |
| 4128 |
a / \unit{\pm} & 123.4(2) & 567.8(4) \\ |
| 4129 |
\beta / \unit{\degree} & 90.34(4) & 104.45(5) \\ |
| 4130 |
\mu / \unit{\per\mm} & 0.532 & 0.894 \\ |
| 4131 |
\bottomrule |
| 4132 |
\end{tabular} |
| 4133 |
\hspace{\fill}% |
| 4134 |
\begin{tabular} |
| 4135 |
{ |
| 4136 |
@{} |
| 4137 |
S[table-format=1.3]@{\,} |
| 4138 |
>{\collectcell\unit}l<{\endcollectcell} |
| 4139 |
@{} |
| 4140 |
} |
| 4141 |
\toprule |
| 4142 |
\multicolumn{2}{@{}c}{Heading} \\ |
| 4143 |
\midrule |
| 4144 |
1.234 & \metre \\ |
| 4145 |
0.835 & \candela \\ |
| 4146 |
4.23 & \joule\per\mole \\ |
| 4147 |
\bottomrule |
| 4148 |
\end{tabular} |
| 4149 |
\hspace{\fill}% |
| 4150 |
\end{table} |
| 4151 |
\end{LaTeXdemo} |
| 4152 |
|
| 4153 |
\subsection{Tables with heading rows% |
| 4154 |
\label{sec:hint:heading}} |
| 4155 |
|
| 4156 |
A common format for tables is to make the heading row visually distinct using a |
| 4157 |
background color and bold text. If numbers appear in such a heading row within |
| 4158 |
an \texttt{S} column then getting the appearance right can be challenging. The |
| 4159 |
best approach is to make the \cs{bfseries} macro \enquote{robust} (as |
| 4160 |
demonstrated in Section~\ref{sec:hint:expanding}), then to use this macro to |
| 4161 |
make the heading cells bold. This approach is illustrated in |
| 4162 |
Table~\ref{tab:xmpl:headers}, along with the use of \cs{rowcolor} to provide a |
| 4163 |
background color. Some typical \LaTeX{} font arrangements use a wider |
| 4164 |
(extended) width for the bold font compared with the normal font. This will |
| 4165 |
disturb the alignment if the \opt{table-format} is not symmetrical. For these |
| 4166 |
cases, the \opt{table-model-setup} key may be used to apply the wider font to |
| 4167 |
the \enquote{model} used in ensuring alignment. |
| 4168 |
\begin{LaTeXdemo}[code and float] |
| 4169 |
\begin{table} |
| 4170 |
\caption{Header row in a table.% |
| 4171 |
\label{tab:xmpl:headers}} |
| 4172 |
\robustify\bfseries |
| 4173 |
\centering |
| 4174 |
\sisetup{text-series-to-math} |
| 4175 |
\begin{tabular} |
| 4176 |
{ |
| 4177 |
@{} |
| 4178 |
S[table-format = 3.3] |
| 4179 |
S[table-format = 3.6, table-model-setup = \bfseries] |
| 4180 |
@{} |
| 4181 |
} |
| 4182 |
\rowcolor[gray]{0.9} |
| 4183 |
\bfseries 123.456 & \bfseries 123.456789 \\ |
| 4184 |
23.45 & 23.45 \\ |
| 4185 |
123.4 & 123.4 \\ |
| 4186 |
3.456 & 3.456 \\ |
| 4187 |
\end{tabular} |
| 4188 |
\end{table} |
| 4189 |
\end{LaTeXdemo} |
| 4190 |
|
| 4191 |
\subsection{Associating a locale with a \pkg{babel} language% |
| 4192 |
\label{sec:hint:babel}} |
| 4193 |
|
| 4194 |
It is possible to instruct the \pkg{babel} package to switch to a particular |
| 4195 |
\pkg{siunitx} locale when changing language. This can be done using the |
| 4196 |
\pkg{babel} \cs{extras\meta{language}} system. For example, to associate the |
| 4197 |
\texttt{DE} locale with the \texttt{german} \pkg{babel} language, the |
| 4198 |
appropriate code would be |
| 4199 |
\begin{LaTeXdemo}[code only] |
| 4200 |
\addto\extrasgerman{\sisetup{locale = DE}} |
| 4201 |
\end{LaTeXdemo} |
| 4202 |
|
| 4203 |
\subsection{Symbolic \enquote{digits}% |
| 4204 |
\label{sec:hint:symbols}} |
| 4205 |
|
| 4206 |
In some cases you may want to use \enquote{digits} which do not fall within the |
| 4207 |
usual set |0123456789|. This can be done by setting the \opt{input-digits} |
| 4208 |
option, but bearing in mind that this will affect (prevent) for example |
| 4209 |
rounding. |
| 4210 |
\begin{LaTeXdemo} |
| 4211 |
\sisetup{input-digits = 0123456789\pi}% |
| 4212 |
\num{4\pi e-7} |
| 4213 |
\end{LaTeXdemo} |
| 4214 |
Each extra entry should be a single token, and should either have a definition |
| 4215 |
which is safe in both math and text mode, or should only be used when the |
| 4216 |
output mode is known. It may be necessary to make some tokens robust using |
| 4217 |
\pkg{etoolbox} for this to work, for example |
| 4218 |
\begin{LaTeXdemo} |
| 4219 |
\robustify\dots |
| 4220 |
\sisetup{input-digits = 0123456789\dots}% |
| 4221 |
\qty{0,4066\dots}{\metre\squared} |
| 4222 |
\end{LaTeXdemo} |
| 4223 |
|
| 4224 |
\subsection{Demonstrating prefixes% |
| 4225 |
\label{sec:hint:prefixes}} |
| 4226 |
|
| 4227 |
As \pkg{siunitx} contains data about the numerical values of unit prefixes, |
| 4228 |
you may wish to print this in an automated way. Prefixes cannot be given |
| 4229 |
on their own, but it is possible to create a \enquote{do nothing} unit. |
| 4230 |
\begin{LaTeXdemo}[code only] |
| 4231 |
\DeclareSIUnit\noop{\relax} |
| 4232 |
\end{LaTeXdemo} |
| 4233 |
which can then be used to show just the prefix symbol. |
| 4234 |
\begin{LaTeXdemo} |
| 4235 |
\unit{\yotta\noop} |
| 4236 |
\end{LaTeXdemo} |
| 4237 |
To show just the numerical value of a prefix, you will need to use \cs{qty} |
| 4238 |
and appropriate settings. |
| 4239 |
\begin{LaTeXdemo} |
| 4240 |
\qty[prefix-mode = extract-exponent, print-unity-mantissa = false]% |
| 4241 |
{1}{\yotta\noop} |
| 4242 |
\end{LaTeXdemo} |
| 4243 |
This may be conveniently wrapped up inside a document command, for example |
| 4244 |
\begin{LaTeXdemo}[code only] |
| 4245 |
\NewDocumentCommand\prefixvalue{m}{% |
| 4246 |
\qty[prefix-mode=extract-exponent,print-unity-mantissa=false]{1}{#1\noop} |
| 4247 |
} |
| 4248 |
\end{LaTeXdemo} |
| 4249 |
|
| 4250 |
\subsection{Creating a set of pre-defined units% |
| 4251 |
\label{sec:hint:config}} |
| 4252 |
|
| 4253 |
There are many units which sit outside of those defined in the (current) |
| 4254 |
\acro{SI} Brochure which are of use to many people. Most obvious are those |
| 4255 |
which have been detailed in previous editions of the Brochure, as described |
| 4256 |
in Section~\ref{sec:BIPM8}, but there are many others. |
| 4257 |
|
| 4258 |
It is often convenient to have a pre-defined set of useful units available |
| 4259 |
without needing to copy the full set of definitions into each source file. At |
| 4260 |
the same time, it is important that such sources do show that they are using |
| 4261 |
units not defined by the core part of \pkg{siunitx}. The most straight-forward |
| 4262 |
way to achieve this is to create a separate file, for example |
| 4263 |
\texttt{siunitx-local-units.tex}, and place it in your local \TeX{} tree |
| 4264 |
(usually \verb|~/texmf/tex/latex/| on Linux, \verb|~/Library/texmf/tex/latex/| |
| 4265 |
on macOS or \verb|C:\Users\<name>\texmf\tex\latex| on Windows). This can then |
| 4266 |
be loaded in the preamble using |
| 4267 |
\begin{LaTeXdemo}[code only] |
| 4268 |
% Load useful 'local' units |
| 4269 |
\input{siunitx-local-units} |
| 4270 |
\end{LaTeXdemo} |
| 4271 |
|
| 4272 |
\subsection{Overloading the standard interfaces% |
| 4273 |
\label{sec:hint:overload}} |
| 4274 |
|
| 4275 |
The interfaces in \pkg{siunitx} deliberately split up different types of |
| 4276 |
numerical input (ranges, products, etc.) for semantic reasons. This also means |
| 4277 |
that there is less chance of confusion in parsing input. However, some users |
| 4278 |
would prefer to overload the \cs{num} and \cs{qty} commands such that they |
| 4279 |
accept multiple different types of input. There is a code-level interface that |
| 4280 |
could be used for this, but most end-users will likely want to avoid this. A |
| 4281 |
possible approach that covers most of the common cases is. |
| 4282 |
\begin{LaTeXdemo}[code only] |
| 4283 |
\ExplSyntaxOn |
| 4284 |
\cs_gset_eq:NN \ifstrpresent \tl_if_in:nnTF |
| 4285 |
\ExplSyntaxOff |
| 4286 |
\NewCommandCopy\oldnum\num |
| 4287 |
\NewCommandCopy\oldnumrange\numrange |
| 4288 |
\RenewDocumentCommand\num{O{}m}{% |
| 4289 |
\ifstrpresent{#2}{x} |
| 4290 |
{\numproduct[#1]{#2}} |
| 4291 |
{% |
| 4292 |
\ifstrpresent{#2}{;} |
| 4293 |
{\numlist[#1]{#2}} |
| 4294 |
{% |
| 4295 |
\ifstrpresent{#2}{:} |
| 4296 |
{\numrange[#1]{#2}} |
| 4297 |
{\oldnum[#1]{#2}}% |
| 4298 |
}% |
| 4299 |
}% |
| 4300 |
} |
| 4301 |
\RenewDocumentCommand\numrange{O{}>{\SplitList{:}}m} |
| 4302 |
{\oldnumrange[#1]#2} |
| 4303 |
\end{LaTeXdemo} |
| 4304 |
for the \cs{num} command and |
| 4305 |
\begin{LaTeXdemo}[code only] |
| 4306 |
\ExplSyntaxOn |
| 4307 |
\cs_gset_eq:NN \ifstrpresent \tl_if_in:nnTF |
| 4308 |
\ExplSyntaxOff |
| 4309 |
\NewCommandCopy\oldqty\qty |
| 4310 |
\NewCommandCopy\oldqtyrange\qtyrange |
| 4311 |
\RenewDocumentCommand\qty{O{}mm}{% |
| 4312 |
\ifstrpresent{#2}{x} |
| 4313 |
{\qtyproduct[#1]{#2}{#3}} |
| 4314 |
{% |
| 4315 |
\ifstrpresent{#2}{;} |
| 4316 |
{\qtylist[#1]{#2}{#3}} |
| 4317 |
{% |
| 4318 |
\ifstrpresent{#2}{:} |
| 4319 |
{\qtyrange[#1]{#2}{#3}} |
| 4320 |
{\oldqty[#1]{#2}{#3}}% |
| 4321 |
}% |
| 4322 |
}% |
| 4323 |
} |
| 4324 |
\RenewDocumentCommand\qtyrange{O{}>{\SplitList{:}}mm} |
| 4325 |
{\oldqtyrange[#1]#2{#3}} |
| 4326 |
\end{LaTeXdemo} |
| 4327 |
for \cs{qty}. |
| 4328 |
|
| 4329 |
\section{Using (\acro{SI}) units} |
| 4330 |
|
| 4331 |
Consistent and logical units are a necessity for scientific work, and have |
| 4332 |
applicability everywhere. Historically, a number of systems have been used for |
| 4333 |
physical units. \acro{SI} units were introduced by the \foreign{Conférence |
| 4334 |
Générale des Poids et Mesures} (\acro{CGPM}) in 1960. \acro{SI} units are a |
| 4335 |
coherent system based on seven base units, from which all other units may be |
| 4336 |
derived. |
| 4337 |
|
| 4338 |
At the same time, physical quantities with units are mathematical entities, and |
| 4339 |
as such way that they are typeset is important. In mathematics, changes of type |
| 4340 |
(such as using bold, italic, sans serif typeface and so on) convey information. |
| 4341 |
This means that rules exist not only for the type of units to be used under the |
| 4342 |
\acro{SI} system, but also the way they should appear in print. Advice on best |
| 4343 |
practice has been made available by the \emph{National Institute of Standards |
| 4344 |
and Technology} (\acro{NIST})~\cite{NIST}. |
| 4345 |
|
| 4346 |
As befits an agreed international standard, the full rules are detailed. It is |
| 4347 |
not appropriate to reproduce these in totality here; instead, a useful summary |
| 4348 |
of the key points is provided. The full details are available from the |
| 4349 |
\foreign{Bureau International des Poids et Mesures}~\cite{BIPM}. |
| 4350 |
|
| 4351 |
The \pkg{siunitx} package takes account of the information given here, so far |
| 4352 |
as is possible. Thus the package defaults follow the recommendations made for |
| 4353 |
typesetting numbers and units. Spacing and so forth is handled in such a way as |
| 4354 |
to make implementing the rules (relatively) easy. |
| 4355 |
|
| 4356 |
\subsection{Units} |
| 4357 |
|
| 4358 |
There are seven base \acro{SI} units, listed in Table~\ref{tab:unit:base}.% |
| 4359 |
\footnote{Some base units need others defined first; there is therefore a |
| 4360 |
required order of definition.} The base units have been chosen such that all |
| 4361 |
physical quantities can be expressed using an appropriative combination of |
| 4362 |
these units, needing no others and with no redundancy. |
| 4363 |
|
| 4364 |
All other units within the \acro{SI} system are regarded as \enquote{derived} |
| 4365 |
from the seven base units. At the most basic, all other \acro{SI} units can be |
| 4366 |
expressed as combinations of the base units. However, many units (listed in |
| 4367 |
Table~\ref{tab:unit:derived}) have a special name and symbol. Most of these |
| 4368 |
units are simple combinations of one or more base units (raised to powers as |
| 4369 |
appropriate). |
| 4370 |
|
| 4371 |
A series of \acro{SI} prefixes for decimal multiples and sub-multiples are |
| 4372 |
provided, and can be used as modifiers for any \acro{SI} unit (either base or |
| 4373 |
derived units) with the exception of the kilogram. The prefixes are listed in |
| 4374 |
Table~\ref{tab:unit:prefix}. No space should be used between a prefix and the |
| 4375 |
unit, and only a single prefix should be used. Even the degree Celsius can be |
| 4376 |
given a prefix, for example \qty{1}{\milli\degreeCelsius}. |
| 4377 |
|
| 4378 |
It is important to note that the kilogram is the only \acro{SI} unit with a |
| 4379 |
prefix as part of its name and symbol. Only single prefix may be used, and so |
| 4380 |
in the case of the kilogram prefix names are used with the unit name |
| 4381 |
\enquote{gram} and the prefix symbols are used with the unit symbol |
| 4382 |
\unit{\gram}. For example $\qty{1e-6}{\kilo\gram} = \qty{1e-3}{\gram} = |
| 4383 |
\qty{1}{\milli\gram}$. |
| 4384 |
|
| 4385 |
The application of \acro{SI} units is meant to provide a single set of units |
| 4386 |
which ensure consistency and clarity across all areas. However, other units are |
| 4387 |
common is many areas, and are not without merit. The units provided by |
| 4388 |
\pkg{siunitx} by default do not include any of these; only units which are part |
| 4389 |
of the \acro{SI} set or are accepted for use with \acro{SI} units are defined. |
| 4390 |
However, several other sets of units can be loaded as optional modules. The |
| 4391 |
binary prefixes and units (Table~\ref{tab:unit:binary}) are the most obvious |
| 4392 |
example. These are \emph{not} part of the \acro{SI} specifications, but the |
| 4393 |
prefix names are derived from those in Table~\ref{tab:unit:prefix}. |
| 4394 |
|
| 4395 |
Other units are normally to be avoided where possible. \acro{SI} units should, |
| 4396 |
in the main, be preferred due to the advantages of clear definition and |
| 4397 |
self-consistency this brings. However, there will probably always be a place |
| 4398 |
for specialist or non-standard units. This is particularly true of units |
| 4399 |
derived from basic physical constants. |
| 4400 |
|
| 4401 |
There are also many areas where non-standard units are used so commonly that to |
| 4402 |
do otherwise is difficult or impossible. For example, most synthetic chemists |
| 4403 |
measure the pressure inside vacuum apparatus in \unit{\millimetremercury}, |
| 4404 |
partly because the most common gauge for the task still uses a column of |
| 4405 |
mercury metal. For these reasons, \pkg{siunitx} allows definition of such |
| 4406 |
units. |
| 4407 |
|
| 4408 |
\subsection{Mathematical meaning} |
| 4409 |
|
| 4410 |
As explained earlier, a quantity combination is a single mathematical entity. |
| 4411 |
This has implications for how both the number and the unit should be printed. |
| 4412 |
Firstly, the two parts should not be separated: a quantity is a product of the |
| 4413 |
number and the unit. With the exception of the symbols for plane angles |
| 4414 |
(\unit{\degree}, \unit{\arcminute} and \unit{\arcsecond}), the \acro{BIPM} |
| 4415 |
specifies either a space or half-height (centered) dot should be |
| 4416 |
used~\cite{BIPM}. |
| 4417 |
\begin{LaTeXdemo} |
| 4418 |
A space for \qty{10}{\percent}\\ |
| 4419 |
and also for \qty{100}{\degreeCelsius}\\ |
| 4420 |
but not for \ang{1.23}. |
| 4421 |
\end{LaTeXdemo} |
| 4422 |
|
| 4423 |
The mathematical meaning of units also means that the shape, weight and family |
| 4424 |
are important. Units are supposed to be typeset in an upright, medium weight |
| 4425 |
font. Italic, bold and sans serif are all used mathematically to convey other |
| 4426 |
meanings. (In an all sanserif document, using sans serif for units is |
| 4427 |
reasonable.) The \pkg{siunitx} package defaults again follow this convention: |
| 4428 |
any local settings are ignored, and uses the current upright math font. |
| 4429 |
However, there are occasions where this may not be the most desirable behavior. |
| 4430 |
A classic example would be in an all-bold section heading. As the surrounding |
| 4431 |
text is bold, some people feel that any units should follow this. |
| 4432 |
\begin{LaTeXdemo} |
| 4433 |
Units should \textbf{not be bold: \qty{54}{\farad}}\\ |
| 4434 |
\textbf{But perhaps in a running block,\\ |
| 4435 |
it might look better: |
| 4436 |
\qty[text-series-to-math]{54}{\farad}} |
| 4437 |
\end{LaTeXdemo} |
| 4438 |
|
| 4439 |
Symbols for units formed from other units by multiplication are indicated by |
| 4440 |
means of either a half-height (that is, centered) dot or a (thin) space. |
| 4441 |
\begin{LaTeXdemo} |
| 4442 |
$\unit{\metre\second} = \text{metre second}$ \\ |
| 4443 |
$\unit{\milli\second} = \text{millisecond}$ \\ |
| 4444 |
\sisetup{inter-unit-product = \ensuremath { { } \cdot { } } } |
| 4445 |
$\unit{\metre\second} = \text{metre second}$ \\ |
| 4446 |
$\unit{\milli\second} = \text{millisecond}$ |
| 4447 |
\end{LaTeXdemo} |
| 4448 |
There are some circumstances under which it is common practice to omit any |
| 4449 |
spaces. The classic example is \unit{\kWh}, where |
| 4450 |
\enquote{\unit[inter-unit-product = \,]{\kWh}} does not add any useful |
| 4451 |
information. If using such a unit repeatedly, users of \pkg{siunitx} are |
| 4452 |
advised to create a custom unit to ensure consistency. It is important to note |
| 4453 |
that while this is common practice, it is \emph{not} allowed by the |
| 4454 |
\acro{BIPM}~\cite{BIPM}. |
| 4455 |
|
| 4456 |
Symbols for units formed from other units by division are indicated by means of |
| 4457 |
a virgule (oblique stroke, slash, "/"), a horizontal line, or negative |
| 4458 |
exponents.\footnote{Notice that a virgule and a solidus are not the same |
| 4459 |
symbol.} However, to avoid ambiguity, the virgule must not be repeated on the |
| 4460 |
same line unless parentheses are used. This is ensured when using named unit |
| 4461 |
macros in \pkg{siunitx}, which will \enquote{trap} repeated division and format |
| 4462 |
it correctly. In complicated cases, negative exponents are to be preferred over |
| 4463 |
other formats. |
| 4464 |
\begin{LaTeXdemo} |
| 4465 |
\unit{\joule\per\mole\per\kelvin} \\ |
| 4466 |
\unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\ |
| 4467 |
\unit[per-mode = symbol]{\joule\per\mole\per\kelvin} |
| 4468 |
\end{LaTeXdemo} |
| 4469 |
|
| 4470 |
Products and errors should show what unit applies to each number given. Thus |
| 4471 |
\qtyproduct[product-units = bracket]{2x3}{\metre} is an ordered set of lengths |
| 4472 |
of a geometric area, whereas \qtyproduct[product-units = single]{2x3}{\metre} |
| 4473 |
is a length (and equal to \qty{6}{\metre}). Thus, $\times$ is not a product but |
| 4474 |
is a mathematical operator; in the same way, a $2 \times 3$ matrix is not a $6$ |
| 4475 |
matrix! In some areas, areas and volumes are given with separated units but a |
| 4476 |
unit raised to the appropriate power: \qtyproduct[product-units = power]{2 x |
| 4477 |
3}{\metre}. Although this does display the correct overall units, it is |
| 4478 |
potentially-confusing and is not encouraged. |
| 4479 |
|
| 4480 |
Care must be taken when writing ranges of numbers. For purely numerical values, |
| 4481 |
it is common to use an en-dash to show a range, for example \enquote{see pages |
| 4482 |
1--5}. On the other hand, physical quantities could be misinterpret as negative |
| 4483 |
values if written in this way. As the quantity is a single mathematical entity, |
| 4484 |
writing the values with an en-dash followed by a single unit is also incorrect. |
| 4485 |
As a result, using the word \enquote{to} is strongly recommended. |
| 4486 |
\begin{LaTeXdemo} |
| 4487 |
\qtyrange{1}{5}{\metre} long. |
| 4488 |
\end{LaTeXdemo} |
| 4489 |
|
| 4490 |
\subsection{Graphs and tables} |
| 4491 |
|
| 4492 |
In graphs and tables, repetition of the units following each entry or axis mark |
| 4493 |
is confusing and repetitive. It is therefore best to place the unit in the |
| 4494 |
label part of the information. Placing the unit in square brackets is common |
| 4495 |
but mathematically poor.\footnote{For example, for an acceleration \(a\), the |
| 4496 |
expression $[a]$ is the dimensions of $a$, \foreign{i.e.}~length per time |
| 4497 |
squared in this case.} Much better is to show division of all quantities by the |
| 4498 |
unit, which leaves the entries as unitless ratios. This is illustrated in |
| 4499 |
Table~\ref{tab:xmpl:unitless} and Figure~\ref{fig:xmpl:unitless}. |
| 4500 |
\begin{LaTeXdemo}[code and float] |
| 4501 |
\begin{table} |
| 4502 |
\caption{An example of table labelling.% |
| 4503 |
\label{tab:xmpl:unitless}} |
| 4504 |
\sisetup{ |
| 4505 |
table-number-alignment = center, |
| 4506 |
table-format = 1.4 |
| 4507 |
} |
| 4508 |
\begin{tabular}{@{}cS@{}} |
| 4509 |
\toprule |
| 4510 |
Entry & {Length/\unit{\metre}} \\ |
| 4511 |
\midrule |
| 4512 |
1 & 1.1234 \\ |
| 4513 |
2 & 1.1425 \\ |
| 4514 |
3 & 1.7578 \\ |
| 4515 |
4 & 1.9560 \\ |
| 4516 |
\bottomrule |
| 4517 |
\end{tabular} |
| 4518 |
\end{table} |
| 4519 |
\end{LaTeXdemo} |
| 4520 |
\begin{LaTeXdemo}[code and float] |
| 4521 |
\begin{figure} |
| 4522 |
\begin{tikzpicture} |
| 4523 |
\begin{axis}[ |
| 4524 |
xlabel = $t/\unit{\second}$, |
| 4525 |
xmax = 6, |
| 4526 |
xmin = 0, |
| 4527 |
ylabel = $d/\unit{\metre}$, |
| 4528 |
ymin = 0 |
| 4529 |
] |
| 4530 |
\addplot[smooth,mark=*] |
| 4531 |
plot coordinates { |
| 4532 |
(0,0) |
| 4533 |
(1,5) |
| 4534 |
(2,8) |
| 4535 |
(3,9) |
| 4536 |
(4,8) |
| 4537 |
(5,5) |
| 4538 |
(6,0) |
| 4539 |
}; |
| 4540 |
\end{axis} |
| 4541 |
\end{tikzpicture} |
| 4542 |
\caption{An example of graph labelling.% |
| 4543 |
\label{fig:xmpl:unitless}} |
| 4544 |
\end{figure} |
| 4545 |
\end{LaTeXdemo} |
| 4546 |
|
| 4547 |
In most cases, adding exponent values in the body of a table is |
| 4548 |
less desirable than adding a fixed exponent to column headers. An |
| 4549 |
example is shown in Table~\ref{tab:good}. The use of \cs{multicolumn} is |
| 4550 |
needed here due to the \enquote{\texttt{<}}; without \cs{multicolumn}, |
| 4551 |
the titles are followed by \enquote{\unit{\kilo\gram}}! |
| 4552 |
\begin{LaTeXdemo}[code and float] |
| 4553 |
\begin{table} |
| 4554 |
\caption{Bad and good columns.% |
| 4555 |
\label{tab:good}} |
| 4556 |
\sisetup{table-number-alignment = center} |
| 4557 |
\begin{tabular}{ |
| 4558 |
@{} |
| 4559 |
c |
| 4560 |
S[table-format = 1.3e1] |
| 4561 |
@{\,\unit{\kilogram}} |
| 4562 |
S[table-format = 2.2] |
| 4563 |
@{} |
| 4564 |
} |
| 4565 |
\toprule |
| 4566 |
Entry & \multicolumn{1}{c}{Mass} & |
| 4567 |
{Mass/\qty[print-unity-mantissa = false]{e3}{\kilogram}} \\ |
| 4568 |
\midrule |
| 4569 |
1 & 4.56e3 & 4.56 \\ |
| 4570 |
2 & 2.40e3 & 2.40 \\ |
| 4571 |
3 & 1.345e4 & 13.45 \\ |
| 4572 |
4 & 4.5e2 & 0.45 \\ |
| 4573 |
\bottomrule |
| 4574 |
\end{tabular} |
| 4575 |
\end{table} |
| 4576 |
\end{LaTeXdemo} |
| 4577 |
|
| 4578 |
\section{Installation} |
| 4579 |
|
| 4580 |
For most users, there will be no need to explicitly install \pkg{siunitx}: |
| 4581 |
it is available from the package management system in current \TeX{} Live |
| 4582 |
and MiK\TeX{} systems. |
| 4583 |
|
| 4584 |
For manual installation, the package is available from |
| 4585 |
\href{http://ctan.org/pkg/siunitx}{\acro{CTAN}}. As well as the raw source |
| 4586 |
files, \acro{CTAN} hold the package as a pre-extracted zip file, |
| 4587 |
\file{siunitx.tds.zip}. The later is most convenient for most users: simply |
| 4588 |
unzip this in your local \path{texmf} directory. |
| 4589 |
|
| 4590 |
The package requires \pkg{expl3} support as provided in the \pkg{l3kernel} and |
| 4591 |
bundle, which is required by the \LaTeX{} kernel. As such, you are very |
| 4592 |
unlikely to need to update this manually. |
| 4593 |
|
| 4594 |
\section{Thanks} |
| 4595 |
|
| 4596 |
Many users have provided feedback, bug reports and ideas for new features for |
| 4597 |
\pkg{siunitx}: thanks to all of them. Particular thanks to Stefan Pinnow, who |
| 4598 |
has taken the lead role as beta tester for \pkg{siunitx}, finding incorrect |
| 4599 |
output, bad documentation and the odd spelling mistake in the documentation. |
| 4600 |
Thanks also to Enrico Gregorio for encouraging me to complete a fully |
| 4601 |
\pkg{expl3}-compliant version of the package. Thanks also to Danie Els and |
| 4602 |
Marcel Heldoorn for the \pkg{SIstyle} and \pkg{SIunits} packages, respectively, |
| 4603 |
which provided the starting point for the development of \pkg{siunitx}. |
| 4604 |
|
| 4605 |
\section{Making suggestions and reporting bugs} |
| 4606 |
|
| 4607 |
Feedback on \pkg{siunitx} is always welcome, either to make suggestions or to |
| 4608 |
report problems. When sending feedback, it is always useful if a small example |
| 4609 |
file is included, showing the bug being reported or illustrating the desired |
| 4610 |
output. It is helpful if a \enquote{reference rendering} is included, showing |
| 4611 |
what the output should look like. A typical example file might read |
| 4612 |
\begin{verbatim} |
| 4613 |
\listfiles |
| 4614 |
% Use the article class unless the problem is class-dependent |
| 4615 |
\documentclass{article} |
| 4616 |
\usepackage{siunitx} |
| 4617 |
% Other packages loaded as required |
| 4618 |
\begin{document} |
| 4619 |
Reference output: $1.23\,\mathrm{m}$ |
| 4620 |
|
| 4621 |
\textsf{siunitx} output: \qty{1.23}{\metre} |
| 4622 |
\end{document} |
| 4623 |
\end{verbatim} |
| 4624 |
As illustrated, it is usually best to use the \cls{article} class and to only |
| 4625 |
load packages which are needed to show the issue. It is also useful to include |
| 4626 |
a copy of the log file generate by \LaTeX{} when reporting a bug (as the |
| 4627 |
versions of packages can be important to solving the issue). |
| 4628 |
|
| 4629 |
Feedback can be sent in a range of ways. The development code and issue tracker |
| 4630 |
are hosted on GitHub: \url{https://github.com/josephwright/siunitx/}. Issues |
| 4631 |
opened there are visible to other users and makes sure that they cannot be |
| 4632 |
forgotten. |
| 4633 |
|
| 4634 |
\end{documentation} |
| 4635 |
|
| 4636 |
\begin{thebibliography}{10} |
| 4637 |
\bibitem{BIPM} |
| 4638 |
\emph{The International System of Units (\acro{SI})}, |
| 4639 |
\url{https://www.bipm.org/en/measurement-units/}. |
| 4640 |
\bibitem{NIST} |
| 4641 |
\emph{International System of Units from \acro{NIST}}, |
| 4642 |
\url{http://physics.nist.gov/cuu/Units/index.html}. |
| 4643 |
\end{thebibliography} |
| 4644 |
|
| 4645 |
\PrintIndex |
| 4646 |
|
| 4647 |
\end{document} |