Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "OVERLOAD 1" | |
132 | .TH OVERLOAD 1 "2001-10-08" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Bit::Vector::Overload \- Overloaded operators add\-on for Bit::Vector | |
135 | .SH "USAGE" | |
136 | .IX Header "USAGE" | |
137 | Note that you do not need to "\f(CW\*(C`use Bit::Vector;\*(C'\fR" | |
138 | in addition to this module. | |
139 | .PP | |
140 | Simply "\f(CW\*(C`use Bit::Vector::Overload;\*(C'\fR" \fB\s-1INSTEAD\s0\fR | |
141 | of "\f(CW\*(C`use Bit::Vector;\*(C'\fR\*(L". You can still use all the | |
142 | methods from the \*(R"Bit::Vector" module in addition | |
143 | to the overloaded operators and methods provided | |
144 | here after that. | |
145 | .SH "SYNOPSIS" | |
146 | .IX Header "SYNOPSIS" | |
147 | .Vb 4 | |
148 | \& Configuration | |
149 | \& $config = Bit::Vector->Configuration(); | |
150 | \& Bit::Vector->Configuration($config); | |
151 | \& $oldconfig = Bit::Vector->Configuration($newconfig); | |
152 | .Ve | |
153 | .PP | |
154 | .Vb 3 | |
155 | \& String Conversion | |
156 | \& $string = "$vector"; # depending on configuration | |
157 | \& print "\e$vector = '$vector'\en"; | |
158 | .Ve | |
159 | .PP | |
160 | .Vb 4 | |
161 | \& Emptyness | |
162 | \& if ($vector) # if not empty (non-zero) | |
163 | \& if (! $vector) # if empty (zero) | |
164 | \& unless ($vector) # if empty (zero) | |
165 | .Ve | |
166 | .PP | |
167 | .Vb 3 | |
168 | \& Complement (one's complement) | |
169 | \& $vector2 = ~$vector1; | |
170 | \& $vector = ~$vector; | |
171 | .Ve | |
172 | .PP | |
173 | .Vb 3 | |
174 | \& Negation (two's complement) | |
175 | \& $vector2 = -$vector1; | |
176 | \& $vector = -$vector; | |
177 | .Ve | |
178 | .PP | |
179 | .Vb 2 | |
180 | \& Norm | |
181 | \& $norm = abs($vector); # depending on configuration | |
182 | .Ve | |
183 | .PP | |
184 | .Vb 2 | |
185 | \& Absolute | |
186 | \& $vector2 = abs($vector1); # depending on configuration | |
187 | .Ve | |
188 | .PP | |
189 | .Vb 7 | |
190 | \& Concatenation | |
191 | \& $vector3 = $vector1 . $vector2; | |
192 | \& $vector1 .= $vector2; | |
193 | \& $vector1 = $vector2 . $vector1; | |
194 | \& $vector2 = $vector1 . $scalar; # depending on configuration | |
195 | \& $vector2 = $scalar . $vector1; | |
196 | \& $vector .= $scalar; | |
197 | .Ve | |
198 | .PP | |
199 | .Vb 3 | |
200 | \& Duplication | |
201 | \& $vector2 = $vector1 x $factor; | |
202 | \& $vector x= $factor; | |
203 | .Ve | |
204 | .PP | |
205 | .Vb 3 | |
206 | \& Shift Left | |
207 | \& $vector2 = $vector1 << $bits; | |
208 | \& $vector <<= $bits; | |
209 | .Ve | |
210 | .PP | |
211 | .Vb 3 | |
212 | \& Shift Right | |
213 | \& $vector2 = $vector1 >> $bits; | |
214 | \& $vector >>= $bits; | |
215 | .Ve | |
216 | .PP | |
217 | .Vb 5 | |
218 | \& Union | |
219 | \& $vector3 = $vector1 | $vector2; | |
220 | \& $vector1 |= $vector2; | |
221 | \& $vector2 = $vector1 | $scalar; | |
222 | \& $vector |= $scalar; | |
223 | .Ve | |
224 | .PP | |
225 | .Vb 4 | |
226 | \& $vector3 = $vector1 + $vector2; # depending on configuration | |
227 | \& $vector1 += $vector2; | |
228 | \& $vector2 = $vector1 + $scalar; | |
229 | \& $vector += $scalar; | |
230 | .Ve | |
231 | .PP | |
232 | .Vb 5 | |
233 | \& Intersection | |
234 | \& $vector3 = $vector1 & $vector2; | |
235 | \& $vector1 &= $vector2; | |
236 | \& $vector2 = $vector1 & $scalar; | |
237 | \& $vector &= $scalar; | |
238 | .Ve | |
239 | .PP | |
240 | .Vb 4 | |
241 | \& $vector3 = $vector1 * $vector2; # depending on configuration | |
242 | \& $vector1 *= $vector2; | |
243 | \& $vector2 = $vector1 * $scalar; | |
244 | \& $vector *= $scalar; | |
245 | .Ve | |
246 | .PP | |
247 | .Vb 5 | |
248 | \& ExclusiveOr | |
249 | \& $vector3 = $vector1 ^ $vector2; | |
250 | \& $vector1 ^= $vector2; | |
251 | \& $vector2 = $vector1 ^ $scalar; | |
252 | \& $vector ^= $scalar; | |
253 | .Ve | |
254 | .PP | |
255 | .Vb 7 | |
256 | \& Set Difference | |
257 | \& $vector3 = $vector1 - $vector2; # depending on configuration | |
258 | \& $vector1 -= $vector2; | |
259 | \& $vector1 = $vector2 - $vector1; | |
260 | \& $vector2 = $vector1 - $scalar; | |
261 | \& $vector2 = $scalar - $vector1; | |
262 | \& $vector -= $scalar; | |
263 | .Ve | |
264 | .PP | |
265 | .Vb 5 | |
266 | \& Addition | |
267 | \& $vector3 = $vector1 + $vector2; # depending on configuration | |
268 | \& $vector1 += $vector2; | |
269 | \& $vector2 = $vector1 + $scalar; | |
270 | \& $vector += $scalar; | |
271 | .Ve | |
272 | .PP | |
273 | .Vb 7 | |
274 | \& Subtraction | |
275 | \& $vector3 = $vector1 - $vector2; # depending on configuration | |
276 | \& $vector1 -= $vector2; | |
277 | \& $vector1 = $vector2 - $vector1; | |
278 | \& $vector2 = $vector1 - $scalar; | |
279 | \& $vector2 = $scalar - $vector1; | |
280 | \& $vector -= $scalar; | |
281 | .Ve | |
282 | .PP | |
283 | .Vb 5 | |
284 | \& Multiplication | |
285 | \& $vector3 = $vector1 * $vector2; # depending on configuration | |
286 | \& $vector1 *= $vector2; | |
287 | \& $vector2 = $vector1 * $scalar; | |
288 | \& $vector *= $scalar; | |
289 | .Ve | |
290 | .PP | |
291 | .Vb 7 | |
292 | \& Division | |
293 | \& $vector3 = $vector1 / $vector2; | |
294 | \& $vector1 /= $vector2; | |
295 | \& $vector1 = $vector2 / $vector1; | |
296 | \& $vector2 = $vector1 / $scalar; | |
297 | \& $vector2 = $scalar / $vector1; | |
298 | \& $vector /= $scalar; | |
299 | .Ve | |
300 | .PP | |
301 | .Vb 7 | |
302 | \& Modulo | |
303 | \& $vector3 = $vector1 % $vector2; | |
304 | \& $vector1 %= $vector2; | |
305 | \& $vector1 = $vector2 % $vector1; | |
306 | \& $vector2 = $vector1 % $scalar; | |
307 | \& $vector2 = $scalar % $vector1; | |
308 | \& $vector %= $scalar; | |
309 | .Ve | |
310 | .PP | |
311 | .Vb 6 | |
312 | \& Exponentiation | |
313 | \& $vector3 = $vector1 ** $vector2; | |
314 | \& $vector1 **= $vector2; | |
315 | \& $vector2 = $vector1 ** $scalar; | |
316 | \& $vector2 = $scalar ** $vector1; | |
317 | \& $vector **= $scalar; | |
318 | .Ve | |
319 | .PP | |
320 | .Vb 3 | |
321 | \& Increment | |
322 | \& ++$vector; | |
323 | \& $vector++; | |
324 | .Ve | |
325 | .PP | |
326 | .Vb 3 | |
327 | \& Decrement | |
328 | \& --$vector; | |
329 | \& $vector--; | |
330 | .Ve | |
331 | .PP | |
332 | .Vb 6 | |
333 | \& Lexical Comparison (unsigned) | |
334 | \& $cmp = $vector1 cmp $vector2; | |
335 | \& if ($vector1 lt $vector2) | |
336 | \& if ($vector1 le $vector2) | |
337 | \& if ($vector1 gt $vector2) | |
338 | \& if ($vector1 ge $vector2) | |
339 | .Ve | |
340 | .PP | |
341 | .Vb 5 | |
342 | \& $cmp = $vector cmp $scalar; | |
343 | \& if ($vector lt $scalar) | |
344 | \& if ($vector le $scalar) | |
345 | \& if ($vector gt $scalar) | |
346 | \& if ($vector ge $scalar) | |
347 | .Ve | |
348 | .PP | |
349 | .Vb 6 | |
350 | \& Comparison (signed) | |
351 | \& $cmp = $vector1 <=> $vector2; | |
352 | \& if ($vector1 < $vector2) # depending on configuration | |
353 | \& if ($vector1 <= $vector2) | |
354 | \& if ($vector1 > $vector2) | |
355 | \& if ($vector1 >= $vector2) | |
356 | .Ve | |
357 | .PP | |
358 | .Vb 5 | |
359 | \& $cmp = $vector <=> $scalar; | |
360 | \& if ($vector < $scalar) # depending on configuration | |
361 | \& if ($vector <= $scalar) | |
362 | \& if ($vector > $scalar) | |
363 | \& if ($vector >= $scalar) | |
364 | .Ve | |
365 | .PP | |
366 | .Vb 5 | |
367 | \& Equality | |
368 | \& if ($vector1 eq $vector2) | |
369 | \& if ($vector1 ne $vector2) | |
370 | \& if ($vector eq $scalar) | |
371 | \& if ($vector ne $scalar) | |
372 | .Ve | |
373 | .PP | |
374 | .Vb 4 | |
375 | \& if ($vector1 == $vector2) | |
376 | \& if ($vector1 != $vector2) | |
377 | \& if ($vector == $scalar) | |
378 | \& if ($vector != $scalar) | |
379 | .Ve | |
380 | .PP | |
381 | .Vb 2 | |
382 | \& Subset Relationship | |
383 | \& if ($vector1 <= $vector2) # depending on configuration | |
384 | .Ve | |
385 | .PP | |
386 | .Vb 2 | |
387 | \& True Subset Relationship | |
388 | \& if ($vector1 < $vector2) # depending on configuration | |
389 | .Ve | |
390 | .PP | |
391 | .Vb 2 | |
392 | \& Superset Relationship | |
393 | \& if ($vector1 >= $vector2) # depending on configuration | |
394 | .Ve | |
395 | .PP | |
396 | .Vb 2 | |
397 | \& True Superset Relationship | |
398 | \& if ($vector1 > $vector2) # depending on configuration | |
399 | .Ve | |
400 | .SH "IMPORTANT NOTES" | |
401 | .IX Header "IMPORTANT NOTES" | |
402 | .IP "\(bu" 2 | |
403 | Boolean values | |
404 | .Sp | |
405 | Boolean values in this module are always a numeric zero ("\f(CW0\fR\*(L") for | |
406 | \&\*(R"false\*(L" and a numeric one (\*(R"\f(CW1\fR\*(L") for \*(R"true". | |
407 | .IP "\(bu" 2 | |
408 | Negative numbers | |
409 | .Sp | |
410 | Numeric factors (as needed for the "\f(CW\*(C`<<\*(C'\fR\*(L", \*(R"\f(CW\*(C`>>\*(C'\fR\*(L" | |
411 | and \*(R"\f(CW\*(C`x\*(C'\fR" operators) and bit numbers are always regarded as being | |
412 | \&\fB\s-1UNSIGNED\s0\fR. | |
413 | .Sp | |
414 | As a consequence, whenever you pass a negative number for such a factor | |
415 | or bit number, it will be treated as a (usually very large) positive | |
416 | number due to its internal two's complement binary representation, usually | |
417 | resulting in malfunctions or an \*(L"index out of range\*(R" error message and | |
418 | program abortion. | |
419 | .Sp | |
420 | Note that this does not apply to \*(L"big integer\*(R" decimal numbers, which | |
421 | are (usually) passed as strings, and which may of course be negative | |
422 | (see also the section \*(L"Big integers\*(R" a little further below). | |
423 | .IP "\(bu" 2 | |
424 | Overloaded operators configuration | |
425 | .Sp | |
426 | Note that the behaviour of certain overloaded operators can be changed | |
427 | in various ways by means of the "\f(CW\*(C`Configuration()\*(C'\fR" method (for more | |
428 | details, see the description of this method further below). | |
429 | .Sp | |
430 | For instance, scalars (i.e., numbers and strings) provided as operands | |
431 | to overloaded operators are automatically converted to bit vectors, | |
432 | internally. | |
433 | .Sp | |
434 | These scalars are thereby automatically assumed to be indices or to be | |
435 | in hexadecimal, binary, decimal or enumeration format, depending on the | |
436 | configuration. | |
437 | .Sp | |
438 | Similarly, when converting bit vectors to strings using double quotes | |
439 | (""), the output format will also depend on the previously chosen | |
440 | configuration. | |
441 | .Sp | |
442 | Finally, some overloaded operators may have different semantics depending | |
443 | on the proper configuration; for instance, the operator \*(L"+\*(R" can be the | |
444 | \&\*(L"union\*(R" operator from set theory or the arithmetic \*(L"add\*(R" operator. | |
445 | .Sp | |
446 | In all cases (input, output and operator semantics), the defaults have | |
447 | been chosen in such a way so that the behaviour of the module is backward | |
448 | compatible with previous versions. | |
449 | .IP "\(bu" 2 | |
450 | \&\*(L"Big integers\*(R" | |
451 | .Sp | |
452 | As long as \*(L"big integers\*(R" (for \*(L"big integer\*(R" arithmetic) are small enough | |
453 | so that Perl doesn't need scientific notation (exponents) to be able to | |
454 | represent them internally, you can provide these \*(L"big integer\*(R" constants | |
455 | to the overloaded operators of this module (or to the method "\f(CW\*(C`from_Dec()\*(C'\fR") | |
456 | in numeric form (i.e., either as a numeric constant or expression or as a | |
457 | Perl variable containing a numeric value). | |
458 | .Sp | |
459 | Note that you will get an error message (resulting in program abortion) | |
460 | if your \*(L"big integer\*(R" numbers exceed that limit. | |
461 | .Sp | |
462 | Because this limit is machine-dependent and not obvious to find out, | |
463 | it is strongly recommended that you enclose \fB\s-1ALL\s0\fR your \*(L"big integer\*(R" | |
464 | constants in your programs in (double or single) quotes. | |
465 | .Sp | |
466 | Examples: | |
467 | .Sp | |
468 | .Vb 1 | |
469 | \& $vector /= 10; # ok because number is small | |
470 | .Ve | |
471 | .Sp | |
472 | .Vb 1 | |
473 | \& $vector /= -10; # ok for same reason | |
474 | .Ve | |
475 | .Sp | |
476 | .Vb 1 | |
477 | \& $vector /= "10"; # always correct | |
478 | .Ve | |
479 | .Sp | |
480 | .Vb 1 | |
481 | \& $vector += "1152921504606846976"; # quotes probably required here | |
482 | .Ve | |
483 | .Sp | |
484 | All examples assume | |
485 | .Sp | |
486 | .Vb 1 | |
487 | \& Bit::Vector->Configuration("input=decimal"); | |
488 | .Ve | |
489 | .Sp | |
490 | having been set beforehand. | |
491 | .Sp | |
492 | Note also that this module does not support scientific notation (exponents) | |
493 | for \*(L"big integer\*(R" decimal numbers because you can always make the bit vector | |
494 | large enough for the whole number to fit without loss of precision (as it | |
495 | would occur if scientific notation were used). | |
496 | .Sp | |
497 | Finally, note that the only characters allowed in \*(L"big integer\*(R" constant | |
498 | strings are the digits \f(CW0..9\fR and an optional leading sign ("\f(CW\*(C`+\*(C'\fR\*(L" or \*(R"\f(CW\*(C`\-\*(C'\fR"). | |
499 | .Sp | |
500 | All other characters produce a syntax error. | |
501 | .IP "\(bu" 2 | |
502 | Valid operands for overloaded operators | |
503 | .Sp | |
504 | All overloaded operators expect at least one bit vector operand, | |
505 | in order for the operator to \*(L"know\*(R" that not the usual operation | |
506 | is to be carried out, but rather the overloaded variant. | |
507 | .Sp | |
508 | This is especially true for all unary operators: | |
509 | .Sp | |
510 | .Vb 10 | |
511 | \& "$vector" | |
512 | \& if ($vector) | |
513 | \& if (!$vector) | |
514 | \& ~$vector | |
515 | \& -$vector | |
516 | \& abs($vector) | |
517 | \& ++$vector | |
518 | \& $vector++ | |
519 | \& --$vector | |
520 | \& $vector-- | |
521 | .Ve | |
522 | .Sp | |
523 | For obvious reasons the left operand (the \*(L"lvalue\*(R") of all | |
524 | assignment operators is also required to be a bit vector: | |
525 | .Sp | |
526 | .Vb 13 | |
527 | \& .= | |
528 | \& x= | |
529 | \& <<= | |
530 | \& >>= | |
531 | \& |= | |
532 | \& &= | |
533 | \& ^= | |
534 | \& += | |
535 | \& -= | |
536 | \& *= | |
537 | \& /= | |
538 | \& %= | |
539 | \& **= | |
540 | .Ve | |
541 | .Sp | |
542 | In the case of three special operators, namely "\f(CW\*(C`<<\*(C'\fR\*(L", | |
543 | \&\*(R"\f(CW\*(C`>>\*(C'\fR\*(L" and \*(R"\f(CW\*(C`x\*(C'\fR\*(L", as well as their related assignment | |
544 | variants, \*(R"\f(CW\*(C`<<=\*(C'\fR\*(L", \*(R"\f(CW\*(C`>>=\*(C'\fR\*(L" and \*(R"\f(CW\*(C`x=\*(C'\fR", the | |
545 | left operand is \fB\s-1ALWAYS\s0\fR a bit vector and the right operand is | |
546 | \&\fB\s-1ALWAYS\s0\fR a number (which is the factor indicating how many times | |
547 | the operator is to be applied). | |
548 | .Sp | |
549 | In all truly binary operators, i.e., | |
550 | .Sp | |
551 | .Vb 17 | |
552 | \& . | |
553 | \& | | |
554 | \& & | |
555 | \& ^ | |
556 | \& + | |
557 | \& - | |
558 | \& * | |
559 | \& / | |
560 | \& % | |
561 | \& ** | |
562 | \& <=> cmp | |
563 | \& == eq | |
564 | \& != ne | |
565 | \& < lt | |
566 | \& <= le | |
567 | \& > gt | |
568 | \& >= ge | |
569 | .Ve | |
570 | .Sp | |
571 | one of either operands may be replaced by a Perl scalar, i.e., | |
572 | a number or a string, either as a Perl constant, a Perl expression | |
573 | or a Perl variable yielding a number or a string. | |
574 | .Sp | |
575 | The same applies to the right side operand (the \*(L"rvalue\*(R") of the | |
576 | remaining assignment operators, i.e., | |
577 | .Sp | |
578 | .Vb 10 | |
579 | \& .= | |
580 | \& |= | |
581 | \& &= | |
582 | \& ^= | |
583 | \& += | |
584 | \& -= | |
585 | \& *= | |
586 | \& /= | |
587 | \& %= | |
588 | \& **= | |
589 | .Ve | |
590 | .Sp | |
591 | Note that this Perl scalar should be of the correct type, i.e., | |
592 | numeric or string, for the chosen configuration, because otherwise | |
593 | a warning message will occur if your program runs under the "\f(CW\*(C`\-w\*(C'\fR" | |
594 | switch of Perl. | |
595 | .Sp | |
596 | The acceptable scalar types for each possible configuration are | |
597 | the following: | |
598 | .Sp | |
599 | .Vb 6 | |
600 | \& input = bit indices (default) : numeric | |
601 | \& input = hexadecimal : string | |
602 | \& input = binary : string | |
603 | \& input = decimal : string (in general) | |
604 | \& input = decimal : numeric (if small enough) | |
605 | \& input = enumeration : string | |
606 | .Ve | |
607 | .Sp | |
608 | \&\s-1NOTE\s0 \s-1ALSO\s0 \s-1THAT\s0 \s-1THESE\s0 \s-1SCALAR\s0 \s-1OPERANDS\s0 \s-1ARE\s0 \s-1CONVERTED\s0 \s-1TO\s0 \s-1BIT\s0 \s-1VECTORS\s0 \s-1OF\s0 | |
609 | \&\s-1THE\s0 \s-1SAME\s0 \s-1SIZE\s0 \s-1AS\s0 \s-1THE\s0 \s-1BIT\s0 \s-1VECTOR\s0 \s-1WHICH\s0 \s-1IS\s0 \s-1THE\s0 \s-1OTHER\s0 \s-1OPERAND\s0. | |
610 | .Sp | |
611 | The only exception from this rule is the concatenation operator | |
612 | ("\f(CW\*(C`.\*(C'\fR\*(L") and its assignment variant (\*(R"\f(CW\*(C`.=\*(C'\fR"): | |
613 | .Sp | |
614 | If one of the two operands of the concatenation operator ("\f(CW\*(C`.\*(C'\fR\*(L") is | |
615 | not a bit vector object but a Perl scalar, the contents of the remaining | |
616 | bit vector operand are converted into a string (the format of which | |
617 | depends on the configuration set with the \*(R"\f(CW\*(C`Configuration()\*(C'\fR" method), | |
618 | which is then concatenated in the proper order (i.e., as indicated by the | |
619 | order of the two operands) with the Perl scalar (in other words, a string | |
620 | is returned in such a case instead of a bit vector object!). | |
621 | .Sp | |
622 | If the right side operand (the \*(L"rvalue\*(R") of the assignment variant | |
623 | ("\f(CW\*(C`.=\*(C'\fR") of the concatenation operator is a Perl scalar, it is converted | |
624 | internally to a bit vector of the same size as the left side operand provided | |
625 | that the configuration states that scalars are to be regarded as indices, | |
626 | decimal strings or enumerations. | |
627 | .Sp | |
628 | If the configuration states that scalars are to be regarded as hexadecimal | |
629 | or boolean strings, however, these strings are converted to bit vectors of | |
630 | a size matching the length of the input string, i.e., four times the length | |
631 | for hexadecimal strings (because each hexadecimal digit is worth 4 bits) and | |
632 | once the length for binary strings. | |
633 | .Sp | |
634 | If a decimal number (\*(L"big integer\*(R") is too large to be stored in a | |
635 | bit vector of the given size, a \*(L"numeric overflow error\*(R" occurs. | |
636 | .Sp | |
637 | If a bit index is out of range for the given bit vector, an \*(L"index | |
638 | out of range\*(R" error occurs. | |
639 | .Sp | |
640 | If a scalar operand cannot be converted successfully due to invalid | |
641 | syntax, a fatal \*(L"input string syntax error\*(R" is issued. | |
642 | .Sp | |
643 | If the two operands of the operator "\f(CW\*(C`<<\*(C'\fR\*(L", \*(R"\f(CW\*(C`>>\*(C'\fR\*(L" | |
644 | or \*(R"\f(CW\*(C`x\*(C'\fR\*(L" are reversed, a fatal \*(R"reversed operands error" occurs. | |
645 | .Sp | |
646 | If an operand is neither a bit vector nor a scalar, then a fatal | |
647 | \&\*(L"illegal operand type error\*(R" occurs. | |
648 | .IP "\(bu" 2 | |
649 | Bit order | |
650 | .Sp | |
651 | Note that bit vectors are stored least order bit and least order word first | |
652 | internally. | |
653 | .Sp | |
654 | I.e., bit #0 of any given bit vector corresponds to bit #0 of word #0 in the | |
655 | array of machine words representing the bit vector. | |
656 | .Sp | |
657 | (Where word #0 comes first in memory, i.e., it is stored at the least memory | |
658 | address in the allocated block of memory holding the given bit vector.) | |
659 | .Sp | |
660 | Note however that machine words can be stored least order byte first or last, | |
661 | depending on your system's implementation. | |
662 | .Sp | |
663 | Note further that whenever bit vectors are converted to and from (binary or | |
664 | hexadecimal) strings, the \fB\s-1RIGHTMOST\s0\fR bit is always the \fB\s-1LEAST\s0 \s-1SIGNIFICANT\s0\fR | |
665 | one, and the \fB\s-1LEFTMOST\s0\fR bit is always the \fB\s-1MOST\s0 \s-1SIGNIFICANT\s0\fR bit. | |
666 | .Sp | |
667 | This is because in our western culture, numbers are always represented in this | |
668 | way (least significant to most significant digits go from right to left). | |
669 | .Sp | |
670 | Of course this requires an internal reversion of order, which the corresponding | |
671 | conversion methods perform automatically (without any additional overhead, it's | |
672 | just a matter of starting the internal loop at the bottom or the top end). | |
673 | .IP "\(bu" 2 | |
674 | Matching sizes | |
675 | .Sp | |
676 | In general, for methods involving several bit vectors at the same time, all | |
677 | bit vector arguments must have identical sizes (number of bits), or a fatal | |
678 | \&\*(L"size mismatch\*(R" error will occur. | |
679 | .Sp | |
680 | Exceptions from this rule are the methods "\f(CW\*(C`Concat()\*(C'\fR\*(L", \*(R"\f(CW\*(C`Concat_List()\*(C'\fR\*(L", | |
681 | \&\*(R"\f(CW\*(C`Copy()\*(C'\fR\*(L", \*(R"\f(CW\*(C`Interval_Copy()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`Interval_Substitute()\*(C'\fR", where no | |
682 | conditions at all are imposed on the size of their bit vector arguments. | |
683 | .Sp | |
684 | In method "\f(CW\*(C`Multiply()\*(C'\fR", all three bit vector arguments must in principle | |
685 | obey the rule of matching sizes, but the bit vector in which the result of | |
686 | the multiplication is to be stored may be larger than the two bit vector | |
687 | arguments containing the factors for the multiplication. | |
688 | .Sp | |
689 | In method "\f(CW\*(C`Power()\*(C'\fR", the bit vector for the result must be the same | |
690 | size or greater than the base of the exponentiation term. The exponent | |
691 | can be any size. | |
692 | .Sp | |
693 | The same applies to the corresponding overloaded operators. | |
694 | .IP "\(bu" 2 | |
695 | Index ranges | |
696 | .Sp | |
697 | All indices for any given bits must lie between "\f(CW0\fR\*(L" and | |
698 | \&\*(R"\f(CW\*(C`$vector\->Size()\-1\*(C'\fR\*(L", or a fatal \*(R"index out of range" | |
699 | error will occur. | |
700 | .SH "DESCRIPTION" | |
701 | .IX Header "DESCRIPTION" | |
702 | .IP "\(bu" 2 | |
703 | \&\f(CW\*(C`$config = Bit::Vector\->Configuration();\*(C'\fR | |
704 | .IP "\(bu" 2 | |
705 | \&\f(CW\*(C`Bit::Vector\->Configuration($config);\*(C'\fR | |
706 | .IP "\(bu" 2 | |
707 | \&\f(CW\*(C`$oldconfig = Bit::Vector\->Configuration($newconfig);\*(C'\fR | |
708 | .Sp | |
709 | This method serves to alter the semantics (i.e., behaviour) of certain | |
710 | overloaded operators (which are all implemented in Perl, by the way). | |
711 | .Sp | |
712 | It does not have any effect whatsoever on anything else. In particular, | |
713 | it does not affect the methods implemented in C. | |
714 | .Sp | |
715 | The method accepts an (optional) string as input in which certain keywords | |
716 | are expected, which influence some or almost all of the overloaded operators | |
717 | in several possible ways. | |
718 | .Sp | |
719 | The method always returns a string (which you do not need to take care of, | |
720 | i.e., to store, in case you aren't interested in keeping it) which is a | |
721 | complete representation of the current configuration (i.e., \fB\s-1BEFORE\s0\fR | |
722 | any modifications are applied) and which can be fed back to this method | |
723 | later in order to restore the previous configuration. | |
724 | .Sp | |
725 | There are three aspects of the way certain overloaded operators behave which | |
726 | can be controlled with this method: | |
727 | .Sp | |
728 | .Vb 4 | |
729 | \& + the way scalar operands (replacing one of the two | |
730 | \& bit vector object operands) are automatically | |
731 | \& converted internally into a bit vector object of | |
732 | \& their own, | |
733 | .Ve | |
734 | .Sp | |
735 | .Vb 3 | |
736 | \& + the operation certain overloaded operators perform, | |
737 | \& i.e., an operation with sets or an arithmetic | |
738 | \& operation, | |
739 | .Ve | |
740 | .Sp | |
741 | .Vb 3 | |
742 | \& + the format to which bit vectors are converted | |
743 | \& automatically when they are enclosed in double | |
744 | \& quotes. | |
745 | .Ve | |
746 | .Sp | |
747 | The input string may contain any number of assignments, each of which | |
748 | controls one of these three aspects. | |
749 | .Sp | |
750 | Each assignment has the form "\f(CW\*(C`<which>=<value>\*(C'\fR". | |
751 | .Sp | |
752 | "\f(CW\*(C`<which>\*(C'\fR\*(L" and \*(R"\f(CW\*(C`<value>\*(C'\fR" thereby consist of letters | |
753 | (\f(CW\*(C`[a\-zA\-Z]\*(C'\fR) and white space. | |
754 | .Sp | |
755 | Multiple assignments have to be separated by one or more comma (\*(L",\*(R"), | |
756 | semi-colon (\*(L";\*(R"), colon (\*(L":\*(R"), vertical bar (\*(L"|\*(R"), slash (\*(L"/\*(R"), | |
757 | newline (\*(L"\en\*(R"), ampersand (\*(L"&\*(R"), plus (\*(L"+\*(R") or dash (\*(L"\-\*(R"). | |
758 | .Sp | |
759 | Empty lines or statements (only white space) are allowed but will be | |
760 | ignored. | |
761 | .Sp | |
762 | "\f(CW\*(C`<which>\*(C'\fR\*(L" has to contain one or more keywords from one of | |
763 | three groups, each group representing one of the three aspects that | |
764 | the \*(R"\f(CW\*(C`Configuration()\*(C'\fR" method controls: | |
765 | .Sp | |
766 | .Vb 1 | |
767 | \& + "^scalar", "^input", "^in$" | |
768 | .Ve | |
769 | .Sp | |
770 | .Vb 1 | |
771 | \& + "^operator", "^semantic", "^ops$" | |
772 | .Ve | |
773 | .Sp | |
774 | .Vb 1 | |
775 | \& + "^string", "^output", "^out$" | |
776 | .Ve | |
777 | .Sp | |
778 | The character \*(L"^\*(R" thereby denotes the beginning of a word, and \*(L"$\*(R" | |
779 | denotes the end. Case is ignored (!). | |
780 | .Sp | |
781 | Using these keywords, you can build any phrase you like to select one | |
782 | of the three aspects (see also examples given below). | |
783 | .Sp | |
784 | The only condition is that no other keyword from any of the other two | |
785 | groups may match \- otherwise a syntax error will occur (i.e., ambiguities | |
786 | are forbidden). A syntax error also occurs if none of the keywords | |
787 | matches. | |
788 | .Sp | |
789 | This same principle applies to "\f(CW\*(C`<value>\*(C'\fR": | |
790 | .Sp | |
791 | Depending on which aspect you specified for "\f(CW\*(C`<which>\*(C'\fR", | |
792 | there are different groups of keywords that determine the value | |
793 | the selected aspect will be set to: | |
794 | .Sp | |
795 | .Vb 1 | |
796 | \& + "<which>" = "^scalar", "^input", "^in$": | |
797 | .Ve | |
798 | .Sp | |
799 | .Vb 1 | |
800 | \& "<value>" = | |
801 | .Ve | |
802 | .Sp | |
803 | .Vb 5 | |
804 | \& * "^bit$", "^index", "^indice" | |
805 | \& * "^hex" | |
806 | \& * "^bin" | |
807 | \& * "^dec" | |
808 | \& * "^enum" | |
809 | .Ve | |
810 | .Sp | |
811 | .Vb 1 | |
812 | \& + "<which>" = "^operator", "^semantic", "^ops$": | |
813 | .Ve | |
814 | .Sp | |
815 | .Vb 1 | |
816 | \& "<value>" = | |
817 | .Ve | |
818 | .Sp | |
819 | .Vb 2 | |
820 | \& * "^set$" | |
821 | \& * "^arithmetic" | |
822 | .Ve | |
823 | .Sp | |
824 | .Vb 1 | |
825 | \& + "<which>" = "^string", "^output", "^out$": | |
826 | .Ve | |
827 | .Sp | |
828 | .Vb 1 | |
829 | \& "<value>" = | |
830 | .Ve | |
831 | .Sp | |
832 | .Vb 4 | |
833 | \& * "^hex" | |
834 | \& * "^bin" | |
835 | \& * "^dec" | |
836 | \& * "^enum" | |
837 | .Ve | |
838 | .Sp | |
839 | Examples: | |
840 | .Sp | |
841 | .Vb 1 | |
842 | \& "Any scalar input I provide should be considered to be = a bit index" | |
843 | .Ve | |
844 | .Sp | |
845 | .Vb 1 | |
846 | \& "I want to have operator semantics suitable for = arithmetics" | |
847 | .Ve | |
848 | .Sp | |
849 | .Vb 1 | |
850 | \& "Any bit vector in double quotes is to be output as = an enumeration" | |
851 | .Ve | |
852 | .Sp | |
853 | \&\fB\s-1SCALAR\s0 \s-1INPUT:\s0\fR | |
854 | .Sp | |
855 | In the case of scalar input, "\f(CW\*(C`^bit$\*(C'\fR\*(L", \*(R"\f(CW\*(C`^index\*(C'\fR\*(L", or \*(R"\f(CW\*(C`^indice\*(C'\fR\*(L" | |
856 | all cause scalar input to be considered to represent a bit index, i.e., | |
857 | \&\*(R"\f(CW\*(C`$vector ^= 5;\*(C'\fR\*(L" will flip bit #5 in the given bit vector (this is | |
858 | essentially the same as \*(R"\f(CW\*(C`$vector\->bit_flip(5);\*(C'\fR"). | |
859 | .Sp | |
860 | Note that \*(L"bit indices\*(R" is the default setting for \*(L"scalar input\*(R". | |
861 | .Sp | |
862 | The keyword "\f(CW\*(C`^hex\*(C'\fR\*(L" will cause scalar input to be considered as being in | |
863 | hexadecimal, i.e., \*(R"\f(CW\*(C`$vector ^= 5;\*(C'\fR\*(L" will flip bit #0 and bit #2 (because | |
864 | hexadecimal \*(R"\f(CW5\fR\*(L" is binary \*(R"\f(CW0101\fR"). | |
865 | .Sp | |
866 | (Note though that hexadecimal input should always be enclosed in quotes, | |
867 | otherwise it will be interpreted as a decimal number by Perl! The example | |
868 | relies on the fact that hexadecimal \f(CW\*(C`0\-9\*(C'\fR and decimal \f(CW\*(C`0\-9\*(C'\fR are the same.) | |
869 | .Sp | |
870 | The keyword "\f(CW\*(C`^bin\*(C'\fR\*(L" will cause scalar input to be considered as being in | |
871 | binary format. All characters except \*(R"\f(CW0\fR\*(L" and \*(R"\f(CW1\fR" are forbidden in | |
872 | this case (i.e., produce a syntax error). | |
873 | .Sp | |
874 | "\f(CW\*(C`$vector ^= '0101';\*(C'\fR", for instance, will flip bit #0 and bit #2. | |
875 | .Sp | |
876 | The keyword "\f(CW\*(C`^dec\*(C'\fR\*(L" causes scalar input to be considered as integers | |
877 | in decimal format, i.e., \*(R"\f(CW\*(C`$vector ^= 5;\*(C'\fR\*(L" will flip bit #0 and bit #2 | |
878 | (because decimal \*(R"\f(CW5\fR\*(L" is binary \*(R"\f(CW0101\fR"). | |
879 | .Sp | |
880 | (Note though that all decimal input should be enclosed in quotes, because | |
881 | for large numbers, Perl will use scientific notation internally for | |
882 | representing them, which produces a syntax error because scientific | |
883 | notation is neither supported by this module nor needed.) | |
884 | .Sp | |
885 | Finally, the keyword "\f(CW\*(C`^enum\*(C'\fR\*(L" causes scalar input to be considered | |
886 | as being a list (\*(R"enumeration\*(L") of indices and ranges of (contiguous) | |
887 | indices, i.e., \*(R"\f(CW\*(C`$vector |= '2,3,5,7\-13,17\-23';\*(C'\fR" will cause bits #2, | |
888 | #3, #5, #7 through #13 and #17 through #23 to be set. | |
889 | .Sp | |
890 | \&\fB\s-1OPERATOR\s0 \s-1SEMANTICS:\s0\fR | |
891 | .Sp | |
892 | Several overloaded operators can have two distinct functions depending | |
893 | on this setting. | |
894 | .Sp | |
895 | The affected operators are: "\f(CW\*(C`+\*(C'\fR\*(L", \*(R"\f(CW\*(C`\-\*(C'\fR\*(L", \*(R"\f(CW\*(C`*\*(C'\fR\*(L", \*(R"\f(CW\*(C`<\*(C'\fR\*(L", \*(R"\f(CW\*(C`<=\*(C'\fR\*(L", | |
896 | \&\*(R"\f(CW\*(C`>\*(C'\fR\*(L" and \*(R"\f(CW\*(C`>=\*(C'\fR". | |
897 | .Sp | |
898 | With the default setting, \*(L"set operations\*(R", these operators perform: | |
899 | .Sp | |
900 | .Vb 7 | |
901 | \& + set union ( set1 u set2 ) | |
902 | \& - set difference ( set1 \e set2 ) | |
903 | \& * set intersection ( set1 n set2 ) | |
904 | \& < true subset relationship ( set1 < set2 ) | |
905 | \& <= subset relationship ( set1 <= set2 ) | |
906 | \& > true superset relationship ( set1 > set2 ) | |
907 | \& >= superset relationship ( set1 >= set2 ) | |
908 | .Ve | |
909 | .Sp | |
910 | With the alternative setting, \*(L"arithmetic operations\*(R", these operators | |
911 | perform: | |
912 | .Sp | |
913 | .Vb 7 | |
914 | \& + addition ( num1 + num2 ) | |
915 | \& - subtraction ( num1 - num2 ) | |
916 | \& * multiplication ( num1 * num2 ) | |
917 | \& < "less than" comparison ( num1 < num2 ) | |
918 | \& <= "less than or equal" comparison ( num1 <= num2 ) | |
919 | \& > "greater than" comparison ( num1 > num2 ) | |
920 | \& >= "greater than or equal" comparison ( num1 >= num2 ) | |
921 | .Ve | |
922 | .Sp | |
923 | Note that these latter comparison operators ("\f(CW\*(C`<\*(C'\fR\*(L", \*(R"\f(CW\*(C`<=\*(C'\fR\*(L", | |
924 | \&\*(R"\f(CW\*(C`>\*(C'\fR\*(L" and \*(R"\f(CW\*(C`>=\*(C'\fR") regard their operands as being \fB\s-1SIGNED\s0\fR. | |
925 | .Sp | |
926 | To perform comparisons with \fB\s-1UNSIGNED\s0\fR operands, use the operators | |
927 | "\f(CW\*(C`lt\*(C'\fR\*(L", \*(R"\f(CW\*(C`le\*(C'\fR\*(L", \*(R"\f(CW\*(C`gt\*(C'\fR\*(L" and \*(R"\f(CW\*(C`ge\*(C'\fR" instead (in contrast to the | |
928 | operators above, these operators are \fB\s-1NOT\s0\fR affected by the | |
929 | \&\*(L"operator semantics\*(R" setting). | |
930 | .Sp | |
931 | \&\fB\s-1STRING\s0 \s-1OUTPUT:\s0\fR | |
932 | .Sp | |
933 | There are four methods which convert the contents of a given bit vector | |
934 | into a string: "\f(CW\*(C`to_Hex()\*(C'\fR\*(L", \*(R"\f(CW\*(C`to_Bin()\*(C'\fR\*(L", \*(R"\f(CW\*(C`to_Dec()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`to_Enum()\*(C'\fR\*(L" | |
935 | (not counting \*(R"\f(CW\*(C`Block_Read()\*(C'\fR", since this method does not return a | |
936 | human-readable string). | |
937 | .Sp | |
938 | (For conversion to octal, see the description of the method | |
939 | "\f(CW\*(C`Chunk_List_Read()\*(C'\fR".) | |
940 | .Sp | |
941 | Therefore, there are four possible formats into which a bit vector can | |
942 | be converted when it is enclosed in double quotes, for example: | |
943 | .Sp | |
944 | .Vb 2 | |
945 | \& print "\e$vector = '$vector'\en"; | |
946 | \& $string = "$vector"; | |
947 | .Ve | |
948 | .Sp | |
949 | Hence you can set \*(L"string output\*(R" to four different values: To \*(L"hex\*(R" | |
950 | for hexadecimal format (which is the default), to \*(L"bin\*(R" for binary | |
951 | format, to \*(L"dec\*(R" for conversion to decimal numbers and to \*(L"enum\*(R" | |
952 | for conversion to enumerations (\*(L".newsrc\*(R" style sets). | |
953 | .Sp | |
954 | \&\fB\s-1BEWARE\s0\fR that the conversion to decimal numbers is inherently slow; | |
955 | it can easily take up several seconds for a single large bit vector! | |
956 | .Sp | |
957 | Therefore you should store the decimal strings returned to you | |
958 | rather than converting a given bit vector again. | |
959 | .Sp | |
960 | \&\fB\s-1EXAMPLES:\s0\fR | |
961 | .Sp | |
962 | The default setting as returned by the method "\f(CW\*(C`Configuration()\*(C'\fR" | |
963 | is: | |
964 | .Sp | |
965 | .Vb 3 | |
966 | \& Scalar Input = Bit Index | |
967 | \& Operator Semantics = Set Operators | |
968 | \& String Output = Hexadecimal | |
969 | .Ve | |
970 | .Sp | |
971 | Performing a statement such as: | |
972 | .Sp | |
973 | .Vb 2 | |
974 | \& Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin"); | |
975 | \& print Bit::Vector->Configuration(), "\en"; | |
976 | .Ve | |
977 | .Sp | |
978 | yields the following output: | |
979 | .Sp | |
980 | .Vb 3 | |
981 | \& Scalar Input = Binary | |
982 | \& Operator Semantics = Arithmetic Operators | |
983 | \& String Output = Binary | |
984 | .Ve | |
985 | .Sp | |
986 | Note that you can always feed this output back into the "\f(CW\*(C`Configuration()\*(C'\fR" | |
987 | method to restore that setting later. | |
988 | .Sp | |
989 | This also means that you can enter the same given setting with almost any | |
990 | degree of verbosity you like (as long as the required keywords appear and | |
991 | no ambiguities arise). | |
992 | .Sp | |
993 | Note further that any aspect you do not specify is not changed, i.e., | |
994 | the statement | |
995 | .Sp | |
996 | .Vb 1 | |
997 | \& Bit::Vector->Configuration("operators = arithmetic"); | |
998 | .Ve | |
999 | .Sp | |
1000 | leaves all other aspects unchanged. | |
1001 | .IP "\(bu" 2 | |
1002 | \&\f(CW"$vector"\fR | |
1003 | .Sp | |
1004 | Remember that variables enclosed in double quotes are always | |
1005 | interpolated in Perl. | |
1006 | .Sp | |
1007 | Whenever a Perl variable containing the reference of a \*(L"Bit::Vector\*(R" | |
1008 | object is enclosed in double quotes (either alone or together with | |
1009 | other text and/or variables), the contents of the corresponding | |
1010 | bit vector are converted into a printable string. | |
1011 | .Sp | |
1012 | Since there are several conversion methods available in this module | |
1013 | (see the description of the methods "\f(CW\*(C`to_Hex()\*(C'\fR\*(L", \*(R"\f(CW\*(C`to_Bin()\*(C'\fR\*(L", | |
1014 | \&\*(R"\f(CW\*(C`to_Dec()\*(C'\fR\*(L" and \*(R"\f(CW\*(C`to_Enum()\*(C'\fR"), it is of course desirable to | |
1015 | be able to choose which of these methods should be applied in this | |
1016 | case. | |
1017 | .Sp | |
1018 | This can actually be done by changing the configuration of this | |
1019 | module using the method "\f(CW\*(C`Configure()\*(C'\fR" (see the previous chapter, | |
1020 | immediately above). | |
1021 | .Sp | |
1022 | The default is conversion to hexadecimal. | |
1023 | .IP "\(bu" 2 | |
1024 | \&\f(CW\*(C`if ($vector)\*(C'\fR | |
1025 | .Sp | |
1026 | It is possible to use a Perl variable containing the reference of a | |
1027 | \&\*(L"Bit::Vector\*(R" object as a boolean expression. | |
1028 | .Sp | |
1029 | The condition above is true if the corresponding bit vector contains | |
1030 | at least one set bit, and it is false if \fB\s-1ALL\s0\fR bits of the corresponding | |
1031 | bit vector are cleared. | |
1032 | .IP "\(bu" 2 | |
1033 | \&\f(CW\*(C`if (!$vector)\*(C'\fR | |
1034 | .Sp | |
1035 | Since it is possible to use a Perl variable containing the reference of a | |
1036 | \&\*(L"Bit::Vector\*(R" object as a boolean expression, you can of course also negate | |
1037 | this boolean expression. | |
1038 | .Sp | |
1039 | The condition above is true if \fB\s-1ALL\s0\fR bits of the corresponding bit vector | |
1040 | are cleared, and it is false if the corresponding bit vector contains at | |
1041 | least one set bit. | |
1042 | .Sp | |
1043 | Note that this is \fB\s-1NOT\s0\fR the same as using the method "\f(CW\*(C`is_full()\*(C'\fR", | |
1044 | which returns true if \fB\s-1ALL\s0\fR bits of the corresponding bit vector are | |
1045 | \&\fB\s-1SET\s0\fR. | |
1046 | .IP "\(bu" 2 | |
1047 | \&\f(CW\*(C`~$vector\*(C'\fR | |
1048 | .Sp | |
1049 | This term returns a new bit vector object which is the one's complement | |
1050 | of the given bit vector. | |
1051 | .Sp | |
1052 | This is equivalent to inverting all bits. | |
1053 | .IP "\(bu" 2 | |
1054 | \&\f(CW\*(C`\-$vector\*(C'\fR (unary minus) | |
1055 | .Sp | |
1056 | This term returns a new bit vector object which is the two's complement | |
1057 | of the given bit vector. | |
1058 | .Sp | |
1059 | This is equivalent to inverting all bits and incrementing the result by one. | |
1060 | .Sp | |
1061 | (This is the same as changing the sign of a number in two's complement | |
1062 | binary representation.) | |
1063 | .IP "\(bu" 2 | |
1064 | \&\f(CW\*(C`abs($vector)\*(C'\fR | |
1065 | .Sp | |
1066 | Depending on the configuration (see the description of the method | |
1067 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this term either returns | |
1068 | the number of set bits in the given bit vector (this is the same | |
1069 | as calculating the number of elements which are contained in the | |
1070 | given set) \- which is the default behaviour, or it returns a new | |
1071 | bit vector object which contains the absolute value of the number | |
1072 | stored in the given bit vector. | |
1073 | .IP "\(bu" 2 | |
1074 | \&\f(CW\*(C`$vector1 . $vector2\*(C'\fR | |
1075 | .Sp | |
1076 | This term usually returns a new bit vector object which is the | |
1077 | result of the concatenation of the two bit vector operands. | |
1078 | .Sp | |
1079 | The left operand becomes the most significant, and the right operand | |
1080 | becomes the least significant part of the new bit vector object. | |
1081 | .Sp | |
1082 | If one of the two operands is not a bit vector object but a Perl scalar, | |
1083 | however, the contents of the remaining bit vector operand are converted | |
1084 | into a string (the format of which depends on the configuration set with | |
1085 | the "\f(CW\*(C`Configuration()\*(C'\fR" method), which is then concatenated in the proper | |
1086 | order (i.e., as indicated by the order of the two operands) with the Perl | |
1087 | scalar. | |
1088 | .Sp | |
1089 | In other words, a string is returned in such a case instead of a | |
1090 | bit vector object! | |
1091 | .IP "\(bu" 2 | |
1092 | \&\f(CW\*(C`$vector x $factor\*(C'\fR | |
1093 | .Sp | |
1094 | This term returns a new bit vector object which is the concatenation | |
1095 | of as many copies of the given bit vector operand (the left operand) | |
1096 | as the factor (the right operand) specifies. | |
1097 | .Sp | |
1098 | If the factor is zero, a bit vector object with a length of zero bits | |
1099 | is returned. | |
1100 | .Sp | |
1101 | If the factor is one, just a new copy of the given bit vector is | |
1102 | returned. | |
1103 | .Sp | |
1104 | Note that a fatal \*(L"reversed operands error\*(R" occurs if the two operands | |
1105 | are swapped. | |
1106 | .IP "\(bu" 2 | |
1107 | \&\f(CW\*(C`$vector << $bits\*(C'\fR | |
1108 | .Sp | |
1109 | This term returns a new bit vector object which is a copy of the given | |
1110 | bit vector (the left operand), which is then shifted left (towards the | |
1111 | most significant bit) by as many places as the right operand, "\f(CW$bits\fR", | |
1112 | specifies. | |
1113 | .Sp | |
1114 | This means that the "\f(CW$bits\fR\*(L" most significant bits are lost, all other | |
1115 | bits move up by \*(R"\f(CW$bits\fR\*(L" positions, and the \*(R"\f(CW$bits\fR" least significant | |
1116 | bits that have been left unoccupied by this shift are all set to zero. | |
1117 | .Sp | |
1118 | If "\f(CW$bits\fR" is greater than the number of bits of the given bit vector, | |
1119 | this term returns an empty bit vector (i.e., with all bits cleared) of | |
1120 | the same size as the given bit vector. | |
1121 | .Sp | |
1122 | Note that a fatal \*(L"reversed operands error\*(R" occurs if the two operands | |
1123 | are swapped. | |
1124 | .IP "\(bu" 2 | |
1125 | \&\f(CW\*(C`$vector >> $bits\*(C'\fR | |
1126 | .Sp | |
1127 | This term returns a new bit vector object which is a copy of the given | |
1128 | bit vector (the left operand), which is then shifted right (towards the | |
1129 | least significant bit) by as many places as the right operand, "\f(CW$bits\fR", | |
1130 | specifies. | |
1131 | .Sp | |
1132 | This means that the "\f(CW$bits\fR\*(L" least significant bits are lost, all other | |
1133 | bits move down by \*(R"\f(CW$bits\fR\*(L" positions, and the \*(R"\f(CW$bits\fR" most significant | |
1134 | bits that have been left unoccupied by this shift are all set to zero. | |
1135 | .Sp | |
1136 | If "\f(CW$bits\fR" is greater than the number of bits of the given bit vector, | |
1137 | this term returns an empty bit vector (i.e., with all bits cleared) of | |
1138 | the same size as the given bit vector. | |
1139 | .Sp | |
1140 | Note that a fatal \*(L"reversed operands error\*(R" occurs if the two operands | |
1141 | are swapped. | |
1142 | .IP "\(bu" 2 | |
1143 | \&\f(CW\*(C`$vector1 | $vector2\*(C'\fR | |
1144 | .Sp | |
1145 | This term returns a new bit vector object which is the result of | |
1146 | a bitwise \s-1OR\s0 operation between the two bit vector operands. | |
1147 | .Sp | |
1148 | This is the same as calculating the union of two sets. | |
1149 | .IP "\(bu" 2 | |
1150 | \&\f(CW\*(C`$vector1 & $vector2\*(C'\fR | |
1151 | .Sp | |
1152 | This term returns a new bit vector object which is the result of | |
1153 | a bitwise \s-1AND\s0 operation between the two bit vector operands. | |
1154 | .Sp | |
1155 | This is the same as calculating the intersection of two sets. | |
1156 | .IP "\(bu" 2 | |
1157 | \&\f(CW\*(C`$vector1 ^ $vector2\*(C'\fR | |
1158 | .Sp | |
1159 | This term returns a new bit vector object which is the result of | |
1160 | a bitwise \s-1XOR\s0 (exclusive\-or) operation between the two bit vector | |
1161 | operands. | |
1162 | .Sp | |
1163 | This is the same as calculating the symmetric difference of two sets. | |
1164 | .IP "\(bu" 2 | |
1165 | \&\f(CW\*(C`$vector1 + $vector2\*(C'\fR | |
1166 | .Sp | |
1167 | Depending on the configuration (see the description of the method | |
1168 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this term either returns | |
1169 | a new bit vector object which is the result of a bitwise \s-1OR\s0 operation | |
1170 | between the two bit vector operands (this is the same as calculating | |
1171 | the union of two sets) \- which is the default behaviour, or it returns | |
1172 | a new bit vector object which contains the sum of the two numbers | |
1173 | stored in the two bit vector operands. | |
1174 | .IP "\(bu" 2 | |
1175 | \&\f(CW\*(C`$vector1 \- $vector2\*(C'\fR | |
1176 | .Sp | |
1177 | Depending on the configuration (see the description of the method | |
1178 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this term either returns | |
1179 | a new bit vector object which is the set difference of the two sets | |
1180 | represented in the two bit vector operands \- which is the default | |
1181 | behaviour, or it returns a new bit vector object which contains | |
1182 | the difference of the two numbers stored in the two bit vector | |
1183 | operands. | |
1184 | .IP "\(bu" 2 | |
1185 | \&\f(CW\*(C`$vector1 * $vector2\*(C'\fR | |
1186 | .Sp | |
1187 | Depending on the configuration (see the description of the method | |
1188 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this term either returns | |
1189 | a new bit vector object which is the result of a bitwise \s-1AND\s0 operation | |
1190 | between the two bit vector operands (this is the same as calculating | |
1191 | the intersection of two sets) \- which is the default behaviour, or it | |
1192 | returns a new bit vector object which contains the product of the two | |
1193 | numbers stored in the two bit vector operands. | |
1194 | .IP "\(bu" 2 | |
1195 | \&\f(CW\*(C`$vector1 / $vector2\*(C'\fR | |
1196 | .Sp | |
1197 | This term returns a new bit vector object containing the result of the | |
1198 | division of the two numbers stored in the two bit vector operands. | |
1199 | .IP "\(bu" 2 | |
1200 | \&\f(CW\*(C`$vector1 % $vector2\*(C'\fR | |
1201 | .Sp | |
1202 | This term returns a new bit vector object containing the remainder of | |
1203 | the division of the two numbers stored in the two bit vector operands. | |
1204 | .IP "\(bu" 2 | |
1205 | \&\f(CW\*(C`$vector1 ** $vector2\*(C'\fR | |
1206 | .Sp | |
1207 | This term returns a new bit vector object containing the result of the | |
1208 | exponentiation of the left bit vector elevated to the right bit vector's | |
1209 | power. | |
1210 | .IP "\(bu" 2 | |
1211 | \&\f(CW\*(C`$vector1 .= $vector2;\*(C'\fR | |
1212 | .Sp | |
1213 | This statement \*(L"appends\*(R" the right bit vector operand (the \*(L"rvalue\*(R") | |
1214 | to the left one (the \*(L"lvalue\*(R"). | |
1215 | .Sp | |
1216 | The former contents of the left operand become the most significant | |
1217 | part of the resulting bit vector, and the right operand becomes the | |
1218 | least significant part. | |
1219 | .Sp | |
1220 | Since bit vectors are stored in \*(L"least order bit first\*(R" order, this | |
1221 | actually requires the left operand to be shifted \*(L"up\*(R" by the length | |
1222 | of the right operand, which is then copied to the now freed least | |
1223 | significant part of the left operand. | |
1224 | .Sp | |
1225 | If the right operand is a Perl scalar, it is first converted to a | |
1226 | bit vector of the same size as the left operand, provided that the | |
1227 | configuration states that scalars are to be regarded as indices, | |
1228 | decimal strings or enumerations. | |
1229 | .Sp | |
1230 | If the configuration states that scalars are to be regarded as hexadecimal | |
1231 | or boolean strings, however, these strings are converted to bit vectors of | |
1232 | a size matching the length of the input string, i.e., four times the length | |
1233 | for hexadecimal strings (because each hexadecimal digit is worth 4 bits) and | |
1234 | once the length for binary strings. | |
1235 | .IP "\(bu" 2 | |
1236 | \&\f(CW\*(C`$vector x= $factor;\*(C'\fR | |
1237 | .Sp | |
1238 | This statement replaces the given bit vector by a concatenation of as many | |
1239 | copies of the original contents of the given bit vector as the factor (the | |
1240 | right operand) specifies. | |
1241 | .Sp | |
1242 | If the factor is zero, the given bit vector is resized to a length of zero | |
1243 | bits. | |
1244 | .Sp | |
1245 | If the factor is one, the given bit vector is not changed at all. | |
1246 | .IP "\(bu" 2 | |
1247 | \&\f(CW\*(C`$vector <<= $bits;\*(C'\fR | |
1248 | .Sp | |
1249 | This statement moves the contents of the given bit vector left by "\f(CW$bits\fR" | |
1250 | positions (towards the most significant bit). | |
1251 | .Sp | |
1252 | This means that the "\f(CW$bits\fR\*(L" most significant bits are lost, all other | |
1253 | bits move up by \*(R"\f(CW$bits\fR\*(L" positions, and the \*(R"\f(CW$bits\fR" least significant | |
1254 | bits that have been left unoccupied by this shift are all set to zero. | |
1255 | .Sp | |
1256 | If "\f(CW$bits\fR" is greater than the number of bits of the given bit vector, | |
1257 | the given bit vector is erased completely (i.e., all bits are cleared). | |
1258 | .IP "\(bu" 2 | |
1259 | \&\f(CW\*(C`$vector >>= $bits;\*(C'\fR | |
1260 | .Sp | |
1261 | This statement moves the contents of the given bit vector right by "\f(CW$bits\fR" | |
1262 | positions (towards the least significant bit). | |
1263 | .Sp | |
1264 | This means that the "\f(CW$bits\fR\*(L" least significant bits are lost, all other | |
1265 | bits move down by \*(R"\f(CW$bits\fR\*(L" positions, and the \*(R"\f(CW$bits\fR" most significant | |
1266 | bits that have been left unoccupied by this shift are all set to zero. | |
1267 | .Sp | |
1268 | If "\f(CW$bits\fR" is greater than the number of bits of the given bit vector, | |
1269 | the given bit vector is erased completely (i.e., all bits are cleared). | |
1270 | .IP "\(bu" 2 | |
1271 | \&\f(CW\*(C`$vector1 |= $vector2;\*(C'\fR | |
1272 | .Sp | |
1273 | This statement performs a bitwise \s-1OR\s0 operation between the two | |
1274 | bit vector operands and stores the result in the left operand. | |
1275 | .Sp | |
1276 | This is the same as calculating the union of two sets. | |
1277 | .IP "\(bu" 2 | |
1278 | \&\f(CW\*(C`$vector1 &= $vector2;\*(C'\fR | |
1279 | .Sp | |
1280 | This statement performs a bitwise \s-1AND\s0 operation between the two | |
1281 | bit vector operands and stores the result in the left operand. | |
1282 | .Sp | |
1283 | This is the same as calculating the intersection of two sets. | |
1284 | .IP "\(bu" 2 | |
1285 | \&\f(CW\*(C`$vector1 ^= $vector2;\*(C'\fR | |
1286 | .Sp | |
1287 | This statement performs a bitwise \s-1XOR\s0 (exclusive\-or) operation | |
1288 | between the two bit vector operands and stores the result in the | |
1289 | left operand. | |
1290 | .Sp | |
1291 | This is the same as calculating the symmetric difference of two sets. | |
1292 | .IP "\(bu" 2 | |
1293 | \&\f(CW\*(C`$vector1 += $vector2;\*(C'\fR | |
1294 | .Sp | |
1295 | Depending on the configuration (see the description of the method | |
1296 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this statement either performs | |
1297 | a bitwise \s-1OR\s0 operation between the two bit vector operands (this is | |
1298 | the same as calculating the union of two sets) \- which is the default | |
1299 | behaviour, or it calculates the sum of the two numbers stored in the | |
1300 | two bit vector operands. | |
1301 | .Sp | |
1302 | The result of this operation is stored in the left operand. | |
1303 | .IP "\(bu" 2 | |
1304 | \&\f(CW\*(C`$vector1 \-= $vector2;\*(C'\fR | |
1305 | .Sp | |
1306 | Depending on the configuration (see the description of the method | |
1307 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this statement either calculates | |
1308 | the set difference of the two sets represented in the two bit vector | |
1309 | operands \- which is the default behaviour, or it calculates the | |
1310 | difference of the two numbers stored in the two bit vector operands. | |
1311 | .Sp | |
1312 | The result of this operation is stored in the left operand. | |
1313 | .IP "\(bu" 2 | |
1314 | \&\f(CW\*(C`$vector1 *= $vector2;\*(C'\fR | |
1315 | .Sp | |
1316 | Depending on the configuration (see the description of the method | |
1317 | "\f(CW\*(C`Configuration()\*(C'\fR" for more details), this statement either performs | |
1318 | a bitwise \s-1AND\s0 operation between the two bit vector operands (this is | |
1319 | the same as calculating the intersection of two sets) \- which is the | |
1320 | default behaviour, or it calculates the product of the two numbers | |
1321 | stored in the two bit vector operands. | |
1322 | .Sp | |
1323 | The result of this operation is stored in the left operand. | |
1324 | .IP "\(bu" 2 | |
1325 | \&\f(CW\*(C`$vector1 /= $vector2;\*(C'\fR | |
1326 | .Sp | |
1327 | This statement puts the result of the division of the two numbers | |
1328 | stored in the two bit vector operands into the left operand. | |
1329 | .IP "\(bu" 2 | |
1330 | \&\f(CW\*(C`$vector1 %= $vector2;\*(C'\fR | |
1331 | .Sp | |
1332 | This statement puts the remainder of the division of the two numbers | |
1333 | stored in the two bit vector operands into the left operand. | |
1334 | .IP "\(bu" 2 | |
1335 | \&\f(CW\*(C`$vector1 **= $vector2;\*(C'\fR | |
1336 | .Sp | |
1337 | This statement puts the result of the exponentiation of the left | |
1338 | operand elevated to the right operand's power into the left operand. | |
1339 | .IP "\(bu" 2 | |
1340 | \&\f(CW\*(C`++$vector\*(C'\fR, \f(CW\*(C`$vector++\*(C'\fR | |
1341 | .Sp | |
1342 | This operator performs pre\- and post-incrementation of the | |
1343 | given bit vector. | |
1344 | .Sp | |
1345 | The value returned by this term is a reference of the given | |
1346 | bit vector object (after or before the incrementation, | |
1347 | respectively). | |
1348 | .IP "\(bu" 2 | |
1349 | \&\f(CW\*(C`\-\-$vector\*(C'\fR, \f(CW\*(C`$vector\-\-\*(C'\fR | |
1350 | .Sp | |
1351 | This operator performs pre\- and post-decrementation of the | |
1352 | given bit vector. | |
1353 | .Sp | |
1354 | The value returned by this term is a reference of the given | |
1355 | bit vector object (after or before the decrementation, | |
1356 | respectively). | |
1357 | .IP "\(bu" 2 | |
1358 | \&\f(CW\*(C`($vector1 cmp $vector2)\*(C'\fR | |
1359 | .Sp | |
1360 | This term returns "\f(CW\*(C`\-1\*(C'\fR\*(L" if \*(R"\f(CW$vector1\fR\*(L" is less than \*(R"\f(CW$vector2\fR\*(L", | |
1361 | \&\*(R"\f(CW0\fR\*(L" if \*(R"\f(CW$vector1\fR\*(L" and \*(R"\f(CW$vector2\fR\*(L" are the same, and \*(R"\f(CW1\fR\*(L" | |
1362 | if \*(R"\f(CW$vector1\fR\*(L" is greater than \*(R"\f(CW$vector2\fR". | |
1363 | .Sp | |
1364 | This comparison assumes \fB\s-1UNSIGNED\s0\fR bit vectors. | |
1365 | .IP "\(bu" 2 | |
1366 | \&\f(CW\*(C`($vector1 eq $vector2)\*(C'\fR | |
1367 | .Sp | |
1368 | This term returns true ("\f(CW1\fR\*(L") if the contents of the two bit vector | |
1369 | operands are the same and false (\*(R"\f(CW0\fR") otherwise. | |
1370 | .IP "\(bu" 2 | |
1371 | \&\f(CW\*(C`($vector1 ne $vector2)\*(C'\fR | |
1372 | .Sp | |
1373 | This term returns true ("\f(CW1\fR\*(L") if the two bit vector operands differ | |
1374 | and false (\*(R"\f(CW0\fR") otherwise. | |
1375 | .IP "\(bu" 2 | |
1376 | \&\f(CW\*(C`($vector1 lt $vector2)\*(C'\fR | |
1377 | .Sp | |
1378 | This term returns true ("\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is less than \*(R"\f(CW$vector2\fR\*(L", | |
1379 | and false (\*(R"\f(CW0\fR") otherwise. | |
1380 | .Sp | |
1381 | This comparison assumes \fB\s-1UNSIGNED\s0\fR bit vectors. | |
1382 | .IP "\(bu" 2 | |
1383 | \&\f(CW\*(C`($vector1 le $vector2)\*(C'\fR | |
1384 | .Sp | |
1385 | This term returns true ("\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is less than or equal to | |
1386 | \&\*(R"\f(CW$vector2\fR\*(L", and false (\*(R"\f(CW0\fR") otherwise. | |
1387 | .Sp | |
1388 | This comparison assumes \fB\s-1UNSIGNED\s0\fR bit vectors. | |
1389 | .IP "\(bu" 2 | |
1390 | \&\f(CW\*(C`($vector1 gt $vector2)\*(C'\fR | |
1391 | .Sp | |
1392 | This term returns true ("\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is greater than \*(R"\f(CW$vector2\fR\*(L", | |
1393 | and false (\*(R"\f(CW0\fR") otherwise. | |
1394 | .Sp | |
1395 | This comparison assumes \fB\s-1UNSIGNED\s0\fR bit vectors. | |
1396 | .IP "\(bu" 2 | |
1397 | \&\f(CW\*(C`($vector1 ge $vector2)\*(C'\fR | |
1398 | .Sp | |
1399 | This term returns true ("\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is greater than or equal to | |
1400 | \&\*(R"\f(CW$vector2\fR\*(L", and false (\*(R"\f(CW0\fR") otherwise. | |
1401 | .Sp | |
1402 | This comparison assumes \fB\s-1UNSIGNED\s0\fR bit vectors. | |
1403 | .IP "\(bu" 2 | |
1404 | \&\f(CW\*(C`($vector1 <=> $vector2)\*(C'\fR | |
1405 | .Sp | |
1406 | This term returns "\f(CW\*(C`\-1\*(C'\fR\*(L" if \*(R"\f(CW$vector1\fR\*(L" is less than \*(R"\f(CW$vector2\fR\*(L", | |
1407 | \&\*(R"\f(CW0\fR\*(L" if \*(R"\f(CW$vector1\fR\*(L" and \*(R"\f(CW$vector2\fR\*(L" are the same, and \*(R"\f(CW1\fR\*(L" | |
1408 | if \*(R"\f(CW$vector1\fR\*(L" is greater than \*(R"\f(CW$vector2\fR". | |
1409 | .Sp | |
1410 | This comparison assumes \fB\s-1SIGNED\s0\fR bit vectors. | |
1411 | .IP "\(bu" 2 | |
1412 | \&\f(CW\*(C`($vector1 == $vector2)\*(C'\fR | |
1413 | .Sp | |
1414 | This term returns true ("\f(CW1\fR\*(L") if the contents of the two bit vector | |
1415 | operands are the same and false (\*(R"\f(CW0\fR") otherwise. | |
1416 | .IP "\(bu" 2 | |
1417 | \&\f(CW\*(C`($vector1 != $vector2)\*(C'\fR | |
1418 | .Sp | |
1419 | This term returns true ("\f(CW1\fR\*(L") if the two bit vector operands differ | |
1420 | and false (\*(R"\f(CW0\fR") otherwise. | |
1421 | .IP "\(bu" 2 | |
1422 | \&\f(CW\*(C`($vector1 < $vector2)\*(C'\fR | |
1423 | .Sp | |
1424 | Depending on the configuration (see the description of the method | |
1425 | "\f(CW\*(C`Configuration()\*(C'\fR\*(L" for more details), this term either returns | |
1426 | true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is a true subset of \*(R"\f(CW$vector2\fR\*(L" | |
1427 | (and false (\*(R"\f(CW0\fR\*(L") otherwise) \- which is the default behaviour, | |
1428 | or it returns true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is less than | |
1429 | \&\*(R"\f(CW$vector2\fR\*(L" (and false (\*(R"\f(CW0\fR") otherwise). | |
1430 | .Sp | |
1431 | The latter comparison assumes \fB\s-1SIGNED\s0\fR bit vectors. | |
1432 | .IP "\(bu" 2 | |
1433 | \&\f(CW\*(C`($vector1 <= $vector2)\*(C'\fR | |
1434 | .Sp | |
1435 | Depending on the configuration (see the description of the method | |
1436 | "\f(CW\*(C`Configuration()\*(C'\fR\*(L" for more details), this term either returns | |
1437 | true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is a subset of \*(R"\f(CW$vector2\fR\*(L" (and | |
1438 | false (\*(R"\f(CW0\fR\*(L") otherwise) \- which is the default behaviour, or it | |
1439 | returns true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is less than or equal to | |
1440 | \&\*(R"\f(CW$vector2\fR\*(L" (and false (\*(R"\f(CW0\fR") otherwise). | |
1441 | .Sp | |
1442 | The latter comparison assumes \fB\s-1SIGNED\s0\fR bit vectors. | |
1443 | .IP "\(bu" 2 | |
1444 | \&\f(CW\*(C`($vector1 > $vector2)\*(C'\fR | |
1445 | .Sp | |
1446 | Depending on the configuration (see the description of the method | |
1447 | "\f(CW\*(C`Configuration()\*(C'\fR\*(L" for more details), this term either returns | |
1448 | true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is a true superset of \*(R"\f(CW$vector2\fR\*(L" | |
1449 | (and false (\*(R"\f(CW0\fR\*(L") otherwise) \- which is the default behaviour, | |
1450 | or it returns true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is greater than | |
1451 | \&\*(R"\f(CW$vector2\fR\*(L" (and false (\*(R"\f(CW0\fR") otherwise). | |
1452 | .Sp | |
1453 | The latter comparison assumes \fB\s-1SIGNED\s0\fR bit vectors. | |
1454 | .IP "\(bu" 2 | |
1455 | \&\f(CW\*(C`($vector1 >= $vector2)\*(C'\fR | |
1456 | .Sp | |
1457 | Depending on the configuration (see the description of the method | |
1458 | "\f(CW\*(C`Configuration()\*(C'\fR\*(L" for more details), this term either returns | |
1459 | true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is a superset of \*(R"\f(CW$vector2\fR\*(L" (and | |
1460 | false (\*(R"\f(CW0\fR\*(L") otherwise) \- which is the default behaviour, or it | |
1461 | returns true (\*(R"\f(CW1\fR\*(L") if \*(R"\f(CW$vector1\fR\*(L" is greater than or equal to | |
1462 | \&\*(R"\f(CW$vector2\fR\*(L" (and false (\*(R"\f(CW0\fR") otherwise). | |
1463 | .Sp | |
1464 | The latter comparison assumes \fB\s-1SIGNED\s0\fR bit vectors. | |
1465 | .SH "SEE ALSO" | |
1466 | .IX Header "SEE ALSO" | |
1467 | \&\fIBit::Vector\fR\|(3), \fISet::IntRange\fR\|(3), \fIMath::MatrixBool\fR\|(3), | |
1468 | \&\fIMath::MatrixReal\fR\|(3), \fIDFA::Kleene\fR\|(3), \fIMath::Kleene\fR\|(3), | |
1469 | \&\fIGraph::Kruskal\fR\|(3). | |
1470 | .PP | |
1471 | \&\fIperl\fR\|(1), \fIperlsub\fR\|(1), \fIperlmod\fR\|(1), \fIperlref\fR\|(1), \fIperlobj\fR\|(1), | |
1472 | \&\fIperlbot\fR\|(1), \fIperltoot\fR\|(1), \fIperlxs\fR\|(1), \fIperlxstut\fR\|(1), | |
1473 | \&\fIperlguts\fR\|(1), \fIoverload\fR\|(3). | |
1474 | .SH "VERSION" | |
1475 | .IX Header "VERSION" | |
1476 | This man page documents \*(L"Bit::Vector::Overload\*(R" version 6.1. | |
1477 | .SH "AUTHOR" | |
1478 | .IX Header "AUTHOR" | |
1479 | .Vb 3 | |
1480 | \& Steffen Beyer | |
1481 | \& mailto:sb@engelschall.com | |
1482 | \& http://www.engelschall.com/u/sb/download/ | |
1483 | .Ve | |
1484 | .SH "COPYRIGHT" | |
1485 | .IX Header "COPYRIGHT" | |
1486 | Copyright (c) 2000 \- 2001 by Steffen Beyer. All rights reserved. | |
1487 | .SH "LICENSE" | |
1488 | .IX Header "LICENSE" | |
1489 | This package is free software; you can redistribute it and/or | |
1490 | modify it under the same terms as Perl itself, i.e., under the | |
1491 | terms of the \*(L"Artistic License\*(R" or the \*(L"\s-1GNU\s0 General Public License\*(R". | |
1492 | .PP | |
1493 | The C library at the core of this Perl module can additionally | |
1494 | be redistributed and/or modified under the terms of the \*(L"\s-1GNU\s0 | |
1495 | Library General Public License\*(R". | |
1496 | .PP | |
1497 | Please refer to the files \*(L"Artistic.txt\*(R", \*(L"\s-1GNU_GPL\s0.txt\*(R" and | |
1498 | \&\*(L"\s-1GNU_LGPL\s0.txt\*(R" in this distribution for details! | |
1499 | .SH "DISCLAIMER" | |
1500 | .IX Header "DISCLAIMER" | |
1501 | This package is distributed in the hope that it will be useful, | |
1502 | but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of | |
1503 | \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. | |
1504 | .PP | |
1505 | See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details. |