From 3be8c207009de29d1b986abc9e11c9815a42beec Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 29 May 2012 09:44:44 +0000 Subject: [Bug 2931407]: Clarified semantics of division and remainder operators. --- ChangeLog | 5 +++++ doc/expr.n | 15 ++++++++++++++- doc/mathop.n | 16 +++++++++++----- 3 files changed, 30 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4266d9b..43c73c1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2012-05-29 Donal K. Fellows + + * doc/expr.n, doc/mathop.n: [Bug 2931407]: Clarified semantics of + division and remainder operators. + 2012-05-25 Donal K. Fellows * doc/namespace.n, doc/Ensemble.3: [Bug 3528418]: Document what is diff --git a/doc/expr.n b/doc/expr.n index 177e127..dbc9026 100644 --- a/doc/expr.n +++ b/doc/expr.n @@ -131,7 +131,20 @@ Multiply, divide, remainder. None of these operators may be applied to string operands, and remainder may be applied only to integers. The remainder will always have the same sign as the divisor and -an absolute value smaller than the divisor. +an absolute value smaller than the absolute value of the divisor. +.RS +.PP +When applied to integers, the division and remainder operators can be +considered to partition the number line into a sequence of equal-sized +adjacent non-overlapping pieces where each piece is the size of the divisor; +the division result identifies which piece the divisor lay within, and the +remainder result identifies where within that piece the divisor lay. A +consequence of this is that the result of +.QW "-57 \fB/\fR 10" +is always -6, and the result of +.QW "-57 \fB%\fR 10" +is always 3. +.RE .TP 20 \fB+\0\0\-\fR Add and subtract. Valid for any numeric operands. diff --git a/doc/mathop.n b/doc/mathop.n index 5a6ba4e..5757f87 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -126,13 +126,19 @@ will be an integer. .TP \fB%\fR \fInumber number\fR . -Returns the integral modulus of the first argument with respect to the second. -Each \fInumber\fR must have an integral value. Note that Tcl defines this -operation exactly even for negative numbers, so that the following equality -holds true: +Returns the integral modulus (i.e., remainder) of the first argument +with respect to the second. +Each \fInumber\fR must have an integral value. +Also, the sign of the result will be the same as the sign of the second +\fInumber\fR, which must not be zero. .RS +.PP +Note that Tcl defines this operation exactly even for negative numbers, so +that the following command returns a true value (omitting the namespace for +clarity): +.PP .CS -(\fIx \fB/ \fIy\fR) \fB* \fIy \fB== \fIx \fB-\fR (\fIx \fB% \fIy\fR) +\fB==\fR [\fB*\fR [\fB/\fI x y\fR] \fIy\fR] [\fB-\fI x\fR [\fB%\fI x y\fR]] .CE .RE .TP -- cgit v0.12