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
227 (for 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
400 ""Configuration()"" method), which is then concatenated in the proper
401 order (i.e., as indicated by the order of the two operands) with the
402 Perl scalar (in other words, a string is returned in such a case
403 instead 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
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
689 not 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
757 to 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()"",
785 which returns true if ALL bits of the corresponding bit vector are
786 SET.
787 · "~$vector"
789 This term returns a new bit vector object which is the one's
791 complement of the given bit vector.
792 This is equivalent to inverting all bits.
794 · "-$vector" (unary minus)
796 This term returns a new bit vector object which is the two's
798 complement of the given bit vector.
799 This is equivalent to inverting all bits and incrementing the result
801 by one.
802 (This is the same as changing the sign of a number in two's
804 complement binary representation.)
805 · "abs($vector)"
807 Depending on the configuration (see the description of the method
809 ""Configuration()"" for more details), this term either returns the
810 number of set bits in the given bit vector (this is the same as
811 calculating the number of elements which are contained in the given
812 set) - which is the default behaviour, or it returns a new bit vector
813 object which contains the absolute value of the number stored in the
814 given bit vector.
815 · "$vector1 . $vector2"
817 This term usually returns a new bit vector object which is the result
819 of the concatenation of the two bit vector operands.
820 The left operand becomes the most significant, and the right operand
822 becomes the least significant part of the new bit vector object.
823 If one of the two operands is not a bit vector object but a Perl
825 scalar, however, the contents of the remaining bit vector operand are
826 converted into a string (the format of which depends on the
827 configuration set with the ""Configuration()"" method), which is then
828 concatenated in the proper order (i.e., as indicated by the order of
829 the two operands) with the Perl scalar.
830 In other words, a string is returned in such a case instead of a bit
832 vector object!
833 · "$vector x $factor"
835 This term returns a new bit vector object which is the concatenation
837 of as many copies of the given bit vector operand (the left operand)
838 as the factor (the right operand) specifies.
839 If the factor is zero, a bit vector object with a length of zero bits
841 is returned.
842 If the factor is one, just a new copy of the given bit vector is
844 returned.
845 Note that a fatal "reversed operands error" occurs if the two
847 operands are swapped.
848 · "$vector << $bits"
850 This term returns a new bit vector object which is a copy of the
852 given bit vector (the left operand), which is then shifted left
853 (towards the most significant bit) by as many places as the right
854 operand, "$bits", specifies.
855 This means that the "$bits" most significant bits are lost, all other
857 bits move up by "$bits" positions, and the "$bits" least significant
858 bits that have been left unoccupied by this shift are all set to
859 zero.
860 If "$bits" is greater than the number of bits of the given bit
862 vector, this term returns an empty bit vector (i.e., with all bits
863 cleared) of the same size as the given bit vector.
864 Note that a fatal "reversed operands error" occurs if the two
866 operands are swapped.
867 · "$vector >> $bits"
869 This term returns a new bit vector object which is a copy of the
871 given bit vector (the left operand), which is then shifted right
872 (towards the least significant bit) by as many places as the right
873 operand, "$bits", specifies.
874 This means that the "$bits" least significant bits are lost, all
876 other bits move down by "$bits" positions, and the "$bits" most
877 significant bits that have been left unoccupied by this shift are all
878 set to zero.
879 If "$bits" is greater than the number of bits of the given bit
881 vector, this term returns an empty bit vector (i.e., with all bits
882 cleared) of the same size as the given bit vector.
883 Note that a fatal "reversed operands error" occurs if the two
885 operands are swapped.
886 · "$vector1 | $vector2"
888 This term returns a new bit vector object which is the result of a
890 bitwise OR operation between the two bit vector operands.
891 This is the same as calculating the union of two sets.
893 · "$vector1 & $vector2"
895 This term returns a new bit vector object which is the result of a
897 bitwise AND operation between the two bit vector operands.
898 This is the same as calculating the intersection of two sets.
900 · "$vector1 ^ $vector2"
902 This term returns a new bit vector object which is the result of a
904 bitwise XOR (exclusive-or) operation between the two bit vector
905 operands.
906 This is the same as calculating the symmetric difference of two sets.
908 · "$vector1 + $vector2"
910 Depending on the configuration (see the description of the method
912 ""Configuration()"" for more details), this term either returns a new
913 bit vector object which is the result of a bitwise OR operation
914 between the two bit vector operands (this is the same as calculating
915 the union of two sets) - which is the default behaviour, or it
916 returns a new bit vector object which contains the sum of the two
917 numbers stored in the two bit vector operands.
918 · "$vector1 - $vector2"
920 Depending on the configuration (see the description of the method
922 ""Configuration()"" for more details), this term either returns a new
923 bit vector object which is the set difference of the two sets
924 represented in the two bit vector operands - which is the default
925 behaviour, or it returns a new bit vector object which contains the
926 difference of the two numbers stored in the two bit vector operands.
927 · "$vector1 * $vector2"
929 Depending on the configuration (see the description of the method
931 ""Configuration()"" for more details), this term either returns a new
932 bit vector object which is the result of a bitwise AND operation
933 between the two bit vector operands (this is the same as calculating
934 the intersection of two sets) - which is the default behaviour, or it
935 returns a new bit vector object which contains the product of the two
936 numbers stored in the two bit vector operands.
937 · "$vector1 / $vector2"
939 This term returns a new bit vector object containing the result of
941 the division of the two numbers stored in the two bit vector
942 operands.
943 · "$vector1 % $vector2"
945 This term returns a new bit vector object containing the remainder of
947 the division of the two numbers stored in the two bit vector
948 operands.
949 · "$vector1 ** $vector2"
951 This term returns a new bit vector object containing the result of
953 the exponentiation of the left bit vector elevated to the right bit
954 vector's power.
955 · "$vector1 .= $vector2;"
957 This statement "appends" the right bit vector operand (the "rvalue")
959 to the left one (the "lvalue").
960 The former contents of the left operand become the most significant
962 part of the resulting bit vector, and the right operand becomes the
963 least significant part.
964 Since bit vectors are stored in "least order bit first" order, this
966 actually requires the left operand to be shifted "up" by the length
967 of the right operand, which is then copied to the now freed least
968 significant part of the left operand.
969 If the right operand is a Perl scalar, it is first converted to a bit
971 vector of the same size as the left operand, provided that the
972 configuration states that scalars are to be regarded as indices,
973 decimal strings or enumerations.
974 If the configuration states that scalars are to be regarded as
976 hexadecimal or boolean strings, however, these strings are converted
977 to bit vectors of a size matching the length of the input string,
978 i.e., four times the length for hexadecimal strings (because each
979 hexadecimal digit is worth 4 bits) and once the length for binary
980 strings.
981 · "$vector x= $factor;"
983 This statement replaces the given bit vector by a concatenation of as
985 many copies of the original contents of the given bit vector as the
986 factor (the right operand) specifies.
987 If the factor is zero, the given bit vector is resized to a length of
989 zero bits.
990 If the factor is one, the given bit vector is not changed at all.
992 · "$vector <<= $bits;"
994 This statement moves the contents of the given bit vector left by
996 "$bits" positions (towards the most significant bit).
997 This means that the "$bits" most significant bits are lost, all other
999 bits move up by "$bits" positions, and the "$bits" least significant
1000 bits that have been left unoccupied by this shift are all set to
1001 zero.
1002 If "$bits" is greater than the number of bits of the given bit
1004 vector, the given bit vector is erased completely (i.e., all bits are
1005 cleared).
1006 · "$vector >>= $bits;"
1008 This statement moves the contents of the given bit vector right by
1010 "$bits" positions (towards the least significant bit).
1011 This means that the "$bits" least significant bits are lost, all
1013 other bits move down by "$bits" positions, and the "$bits" most
1014 significant bits that have been left unoccupied by this shift are all
1015 set to zero.
1016 If "$bits" is greater than the number of bits of the given bit
1018 vector, the given bit vector is erased completely (i.e., all bits are
1019 cleared).
1020 · "$vector1 |= $vector2;"
1022 This statement performs a bitwise OR operation between the two bit
1024 vector operands and stores the result in the left operand.
1025 This is the same as calculating the union of two sets.
1027 · "$vector1 &= $vector2;"
1029 This statement performs a bitwise AND operation between the two bit
1031 vector operands and stores the result in the left operand.
1032 This is the same as calculating the intersection of two sets.
1034 · "$vector1 ^= $vector2;"
1036 This statement performs a bitwise XOR (exclusive-or) operation
1038 between the two bit vector operands and stores the result in the left
1039 operand.
1040 This is the same as calculating the symmetric difference of two sets.
1042 · "$vector1 += $vector2;"
1044 Depending on the configuration (see the description of the method
1046 ""Configuration()"" for more details), this statement either performs
1047 a bitwise OR operation between the two bit vector operands (this is
1048 the same as calculating the union of two sets) - which is the default
1049 behaviour, or it calculates the sum of the two numbers stored in the
1050 two bit vector operands.
1051 The result of this operation is stored in the left operand.
1053 · "$vector1 -= $vector2;"
1055 Depending on the configuration (see the description of the method
1057 ""Configuration()"" for more details), this statement either
1058 calculates the set difference of the two sets represented in the two
1059 bit vector operands - which is the default behaviour, or it
1060 calculates the difference of the two numbers stored in the two bit
1061 vector operands.
1062 The result of this operation is stored in the left operand.
1064 · "$vector1 *= $vector2;"
1066 Depending on the configuration (see the description of the method
1068 ""Configuration()"" for more details), this statement either performs
1069 a bitwise AND operation between the two bit vector operands (this is
1070 the same as calculating the intersection of two sets) - which is the
1071 default behaviour, or it calculates the product of the two numbers
1072 stored in the two bit vector operands.
1073 The result of this operation is stored in the left operand.
1075 · "$vector1 /= $vector2;"
1077 This statement puts the result of the division of the two numbers
1079 stored in the two bit vector operands into the left operand.
1080 · "$vector1 %= $vector2;"
1082 This statement puts the remainder of the division of the two numbers
1084 stored in the two bit vector operands into the left operand.
1085 · "$vector1 **= $vector2;"
1087 This statement puts the result of the exponentiation of the left
1089 operand elevated to the right operand's power into the left operand.
1090 · "++$vector", "$vector++"
1092 This operator performs pre- and post-incrementation of the given bit
1094 vector.
1095 The value returned by this term is a reference of the given bit
1097 vector object (after or before the incrementation, respectively).
1098 · "--$vector", "$vector--"
1100 This operator performs pre- and post-decrementation of the given bit
1102 vector.
1103 The value returned by this term is a reference of the given bit
1105 vector object (after or before the decrementation, respectively).
1106 · "($vector1 cmp $vector2)"
1108 This term returns ""-1"" if "$vector1" is less than "$vector2", "0"
1110 if "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1111 greater than "$vector2".
1112 This comparison assumes UNSIGNED bit vectors.
1114 · "($vector1 eq $vector2)"
1116 This term returns true ("1") if the contents of the two bit vector
1118 operands are the same and false ("0") otherwise.
1119 · "($vector1 ne $vector2)"
1121 This term returns true ("1") if the two bit vector operands differ
1123 and false ("0") otherwise.
1124 · "($vector1 lt $vector2)"
1126 This term returns true ("1") if "$vector1" is less than "$vector2",
1128 and false ("0") otherwise.
1129 This comparison assumes UNSIGNED bit vectors.
1131 · "($vector1 le $vector2)"
1133 This term returns true ("1") if "$vector1" is less than or equal to
1135 "$vector2", and false ("0") otherwise.
1136 This comparison assumes UNSIGNED bit vectors.
1138 · "($vector1 gt $vector2)"
1140 This term returns true ("1") if "$vector1" is greater than
1142 "$vector2", and false ("0") otherwise.
1143 This comparison assumes UNSIGNED bit vectors.
1145 · "($vector1 ge $vector2)"
1147 This term returns true ("1") if "$vector1" is greater than or equal
1149 to "$vector2", and false ("0") otherwise.
1150 This comparison assumes UNSIGNED bit vectors.
1152 · "($vector1 <=> $vector2)"
1154 This term returns ""-1"" if "$vector1" is less than "$vector2", "0"
1156 if "$vector1" and "$vector2" are the same, and "1" if "$vector1" is
1157 greater than "$vector2".
1158 This comparison assumes SIGNED bit vectors.
1160 · "($vector1 == $vector2)"
1162 This term returns true ("1") if the contents of the two bit vector
1164 operands are the same and false ("0") otherwise.
1165 · "($vector1 != $vector2)"
1167 This term returns true ("1") if the two bit vector operands differ
1169 and false ("0") otherwise.
1170 · "($vector1 < $vector2)"
1172 Depending on the configuration (see the description of the method
1174 ""Configuration()"" for more details), this term either returns true
1175 ("1") if "$vector1" is a true subset of "$vector2" (and false ("0")
1176 otherwise) - which is the default behaviour, or it returns true ("1")
1177 if "$vector1" is less than "$vector2" (and false ("0") otherwise).
1178 The latter comparison assumes SIGNED bit vectors.
1180 · "($vector1 <= $vector2)"
1182 Depending on the configuration (see the description of the method
1184 ""Configuration()"" for more details), this term either returns true
1185 ("1") if "$vector1" is a subset of "$vector2" (and false ("0")
1186 otherwise) - which is the default behaviour, or it returns true ("1")
1187 if "$vector1" is less than or equal to "$vector2" (and false ("0")
1188 otherwise).
1189 The latter comparison assumes SIGNED bit vectors.
1191 · "($vector1 > $vector2)"
1193 Depending on the configuration (see the description of the method
1195 ""Configuration()"" for more details), this term either returns true
1196 ("1") if "$vector1" is a true superset of "$vector2" (and false ("0")
1197 otherwise) - which is the default behaviour, or it returns true ("1")
1198 if "$vector1" is greater than "$vector2" (and false ("0") otherwise).
1199 The latter comparison assumes SIGNED bit vectors.
1201 · "($vector1 >= $vector2)"
1203 Depending on the configuration (see the description of the method
1205 ""Configuration()"" for more details), this term either returns true
1206 ("1") if "$vector1" is a superset of "$vector2" (and false ("0")
1207 otherwise) - which is the default behaviour, or it returns true ("1")
1208 if "$vector1" is greater than or equal to "$vector2" (and false ("0")
1209 otherwise).
1210 The latter comparison assumes SIGNED bit vectors.
1212
1214 Bit::Vector(3), Bit::Vector::String(3).
1215
1217 This man page documents "Bit::Vector::Overload" version 7.3.
1218
1220 Steffen Beyer
1221 mailto:STBEY@cpan.org
1222 http://www.engelschall.com/u/sb/download/
1223
1225 Copyright (c) 2000 - 2013 by Steffen Beyer. All rights reserved.
1226
1228 This package is free software; you can redistribute it and/or modify it
1229 under the same terms as Perl itself, i.e., under the terms of the
1230 "Artistic License" or the "GNU General Public License".
1231 The C library at the core of this Perl module can additionally be
1233 redistributed and/or modified under the terms of the "GNU Library
1234 General Public License".
1235 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
1237 "GNU_LGPL.txt" in this distribution for details!
1238
1240 This package is distributed in the hope that it will be useful, but
1241 WITHOUT ANY WARRANTY; without even the implied warranty of
1242 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1243 See the "GNU General Public License" for more details.
1245perl v5.16.3 2013-06-01 Bit::Vector::Overload(3)