summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/siunitx/siunitx.tex
blob: 3cb5f25ed55a958725afcb5194778f48e3bdc30f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
\iffalse meta-comment

File: siunitx.tex Copyright (C) 2014-2021 Joseph Wright

It may be distributed and/or modified under the conditions of the
LaTeX Project Public License (LPPL), either version 1.3c of this
license or (at your option) any later version.  The latest version
of this license is in the file

   https://www.latex-project.org/lppl.txt

This file is part of the "siunitx bundle" (The Work in LPPL)
and all files in that bundle must be distributed together.

The released version of this bundle is available from CTAN.

-----------------------------------------------------------------------

The development version of the bundle can be found at

   https://github.com/josephwright/siunitx

for those people who are interested.

-----------------------------------------------------------------------

\fi

\documentclass{l3doc}

% The next line is needed so that \GetFileInfo will be able to pick up
% version data (quite apart from making the demos work).
\usepackage{siunitx}
\DeclareSIUnit\noop{\relax} % For printing prefixes
\DeclareSIPower\quartic\tothefourth{4} % For demos
\DeclareSIUnit\KWH{kWh}
\DeclareSIQualifier\polymer{pol}
\DeclareSIQualifier\catalyst{cat}
\DeclareSIUnit\millimetremercury{mmHg}

% Commands for this document
\ExplSyntaxOn
\makeatletter
\NewDocumentCommand \acro { m }
  {
    \textsc
      {
        \exp_args:NV \tl_if_head_eq_charcode:nNTF \f@series { m }
          { \tl_lower_case:n }
          { \use:n }
            {#1}
      }
  }
\makeatother
\ExplSyntaxOff
\NewDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
\NewDocumentCommand\ext{m}{\texttt{.#1}}
\NewDocumentCommand\foreign{m}{\textit{#1}}
\NewDocumentCommand\opt{m}{\texttt{#1}}
% Tidy up the above in bookmarks
\makeatletter
\pdfstringdefDisableCommands{%
  \let\acro\@firstofone
  \let\ext\@firstofone
  \let\foreign\@firstofone
  \let\opt\@firstofone
}
\makeatother

\NewDocumentCommand\DescribePrefix{m}{%
  #1 &
  \cs{#1} &
  \unit{\csname #1\endcsname\noop}
}
\NewDocumentCommand\DescribeUnit{O{#2}m}{%
  #1 &
  \cs{#2} &
  \unit{\csname #2\endcsname}
}

% For demos
\usepackage[french,german,spanish,UKenglish]{babel}
\AtBeginDocument{\shorthandoff{:<>}}
\usepackage{translations}
\usepackage{cancel}
\usepackage{collcell}
\usepackage{sansmath}
\newlength{\mylength}

% For creating code demonstrations
% This needs access to some code-level interfaces in listings
\usepackage{listings}
\makeatletter
\lst@RequireAspects{writefile}
\newsavebox\LaTeXdemo@box
\lstnewenvironment{LaTeXdemo}[1][code and example]
  {%
    \global\let\lst@intname\@empty
    \edef\LaTeXdemo@end{%
      \expandafter\noexpand\csname LaTeXdemo@@#1@end\endcsname
    }%
    \@nameuse{LaTeXdemo@@#1}%
  }
  {\LaTeXdemo@end}
\newcommand\LaTeXdemo@new[3]{%
  \@namedef{LaTeXdemo@@#1}{#2}%
  \@namedef{LaTeXdemo@@#1@end}{#3}%
}
\newcommand*\LaTeXdemo@common{%
  \setkeys{lst}
    {%
       basicstyle   = \small\ttfamily,
       basewidth    = 0.51em,
       gobble       = 2,
       language     = [LaTeX]{TeX},
    }%
}
\newcount\LaTeXdemo@count
\newcommand*\LaTeXdemo@input{%
  \catcode`\^^M = 10\relax
  \input{\jobname-\number\LaTeXdemo@count.tmp}%
}
\LaTeXdemo@new{code and example}{%
  \setbox\LaTeXdemo@box=\hbox\bgroup
    \global\advance\LaTeXdemo@count by 1 %
    \lst@BeginAlsoWriteFile{\jobname-\number\LaTeXdemo@count.tmp}%
    \LaTeXdemo@common
}{%
    \lst@EndWriteFile
  \egroup
  \begin{center}
    \ifdim\wd\LaTeXdemo@box > 0.48\linewidth
      \begin{minipage}{\linewidth}
        \usebox\LaTeXdemo@box
      \end{minipage}%
      \par
      \begin{minipage}{\linewidth}
        \LaTeXdemo@input
      \end{minipage}
    \else
      \begin{minipage}{0.48\linewidth}
        \LaTeXdemo@input
      \end{minipage}%
      \hfil
      \begin{minipage}{0.48\linewidth}
        \usebox\LaTeXdemo@box
      \end{minipage}%
    \fi
  \end{center}
}
\LaTeXdemo@new{code and float}{%
  \global\advance\LaTeXdemo@count by 1 %
  \lst@BeginAlsoWriteFile{\jobname-\number\LaTeXdemo@count.tmp}%
  \LaTeXdemo@common
}{%
  \lst@EndWriteFile
  \LaTeXdemo@input
}
\LaTeXdemo@new{code only}{\LaTeXdemo@common}{}
\makeatother

% For table demos
\usepackage{datatool}
\usepackage{multirow}
\usepackage[table]{xcolor}
% Has to come after xcolor
\usepackage{pgfplots}
\pgfplotsset{compat = 1.16, compat/show suggested version = false}
\usepackage{xfp}

% For the extra-long tables
\usepackage{xtab}

% For the table notes
\usepackage{threeparttable}

% Design changes
\usepackage{caption}
\makeatletter
\edef\@floatboxreset{%
  \unexpanded\expandafter{\@floatboxreset}%
  \noexpand\centering
}
\makeatother
\usepackage[osf]{mathpazo}

\hypersetup{hidelinks}

\begin{document}

\GetFileInfo{siunitx.sty}

\title{%
  \pkg{siunitx} -- A comprehensive (\acro{SI}) units package%
  \thanks{This file describes \fileversion,
    last revised \filedate.}%
}

\author{%
  Joseph Wright%
  \thanks{%
    E-mail:
    \href{mailto:joseph.wright@morningstar2.co.uk}
      {joseph.wright@morningstar2.co.uk}%
  }%
}

\date{Released \filedate}

\maketitle

\tableofcontents

\begin{abstract}
  Physical quantities have both numbers and units, and each physical quantity
  should be expressed as the product of a number and a unit. Typesetting
  physical quantities requires care to ensure that the combined mathematical
  meaning of the number--unit combination is clear. In particular, the
  \acro{SI} units system lays down a consistent set of units with rules on how
  these are to be used. However, different countries and publishers have
  differing conventions on the exact appearance of numbers (and units). The
  \pkg{siunitx} package provides a set of tools for authors to typeset
  quantities in a consistent way. The package has an extended set of
  configuration options which make it possible to follow varying typographic
  conventions with the same input syntax. The package includes automated
  processing of numbers and units, and the ability to control tabular alignment
  of numbers.
\end{abstract}

\begin{documentation}

\section{Introduction}

The correct application of units of measurement is very important in technical
applications. For this reason, carefully-crafted definitions of a coherent
units system have been laid down by the \foreign{Conférence Génrale des Poids
et Mesures} (\acro{CGPM}): this has resulted in the \foreign{Système
International d'Unités}~(\acro{SI}). At the same time, typographic conventions
for correctly displaying both numbers and units exist to ensure that no loss of
meaning occurs in printed matter.

The \pkg{siunitx} package aims to provide a unified method for \LaTeX{} users
to typeset numbers and units correctly and easily. The design philosophy of
\pkg{siunitx} is to follow the agreed rules by default, but to allow variation
through option settings. In this way, users can use \pkg{siunitx} to follow the
requirements of publishers, co-authors, universities, \foreign{etc}.\ without
needing to alter the input at all.

\section{\pkg{siunitx} for the impatient}

The package provides the user macros:
\begin{itemize}
  \item \cs{ang}\oarg{options}\marg{angle}
  \item \cs{num}\oarg{options}\marg{number}
  \item \cs{unit}\oarg{options}\marg{unit}
  \item \cs{qty}\oarg{options}\marg{number}\marg{unit}
  \item \cs{numlist}\oarg{options}\marg{numbers}
  \item \cs{numproduct}\oarg{options}\marg{numbers}
  \item \cs{numrange}\oarg{options}\marg{numbers}\marg{number2}
  \item \cs{qtylist}\oarg{options}\marg{numbers}\marg{unit}
  \item \cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit}
  \item \cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit}
  \item \cs{complexnum}\oarg{options}\marg{number}
  \item \cs{complexqty}\oarg{options}\marg{number}\marg{unit}
  \item \cs{sisetup}\marg{options}
  \item \cs{tablenum}\oarg{options}\marg{number}
\end{itemize}
plus the \texttt{S} column type for decimal alignments and units in tabular
environments. These user macros and column types are designed for typesetting
numbers and units with control of appearance and with intelligent processing.

Numbers are processed with understanding of exponents, or using additional
commands for products and complex numbers.
\begin{LaTeXdemo}
  \num{12345,67890}  \\
  \num{.3e45}        \\
  \complexnum{1+-2i} \\
  \numproduct{1.654 x 2.34 x 3.430}
\end{LaTeXdemo}

The unit system can interpret units given as text to be used directly or as
macro-based units. In the latter case, different formatting is possible.
\begin{LaTeXdemo}
  \unit{kg.m.s^{-1}}                \\
  \unit{\kilogram\metre\per\second} \\
  \unit[per-mode = symbol]
    {\kilogram\metre\per\second}  \\
  \unit[per-mode = symbol]
    {\kilogram\metre\per\ampere\per\second}
\end{LaTeXdemo}

Simple lists and ranges of numbers can be handled.
\begin{LaTeXdemo}
  \numlist{10;20;30}                     \\
  \qtylist{0.13;0.67;0.80}{\milli\metre} \\
  \numrange{10}{20}                      \\
  \qtyrange{0.13}{0.67}{\milli\metre}
\end{LaTeXdemo}

By default, all text is typeset in the current upright math font. This can be
changed by setting the appropriate options.

\section{Using the \pkg{siunitx} package}

\subsection{Numbers}

\begin{function}{\num}
  \begin{syntax}
    \cs{num}\oarg{options}\marg{number}
  \end{syntax}
\end{function}
Numbers are automatically formatted by the \cs{num} macro. This takes one
optional argument, \meta{options}, and one mandatory one, \meta{number}. The
contents of \meta{number} are automatically formatted. The formatter removes
both \enquote{soft} (\verb*| |) and \enquote{hard} spaces (|\,| and |~|),
automatically identifies exponents (as standard marked using |e|, |E|, |d| or
|D|) and adds the appropriate spacing of large numbers. With the standard
settings a leading zero is added before a decimal marker, if needed: both |.|
and "," are recognised as decimal markers.
\begin{LaTeXdemo}
  \num{123}     \\
  \num{1234}    \\
  \num{12345}   \\
  \num{0.123}   \\
  \num{0,1234}  \\
  \num{.12345}  \\
  \num{3.45d-4} \\
  \num{-e10}
\end{LaTeXdemo}

Note that numbers are parsed before typesetting, which does have a performance
overhead (only obvious with very large amounts of numerical input). The parser
understands a range of input syntaxes, as demonstrated above.

\begin{function}{\numlist}
  \begin{syntax}
    \cs{numlist}\oarg{options}\marg{numbers}
  \end{syntax}
\end{function}
Lists of numbers may be processed using the \cs{numlist} function. Each
\meta{number} is given within the list of \meta{numbers} within a brace pair,
as the list can have a flexible length.
\begin{LaTeXdemo}
  \numlist{10;30;50;70}
\end{LaTeXdemo}

\begin{function}{\numproduct}
  \begin{syntax}
    \cs{numproduct}\oarg{options}\marg{numbers}
  \end{syntax}
\end{function}
Runs of products of numbers may be inserted using the \cs{numproduct} function.
This acts in the same way as \cs{num}, but inserts either a symbol or phrase
between the entries. The latter should be separated by |x| tokens.
\begin{LaTeXdemo}
  \numproduct{10 x 30}
\end{LaTeXdemo}

\begin{function}{\numrange}
  \begin{syntax}
    \cs{numrange}\oarg{options}\marg{number1}\marg{number2}
  \end{syntax}
\end{function}
Simple ranges of numbers can be handled using the \cs{numrange} function. This
acts in the same way as \cs{num}, but inserts a phrase or other text between
the two entries.
\begin{LaTeXdemo}
  \numrange{10}{30}
\end{LaTeXdemo}

\subsection{Angles}

\begin{function}{\ang}
  \begin{syntax}
    \cs{ang}\oarg{options}\marg{angle}
  \end{syntax}
\end{function}
Angles can be typeset using the \cs{ang} command. The \meta{angle} can be given
either as a decimal number or as a semi-colon separated list of degrees,
minutes and seconds, which is called \enquote{arc format} in this document. The
numbers which make up an angle are processed using the same system as other
numbers.
\begin{LaTeXdemo}
  \ang{10}    \\
  \ang{12.3}  \\
  \ang{4,5}   \\
  \ang{1;2;3} \\
  \ang{;;1}   \\
  \ang{+10;;} \\
  \ang{-0;1;}
\end{LaTeXdemo}

\subsection{Units}

\begin{function}{\unit}
  \begin{syntax}
    \cs{unit}\oarg{options}\marg{unit}
  \end{syntax}
\end{function}
The symbol for a unit can be typeset using the \cs{unit} macro: this provides
full control over output format for the unit. Like the \cs{num} macro,
\cs{unit} takes one optional and one mandatory argument. The unit formatting
system can accept two types of input. When the \meta{unit} contains literal
items (for example letters or numbers) then \pkg{siunitx} converts |.| and |~|
into inter-unit product and correctly positions sub- and superscripts specified
using |_| and |^|. The formatting methods will work with both math and text
mode.
\begin{LaTeXdemo}
  \unit{kg.m/s^2} \\
  \unit{g_{polymer}~mol_{cat}.s^{-1}}
\end{LaTeXdemo}

The second operation mode for the \cs{unit} macro is an \enquote{interpreted}
system, Here, each unit, \acro{SI} multiple prefix and power is given a macro
name. These are entered in a method very similar to the reading of the unit
name in English.
\begin{LaTeXdemo}
  \unit{\kilo\gram\metre\per\square\second} \\
  \unit{\gram\per\cubic\centi\metre}        \\
  \unit{\square\volt\cubic\lumen\per\farad} \\
  \unit{\metre\squared\per\gray\cubic\lux}  \\
  \unit{\henry\second}
\end{LaTeXdemo}

On its own, this is less convenient than the direct method, although it does
use meaning rather than appearance for input. However, the package allows you
to define new unit macros; a large number of pre-defined abbreviations are also
supplied. More importantly, by defining macros for units, instead of literal
input, new functionality is made available. By altering the settings used by
the package, the same input can yield a variety of different output formats.
For example, the \cs{per} macro can give reciprocal powers, slashes or be used
to construct units as fractions.

\begin{function}{\qty}
  \begin{syntax}
    \cs{qty}\oarg{options}\marg{number}\marg{unit}
  \end{syntax}
\end{function}
Very often, numbers and units are given together. Formally, the value of a
quantity is the product of the number and the unit, the space being regarded as
a multiplication sign. The \cs{qty} macro combines the
functionality of \cs{num} and \cs{unit}, and makes this both possible and easy.
The \meta{number} and \meta{unit} arguments work exactly like those for the
\cs{num} and \cs{unit} macros, respectively.
\begin{LaTeXdemo}
  \qty[mode = text]{1.23}{J.mol^{-1}.K^{-1}}          \\
  \qty{.23e7}{\candela}                               \\
  \qty[per-mode = symbol]{1.99}{\per\kilogram}        \\
  \qty[per-mode = fraction]{1,345}{\coulomb\per\mole}
\end{LaTeXdemo}

It is possible to set up the unit macros to be available outside of the
\cs{qty} and \cs{unit} functions. This is not the standard behaviour as there
is the risk of name clashes (for example, \cs{day} is a \TeX{} primitive
and several packages define \cs{degree}). Full details of using \enquote{stand
alone} units are found in \ref{sec:units:creating}.

\begin{function}{\qtylist}
  \begin{syntax}
    \cs{qtylist}\oarg{options}\marg{numbers}\marg{unit}
  \end{syntax}
\end{function}
Lists of numbers with units can be handled using the \cs{qtylist} function. The
behaviour of this function is similar to \cs{numlist}, but with the addition of
the unit to each number.
\begin{LaTeXdemo}
  \qtylist{10;30;45}{\metre}
\end{LaTeXdemo}

\begin{function}{\qtyproduct}
  \begin{syntax}
    \cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit}
  \end{syntax}
\end{function}
Runs of products of of numbers with units can be handled using the
\cs{qtyproduct} function. The behaviour of this function is similar to
\cs{numproduct}, but with the addition of a unit to each number.
\begin{LaTeXdemo}
  \qtyproduct{10 x 30 x 45}{\metre}
\end{LaTeXdemo}

\begin{function}{\qtyrange}
  \begin{syntax}
    \cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit}
  \end{syntax}
\end{function}
Ranges of numbers with units can be handled using the \cs{qtyrange}
function. The behaviour of this function is similar to \cs{numrange}, but
with the addition of a unit to each number.
\begin{LaTeXdemo}
  \qtyrange{10}{30}{\metre}
\end{LaTeXdemo}

The input of lists, products and ranges of quantities using a single command
allows them to be adjusted together. These commands are intended to allow
consistent formatting of related values: as such, they apply a single
unit to all of the values. This is particularly notable when using
adjustment of the numerical values.

\subsection{Complex numbers and quantities}

\begin{function}{\complexnum}
  \begin{syntax}
    \cs{complexnum}\oarg{options}\marg{number}
  \end{syntax}
\end{function}
Typesets the complex number, which must be given in the form $a + b\mathrm{i}$
or $a + \mathrm{i}b$. Processing of the numerical parts is otherwise identical
to the standard \cs{num} command.

\begin{function}{\complexqty}
  \begin{syntax}
    \cs{complexqty}\oarg{options}\marg{number}\marg{unit}
  \end{syntax}
\end{function}
Typesets the complex quantity, which must be given in the form $a + b\mathrm{i}$
or $a + \mathrm{i}b$. Processing of the numerical parts is otherwise identical
to the standard \cs{qty} command.

\subsection{The unit macros}

The package always defines the basic set of \acro{SI} units with macro names.
This includes the base \acro{SI} units, the derived units with special names
and the prefixes. A small number of powers are also given pre-defined names.
Full details of units in the \acro{SI} are available on-line~\cite{BIPM}.

The seven base \acro{SI} units are always defined (Table~\ref{tab:unit:base}).
In addition, the macro \cs{meter} is available as an alias for \cs{metre}, for
users of US spellings. The full details of the base units are given in the
\acro{SI} Brochure.
\begin{table}
  \caption{\acro{SI} base units.%
    \label{tab:unit:base}}
  \begin{tabular}{@{}lll@{}}
    \toprule
      Unit & Command & Symbol \\
    \midrule
      \DescribeUnit{ampere}   \\
      \DescribeUnit{candela}  \\
      \DescribeUnit{kelvin}   \\
      \DescribeUnit{kilogram} \\
      \DescribeUnit{metre}    \\
      \DescribeUnit{mole}     \\
      \DescribeUnit{second}   \\
    \bottomrule
  \end{tabular}
\end{table}

The \acro{SI} also lists a number of units which have special names and
symbols: these are listed in Table~\ref{tab:unit:derived}.
\begin{table}
  \caption{Coherent derived units in the \acro{SI} with special names and
      symbols.%
      \label{tab:unit:derived}}
  \begin{tabular}{@{}lll>{\qquad}lll@{}}
    \toprule
      Unit & Command & Symbol & Unit & Command & Symbol \\
    \midrule
      \DescribeUnit{becquerel} &
      \DescribeUnit{newton}    \\
      \DescribeUnit[degree Celsius]{degreeCelsius} &
      \DescribeUnit{ohm}       \\
      \DescribeUnit{coulomb}   &
      \DescribeUnit{pascal}    \\
      \DescribeUnit{farad}     &
      \DescribeUnit{radian}    \\
      \DescribeUnit{gray}      &
      \DescribeUnit{siemens}   \\
      \DescribeUnit{hertz}     &
      \DescribeUnit{sievert}   \\
      \DescribeUnit{henry}     &
      \DescribeUnit{steradian} \\
      \DescribeUnit{joule}     &
      \DescribeUnit{tesla}     \\
      \DescribeUnit{lumen}     &
      \DescribeUnit{volt}      \\
      \DescribeUnit{katal}     &
      \DescribeUnit{watt}      \\
      \DescribeUnit{lux}       &
      \DescribeUnit{weber}     \\
    \bottomrule
  \end{tabular}
\end{table}

In addition to the official \acro{SI} units, \pkg{siunitx} also provides macros
for a number of units which are accepted for use in the \acro{SI} although they
are not \acro{SI} units. Table~\ref{tab:unit:accepted} lists the
\enquote{accepted} units. The command \cs{percent} is also provided for use in
units: this is accepted with the \acro{SI} as detailed in Section~5.3.7 of the
Brochure.
\begin{table}
  \caption{Non-\acro{SI} units accepted for use with the International System of
    Units.%
      \label{tab:unit:accepted}}
  \begin{tabular}{@{}lll@{}}
    \toprule
      Unit & Command & Symbol \\
    \midrule
      \DescribeUnit{astronomicalunit} \\
      \DescribeUnit{bel}              \\
      \DescribeUnit{dalton}           \\
      \DescribeUnit{day}              \\
      \DescribeUnit{decibel}          \\
      \DescribeUnit{degree}           \\
      \DescribeUnit{electronvolt}     \\
      \DescribeUnit{hectare}          \\
      \DescribeUnit{hour}             \\
      \DescribeUnit{litre} \\
       & \cs{liter} & \unit{\liter} \\
      \DescribeUnit[minute (plane angle)]{arcminute} \\
      \DescribeUnit[minute (time)]{minute} \\
      \DescribeUnit[second (plane angle)]{arcsecond} \\
      \DescribeUnit{neper}            \\
      \DescribeUnit{tonne}            \\
    \bottomrule
  \end{tabular}
\end{table}

In addition to the units themselves, \pkg{siunitx} provides pre-defined macros
for all of the \acro{SI} prefixes (Table~\ref{tab:unit:prefix}).
The spelling \enquote{\cs{deka}} is provided for US users as an alternative to
\cs{deca}.
\begin{table}
  \caption{SI prefixes.%
    \label{tab:unit:prefix}}
  \sisetup{table-number-alignment = right, table-format = 2}
  \begin{tabular}{@{}llcS[table-format = -2]>{\qquad}llcS@{}}
    \toprule
      Prefix & Command & Symbol & \multicolumn{1}{l}{Power} &
      Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\
    \midrule
      \DescribePrefix{yocto} & -24 &
      \DescribePrefix{deca}  &   1 \\
      \DescribePrefix{zepto} & -21 &
      \DescribePrefix{hecto} &   2 \\
      \DescribePrefix{atto}  & -18 &
      \DescribePrefix{kilo}  &   3 \\
      \DescribePrefix{femto} & -15 &
      \DescribePrefix{mega}  &   6 \\
      \DescribePrefix{pico}  & -12 &
      \DescribePrefix{giga}  &  9 \\
      \DescribePrefix{nano}  &  -9 &
      \DescribePrefix{tera}  &  12 \\
      \DescribePrefix{micro} & -6 &
      \DescribePrefix{peta}  &  15 \\
      \DescribePrefix{milli} &  -3 &
      \DescribePrefix{exa}   &  18 \\
      \DescribePrefix{centi} &  -2 &
      \DescribePrefix{zetta} &  21 \\
      \DescribePrefix{deci}  &  -1 &
      \DescribePrefix{yotta} &  24 \\
    \bottomrule
  \end{tabular}
\end{table}

A small number of pre-defined powers are provided as macros. \cs{square} and
\cs{cubic} are intended for use before units, with \cs{squared} and \cs{cubed}
going after the unit.
\begin{LaTeXdemo}
  \unit{\square\becquerel} \\
  \unit{\joule\squared\per\lumen} \\
  \unit{\cubic\lux\volt\tesla\cubed}
\end{LaTeXdemo}
Generic powers can be inserted on a one-off basis using the \cs{tothe} and
\cs{raiseto} macros. These are the only macros for units which take an
argument:
\begin{LaTeXdemo}
  \unit{\henry\tothe{5}} \\
  \unit{\raiseto{4.5}\radian}
\end{LaTeXdemo}
Reciprocal powers are indicated using the \cs{per} macro. This applies to the
next unit only, unless the \opt{sticky-per} option is turned on.
\begin{LaTeXdemo}
  \unit{\joule\per\mole\per\kelvin} \\
  \unit{\joule\per\mole\kelvin} \\
  \unit{\per\henry\tothe{5}} \\
  \unit{\per\square\becquerel}
\end{LaTeXdemo}
As for generic powers, generic qualifiers are also available using the \cs{of}
function:
\begin{LaTeXdemo}
  \unit{\kilogram\of{metal}} \\
  \qty[qualifier-mode = bracket]
    {0.1}{\milli\mole\of{cat}\per\kilogram\of{prod}}
\end{LaTeXdemo}

When the \pkg{cancel} package is loaded, it is possible to \enquote{cancel out}
units using the \cs{cancel} macro. This applies to the next unit, in a similar
manner to a prefix. The \cs{highlight} macro is also available to selectively
color units. Both \cs{cancel} and \cs{highlight} are outside of the normal
semantic meaning of units, but are provided as they may be useful in some
cases.
\begin{LaTeXdemo}
  \unit[per-mode = fraction]
    {\cancel\kilogram\metre\per\cancel\kilogram\per\second} \\
  \unit{\highlight{red}\kilogram\metre\per\second} \\
  \unit[unit-color = purple]
    {\highlight{blue}\kilogram\metre\per\second}
\end{LaTeXdemo}

\subsection{Unit abbreviations}

In addition to the \enquote{full} names, \pkg{siunitx} loads a set of
abbreviated versions of the \acro{SI} units (Table~\ref{tab:unit:abbr}). The
standard \pkg{siunitx} settings only create these abbreviations within the
scope of the \cs{unit} and \cs{qty} functions, meaning that no clashes should
occur (for example with the standard \cs{pm} symbol).
\begin{center}
  \tablecaption{Unit abbreviations}
  \label{tab:unit:abbr}
  \tablefirsthead{%
    \toprule
      \multicolumn{1}{@{}l}{Unit}      &
      \multicolumn{1}{l}{Abbreviation} &
      \multicolumn{1}{l@{}}{Symbol} \\
    \midrule
  }
  \tablehead{%
    \multicolumn{3}{@{}l@{}}{\emph{Continued from previous page}} \\
    \toprule
      \multicolumn{1}{@{}l}{Unit}      &
      \multicolumn{1}{l}{Abbreviation} &
      \multicolumn{1}{l@{}}{Symbol} \\
    \midrule
  }
  \tabletail{%
    \bottomrule
    \multicolumn{3}{@{}r@{}}{\emph{Continued on next page}} \\
  }
  \tablelasttail{\bottomrule}
  \begin{xtabular}{@{}lcc@{}}
      \DescribeUnit[femtogram]{fg} \\
      \DescribeUnit[picogram]{pg}  \\
      \DescribeUnit[nanogram]{ng}  \\
      \DescribeUnit[microgram]{ug} \\
      \DescribeUnit[milligram]{mg} \\
      \DescribeUnit[gram]{g}       \\
      \DescribeUnit[kilogram]{kg}  \\

      \midrule

      \DescribeUnit[picometre]{pm}  \\
      \DescribeUnit[nanometre]{nm}  \\
      \DescribeUnit[micrometre]{um} \\
      \DescribeUnit[millimetre]{mm} \\
      \DescribeUnit[centimetre]{cm} \\
      \DescribeUnit[decimetre]{dm}  \\
      \DescribeUnit[metre]{m}       \\
      \DescribeUnit[kilometre]{km}  \\

      \midrule

      \DescribeUnit[attosecond]{as}  \\
      \DescribeUnit[femtosecond]{fs} \\
      \DescribeUnit[picosecond]{ps}  \\
      \DescribeUnit[nanosecond]{ns}  \\
      \DescribeUnit[microsecond]{us} \\
      \DescribeUnit[millisecond]{ms} \\
      \DescribeUnit[second]{s}       \\

      \midrule

      \DescribeUnit[femtomole]{fmol} \\
      \DescribeUnit[picomole]{pmol}  \\
      \DescribeUnit[nanomole]{nmol}  \\
      \DescribeUnit[micromole]{umol} \\
      \DescribeUnit[millimole]{mmol} \\
      \DescribeUnit[mole]{mol}       \\
      \DescribeUnit[kilomole]{kmol}  \\

      \midrule

      \DescribeUnit[picoampere]{pA}  \\
      \DescribeUnit[nanoampere]{nA}  \\
      \DescribeUnit[microampere]{uA} \\
      \DescribeUnit[milliampere]{mA} \\
      \DescribeUnit[ampere]{A}       \\
      \DescribeUnit[kiloampere]{kA}  \\

      \midrule

      \DescribeUnit[microlitre]{ul} \\
      \DescribeUnit[millilitre]{ml} \\
      \DescribeUnit[litre]{l}       \\
      \DescribeUnit[hectolitre]{hl} \\
      \DescribeUnit[microliter]{uL} \\
      \DescribeUnit[milliliter]{mL} \\
      \DescribeUnit[liter]{L}       \\
      \DescribeUnit[hectoliter]{hL} \\

      \midrule

      \DescribeUnit[millihertz]{mHz} \\
      \DescribeUnit[hertz]{Hz}       \\
      \DescribeUnit[kilohertz]{kHz}  \\
      \DescribeUnit[megahertz]{MHz}  \\
      \DescribeUnit[gigahertz]{GHz}  \\
      \DescribeUnit[terahertz]{THz}  \\

      \midrule

      \DescribeUnit[millinewton]{mN} \\
      \DescribeUnit[newton]{N}       \\
      \DescribeUnit[kilonewton]{kN}  \\
      \DescribeUnit[meganewton]{MN}  \\

      \midrule

      \DescribeUnit[pascal]{Pa}      \\
      \DescribeUnit[kilopascal]{kPa} \\
      \DescribeUnit[megapacal]{MPa}  \\
      \DescribeUnit[gigapascal]{GPa} \\

      \midrule

      \DescribeUnit[milliohm]{mohm} \\
      \DescribeUnit[kilohm]{kohm}   \\
      \DescribeUnit[megohm]{Mohm}   \\

      \midrule

      \DescribeUnit[picovolt]{pV}  \\
      \DescribeUnit[nanovolt]{nV}  \\
      \DescribeUnit[microvolt]{uV} \\
      \DescribeUnit[millivolt]{mV} \\
      \DescribeUnit[volt]{V}       \\
      \DescribeUnit[kilovolt]{kV}  \\

      \midrule

      \DescribeUnit[watt]{W}                \\
      \DescribeUnit[microwatt]{uW}          \\
      \DescribeUnit[milliwatt]{mW}          \\
      \DescribeUnit[kilowatt]{kW}           \\
      \DescribeUnit[megawatt]{MW}           \\
      \DescribeUnit[gigawatt]{GW}           \\
      \DescribeUnit[joule]{J}               \\
      \DescribeUnit[microjoule]{uJ}         \\
      \DescribeUnit[millijoule]{mJ}         \\
      \DescribeUnit[kilojoule]{kJ}          \\
      \DescribeUnit[electronvolt]{eV}       \\
      \DescribeUnit[millielectronvolt]{meV} \\
      \DescribeUnit[kiloelectronvolt]{keV}  \\
      \DescribeUnit[megaelectronvolt]{MeV}  \\
      \DescribeUnit[gigaelectronvolt]{GeV}  \\
      \DescribeUnit[teraelectronvolt]{TeV}  \\
      \DescribeUnit[kilowatt hour]{kWh}     \\

      \midrule

      \DescribeUnit[farad]{F}       \\
      \DescribeUnit[femtofarad]{fF} \\
      \DescribeUnit[picofarad]{pF}  \\
      \DescribeUnit[nanofarad]{nF}  \\
      \DescribeUnit[microfarad]{uF} \\

      \midrule

      \DescribeUnit[henry]{H}       \\
      \DescribeUnit[millihenry]{mH} \\
      \DescribeUnit[microhenry]{uH} \\

      \midrule

      \DescribeUnit[kelvin]{K} \\

      \midrule

      \DescribeUnit[decibel]{dB} \\

  \end{xtabular}
\end{center}

\DescribeMacro{bit}
\DescribeMacro{byte}
Binary data is expressed in units of bits and bytes. These are normally given
prefixes which use powers of two, rather than the powers of ten used by the
\acro{SI} prefixes. As these binary prefixes are closely related to the
\acro{SI} prefixes, they are defined by \pkg{siunitx}.
\begin{table}
  \caption{Binary prefixes.%
    \label{tab:unit:binary}}
  \sisetup{table-number-alignment = right, table-format = 2}
  \begin{tabular}{@{}llcS@{}}
    \toprule
      Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\ \\
    \midrule
      \DescribePrefix{kibi} & 10 \\
      \DescribePrefix{mebi} & 20 \\
      \DescribePrefix{gibi} & 30 \\
      \DescribePrefix{tebi} & 40 \\
      \DescribePrefix{pebi} & 50 \\
      \DescribePrefix{exbi} & 60 \\
      \DescribePrefix{zebi} & 70 \\
      \DescribePrefix{yobi} & 80 \\
    \bottomrule
  \end{tabular}
\end{table}

\subsection{Creating new macros}

The various macro components of a unit have to be defined before they can be
used. The package supplies a number of common definitions, but new definitions
are also possible. As the definition of a logical unit should remain the same
in a single document, these creation functions are all preamble-only.

\begin{function}{\DeclareSIUnit}
  \begin{syntax}
    \cs{DeclareSIUnit}\oarg{options}\marg{unit}\marg{symbol}
  \end{syntax}
\end{function}
New units are produced using the \cs{DeclareSIUnit} macro. The \meta{symbol}
can contain literal input, other units, multiple prefixes, powers and \cs{per},
although literal text should not be intermixed with unit macros. Units can be
created with \meta{options} from the usual list understood by \pkg{siunitx},
and apply the specific unit macro only. The (first) optional argument to
\cs{qty} and \cs{unit} can be used to override the settings for the unit: an
example is the \cs{degree} unit.
\begin{LaTeXdemo}
  \qty{3.1415}{\degree}
\end{LaTeXdemo}
 This is declared in the package (effectively) as
\begin{LaTeXdemo}[code only]
  \DeclareSIUnit[quantity-product = {}]
    \degree{\text{\textdegree}}
\end{LaTeXdemo}
 The spacing can still be altered at point of use:
\begin{LaTeXdemo}
  \qty{67890}{\degree} \\
  \qty[quantity-product = \,]{67890}{\degree}
\end{LaTeXdemo}
The meaning of a pre-defined unit can be altered by using \cs{DeclareSIUnit}
after loading \pkg{siunitx}. This will overwrite the original definition with
the newer version.

\begin{function}{\DeclareSIPrefix}
  \begin{syntax}
    \cs{DeclareSIPrefix}\marg{prefix}\marg{symbol}\marg{powers-ten}
  \end{syntax}
\end{function}
The standard \acro{SI} powers of ten are defined by the package, and are
described above. However, the user can define new prefixes with
\cs{DeclareSIPrefix}. For example, \cs{kilo} is defined
\begin{LaTeXdemo}[code only]
  \DeclareSIPrefix\kilo{k}{3}
\end{LaTeXdemo}

\begin{function}{\DeclareSIPower}
  \begin{syntax}
    \cs{DeclareSIPower}\marg{symbol-before}\marg{symbol-after}\marg{power}
  \end{syntax}
\end{function}
This function creates two symbols, one for use before a unit, the second
for use after a unit, both of which are equivalent to the \meta{power}.
For example, one might use
\begin{LaTeXdemo}[code only]
  \DeclareSIPower\quartic\tothefourth{4}
\end{LaTeXdemo}
 with the functions then used in the document as
\begin{LaTeXdemo}
  \unit{\kilogram\tothefourth}\\
  \unit{\quartic\metre}
\end{LaTeXdemo}

\begin{function}{\DeclareSIQualifier}
  \begin{syntax}
    \cs{DeclareSIQualifier}\marg{qualifier}\marg{symbol}
  \end{syntax}
\end{function}
Following the syntax of the other macros, qualifiers may be created using the
\cs{DeclareSIQualifier} command. In contrast to the other parts of a unit,
there are no pre-defined qualifiers. It is therefore entirely up to the user to
create these. For example, to identify the mass of a product created when using
a particular catalyst, the preamble could contain:
\begin{LaTeXdemo}[code only]
  \DeclareSIQualifier\polymer{pol}
  \DeclareSIQualifier\catalyst{cat}
\end{LaTeXdemo}
 and then in the body the document could read
\begin{LaTeXdemo}
  \qty{1.234}{\gram\polymer\per\mole\catalyst\per\hour}
\end{LaTeXdemo}

\subsection{Tabular material}

Aligning numbers in tabular content is handled by a new column type, the
\texttt{S} column. This new column type can align material using a number of
different strategies, with the aim of flexibility of output without needing to
alter the input. The method used as standard is to place the decimal marker in
the number at the centre of the cell and to align the material appropriately
(Table~\ref{tab:S:standard}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Standard behaviour of the \texttt{S} column type.%
      \label{tab:S:standard}}
    \begin{tabular}{@{}S@{}}
    \toprule
      {Some Values} \\
    \midrule
         2.3456 \\
        34.2345 \\
        -6.7835 \\
        90.473  \\
      5642.5    \\
          1.2e3 \\
            e4  \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

The \texttt{S} column will attempt to automatically detect material which
should be placed before or after a number, and will maintain the alignment of
the numerical data (Table~\ref{tab:S:extras}). If the material could be
mistaken for part of a number, it should be protected by braces. The use of
\cs{color} in a table cell will also be detected and will override any general
color applied by \pkg{siunitx}.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Detection of surrounding material in an \texttt{S} column.%
      \label{tab:S:extras}}
    \begin{tabular}{@{}S[color = orange]@{}}
    \toprule
      {Some Values} \\
    \midrule
      12.34 \\
      \color{purple} 975,31 \\
      44.268 \textsuperscript{\emph{a}} \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\begin{function}{\tablenum}
  \begin{syntax}
    \cs{tablenum}\oarg{options}\marg{number}
  \end{syntax}
\end{function}
Within more complex tables, aligned numbers may be desirable within the
argument of \cs{multicolumn} or \cs{multirow}.\footnote{Provided by the
\pkg{multirow} package} The \cs{tablenum} function is available to achieve
alignment in these situations: this is, in effect, a macro version of the
\texttt{S} column (Table~\ref{tab:tablenum}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Controlling complex alignment with the \cs{tablenum} macro.%
      \label{tab:tablenum}}
    \begin{tabular}{@{}lr@{}}
      \toprule
      Heading & Heading \\
      \midrule
      Info & More info \\
      Info & More info \\
      \multicolumn{2}{c}{\tablenum[table-format = 4.4]{12,34}}    \\
      \multicolumn{2}{c}{\tablenum[table-format = 4.4]{333.5567}} \\
      \multicolumn{2}{c}{\tablenum[table-format = 4.4]{4563.21}}  \\
      \bottomrule
    \end{tabular}
    \hfil
    \begin{tabular}{@{}lr@{}}
      \toprule
      Heading & Heading \\
      \midrule
      \multirow{2}*{\tablenum{88,999}} & aaa \\
                                       & bbb \\
      \multirow{2}*{\tablenum{33,435}} & ccc \\
                                       & ddd \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\section{Package control options}

\subsection{The key--value control system}

 The package uses a range of different key types:
\begin{description}
  \item[\texttt{Choice}] Takes a limited number of choices, which are described
    separately for each key.
  \item[\texttt{Integer}] Requires a number as the argument.
  \item[\texttt{Length}] Requires a length, either as a literal
    value such as \texttt{2.0cm}, or stored as a \LaTeX{} length.
  \item[\texttt{Literal}] A key which uses the value(s) given directly,
    either to check input or in output.
  \item[\texttt{Macro}] Requires a macro, which may need a single argument.
  \item[\texttt{Math}] Similar to a \texttt{literal} option, but the input is
    always used in math mode, irrespective of other \pkg{siunitx} settings.
    Thus to text-mode only input must be placed inside the argument of a
    \cs{text} macro.
  \item[\texttt{Meta}] These are options which actually apply a number of
    other options.
  \item[\texttt{Switch}] These are on--off switches, and recognise \opt{true}
    and \opt{false}.  Giving just the key name also turns the key on.
\end{description}
The tables of option names use these descriptions to indicate how the keys
should be used.

\subsection{Printing%
  \label{sec:print}}

The \pkg{siunitx} package can control the font used to print output
independently of the surrounding material. Which aspects of the font follow
those of the surroundings is influenced by a range of setting as detailed in
Table~\ref{tab:opt:print}.
\begin{table}
  \caption{Print options.%
    \label{tab:opt:print}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      color               & Literal & \meta{none} \\
      mode                & Choice  & math        \\
      number-color        & Literal & \meta{none} \\
      number-mode         & Choice  & math        \\
      propagate-math-font & Switch  & false       \\
      reset-math-version  & Switch  & true        \\
      reset-text-family   & Switch  & true        \\
      reset-text-series   & Switch  & true        \\
      reset-text-shape    & Switch  & true        \\
      text-family-to-math & Switch  & false       \\
      text-font-command   & Literal & \meta{none} \\
      text-series-to-math & Switch  & false       \\
      unit-color          & Literal & \meta{none} \\
      unit-mode           & Choice  & math        \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{mode}
\DescribeOption{number-mode}
\DescribeOption{unit-mode}
The \opt{mode} option determines whether \pkg{siunitx} uses math or text mode
when printing output. The choices are \opt{match}, \opt{math}, \opt{text}. The
\opt{match} setting means that printing uses the prevailing mode unchanged
whereas \opt{math} and \opt{text} select the appropriate \TeX{} mode. It is
possible to have different fonts in math and text modes, which will highlight
the difference. The font settings which apply are also different depending on
the mode. As well as the overall setting, it is possible to apply mode
to numbers and units separately using the \opt{number-mode} and \opt{unit-mode}
options.

\DescribeOption{reset-text-family}
\DescribeOption{reset-text-series}
\DescribeOption{reset-text-shape}
When printing in text mode, the options \opt{reset-text-family},
\opt{reset-text-series} and \opt{reset-text-shape} apply. When these are
active, \pkg{siunitx} resets the relevant font selection axis property
when printing: the standard font setting is upright mid-weight roman
(|\upshape| |\mdseries| |\rmfamily|).
\begin{LaTeXdemo}
  \sisetup{mode = text}
  {\itshape  \num{1234}}\\
  {\bfseries \num{1234}}\\
  {\sffamily \num{1234}}\\
  \sisetup{
    reset-text-family = false ,
    reset-text-series = false ,
    reset-text-shape  = false
  }
  {\itshape  \num{1234}}\\
  {\bfseries \num{1234}}\\
  {\sffamily \num{1234}}\\
\end{LaTeXdemo}

\DescribeOption{propagate-math-font}
\DescribeOption{reset-math-version}
In math mode, the font used by \LaTeX{} is \enquote{invariant}, and this is
reflected in the options available. With the standard settings, in math mode
printing uses the standard math font and version (weight). The option
\opt{propagate-math-font} may be used to apply the a prevailing math font
to the printed material. The setting \opt{reset-math-version} controls
whether the math version is reset or not. Note that math version is typically
used to set \enquote{bold math} but may also be used for other effects, for
example all sanserif math.
\begin{LaTeXdemo}
  {\boldmath \unit{\kilogram}}\\
  {\sansmath $\unit{\kilogram}$}\\
  {$\mathsf{\unit{\kilogram}}$}\\
  \sisetup{
    propagate-math-font = true  ,
    reset-math-version  = false
  }
  {\boldmath \unit{\kilogram}}\\
  {\sansmath $\unit{\kilogram}$}\\
  {$\mathsf{\unit{\kilogram}}$}
\end{LaTeXdemo}

\DescribeOption{text-family-to-math}
\DescribeOption{text-series-to-math}
The options \opt{text-family-to-math} and \opt{text-family-to-math} can be
used to match (as far as possible) math mode output to the surrounding text.
These options work by detecting the current text settings and making the
appropriate choice in math mode.
\begin{LaTeXdemo}
  {\sffamily \unit{\kilogram}}\\
  {\bfseries $\unit{\kilogram}$}\\
  \sisetup{
    text-family-to-math = true  ,
    text-series-to-math = true
  }
  {\sffamily \unit{\kilogram}}\\
  {\bfseries $\unit{\kilogram}$}
\end{LaTeXdemo}

\DescribeOption{text-font-command}
In some circumstances, it may be desirable to use a non-standard font command
when printing in text mode. This might be used for example to switch from
old-style to lining numbers whilst still using text mode. This may be achieved
by setting \opt{text-font-command}. For example, this document uses old-style
numbers in text mode as-standard, which can be over-ridden by selecting the
font variant which does not feature them.
\begin{LaTeXdemo}
  \sisetup{number-mode = text}
  \qty{123456789}{\kilo\volt\per\centi\metre} \\
  \sisetup{text-font-command = \fontfamily{pplx}\selectfont}
  \qty{123456789}{\kilo\volt\per\centi\metre}
\end{LaTeXdemo}

\DescribeOption{color}
\DescribeOption{number-color}
\DescribeOption{unit-color}
The color of printed output can be set using the \opt{color} option. When no
color is given, printing follows the surrounding text. In contrast, when a
specific color is given, it is used irrespective of the surroundings. As with
\opt{mode}, the \opt{color} setting may also be applied to numbers and units
independently.
\begin{LaTeXdemo}
  \color{red}%
  Some text \\
  \qty{4}{\kilogram} \\
  More text \\
  \qty[color = blue]{4}{\kilogram} \\
  Still red here!
\end{LaTeXdemo}

\subsection{Parsing numbers}

The package uses a sophisticated parsing system to understand numbers. This
allows \pkg{siunitx} to carry out a range of formatting, as described later.
All of the input options take lists of literal tokens, and are summarised in
Table~\ref{tab:opt:num:in}.
\begin{table}
  \caption{Options for number parsing.%
    \label{tab:opt:num:in}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      evaluate-expression     & Switch  & false            \\
      expression              & Literal & |#1|             \\^^A (
      input-close-uncertainty & Literal & )                \\
      input-comparators       & Literal &
        <=>\cs{approx}\cs{ge}\cs{geq} \\
        & & \cs{gg}\cs{le}\cs{leq}\cs{ll} \cs{sim} \\
      input-decimal-markers   & Literal & .,               \\
      input-digits            & Literal & 0123456789       \\
      input-exponent-markers  & Literal & dDeE             \\
      input-ignore            & Literal & \meta{none}      \\
      input-open-uncertainty  & Literal & (                \\ ^^A )
      input-signs             & Literal & +-\cs{pm}\cs{mp} \\
      input-uncertainty-signs & Literal & \cs{pm}          \\
      parse-numbers           & Switch  & true             \\
      retain-explicit-plus    & Switch  & false            \\
      retain-zero-uncertainty & Switch  & false            \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{input-digits}
\DescribeOption{input-decimal-markers}
\DescribeOption{input-signs}
\DescribeOption{input-exponent-markers}
The basic parts of a number are the digits, any sign and a separator between
the integer and decimal parts. These are stored in the input options
\opt{input-digits}, \opt{input-decimal-markers} and \opt{input-signs},
respectively. More than one input decimal marker can be used: it will be
converted by the package to the appropriate output marker. Numbers which
include an exponent part also require a marker for the exponent: this again is
taken from the range of tokens in the \opt{input-exponent-markers} option.

\DescribeOption{input-ignore}
Tokens given in the \opt{input-ignore} list are totally passed over by
\pkg{siunitx}: they will be removed from the input with no further processing.

\DescribeOption{input-comparators}
In addition to signs, \pkg{siunitx} can recognise comparators, such as |<|. The
package will automatically carry out conversions for |<<|, |>>|, |<=| and |>=|
to |\ll|, |\gg|, |\le| and |\ge|, respectively.
\begin{LaTeXdemo}
  \num{< 10} \\
  \qty{>> 5}{\metre} \\
  \num{\le 0.12}
\end{LaTeXdemo}

\DescribeOption{input-open-uncertainty}
\DescribeOption{input-close-uncertainty}
\DescribeOption{input-uncertainty-signs}
In some fields, it is common to give the uncertainty in a number in brackets
after the main part of the number, for example \enquote{\num{1.234(5)}}. The
opening and closing symbols used for this type of input are set as
\opt{input-open-uncertainty} and \opt{input-close-uncertainty}. Alternatively,
the uncertainty may be given as a separate part following a sign. Which signs
are valid for this operation is determined by the \opt{input-uncertainty-signs}
option. As with other signs, the combination |+-| will automatically be
converted to |\pm| internally.
\begin{LaTeXdemo}
  \num{9.99(9)}       \\
  \num{9.99 +- 0.09}  \\
  \num{9.99 \pm 0.09} \\
  \num{123 +- 4.5}    \\
  \num{12.3 +- 6}
\end{LaTeXdemo}

Uncertainties which cross the decimal marker may be given with or without a
decimal marker in \enquote{compact} form. These are treated as equivalent by
the code.\footnote{The package author favors the form without a decimal marker,
and formal guidance is ambiguous on which is correct. The form with a decimal
marker is seen in for example some \acro{NIST} publications.}
\begin{LaTeXdemo}
  \num{123.4(12)} \\
  \num{123.4(1.2)}
\end{LaTeXdemo}

\DescribeOption{parse-numbers}
The \opt{parse-numbers} option turns the entire parsing system on and off. The
option is made available for two reasons. First, if all of the numbers in a
document are to be reproduced \enquote{as given}, turning off the parser will
represent a significant saving in processing required. Second, it allows the
use of arbitrary \TeX{} code in numbers. If the parser is turned off, the input
will be printed in math mode (requiring |\text| to protect any text in the
number).
\begin{LaTeXdemo}
  \num[parse-numbers = false]{\sqrt{2}}        \\
  \qty[parse-numbers = false]{\sqrt{3}}{\metre}
\end{LaTeXdemo}

\DescribeOption{evaluate-expression}
\DescribeOption{expression}
With the standard settings, numerical input is parsed \enquote{as is} with no
attempt to interpret it mathematically. By enabling the
\opt{evaluate-expression} option, the input can be processed by the standard
\LaTeX3 \acro{FPU} (see package \pkg{xfp} for more). The nature of the
expression itself can be adjusted using the \opt{expression} setting: as
standard, the entire input is simply parsed with no change, but this setting
may be used to add additional steps. The \emph{input} in such an expression is
represented by |#1|. Note that the \acro{FPU} uses its own syntax for numbers,
most notably in that a decimal marker must be |.|.
\begin{LaTeXdemo}
  \sisetup{evaluate-expression}%
  \qty{2 + 4 * 3}{\joule} \\
  \qty[expression = 10 * (#1)]{2 + 4 * 3}{\joule}
\end{LaTeXdemo}

\DescribeOption{retain-explicit-plus}
\DescribeOption{retain-zero-uncertainty}
The inclusion of a leading plus sign is usually unnecessary for positive
numbers, and so they are not retained as-standard when parsing. The
\opt{retain-explicit-plus} option is available to control this behaviour.
Similarly, an uncertainty of zero is normally not meaningful, and so is
ignored by the parser. This can be controlled using the
\opt{retain-zero-uncertainty} option.
\begin{LaTeXdemo}
  \num{+345} \\
  \num[retain-explicit-plus]{+345} \\
  \num{12.3(0)} \\
  \num[retain-zero-uncertainty]{12.3(0)}
\end{LaTeXdemo}

\subsection{Post-processing numbers}

Before typesetting numbers, various post-processing steps can be carried out.
These involve adding or removing information from the number in a systematic
way; the options are summarised in Table~\ref{tab:opt:num:post}.
\begin{table}
  \caption{Number post-processing options.%
    \label{tab:opt:num:post}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      drop-exponent          & Switch  & false       \\
      drop-uncertainty       & Switch  & false       \\
      drop-zero-decimal      & Switch  & false       \\
      exponent-mode          & Switch  & input       \\
      fixed-exponent         & Integer & 0           \\
      minimum-integer-digits & Integer & 0           \\
      minimum-decimal-digits & Integer & 0           \\
      round-half             & Choice  & up          \\
      round-minimum          & Literal & 0           \\
      round-mode             & Choice  & none        \\
      round-pad              & Switch  & true        \\
      round-precision        & Integer & 2           \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{exponent-mode}
\DescribeOption{fixed-exponent}
Numbers can be converted to scientific notation by the package. This is
controlled by the \opt{exponent-mode} option, which takes choices \opt{input},
\opt{fixed}, \opt{engineering} and \opt{scientific}. The \opt{fixed} setting
will use the exponent value by the \opt{fixed-exponent} option. When
\opt{engineering} is set, the exponent is always a power of three.
\begin{LaTeXdemo}
  \num{0.001}  \\
  \num{0.0100} \\
  \num{1200}   \\
  \sisetup{exponent-mode = scientific}%
  \num{0.001}  \\
  \num{0.0100} \\
  \num{1200}   \\
  \sisetup{exponent-mode = engineering}%
  \num{0.001}  \\
  \num{0.0100} \\
  \num{1200}   \\
  \sisetup{
    exponent-mode  = fixed,
    fixed-exponent = 2,
  }%
  \num{0.001}  \\
  \num{0.0100} \\
  \num{1200}
\end{LaTeXdemo}
When used with a \opt{fixed-exponent} of zero, this may be used to remove
scientific notation from the input
\begin{LaTeXdemo}
  \num{1.23e4} \\
  \num[exponent-mode = fixed, fixed-exponent = 0]{1.23e4}
\end{LaTeXdemo}
Exponent mode applies \emph{after} rounding, such that the number of decimal
places for rounding is those which appear in the output.

\DescribeOption{drop-exponent}
\DescribeOption{drop-uncertainty}
The use of an uncertainty can be suppressed entirely using the
\opt{drop-uncertainty} option: this applies \emph{before} rounding is
attempted. Similarly, exponents can be dropped using \opt{drop-exponent} can be
used to suppress the exponent part (\emph{after} conversion to a fixed
exponent).
\begin{LaTeXdemo}
  \num{0.01(2)} \\
  \num[drop-uncertainty]{0.01(2)} \\
   \num{0.01e3} \\
  \num[drop-exponent]{0.01e3}
\end{LaTeXdemo}

\DescribeOption{round-mode}
\DescribeOption{round-precision}
\DescribeOption{round-pad}
The package can round numerical input to a fixed number of significant figures
or decimal places. This is controlled by the \opt{round-mode} option, which
takes the choices \opt{none}, \opt{figures}, \opt{places} and
\opt{uncertainty}. When rounding is turned on, the number of digits used
(either decimal places or significant figures in the mantissa) is set using the
\opt{round-precision} option. Rounding numbers with uncertainties may be
carried out using the \opt{uncertainty} setting to \opt{round-mode}. In this
case the precision is used first to round the uncertainty itself (to a number
of figures), before rounding the main value to follow.
\begin{LaTeXdemo}
  \num{1.23456}     \\
  \num{14.23}      \\
  \num{0.12345(9)} \\
  \sisetup{
    round-mode      = places,
    round-precision = 3
  }%
  \num{1.23456}     \\
  \num{14.23}      \\
  \num{0.12345(9)} \\
  \sisetup{
    round-mode      = figures,
    round-precision = 3
  }%
  \num{1.23456}     \\
  \num{14.23}      \\
  \num{0.12345(9)} \\
  \sisetup{
    round-mode      = uncertainty,
    round-precision = 1
  }%
  \num{0.12345(9)}   \\
  \num{0.12345(23)}  \\
  \num{0.12345(234)}
\end{LaTeXdemo}
Rounding my \enquote{extend} a short number to more digits (or figures): this
is controlled by the switch \opt{round-pad}, which is \opt{true} as standard.
\begin{LaTeXdemo}
  \sisetup{round-mode = figures, round-precision = 4}%
  \num{12.3} \\
  \num[round-pad = false]{12.3}
\end{LaTeXdemo}

\DescribeOption{round-half}
In cases where the rounded part of a number is exactly half, there are two
common methods for \enquote{breaking the tie}. The choice of method is
determined by the option \opt{round-half}, which recognises the choices
\opt{up} and \opt{even}.
\begin{LaTeXdemo}
  \sisetup{
    round-mode      = figures,
    round-precision = 1,
    round-half      = up
  }%
  \num{0.055} \\
  \num{0.045} \\
  \sisetup{round-half = even}%
  \num{0.055} \\
  \num{0.045}
\end{LaTeXdemo}

\DescribeOption{round-minimum}
There are cases in which rounding will result in the number reaching zero. It
may be desirable to show such results as below a threshold value. This can be
achieved by setting \opt{round-minimum} to the threshold value. There will be
no effect when rounding to a number of significant figures as it is not
possible to obtain the value zero in these cases.
\begin{LaTeXdemo}
  \sisetup{round-mode = places}%
  \num{0.0055} \\
  \num{0.0045} \\
  \sisetup{round-minimum = 0.01}%
  \num{0.0055} \\
  \num{0.0045}
\end{LaTeXdemo}

\DescribeOption{drop-zero-decimal}
It may be desirable to convert decimals to integers when the decimal part is
zero. This is set up using the \opt{drop-zero-decimal} option, which applies
after rounding but before setting minimum numbers of digits.
\begin{LaTeXdemo}
  \num{2.0} \\
  \num{2.1} \\
  \sisetup{drop-zero-decimal}%
  \num{2.0} \\
  \num{2.1}
\end{LaTeXdemo}

\DescribeOption{minimum-decimal-digits}
\DescribeOption{minimum-integer-digits}
The \opt{minimum-decimal-digits} and \opt{minimum-integer-digits} option may be
used to pad numbers to a given size. This applies independent of any rounding.
\begin{LaTeXdemo}
  \num{123} \\
  \num[minimum-integer-digits = 2]{123} \\
  \num[minimum-integer-digits = 4]{123} \\
  \num{0.123} \\
  \num[minimum-decimal-digits = 2]{0.123} \\
  \num[minimum-decimal-digits = 4]{0.123} \\
\end{LaTeXdemo}

\subsection{Printing numbers}

Actually printing numbers is controlled by a number of settings, which apply
ideas such as differing decimal markers, digit grouping and so on. All of these
options are concerned with the appearance of output, rather than the data it
conveys. The options are summarised in Table~\ref{tab:opt:num:out}.
\begin{table}
  \caption{Output options for numbers.%
    \label{tab:opt:num:out}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{l}{Option name} &
      Type &
      \multicolumn{1}{l}{Default} \\
    \midrule
      bracket-negative-numbers & Switch  & false             \\
      exponent-base            & Literal & 10                \\
      exponent-product         & Math    & \verb=\times=     \\
      group-digits             & Choice  & all               \\
      group-minimum-digits     & integer & 5                 \\
      group-separator          & Literal & \cs{,}            \\
      negative-color           & Literal & \meta{none}       \\ ^^A (
      output-close-uncertainty & Literal & )                 \\
      output-decimal-marker    & Literal & .                 \\
      output-exponent-marker   & Literal & \meta{none}       \\
      output-open-uncertainty  & Literal & (                 \\ ^^A )
      print-implicit-plus      & Switch  & false             \\
      print-unity-mantissa     & Switch  & true              \\
      print-zero-exponent      & Switch  & false             \\
      tight-spacing            & Switch  & false             \\
      uncertainty-mode         & Choice  & compact           \\
      uncertainty-separator    & Literal & \meta{none}       \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{group-digits}
\DescribeOption{group-four-digits}
\DescribeOption{group-separator}
Grouping digits into blocks of three is a common method to increase the ease of
reading of numbers. The \opt{group-digits} choice controls whether this
behaviour applies, and takes the values \opt{all}, \opt{none}, \opt{decimal}
and \opt{integer}. Grouping can be activated separately for the integer and
decimal parts of a number using the appropriately-named values.
\begin{LaTeXdemo}
  \num{12345.67890} \\
  \num[group-digits = none]{12345.67890}   \\
  \num[group-digits = decimal]{12345.67890} \\
  \num[group-digits = integer]{12345.67890}
\end{LaTeXdemo}
The separator used between groups of digits is stored by the
\opt{group-separator} option. This takes literal input and may be used in math
mode: for a text-mode full space use \verb*|\ |.
\begin{LaTeXdemo}
  \num{12345} \\
  \num[group-separator = {,}]{12345} \\
  \num[group-separator = \ ]{12345}
\end{LaTeXdemo}

\DescribeOption{group-minimum-digits}
Grouping is not always applied to smaller numbers; this can be controlled using
the option \opt{group-minimum-digits}, which specifies how many digits must be
present before grouping is applied. The number of digits is considered
separately for the integer and decimal parts of the number: grouping does not
\enquote{cross the boundary}.
\begin{LaTeXdemo}
  \num{1234} \\
  \num{12345} \\
  \num[group-minimum-digits = 5]{1234} \\
  \num[group-minimum-digits = 5]{12345} \\
  \num{1234.5678} \\
  \num{12345.67890} \\
  \num[group-minimum-digits = 5]{1234.5678} \\
  \num[group-minimum-digits = 5]{12345.67890}
\end{LaTeXdemo}

\DescribeOption{output-decimal-marker}
The decimal marker used in output is set using the \opt{output-decimal-marker}
option; this can differ from the input marker.
\begin{LaTeXdemo}
  \num{1.23} \\
  \num[output-decimal-marker = {,}]{1.23} \\
\end{LaTeXdemo}

\DescribeOption{exponent-base}
\DescribeOption{exponent-product}
When exponents are present in the input, the \opt{exponent-base} and
\opt{exponent-product} options set the obvious parts of the output.
\begin{LaTeXdemo}
  \num[exponent-product = \times]{1e2} \\
  \num[exponent-product = \cdot]{1e2} \\
  \num[exponent-base = 2]{1e2}
\end{LaTeXdemo}
\DescribeOption{output-exponent-marker}
Alternatively, if the \opt{output-exponent-marker} option is set then the value
stored will be used in place of the normal product and base combination.
\begin{LaTeXdemo}
  \num[output-exponent-marker = e]{1e2} \\
  \num[output-exponent-marker = \mathrm{E}]{1e2}
\end{LaTeXdemo}

\DescribeOption{uncertainty-separator}
\DescribeOption{output-open-uncertainty}
\DescribeOption{output-close-uncertainty}
\DescribeOption{uncertainty-separator}
When input is given including an uncertainty in a number, it can be printed
either with the uncertainty in brackets or as a separate number. This behaviour
is controlled by the \opt{uncertainty-mode} choice.When this is set to
\opt{separate}, the uncertainty is printed as an entirely separate number
preceded by \cs{pm}. Other settings all place the uncertainty in brackets
directly attached to the main value. The standard setting of \opt{compact}
prints digits of uncertainty in the least-significant digits. It does
\emph{not} print a decimal marker if the uncertainty crosses the decimal. The
setting \opt{full} prints the full value of the uncertainty. Finally,
\opt{compact-marker} is available to print in the \opt{compact} style except
where the uncertainty crosses the decimal, in which case the \opt{full} style
is used. When the uncertainty is given in brackets, a space may be added
between the main number and the uncertainty: this is stored using the
\opt{uncertainty-separator} option. The opening and closing brackets used are
stored in \opt{output-open-uncertainty} and \opt{output-close-uncertainty},
respectively. Tokens may be inserted before the opening bracket using
\opt{uncertainty-separator}.
\begin{LaTeXdemo}
  \num{123.45(120)} \\
  \num{0.035(14)}   \\
  \sisetup{uncertainty-mode = full}
  \num{123.45(120)} \\
  \num{0.035(14)}   \\
  \sisetup{uncertainty-mode = compact-marker}
  \num{123.45(120)} \\
  \num{0.035(14)}   \\
  \sisetup{uncertainty-mode = separate}
  \sisetup{
    output-open-uncertainty  = [,
    output-close-uncertainty = ],
    uncertainty-separator    = \,
  }%
  \num{1.234(5)}
\end{LaTeXdemo}

\DescribeOption{bracket-ambiguous-numbers}
There are certain combinations of numerical input which can be ambiguous. This
can be corrected by adding brackets in the appropriate place, and is controlled
by the \opt{bracket-ambiguous-numbers} switch. This option only applies to pure
numbers: when formatting quantities, the need for brackets also depends on the
placement of units, so is controlled by \opt{separate-uncertainty-units}.
\begin{LaTeXdemo}
  \sisetup{separate-uncertainty}
  \num{1.2(3)e4} \\
  \num[bracket-ambiguous-numbers = false]{1.2(3)e4}
\end{LaTeXdemo}

\DescribeOption{negative-color}
The package can detect negative mantissa values and alter print color
accordingly. This is disabled by setting the option to an empty value.
\begin{LaTeXdemo}
  \num{-15673} \\
  \num[negative-color = red]{-15673}
\end{LaTeXdemo}

\DescribeOption{bracket-negative-numbers}
A common means to display negative numbers in financial situations is to place
them in brackets. This can be carried out automatically using the
\opt{bracket-negative-numbers} option.
\begin{LaTeXdemo}
  \num{-15673} \\
  \num[bracket-negative-numbers]{-15673} \\
  \qty{-10}{\metre} \\
  \qty[bracket-negative-numbers]{-10}{\metre}
\end{LaTeXdemo}

\DescribeOption{tight-spacing}
Under some circumstances is may be desirable to \enquote{squeeze} the output
spacing. This is turned on using the \opt{tight-spacing} switch, which
compresses spacing where possible.
\begin{LaTeXdemo}
  \num{2e3} \\
  \num[tight-spacing = true]{2e3}
\end{LaTeXdemo}

\DescribeOption{print-implicit-plus}
It may be useful to force all numbers to have a sign. This behaviour is
controlled by the \opt{print-implicit-plus} option: this is used if given and
if no sign was present in the input.
\begin{LaTeXdemo}
  \num{345} \\
  \num[print-implicit-plus]{345}
\end{LaTeXdemo}

\DescribeOption{print-unity-mantissa}
\DescribeOption{print-zero-exponent}
Printing of a mantissa of $1$ and an exponent of $0$ is controllable by the
options \opt{print-unity-mantissa} and \opt{print-zero-exponent}. The standard
settings print a mantissa of $1$ but omit an exponent of $0$.
\begin{LaTeXdemo}
  \num{1e4} \\
  \num[print-unity-mantissa = false]{1e4} \\
  \num{444e0} \\
  \num[print-zero-exponent = true]{444e0}
\end{LaTeXdemo}

\subsection{Lists, products and ranges}

Lists, products and ranges of numbers and quantities have a small number of
specialised options, which apply to these more unusual input forms
(Table~\ref{tab:opt:num:list}).
\begin{table}
  \begin{threeparttable}
    \caption{Output options for lists, products and ranges of numbers and
      quantities.%
      \label{tab:opt:num:list}}
    \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
      \toprule
        \multicolumn{1}{l}{Option name} &
        Type &
        \multicolumn{1}{l}{Default\tnote{*}} \\
      \midrule
        list-exponents       & Choice  & individual           \\
        list-final-separator & Literal & \verb*= \text{and} = \\
        list-pair-separator  & Literal & \verb*= \text{and} = \\
        list-separator       & Literal & \verb*=\text{,} =    \\
        list-units           & Choice  & repeat               \\
        product-exponents    & Choice  & individual           \\
        product-mode         & Choice  & symbol               \\
        product-phrase       & Literal & \verb*= \text{by} =  \\
        product-symbol       & Literal & \cs{times}           \\
        product-units        & Choice  & repeat               \\
        range-exponents      & Choice  & individual           \\
        range-phrase         & Literal & \verb*= \text{to} =  \\
        range-units          & Choice  & repeat               \\
      \bottomrule
    \end{tabular}
    \footnotesize
    \begin{tablenotes}
      \item[*] The default values are actually more complex for two
        reasons: allowing spaces to work in both math and text modes,
        and localization of strings.
    \end{tablenotes}
  \end{threeparttable}
\end{table}

\DescribeOption{list-final-separator}
\DescribeOption{list-pair-separator}
\DescribeOption{list-separator}
Lists of numbers are printed with a separator between each item, which is
stored using the \opt{list-separator} option. The separator before the last
item of a list may be different, and is therefore set using the
\opt{list-final-separator} option. The separator used for exactly two items is
set using the \opt{list-pair-separator} option. Any spaces needed should be
included in the option settings: none are added within the code. The separators
are always printed in text mode.
\begin{LaTeXdemo}
  \numlist{0.1;0.2;0.3}                              \\
  \numlist[list-separator = {; }]{0.1;0.2;0.3}       \\
  \numlist[list-final-separator = {, }]{0.1;0.2;0.3} \\
  \numlist[
    list-separator       = { and },
    list-final-separator = { and finally }
  ]{0.1;0.2;0.3} \\
  \numlist{0.1;0.2} \\
  \numlist[list-pair-separator = {, and }]{0.1;0.2}
\end{LaTeXdemo}

\DescribeOption{product-mode}
\DescribeOption{product-phrase}
\DescribeOption{product-symbol}
Products of numbers can be output using either a product symbol or phrase:
this is controlled by the \opt{product-mode} setting. When \opt{symbol} is
set, the appropriate symbol is stored in \opt{product-symbol}. When using
\opt{phrase-mode}, the information is stored in \opt{product-phrase}. Phrases
are always printed in text mode; symbols are printed using the same routine
as for numbers.
\begin{LaTeXdemo}
  \numproduct{5 x 100 x 2} \\
  \numproduct[product-symbol = \ensuremath{\cdot}]{5 x 100 x 2} \\
  \sisetup{product-mode = phrase}%
  \numproduct{5 x 100 x 2}\\
  \numproduct[product-phrase = { BY }]{5 x 100 x 2} \\
\end{LaTeXdemo}

\DescribeOption{range-phrase}
Ranges of numbers can be given as input. These will have an appropriate word or
symbol inserted between the two entries: this is stored using the
\opt{range-phrase} option. The phrase should include any necessary spaces: no
extra space is added. The phrase is always printed in text mode.
\begin{LaTeXdemo}
  \numrange{5}{100} \\
  \numrange[range-phrase = --]{5}{100}
\end{LaTeXdemo}

\DescribeOption{list-exponents}
\DescribeOption{product-exponents}
\DescribeOption{range-exponents}
Lists, products and ranges can be \enquote{compressed} by combining the
exponent parts. This is controlled by the options \opt{list-exponents},
\opt{product-exponents} and \opt{range-exponents}, all of which take the
choices \opt{individual}, \opt{combine-bracket} and \opt{combine}. The standard
setting, \opt{individual}, leaves the exponent with the matching value. Both
\opt{combine} and \opt{combine-bracket} take the exponent of the first entry
and apply to to all other entries, with the exponent itself places at the end.
\begin{LaTeXdemo}
  \numlist{5e3;7e3;9e3;1e4} \\
  \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
  \numrange{5e3}{7e3} \\
  \sisetup
    {
      list-exponents    = combine-bracket ,
      product-exponents = combine-bracket ,
      range-exponents   = combine-bracket
    }
  \numlist{5e3;7e3;9e3;1e4} \\
  \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
  \numrange{5e3}{7e3} \\
  \sisetup
    {
      list-exponents    = combine ,
      product-exponents = combine ,
      range-exponents   = combine
    }
  \numlist{5e3;7e3;9e3;1e4} \\
  \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
  \numrange{5e3}{7e3}
\end{LaTeXdemo}

\DescribeOption{list-units}
\DescribeOption{product-units}
\DescribeOption{range-units}
The \opt{list-units}, \opt{product-units} and \opt{range-units} options
determine how \cs{qtylist}, \cs{qtyproduct} and \cs{qtyrange} command print
units, respectively. The standard setting for these is \opt{repeat}, where each
number will be printed with a unit. Alternatives are \opt{bracket} and
\opt{single}. If set to \opt{single}, this will override collection of
exponents.
\begin{LaTeXdemo}
  \qtylist{2;4;6;8}{\tesla} \\
  \qtylist[list-units = bracket]{2;4;6;8}{\tesla} \\
  \qtylist[list-units = repeat]{2;4;6;8}{\tesla} \\
  \qtylist[list-units = single]{2;4;6;8}{\tesla} \\
  \qtyrange{2}{4}{\degreeCelsius} \\
  \qtyrange[range-units = bracket]{2}{4}{\degreeCelsius} \\
  \qtyrange[range-units = repeat]{2}{4}{\degreeCelsius} \\
  \qtyrange[range-units = single]{2}{4}{\degreeCelsius}
\end{LaTeXdemo}

\subsection{Complex numbers}

A small number of options apply specifically to the handling of complex
numbers; these are summarised in Table~\ref{tab:opt:num:complex}.
\begin{table}
  \caption{Options for complex numbers.%
    \label{tab:opt:num:complex}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      complex-root-position & Choice  & after-number      \\
      input-complex-root    & Literal & ij                \\
      output-complex-root   & Literal & \verb=\mathrm{i}= \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{input-complex-root}
When using complex numbers in input, the complex root $(\mathrm{i} =
\sqrt{-1}\,)$ is indicated by one of the tokens stored in
\opt{input-complex-roots}. The parser understands complex root symbols given
either before or after the associated number (but will detect any invalid
arrangement):
\begin{LaTeXdemo}
  \complexnum{9.99 + 88.8i} \\
  \complexnum{9.99 + i88.8}
\end{LaTeXdemo}

\DescribeOption{output-complex-root}
The output complex root symbol is independent of the input and can be changed
using the \opt{output-complex-root} setting.
\begin{LaTeXdemo}
  \complexnum[output-complex-root = i]{1+2i} \\
  \complexnum[output-complex-root = j]{1+2i}
\end{LaTeXdemo}

\DescribeOption{complex-root-position}
 The position of the complex root can be adjusted to place it
 either before or after the associated numeral in a complex number
 using the \opt{complex-root-position} option.
\begin{LaTeXdemo}
  \complexnum{67-0.9i} \\
  \complexnum[complex-root-position = before-number]{67-0.9i} \\
  \complexnum[complex-root-position = after-number]{67-0.9i}
\end{LaTeXdemo}

\subsection{Angles}

Angle processing provided by the \cs{ang} function has a set of options which
apply in addition to the general ones set up for number processing.
\begin{table}
  \caption{Angle options.%
    \label{tab:opt:ang}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      angle-mode                & Choice  & input          \\
      angle-symbol-degree       & Literal & \cs{degree}    \\
      angle-symbol-minute       & Literal & \cs{arcminute} \\
      angle-symbol-over-decimal & Switch  & false          \\
      angle-symbol-second       & Literal & \cs{arcsecond} \\
      angle-separator           & Literal & \meta{empty}   \\
      fill-angle-degrees        & Switch  & false          \\
      fill-angle-minutes        & Switch  & false          \\
      fill-angle-seconds        & Switch  & false          \\
      number-angle-product      & Literal & \meta{empty}   \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{angle-mode}
The format in which angles are printed can be set using the \opt{angle-mode}
option. With the standard setting (\opt{input}), the angle is printed as-given.
By setting the option to \opt{arc} or \opt{decimal}, the output format can
be set to an arc (degrees/minutes/seconds) or decimal value. Conversion uses
the \LaTeX3 floating-point unit, so is limited to $16$ decimal places.
\begin{LaTeXdemo}
  \ang{2.67} \\
  \ang{2;3;4} \\
  \ang[angle-mode = arc]{2.67} \\
  \ang[angle-mode = arc]{2;3;4} \\
  \ang[angle-mode = decimal]{2.67} \\
  \ang[angle-mode = decimal]{2;3;4} \\
\end{LaTeXdemo}

\DescribeOption{number-angle-product}
The separator between the number and angle symbol (degrees, minutes or seconds)
can be set using the \opt{number-angle-product} option, independent of the
related \opt{number-unit-product} option used by the \cs{qty} command.
\begin{LaTeXdemo}
  \ang{2.67} \\
  \ang[number-angle-product = \,]{2.67}
\end{LaTeXdemo}

\DescribeOption{angle-separator}
When angles are printed in arc format, the separation of the different parts is
set up using the \opt{arc-separator} option.
\begin{LaTeXdemo}
  \ang{6;7;6.5} \\
  \ang[angle-separator = \,]{6;7;6.5}
\end{LaTeXdemo}

\DescribeOption{fill-angle-degrees}
\DescribeOption{fill-angle-minutes}
\DescribeOption{fill-angle-seconds}
Zero-filling for the degree, minute or second parts of an arc is controlled
using the \opt{fill-angle-degrees}, \opt{fill-angle-minutes} and
\opt{fill-angle-seconds} options. All are off as standard.
\begin{LaTeXdemo}
  \ang{-1;;} \\
  \ang{;-2;} \\
  \ang{;;-3} \\
  {
    \sisetup{fill-angle-degrees}
    \ang{-1;;} \\
    \ang{;-2;} \\
    \ang{;;-3} \\
  }
  {
    \sisetup{fill-angle-minutes}
    \ang{-1;;} \\
    \ang{;-2;} \\
    \ang{;;-3} \\
  }
  {
    \sisetup{fill-angle-seconds}
    \ang{-1;;} \\
    \ang{;-2;} \\
    \ang{;;-3}
  }
\end{LaTeXdemo}

\DescribeOption{angle-symbol-degree}
\DescribeOption{angle-symbol-minute}
\DescribeOption{angle-symbol-second}
With the standard settings, the symbols used for arc angles are the unit
commands \cs{degree}, \cs{arcminute} and \cs{arcsecond}. These can be altered
using \opt{angle-symbol-degree}, \opt{angle-symbol-minute} and
\opt{angle-symbol-second}. This is most likely to be used when the definition
of the unit macros is altered, for example to set \cs{arcsecond} as
\texttt{as}.
\begin{LaTeXdemo}
  \ang{6;7;6.5} \\
  \sisetup{
    angle-symbol-degree = d ,
    angle-symbol-minute = m ,
    angle-symbol-second = s
  }
  \ang{6;7;6.5}
\end{LaTeXdemo}

\DescribeOption{angle-symbol-over-decimal}
In some subject areas, most notably astronomy, the angle symbols are given over
the decimal marker, rather than at the end of the number. This behaviour is
available using the \opt{angle-symbol-over-decimal} option.
\begin{LaTeXdemo}
  \ang{45.697}  \\
  \ang{6;7;6.5} \\
  \ang[angle-symbol-over-decimal]{45.697} \\
  \ang[angle-symbol-over-decimal]{6;7;6.5}
\end{LaTeXdemo}

\subsection{Creating units%
  \label{sec:units:creating}}

The various macro units are created at the start of the document. \pkg{siunitx}
can define these such that they are only available for use within the \cs{unit}
and \cs{qty} functions, or can make the unit macros available throughout the
document body. There are a number of settings which control this creation
process (Table~\ref{tab:opt:units:def}). As a result, these options all apply
in the preamble only.
\begin{table}
  \caption{Unit creation options.%
    \label{tab:opt:units:def}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      free-standing-units    & Switch & false \\
      overwrite-command      & Switch & false \\
      space-before-unit      & Switch & false \\
      unit-optional-argument & Switch & false \\
      use-xspace             & Switch & false \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{free-standing-units}
\DescribeOption{overwrite-functions}
The \opt{free-standing-units} option controls whether the unit macros exist
outside of the \cs{unit} and \cs{qty} arguments. When this option is
\opt{true}, \pkg{siunitx} creates the macros for general use. The standard
method to achieve this does not overwrite any existing macros: this behaviour
can be altered using the \opt{overwrite-commands} switch.

\DescribeOption{space-before-unit}
\DescribeOption{unit-optional-argument}
\DescribeOption{use-xspace}
When \enquote{free standing} unit macros are created, their behaviour can be
adjusted by a number of options. These are mainly intended for emulating the
input syntax of older packages. The option \opt{unit-optional-argument} gives
the same behaviour for the inputs
\begin{LaTeXdemo}[code only]
  \qty{10}{\metre}
\end{LaTeXdemo}
and
\begin{LaTeXdemo}[code only]
  \metre[10].
\end{LaTeXdemo}
The \opt{space-before-unit} and \opt{use-xspace} options control the behaviour
at the \enquote{ends} of the unit macros. Activating \opt{space-before-unit}
inserts the number--unit space before the unit is printed. This is suitable for
the input syntax
\begin{LaTeXdemo}[code only]
  30\metre
\end{LaTeXdemo}
but does mean that the unit macros are incorrectly spaced in running text. On
the other hand, the \opt{use-xspace} option attempts to correctly space input
such as
\begin{LaTeXdemo}[code only]
  \metre is the symbol for metres.
\end{LaTeXdemo}

\subsection{Using units}

Part of the power of \pkg{siunitx} is the ability to alter the output format
for units without changing the input. The behaviour of units is therefore
controlled by a number of options which alter either the processing of units or
the output directly (Table~\ref{tab:opt:units:out}).
\begin{table}
  \centering
  \caption{Unit output options.%
    \label{tab:opt:units:out}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      bracket-unit-denominator & Switch  & true         \\
      forbid-literal-units     & Switch  & false        \\
      inter-unit-product       & Literal & \cs{,}       \\
      parse-units              & Switch  & true         \\
      per-mode                 & Choice  & power        \\
      per-symbol               & Literal & /            \\
      qualifier-mode           & Choice  & subscript    \\
      qualifier-phrase         & Literal & \meta{empty} \\
      sticky-per               & Switch  & false        \\
      unit-font-command        & Literal & \cs{mathrm}  \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{inter-unit-product}
The separator between each unit is stored using the \opt{inter-unit-product}
option. The standard setting is a thin space: another common choice is a
centred dot. To get the correct spacing it is necessary to use
|\ensuremath{{}\cdot{}}| in the latter case.
\begin{LaTeXdemo}
  \unit{\farad\squared\lumen\candela} \\
  \unit[inter-unit-product = \ensuremath{{}\cdot{}}]
    {\farad\squared\lumen\candela}
\end{LaTeXdemo}

\DescribeOption{per-mode}
\DescribeOption{per-symbol}
\DescribeOption{bracket-unit-denominator}
The handling of \cs{per} is altered using the \opt{per-mode} choice option. The
standard setting is \opt{power}, meaning that \cs{per} generates reciprocal
powers for units. Setting the option to \opt{fraction} uses the |\frac|
function to typeset the positive and negative powers of a unit separately.
\begin{LaTeXdemo}
  \unit{\joule\per\mole\per\kelvin} \\
  \unit{\metre\per\second\squared} \\
  \unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\
  \unit[per-mode = fraction]{\metre\per\second\squared}
\end{LaTeXdemo}
The closely-related \opt{power-positive-first} setting acts in the same way but
places all of the positive powers before any negative ones.
\begin{LaTeXdemo}
  \unit{\ampere\per\mole\second} \\
  \unit[per-mode = power-positive-first]
    {\ampere\per\mole\second}
\end{LaTeXdemo}
It is possible to use a symbol (usually |/|) to separate the two parts of a
unit by setting \opt{per-mode} to \opt{symbol}; the symbol used is stored using
the setting \opt{per-symbol}. This method for displaying units can be
ambiguous, and so brackets are added unless \opt{bracket-unit-denominator} is
set to \opt{false}. Notice that \opt{bracket-unit-denominator} only applies
when \opt{per-mode} is set to \opt{symbol} or \opt{symbol-or-fraction}.
\begin{LaTeXdemo}
  \sisetup{per-mode = symbol}%
  \unit{\joule\per\mole\per\kelvin} \\
  \unit{\metre\per\second\squared} \\
  \unit[per-symbol = \ \text{div}\ ]{\joule\per\mole\per\kelvin} \\
  \unit[bracket-unit-denominator = false]{\joule\per\mole\per\kelvin}
\end{LaTeXdemo}
The often-requested (but mathematically invalid) \opt{repeated-symbol} option
is also available to repeat the symbol for each \cs{per}.
\begin{LaTeXdemo}
  \unit[per-mode = repeated-symbol]{\joule\per\mole\per\kelvin}
\end{LaTeXdemo}
Finally, it is possible for the behaviour of the \cs{per} function to depend on
the prevailing math style. Setting \opt{per-mode} to \opt{symbol-or-fraction}
will use the \opt{symbol} setting for in line math, and the \opt{fraction}
setting when used in display math.
\begin{LaTeXdemo}
  \sisetup{per-mode = symbol-or-fraction}%
  $ \unit{\joule\per\mole\per\kelvin} $
  \[ \unit{\joule\per\mole\per\kelvin} \]
     \unit{\joule\per\mole\per\kelvin} \\
  $
    \displaystyle
    \unit{\joule\per\mole\per\kelvin}
  $
  \[
    \textstyle
    \unit{\joule\per\mole\per\kelvin}
  \]
\end{LaTeXdemo}

\DescribeOption{sticky-per}
By default, \cs{per} applies only to the next unit given.\footnote{This is the
standard method of reading units in English: for example,
\unit{\joule\per\mole\per\kelvin} is pronounced \enquote{joules per mole per
kelvin}.} By setting the \opt{sticky-per} flag, this behaviour is changed so
that \cs{per} applies to all subsequent units.
\begin{LaTeXdemo}
  \unit{\pascal\per\gray\henry} \\
  \unit[sticky-per]{\pascal\per\gray\henry}
\end{LaTeXdemo}

\DescribeOption{qualifier-mode}
\DescribeOption{qualifier-phrase}
Unit qualifiers can be printed in three different formats, set by the
\opt{qualifier-mode} option. The standard setting is \opt{subscript}, while the
options \opt{bracket}, \opt{combine} and \opt{phrase} are also possible. With
the last settings, powers can lead to ambiguity and are automatically detected
and brackets added as appropriate.
\begin{LaTeXdemo}
  \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
  \unit[qualifier-mode = bracket]
    {\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
  \unit[qualifier-mode = combine]
    {\deci\bel\of{i}}
\end{LaTeXdemo}
The \opt{phrase} option is used with \opt{qualifier-phrase}, which allows for
example a space or other linking text to be inserted.
\begin{LaTeXdemo}
  \sisetup{qualifier-mode = phrase, qualifier-phrase = \ }%
  \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
  \sisetup{qualifier-phrase = \ \mbox{of}\ }%
  \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour}
\end{LaTeXdemo}

\DescribeOption{parse-units}
Normally, \pkg{siunitx} is used with the unit parse enabled, and only prints
units directly if there is literal input. However, if the input is known to be
essentially consistent and high performance is desired, then the parser can be
turned off using the \opt{parse-units} switch.
\begin{LaTeXdemo}
  \qty{300}{\MHz} \\
  \qty[parse-units = false]{300}{\MHz}
\end{LaTeXdemo}

\DescribeOption{forbid-literal-units}
Some users may prefer to completely disable the use of literal input in units,
for example to enforce consistency. This can be accomplished by setting the
\opt{forbid-literal-units} switch. With this option enabled, only macro-based
units can be used in a document. This only applies when \opt{parse-units} is
\opt{true}.

\DescribeOption{unit-font-command}
The command used to set unit themselves may be adjusted using the
\opt{unit-font-command} option. This is typically set to |\mathrm|.
\begin{LaTeXdemo}
  \unit{\lumen} \\
  \unit[unit-font-command = \mathit]{\lumen}
\end{LaTeXdemo}

\subsection{Quantities}

Some options apply to quantities (the combination of a number and a unit),
rather than to the numbers or units alone (Table~\ref{tab:opt:quantities}).
\begin{table}
  \centering
  \caption{Options for quantities.%
    \label{tab:opt:quantities}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{@{}l}{Default} \\
    \midrule
      allow-quantity-breaks      & Switch  & false   \\
      extract-mass-in-kilograms  & Switch  & true    \\
      prefix-mode                & Choice  & input   \\
      quantity-product           & Literal & \cs{,}  \\
      separate-uncertainty-units & Choice  & bracket \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{allow-quantity-breaks}
Usually, the combination of a number and unit is regarded as a single
mathematical entity which should not be split across lines. However, there are
cases (very long units, narrow columns, \foreign{etc}.) where breaks may be
needed. This can be turned on using the \opt{allow-quantity-breaks} option.
\begin{LaTeXdemo}
  \begin{minipage}{2.55cm}
    % Gives an underfull hbox
    Some filler text \qty{10}{\metre} \\
    \sisetup{allow-quantity-breaks}
    Some filler text \qty{10}{\metre}
  \end{minipage}
\end{LaTeXdemo}

\DescribeOption{number-unit-product}
The product symbol between the number and unit is set using the
\opt{quantity-product} option.
\begin{LaTeXdemo}
  \qty{2.67}{\farad} \\
  \qty[quantity-product = \ ]{2.67}{\farad} \\
  \qty[quantity-product = ]{2.67}{\farad}
\end{LaTeXdemo}

\DescribeOption{prefix-mode}
\DescribeOption{extract-mass-in-kilograms}
The unit prefixes (\cs{kilo}, \foreign{etc}.) are normally given as letters.
However, the package can convert these into numerical powers. This is
controlled by the \opt{prefix-mode} option, which takes the values \opt{input},
\opt{combine-exponent} and \opt{extract-exponent}. The \opt{input} setting
leaves the prefixes unchanged. Using \opt{combine-exponent} will add any
exponent amount from the number to the first unit: this will modify any
existing prefix. Finally, using \opt{extract-exponent} will remove all prefixes
and express them as an exponent. The treatment of kilograms in this case can be
set using \opt{extract-mass-in-kilograms}: when \opt{true}, the \emph{kilo}
prefix is retained as part of the unit. This will mean that all grams are
converted to kilograms.
\begin{LaTeXdemo}
  \qty{1e3}{\metre\second} \\
  \qty[prefix-mode = combine-exponent]{1e3}{\metre\second} \\
  \qty{10}{\kilo\gram\squared\deci\second} \\
  \qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second}\\
  \qty[prefix-mode = extract-exponent]{7.5}{\gram} \\
  \sisetup{extract-mass-in-kilograms = false}
  \qty{10}{\kilo\gram\squared\deci\second} \\
  \qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second} \\
  \qty[prefix-mode = extract-exponent]{7.5}{\gram} \\
\end{LaTeXdemo}

\DescribeOption{separate-uncertainty-units}
When a number has multiple parts (such as a separate uncertainty) then the unit
must apply to all parts of the number. How this is shown is controlled using
the \opt{separate-uncertainty-units} options. The standard setting is
\opt{brackets}, which will place the entire numerical part in brackets and use
a single unit symbol. Alternative options are \opt{repeat} (print the unit for
each part of the number) and \opt{single} (print only one unit symbol:
mathematically incorrect).
\begin{LaTeXdemo}
  \sisetup{separate-uncertainty}
  \qty{12.3(4)}{\kilo\gram} \\
  \qty[separate-uncertainty-units = bracket]{12.3(4)}{\kilo\gram} \\
  \qty[separate-uncertainty-units = repeat]{12.3(4)}{\kilo\gram}  \\
  \qty[separate-uncertainty-units = single]{12.3(4)}{\kilo\gram}
\end{LaTeXdemo}

\subsection{Tabular material}

Processing of material in tables obeys the same settings as described for the
functions already described. However, there are some settings which apply only
to the layout of tabular material (Table~\ref{tab:opt:tables}).
\begin{table}
  \caption{Options for tabular material.%
    \label{tab:opt:tables}}
  \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
    \toprule
      \multicolumn{1}{@{}l}{Option name} &
      Type &
      \multicolumn{1}{l@{}}{Default} \\
    \midrule
      table-align-comparator    & Switch  & true   \\
      table-align-exponent      & Switch  & true   \\
      table-align-text-after    & Switch  & true   \\
      table-align-text-before   & Switch  & true   \\
      table-align-uncertainty   & Switch  & true   \\
      table-alignment           & Meta    & center \\
      table-alignment-mode      & Choice  & marker \\
      table-auto-round          & Switch  & false  \\
      table-column-width        & Length  & 0pt    \\
      table-fixed-width         & Switch  & false  \\
      table-format              & Special & 2.2    \\
      table-number-alignment    & Choice  & center \\
      table-text-alignment      & Choice  & center \\
    \bottomrule
  \end{tabular}
\end{table}

\DescribeOption{table-alignment-mode}
The method used by \pkg{siunitx} to align numbers is selected using the
\opt{table-alignment-mode} option, which may be one of \opt{marker},
\opt{format} or \meta{none}. With the standard setting, \meta{marker}, the
package centers the decimal marker in a tabular column, potentially leaving
white space at the shorter end of a number. The \meta{format} mode uses
information from the \meta{table-format} key to construct a model: this is then
used to define the space available to a number. For asymmetrical numbers, this
method is strongly preferable. Finally, \opt{none} disables alignment entirely:
numbers are simply parsed.

\DescribeOption{table-number-alignment}
When \opt{table-alignment-mode} is set to \meta{format} or \meta{none}, the
placement of the number \enquote{block} within the cell as a whole is set by
the \meta{table-number-alignment} option, which may be one of \meta{left},
\meta{center} or \meta{right}. (When \opt{table-alignment-mode} is set to
\meta{marker}, the decimal marker is always centered in the cell.) The
different alignment choices are illustrated in Table~\ref{tab:S:align}, which
uses somewhat exaggerated column headings to show the relative position of the
cell contents.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Aligning the \texttt{S} column.%
      \label{tab:S:align}}
    \centering
    \sisetup{table-format = 2.4, table-alignment-mode = format}
    \begin{tabular}{@{}
      S[table-alignment-mode = marker]
      S[table-number-alignment = center]
      S[table-number-alignment = left]
      S[table-number-alignment = right]
    @{}}
    \toprule
    {Some Values} & {Some Values} & {Some Values} & {Some Values} \\
    \midrule
       2.3456  &  2.3456  &  2.3456 &  2.3456 \\
      34.2345  & 34.2345  & 34.2345 & 34.2345 \\
      56.7835  & 56.7835  & 56.7835 & 56.7835 \\
      90.473   & 90.473   & 90.473  & 90.473  \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}
When the alignment mode is set to \opt{none}, number are simply collected and
parsed without any further processing, as illustrated in
Table~\ref{tab:S:parse}.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Parsing without aligning in an \texttt{S} column.%
      \label{tab:S:parse}}
    \begin{tabular}
      {@{}
        S
        S[table-alignment-mode = none]
      @{}}
      \toprule
        {Decimal-centred} &
        {Simple centring} \\
      \midrule
        12.345   & 12.345   \\
        6,78     & 6,78     \\
        -88.8(9) & -88.8(9) \\
        4.5e3    & 4.5e3    \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-format}
When the \opt{table-alignment-mode} is set to \opt{format}, \pkg{siunitx} uses
the information set in \meta{table-format} to construct a \enquote{model} which
defines the space to reserve for a number. The \opt{table-format} key is
interpreted in much the same way as a table cell. The numerical part should
consist of a number showing how many figures to reserve in each part of the
input, plus any comparators, signs, \foreign{etc.} A variety of examples are
given in Table~\ref{tab:S:format}.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Reserving space in \texttt{S} columns.%
      \label{tab:S:format}}
    \sisetup{
      table-alignment-mode   = format,
      table-number-alignment = center,
    }
    \begin{tabular}{@{}
      S[table-format = 2.2]
      S[table-format = 2.2, table-number-alignment = right]
      S[table-format = 2.2(1)]
      S[table-format = 2.2(1), separate-uncertainty]
      S[table-format = +2.2]
      S[table-format = 2.2e1]
     @{}}
    \toprule
        {Values}
      & {Values}
      & {Values}
      & {Values}
      & {Values}
      & {Values} \\
    \midrule
       2.3  &  2.3  &  2.3(5)  &  2.3(5)  &   2.3  &  2.3e8  \\
      34.23 & 34.23 & 34.23(4) & 34.23(4) &  34.23 & 34.23   \\
      56.78 & 56.78 & 56.78(3) & 56.78(3) & -56.78 & 56.78e3 \\
       3,76 &  3,76 &  3,76(2) &  3.76(2) & +-3.76 &      e6 \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}
It is important to note that any parts of a number \emph{not} specified in the
table format argument are set to be absent (the number of figures is set to
zero). Setting the \opt{table-format} option also resets
\opt{table-alignment-mode} to \opt{format}.

Space for material before and after the \texttt{S} column can be reserved by
giving model text as part of the \opt{table-format} key. This is then used to
provide the necessary gap while maintaining alignment (Table~\ref{tab:S:ends}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Text before and after numbers.%
      \label{tab:S:ends}}
    \sisetup{table-format = {now }2.4{\textsuperscript{\emph{a}}}}
    \begin{tabular}{@{}S@{}}
    \toprule
    {Values} \\
    \midrule
            2.3456  \\
           34.2345  \textsuperscript{\emph{a}}\\
           56.7835  \\
      now~ 90.473   \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-align-exponent}
\DescribeOption{table-align-uncertainty}
When printing exponents in tables, there is a choice of aligning the exponent
parts or having these close up to the mantissa. This is controlled by the
\opt{table-align-exponent} option (Table~\ref{tab:align:exp}). Similarly,
uncertainty parts which are printed separately from the mantissa can be aligned
or closed up. This is set by the \opt{table-align-uncertainty} option
(Table~\ref{tab:align:uncert}). Finally, the same approach is available for the
comparator with the \opt{table-align-comparator} option
(Table~\ref{tab:align:comp}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{The \opt{table-align-exponent} option.%
      \label{tab:align:exp}}
    \sisetup{table-format = 1.3e2}
    \begin{tabular}{@{}SS[table-align-exponent = false]@{}}
      \toprule
        {Header} & {Header} \\
      \midrule
        1.2e3    & 1.2e3    \\
        1.234e56 & 1.234e56 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{The \opt{table-align-uncertainty} option.%
      \label{tab:align:uncert}}
    \sisetup{
      separate-uncertainty,
      table-format = 1.3(1),
    }
    \begin{tabular}{@{}SS[table-align-uncertainty = false]@{}}
      \toprule
        {Header} & {Header} \\
      \midrule
        1.2(1)   & 1.2(3)    \\
        1.234(5) & 1.234(5) \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{The \opt{table-align-comparator} option.%
      \label{tab:align:comp}}
    \sisetup{table-format = >2.2}
    \begin{tabular}{@{}SS[table-align-comparator = false]@{}}
      \toprule
        {Header} & {Header} \\
      \midrule
        >  1.2  & >  1.2  \\
        < 12.34 & < 12.34 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-align-text-before}
\DescribeOption{table-align-text-after}
Note markers are often given in tables after the numerical content. It may be
desirable for these to close up to the numbers. Whether this takes place is
controlled by the \opt{table-align-text-before} and \opt{\ldots-after}
 option (Table~\ref{tab:S:notes}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Closing notes up to text.%
      \label{tab:S:notes}}
    \newrobustcmd\NoteMark[1]{%
      \textsuperscript{\emph{#1}}%
    }
    \sisetup{table-format = {\NoteMark{a}}2.4}
    \begin{tabular}{@{}
      S
      S[table-align-text-before = false]
    @{}}
    \toprule
      {Values}             & {Values} \\
    \midrule
                    2.3456 &               2.3456 \\
      \NoteMark{a}  4.234  & \NoteMark{a}  4.234 \\
      \NoteMark{b}   .78   & \NoteMark{b}   .78  \\
      \NoteMark{d} 88      & \NoteMark{d} 88     \\
    \bottomrule
    \end{tabular}
    \hfil
    \sisetup{table-format = 2.4\NoteMark{a}}
    \begin{tabular}{@{}
      S
      S[table-align-text-after = false]
    @{}}
    \toprule
      {Values}             & {Values} \\
    \midrule
       2.3456              & 2.3456 \\
      34.234  \NoteMark{a} & 34.234 \NoteMark{a} \\
      56.78   \NoteMark{b} & 56.78  \NoteMark{b} \\
      90.4    \NoteMark{c} & 90.4   \NoteMark{c} \\
      88      \NoteMark{d} & 88     \NoteMark{d} \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-auto-round}
The contents of table cells can automatically be rounded or zero-filled to the
number of decimal digits given for the decimal part of the \opt{table-format}
option. This mode is activated using the \opt{table-auto-round} switch, as
illustrated in Table~\ref{tab:S:auto}.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \centering
    \caption{The \opt{table-auto-round} option.%
      \label{tab:S:auto}}
    \sisetup{table-format = 1.3}
    \begin{tabular}{@{}SS[table-auto-round]@{}}
      \toprule
        {Header} & {Header} \\
      \midrule
        1.2    & 1.2    \\
        1.2345 & 1.2345 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{parse-numbers}
When the \opt{parse-numbers} option is set to \opt{false}, then the alignment
code for tables takes a different approach. The output is always set in math
mode, and alignment takes place at the first decimal marker. This is achieved
by making it active in math mode. When reserving space for content only the
integer and decimal values for the mantissa are considered
(Table~\ref{tab:S:nonparsed}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Aligning without parsing.%
      \label{tab:S:nonparsed}}
    \sisetup{
      parse-numbers = false,
      table-format  = 3.3
    }
    \centering
    \begin{tabular}{@{}
      S
      S[table-number-alignment = center]
      S[table-number-alignment = right]
      S[table-number-alignment = left]
      @{}}
    \toprule
        {Some values}
      & {Some values}
      & {Some values}
      & {Some values} \\
    \midrule
       2.35  &    2.35  &    2.35  &   2.35   \\
      34.234 &   34.234 &   34.234 &  34.234  \\
      56.783 &   56.783 &   56.783 &  56.783  \\
       3,762 &    3,762 &    3,762 &   3.762  \\
    \sqrt{2} & \sqrt{2} & \sqrt{2} & \sqrt{2} \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{drop-exponent}
In cases where data cover a range of values, printing using a fixed exponent in
a table may make presentation clearer. In these cases, dropping the exponent
value from the table is useful. The general numerical options \opt{drop-exponent}
combined with \opt{exponent-mode = fixed} can be used to achieve this
(Table~\ref{tab:exp:omit}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{The \opt{table-omit-exponent} option.%
      \label{tab:exp:omit}}
    \begin{tabular}{@{}
      S[table-format = 1.1e1]
      S[
        drop-exponent  = true,
        exponent-mode  = fixed,
        fixed-exponent = 3,
        table-format   = 2.1,
      ]
    @{}}
      \toprule
        {Header} &
          \multicolumn{1}{c@{}}{Header / \num[print-unity-mantissa = false]{e3}} \\
      \midrule
        1.2e3 & 1.2e3 \\
         3e2  &   3e2 \\
       1.0e4  & 1.0e4 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-column-width}
\DescribeOption{table-fixed-width}
Usually, the width of the numerical column is allowed to vary depending on the
content. However, there are cases where a strictly fixed width is desirable.
For these cases, the \opt{table-fixed-width} and \opt{table-column-width}
options are available. The \opt{table-fixed-width} option activates fixed-width
columns, whilst \opt{table-column-width} defines the target width
(Table~\ref{tab:width:fixed}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Fixed-width columns.%
      \label{tab:width:fixed}}
    \begin{tabular}
      {@{}
        S
        S[table-column-width = 2cm]
      @{}}
      \toprule
        {Flexible} &
        {Fixed}    \\
      \midrule
        1.23 & 1.23 \\
        45.6 & 45.6 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

The \opt{table-column-width} option can also be used to achieve special
effects. One example is centring a column of numbers under a wide heading, with
the numbers themselves right-aligned (Table~\ref{tab:width:special}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \centering
    \caption{Right-aligning under a heading.%
      \label{tab:width:special}}
    \settowidth{\mylength}{Long header}
    \sisetup{
      table-alignment-mode   = none      ,
      table-column-width     = \mylength ,
      table-number-alignment = right
    }
    \begin{tabular}{@{}S@{}}
    \toprule
    {Long header} \\
    \midrule
        12.33 \\
         2    \\
      1234    \\
     \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-text-alignment}
\DescribeOption{table-alignment}
Cell contents which are not part of a number can be protected using braces, as
illustrated. Cells which contain no numerical data at all are aligned using the
setting specified by the \opt{table-text-alignment} option, which recognises
the values \opt{center}, \opt{left} and \opt{right} (Table~\ref{tab:S:text}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Aligning text in \texttt{S} columns.%
      \label{tab:S:text}}
    \sisetup{table-format = 4.4}
    \centering
    \begin{tabular}{@{}
      S
      S[table-text-alignment = left]
      S[table-text-alignment = right]
    @{}}
    \toprule
        {Values}
      & {Values}
      & {Values} \\
    \midrule
      992.435  &  992.435  &  992.435  \\
     7734.2344 & 7734.2344 & 7734.2344 \\
       56.7834 &   56.7834 &   56.7834 \\
        3,7462 &    3,7462 &    3,7462 \\
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\DescribeOption{table-alignment}
The table alignment options \opt{table-number-alignment} and
\opt{table-text-alignment} can be set to the same value using the
\opt{table-alignment} option. This will set all three alignment options to the
same value (one of \opt{center}, \opt{right} or \opt{left}).

\subsection{Locale options}

\DescribeOption{locale}
\pkg{siunitx} allows the user to switch between the typographic conventions of
different (geographical) areas by using locales. Currently, the package is
supplied with configurations for locales \opt{UK}, \opt{US}, \opt{DE}
(Germany), \opt{FR} (French) and \opt{ZA} (South Africa). The \opt{locale}
option is used to switch to a particular locale.
\begin{LaTeXdemo}
  \qty{1.234}{\metre}\\
  \qty[locale = DE]{6.789}{\metre}
\end{LaTeXdemo}

\subsection{Preamble-only options}

\DescribeOption{table-column-type}
The letter(s) used to create table columns can be adjusted using the
\opt{table-column-type} option. The standard setting is |S|, but one or more
letters may be used: these must be single tokens. For example, provided the
\pkg{numprint} package has not been loaded, the letter |n| could be used as
this would suggest a numerical column.

\section{Upgrading from version~\texorpdfstring{$2$}{2}}

The package has been largely re-written internally between versions $2$ and
$3$. A significant number of key--value settings have new, more descriptive,
names. Where possible, older names are mapped to newer ones internally: you
will be warned in the log if this is the case.

Updating to the latest edition of the \acro{SI} Brochure means that a small
number of unit macros have been removed: of those accepted for use,
\cs{angstrom} is no longer present, whilst the units determined experimentally
are all no longer listed (\cs{atomicmassunit}, \cs{bohr}, \cs{clight},
\cs{electronmass}, \cs{elementarycharge}, \cs{hartree}, \cs{planckbar}).

It is possible to use the \LaTeXe{} kernel mechanism to load the last
version~$2$ release for documents that cannot be successfully processed using
version~$3$. This can be achieved using
\begin{LaTeXdemo}[code only]
  \usepackage{siunitx}[=2021-04-09]
\end{LaTeXdemo}
or
\begin{LaTeXdemo}[code only]
  \usepackage{siunitx}[=v2]
\end{LaTeXdemo}
This approach will work with older systems which still have version~$2$
installed, meaning that you can reliably use it to work between systems
with different versions of \pkg{siunitx}.

\begin{function}{\SI, \SIlist, \SIrange, \si}
  In version~$3$, the document commands have been revised to be more
  descriptive. As such, the commands \cs{SI}, \cs{SIlist}, \cs{SIrange}
  and \cs{si} remain available but are not recommended for use in new
  documents. Use the new \cs{qty\ldots} commands instead: they are clearer
  and in some cases very slightly faster.
\end{function}

Some changes have been made to the semantics of commands or options. Most
notably
\begin{itemize}
  \item prefixes cannot now be given without units;
  \item prefixes can only be interconverted with numbers as part
    of a quantity, not as stand-alone units.
\end{itemize}
See Section~\ref{sec:hint:prefixes} for how to work with the new approach
if you want to print prefix information.

The font control system has been completely re-written for version~$3$. The
method used is entirely different from version~$2$. Emulation is therefore not
provided for all outcomes: if you need non-standard font settings, you will
need to adjust your source. See Section~\ref{sec:print} for more details on the
options available in this area.

The input approach for version~$3$ is slightly more structured and restricted
than for version~$2$. As well as the updated names for document commands,
this means that
\begin{itemize}
  \item Products of numbers must now be given using the dedicated
    \cs{numproduct} and \cs{qtyproduct} commands;
  \item Quotients of numbers are only supported as literals;
  \item Complex values need to be given using the dedicated command
    \cs{complexnum}.
\end{itemize}

A new approach has been taken to providing non-Latin symbols for use in
units: these are now handled directly where needed, for example in the
definition of the \cs{micro} prefix.

Translation of fixed strings is now carried out using the \pkg{translations}
package. If you have manually set up translations in version~$2$ using
\pkg{translator}, you will need to load it manually.

The letter used for a numerical tabular column can now be selected by the
user: the letter |S| has been retained as the standard interface. The unit
column (|s|) has been removed from this release. It can be emulated using
the \pkg{collcell} package, for example
\begin{LaTeXdemo}[code only]
  \usepackage{collcell}
  \newcolumntype{s}{>{\collectcell\unit}c<{\endcollectcell}}
\end{LaTeXdemo}
or
\begin{LaTeXdemo}[code only]
  \usepackage{collcell}
  \newcolumntype{s}{>{\collectcell\si}c<{\endcollectcell}}
\end{LaTeXdemo}

If you are using \opt{table-column-width} to have fixed-width columns, you
also now need \opt{table-fixed-width} to set this option active.

\section{Localisation}

The \pkg{translations} package provides a structured framework for localisation
of words and phrases, and is part of the larger \pkg{beamer} bundle. The
\pkg{translations} package provides the \cs{translate} macro, which will provide
appropriate translations based on the current \pkg{babel} or \pkg{polyglossia}
language setting.

If \pkg{translations} is available, \pkg{siunitx} will load it and alter the
standard settings for the \opt{list-final-separator} and \opt{range-phrase}
options to read:
\begin{LaTeXdemo}[code only]
  \sisetup{
    list-final-separator = { \GetTranslation{and} },
    list-pair-separator  = { \GetTranslation{and} },
    range-phrase         = { \GetTranslation{to (numerical range)} },
  }
\end{LaTeXdemo}
If the current language is known to the \pkg{translator} package then the
result will be localised text. The preamble for this manual loads English,
French, German and Spanish as options, and also loads the \pkg{babel} package:
\begin{LaTeXdemo}
  % In English by default
  \numlist{1;2;3} \\
  \numrange{1}{10} \\
  \selectlanguage{french}%
  \numlist{1;2;3} \\
  \numrange{1}{10} \\
  \selectlanguage{german}%
  \numlist{1;2;3} \\
  \numrange{1}{10} \\
  \selectlanguage{spanish}%
  \numlist{1;2;3} \\
  \numrange{1}{10}
\end{LaTeXdemo}

\section{Compatibility with other packages}

In general, \pkg{siunitx} should be usable with other packages without
interference.

When the \pkg{physics} package is loaded before \pkg{siunitx}, the command
\cs{qty} is not defined: users will need to use the version~$2$ command
\cs{SI}.

\section{Hints for using \pkg{siunitx}}

\subsection{Ensuring text or math output%
  \label{sec:hint:text-math}}

The macros \cs{ensuremath} and \cs{text} should be used to ensure that a
particular item is always printed in the desired mode. Some mathematical output
does not work well in \cs{mathrm} (the font setting used by \pkg{siunitx} for
printing units). The easiest way to solve this is to use the construction
"\text{\ensuremath{...}}", which will print the material in the standard
mathematics font without affecting the rest of the output. In some cases,
simply forcing \cs{mathnormal} will suffice, but this is less reliable with
non-Latin characters.

\subsection{Expanding content in tables%
  \label{sec:hint:expanding}}

When processing tables, \pkg{siunitx} will expand anything stored inside a
macro, unless it is long or protected. \LaTeXe{} robust commands are also
detected and are not expanded (Table~\ref{tab:xmpl:macro}). Values which would
otherwise be expanded can be protected by wrapping them in a set of braces. As
\TeX{} itself will expand the first token in a table cell before \pkg{siunitx}
can act on it, using the \eTeX{} protected mechanism is the recommended course
of action to prevent expansion of macros in table cells. (As is shown in the
table, \TeX's expansion of \LaTeXe{} robust commands can lead to unexpected
results.)
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Values as macros in \texttt{S} columns.%
      \label{tab:xmpl:macro}}
    \newcommand*\myvaluea{1234}
    \newcommand\myvalueb{1234}
    \DeclareRobustCommand*\myvaluec{1234}
    \protected\def\myvalued{1234}
    \begin{tabular}{@{}S@{}}
    \toprule
      {Some Values} \\
    \midrule
       \myvaluea  8.8 \myvaluea  \\ % Both expanded
       \myvalueb  8.8 \myvalueb  \\ % First expanded by TeX
                                    % to numbers
       \myvaluec  8.8 \myvaluec  \\ % First expanded by TeX
                                    % but not to numbers!
       \myvalued  8.8 \myvalued  \\ % Neither expanded
      {\myvaluea\ 8.8 \myvaluea} \\ % Neither expanded
    \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

It is possible to use calculated values in tables. For this to work, the
calculation must take place before attempting to parse the number (the parser
cannot \enquote{know} all of the possible values inside an expression). This is
most conveniently handled using the \pkg{xfp} package, which is distributed as
part of the required support for \pkg{siunitx}. The general approach is
illustrated in Table~\ref{tab:xmpl:calc}
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Calculated values.%
      \label{tab:xmpl:calc}}
    \newcommand{\valuea}{66.7012}
    \newcommand{\valueb}{66.0212}
    \newcommand{\valuec}{64.9026}
    \begin{tabular}{
      @{}
      S[table-format = 2.4]
      S[table-format = 3.4]
      @{}
    }
      \toprule
        {Value} & {Doubled} \\
      \midrule
        \valuea & \fpeval{\valuea * 2} \\
        \valueb & \fpeval{\valueb * 2} \\
        \valuec & \fpeval{\valuec * 2} \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

A more sophisticated approach is to generate the rows themselves from a
database: this is illustrated in Section~\ref{sec:hint:datatool}.

\subsection{Using \pkg{siunitx} with \pkg{datatool}%
  \label{sec:hint:datatool}}

As illustrated in Table~\ref{tab:xmpl:calc}, \pkg{siunitx} can be used to
typeset data stored using \pkg{datatool}. For quickly displaying the contents
of tables, \pkg{datatool} offers the \cs{DTLshowtable} macro. This will only
work with \texttt{S} columns if number parsing is turned off
(Table~\ref{tab:xmpl:datatool}).
\begin{LaTeXdemo}[code and float]
  \DTLnewdb{moredata}
  \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{ 6.7012}
  \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{66.0212}
  \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{64.902 }
  \begin{table}
    \caption{Displaying a \textsf{datatool} table.%
      \label{tab:xmpl:datatool}}
    \sisetup{parse-numbers= false, table-format = 2.4}
    \renewcommand*\dtlrealalign{S}
    \DTLdisplaydb{moredata}
  \end{table}
\end{LaTeXdemo}

The \pkg{datatool} package may also be used to create on-the-fly tables using
calculations. For example, the demonstration in Table~\ref{tab:xmpl:calc} may
be achieved without needing to write out each row, as shown in
Table~\ref{tab:xmpl:datatool-calc}. An extra column is used to contain the
calculations in this case.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Calculated values using \pkg{datatool}.%
      \label{tab:xmpl:datatool-calc}}
    \DTLnewdb{data}
    \DTLnewrow{data}\DTLnewdbentry{data}{value}{66.7012}
    \DTLnewrow{data}\DTLnewdbentry{data}{value}{66.0212}
    \DTLnewrow{data}\DTLnewdbentry{data}{value}{64.9026}
    \begin{tabular}{
      @{}
      S[table-format = 2.4]
      S[table-format = 3.4]
      @{}l
      @{}
    }
      \toprule
        {Value} & {Doubled} &
      \DTLforeach{data}{\myvalue=value}{%
        \DTLiffirstrow {\\ \midrule}{\\}%
        \myvalue &            % First column
        \fpeval{\myvalue * 2} % second column
        & }\\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\subsection{Using units in section headings and bookmarks%
  \label{sec:hint:bookmarks}}

The \pkg{siunitx} code is designed to work correctly with functions in
headings. They will print correctly in headings and in the table of contents.
As illustrated here, the standard behaviour is to ignore font changes. When the
\pkg{hyperref} package is loaded, the functions automatically \enquote{degrade
gracefully} to produce useful information in \acro{pdf} bookmarks. If you want
more control over the bookmark text, use the \cs{texorpdfstring} function from
\pkg{hyperref}, for example:
\begin{LaTeXdemo}[code only]
  \section{Some text
    \texorpdfstring
      {\unit{\joule\per\mole\per\kelvin}}
      {J mol-1 K-1}%
    }
\end{LaTeXdemo}

You may find it useful to load \pkg{hyperref} with the \opt{unicode} option,
as this will allow \unit{\ohm} to appear in bookmarks. Without the option,
the encoding used by \pkg{hyperref} does not support this symbol.

\subsection{A left-aligned column visually centred under a heading%
  \label{sec:hint:left-column}}

When you have a column of non-related numbers, the usual advice is to make
these left-aligned and then centre the resulting column under the heading. With
the \pkg{dcolumn} package, that would be done with something like
|D{x}{}{5.0}|. This is something of an abuse of the nature of a number, but can
also be done using \pkg{siunitx} (Table~\ref{tbl:xmpl:unrel}).
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Formatting unrelated numbers.%
      \label{tbl:xmpl:unrel}}
    \centering
    \begin{tabular}
      {
        @{}
        S[
          table-format = 5.0,
          parse-numbers = false,
          input-decimal-markers = x
        ]
        @{}
      }
      \toprule
      \multicolumn{1}{@{}c@{}}{Header} \\
      \midrule
      120   \\
      12.3  \\
      12340 \\
      12.02 \\
      123   \\
      1     \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\subsection{Maximising performance%
  \label{sec:hint:performance}}

Both the number and unit parsers require significant effort in terms of \TeX{}
programming. For input that does not require such processing, the maximum
performance for \pkg{siunitx} can therefore be obtained by turning off both
systems:
\begin{LaTeXdemo}
  \qty{7.3}{\Hz} \\
  \qty[parse-units = false]{7.3}{\Hz} \\
  \qty[
    parse-numbers = false,
    parse-units   = false
  ]{7.3}{\Hz}
\end{LaTeXdemo}

\subsection{Special considerations for the \cs{kWh} unit%
  \label{sec:hint:kWh}}

The standard settings provide the \cs{kWh} unit set up with no spacing between
the \enquote{\unit{\kilo\watt}} and the \enquote{\unit{\hour}} unit to give
\enquote{\unit{\kWh}}. However, this only applies when the unit is given on its
own: combinations will follow the normal rules
\begin{LaTeXdemo}
  \unit{\kWh} \\
  \unit{\kWh\per\metre}
\end{LaTeXdemo}
This is because the unit \cs{kWh} is defined so that it can still be varied by
altering \cs{kilo}, \cs{watt} and \cs{hour}, and so that the prefix can still
be turned into a number. However, some users may prefer to have a non-flexible
macro which never adds a space. This can be achieved by redefining \cs{kWh}
with \cs{DeclareSIUnit}, by added an alternative definition
\begin{LaTeXdemo}[code only]
  \DeclareSIUnit\kWh{kWh}
  \DeclareSIUnit\KWH{kWh}
\end{LaTeXdemo}
 or of course by using literal unit input.
\begin{LaTeXdemo}
  \unit{\KWH\per\metre}\\
  \unit{kWh.m^{-1}}
\end{LaTeXdemo}

Another point to notice is that the \cs{per} macro applies to the next unit,
and not an entire unit combination. Thus in
\begin{LaTeXdemo}
  \unit{\candela\per\kWh}
\end{LaTeXdemo}
\cs{per} applies to the watts but not to the hours. In this case, the units
need to be written out in full or the \opt{sticky-per} option should be used.
\begin{LaTeXdemo}
  \unit{\candela\per\kilo\watt\per\hour} \\
  \unit[sticky-per]{\candela\per\kWh}
\end{LaTeXdemo}

\subsection{Creating a column with numbers and units%
  \label{sec:hint:mixed}}

Usually, numbers in a table should be given with the units in the column
heading. However, there are cases where a series of data are best presented in
a table but have different units. There are two ways to do this
(Table~\ref{tab:xmpl:mixed}). The first is to place the units in the first
column of the table, which makes sense if there are several related items in
the table. The second method is to generate two columns, one for numbers and a
second for units, and then to format these to give the visual effect of a
single column. The later effect is most appropriate when only one set of
numbers are presented in a table. This method requires cell content is
collected, easiest to do using the \pkg{collcell} package.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Tables where numbers have different units.%
      \label{tab:xmpl:mixed}}
    \hfil
    \begin{tabular}
      {
        @{}
        >{$}l<{$}
        S[table-format = 3.3(1)]
        S[table-format = 3.3(1)]
        @{}
      }
      \toprule
        & {One} & {Two} \\
      \midrule
      a / \unit{\pm}         &  123.4(2) &   567.8(4) \\
      \beta / \unit{\degree} & 90.34(4)  & 104.45(5)  \\
      \mu / \unit{\per\mm}   &  0.532    &   0.894    \\
      \bottomrule
    \end{tabular}
    \hfil
    \begin{tabular}
      {
        @{}
        S[table-format=1.3]@{\,}
        >{\collectcell\unit}l<{\endcollectcell}
        @{}
      }
      \toprule
      \multicolumn{2}{@{}c}{Heading} \\
      \midrule
      1.234 & \metre   \\
      0.835 & \candela \\
      4.23  & \joule\per\mole \\
      \bottomrule
    \end{tabular}
    \hfil
  \end{table}
\end{LaTeXdemo}

\subsection{Tables with heading rows%
  \label{sec:hint:heading}}

A common format for tables is to make the heading row visually distinct using a
background color and bold text. If numbers appear in such a heading row within
an \texttt{S} column then getting the appearance right can be challenging. The
best approach is to make the \cs{bfseries} macro \enquote{robust} (as
demonstrated in Section~\ref{sec:hint:expanding}), then to use this macro to
make the heading cells bold. This approach is illustrated in
Table~\ref{tab:xmpl:headers}, along with the use of \cs{rowcolor} to provide a
background color.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Header row in a table.%
      \label{tab:xmpl:headers}}
    \robustify\bfseries
    \centering
    \begin{tabular}
      {@{}S[text-series-to-math, table-format = 3.3]@{}}
      \rowcolor[gray]{0.9}
      \bfseries 123.456 \\
       23.45  \\
      123.4   \\
        3.456 \\
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\subsection{Associating a locale with a \pkg{babel} language%
  \label{sec:hint:babel}}

It is possible to instruct the \pkg{babel} package to switch to a particular
\pkg{siunitx} locale when changing language. This can be done using the
\pkg{babel} \cs{extras\meta{language}} system. For example, to associate the
\texttt{DE} locale with the \texttt{german} \pkg{babel} language, the
appropriate code would be
\begin{LaTeXdemo}[code only]
  \addto\extrasgerman{\sisetup{locale = DE}}
\end{LaTeXdemo}

\subsection{Symbolic \enquote{digits}%
  \label{sec:hint:symbols}}

In some cases you may want to use \enquote{digits} which do not fall within the
usual set |0123456789|. This can be done by setting the \opt{input-digits}
option, but bearing in mind that this will affect (prevent) for example
rounding.
\begin{LaTeXdemo}
  \sisetup{input-digits = 0123456789\pi}%
  \num{4\pi e-7}
\end{LaTeXdemo}
Each extra entry should be a single token, and should either have a definition
which is safe in both math and text mode, or should only be used when the
output mode is known. It may be necessary to make some tokens robust using
\pkg{etoolbox} for this to work, for example
\begin{LaTeXdemo}
  \robustify\dots
  \sisetup{input-digits = 0123456789\dots}%
  \qty{0,4066\dots}{\metre\squared}
\end{LaTeXdemo}

\subsection{Demonstrating prefixes
  \label{sec:hint:prefixes}}

As \pkg{siunitx} contains data about the numerical values of unit prefixes,
you may wish to print this in an automated way. Prefixes cannot be given
on their own, but it is possible to create a \enquote{do nothing} unit.
\begin{LaTeXdemo}[code only]
  \DeclareSIUnit\noop{\relax}
\end{LaTeXdemo}
which can then be used to show just the prefix symbol.
\begin{LaTeXdemo}
  \unit{\yotta\noop}
\end{LaTeXdemo}
To show just the numerical value of a prefix, you will need to use \cs{qty}
and appropriate settings.
\begin{LaTeXdemo}
  \qty[prefix-mode = extract-exponent, print-unity-mantissa = false]%
    {1}{\yotta\noop}
\end{LaTeXdemo}
This may be conveniently wrapped up inside a document command, for example
\begin{LaTeXdemo}[code only]
  \NewDocumentCommand\prefixvalue{m}{%
    \qty[prefix-mode=extract-exponent,print-unity-mantissa=false]{1}{#1\noop}
  }
\end{LaTeXdemo}

\section{Using (\acro{SI}) units}

Consistent and logical units are a necessity for scientific work, and have
applicability everywhere. Historically, a number of systems have been used for
physical units. \acro{SI} units were introduced by the \foreign{Conférence
Générale des Poids et Mesures} (\acro{CGPM}) in 1960. \acro{SI} units are a
coherent system based on seven base units, from which all other units may be
derived.

At the same time, physical quantities with units are mathematical entities, and
as such way that they are typeset is important. In mathematics, changes of type
(such as using bold, italic, sans serif typeface and so on) convey information.
This means that rules exist not only for the type of units to be used under the
\acro{SI} system, but also the way they should appear in print. Advice on best
practice has been made available by the \emph{National Institute of Standards
and Technology} (\acro{NIST})~\cite{NIST}.

As befits an agreed international standard, the full rules are detailed. It is
not appropriate to reproduce these in totality here; instead, a useful summary
of the key points is provided. The full details are available from the
\foreign{Bureau International des Poids et Mesures}~\cite{BIPM}.

The \pkg{siunitx} package takes account of the information given here, so far
as is possible. Thus the package defaults follow the recommendations made for
typesetting numbers and units. Spacing and so forth is handled in such a way as
to make implementing the rules (relatively) easy.

\subsection{Units}

There are seven base \acro{SI} units, listed in Table~\ref{tab:unit:base}.%
\footnote{Some base units need others defined first; there is therefore a
required order of definition.} The base units have been chosen such that all
physical quantities can be expressed using an appropriative combination of
these units, needing no others and with no redundancy.

All other units within the \acro{SI} system are regarded as \enquote{derived}
from the seven base units. At the most basic, all other \acro{SI} units can be
expressed as combinations of the base units. However, many units (listed in
Table~\ref{tab:unit:derived}) have a special name and symbol. Most of these
units are simple combinations of one or more base units (raised to powers as
appropriate).

A series of \acro{SI} prefixes for decimal multiples and sub-multiples are
provided, and can be used as modifiers for any \acro{SI} unit (either base or
derived units) with the exception of the kilogram. The prefixes are listed in
Table~\ref{tab:unit:prefix}. No space should be used between a prefix and the
unit, and only a single prefix should be used. Even the degree Celsius can be
given a prefix, for example \qty{1}{\milli\degreeCelsius}.

It is important to note that the kilogram is the only \acro{SI} unit with a
prefix as part of its name and symbol. Only single prefix may be used, and so
in the case of the kilogram prefix names are used with the unit name
\enquote{gram} and the prefix symbols are used with the unit symbol
\unit{\gram}. For example $\qty{1e-6}{\kilo\gram} = \qty{1e-3}{\gram} =
\qty{1}{\milli\gram}$.

The application of \acro{SI} units is meant to provide a single set of units
which ensure consistency and clarity across all areas. However, other units are
common is many areas, and are not without merit. The units provided by
\pkg{siunitx} by default do not include any of these; only units which are part
of the \acro{SI} set or are accepted for use with \acro{SI} units are defined.
However, several other sets of units can be loaded as optional modules. The
binary prefixes and units (Table~\ref{tab:unit:binary}) are the most obvious
example. These are \emph{not} part of the \acro{SI} specifications, but the
prefix names are derived from those in Table~\ref{tab:unit:prefix}.

Other units are normally to be avoided where possible. \acro{SI} units should,
in the main, be preferred due to the advantages of clear definition and
self-consistency this brings. However, there will probably always be a place
for specialist or non-standard units. This is particularly true of units
derived from basic physical constants.

There are also many areas where non-standard units are used so commonly that to
do otherwise is difficult or impossible. For example, most synthetic chemists
measure the pressure inside vacuum apparatus in \unit{\millimetremercury},
partly because the most common gauge for the task still uses a column of
mercury metal. For these reasons, \pkg{siunitx} allows definition of such
units.

\subsection{Mathematical meaning}

As explained earlier, a quantity combination is a single mathematical entity.
This has implications for how both the number and the unit should be printed.
Firstly, the two parts should not be separated: a quantity is a product of the
number and the unit. With the exception of the symbols for plane angles
(\unit{\degree}, \unit{\arcminute} and \unit{\arcsecond}), the \acro{BIPM}
specifies either a space or half-height (centred) dot should be
used~\cite{BIPM}.
\begin{LaTeXdemo}
  A space for \qty{10}{\percent}\\
  and also for \qty{100}{\degreeCelsius}\\
  but not for \ang{1.23}.
\end{LaTeXdemo}

The mathematical meaning of units also means that the shape, weight and family
are important. Units are supposed to be typeset in an upright, medium weight
font. Italic, bold and sans serif are all used mathematically to convey other
meanings. (In an all sanserif document, using sans serif for units is
reasonable.) The \pkg{siunitx} package defaults again follow this convention:
any local settings are ignored, and uses the current upright math font.
However, there are occasions where this may not be the most desirable
behaviour. A classic example would be in an all-bold section heading. As the
surrounding text is bold, some people feel that any units should follow this.
\begin{LaTeXdemo}
  Units should \textbf{not be bold: \qty{54}{\farad}}\\
  \textbf{But perhaps in a running block,\\
  it might look better:
    \qty[text-series-to-math]{54}{\farad}}
\end{LaTeXdemo}

Symbols for units formed from other units by multiplication are indicated by
means of either a half-height (that is, centred) dot or a (thin) space.
\begin{LaTeXdemo}
  $\unit{\metre\second} = \text{metre second}$ \\
  $\unit{\milli\second} = \text{millisecond}$ \\
  \sisetup{inter-unit-product = \ensuremath { { } \cdot { } } }
  $\unit{\metre\second} = \text{metre second}$ \\
  $\unit{\milli\second} = \text{millisecond}$
\end{LaTeXdemo}
There are some circumstances under which it is common practice to omit any
spaces. The classic example is \unit{\kWh}, where
\enquote{\unit[inter-unit-product = \,]{\kWh}} does not add any useful
information. If using such a unit repeatedly, users of \pkg{siunitx} are
advised to create a custom unit to ensure consistency. It is important to note
that while this is common practice, it is \emph{not} allowed by the
\acro{BIPM}~\cite{BIPM}.

Symbols for units formed from other units by division are indicated by means of
a virgule (oblique stroke, slash, "/"), a horizontal line, or negative
exponents.\footnote{Notice that a virgule and a solidus are not the same
symbol.} However, to avoid ambiguity, the virgule must not be repeated on the
same line unless parentheses are used. This is ensured when using named unit
macros in \pkg{siunitx}, which will \enquote{trap} repeated division and format
it correctly. In complicated cases, negative exponents are to be preferred over
other formats.
\begin{LaTeXdemo}
  \unit{\joule\per\mole\per\kelvin} \\
  \unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\
  \unit[per-mode = symbol]{\joule\per\mole\per\kelvin}
\end{LaTeXdemo}

Products and errors should show what unit applies to each number given. Thus
\qtyproduct[product-units = bracket]{2x3}{\metre} is an ordered set of lengths
of a geometric area, whereas \qtyproduct[product-units = single]{2x3}{\metre}
is a length (and equal to \qty{6}{\metre}). Thus, $\times$ is not a product but
is a mathematical operator; in the same way, a $2 \times 3$ matrix is not a $6$
matrix! In some areas, areas and volumes are given with separated units but a
unit raised to the appropriate power: \qtyproduct[product-units = power]{2 x
3}{\metre}. Although this does display the correct overall units, it is
potentially-confusing and is not encouraged.

Care must be taken when writing ranges of numbers. For purely numerical values,
it is common to use a en-dash to show a range, for example \enquote{see pages
1--5}. On the other hand, physical quantities could be misinterpret as negative
values if written in this way. As the quantity is a single mathematical entity,
writing the values with an en-dash followed by a single unit is also incorrect.
As a result, using the word \enquote{to} is strongly recommended.
\begin{LaTeXdemo}
  \qtyrange{1}{5}{\metre} long.
\end{LaTeXdemo}

\subsection{Graphs and tables}

In graphs and tables, repetition of the units following each entry or axis mark
is confusing and repetitive. It is therefore best to place the unit in the
label part of the information. Placing the unit in square brackets is common
but mathematically poor.\footnote{For example, for an acceleration \(a\), the
expression $[a]$ is the dimensions of $a$, \foreign{i.e.}~length per time
squared in this case.} Much better is to show division of all quantities by the
unit, which leaves the entries as unitless ratios. This is illustrated in
Table~\ref{tab:xmpl:unitless} and Figure~\ref{fig:xmpl:unitless}.
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{An example of table labelling.%
      \label{tab:xmpl:unitless}}
    \sisetup{
      table-number-alignment = center,
      table-format = 1.4
    }
    \begin{tabular}{@{}cS@{}}
      \toprule
        Entry & {Length/\unit{\metre}} \\
      \midrule
        1 & 1.1234 \\
        2 & 1.1425 \\
        3 & 1.7578 \\
        4 & 1.9560 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}
\begin{LaTeXdemo}[code and float]
  \begin{figure}
    \begin{tikzpicture}
      \begin{axis}[
        xlabel = $t/\unit{\second}$,
        xmax   = 6,
        xmin   = 0,
        ylabel = $d/\unit{\metre}$,
        ymin   = 0
      ]
        \addplot[smooth,mark=*]
          plot coordinates {
            (0,0)
            (1,5)
            (2,8)
            (3,9)
            (4,8)
            (5,5)
            (6,0)
           };
      \end{axis}
    \end{tikzpicture}
    \caption{An example of graph labelling.%
      \label{fig:xmpl:unitless}}
  \end{figure}
\end{LaTeXdemo}

 In most cases, adding exponent values in the body of a table is
 less desirable than adding a fixed exponent to column headers.  An
 example is shown in Table~\ref{tab:good}.  The use of \cs{multicolumn} is
 needed here due to the \enquote{\texttt{<}}; without \cs{multicolumn},
 the titles are followed by \enquote{\unit{\kilo\gram}}!
\begin{LaTeXdemo}[code and float]
  \begin{table}
    \caption{Bad and good columns.%
      \label{tab:good}}
    \sisetup{table-number-alignment = center}
    \begin{tabular}{
      @{}
      c
      S[table-format = 1.3e1]
      @{\,\unit{\kilogram}}
      S[table-format = 2.2]
      @{}
    }
      \toprule
        Entry & \multicolumn{1}{c}{Mass} &
          {Mass/\qty[print-unity-mantissa = false]{e3}{\kilogram}} \\
      \midrule
        1 & 4.56e3  & 4.56 \\
        2 & 2.40e3  & 2.40 \\
        3 & 1.345e4 & 13.45 \\
        4 & 4.5e2   & 0.45 \\
      \bottomrule
    \end{tabular}
  \end{table}
\end{LaTeXdemo}

\section{Installation}

For most users, there will be no need to explicitly install \pkg{siunitx}:
it is available from the package management system in current \TeX{} Live
and MiK\TeX{} systems.

For manual installation, the package is available from
\href{http://ctan.org/pkg/siunitx}{\acro{CTAN}}. As well as the raw source
files, \acro{CTAN} hold the package as a pre-extracted zip file,
\file{siunitx.tds.zip}. The later is most convenient for most users: simply
unzip this in your local \path{texmf} directory.

The package requires \LaTeX3 support as provided in the \pkg{l3kernel} and
\pkg{l3packages} bundles. Both of these are included in \TeX{} Live and
MiK\TeX{}, or are again available in ready-to-install form from \acro{CTAN}.

\section{Thanks}

Many users have provided feedback, bug reports and ideas for new features for
\pkg{siunitx}: thanks to all of them. Particular thanks to Stefan Pinnow, who
has taken the lead role as beta tester for \pkg{siunitx}, finding incorrect
output, bad documentation and the odd spelling mistake in the documentation.
Thanks also to Enrico Gregorio for encouraging me to complete a fully
\pkg{expl3}-compliant version of the package. Thanks also to Danie Els and
Marcel Heldoorn for the \pkg{SIstyle} and \pkg{SIunits} packages, respectively,
which provided the starting point for the development of \pkg{siunitx}.

\section{Making suggestions and reporting bugs}

Feedback on \pkg{siunitx} is always welcome, either to make suggestions or to
report problems. When sending feedback, it is always useful if a small example
file is included, showing the bug being reported or illustrating the desired
output. It is helpful if a \enquote{reference rendering} is included, showing
what the output should look like. A typical example file might read
\begin{verbatim}
  \listfiles
  % Use the article class unless the problem is class-dependent
  \documentclass{article}
  \usepackage{siunitx}
  % Other packages loaded as required
  \begin{document}
  Reference output: $1.23\,\mathrm{m}$

  \textsf{siunitx} output: \qty{1.23}{\metre}
  \end{document}
\end{verbatim}
As illustrated, it is usually best to use the \cls{article} class and to only
load packages which are needed to show the issue. It is also useful to include
a copy of the log file generate by \LaTeX{} when reporting a bug (as the
versions of packages can be important to solving the issue).

Feedback can be sent in a range of ways. The development code and issue tracker
are hosted on \href{https://github.com/josephwright/siunitx/}{GitHub}. Issues
opened there are visible to other users and makes sure that they cannot be
forgotten.

\end{documentation}

\begin{thebibliography}{10}
  \bibitem{BIPM}
    \emph{The International System of Units (\acro{SI})},
    \url{https://www.bipm.org/en/measurement-units/}.
  \bibitem{NIST}
    \emph{International System of Units from \acro{NIST}},
    \url{http://physics.nist.gov/cuu/Units/index.html}.
\end{thebibliography}

\PrintIndex

\end{document}