% \iffalse
% $Id: warpcol.dtx,v 1.4 1998/09/12 05:59:06 wayner Exp $
% 1998-06-08 Wayne A. Rochester
%
%%
%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License Distributed from CTAN archives
%% in directory macros/latex/base/lppl.txt.
%%
%
% Doc-source file for use with LaTeX2e
%
% \fi
% \iffalse
%<*dtx>
\ProvidesFile{warpcol.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{warpcol}
%<driver>\ProvidesFile{warpcol.drv}
% \fi
% \ProvidesFile{warpcol.dtx}
[2007/11/21 v1.0c Numerical column definition]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{warpcol}
\begin{document}
\DocInput{warpcol.dtx}
\end{document}
%</driver>
% \fi
%
% \changes{v1.0a}{1998/06/08}{First release}
% \changes{v1.0b}{1998/09/12}{Prevented macro expansion during pattern scanning}
% \changes{v1.0c}{2007/11/21}{Add LPPL license statement (hv)}
%
% \MakeShortVerb{\|}
% \GetFileInfo{warpcol.dtx}
%
% \title{The |warpcol| package\thanks{This file has version number
% \fileversion, last revised \filedate\ for adding LPPL license statement.}}
% \author{W. A. Rochester}
% \maketitle
% \date{\filedate}
%
% \begin{abstract}
% This file defines a tabular column type for formatting numerical
% columns. The column type enables numerical items to be right justified
% relative to each other, while centred beneath the column label. In
% addition, macros are provided to enable variations on this column type
% to be defined.
% \end{abstract}
%
% \section{Introduction}
%
% The primary aim of this package is to provide a means to centre a
% tabular column label over a column of right-justified numbers.
% However, the package goes further to provide a general mechanism for
% justifying numerical items relative to each other and column labels.
% The package works by justifying each numerical item within a box whose
% width is specified by a `pattern'. The width is calculated as the
% width of the pattern after each number in the pattern is expanded to
% that number of zeros. For example, the pattern `$-3.2$' would be
% expanded to `$-000.00$'. Naturally, pattern width calculation and
% typesetting of numerical items are performed in math mode.
%
% The applications of this package overlap with those of David
% Carlisle's |dcolumn| package, which aligns numbers on their decimal
% points. However, the differing approaches of the packages create a
% number of differences in the ways they can be used. First, the
% |dcolumn| package can align items with varying numbers of decimal
% places. To achieve such alignment with this package, numbers must be
% padded with, for example, the active character |~|, redefined to print
% a space the width of a digit. Second, the present package can align
% items that are not simple numbers. Such items include negative
% numbers, which are not properly handled by the |dcolumn| package
% (but can be if the package is modified slightly).
%
% \section{Usage}
%
% The package defines the |P| column type for use with the most common
% application of the package: centring labels over right-justified
% numbers. This column type is used as follows:
%
% \begin{verbatim}
% \begin{tabular}{P{3.1}P{-2.1}} \hline\hline
% \multicolumn{1}{c}{Label 1} & \multicolumn{1}{c}{Label 2} \\ \hline
% 123.4 & -12.3 \\
%  12.3 &  12.3 \\
%   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \end{verbatim}
%
% \noindent
% \begin{tabular}{P{3.1}P{-2.1}} \hline\hline
% \multicolumn{1}{c}{Label 1} & \multicolumn{1}{c}{Label 2} \\ \hline
% 123.4 & -12.3 \\
%  12.3 &  12.3 \\
%   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \vspace{\baselineskip}
%
% The column labels must be set using the |\multicolumn| command to
% prevent them from being formatted with the |P| column type. Additional
% column types can be defined by the use of the |\pcolbegin| and
% |\pcolend| commands. The |\pcolbegin| command takes two arguments. The
% first is a code (l, c or r) specifying how numerical items should be
% justified relative to each other. The second is the pattern. The
% remaining examples make use of the following definitions (which are
% not included in the package):
%
% \begin{verbatim}
% \newcolumntype{L}[1]{>{\pcolbegin{r}{#1}}l<{\pcolend}}
% \newcolumntype{R}[1]{>{\pcolbegin{r}{#1}}r<{\pcolend}}
% \newcommand{\pcolhd}[1]{\multicolumn{1}{c}{#1}}
% \end{verbatim}
%
% \newcolumntype{L}[1]{>{\pcolbegin{r}{#1}}l<{\pcolend}}
% \newcolumntype{R}[1]{>{\pcolbegin{r}{#1}}r<{\pcolend}}
% \newcommand{\pcolhd}[1]{\multicolumn{1}{c}{#1}}
%
% Column labels are justified correctly regardless of whether they are
% shorter or longer than the numerical items:
%
% \begin{verbatim}
% \begin{tabular}{L{3.1}L{3.1}P{3.1}P{3.1}R{3.1}R{3.1}} \hline\hline
% \multicolumn{1}{l}{SL} & \multicolumn{1}{l}{Long label} &
% \multicolumn{1}{c}{SL} & \multicolumn{1}{c}{Long label} &
% \multicolumn{1}{r}{SL} & \multicolumn{1}{r}{Long label} \\ \hline
% 123.4 & 123.4 & 123.4 & 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 &  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 &   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \end{verbatim}
%
% \noindent
% \begin{tabular}{L{3.1}L{3.1}P{3.1}P{3.1}R{3.1}R{3.1}} \hline\hline
% \multicolumn{1}{l}{SL} & \multicolumn{1}{l}{Long label} &
% \multicolumn{1}{c}{SL} & \multicolumn{1}{c}{Long label} &
% \multicolumn{1}{r}{SL} & \multicolumn{1}{r}{Long label} \\ \hline
% 123.4 & 123.4 & 123.4 & 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 &  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 &   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \vspace{\baselineskip}
%
% Numerical items can be left justified, right justified or centred
% relative to column labels:
%
% \begin{verbatim}
% \begin{tabular}{L{3.1}R{3.1}P{3.1}} \hline\hline
% \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
% \\ \hline
% 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \end{verbatim}
%
% \noindent
% \begin{tabular}{L{3.1}R{3.1}P{3.1}} \hline\hline
% \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
% \\ \hline
% 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \vspace{\baselineskip}
%
% They can also be left justified, right justified or centred relative
% to each other:
%
% \begin{verbatim}
% \begin{tabular}{>{\pcolbegin{l}{3.1}}c<{\pcolend}P{3.1}%
% >{\pcolbegin{c}{3.1}}c<{\pcolend}} \hline\hline
% \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
% \\ \hline
% 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \end{verbatim}
%
% \noindent
% \begin{tabular}{>{\pcolbegin{l}{3.1}}c<{\pcolend}P{3.1}%
% >{\pcolbegin{c}{3.1}}c<{\pcolend}} \hline\hline
% \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
% \\ \hline
% 123.4 & 123.4 & 123.4 \\
%  12.3 &  12.3 &  12.3 \\
%   1.2 &   1.2 &   1.2 \\ \hline\hline
% \end{tabular}
% \vspace{\baselineskip}
%
% Finally, here is an example with columns that contain something other
% than simple numbers:
%
% \begin{verbatim}
% \begin{tabular}{>{\pcolbegin{l}{< 1.3}}c<{\pcolend}P{3\,3.2}}
% \hline\hline
% \pcolhd{$p$} & \pcolhd{Cost (\$)} \\ \hline
% > 0.1   & 123\,456.78 \\
% < 0.1   &  23\,456.78 \\
% < 0.01  &   4\,523.45 \\
% < 0.001 &      345.67 \\ \hline\hline
% \end{tabular}
% \end{verbatim}
%
% \noindent
% \begin{tabular}{L{< 1.3}P{3\,3.2}}
% \hline\hline
% \pcolhd{$p$} & \pcolhd{Cost (\$)} \\ \hline
% > 0.1   & 123\,456.78 \\
% < 0.1   &  23\,456.78 \\
% < 0.01  &   4\,523.45 \\
% < 0.001 &      345.67 \\ \hline\hline
% \end{tabular}
% \vspace{\baselineskip}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Load the |array| package, if it is not already loaded.
%    \begin{macrocode}
\RequirePackage{array}
%    \end{macrocode}
%
% Declare counters and dimensions.
%    \begin{macrocode}
\newcount\WPC@digcnt
\newbox\WPC@patbox
\newbox\WPC@valbox
%    \end{macrocode}
%
% \begin{macro}{\WPC@digval}
% The |\WPC@digval| command prints the given character if the character is a
% digit, and `x' otherwise.
%    \begin{macrocode}
\def\WPC@digval#1{%
\ifx#100%
\else\ifx#111%
\else\ifx#122%
\else\ifx#133%
\else\ifx#144%
\else\ifx#155%
\else\ifx#166%
\else\ifx#177%
\else\ifx#188%
\else\ifx#199%
\else x\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\WPC@digstr}
% The |\WPC@digstr| command prints a row of zeroes the length of the
% count in the |\WPC@digcnt| counter.
%    \begin{macrocode}
\def\WPC@digstr{%
\loop 0\advance\WPC@digcnt by-1 \ifnum\WPC@digcnt>0 \repeat}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\WPC@expandpat}
% The |\WPC@expandpat| command expands the given pattern, for example from
% $-3.2$ to $-000.00$.
%    \begin{macrocode}
\def\WPC@expandpat#1{%
\ifx#1\end
   \ifnum\WPC@digcnt>0 \WPC@digstr\fi
   \let\WPC@next=\relax
\else
   \edef\WPC@dv{\WPC@digval#1}%
   \if x\WPC@dv
      \ifnum\WPC@digcnt>0 \WPC@digstr\fi
      #1%
   \else
      \multiply\WPC@digcnt by10 \advance\WPC@digcnt by\WPC@dv
   \fi
   \let\WPC@next=\WPC@expandpat
\fi
\WPC@next}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pcolbegin}
% The |\pcolbegin| command is executed before column entries. The first argument
% is the justification code (l, r or c), and the second is the pattern (e.g.\
% $-2.1$). The command begins the definition of a box containing the table item.
% The width of the box is set to the width of the expanded pattern. Fill
% commands justify the value within the box. The value is typeset in math mode.
%    \begin{macrocode}
\def\pcolbegin#1#2{%
%    \end{macrocode}
% Initialise the digit count and save the justification code.
%    \begin{macrocode}
\WPC@digcnt=0
\edef\WPC@just{#1}%
%    \end{macrocode}
% Create a box containing the expanded pattern (e.g.\ $-00.0$).
%    \begin{macrocode}
\setbox\WPC@patbox=\hbox{$\WPC@expandpat#2\end$}%
%    \end{macrocode}
% Begin the definition of the value box.
%    \begin{macrocode}
\setbox\WPC@valbox=\hbox to\wd\WPC@patbox\bgroup
\if#1r\hfil\else\if#1c\hfil\fi\fi$}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pcolend}
% The |\pcolend| command is executed after column entries. It completes the box
% definition started by the |\pcolbegin| command, and then prints the box.
%    \begin{macrocode}
\newcommand{\pcolend}{$%
\if l\WPC@just\hfil\else\if c\WPC@just\hfil\fi\fi
\egroup\box\WPC@valbox}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{P}
% Declare the |P| column type.
%    \begin{macrocode}
\newcolumntype{P}[1]{>{\pcolbegin{r}{#1}}c<{\pcolend}}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \DeleteShortVerb{\|}
\endinput