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 |
---|