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