summaryrefslogtreecommitdiff
path: root/macros/latex/required/tools/dcolumn.dtx
blob: 1899cce5560a91c02daad855b1326ea3f99ea771 (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
% \iffalse meta-comment
%
% Copyright (C) 1993-2020
%
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the Standard LaTeX `Tools Bundle'.
% -------------------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% The list of all files belonging to the LaTeX `Tools Bundle' is
% given in the file `manifest.txt'.
%
% \fi
% \iffalse
%% File: dcolumn.dtx Copyright (C) 1992-1996 1999-2001 David Carlisle
%
%<*dtx>
          \ProvidesFile{dcolumn.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{dcolumn}
%<driver>\ProvidesFile{dcolumn.drv}
% \fi
%         \ProvidesFile{dcolumn.dtx}
          [2014/10/28 v1.06 decimal alignment package (DPC)]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
 \usepackage{dcolumn}
 \DeleteShortVerb{\|}
\begin{document}
 \DocInput{dcolumn.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{dcolumn.dtx}
%
% \title{The \textsf{dcolumn} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}}
% \author{David Carlisle}
% \date{\filedate}
% \author{David Carlisle}
% \MaintainedByLaTeXTeam{tools}
% \maketitle
%
%
% \changes{v1.00}{1992/02/17}{Initial version}
% \changes{v1.01}{1992/06/12}{Re-issue for the new doc and docstrip.}
% \changes{v1.02}{1994/03/14}{Re-issue for LaTeX2e}
% \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
% \changes{v1.05}{1999/07/05}
%      {Minor doc changes latex/3058}
% \changes{v1.06}{2001/05/28}
%      {More doc changes (suggested by BNB, done by CAR) latex/3315}
%
%
%
% \begin{abstract}
% This package defines a system for defining columns of entries in an
% \texttt{array} or \texttt{tabular} which are to be aligned on a
% `decimal point'.
% \end{abstract}
%
% \MakeShortVerb{\"}
%
% This package defines {\tt D} to be a column specifier with three
% arguments.\\
% "D{"\meta{sep.tex}"}{"\meta{sep.dvi}"}{"\meta{decimal
% places}"}"
%
% \meta{sep.tex} should be a single character, this is used as the
% separator in the {\tt .tex} file. Thus it will usually be `{\tt.}' or
% `{\tt,}'.
%
% \mbox{\meta{sep.dvi}} is used as the separator in the output, this may
% be the same as the first argument, but may be any math-mode
% expression, such as "\cdot". It should be noted that \texttt{dcolumn}
% always uses math mode for the digits as well as the separator.
%
% \meta{decimal places} should be the maximum number of decimal places
% in the column. If this is negative, any number of decimal places can
% be used in the column, and all entries will be centred on
% (the leading edge of) the
% separator. Note that this can cause a column to be too wide, compare
% the first two columns in the example below. If this argument is
% positive, the column uses macros equivalent to "\rightdots"
% "\endrightdots" of {\tt array.sty}, otherwise the macros are
% essentially equivalent to "\centerdots" "\endcenterdots".
%
% You may not want to use all three entries in the {\tt array} or {\tt
% tabular} preamble, so you may define your own preamble specifiers
% using "\newcolumntype".
%
% For example we may say:
%
% \noindent"\newcolumntype{d}[1]{D{.}{\cdot}{#1}}"
%
% {\tt d} takes a single argument specifying the number of decimal
% places, and the {\tt .tex} file should use {\tt.}, with $\cdot$ being
% used in the output.
%
% \noindent"\newcolumntype{.}{D{.}{.}{-1}}"
%
% {\tt .} specifies a column of entries to be centred on the~$.$.
%
% \noindent"\newcolumntype{,}{D{,}{,}{2}}"
%
% {\tt ,} specifies takes a column of entries with at most two decimal
% places after a~$,$.
%
% \newcolumntype{d}[1]{D{.}{\cdot}{#1}}
% \newcolumntype{.}{D{.}{.}{-1}}
% \newcolumntype{,}{D{,}{,}{2}}
%
% The following table begins "\begin{tabular}{|d{-1}|d{2}|.|,|}"
%
% \begin{center}
% \begin{tabular}{|d{-1}|d{2}|.|,|}
% 1.2   & 1.2   &1.2    &1,2    \\
% 1.23  & 1.23  &12.5   &300,2  \\
% 1121.2& 1121.2&861.20 &674,29 \\
% 184   & 184   &10     &69     \\
% .4    & .4    &       &,4     \\
%       &       &.4     &
% \end{tabular}
% \end{center}
%
% Note that the first column, which had a negative \meta{decimal places}
% argument is wider than the second column, so that the decimal point
% appears in the middle of the column.
% Also note that this package deals correctly with entries with no
% decimal part, no integer part, and blank entries.
%
% If you have table headings (inserted with "\multicolumn{1}{c}{..}"
% to over-ride the "D" column type) then it may be that neither of the
% above `centred' or `right aligned' forms is quite what you want.
% \begin{center}\small
% \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|}
%\multicolumn{1}{|c|}{head}&
%\multicolumn{1}{c|}{head}&
%\multicolumn{1}{c|}{head}\\[3pt]
% 1.2  & 1.2  &1.2 \\
% 11212.2& 11212.2&11212.2  \\
% .4    & .4    &.4
% \end{tabular}
% \hfill
% \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|}
%\multicolumn{1}{|c|}{wide heading}&
%\multicolumn{1}{c|}{wide heading}&
%\multicolumn{1}{c|}{wide heading}\\[3pt]
% 1.2  & 1.2  &1.2 \\
% .4    & .4    &.4
% \end{tabular}
% \end{center}
%
% In both of these tables the first column is set with "D{.}{.}{-1}"
% to produce a column centered on the ".", and the second column is
% set with "D{.}{.}{1}" to produce a right aligned column.
%
% The centered column produces columns that are wider than necessary
% to fit in the numbers under a heading as it has to ensure that the
% decimal point is centred. The right aligned column two does not have
% this drawback, but under a wide heading a column of small right
% aligned figures looks a bit odd.
%
% In version v1.03 a third possibility is introduced. The third
% \meta{decimal places} argument may specify \emph{both} the number of
% digits to the left and to the right of the decimal place. The third
% column in the first table above is set with "D{.}{.}{5.1}" and in the
% second  table,  "D{.}{.}{1.1}", to specify
% `five places to the left and one to the right' and `one place to the
% left and% one to the right' respectively.  (You may use `,' or other
% tokens, not necessarily `.' in this argument.) The column of figures
% is then positioned such that a number with the specified numbers of
% digits is centred in the column.
%
% This notation also enables columns that are centred on the mid-point
% of the separator, rather than its leading edge; for example
% "D{+}{\,\pm\,}{3,3}" will give nice, symmetric layout of up to three
% digits on either side of a $\pm$ sign.
%
% \StopEventually{}
%
%
% \section{The Macros}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% First we load {\tt array.sty} if it not already loaded.
%    \begin{macrocode}
\RequirePackage{array}
%    \end{macrocode}
%
% The basic ideas behind these macros are explained in the documentation
% for {\tt array.sty}. However they use three
% tricks which may be useful in other contexts.
% \begin{itemize}
% \item The separator is surrounded in extra "{ }", so that it is set
% with "\mathord" spacing, otherwise, for instance a `,' would have
% extra space after it.
% \item The separator is not given its special definition by making it
% active, as this would not work for an entry such as "& .5 &", as the
% first token of an alignment entry is read {\em before\/} the preamble
% part, in case it is an "\omit", in which case the preamble is to be
% omitted. Instead we switch the mathcode to (hex) 8000, which makes the
% token act as if it were active.
% \item Although \verb|\mathcode`.="8000|  makes {\tt.} act as if it
% were active, it is still not allowed in constructions such as
% "\def.{}", even in math-mode, so we have to construct an active
% version of the separator, this is done by making it the uppercase of
% "~", and then using the construct\\
% "\uppercase{\def~}{"\meta{definition}"}".\\
% Note that the \meta{definition} is not uppercased, so the definition
% can refer to the standard, non-active use of the separator.
% \end{itemize}
%
% \begin{macro}{\DC@}
% \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
% Set up uppercase tables as required, and then grab the first part of
% the numerical argument into "\count@".
%    \begin{macrocode}
\def\DC@#1#2#3{%
  \uccode`\~=`#1\relax
  \m@th
  \afterassignment\DC@x\count@#3\relax{#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DC@x}
% \changes{v1.03}{1996/02/28}{Macro added}
% If "\count@" is negative, centre on the decimal point. If it is
% positive either "#1" will be empty in which case bad out decimal
% part to the number of digits specified by "\count@" or (new feature
% in v1.03) it is none empty in which case "\count@" contains the
% number of digits to the left of the point, and "#1" contains a junk
% token (probably ".") followed by the number of digits to the right
% of the point. In either of these latter cases, "\DC@right" is used.
%    \begin{macrocode}
\def\DC@x#1\relax#2#3{%
  \ifnum\z@>\count@
    \expandafter\DC@centre
  \else
    \expandafter\DC@right
  \fi
  {#2}{#3}{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DC@centre}
% If centering on the decimal point, just need to box up the two halves.
%    \begin{macrocode}
\def\DC@centre#1#2#3{%
  \let\DC@end\DC@endcentre
  \uppercase{\def~}{$\egroup\setbox\tw@=\hbox\bgroup${#2}}%
  \setbox\tw@=\hbox{${\phantom{{#2}}}$}%
  \setbox\z@=\hbox\bgroup$\mathcode`#1="8000 }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DC@endcentre}
% and then pad out the smaller of the two boxes so there is the same
% amount of stuff either side of the point.
%    \begin{macrocode}
\def\DC@endcentre{$\egroup
    \ifdim \wd\z@>\wd\tw@
      \setbox\tw@=\hbox to\wd\z@{\unhbox\tw@\hfill}%
    \else
      \setbox\z@=\hbox to\wd\tw@{\hfill\unhbox\z@}\fi
    \box\z@\box\tw@}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DC@right}
% \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
% This deals with both the cases where a specified number of decimal
% places is given.
%    \begin{macrocode}
\def\DC@right#1#2#3{%
  \ifx\relax#3\relax
%    \end{macrocode}
% If "#3" is empty, add "\hfill" to right align the column, and
% Just set "\DC@rl" to begin a group, so nothing fancy is done with
% the whole number part.
%    \begin{macrocode}
    \hfill
    \let\DC@rl\bgroup
  \else
%    \end{macrocode}
% Otherwise  set "\DC@rl" so that the whole number part is put in a
% box "\count@" times as wide as a digit.
% In order to share code with the other branch, then move "#3" (the
% number of decimal places) into "\count@" throwing away the `.' from
% the user syntax.
% \changes{v1.04}{1996/09/23}{Add \cs{hfill} so integer part
%               is still flush right if no decimal point used.}
%    \begin{macrocode}
    \edef\DC@rl{to\the\count@\dimen@ii\bgroup\hss\hfill}%
    \count@\@gobble#3\relax
  \fi
%    \end{macrocode}
%
%    \begin{macrocode}
  \let\DC@end\DC@endright
%    \end{macrocode}
% Box 2 contains the decimal part, set to "\dimen@" which is
% calculated below to be "\count@" times the width of a digit, plus
% the with of the `decimal point'.
%    \begin{macrocode}
  \uppercase{\def~}{$\egroup\setbox\tw@\hbox to\dimen@\bgroup${#2}}%
   \setbox\z@\hbox{$1$}\dimen@ii\wd\z@
   \dimen@\count@\dimen@ii
   \setbox\z@\hbox{${#2}$}\advance\dimen@\wd\z@
   \setbox\tw@\hbox to\dimen@{}%
%    \end{macrocode}
% Box 0 contains the whole number part, either just at its natural
% size for right aligned columns, or set to (the old value of)
% "\count@" times the width of a digit. "\DC@rl" defined above
% determines the two cases.
%    \begin{macrocode}
   \setbox\z@\hbox\DC@rl$\mathcode`#1="8000 }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DC@endright}
% \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
% Just finish off the second box, and then put out both boxes.
%    \begin{macrocode}
\def\DC@endright{$\hfil\egroup\box\z@\box\tw@}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{D}
% The user interface, define the {\tt D} column to take three arguments.
% For special purposes, you may need to directly access "\DC@" rather
% than the "D" column, eg to get a bold version you could use
%\begin{verbatim}
% \newcolumntype{E}[3]{>{\boldmath\DC@{#1}{#2}{#3}}c<{\DC@end}}
%\end{verbatim}
%    \begin{macrocode}
\newcolumntype{D}[3]{>{\DC@{#1}{#2}{#3}}c<{\DC@end}}
%</package>
%    \end{macrocode}
% \end{macro}
%
%
% \Finale
\endinput