4 Bit::Vector::Overload - Overloaded operators add-on for Bit::Vector
8 Note that you do not need to "C<use Bit::Vector;>"
9 in addition to this module.
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
20 $config = Bit::Vector->Configuration();
21 Bit::Vector->Configuration($config);
22 $oldconfig = Bit::Vector->Configuration($newconfig);
25 $string = "$vector"; # depending on configuration
26 print "\$vector = '$vector'\n";
29 if ($vector) # if not empty (non-zero)
30 if (! $vector) # if empty (zero)
31 unless ($vector) # if empty (zero)
33 Complement (one's complement)
37 Negation (two's complement)
42 $norm = abs($vector); # depending on configuration
45 $vector2 = abs($vector1); # depending on configuration
48 $vector3 = $vector1 . $vector2;
50 $vector1 = $vector2 . $vector1;
51 $vector2 = $vector1 . $scalar; # depending on configuration
52 $vector2 = $scalar . $vector1;
56 $vector2 = $vector1 x $factor;
60 $vector2 = $vector1 << $bits;
64 $vector2 = $vector1 >> $bits;
68 $vector3 = $vector1 | $vector2;
70 $vector2 = $vector1 | $scalar;
73 $vector3 = $vector1 + $vector2; # depending on configuration
75 $vector2 = $vector1 + $scalar;
79 $vector3 = $vector1 & $vector2;
81 $vector2 = $vector1 & $scalar;
84 $vector3 = $vector1 * $vector2; # depending on configuration
86 $vector2 = $vector1 * $scalar;
90 $vector3 = $vector1 ^ $vector2;
92 $vector2 = $vector1 ^ $scalar;
96 $vector3 = $vector1 - $vector2; # depending on configuration
98 $vector1 = $vector2 - $vector1;
99 $vector2 = $vector1 - $scalar;
100 $vector2 = $scalar - $vector1;
104 $vector3 = $vector1 + $vector2; # depending on configuration
105 $vector1 += $vector2;
106 $vector2 = $vector1 + $scalar;
110 $vector3 = $vector1 - $vector2; # depending on configuration
111 $vector1 -= $vector2;
112 $vector1 = $vector2 - $vector1;
113 $vector2 = $vector1 - $scalar;
114 $vector2 = $scalar - $vector1;
118 $vector3 = $vector1 * $vector2; # depending on configuration
119 $vector1 *= $vector2;
120 $vector2 = $vector1 * $scalar;
124 $vector3 = $vector1 / $vector2;
125 $vector1 /= $vector2;
126 $vector1 = $vector2 / $vector1;
127 $vector2 = $vector1 / $scalar;
128 $vector2 = $scalar / $vector1;
132 $vector3 = $vector1 % $vector2;
133 $vector1 %= $vector2;
134 $vector1 = $vector2 % $vector1;
135 $vector2 = $vector1 % $scalar;
136 $vector2 = $scalar % $vector1;
140 $vector3 = $vector1 ** $vector2;
141 $vector1 **= $vector2;
142 $vector2 = $vector1 ** $scalar;
143 $vector2 = $scalar ** $vector1;
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)
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)
168 $cmp = $vector1 <=> $vector2;
169 if ($vector1 < $vector2) # depending on configuration
170 if ($vector1 <= $vector2)
171 if ($vector1 > $vector2)
172 if ($vector1 >= $vector2)
174 $cmp = $vector <=> $scalar;
175 if ($vector < $scalar) # depending on configuration
176 if ($vector <= $scalar)
177 if ($vector > $scalar)
178 if ($vector >= $scalar)
181 if ($vector1 eq $vector2)
182 if ($vector1 ne $vector2)
183 if ($vector eq $scalar)
184 if ($vector ne $scalar)
186 if ($vector1 == $vector2)
187 if ($vector1 != $vector2)
188 if ($vector == $scalar)
189 if ($vector != $scalar)
192 if ($vector1 <= $vector2) # depending on configuration
194 True Subset Relationship
195 if ($vector1 < $vector2) # depending on configuration
197 Superset Relationship
198 if ($vector1 >= $vector2) # depending on configuration
200 True Superset Relationship
201 if ($vector1 > $vector2) # depending on configuration
203 =head1 IMPORTANT NOTES
211 Boolean values in this module are always a numeric zero ("C<0>") for
212 "false" and a numeric one ("C<1>") for "true".
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
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
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).
234 Overloaded operators configuration
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).
240 For instance, scalars (i.e., numbers and strings) provided as operands
241 to overloaded operators are automatically converted to bit vectors,
244 These scalars are thereby automatically assumed to be indices or to be
245 in hexadecimal, binary, decimal or enumeration format, depending on the
248 Similarly, when converting bit vectors to strings using double quotes
249 (""), the output format will also depend on the previously chosen
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.
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.
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).
271 Note that you will get an error message (resulting in program abortion)
272 if your "big integer" numbers exceed that limit.
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.
280 $vector /= 10; # ok because number is small
282 $vector /= -10; # ok for same reason
284 $vector /= "10"; # always correct
286 $vector += "1152921504606846976"; # quotes probably required here
290 Bit::Vector->Configuration("input=decimal");
292 having been set beforehand.
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).
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<->").
302 All other characters produce a syntax error.
306 Valid operands for overloaded operators
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.
312 This is especially true for all unary operators:
325 For obvious reasons the left operand (the "lvalue") of all
326 assignment operators is also required to be a bit vector:
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).
349 In all truly binary operators, i.e.,
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.
373 The same applies to the right side operand (the "rvalue") of the
374 remaining assignment operators, i.e.,
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>"
392 The acceptable scalar types for each possible configuration are
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
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.
405 The only exception from this rule is the concatenation operator
406 ("C<.>") and its assignment variant ("C<.=>"):
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!).
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.
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.
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.
431 If a bit index is out of range for the given bit vector, an "index
432 out of range" error occurs.
434 If a scalar operand cannot be converted successfully due to invalid
435 syntax, a fatal "input string syntax error" is issued.
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.
440 If an operand is neither a bit vector nor a scalar, then a fatal
441 "illegal operand type error" occurs.
447 Note that bit vectors are stored least order bit and least order word first
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.
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.)
456 Note however that machine words can be stored least order byte first or last,
457 depending on your system's implementation.
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.
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).
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).
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.
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.
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.
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
491 The same applies to the corresponding overloaded operators.
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"
509 C<$config = Bit::Vector-E<gt>Configuration();>
513 C<Bit::Vector-E<gt>Configuration($config);>
517 C<$oldconfig = Bit::Vector-E<gt>Configuration($newconfig);>
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).
522 It does not have any effect whatsoever on anything else. In particular,
523 it does not affect the methods implemented in C.
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.
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.
535 There are three aspects of the way certain overloaded operators behave which
536 can be controlled with this method:
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
543 + the operation certain overloaded operators perform,
544 i.e., an operation with sets or an arithmetic
547 + the format to which bit vectors are converted
548 automatically when they are enclosed in double
551 The input string may contain any number of assignments, each of which
552 controls one of these three aspects.
554 Each assignment has the form "C<E<lt>whichE<gt>=E<lt>valueE<gt>>".
556 "C<E<lt>whichE<gt>>" and "C<E<lt>valueE<gt>>" thereby consist of letters
557 (C<[a-zA-Z]>) and white space.
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 ("-").
563 Empty lines or statements (only white space) are allowed but will be
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:
570 + "^scalar", "^input", "^in$"
572 + "^operator", "^semantic", "^ops$"
574 + "^string", "^output", "^out$"
576 The character "^" thereby denotes the beginning of a word, and "$"
577 denotes the end. Case is ignored (!).
579 Using these keywords, you can build any phrase you like to select one
580 of the three aspects (see also examples given below).
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
587 This same principle applies to "C<E<lt>valueE<gt>>":
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:
593 + "<which>" = "^scalar", "^input", "^in$":
597 * "^bit$", "^index", "^indice"
603 + "<which>" = "^operator", "^semantic", "^ops$":
610 + "<which>" = "^string", "^output", "^out$":
621 "Any scalar input I provide should be considered to be = a bit index"
623 "I want to have operator semantics suitable for = arithmetics"
625 "Any bit vector in double quotes is to be output as = an enumeration"
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);>").
634 Note that "bit indices" is the default setting for "scalar input".
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>").
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.)
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).
648 "C<$vector ^= '0101';>", for instance, will flip bit #0 and bit #2.
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>").
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.)
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.
664 B<OPERATOR SEMANTICS:>
666 Several overloaded operators can have two distinct functions depending
669 The affected operators are: "C<+>", "C<->", "C<*>", "C<E<lt>>", "C<E<lt>=>",
670 "C<E<gt>>" and "C<E<gt>=>".
672 With the default setting, "set operations", these operators perform:
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 )
682 With the alternative setting, "arithmetic operations", these operators
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 )
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>.
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).
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).
708 (For conversion to octal, see the description of the method
709 "C<Chunk_List_Read()>".)
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:
714 print "\$vector = '$vector'\n";
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).
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!
725 Therefore you should store the decimal strings returned to you
726 rather than converting a given bit vector again.
730 The default setting as returned by the method "C<Configuration()>"
733 Scalar Input = Bit Index
734 Operator Semantics = Set Operators
735 String Output = Hexadecimal
737 Performing a statement such as:
739 Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
740 print Bit::Vector->Configuration(), "\n";
742 yields the following output:
744 Scalar Input = Binary
745 Operator Semantics = Arithmetic Operators
746 String Output = Binary
748 Note that you can always feed this output back into the "C<Configuration()>"
749 method to restore that setting later.
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).
755 Note further that any aspect you do not specify is not changed, i.e.,
758 Bit::Vector->Configuration("operators = arithmetic");
760 leaves all other aspects unchanged.
766 Remember that variables enclosed in double quotes are always
767 interpolated in Perl.
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.
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
780 This can actually be done by changing the configuration of this
781 module using the method "C<Configure()>" (see the previous chapter,
784 The default is conversion to hexadecimal.
790 It is possible to use a Perl variable containing the reference of a
791 "Bit::Vector" object as a boolean expression.
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.
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.
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
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
817 This term returns a new bit vector object which is the one's complement
818 of the given bit vector.
820 This is equivalent to inverting all bits.
824 C<-$vector> (unary minus)
826 This term returns a new bit vector object which is the two's complement
827 of the given bit vector.
829 This is equivalent to inverting all bits and incrementing the result by one.
831 (This is the same as changing the sign of a number in two's complement
832 binary representation.)
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.
848 C<$vector1 . $vector2>
850 This term usually returns a new bit vector object which is the
851 result of the concatenation of the two bit vector operands.
853 The left operand becomes the most significant, and the right operand
854 becomes the least significant part of the new bit vector object.
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
863 In other words, a string is returned in such a case instead of a
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.
874 If the factor is zero, a bit vector object with a length of zero bits
877 If the factor is one, just a new copy of the given bit vector is
880 Note that a fatal "reversed operands error" occurs if the two operands
885 C<$vector E<lt>E<lt> $bits>
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>",
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.
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.
900 Note that a fatal "reversed operands error" occurs if the two operands
905 C<$vector E<gt>E<gt> $bits>
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>",
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.
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.
920 Note that a fatal "reversed operands error" occurs if the two operands
925 C<$vector1 | $vector2>
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.
930 This is the same as calculating the union of two sets.
934 C<$vector1 & $vector2>
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.
939 This is the same as calculating the intersection of two sets.
943 C<$vector1 ^ $vector2>
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
949 This is the same as calculating the symmetric difference of two sets.
953 C<$vector1 + $vector2>
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.
965 C<$vector1 - $vector2>
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
977 C<$vector1 * $vector2>
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.
989 C<$vector1 / $vector2>
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.
996 C<$vector1 % $vector2>
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.
1003 C<$vector1 ** $vector2>
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
1011 C<$vector1 .= $vector2;>
1013 This statement "appends" the right bit vector operand (the "rvalue")
1014 to the left one (the "lvalue").
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.
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.
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.
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.
1038 C<$vector x= $factor;>
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.
1044 If the factor is zero, the given bit vector is resized to a length of zero
1047 If the factor is one, the given bit vector is not changed at all.
1051 C<$vector E<lt>E<lt>= $bits;>
1053 This statement moves the contents of the given bit vector left by "C<$bits>"
1054 positions (towards the most significant bit).
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.
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).
1065 C<$vector E<gt>E<gt>= $bits;>
1067 This statement moves the contents of the given bit vector right by "C<$bits>"
1068 positions (towards the least significant bit).
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.
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).
1079 C<$vector1 |= $vector2;>
1081 This statement performs a bitwise OR operation between the two
1082 bit vector operands and stores the result in the left operand.
1084 This is the same as calculating the union of two sets.
1088 C<$vector1 &= $vector2;>
1090 This statement performs a bitwise AND operation between the two
1091 bit vector operands and stores the result in the left operand.
1093 This is the same as calculating the intersection of two sets.
1097 C<$vector1 ^= $vector2;>
1099 This statement performs a bitwise XOR (exclusive-or) operation
1100 between the two bit vector operands and stores the result in the
1103 This is the same as calculating the symmetric difference of two sets.
1107 C<$vector1 += $vector2;>
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.
1116 The result of this operation is stored in the left operand.
1120 C<$vector1 -= $vector2;>
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.
1128 The result of this operation is stored in the left operand.
1132 C<$vector1 *= $vector2;>
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.
1141 The result of this operation is stored in the left operand.
1145 C<$vector1 /= $vector2;>
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.
1152 C<$vector1 %= $vector2;>
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.
1159 C<$vector1 **= $vector2;>
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.
1166 C<++$vector>, C<$vector++>
1168 This operator performs pre- and post-incrementation of the
1171 The value returned by this term is a reference of the given
1172 bit vector object (after or before the incrementation,
1177 C<--$vector>, C<$vector-->
1179 This operator performs pre- and post-decrementation of the
1182 The value returned by this term is a reference of the given
1183 bit vector object (after or before the decrementation,
1188 C<($vector1 cmp $vector2)>
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>".
1194 This comparison assumes B<UNSIGNED> bit vectors.
1198 C<($vector1 eq $vector2)>
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.
1205 C<($vector1 ne $vector2)>
1207 This term returns true ("C<1>") if the two bit vector operands differ
1208 and false ("C<0>") otherwise.
1212 C<($vector1 lt $vector2)>
1214 This term returns true ("C<1>") if "C<$vector1>" is less than "C<$vector2>",
1215 and false ("C<0>") otherwise.
1217 This comparison assumes B<UNSIGNED> bit vectors.
1221 C<($vector1 le $vector2)>
1223 This term returns true ("C<1>") if "C<$vector1>" is less than or equal to
1224 "C<$vector2>", and false ("C<0>") otherwise.
1226 This comparison assumes B<UNSIGNED> bit vectors.
1230 C<($vector1 gt $vector2)>
1232 This term returns true ("C<1>") if "C<$vector1>" is greater than "C<$vector2>",
1233 and false ("C<0>") otherwise.
1235 This comparison assumes B<UNSIGNED> bit vectors.
1239 C<($vector1 ge $vector2)>
1241 This term returns true ("C<1>") if "C<$vector1>" is greater than or equal to
1242 "C<$vector2>", and false ("C<0>") otherwise.
1244 This comparison assumes B<UNSIGNED> bit vectors.
1248 C<($vector1 E<lt>=E<gt> $vector2)>
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>".
1254 This comparison assumes B<SIGNED> bit vectors.
1258 C<($vector1 == $vector2)>
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.
1265 C<($vector1 != $vector2)>
1267 This term returns true ("C<1>") if the two bit vector operands differ
1268 and false ("C<0>") otherwise.
1272 C<($vector1 E<lt> $vector2)>
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).
1281 The latter comparison assumes B<SIGNED> bit vectors.
1285 C<($vector1 E<lt>= $vector2)>
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).
1294 The latter comparison assumes B<SIGNED> bit vectors.
1298 C<($vector1 E<gt> $vector2)>
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).
1307 The latter comparison assumes B<SIGNED> bit vectors.
1311 C<($vector1 E<gt>= $vector2)>
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).
1320 The latter comparison assumes B<SIGNED> bit vectors.
1326 Bit::Vector(3), Bit::Vector::String(3).
1330 This man page documents "Bit::Vector::Overload" version 6.4.
1335 mailto:sb@engelschall.com
1336 http://www.engelschall.com/u/sb/download/
1340 Copyright (c) 2000 - 2004 by Steffen Beyer. All rights reserved.
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".
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".
1352 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
1353 "GNU_LGPL.txt" in this distribution for details!
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.
1361 See the "GNU General Public License" for more details.