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""
211 operators) and bit numbers are always regarded as being UNSIGNED.
212 As a consequence, whenever you pass a negative number for such a
214 factor or bit number, it will be treated as a (usually very large)
215 positive number due to its internal two's complement binary
216 representation, usually resulting in malfunctions or an "index out of
217 range" 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 (for
227 more details, see the description of this method further below).
228 For instance, scalars (i.e., numbers and strings) provided as
230 operands to overloaded operators are automatically converted to bit
231 vectors, 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
261 abortion) 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"
290 constant 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
334 operand 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
358 number 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 "Configuration()"
400 method), which is then concatenated in the proper order (i.e., as
401 indicated by the order of the two operands) with the Perl scalar (in
402 other words, a string is returned in such a case instead of a bit
403 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
407 converted internally to a bit vector of the same size as the left
408 side operand provided that the configuration states that scalars are
409 to be regarded as indices, decimal strings or enumerations.
410 If the configuration states that scalars are to be regarded as
412 hexadecimal or boolean strings, however, these strings are converted
413 to bit vectors of a size matching the length of the input string,
414 i.e., four times the length for hexadecimal strings (because each
415 hexadecimal digit is worth 4 bits) and once the length for binary
416 strings.
417 If a decimal number ("big integer") is too large to be stored in a
419 bit vector of the given size, a "numeric overflow error" occurs.
420 If a bit index is out of range for the given bit vector, an "index
422 out of range" error occurs.
423 If a scalar operand cannot be converted successfully due to invalid
425 syntax, a fatal "input string syntax error" is issued.
426 If the two operands of the operator ""<<"", "">>"" or ""x"" are
428 reversed, a fatal "reversed operands error" occurs.
429 If an operand is neither a bit vector nor a scalar, then a fatal
431 "illegal operand type error" occurs.
432 • Bit order
434 Note that bit vectors are stored least order bit and least order word
436 first internally.
437 I.e., bit #0 of any given bit vector corresponds to bit #0 of word #0
439 in the array of machine words representing the bit vector.
440 (Where word #0 comes first in memory, i.e., it is stored at the least
442 memory address in the allocated block of memory holding the given bit
443 vector.)
444 Note however that machine words can be stored least order byte first
446 or last, depending on your system's implementation.
447 Note further that whenever bit vectors are converted to and from
449 (binary or hexadecimal) strings, the RIGHTMOST bit is always the
450 LEAST SIGNIFICANT one, and the LEFTMOST bit is always the MOST
451 SIGNIFICANT bit.
452 This is because in our western culture, numbers are always
454 represented in this way (least significant to most significant digits
455 go from right to left).
456 Of course this requires an internal reversion of order, which the
458 corresponding conversion methods perform automatically (without any
459 additional overhead, it's just a matter of starting the internal loop
460 at the bottom or the top end).
461 • Matching sizes
463 In general, for methods involving several bit vectors at the same
465 time, all bit vector arguments must have identical sizes (number of
466 bits), or a fatal "size mismatch" error will occur.
467 Exceptions from this rule are the methods "Concat()",
469 "Concat_List()", "Copy()", "Interval_Copy()" and
470 "Interval_Substitute()", where no conditions at all are imposed on
471 the size of their bit vector arguments.
472 In method "Multiply()", all three bit vector arguments must in
474 principle obey the rule of matching sizes, but the bit vector in
475 which the result of the multiplication is to be stored may be larger
476 than the two bit vector arguments containing the factors for the
477 multiplication.
478 In method "Power()", the bit vector for the result must be the same
480 size or greater than the base of the exponentiation term. The
481 exponent can be any size.
482 The same applies to the corresponding overloaded operators.
484 • Index ranges
486 All indices for any given bits must lie between "0" and
488 ""$vector->Size()-1"", or a fatal "index out of range" error will
489 occur.
490
492 • "$config = Bit::Vector->Configuration();"
493 • "Bit::Vector->Configuration($config);"
495 • "$oldconfig = Bit::Vector->Configuration($newconfig);"
497 This method serves to alter the semantics (i.e., behaviour) of
499 certain overloaded operators (which are all implemented in Perl, by
500 the way).
501 It does not have any effect whatsoever on anything else. In
503 particular, it does not affect the methods implemented in C.
504 The method accepts an (optional) string as input in which certain
506 keywords are expected, which influence some or almost all of the
507 overloaded operators in several possible ways.
508 The method always returns a string (which you do not need to take
510 care of, i.e., to store, in case you aren't interested in keeping it)
511 which is a complete representation of the current configuration
512 (i.e., BEFORE any modifications are applied) and which can be fed
513 back to this method later in order to restore the previous
514 configuration.
515 There are three aspects of the way certain overloaded operators
517 behave which can be controlled with this method:
518 + the way scalar operands (replacing one of the two
520 bit vector object operands) are automatically
521 converted internally into a bit vector object of
522 their own,
523 + the operation certain overloaded operators perform,
525 i.e., an operation with sets or an arithmetic
526 operation,
527 + the format to which bit vectors are converted
529 automatically when they are enclosed in double
530 quotes.
531 The input string may contain any number of assignments, each of which
533 controls one of these three aspects.
534 Each assignment has the form ""<which>=<value>"".
536 ""<which>"" and ""<value>"" thereby consist of letters ("[a-zA-Z]")
538 and white space.
539 Multiple assignments have to be separated by one or more comma (","),
541 semi-colon (";"), colon (":"), vertical bar ("|"), slash ("/"),
542 newline ("\n"), ampersand ("&"), plus ("+") or dash ("-").
543 Empty lines or statements (only white space) are allowed but will be
545 ignored.
546 ""<which>"" has to contain one or more keywords from one of three
548 groups, each group representing one of the three aspects that the
549 "Configuration()" method controls:
550 + "^scalar", "^input", "^in$"
552 + "^operator", "^semantic", "^ops$"
554 + "^string", "^output", "^out$"
556 The character "^" thereby denotes the beginning of a word, and "$"
558 denotes the end. Case is ignored (!).
559 Using these keywords, you can build any phrase you like to select one
561 of the three aspects (see also examples given below).
562 The only condition is that no other keyword from any of the other two
564 groups may match - otherwise a syntax error will occur (i.e.,
565 ambiguities are forbidden). A syntax error also occurs if none of the
566 keywords matches.
567 This same principle applies to ""<value>"":
569 Depending on which aspect you specified for ""<which>"", there are
571 different groups of keywords that determine the value the selected
572 aspect will be set to:
573 + "<which>" = "^scalar", "^input", "^in$":
575 "<value>" =
577 * "^bit$", "^index", "^indice"
579 * "^hex"
580 * "^bin"
581 * "^dec"
582 * "^enum"
583 + "<which>" = "^operator", "^semantic", "^ops$":
585 "<value>" =
587 * "^set$"
589 * "^arithmetic"
590 + "<which>" = "^string", "^output", "^out$":
592 "<value>" =
594 * "^hex"
596 * "^bin"
597 * "^dec"
598 * "^enum"
599 Examples:
601 "Any scalar input I provide should be considered to be = a bit index"
603 "I want to have operator semantics suitable for = arithmetics"
605 "Any bit vector in double quotes is to be output as = an enumeration"
607 SCALAR INPUT:
609 In the case of scalar input, ""^bit$"", ""^index"", or ""^indice""
611 all cause scalar input to be considered to represent a bit index,
612 i.e., ""$vector ^= 5;"" will flip bit #5 in the given bit vector
613 (this is essentially the same as ""$vector->bit_flip(5);"").
614 Note that "bit indices" is the default setting for "scalar input".
616 The keyword ""^hex"" will cause scalar input to be considered as
618 being in hexadecimal, i.e., ""$vector ^= 5;"" will flip bit #0 and
619 bit #2 (because hexadecimal "5" is binary "0101").
620 (Note though that hexadecimal input should always be enclosed in
622 quotes, otherwise it will be interpreted as a decimal number by Perl!
623 The example relies on the fact that hexadecimal "0-9" and decimal
624 "0-9" are the same.)
625 The keyword ""^bin"" will cause scalar input to be considered as
627 being in binary format. All characters except "0" and "1" are
628 forbidden in this case (i.e., produce a syntax error).
629 ""$vector ^= '0101';"", for instance, will flip bit #0 and bit #2.
631 The keyword ""^dec"" causes scalar input to be considered as integers
633 in decimal format, i.e., ""$vector ^= 5;"" will flip bit #0 and bit
634 #2 (because decimal "5" is binary "0101").
635 (Note though that all decimal input should be enclosed in quotes,
637 because for large numbers, Perl will use scientific notation
638 internally for representing them, which produces a syntax error
639 because scientific notation is neither supported by this module nor
640 needed.)
641 Finally, the keyword ""^enum"" causes scalar input to be considered
643 as being a list ("enumeration") of indices and ranges of (contiguous)
644 indices, i.e., ""$vector |= '2,3,5,7-13,17-23';"" will cause bits #2,
645 #3, #5, #7 through #13 and #17 through #23 to be set.
646 OPERATOR SEMANTICS:
648 Several overloaded operators can have two distinct functions
650 depending on this setting.
651 The affected operators are: ""+"", ""-"", ""*"", ""<"", ""<="", "">""
653 and "">="".
654 With the default setting, "set operations", these operators perform:
656 + set union ( set1 u set2 )
658 - set difference ( set1 \ set2 )
659 * set intersection ( set1 n set2 )
660 < true subset relationship ( set1 < set2 )
661 <= subset relationship ( set1 <= set2 )
662 > true superset relationship ( set1 > set2 )
663 >= superset relationship ( set1 >= set2 )
664 With the alternative setting, "arithmetic operations", these
666 operators perform:
667 + addition ( num1 + num2 )
669 - subtraction ( num1 - num2 )
670 * multiplication ( num1 * num2 )
671 < "less than" comparison ( num1 < num2 )
672 <= "less than or equal" comparison ( num1 <= num2 )
673 > "greater than" comparison ( num1 > num2 )
674 >= "greater than or equal" comparison ( num1 >= num2 )
675 Note that these latter comparison operators (""<"", ""<="", "">"" and
677 "">="") regard their operands as being SIGNED.
678 To perform comparisons with UNSIGNED operands, use the operators
680 ""lt"", ""le"", ""gt"" and ""ge"" instead (in contrast to the
681 operators above, these operators are NOT affected by the "operator
682 semantics" setting).
683 STRING OUTPUT:
685 There are four methods which convert the contents of a given bit
687 vector into a string: "to_Hex()", "to_Bin()", "to_Dec()" and
688 "to_Enum()" (not counting "Block_Read()", since this method does not
689 return a human-readable string).
690 (For conversion to octal, see the description of the method
692 "Chunk_List_Read()".)
693 Therefore, there are four possible formats into which a bit vector
695 can be converted when it is enclosed in double quotes, for example:
696 print "\$vector = '$vector'\n";
698 $string = "$vector";
699 Hence you can set "string output" to four different values: To "hex"
701 for hexadecimal format (which is the default), to "bin" for binary
702 format, to "dec" for conversion to decimal numbers and to "enum" for
703 conversion to enumerations (".newsrc" style sets).
704 BEWARE that the conversion to decimal numbers is inherently slow; it
706 can easily take up several seconds for a single large bit vector!
707 Therefore you should store the decimal strings returned to you rather
709 than converting a given bit vector again.
710 EXAMPLES:
712 The default setting as returned by the method "Configuration()" is:
714 Scalar Input = Bit Index
716 Operator Semantics = Set Operators
717 String Output = Hexadecimal
718 Performing a statement such as:
720 Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
722 print Bit::Vector->Configuration(), "\n";
723 yields the following output:
725 Scalar Input = Binary
727 Operator Semantics = Arithmetic Operators
728 String Output = Binary
729 Note that you can always feed this output back into the
731 "Configuration()" method to restore that setting later.
732 This also means that you can enter the same given setting with almost
734 any degree of verbosity you like (as long as the required keywords
735 appear and no ambiguities arise).
736 Note further that any aspect you do not specify is not changed, i.e.,
738 the statement
739 Bit::Vector->Configuration("operators = arithmetic");
741 leaves all other aspects unchanged.
743 • "$vector"
745 Remember that variables enclosed in double quotes are always
747 interpolated in Perl.
748 Whenever a Perl variable containing the reference of a "Bit::Vector"
750 object is enclosed in double quotes (either alone or together with
751 other text and/or variables), the contents of the corresponding bit
752 vector are converted into a printable string.
753 Since there are several conversion methods available in this module
755 (see the description of the methods "to_Hex()", "to_Bin()",
756 "to_Dec()" and "to_Enum()"), it is of course desirable to be able to
757 choose which of these methods should be applied in this case.
758 This can actually be done by changing the configuration of this
760 module using the method "Configure()" (see the previous chapter,
761 immediately above).
762 The default is conversion to hexadecimal.
764 • "if ($vector)"
766 It is possible to use a Perl variable containing the reference of a
768 "Bit::Vector" object as a boolean expression.
769 The condition above is true if the corresponding bit vector contains
771 at least one set bit, and it is false if ALL bits of the
772 corresponding bit vector are cleared.
773 • "if (!$vector)"
775 Since it is possible to use a Perl variable containing the reference
777 of a "Bit::Vector" object as a boolean expression, you can of course
778 also negate this boolean expression.
779 The condition above is true if ALL bits of the corresponding bit
781 vector are cleared, and it is false if the corresponding bit vector
782 contains at least one set bit.
783 Note that this is NOT the same as using the method "is_full()", which
785 returns true if ALL bits of the corresponding bit vector are SET.
786 • "~$vector"
788 This term returns a new bit vector object which is the one's
790 complement of the given bit vector.
791 This is equivalent to inverting all bits.
793 • "-$vector" (unary minus)
795 This term returns a new bit vector object which is the two's
797 complement of the given bit vector.
798 This is equivalent to inverting all bits and incrementing the result
800 by one.
801 (This is the same as changing the sign of a number in two's
803 complement binary representation.)
804 • abs($vector)
806 Depending on the configuration (see the description of the method
808 "Configuration()" for more details), this term either returns the
809 number of set bits in the given bit vector (this is the same as
810 calculating the number of elements which are contained in the given
811 set) - which is the default behaviour, or it returns a new bit vector
812 object which contains the absolute value of the number stored in the
813 given bit vector.
814 • "$vector1 . $vector2"
816 This term usually returns a new bit vector object which is the result
818 of the concatenation of the two bit vector operands.
819 The left operand becomes the most significant, and the right operand
821 becomes the least significant part of the new bit vector object.
822 If one of the two operands is not a bit vector object but a Perl
824 scalar, however, the contents of the remaining bit vector operand are
825 converted into a string (the format of which depends on the
826 configuration set with the "Configuration()" method), which is then
827 concatenated in the proper order (i.e., as indicated by the order of
828 the two operands) with the Perl scalar.
829 In other words, a string is returned in such a case instead of a bit
831 vector object!
832 • "$vector x $factor"
834 This term returns a new bit vector object which is the concatenation
836 of as many copies of the given bit vector operand (the left operand)
837 as the factor (the right operand) specifies.
838 If the factor is zero, a bit vector object with a length of zero bits
840 is returned.
841 If the factor is one, just a new copy of the given bit vector is
843 returned.
844 Note that a fatal "reversed operands error" occurs if the two
846 operands are swapped.
847 • "$vector << $bits"
849 This term returns a new bit vector object which is a copy of the
851 given bit vector (the left operand), which is then shifted left
852 (towards the most significant bit) by as many places as the right
853 operand, "$bits", specifies.
854 This means that the "$bits" most significant bits are lost, all other
856 bits move up by "$bits" positions, and the "$bits" least significant
857 bits that have been left unoccupied by this shift are all set to
858 zero.
859 If "$bits" is greater than the number of bits of the given bit
861 vector, this term returns an empty bit vector (i.e., with all bits
862 cleared) of the same size as the given bit vector.
863 Note that a fatal "reversed operands error" occurs if the two
865 operands are swapped.
866 • "$vector >> $bits"
868 This term returns a new bit vector object which is a copy of the
870 given bit vector (the left operand), which is then shifted right
871 (towards the least significant bit) by as many places as the right
872 operand, "$bits", specifies.
873 This means that the "$bits" least significant bits are lost, all
875 other bits move down by "$bits" positions, and the "$bits" most
876 significant bits that have been left unoccupied by this shift are all
877 set to zero.
878 If "$bits" is greater than the number of bits of the given bit
880 vector, this term returns an empty bit vector (i.e., with all bits
881 cleared) of the same size as the given bit vector.
882 Note that a fatal "reversed operands error" occurs if the two
884 operands are swapped.
885 • "$vector1 | $vector2"
887 This term returns a new bit vector object which is the result of a
889 bitwise OR operation between the two bit vector operands.
890 This is the same as calculating the union of two sets.
892 • "$vector1 & $vector2"
894 This term returns a new bit vector object which is the result of a
896 bitwise AND operation between the two bit vector operands.
897 This is the same as calculating the intersection of two sets.
899 • "$vector1 ^ $vector2"
901 This term returns a new bit vector object which is the result of a
903 bitwise XOR (exclusive-or) operation between the two bit vector
904 operands.
905 This is the same as calculating the symmetric difference of two sets.
907 • "$vector1 + $vector2"
909 Depending on the configuration (see the description of the method
911 "Configuration()" for more details), this term either returns a new
912 bit vector object which is the result of a bitwise OR operation
913 between the two bit vector operands (this is the same as calculating
914 the union of two sets) - which is the default behaviour, or it
915 returns a new bit vector object which contains the sum of the two
916 numbers stored in the two bit vector operands.
917 • "$vector1 - $vector2"
919 Depending on the configuration (see the description of the method
921 "Configuration()" for more details), this term either returns a new
922 bit vector object which is the set difference of the two sets
923 represented in the two bit vector operands - which is the default
924 behaviour, or it returns a new bit vector object which contains the
925 difference of the two numbers stored in the two bit vector operands.
926 • "$vector1 * $vector2"
928 Depending on the configuration (see the description of the method
930 "Configuration()" for more details), this term either returns a new
931 bit vector object which is the result of a bitwise AND operation
932 between the two bit vector operands (this is the same as calculating
933 the intersection of two sets) - which is the default behaviour, or it
934 returns a new bit vector object which contains the product of the two
935 numbers stored in the two bit vector operands.
936 • "$vector1 / $vector2"
938 This term returns a new bit vector object containing the result of
940 the division of the two numbers stored in the two bit vector
941 operands.
942 • "$vector1 % $vector2"
944 This term returns a new bit vector object containing the remainder of
946 the division of the two numbers stored in the two bit vector
947 operands.
948 • "$vector1 ** $vector2"
950 This term returns a new bit vector object containing the result of
952 the exponentiation of the left bit vector elevated to the right bit
953 vector's power.
954 • "$vector1 .= $vector2;"
956 This statement "appends" the right bit vector operand (the "rvalue")
958 to the left one (the "lvalue").
959 The former contents of the left operand become the most significant
961 part of the resulting bit vector, and the right operand becomes the
962 least significant part.
963 Since bit vectors are stored in "least order bit first" order, this
965 actually requires the left operand to be shifted "up" by the length
966 of the right operand, which is then copied to the now freed least
967 significant part of the left operand.
968 If the right operand is a Perl scalar, it is first converted to a bit
970 vector of the same size as the left operand, provided that the
971 configuration states that scalars are to be regarded as indices,
972 decimal strings or enumerations.
973 If the configuration states that scalars are to be regarded as
975 hexadecimal or boolean strings, however, these strings are converted
976 to bit vectors of a size matching the length of the input string,
977 i.e., four times the length for hexadecimal strings (because each
978 hexadecimal digit is worth 4 bits) and once the length for binary
979 strings.
980 • "$vector x= $factor;"
982 This statement replaces the given bit vector by a concatenation of as
984 many copies of the original contents of the given bit vector as the
985 factor (the right operand) specifies.
986 If the factor is zero, the given bit vector is resized to a length of
988 zero bits.
989 If the factor is one, the given bit vector is not changed at all.
991 • "$vector <<= $bits;"
993 This statement moves the contents of the given bit vector left by
995 "$bits" positions (towards the most significant bit).
996 This means that the "$bits" most significant bits are lost, all other
998 bits move up by "$bits" positions, and the "$bits" least significant
999 bits that have been left unoccupied by this shift are all set to
1000 zero.
1001 If "$bits" is greater than the number of bits of the given bit
1003 vector, the given bit vector is erased completely (i.e., all bits are
1004 cleared).
1005 • "$vector >>= $bits;"
1007 This statement moves the contents of the given bit vector right by
1009 "$bits" positions (towards the least significant bit).
1010 This means that the "$bits" least significant bits are lost, all
1012 other bits move down by "$bits" positions, and the "$bits" most
1013 significant bits that have been left unoccupied by this shift are all
1014 set to zero.
1015 If "$bits" is greater than the number of bits of the given bit
1017 vector, the given bit vector is erased completely (i.e., all bits are
1018 cleared).
1019 • "$vector1 |= $vector2;"
1021 This statement performs a bitwise OR operation between the two bit
1023 vector operands and stores the result in the left operand.
1024 This is the same as calculating the union of two sets.
1026 • "$vector1 &= $vector2;"
1028 This statement performs a bitwise AND operation between the two bit
1030 vector operands and stores the result in the left operand.
1031 This is the same as calculating the intersection of two sets.
1033 • "$vector1 ^= $vector2;"
1035 This statement performs a bitwise XOR (exclusive-or) operation
1037 between the two bit vector operands and stores the result in the left
1038 operand.
1039 This is the same as calculating the symmetric difference of two sets.
1041 • "$vector1 += $vector2;"
1043 Depending on the configuration (see the description of the method
1045 "Configuration()" for more details), this statement either performs a
1046 bitwise OR operation between the two bit vector operands (this is the
1047 same as calculating the union of two sets) - which is the default
1048 behaviour, or it calculates the sum of the two numbers stored in the
1049 two bit vector operands.
1050 The result of this operation is stored in the left operand.
1052 • "$vector1 -= $vector2;"
1054 Depending on the configuration (see the description of the method
1056 "Configuration()" for more details), this statement either calculates
1057 the set difference of the two sets represented in the two bit vector
1058 operands - which is the default behaviour, or it calculates the
1059 difference of the two numbers stored in the two bit vector operands.
1060 The result of this operation is stored in the left operand.
1062 • "$vector1 *= $vector2;"
1064 Depending on the configuration (see the description of the method
1066 "Configuration()" for more details), this statement either performs a
1067 bitwise AND operation between the two bit vector operands (this is
1068 the same as calculating the intersection of two sets) - which is the
1069 default behaviour, or it calculates the product of the two numbers
1070 stored in the two bit vector operands.
1071 The result of this operation is stored in the left operand.
1073 • "$vector1 /= $vector2;"
1075 This statement puts the result of the division of the two numbers
1077 stored in the two bit vector operands into the left operand.
1078 • "$vector1 %= $vector2;"
1080 This statement puts the remainder of the division of the two numbers
1082 stored in the two bit vector operands into the left operand.
1083 • "$vector1 **= $vector2;"
1085 This statement puts the result of the exponentiation of the left
1087 operand elevated to the right operand's power into the left operand.
1088 • "++$vector", "$vector++"
1090 This operator performs pre- and post-incrementation of the given bit
1092 vector.
1093 The value returned by this term is a reference of the given bit
1095 vector object (after or before the incrementation, respectively).
1096 • "--$vector", "$vector--"
1098 This operator performs pre- and post-decrementation of the given bit
1100 vector.
1101 The value returned by this term is a reference of the given bit
1103 vector object (after or before the decrementation, respectively).
1104 • "($vector1 cmp $vector2)"
1106 This term returns "-1" if "$vector1" is less than "$vector2", "0" if
1108 "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1109 greater than "$vector2".
1110 This comparison assumes UNSIGNED bit vectors.
1112 • "($vector1 eq $vector2)"
1114 This term returns true ("1") if the contents of the two bit vector
1116 operands are the same and false ("0") otherwise.
1117 • "($vector1 ne $vector2)"
1119 This term returns true ("1") if the two bit vector operands differ
1121 and false ("0") otherwise.
1122 • "($vector1 lt $vector2)"
1124 This term returns true ("1") if "$vector1" is less than "$vector2",
1126 and false ("0") otherwise.
1127 This comparison assumes UNSIGNED bit vectors.
1129 • "($vector1 le $vector2)"
1131 This term returns true ("1") if "$vector1" is less than or equal to
1133 "$vector2", and false ("0") otherwise.
1134 This comparison assumes UNSIGNED bit vectors.
1136 • "($vector1 gt $vector2)"
1138 This term returns true ("1") if "$vector1" is greater than
1140 "$vector2", and false ("0") otherwise.
1141 This comparison assumes UNSIGNED bit vectors.
1143 • "($vector1 ge $vector2)"
1145 This term returns true ("1") if "$vector1" is greater than or equal
1147 to "$vector2", and false ("0") otherwise.
1148 This comparison assumes UNSIGNED bit vectors.
1150 • "($vector1 <=> $vector2)"
1152 This term returns "-1" if "$vector1" is less than "$vector2", "0" if
1154 "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1155 greater than "$vector2".
1156 This comparison assumes SIGNED bit vectors.
1158 • "($vector1 == $vector2)"
1160 This term returns true ("1") if the contents of the two bit vector
1162 operands are the same and false ("0") otherwise.
1163 • "($vector1 != $vector2)"
1165 This term returns true ("1") if the two bit vector operands differ
1167 and false ("0") otherwise.
1168 • "($vector1 < $vector2)"
1170 Depending on the configuration (see the description of the method
1172 "Configuration()" for more details), this term either returns true
1173 ("1") if "$vector1" is a true subset of "$vector2" (and false ("0")
1174 otherwise) - which is the default behaviour, or it returns true ("1")
1175 if "$vector1" is less than "$vector2" (and false ("0") otherwise).
1176 The latter comparison assumes SIGNED bit vectors.
1178 • "($vector1 <= $vector2)"
1180 Depending on the configuration (see the description of the method
1182 "Configuration()" for more details), this term either returns true
1183 ("1") if "$vector1" is a subset of "$vector2" (and false ("0")
1184 otherwise) - which is the default behaviour, or it returns true ("1")
1185 if "$vector1" is less than or equal to "$vector2" (and false ("0")
1186 otherwise).
1187 The latter comparison assumes SIGNED bit vectors.
1189 • "($vector1 > $vector2)"
1191 Depending on the configuration (see the description of the method
1193 "Configuration()" for more details), this term either returns true
1194 ("1") if "$vector1" is a true superset of "$vector2" (and false ("0")
1195 otherwise) - which is the default behaviour, or it returns true ("1")
1196 if "$vector1" is greater than "$vector2" (and false ("0") otherwise).
1197 The latter comparison assumes SIGNED bit vectors.
1199 • "($vector1 >= $vector2)"
1201 Depending on the configuration (see the description of the method
1203 "Configuration()" for more details), this term either returns true
1204 ("1") if "$vector1" is a superset of "$vector2" (and false ("0")
1205 otherwise) - which is the default behaviour, or it returns true ("1")
1206 if "$vector1" is greater than or equal to "$vector2" (and false ("0")
1207 otherwise).
1208 The latter comparison assumes SIGNED bit vectors.
1210
1212 Bit::Vector(3), Bit::Vector::String(3).
1213
1215 This man page documents "Bit::Vector::Overload" version 7.4.
1216
1218 Steffen Beyer
1219 mailto:STBEY@cpan.org
1220 http://www.engelschall.com/u/sb/download/
1221
1223 Copyright (c) 2000 - 2013 by Steffen Beyer. All rights reserved.
1224
1226 This package is free software; you can redistribute it and/or modify it
1227 under the same terms as Perl itself, i.e., under the terms of the
1228 "Artistic License" or the "GNU General Public License".
1229 The C library at the core of this Perl module can additionally be
1231 redistributed and/or modified under the terms of the "GNU Library
1232 General Public License".
1233 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
1235 "GNU_LGPL.txt" in this distribution for details!
1236
1238 This package is distributed in the hope that it will be useful, but
1239 WITHOUT ANY WARRANTY; without even the implied warranty of
1240 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1241 See the "GNU General Public License" for more details.
1243perl v5.36.0 2023-01-20 Bit::Vector::Overload(3)