[25] | 1 | .\" -*- nroff -*- |
---|
| 2 | .\" Copyright (c) 2006-2007 Donal K. Fellows. |
---|
| 3 | .\" |
---|
| 4 | .\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | .\" |
---|
| 7 | .\" RCS: @(#) $Id: mathop.n,v 1.10 2007/12/13 15:22:32 dgp Exp $ |
---|
| 8 | .\" |
---|
| 9 | .so man.macros |
---|
| 10 | .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands" |
---|
| 11 | .BS |
---|
| 12 | .\" Note: do not modify the .SH NAME line immediately below! |
---|
| 13 | .SH NAME |
---|
| 14 | mathop \- Mathematical operators as Tcl commands |
---|
| 15 | .SH SYNOPSIS |
---|
| 16 | package require \fBTcl 8.5\fR |
---|
| 17 | .sp |
---|
| 18 | \fB::tcl::mathop::!\fR \fInumber\fR |
---|
| 19 | .br |
---|
| 20 | \fB::tcl::mathop::~\fR \fInumber\fR |
---|
| 21 | .br |
---|
| 22 | \fB::tcl::mathop::+\fR ?\fInumber\fR ...? |
---|
| 23 | .br |
---|
| 24 | \fB::tcl::mathop::\-\fR \fInumber\fR ?\fInumber\fR ...? |
---|
| 25 | .br |
---|
| 26 | \fB::tcl::mathop::*\fR ?\fInumber\fR ...? |
---|
| 27 | .br |
---|
| 28 | \fB::tcl::mathop::/\fR \fInumber\fR ?\fInumber\fR ...? |
---|
| 29 | .br |
---|
| 30 | \fB::tcl::mathop::%\fR \fInumber number\fR |
---|
| 31 | .br |
---|
| 32 | \fB::tcl::mathop::**\fR ?\fInumber\fR ...? |
---|
| 33 | .br |
---|
| 34 | \fB::tcl::mathop::&\fR ?\fInumber\fR ...? |
---|
| 35 | .br |
---|
| 36 | \fB::tcl::mathop::|\fR ?\fInumber\fR ...? |
---|
| 37 | .br |
---|
| 38 | \fB::tcl::mathop::^\fR ?\fInumber\fR ...? |
---|
| 39 | .br |
---|
| 40 | \fB::tcl::mathop::<<\fR \fInumber number\fR |
---|
| 41 | .br |
---|
| 42 | \fB::tcl::mathop::>>\fR \fInumber number\fR |
---|
| 43 | .br |
---|
| 44 | \fB::tcl::mathop::==\fR ?\fIarg\fR ...? |
---|
| 45 | .br |
---|
| 46 | \fB::tcl::mathop::!=\fR \fIarg arg\fR |
---|
| 47 | .br |
---|
| 48 | \fB::tcl::mathop::<\fR ?\fIarg\fR ...? |
---|
| 49 | .br |
---|
| 50 | \fB::tcl::mathop::<=\fR ?\fIarg\fR ...? |
---|
| 51 | .br |
---|
| 52 | \fB::tcl::mathop::>=\fR ?\fIarg\fR ...? |
---|
| 53 | .br |
---|
| 54 | \fB::tcl::mathop::>\fR ?\fIarg\fR ...? |
---|
| 55 | .br |
---|
| 56 | \fB::tcl::mathop::eq\fR ?\fIarg\fR ...? |
---|
| 57 | .br |
---|
| 58 | \fB::tcl::mathop::ne\fR \fIarg arg\fR |
---|
| 59 | .br |
---|
| 60 | \fB::tcl::mathop::in\fR \fIarg list\fR |
---|
| 61 | .br |
---|
| 62 | \fB::tcl::mathop::ni\fR \fIarg list\fR |
---|
| 63 | .sp |
---|
| 64 | .BE |
---|
| 65 | .SH DESCRIPTION |
---|
| 66 | .PP |
---|
| 67 | The commands in the \fB::tcl::mathop\fR namespace implement the same set of |
---|
| 68 | operations as supported by the \fBexpr\fR command. All are exported from the |
---|
| 69 | namespace, but are not imported into any other namespace by default. Note that |
---|
| 70 | renaming, reimplementing or deleting any of the commands in the namespace does |
---|
| 71 | \fInot\fR alter the way that the \fBexpr\fR command behaves, and nor does |
---|
| 72 | defining any new commands in the \fB::tcl::mathop\fR namespace. |
---|
| 73 | .PP |
---|
| 74 | The following operator commands are supported: |
---|
| 75 | .DS |
---|
| 76 | .ta 2c 4c 6c 8c |
---|
| 77 | \fB~\fR \fB!\fR \fB+\fR \fB\-\fR \fB*\fR |
---|
| 78 | \fB/\fR \fB%\fR \fB**\fR \fB&\fR \fB|\fR |
---|
| 79 | \fB^\fR \fB>>\fR \fB<<\fR \fB==\fR \fBeq\fR |
---|
| 80 | \fB!=\fR \fBne\fR \fB<\fR \fB<=\fR \fB>\fR |
---|
| 81 | \fB>=\fR \fBin\fR \fBni\fR |
---|
| 82 | .DE |
---|
| 83 | .SS "MATHEMATICAL OPERATORS" |
---|
| 84 | .PP |
---|
| 85 | The behaviors of the mathematical operator commands are as follows: |
---|
| 86 | .TP |
---|
| 87 | \fB!\fR \fIboolean\fR |
---|
| 88 | . |
---|
| 89 | Returns the boolean negation of \fIboolean\fR, where \fIboolean\fR may be any |
---|
| 90 | numeric value or any other form of boolean value (i.e. it returns truth if the |
---|
| 91 | argument is falsity or zero, and falsity if the argument is truth or |
---|
| 92 | non-zero). |
---|
| 93 | .TP |
---|
| 94 | \fB+\fR ?\fInumber\fR ...? |
---|
| 95 | . |
---|
| 96 | Returns the sum of arbitrarily many arguments. Each \fInumber\fR argument may |
---|
| 97 | be any numeric value. If no arguments are given, the result will be zero (the |
---|
| 98 | summation identity). |
---|
| 99 | .TP |
---|
| 100 | \fB\-\fR \fInumber\fR ?\fInumber\fR ...? |
---|
| 101 | . |
---|
| 102 | If only a single \fInumber\fR argument is given, returns the negation of that |
---|
| 103 | numeric value. Otherwise returns the number that results when all subsequent |
---|
| 104 | numeric values are subtracted from the first one. All \fInumber\fR arguments |
---|
| 105 | must be numeric values. At least one argument must be given. |
---|
| 106 | .TP |
---|
| 107 | \fB*\fR ?\fInumber\fR ...? |
---|
| 108 | . |
---|
| 109 | Returns the product of arbitrarily many arguments. Each \fInumber\fR may be |
---|
| 110 | any numeric value. If no arguments are given, the result will be one (the |
---|
| 111 | multiplicative identity). |
---|
| 112 | .TP |
---|
| 113 | \fB/\fR \fInumber\fR ?\fInumber\fR ...? |
---|
| 114 | . |
---|
| 115 | If only a single \fInumber\fR argument is given, returns the reciprocal of that |
---|
| 116 | numeric value (i.e. the value obtained by dividing 1.0 by that value). |
---|
| 117 | Otherwise returns the number that results when the first numeric argument is |
---|
| 118 | divided by all subsequent numeric arguments. All \fInumber\fR arguments must |
---|
| 119 | be numeric values. At least one argument must be given. |
---|
| 120 | .RS |
---|
| 121 | .PP |
---|
| 122 | Note that when the leading values in the list of arguments are integers, |
---|
| 123 | integer division will be used for those initial steps (i.e. the intermediate |
---|
| 124 | results will be as if the functions \fIfloor\fR and \fIint\fR are applied to |
---|
| 125 | them, in that order). If all values in the operation are integers, the result |
---|
| 126 | will be an integer. |
---|
| 127 | .RE |
---|
| 128 | .TP |
---|
| 129 | \fB%\fR \fInumber number\fR |
---|
| 130 | . |
---|
| 131 | Returns the integral modulus of the first argument with respect to the second. |
---|
| 132 | Each \fInumber\fR must have an integral value. Note that Tcl defines this |
---|
| 133 | operation exactly even for negative numbers, so that the following equality |
---|
| 134 | holds true: |
---|
| 135 | .RS |
---|
| 136 | .CS |
---|
| 137 | (\fIx \fB/ \fIy\fR) \fB* \fIy \fB== \fIx \fB-\fR (\fIx \fB% \fIy\fR) |
---|
| 138 | .CE |
---|
| 139 | .RE |
---|
| 140 | .TP |
---|
| 141 | \fB**\fR ?\fInumber\fR ...? |
---|
| 142 | . |
---|
| 143 | Returns the result of raising each value to the power of the result of |
---|
| 144 | recursively operating on the result of processing the following arguments, so |
---|
| 145 | .QW "\fB** 2 3 4\fR" |
---|
| 146 | is the same as |
---|
| 147 | .QW "\fB** 2 [** 3 4]\fR" . |
---|
| 148 | Each \fInumber\fR may be |
---|
| 149 | any numeric value, though the second number must not be fractional if the |
---|
| 150 | first is negative. If no arguments are given, the result will be one, and if |
---|
| 151 | only one argument is given, the result will be that argument. The |
---|
| 152 | result will have an integral value only when all arguments are |
---|
| 153 | integral values. |
---|
| 154 | .SS "COMPARISON OPERATORS" |
---|
| 155 | .PP |
---|
| 156 | The behaviors of the comparison operator commands (most of which operate |
---|
| 157 | preferentially on numeric arguments) are as follows: |
---|
| 158 | .TP |
---|
| 159 | \fB==\fR ?\fIarg\fR ...? |
---|
| 160 | . |
---|
| 161 | Returns whether each argument is equal to the arguments on each side of it in |
---|
| 162 | the sense of the \fBexpr\fR == operator (\fIi.e.\fR, numeric comparison if |
---|
| 163 | possible, exact string comparison otherwise). If fewer than two arguments |
---|
| 164 | are given, this operation always returns a true value. |
---|
| 165 | .TP |
---|
| 166 | \fBeq\fR ?\fIarg\fR ...? |
---|
| 167 | . |
---|
| 168 | Returns whether each argument is equal to the arguments on each side of it |
---|
| 169 | using exact string comparison. If fewer than two arguments are given, this |
---|
| 170 | operation always returns a true value. |
---|
| 171 | .TP |
---|
| 172 | \fB!=\fR \fIarg arg\fR |
---|
| 173 | . |
---|
| 174 | Returns whether the two arguments are not equal to each other, in the sense of |
---|
| 175 | the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible, exact |
---|
| 176 | string comparison otherwise). |
---|
| 177 | .TP |
---|
| 178 | \fBne\fR \fIarg arg\fR |
---|
| 179 | . |
---|
| 180 | Returns whether the two arguments are not equal to each other using exact |
---|
| 181 | string comparison. |
---|
| 182 | .TP |
---|
| 183 | \fB<\fR ?\fIarg\fR ...? |
---|
| 184 | . |
---|
| 185 | Returns whether the arbitrarily-many arguments are ordered, with each argument |
---|
| 186 | after the first having to be strictly more than the one preceding it. |
---|
| 187 | Comparisons are performed preferentially on the numeric values, and are |
---|
| 188 | otherwise performed using UNICODE string comparison. If fewer than two |
---|
| 189 | arguments are present, this operation always returns a true value. When the |
---|
| 190 | arguments are numeric but should be compared as strings, the \fBstring |
---|
| 191 | compare\fR command should be used instead. |
---|
| 192 | .TP |
---|
| 193 | \fB<=\fR ?\fIarg\fR ...? |
---|
| 194 | . |
---|
| 195 | Returns whether the arbitrarily-many arguments are ordered, with each argument |
---|
| 196 | after the first having to be equal to or more than the one preceding it. |
---|
| 197 | Comparisons are performed preferentially on the numeric values, and are |
---|
| 198 | otherwise performed using UNICODE string comparison. If fewer than two |
---|
| 199 | arguments are present, this operation always returns a true value. When the |
---|
| 200 | arguments are numeric but should be compared as strings, the \fBstring |
---|
| 201 | compare\fR command should be used instead. |
---|
| 202 | .TP |
---|
| 203 | \fB>\fR ?\fIarg\fR ...? |
---|
| 204 | . |
---|
| 205 | Returns whether the arbitrarily-many arguments are ordered, with each argument |
---|
| 206 | after the first having to be strictly less than the one preceding it. |
---|
| 207 | Comparisons are performed preferentially on the numeric values, and are |
---|
| 208 | otherwise performed using UNICODE string comparison. If fewer than two |
---|
| 209 | arguments are present, this operation always returns a true value. When the |
---|
| 210 | arguments are numeric but should be compared as strings, the \fBstring |
---|
| 211 | compare\fR command should be used instead. |
---|
| 212 | .TP |
---|
| 213 | \fB>=\fR ?\fIarg\fR ...? |
---|
| 214 | . |
---|
| 215 | Returns whether the arbitrarily-many arguments are ordered, with each argument |
---|
| 216 | after the first having to be equal to or less than the one preceding it. |
---|
| 217 | Comparisons are performed preferentially on the numeric values, and are |
---|
| 218 | otherwise performed using UNICODE string comparison. If fewer than two |
---|
| 219 | arguments are present, this operation always returns a true value. When the |
---|
| 220 | arguments are numeric but should be compared as strings, the \fBstring |
---|
| 221 | compare\fR command should be used instead. |
---|
| 222 | .SS "BIT-WISE OPERATORS" |
---|
| 223 | .PP |
---|
| 224 | The behaviors of the bit-wise operator commands (all of which only operate on |
---|
| 225 | integral arguments) are as follows: |
---|
| 226 | .TP |
---|
| 227 | \fB~\fR \fInumber\fR |
---|
| 228 | . |
---|
| 229 | Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer |
---|
| 230 | of any size. Note that the result of this operation will always have the |
---|
| 231 | opposite sign to the input \fInumber\fR. |
---|
| 232 | .TP |
---|
| 233 | \fB&\fR ?\fInumber\fR ...? |
---|
| 234 | . |
---|
| 235 | Returns the bit-wise AND of each of the arbitrarily many arguments. Each |
---|
| 236 | \fInumber\fR must have an integral value. If no arguments are given, the |
---|
| 237 | result will be minus one. |
---|
| 238 | .TP |
---|
| 239 | \fB|\fR ?\fInumber\fR ...? |
---|
| 240 | . |
---|
| 241 | Returns the bit-wise OR of each of the arbitrarily many arguments. Each |
---|
| 242 | \fInumber\fR must have an integral value. If no arguments are given, the |
---|
| 243 | result will be zero..TP |
---|
| 244 | \fB^\fR ?\fInumber\fR ...? |
---|
| 245 | . |
---|
| 246 | Returns the bit-wise XOR of each of the arbitrarily many arguments. Each |
---|
| 247 | \fInumber\fR must have an integral value. If no arguments are given, the |
---|
| 248 | result will be zero. |
---|
| 249 | .TP |
---|
| 250 | \fB<<\fR \fInumber number\fR |
---|
| 251 | . |
---|
| 252 | Returns the result of bit-wise shifting the first argument left by the |
---|
| 253 | number of bits specified in the second argument. Each \fInumber\fR |
---|
| 254 | must have an integral value. |
---|
| 255 | .TP |
---|
| 256 | \fB>>\fR \fInumber number\fR |
---|
| 257 | . |
---|
| 258 | Returns the result of bit-wise shifting the first argument right by |
---|
| 259 | the number of bits specified in the second argument. Each \fInumber\fR |
---|
| 260 | must have an integral value. |
---|
| 261 | .SS "LIST OPERATORS" |
---|
| 262 | .PP |
---|
| 263 | The behaviors of the list-oriented operator commands are as follows: |
---|
| 264 | .TP |
---|
| 265 | \fBin\fR \fIarg list\fR |
---|
| 266 | . |
---|
| 267 | Returns whether the value \fIarg\fR is present in the list \fIlist\fR |
---|
| 268 | (according to exact string comparison of elements). |
---|
| 269 | .TP |
---|
| 270 | \fBni\fR \fIarg list\fR |
---|
| 271 | . |
---|
| 272 | Returns whether the value \fIarg\fR is not present in the list \fIlist\fR |
---|
| 273 | (according to exact string comparison of elements). |
---|
| 274 | .SH EXAMPLES |
---|
| 275 | The simplest way to use the operators is often by using \fBnamespace path\fR |
---|
| 276 | to make the commands available. This has the advantage of not affecting the |
---|
| 277 | set of commands defined by the current namespace. |
---|
| 278 | .CS |
---|
| 279 | namespace path {\fB::tcl::mathop\fR ::tcl::mathfunc} |
---|
| 280 | |
---|
| 281 | \fI# Compute the sum of some numbers\fR |
---|
| 282 | set sum [\fB+\fR 1 2 3] |
---|
| 283 | |
---|
| 284 | \fI# Compute the average of a list\fR |
---|
| 285 | set list {1 2 3 4 5 6} |
---|
| 286 | set mean [\fB/\fR [\fB+\fR {*}$list] [double [llength $list]]] |
---|
| 287 | |
---|
| 288 | \fI# Test for list membership\fR |
---|
| 289 | set gotIt [\fBin\fR 3 $list] |
---|
| 290 | |
---|
| 291 | \fI# Test to see if a value is within some defined range\fR |
---|
| 292 | set inRange [\fB<=\fR 1 $x 5] |
---|
| 293 | |
---|
| 294 | \fI# Test to see if a list is sorted\fR |
---|
| 295 | set sorted [\fB<=\fR {*}$list] |
---|
| 296 | .CE |
---|
| 297 | .SH "SEE ALSO" |
---|
| 298 | expr(n), mathfunc(n), namespace(n) |
---|
| 299 | .SH KEYWORDS |
---|
| 300 | command, expression, operator |
---|