summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2012-05-29 09:48:29 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2012-05-29 09:48:29 (GMT)
commit21a263ff25b234d76b4215f24087263e934110cf (patch)
treea19c305f82d180a47f31466d9bedd2e93df532dc
parenta323b36b630d69fb11b797938d4d360e95fe0e8e (diff)
parent3be8c207009de29d1b986abc9e11c9815a42beec (diff)
downloadtcl-21a263ff25b234d76b4215f24087263e934110cf.zip
tcl-21a263ff25b234d76b4215f24087263e934110cf.tar.gz
tcl-21a263ff25b234d76b4215f24087263e934110cf.tar.bz2
[Bug 2931407]: Clarified semantics of division and remainder operators.
-rw-r--r--ChangeLog5
-rw-r--r--doc/expr.n15
-rw-r--r--doc/mathop.n15
3 files changed, 29 insertions, 6 deletions
diff --git a/ChangeLog b/ChangeLog
index a4cd6bb..17ebcd3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2012-05-29 Donal K. Fellows <dkf@users.sf.net>
+
+ * doc/expr.n, doc/mathop.n: [Bug 2931407]: Clarified semantics of
+ division and remainder operators.
+
2012-05-29 Jan Nijtmans <nijtmans@users.sf.net>
* win/tclWinDde.c: [Bug 3525762]: Encoding handling in dde.
diff --git a/doc/expr.n b/doc/expr.n
index 7b29f81..6d965fb 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -134,7 +134,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
.
diff --git a/doc/mathop.n b/doc/mathop.n
index e359276..ac2ebc1 100644
--- a/doc/mathop.n
+++ b/doc/mathop.n
@@ -126,14 +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