1Bit::Vector::Overload(3U)ser Contributed Perl DocumentatiBoint::Vector::Overload(3)
2
6 Bit::Vector::Overload - Overloaded operators add-on for Bit::Vector
7
9 Note that you do not need to ""use Bit::Vector;"" in addition to this
10 module.
11 Simply ""use Bit::Vector::Overload;"" INSTEAD of ""use Bit::Vector;"".
13 You can still use all the methods from the "Bit::Vector" module in
14 addition to the overloaded operators and methods provided here after
15 that.
16
18 Configuration
19 $config = Bit::Vector->Configuration();
20 Bit::Vector->Configuration($config);
21 $oldconfig = Bit::Vector->Configuration($newconfig);
22 String Conversion
24 $string = "$vector"; # depending on configuration
25 print "\$vector = '$vector'\n";
26 Emptyness
28 if ($vector) # if not empty (non-zero)
29 if (! $vector) # if empty (zero)
30 unless ($vector) # if empty (zero)
31 Complement (one's complement)
33 $vector2 = ~$vector1;
34 $vector = ~$vector;
35 Negation (two's complement)
37 $vector2 = -$vector1;
38 $vector = -$vector;
39 Norm
41 $norm = abs($vector); # depending on configuration
42 Absolute
44 $vector2 = abs($vector1); # depending on configuration
45 Concatenation
47 $vector3 = $vector1 . $vector2;
48 $vector1 .= $vector2;
49 $vector1 = $vector2 . $vector1;
50 $vector2 = $vector1 . $scalar; # depending on configuration
51 $vector2 = $scalar . $vector1;
52 $vector .= $scalar;
53 Duplication
55 $vector2 = $vector1 x $factor;
56 $vector x= $factor;
57 Shift Left
59 $vector2 = $vector1 << $bits;
60 $vector <<= $bits;
61 Shift Right
63 $vector2 = $vector1 >> $bits;
64 $vector >>= $bits;
65 Union
67 $vector3 = $vector1 ⎪ $vector2;
68 $vector1 ⎪= $vector2;
69 $vector2 = $vector1 ⎪ $scalar;
70 $vector ⎪= $scalar;
71 $vector3 = $vector1 + $vector2; # depending on configuration
73 $vector1 += $vector2;
74 $vector2 = $vector1 + $scalar;
75 $vector += $scalar;
76 Intersection
78 $vector3 = $vector1 & $vector2;
79 $vector1 &= $vector2;
80 $vector2 = $vector1 & $scalar;
81 $vector &= $scalar;
82 $vector3 = $vector1 * $vector2; # depending on configuration
84 $vector1 *= $vector2;
85 $vector2 = $vector1 * $scalar;
86 $vector *= $scalar;
87 ExclusiveOr
89 $vector3 = $vector1 ^ $vector2;
90 $vector1 ^= $vector2;
91 $vector2 = $vector1 ^ $scalar;
92 $vector ^= $scalar;
93 Set Difference
95 $vector3 = $vector1 - $vector2; # depending on configuration
96 $vector1 -= $vector2;
97 $vector1 = $vector2 - $vector1;
98 $vector2 = $vector1 - $scalar;
99 $vector2 = $scalar - $vector1;
100 $vector -= $scalar;
101 Addition
103 $vector3 = $vector1 + $vector2; # depending on configuration
104 $vector1 += $vector2;
105 $vector2 = $vector1 + $scalar;
106 $vector += $scalar;
107 Subtraction
109 $vector3 = $vector1 - $vector2; # depending on configuration
110 $vector1 -= $vector2;
111 $vector1 = $vector2 - $vector1;
112 $vector2 = $vector1 - $scalar;
113 $vector2 = $scalar - $vector1;
114 $vector -= $scalar;
115 Multiplication
117 $vector3 = $vector1 * $vector2; # depending on configuration
118 $vector1 *= $vector2;
119 $vector2 = $vector1 * $scalar;
120 $vector *= $scalar;
121 Division
123 $vector3 = $vector1 / $vector2;
124 $vector1 /= $vector2;
125 $vector1 = $vector2 / $vector1;
126 $vector2 = $vector1 / $scalar;
127 $vector2 = $scalar / $vector1;
128 $vector /= $scalar;
129 Modulo
131 $vector3 = $vector1 % $vector2;
132 $vector1 %= $vector2;
133 $vector1 = $vector2 % $vector1;
134 $vector2 = $vector1 % $scalar;
135 $vector2 = $scalar % $vector1;
136 $vector %= $scalar;
137 Exponentiation
139 $vector3 = $vector1 ** $vector2;
140 $vector1 **= $vector2;
141 $vector2 = $vector1 ** $scalar;
142 $vector2 = $scalar ** $vector1;
143 $vector **= $scalar;
144 Increment
146 ++$vector;
147 $vector++;
148 Decrement
150 --$vector;
151 $vector--;
152 Lexical Comparison (unsigned)
154 $cmp = $vector1 cmp $vector2;
155 if ($vector1 lt $vector2)
156 if ($vector1 le $vector2)
157 if ($vector1 gt $vector2)
158 if ($vector1 ge $vector2)
159 $cmp = $vector cmp $scalar;
161 if ($vector lt $scalar)
162 if ($vector le $scalar)
163 if ($vector gt $scalar)
164 if ($vector ge $scalar)
165 Comparison (signed)
167 $cmp = $vector1 <=> $vector2;
168 if ($vector1 < $vector2) # depending on configuration
169 if ($vector1 <= $vector2)
170 if ($vector1 > $vector2)
171 if ($vector1 >= $vector2)
172 $cmp = $vector <=> $scalar;
174 if ($vector < $scalar) # depending on configuration
175 if ($vector <= $scalar)
176 if ($vector > $scalar)
177 if ($vector >= $scalar)
178 Equality
180 if ($vector1 eq $vector2)
181 if ($vector1 ne $vector2)
182 if ($vector eq $scalar)
183 if ($vector ne $scalar)
184 if ($vector1 == $vector2)
186 if ($vector1 != $vector2)
187 if ($vector == $scalar)
188 if ($vector != $scalar)
189 Subset Relationship
191 if ($vector1 <= $vector2) # depending on configuration
192 True Subset Relationship
194 if ($vector1 < $vector2) # depending on configuration
195 Superset Relationship
197 if ($vector1 >= $vector2) # depending on configuration
198 True Superset Relationship
200 if ($vector1 > $vector2) # depending on configuration
201
203 · Boolean values
204 Boolean values in this module are always a numeric zero ("0") for
206 "false" and a numeric one ("1") for "true".
207 · Negative numbers
209 Numeric factors (as needed for the ""<<"", "">>"" and ""x"" opera‐
211 tors) and bit numbers are always regarded as being UNSIGNED.
212 As a consequence, whenever you pass a negative number for such a fac‐
214 tor or bit number, it will be treated as a (usually very large) posi‐
215 tive number due to its internal two's complement binary representa‐
216 tion, usually resulting in malfunctions or an "index out of range"
217 error message and program abortion.
218 Note that this does not apply to "big integer" decimal numbers, which
220 are (usually) passed as strings, and which may of course be negative
221 (see also the section "Big integers" a little further below).
222 · Overloaded operators configuration
224 Note that the behaviour of certain overloaded operators can be
226 changed in various ways by means of the ""Configuration()"" method
227 (for more details, see the description of this method further below).
228 For instance, scalars (i.e., numbers and strings) provided as oper‐
230 ands to overloaded operators are automatically converted to bit vec‐
231 tors, internally.
232 These scalars are thereby automatically assumed to be indices or to
234 be in hexadecimal, binary, decimal or enumeration format, depending
235 on the configuration.
236 Similarly, when converting bit vectors to strings using double quotes
238 (""), the output format will also depend on the previously chosen
239 configuration.
240 Finally, some overloaded operators may have different semantics
242 depending on the proper configuration; for instance, the operator "+"
243 can be the "union" operator from set theory or the arithmetic "add"
244 operator.
245 In all cases (input, output and operator semantics), the defaults
247 have been chosen in such a way so that the behaviour of the module is
248 backward compatible with previous versions.
249 · "Big integers"
251 As long as "big integers" (for "big integer" arithmetic) are small
253 enough so that Perl doesn't need scientific notation (exponents) to
254 be able to represent them internally, you can provide these "big
255 integer" constants to the overloaded operators of this module (or to
256 the method ""from_Dec()"") in numeric form (i.e., either as a numeric
257 constant or expression or as a Perl variable containing a numeric
258 value).
259 Note that you will get an error message (resulting in program abor‐
261 tion) if your "big integer" numbers exceed that limit.
262 Because this limit is machine-dependent and not obvious to find out,
264 it is strongly recommended that you enclose ALL your "big integer"
265 constants in your programs in (double or single) quotes.
266 Examples:
268 $vector /= 10; # ok because number is small
270 $vector /= -10; # ok for same reason
272 $vector /= "10"; # always correct
274 $vector += "1152921504606846976"; # quotes probably required here
276 All examples assume
278 Bit::Vector->Configuration("input=decimal");
280 having been set beforehand.
282 Note also that this module does not support scientific notation
284 (exponents) for "big integer" decimal numbers because you can always
285 make the bit vector large enough for the whole number to fit without
286 loss of precision (as it would occur if scientific notation were
287 used).
288 Finally, note that the only characters allowed in "big integer" con‐
290 stant strings are the digits 0..9 and an optional leading sign (""+""
291 or ""-"").
292 All other characters produce a syntax error.
294 · Valid operands for overloaded operators
296 All overloaded operators expect at least one bit vector operand, in
298 order for the operator to "know" that not the usual operation is to
299 be carried out, but rather the overloaded variant.
300 This is especially true for all unary operators:
302 "$vector"
304 if ($vector)
305 if (!$vector)
306 ~$vector
307 -$vector
308 abs($vector)
309 ++$vector
310 $vector++
311 --$vector
312 $vector--
313 For obvious reasons the left operand (the "lvalue") of all assignment
315 operators is also required to be a bit vector:
316 .=
318 x=
319 <<=
320 >>=
321 ⎪=
322 &=
323 ^=
324 +=
325 -=
326 *=
327 /=
328 %=
329 **=
330 In the case of three special operators, namely ""<<"", "">>"" and
332 ""x"", as well as their related assignment variants, ""<<="", "">>=""
333 and ""x="", the left operand is ALWAYS a bit vector and the right op‐
334 erand is ALWAYS a number (which is the factor indicating how many
335 times the operator is to be applied).
336 In all truly binary operators, i.e.,
338 .
340 ⎪
341 &
342 ^
343 +
344 -
345 *
346 /
347 %
348 **
349 <=> cmp
350 == eq
351 != ne
352 < lt
353 <= le
354 > gt
355 >= ge
356 one of either operands may be replaced by a Perl scalar, i.e., a num‐
358 ber or a string, either as a Perl constant, a Perl expression or a
359 Perl variable yielding a number or a string.
360 The same applies to the right side operand (the "rvalue") of the
362 remaining assignment operators, i.e.,
363 .=
365 ⎪=
366 &=
367 ^=
368 +=
369 -=
370 *=
371 /=
372 %=
373 **=
374 Note that this Perl scalar should be of the correct type, i.e.,
376 numeric or string, for the chosen configuration, because otherwise a
377 warning message will occur if your program runs under the ""-w""
378 switch of Perl.
379 The acceptable scalar types for each possible configuration are the
381 following:
382 input = bit indices (default) : numeric
384 input = hexadecimal : string
385 input = binary : string
386 input = decimal : string (in general)
387 input = decimal : numeric (if small enough)
388 input = enumeration : string
389 NOTE ALSO THAT THESE SCALAR OPERANDS ARE CONVERTED TO BIT VECTORS OF
391 THE SAME SIZE AS THE BIT VECTOR WHICH IS THE OTHER OPERAND.
392 The only exception from this rule is the concatenation operator
394 (""."") and its assignment variant ("".=""):
395 If one of the two operands of the concatenation operator (""."") is
397 not a bit vector object but a Perl scalar, the contents of the
398 remaining bit vector operand are converted into a string (the format
399 of which depends on the configuration set with the ""Configura‐
400 tion()"" method), which is then concatenated in the proper order
401 (i.e., as indicated by the order of the two operands) with the Perl
402 scalar (in other words, a string is returned in such a case instead
403 of a bit vector object!).
404 If the right side operand (the "rvalue") of the assignment variant
406 ("".="") of the concatenation operator is a Perl scalar, it is con‐
407 verted internally to a bit vector of the same size as the left side
408 operand provided that the configuration states that scalars are to be
409 regarded as indices, decimal strings or enumerations.
410 If the configuration states that scalars are to be regarded as hexa‐
412 decimal or boolean strings, however, these strings are converted to
413 bit vectors of a size matching the length of the input string, i.e.,
414 four times the length for hexadecimal strings (because each hexadeci‐
415 mal digit is worth 4 bits) and once the length for binary strings.
416 If a decimal number ("big integer") is too large to be stored in a
418 bit vector of the given size, a "numeric overflow error" occurs.
419 If a bit index is out of range for the given bit vector, an "index
421 out of range" error occurs.
422 If a scalar operand cannot be converted successfully due to invalid
424 syntax, a fatal "input string syntax error" is issued.
425 If the two operands of the operator ""<<"", "">>"" or ""x"" are
427 reversed, a fatal "reversed operands error" occurs.
428 If an operand is neither a bit vector nor a scalar, then a fatal
430 "illegal operand type error" occurs.
431 · Bit order
433 Note that bit vectors are stored least order bit and least order word
435 first internally.
436 I.e., bit #0 of any given bit vector corresponds to bit #0 of word #0
438 in the array of machine words representing the bit vector.
439 (Where word #0 comes first in memory, i.e., it is stored at the least
441 memory address in the allocated block of memory holding the given bit
442 vector.)
443 Note however that machine words can be stored least order byte first
445 or last, depending on your system's implementation.
446 Note further that whenever bit vectors are converted to and from
448 (binary or hexadecimal) strings, the RIGHTMOST bit is always the
449 LEAST SIGNIFICANT one, and the LEFTMOST bit is always the MOST SIG‐
450 NIFICANT bit.
451 This is because in our western culture, numbers are always repre‐
453 sented in this way (least significant to most significant digits go
454 from right to left).
455 Of course this requires an internal reversion of order, which the
457 corresponding conversion methods perform automatically (without any
458 additional overhead, it's just a matter of starting the internal loop
459 at the bottom or the top end).
460 · Matching sizes
462 In general, for methods involving several bit vectors at the same
464 time, all bit vector arguments must have identical sizes (number of
465 bits), or a fatal "size mismatch" error will occur.
466 Exceptions from this rule are the methods ""Concat()"", ""Con‐
468 cat_List()"", ""Copy()"", ""Interval_Copy()"" and ""Interval_Substi‐
469 tute()"", where no conditions at all are imposed on the size of their
470 bit vector arguments.
471 In method ""Multiply()"", all three bit vector arguments must in
473 principle obey the rule of matching sizes, but the bit vector in
474 which the result of the multiplication is to be stored may be larger
475 than the two bit vector arguments containing the factors for the mul‐
476 tiplication.
477 In method ""Power()"", the bit vector for the result must be the same
479 size or greater than the base of the exponentiation term. The expo‐
480 nent can be any size.
481 The same applies to the corresponding overloaded operators.
483 · Index ranges
485 All indices for any given bits must lie between "0" and ""$vec‐
487 tor->Size()-1"", or a fatal "index out of range" error will occur.
488
490 · "$config = Bit::Vector->Configuration();"
491 · "Bit::Vector->Configuration($config);"
493 · "$oldconfig = Bit::Vector->Configuration($newconfig);"
495 This method serves to alter the semantics (i.e., behaviour) of cer‐
497 tain overloaded operators (which are all implemented in Perl, by the
498 way).
499 It does not have any effect whatsoever on anything else. In particu‐
501 lar, it does not affect the methods implemented in C.
502 The method accepts an (optional) string as input in which certain
504 keywords are expected, which influence some or almost all of the
505 overloaded operators in several possible ways.
506 The method always returns a string (which you do not need to take
508 care of, i.e., to store, in case you aren't interested in keeping it)
509 which is a complete representation of the current configuration
510 (i.e., BEFORE any modifications are applied) and which can be fed
511 back to this method later in order to restore the previous configura‐
512 tion.
513 There are three aspects of the way certain overloaded operators
515 behave which can be controlled with this method:
516 + the way scalar operands (replacing one of the two
518 bit vector object operands) are automatically
519 converted internally into a bit vector object of
520 their own,
521 + the operation certain overloaded operators perform,
523 i.e., an operation with sets or an arithmetic
524 operation,
525 + the format to which bit vectors are converted
527 automatically when they are enclosed in double
528 quotes.
529 The input string may contain any number of assignments, each of which
531 controls one of these three aspects.
532 Each assignment has the form ""<which>=<value>"".
534 ""<which>"" and ""<value>"" thereby consist of letters ("[a-zA-Z]")
536 and white space.
537 Multiple assignments have to be separated by one or more comma (","),
539 semi-colon (";"), colon (":"), vertical bar ("⎪"), slash ("/"), new‐
540 line ("\n"), ampersand ("&"), plus ("+") or dash ("-").
541 Empty lines or statements (only white space) are allowed but will be
543 ignored.
544 ""<which>"" has to contain one or more keywords from one of three
546 groups, each group representing one of the three aspects that the
547 ""Configuration()"" method controls:
548 + "^scalar", "^input", "^in$"
550 + "^operator", "^semantic", "^ops$"
552 + "^string", "^output", "^out$"
554 The character "^" thereby denotes the beginning of a word, and "$"
556 denotes the end. Case is ignored (!).
557 Using these keywords, you can build any phrase you like to select one
559 of the three aspects (see also examples given below).
560 The only condition is that no other keyword from any of the other two
562 groups may match - otherwise a syntax error will occur (i.e., ambigu‐
563 ities are forbidden). A syntax error also occurs if none of the key‐
564 words matches.
565 This same principle applies to ""<value>"":
567 Depending on which aspect you specified for ""<which>"", there are
569 different groups of keywords that determine the value the selected
570 aspect will be set to:
571 + "<which>" = "^scalar", "^input", "^in$":
573 "<value>" =
575 * "^bit$", "^index", "^indice"
577 * "^hex"
578 * "^bin"
579 * "^dec"
580 * "^enum"
581 + "<which>" = "^operator", "^semantic", "^ops$":
583 "<value>" =
585 * "^set$"
587 * "^arithmetic"
588 + "<which>" = "^string", "^output", "^out$":
590 "<value>" =
592 * "^hex"
594 * "^bin"
595 * "^dec"
596 * "^enum"
597 Examples:
599 "Any scalar input I provide should be considered to be = a bit index"
601 "I want to have operator semantics suitable for = arithmetics"
603 "Any bit vector in double quotes is to be output as = an enumeration"
605 SCALAR INPUT:
607 In the case of scalar input, ""^bit$"", ""^index"", or ""^indice""
609 all cause scalar input to be considered to represent a bit index,
610 i.e., ""$vector ^= 5;"" will flip bit #5 in the given bit vector
611 (this is essentially the same as ""$vector->bit_flip(5);"").
612 Note that "bit indices" is the default setting for "scalar input".
614 The keyword ""^hex"" will cause scalar input to be considered as
616 being in hexadecimal, i.e., ""$vector ^= 5;"" will flip bit #0 and
617 bit #2 (because hexadecimal "5" is binary "0101").
618 (Note though that hexadecimal input should always be enclosed in
620 quotes, otherwise it will be interpreted as a decimal number by Perl!
621 The example relies on the fact that hexadecimal "0-9" and decimal
622 "0-9" are the same.)
623 The keyword ""^bin"" will cause scalar input to be considered as
625 being in binary format. All characters except "0" and "1" are forbid‐
626 den in this case (i.e., produce a syntax error).
627 ""$vector ^= '0101';"", for instance, will flip bit #0 and bit #2.
629 The keyword ""^dec"" causes scalar input to be considered as integers
631 in decimal format, i.e., ""$vector ^= 5;"" will flip bit #0 and bit
632 #2 (because decimal "5" is binary "0101").
633 (Note though that all decimal input should be enclosed in quotes,
635 because for large numbers, Perl will use scientific notation inter‐
636 nally for representing them, which produces a syntax error because
637 scientific notation is neither supported by this module nor needed.)
638 Finally, the keyword ""^enum"" causes scalar input to be considered
640 as being a list ("enumeration") of indices and ranges of (contiguous)
641 indices, i.e., ""$vector ⎪= '2,3,5,7-13,17-23';"" will cause bits #2,
642 #3, #5, #7 through #13 and #17 through #23 to be set.
643 OPERATOR SEMANTICS:
645 Several overloaded operators can have two distinct functions depend‐
647 ing on this setting.
648 The affected operators are: ""+"", ""-"", ""*"", ""<"", ""<="", "">""
650 and "">="".
651 With the default setting, "set operations", these operators perform:
653 + set union ( set1 u set2 )
655 - set difference ( set1 \ set2 )
656 * set intersection ( set1 n set2 )
657 < true subset relationship ( set1 < set2 )
658 <= subset relationship ( set1 <= set2 )
659 > true superset relationship ( set1 > set2 )
660 >= superset relationship ( set1 >= set2 )
661 With the alternative setting, "arithmetic operations", these opera‐
663 tors perform:
664 + addition ( num1 + num2 )
666 - subtraction ( num1 - num2 )
667 * multiplication ( num1 * num2 )
668 < "less than" comparison ( num1 < num2 )
669 <= "less than or equal" comparison ( num1 <= num2 )
670 > "greater than" comparison ( num1 > num2 )
671 >= "greater than or equal" comparison ( num1 >= num2 )
672 Note that these latter comparison operators (""<"", ""<="", "">"" and
674 "">="") regard their operands as being SIGNED.
675 To perform comparisons with UNSIGNED operands, use the operators
677 ""lt"", ""le"", ""gt"" and ""ge"" instead (in contrast to the opera‐
678 tors above, these operators are NOT affected by the "operator seman‐
679 tics" setting).
680 STRING OUTPUT:
682 There are four methods which convert the contents of a given bit vec‐
684 tor into a string: ""to_Hex()"", ""to_Bin()"", ""to_Dec()"" and
685 ""to_Enum()"" (not counting ""Block_Read()"", since this method does
686 not return a human-readable string).
687 (For conversion to octal, see the description of the method
689 ""Chunk_List_Read()"".)
690 Therefore, there are four possible formats into which a bit vector
692 can be converted when it is enclosed in double quotes, for example:
693 print "\$vector = '$vector'\n";
695 $string = "$vector";
696 Hence you can set "string output" to four different values: To "hex"
698 for hexadecimal format (which is the default), to "bin" for binary
699 format, to "dec" for conversion to decimal numbers and to "enum" for
700 conversion to enumerations (".newsrc" style sets).
701 BEWARE that the conversion to decimal numbers is inherently slow; it
703 can easily take up several seconds for a single large bit vector!
704 Therefore you should store the decimal strings returned to you rather
706 than converting a given bit vector again.
707 EXAMPLES:
709 The default setting as returned by the method ""Configuration()"" is:
711 Scalar Input = Bit Index
713 Operator Semantics = Set Operators
714 String Output = Hexadecimal
715 Performing a statement such as:
717 Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
719 print Bit::Vector->Configuration(), "\n";
720 yields the following output:
722 Scalar Input = Binary
724 Operator Semantics = Arithmetic Operators
725 String Output = Binary
726 Note that you can always feed this output back into the ""Configura‐
728 tion()"" method to restore that setting later.
729 This also means that you can enter the same given setting with almost
731 any degree of verbosity you like (as long as the required keywords
732 appear and no ambiguities arise).
733 Note further that any aspect you do not specify is not changed, i.e.,
735 the statement
736 Bit::Vector->Configuration("operators = arithmetic");
738 leaves all other aspects unchanged.
740 · "$vector"
742 Remember that variables enclosed in double quotes are always interpo‐
744 lated in Perl.
745 Whenever a Perl variable containing the reference of a "Bit::Vector"
747 object is enclosed in double quotes (either alone or together with
748 other text and/or variables), the contents of the corresponding bit
749 vector are converted into a printable string.
750 Since there are several conversion methods available in this module
752 (see the description of the methods ""to_Hex()"", ""to_Bin()"",
753 ""to_Dec()"" and ""to_Enum()""), it is of course desirable to be able
754 to choose which of these methods should be applied in this case.
755 This can actually be done by changing the configuration of this mod‐
757 ule using the method ""Configure()"" (see the previous chapter, imme‐
758 diately above).
759 The default is conversion to hexadecimal.
761 · "if ($vector)"
763 It is possible to use a Perl variable containing the reference of a
765 "Bit::Vector" object as a boolean expression.
766 The condition above is true if the corresponding bit vector contains
768 at least one set bit, and it is false if ALL bits of the correspond‐
769 ing bit vector are cleared.
770 · "if (!$vector)"
772 Since it is possible to use a Perl variable containing the reference
774 of a "Bit::Vector" object as a boolean expression, you can of course
775 also negate this boolean expression.
776 The condition above is true if ALL bits of the corresponding bit vec‐
778 tor are cleared, and it is false if the corresponding bit vector con‐
779 tains at least one set bit.
780 Note that this is NOT the same as using the method ""is_full()"",
782 which returns true if ALL bits of the corresponding bit vector are
783 SET.
784 · "~$vector"
786 This term returns a new bit vector object which is the one's comple‐
788 ment of the given bit vector.
789 This is equivalent to inverting all bits.
791 · "-$vector" (unary minus)
793 This term returns a new bit vector object which is the two's comple‐
795 ment of the given bit vector.
796 This is equivalent to inverting all bits and incrementing the result
798 by one.
799 (This is the same as changing the sign of a number in two's comple‐
801 ment binary representation.)
802 · "abs($vector)"
804 Depending on the configuration (see the description of the method
806 ""Configuration()"" for more details), this term either returns the
807 number of set bits in the given bit vector (this is the same as cal‐
808 culating the number of elements which are contained in the given set)
809 - which is the default behaviour, or it returns a new bit vector
810 object which contains the absolute value of the number stored in the
811 given bit vector.
812 · "$vector1 . $vector2"
814 This term usually returns a new bit vector object which is the result
816 of the concatenation of the two bit vector operands.
817 The left operand becomes the most significant, and the right operand
819 becomes the least significant part of the new bit vector object.
820 If one of the two operands is not a bit vector object but a Perl
822 scalar, however, the contents of the remaining bit vector operand are
823 converted into a string (the format of which depends on the configu‐
824 ration set with the ""Configuration()"" method), which is then con‐
825 catenated in the proper order (i.e., as indicated by the order of the
826 two operands) with the Perl scalar.
827 In other words, a string is returned in such a case instead of a bit
829 vector object!
830 · "$vector x $factor"
832 This term returns a new bit vector object which is the concatenation
834 of as many copies of the given bit vector operand (the left operand)
835 as the factor (the right operand) specifies.
836 If the factor is zero, a bit vector object with a length of zero bits
838 is returned.
839 If the factor is one, just a new copy of the given bit vector is
841 returned.
842 Note that a fatal "reversed operands error" occurs if the two oper‐
844 ands are swapped.
845 · "$vector << $bits"
847 This term returns a new bit vector object which is a copy of the
849 given bit vector (the left operand), which is then shifted left
850 (towards the most significant bit) by as many places as the right op‐
851 erand, "$bits", specifies.
852 This means that the "$bits" most significant bits are lost, all other
854 bits move up by "$bits" positions, and the "$bits" least significant
855 bits that have been left unoccupied by this shift are all set to
856 zero.
857 If "$bits" is greater than the number of bits of the given bit vec‐
859 tor, this term returns an empty bit vector (i.e., with all bits
860 cleared) of the same size as the given bit vector.
861 Note that a fatal "reversed operands error" occurs if the two oper‐
863 ands are swapped.
864 · "$vector >> $bits"
866 This term returns a new bit vector object which is a copy of the
868 given bit vector (the left operand), which is then shifted right
869 (towards the least significant bit) by as many places as the right
870 operand, "$bits", specifies.
871 This means that the "$bits" least significant bits are lost, all
873 other bits move down by "$bits" positions, and the "$bits" most sig‐
874 nificant bits that have been left unoccupied by this shift are all
875 set to zero.
876 If "$bits" is greater than the number of bits of the given bit vec‐
878 tor, this term returns an empty bit vector (i.e., with all bits
879 cleared) of the same size as the given bit vector.
880 Note that a fatal "reversed operands error" occurs if the two oper‐
882 ands are swapped.
883 · "$vector1 ⎪ $vector2"
885 This term returns a new bit vector object which is the result of a
887 bitwise OR operation between the two bit vector operands.
888 This is the same as calculating the union of two sets.
890 · "$vector1 & $vector2"
892 This term returns a new bit vector object which is the result of a
894 bitwise AND operation between the two bit vector operands.
895 This is the same as calculating the intersection of two sets.
897 · "$vector1 ^ $vector2"
899 This term returns a new bit vector object which is the result of a
901 bitwise XOR (exclusive-or) operation between the two bit vector oper‐
902 ands.
903 This is the same as calculating the symmetric difference of two sets.
905 · "$vector1 + $vector2"
907 Depending on the configuration (see the description of the method
909 ""Configuration()"" for more details), this term either returns a new
910 bit vector object which is the result of a bitwise OR operation
911 between the two bit vector operands (this is the same as calculating
912 the union of two sets) - which is the default behaviour, or it
913 returns a new bit vector object which contains the sum of the two
914 numbers stored in the two bit vector operands.
915 · "$vector1 - $vector2"
917 Depending on the configuration (see the description of the method
919 ""Configuration()"" for more details), this term either returns a new
920 bit vector object which is the set difference of the two sets repre‐
921 sented in the two bit vector operands - which is the default behav‐
922 iour, or it returns a new bit vector object which contains the dif‐
923 ference of the two numbers stored in the two bit vector operands.
924 · "$vector1 * $vector2"
926 Depending on the configuration (see the description of the method
928 ""Configuration()"" for more details), this term either returns a new
929 bit vector object which is the result of a bitwise AND operation
930 between the two bit vector operands (this is the same as calculating
931 the intersection of two sets) - which is the default behaviour, or it
932 returns a new bit vector object which contains the product of the two
933 numbers stored in the two bit vector operands.
934 · "$vector1 / $vector2"
936 This term returns a new bit vector object containing the result of
938 the division of the two numbers stored in the two bit vector oper‐
939 ands.
940 · "$vector1 % $vector2"
942 This term returns a new bit vector object containing the remainder of
944 the division of the two numbers stored in the two bit vector oper‐
945 ands.
946 · "$vector1 ** $vector2"
948 This term returns a new bit vector object containing the result of
950 the exponentiation of the left bit vector elevated to the right bit
951 vector's power.
952 · "$vector1 .= $vector2;"
954 This statement "appends" the right bit vector operand (the "rvalue")
956 to the left one (the "lvalue").
957 The former contents of the left operand become the most significant
959 part of the resulting bit vector, and the right operand becomes the
960 least significant part.
961 Since bit vectors are stored in "least order bit first" order, this
963 actually requires the left operand to be shifted "up" by the length
964 of the right operand, which is then copied to the now freed least
965 significant part of the left operand.
966 If the right operand is a Perl scalar, it is first converted to a bit
968 vector of the same size as the left operand, provided that the con‐
969 figuration states that scalars are to be regarded as indices, decimal
970 strings or enumerations.
971 If the configuration states that scalars are to be regarded as hexa‐
973 decimal or boolean strings, however, these strings are converted to
974 bit vectors of a size matching the length of the input string, i.e.,
975 four times the length for hexadecimal strings (because each hexadeci‐
976 mal digit is worth 4 bits) and once the length for binary strings.
977 · "$vector x= $factor;"
979 This statement replaces the given bit vector by a concatenation of as
981 many copies of the original contents of the given bit vector as the
982 factor (the right operand) specifies.
983 If the factor is zero, the given bit vector is resized to a length of
985 zero bits.
986 If the factor is one, the given bit vector is not changed at all.
988 · "$vector <<= $bits;"
990 This statement moves the contents of the given bit vector left by
992 "$bits" positions (towards the most significant bit).
993 This means that the "$bits" most significant bits are lost, all other
995 bits move up by "$bits" positions, and the "$bits" least significant
996 bits that have been left unoccupied by this shift are all set to
997 zero.
998 If "$bits" is greater than the number of bits of the given bit vec‐
1000 tor, the given bit vector is erased completely (i.e., all bits are
1001 cleared).
1002 · "$vector >>= $bits;"
1004 This statement moves the contents of the given bit vector right by
1006 "$bits" positions (towards the least significant bit).
1007 This means that the "$bits" least significant bits are lost, all
1009 other bits move down by "$bits" positions, and the "$bits" most sig‐
1010 nificant bits that have been left unoccupied by this shift are all
1011 set to zero.
1012 If "$bits" is greater than the number of bits of the given bit vec‐
1014 tor, the given bit vector is erased completely (i.e., all bits are
1015 cleared).
1016 · "$vector1 ⎪= $vector2;"
1018 This statement performs a bitwise OR operation between the two bit
1020 vector operands and stores the result in the left operand.
1021 This is the same as calculating the union of two sets.
1023 · "$vector1 &= $vector2;"
1025 This statement performs a bitwise AND operation between the two bit
1027 vector operands and stores the result in the left operand.
1028 This is the same as calculating the intersection of two sets.
1030 · "$vector1 ^= $vector2;"
1032 This statement performs a bitwise XOR (exclusive-or) operation
1034 between the two bit vector operands and stores the result in the left
1035 operand.
1036 This is the same as calculating the symmetric difference of two sets.
1038 · "$vector1 += $vector2;"
1040 Depending on the configuration (see the description of the method
1042 ""Configuration()"" for more details), this statement either performs
1043 a bitwise OR operation between the two bit vector operands (this is
1044 the same as calculating the union of two sets) - which is the default
1045 behaviour, or it calculates the sum of the two numbers stored in the
1046 two bit vector operands.
1047 The result of this operation is stored in the left operand.
1049 · "$vector1 -= $vector2;"
1051 Depending on the configuration (see the description of the method
1053 ""Configuration()"" for more details), this statement either calcu‐
1054 lates the set difference of the two sets represented in the two bit
1055 vector operands - which is the default behaviour, or it calculates
1056 the difference of the two numbers stored in the two bit vector oper‐
1057 ands.
1058 The result of this operation is stored in the left operand.
1060 · "$vector1 *= $vector2;"
1062 Depending on the configuration (see the description of the method
1064 ""Configuration()"" for more details), this statement either performs
1065 a bitwise AND operation between the two bit vector operands (this is
1066 the same as calculating the intersection of two sets) - which is the
1067 default behaviour, or it calculates the product of the two numbers
1068 stored in the two bit vector operands.
1069 The result of this operation is stored in the left operand.
1071 · "$vector1 /= $vector2;"
1073 This statement puts the result of the division of the two numbers
1075 stored in the two bit vector operands into the left operand.
1076 · "$vector1 %= $vector2;"
1078 This statement puts the remainder of the division of the two numbers
1080 stored in the two bit vector operands into the left operand.
1081 · "$vector1 **= $vector2;"
1083 This statement puts the result of the exponentiation of the left op‐
1085 erand elevated to the right operand's power into the left operand.
1086 · "++$vector", "$vector++"
1088 This operator performs pre- and post-incrementation of the given bit
1090 vector.
1091 The value returned by this term is a reference of the given bit vec‐
1093 tor object (after or before the incrementation, respectively).
1094 · "--$vector", "$vector--"
1096 This operator performs pre- and post-decrementation of the given bit
1098 vector.
1099 The value returned by this term is a reference of the given bit vec‐
1101 tor object (after or before the decrementation, respectively).
1102 · "($vector1 cmp $vector2)"
1104 This term returns ""-1"" if "$vector1" is less than "$vector2", "0"
1106 if "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1107 greater than "$vector2".
1108 This comparison assumes UNSIGNED bit vectors.
1110 · "($vector1 eq $vector2)"
1112 This term returns true ("1") if the contents of the two bit vector
1114 operands are the same and false ("0") otherwise.
1115 · "($vector1 ne $vector2)"
1117 This term returns true ("1") if the two bit vector operands differ
1119 and false ("0") otherwise.
1120 · "($vector1 lt $vector2)"
1122 This term returns true ("1") if "$vector1" is less than "$vector2",
1124 and false ("0") otherwise.
1125 This comparison assumes UNSIGNED bit vectors.
1127 · "($vector1 le $vector2)"
1129 This term returns true ("1") if "$vector1" is less than or equal to
1131 "$vector2", and false ("0") otherwise.
1132 This comparison assumes UNSIGNED bit vectors.
1134 · "($vector1 gt $vector2)"
1136 This term returns true ("1") if "$vector1" is greater than "$vec‐
1138 tor2", and false ("0") otherwise.
1139 This comparison assumes UNSIGNED bit vectors.
1141 · "($vector1 ge $vector2)"
1143 This term returns true ("1") if "$vector1" is greater than or equal
1145 to "$vector2", and false ("0") otherwise.
1146 This comparison assumes UNSIGNED bit vectors.
1148 · "($vector1 <=> $vector2)"
1150 This term returns ""-1"" if "$vector1" is less than "$vector2", "0"
1152 if "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1153 greater than "$vector2".
1154 This comparison assumes SIGNED bit vectors.
1156 · "($vector1 == $vector2)"
1158 This term returns true ("1") if the contents of the two bit vector
1160 operands are the same and false ("0") otherwise.
1161 · "($vector1 != $vector2)"
1163 This term returns true ("1") if the two bit vector operands differ
1165 and false ("0") otherwise.
1166 · "($vector1 < $vector2)"
1168 Depending on the configuration (see the description of the method
1170 ""Configuration()"" for more details), this term either returns true
1171 ("1") if "$vector1" is a true subset of "$vector2" (and false ("0")
1172 otherwise) - which is the default behaviour, or it returns true ("1")
1173 if "$vector1" is less than "$vector2" (and false ("0") otherwise).
1174 The latter comparison assumes SIGNED bit vectors.
1176 · "($vector1 <= $vector2)"
1178 Depending on the configuration (see the description of the method
1180 ""Configuration()"" for more details), this term either returns true
1181 ("1") if "$vector1" is a subset of "$vector2" (and false ("0") other‐
1182 wise) - which is the default behaviour, or it returns true ("1") if
1183 "$vector1" is less than or equal to "$vector2" (and false ("0") oth‐
1184 erwise).
1185 The latter comparison assumes SIGNED bit vectors.
1187 · "($vector1 > $vector2)"
1189 Depending on the configuration (see the description of the method
1191 ""Configuration()"" for more details), this term either returns true
1192 ("1") if "$vector1" is a true superset of "$vector2" (and false ("0")
1193 otherwise) - which is the default behaviour, or it returns true ("1")
1194 if "$vector1" is greater than "$vector2" (and false ("0") otherwise).
1195 The latter comparison assumes SIGNED bit vectors.
1197 · "($vector1 >= $vector2)"
1199 Depending on the configuration (see the description of the method
1201 ""Configuration()"" for more details), this term either returns true
1202 ("1") if "$vector1" is a superset of "$vector2" (and false ("0") oth‐
1203 erwise) - which is the default behaviour, or it returns true ("1") if
1204 "$vector1" is greater than or equal to "$vector2" (and false ("0")
1205 otherwise).
1206 The latter comparison assumes SIGNED bit vectors.
1208
1210 Bit::Vector(3), Bit::Vector::String(3).
1211
1213 This man page documents "Bit::Vector::Overload" version 6.4.
1214
1216 Steffen Beyer
1217 mailto:sb@engelschall.com
1218 http://www.engelschall.com/u/sb/download/
1219
1221 Copyright (c) 2000 - 2004 by Steffen Beyer. All rights reserved.
1222
1224 This package is free software; you can redistribute it and/or modify it
1225 under the same terms as Perl itself, i.e., under the terms of the
1226 "Artistic License" or the "GNU General Public License".
1227 The C library at the core of this Perl module can additionally be
1229 redistributed and/or modified under the terms of the "GNU Library Gen‐
1230 eral Public License".
1231 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
1233 "GNU_LGPL.txt" in this distribution for details!
1234
1236 This package is distributed in the hope that it will be useful, but
1237 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
1238 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1239 See the "GNU General Public License" for more details.
1241perl v5.8.8 2004-10-03 Bit::Vector::Overload(3)