summaryrefslogtreecommitdiff
path: root/macros/generic/modulus/modulus.dtx
blob: 62d970c231694f7e5f471312c007822ff2ac2a46 (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
% \iffalse
% +AMDG  This document was begun on 1 May 1202, the
% feast of St. Joseph the Worker, and it
% is humbly dedicated to him and to the Immaculate Heart of
% Mary for their prayers, and to the Sacred Heart of Jesus 
% for His mercy.
%
% This document is copyright 2018 by Donald P. Goodman, and is
% released publicly under the LaTeX Project Public License.  The
% distribution and modification of this work is constrained by the
% conditions of that license.  See
% 	http://www.latex-project.org/lppl.txt
% for the text of the license.  This document is released
% under version 1.3c of that license, and this work may be distributed
% or modified under the terms of that license or, at your option, any
% later version.
% 
% This work has the LPPL maintenance status 'maintained'.
% 
% The Current Maintainer of this work is Donald P. Goodman
% (dgoodmaniii@gmail.com).
% 
% This work consists of modulus.dtx, modulus.ins, and
% derived files modulus.sty and modulus.pdf.
% \fi

% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{modulus}[2018/05/07 v1.0 Modulus/modulo operator in plain TeX]
%<*driver>
\documentclass{ltxdoc}

\usepackage{doc}
\usepackage{modulus}
\usepackage{booktabs}

\begin{document}
\DocInput{modulus.dtx}
\end{document}
%</driver> \fi
%
% \title{The |modulus| Package, v1.0}
% \author{Donald P.\ Goodman III}
% \date{\today}
%
% \maketitle
%
% \begin{abstract}
% \noindent
% \TeX\ (traditional \TeX, not even $\epsilon$-\TeX) has the four
% basic functions with |\advance|, |\multiply|, and
% |\divide|, though these are all integer operations.  This
% tiny package makes a modulus operator usable with \TeX\
% (or \LaTeX, and probably most flavors).  It also provides a
% non-destructive way of
% getting at the integer quotient of two numbers.
% \end{abstract}
%
% \tableofcontents
%
% \section{The Operators}
%
% One question immediately occurs to me:  why bother with
% such a package, when $\epsilon$-\TeX\ already has
% |\numexpr|, and there are so many advanced packages
% providing real math, and even floating-point operations
% and bignums?  The answer is twofold:  (1) an interesting
% project, and (2) \TeX\ is the archival format, as Knuth
% has always emphasized, and so doing things in ordinary
% \TeX, where possible, should be preferred, to keep it
% such.
%
% The core of the package is \DescribeMacro{\modulo}|\modulo|:
%
% \begin{center}
% \cmd{\modulo} \marg{dividend} \marg{divisor}
% \end{center}
%
% Running this will assign the remainder of the integer
% division of \textit{dividend} and \textit{divisor} to the
% counter \DescribeMacro{\remainder}|\remainder|.  The
% values of \textit{dividend} and \textit{divisor} will not
% be changed, if they are changeable (e.g., if they are
% counters).
%
% Note that the package works with plain \TeX\ counters,
% \emph{not} \LaTeX-style counters created and set with
% |\newcounter{counter}| and friends.  If you try to
% use it with |\thecounter| or |\value{counter}| in the 
% \LaTeX\ style, it will not work.  Fortunately, plain-\TeX\
% counters are perfectly usable within \LaTeX.
%
% We can use the macro as such:
%
% \begin{quote}
% |\modulo{\the\dividend}{\the\divisor}\the\remainder|
% \end{quote}
%
% This will execute the macro and print the resulting
% remainder.  We can also use simple number tokens in the
% same way:
%
% \begin{quote}
% |\modulo{8}{3}\the\remainder|: \modulo{8}{3}\the\remainder
% \end{quote}
%
% In the table above, the divisor is always the
% value of a counter |\testdivisor|, which is 4; the
% dividend is the value of a counter |\testdividend|, which
% is reset as indicated in each line.  We then do the
% modulus operation and print the value of |\remainder| in
% the ``Modulus'' column.  We then reprint the values of
% |\testdividend| and |\testdivisor|, to show that we have
% not altered them by taking the remainder.
%
% \newcount\testdivisor\testdivisor=4
% \newcount\testdividend
%
% \begin{table}[t]
% \centering
% \begin{tabular}{ccccc}
% \toprule
% Dividend & Divisor & Modulus & Dividend & Divisor \\
% \midrule
% \global\testdividend=1\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=2\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=3\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=4\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=5\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=6\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=7\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=8\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \global\testdividend=9\leavevmode\the\testdividend & \the\testdivisor &
%		\modulo{\the\testdividend}{\the\testdivisor}\the\remainder &
%		\the\testdividend & \the\testdivisor \\
% \bottomrule
% \end{tabular}
% \caption{A few example modulos, dividend and divisor both
% before and after the operation.}
% \label{tab:ex}
% \end{table}
%
% Plain \TeX\ can also very simply take the integer quotient
% of a counter, with the |\divide| operator, like so:
%
% \begin{quote}
% |\divide\thiscounter by4|
% \end{quote}
%
% However, this destroys the original value of
% |\thiscounter| (or whatever else one is dividing).  The
% |modulus| package therefore also provides another macro,
% \DescribeMacro{\quotient}|\quotient|, which
% non-destructively takes the integer quotient of two
% numbers and stores it in the counter
% \DescribeMacro{\intquotient}|\intquotient|:
%
% \begin{quote}
% |\quotient{365}{4}\leavevmode\the\intquotient|: \quotient{365}{4}\leavevmode\the\intquotient\\
% |\modulo{365}{4}\leavevmode\the\remainder|: \modulo{365}{4}\leavevmode\the\remainder
% \end{quote}
%
% Note that if |\the\thecounter| doesn't print as expected,
% it may be because you're still in vertical mode (the
% |\the| operator only works in horizontal mode), so try
% |\leavevmode| before printing the counter.
%
% \section{Implementation}
%
% Not much to this one.  We define our counter to hold the
% eventual modulus:
%    \begin{macrocode}
\newcount\remainder%
%    \end{macrocode}
% Then we define the macro which will assign the modulus to
% that counter:
%    \begin{macrocode}
\def\modulo#1#2{%
	\remainder=#1%
	\divide\remainder by#2%
	\multiply\remainder by#2%
	\multiply\remainder by-1%
	\advance\remainder by#1\relax%
}%
%    \end{macrocode}
% Then, for good measure, we also have a macro which will
% non-destructively take the integer quotient of a division, and
% store it in the counter |\intquotient|:
%    \begin{macrocode}
\newcount\intquotient%
\def\quotient#1#2{%
	\intquotient=#1%
	\divide\intquotient by#2%
}%
%    \end{macrocode}
% Happy \TeX{}ing!