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