1Bit::Vector::Overload(3U)ser Contributed Perl DocumentatiBoint::Vector::Overload(3)
2
3
4

NAME

6       Bit::Vector::Overload - Overloaded operators add-on for Bit::Vector
7

USAGE

9       Note that you do not need to ""use Bit::Vector;"" in addition to this
10       module.
11
12       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

SYNOPSIS

18         Configuration
19             $config = Bit::Vector->Configuration();
20             Bit::Vector->Configuration($config);
21             $oldconfig = Bit::Vector->Configuration($newconfig);
22
23         String Conversion
24             $string = "$vector";             #  depending on configuration
25             print "\$vector = '$vector'\n";
26
27         Emptyness
28             if ($vector)  #  if not empty (non-zero)
29             if (! $vector)  #  if empty (zero)
30             unless ($vector)  #  if empty (zero)
31
32         Complement (one's complement)
33             $vector2 = ~$vector1;
34             $vector = ~$vector;
35
36         Negation (two's complement)
37             $vector2 = -$vector1;
38             $vector = -$vector;
39
40         Norm
41             $norm = abs($vector);  #  depending on configuration
42
43         Absolute
44             $vector2 = abs($vector1);  #  depending on configuration
45
46         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
54         Duplication
55             $vector2 = $vector1 x $factor;
56             $vector x= $factor;
57
58         Shift Left
59             $vector2 = $vector1 << $bits;
60             $vector <<= $bits;
61
62         Shift Right
63             $vector2 = $vector1 >> $bits;
64             $vector >>= $bits;
65
66         Union
67             $vector3 = $vector1 | $vector2;
68             $vector1 |= $vector2;
69             $vector2 = $vector1 | $scalar;
70             $vector |= $scalar;
71
72             $vector3 = $vector1 + $vector2;  #  depending on configuration
73             $vector1 += $vector2;
74             $vector2 = $vector1 + $scalar;
75             $vector += $scalar;
76
77         Intersection
78             $vector3 = $vector1 & $vector2;
79             $vector1 &= $vector2;
80             $vector2 = $vector1 & $scalar;
81             $vector &= $scalar;
82
83             $vector3 = $vector1 * $vector2;  #  depending on configuration
84             $vector1 *= $vector2;
85             $vector2 = $vector1 * $scalar;
86             $vector *= $scalar;
87
88         ExclusiveOr
89             $vector3 = $vector1 ^ $vector2;
90             $vector1 ^= $vector2;
91             $vector2 = $vector1 ^ $scalar;
92             $vector ^= $scalar;
93
94         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
102         Addition
103             $vector3 = $vector1 + $vector2;  #  depending on configuration
104             $vector1 += $vector2;
105             $vector2 = $vector1 + $scalar;
106             $vector += $scalar;
107
108         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
116         Multiplication
117             $vector3 = $vector1 * $vector2;  #  depending on configuration
118             $vector1 *= $vector2;
119             $vector2 = $vector1 * $scalar;
120             $vector *= $scalar;
121
122         Division
123             $vector3 = $vector1 / $vector2;
124             $vector1 /= $vector2;
125             $vector1 = $vector2 / $vector1;
126             $vector2 = $vector1 / $scalar;
127             $vector2 = $scalar / $vector1;
128             $vector /= $scalar;
129
130         Modulo
131             $vector3 = $vector1 % $vector2;
132             $vector1 %= $vector2;
133             $vector1 = $vector2 % $vector1;
134             $vector2 = $vector1 % $scalar;
135             $vector2 = $scalar % $vector1;
136             $vector %= $scalar;
137
138         Exponentiation
139             $vector3 = $vector1 ** $vector2;
140             $vector1 **= $vector2;
141             $vector2 = $vector1 ** $scalar;
142             $vector2 = $scalar ** $vector1;
143             $vector **= $scalar;
144
145         Increment
146             ++$vector;
147             $vector++;
148
149         Decrement
150             --$vector;
151             $vector--;
152
153         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
160             $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
166         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
173             $cmp = $vector <=> $scalar;
174             if ($vector < $scalar)  #  depending on configuration
175             if ($vector <= $scalar)
176             if ($vector > $scalar)
177             if ($vector >= $scalar)
178
179         Equality
180             if ($vector1 eq $vector2)
181             if ($vector1 ne $vector2)
182             if ($vector eq $scalar)
183             if ($vector ne $scalar)
184
185             if ($vector1 == $vector2)
186             if ($vector1 != $vector2)
187             if ($vector == $scalar)
188             if ($vector != $scalar)
189
190         Subset Relationship
191             if ($vector1 <= $vector2)  #  depending on configuration
192
193         True Subset Relationship
194             if ($vector1 < $vector2)  #  depending on configuration
195
196         Superset Relationship
197             if ($vector1 >= $vector2)  #  depending on configuration
198
199         True Superset Relationship
200             if ($vector1 > $vector2)  #  depending on configuration
201

IMPORTANT NOTES

203       · Boolean values
204
205         Boolean values in this module are always a numeric zero ("0") for
206         "false" and a numeric one ("1") for "true".
207
208       · Negative numbers
209
210         Numeric factors (as needed for the ""<<"", "">>"" and ""x""
211         operators) and bit numbers are always regarded as being UNSIGNED.
212
213         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
219         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
223       · Overloaded operators configuration
224
225         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
229         For instance, scalars (i.e., numbers and strings) provided as
230         operands to overloaded operators are automatically converted to bit
231         vectors, internally.
232
233         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
237         Similarly, when converting bit vectors to strings using double quotes
238         (""), the output format will also depend on the previously chosen
239         configuration.
240
241         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
246         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
250       · "Big integers"
251
252         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
260         Note that you will get an error message (resulting in program
261         abortion) if your "big integer" numbers exceed that limit.
262
263         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
267         Examples:
268
269             $vector /= 10;  #  ok because number is small
270
271             $vector /= -10;  #  ok for same reason
272
273             $vector /= "10";  #  always correct
274
275             $vector += "1152921504606846976";  #  quotes probably required here
276
277         All examples assume
278
279             Bit::Vector->Configuration("input=decimal");
280
281         having been set beforehand.
282
283         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
289         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
293         All other characters produce a syntax error.
294
295       · Valid operands for overloaded operators
296
297         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
301         This is especially true for all unary operators:
302
303                             "$vector"
304                             if ($vector)
305                             if (!$vector)
306                             ~$vector
307                             -$vector
308                             abs($vector)
309                             ++$vector
310                             $vector++
311                             --$vector
312                             $vector--
313
314         For obvious reasons the left operand (the "lvalue") of all assignment
315         operators is also required to be a bit vector:
316
317                                 .=
318                                 x=
319                                 <<=
320                                 >>=
321                                 |=
322                                 &=
323                                 ^=
324                                 +=
325                                 -=
326                                 *=
327                                 /=
328                                 %=
329                                **=
330
331         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
337         In all truly binary operators, i.e.,
338
339                                 .
340                                 |
341                                 &
342                                 ^
343                                 +
344                                 -
345                                 *
346                                 /
347                                 %
348                                **
349                             <=>   cmp
350                              ==    eq
351                              !=    ne
352                              <     lt
353                              <=    le
354                              >     gt
355                              >=    ge
356
357         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
361         The same applies to the right side operand (the "rvalue") of the
362         remaining assignment operators, i.e.,
363
364                                 .=
365                                 |=
366                                 &=
367                                 ^=
368                                 +=
369                                 -=
370                                 *=
371                                 /=
372                                 %=
373                                **=
374
375         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
380         The acceptable scalar types for each possible configuration are the
381         following:
382
383             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
390         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
393         The only exception from this rule is the concatenation operator
394         (""."") and its assignment variant ("".=""):
395
396         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
405         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
411         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
418         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
421         If a bit index is out of range for the given bit vector, an "index
422         out of range" error occurs.
423
424         If a scalar operand cannot be converted successfully due to invalid
425         syntax, a fatal "input string syntax error" is issued.
426
427         If the two operands of the operator ""<<"", "">>"" or ""x"" are
428         reversed, a fatal "reversed operands error" occurs.
429
430         If an operand is neither a bit vector nor a scalar, then a fatal
431         "illegal operand type error" occurs.
432
433       · Bit order
434
435         Note that bit vectors are stored least order bit and least order word
436         first internally.
437
438         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
441         (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
445         Note however that machine words can be stored least order byte first
446         or last, depending on your system's implementation.
447
448         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
453         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
457         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
462       · Matching sizes
463
464         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
468         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
473         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
479         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
483         The same applies to the corresponding overloaded operators.
484
485       · Index ranges
486
487         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

DESCRIPTION

492       · "$config = Bit::Vector->Configuration();"
493
494       · "Bit::Vector->Configuration($config);"
495
496       · "$oldconfig = Bit::Vector->Configuration($newconfig);"
497
498         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
502         It does not have any effect whatsoever on anything else. In
503         particular, it does not affect the methods implemented in C.
504
505         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
509         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
516         There are three aspects of the way certain overloaded operators
517         behave which can be controlled with this method:
518
519           +  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
524           +  the operation certain overloaded operators perform,
525              i.e., an operation with sets or an arithmetic
526              operation,
527
528           +  the format to which bit vectors are converted
529              automatically when they are enclosed in double
530              quotes.
531
532         The input string may contain any number of assignments, each of which
533         controls one of these three aspects.
534
535         Each assignment has the form ""<which>=<value>"".
536
537         ""<which>"" and ""<value>"" thereby consist of letters ("[a-zA-Z]")
538         and white space.
539
540         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
544         Empty lines or statements (only white space) are allowed but will be
545         ignored.
546
547         ""<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
551           +  "^scalar", "^input", "^in$"
552
553           +  "^operator", "^semantic", "^ops$"
554
555           +  "^string", "^output", "^out$"
556
557         The character "^" thereby denotes the beginning of a word, and "$"
558         denotes the end. Case is ignored (!).
559
560         Using these keywords, you can build any phrase you like to select one
561         of the three aspects (see also examples given below).
562
563         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
568         This same principle applies to ""<value>"":
569
570         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
574           +  "<which>" = "^scalar", "^input", "^in$":
575
576                "<value>" =
577
578                *  "^bit$", "^index", "^indice"
579                *  "^hex"
580                *  "^bin"
581                *  "^dec"
582                *  "^enum"
583
584           +  "<which>" = "^operator", "^semantic", "^ops$":
585
586                "<value>" =
587
588                *  "^set$"
589                *  "^arithmetic"
590
591           +  "<which>" = "^string", "^output", "^out$":
592
593                "<value>" =
594
595                *  "^hex"
596                *  "^bin"
597                *  "^dec"
598                *  "^enum"
599
600         Examples:
601
602           "Any scalar input I provide should be considered to be = a bit index"
603
604           "I want to have operator semantics suitable for = arithmetics"
605
606           "Any bit vector in double quotes is to be output as = an enumeration"
607
608         SCALAR INPUT:
609
610         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
615         Note that "bit indices" is the default setting for "scalar input".
616
617         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
621         (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
626         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
630         ""$vector ^= '0101';"", for instance, will flip bit #0 and bit #2.
631
632         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
636         (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
642         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
647         OPERATOR SEMANTICS:
648
649         Several overloaded operators can have two distinct functions
650         depending on this setting.
651
652         The affected operators are: ""+"", ""-"", ""*"", ""<"", ""<="", "">""
653         and "">="".
654
655         With the default setting, "set operations", these operators perform:
656
657           +       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
665         With the alternative setting, "arithmetic operations", these
666         operators perform:
667
668           +       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
676         Note that these latter comparison operators (""<"", ""<="", "">"" and
677         "">="") regard their operands as being SIGNED.
678
679         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
684         STRING OUTPUT:
685
686         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
691         (For conversion to octal, see the description of the method
692         ""Chunk_List_Read()"".)
693
694         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
697           print "\$vector = '$vector'\n";
698           $string = "$vector";
699
700         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
705         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
708         Therefore you should store the decimal strings returned to you rather
709         than converting a given bit vector again.
710
711         EXAMPLES:
712
713         The default setting as returned by the method ""Configuration()"" is:
714
715                 Scalar Input       = Bit Index
716                 Operator Semantics = Set Operators
717                 String Output      = Hexadecimal
718
719         Performing a statement such as:
720
721           Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
722           print Bit::Vector->Configuration(), "\n";
723
724         yields the following output:
725
726                 Scalar Input       = Binary
727                 Operator Semantics = Arithmetic Operators
728                 String Output      = Binary
729
730         Note that you can always feed this output back into the
731         ""Configuration()"" method to restore that setting later.
732
733         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
737         Note further that any aspect you do not specify is not changed, i.e.,
738         the statement
739
740           Bit::Vector->Configuration("operators = arithmetic");
741
742         leaves all other aspects unchanged.
743
744       · "$vector"
745
746         Remember that variables enclosed in double quotes are always
747         interpolated in Perl.
748
749         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
754         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
759         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
763         The default is conversion to hexadecimal.
764
765       · "if ($vector)"
766
767         It is possible to use a Perl variable containing the reference of a
768         "Bit::Vector" object as a boolean expression.
769
770         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
774       · "if (!$vector)"
775
776         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
780         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
784         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
788       · "~$vector"
789
790         This term returns a new bit vector object which is the one's
791         complement of the given bit vector.
792
793         This is equivalent to inverting all bits.
794
795       · "-$vector" (unary minus)
796
797         This term returns a new bit vector object which is the two's
798         complement of the given bit vector.
799
800         This is equivalent to inverting all bits and incrementing the result
801         by one.
802
803         (This is the same as changing the sign of a number in two's
804         complement binary representation.)
805
806       · "abs($vector)"
807
808         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
816       · "$vector1 . $vector2"
817
818         This term usually returns a new bit vector object which is the result
819         of the concatenation of the two bit vector operands.
820
821         The left operand becomes the most significant, and the right operand
822         becomes the least significant part of the new bit vector object.
823
824         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
831         In other words, a string is returned in such a case instead of a bit
832         vector object!
833
834       · "$vector x $factor"
835
836         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
840         If the factor is zero, a bit vector object with a length of zero bits
841         is returned.
842
843         If the factor is one, just a new copy of the given bit vector is
844         returned.
845
846         Note that a fatal "reversed operands error" occurs if the two
847         operands are swapped.
848
849       · "$vector << $bits"
850
851         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
856         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
861         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
865         Note that a fatal "reversed operands error" occurs if the two
866         operands are swapped.
867
868       · "$vector >> $bits"
869
870         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
875         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
880         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
884         Note that a fatal "reversed operands error" occurs if the two
885         operands are swapped.
886
887       · "$vector1 | $vector2"
888
889         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
892         This is the same as calculating the union of two sets.
893
894       · "$vector1 & $vector2"
895
896         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
899         This is the same as calculating the intersection of two sets.
900
901       · "$vector1 ^ $vector2"
902
903         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
907         This is the same as calculating the symmetric difference of two sets.
908
909       · "$vector1 + $vector2"
910
911         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
919       · "$vector1 - $vector2"
920
921         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
928       · "$vector1 * $vector2"
929
930         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
938       · "$vector1 / $vector2"
939
940         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
944       · "$vector1 % $vector2"
945
946         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
950       · "$vector1 ** $vector2"
951
952         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
956       · "$vector1 .= $vector2;"
957
958         This statement "appends" the right bit vector operand (the "rvalue")
959         to the left one (the "lvalue").
960
961         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
965         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
970         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
975         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
982       · "$vector x= $factor;"
983
984         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
988         If the factor is zero, the given bit vector is resized to a length of
989         zero bits.
990
991         If the factor is one, the given bit vector is not changed at all.
992
993       · "$vector <<= $bits;"
994
995         This statement moves the contents of the given bit vector left by
996         "$bits" positions (towards the most significant bit).
997
998         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
1003         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
1007       · "$vector >>= $bits;"
1008
1009         This statement moves the contents of the given bit vector right by
1010         "$bits" positions (towards the least significant bit).
1011
1012         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
1017         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
1021       · "$vector1 |= $vector2;"
1022
1023         This statement performs a bitwise OR operation between the two bit
1024         vector operands and stores the result in the left operand.
1025
1026         This is the same as calculating the union of two sets.
1027
1028       · "$vector1 &= $vector2;"
1029
1030         This statement performs a bitwise AND operation between the two bit
1031         vector operands and stores the result in the left operand.
1032
1033         This is the same as calculating the intersection of two sets.
1034
1035       · "$vector1 ^= $vector2;"
1036
1037         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
1041         This is the same as calculating the symmetric difference of two sets.
1042
1043       · "$vector1 += $vector2;"
1044
1045         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
1052         The result of this operation is stored in the left operand.
1053
1054       · "$vector1 -= $vector2;"
1055
1056         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
1063         The result of this operation is stored in the left operand.
1064
1065       · "$vector1 *= $vector2;"
1066
1067         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
1074         The result of this operation is stored in the left operand.
1075
1076       · "$vector1 /= $vector2;"
1077
1078         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
1081       · "$vector1 %= $vector2;"
1082
1083         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
1086       · "$vector1 **= $vector2;"
1087
1088         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
1091       · "++$vector", "$vector++"
1092
1093         This operator performs pre- and post-incrementation of the given bit
1094         vector.
1095
1096         The value returned by this term is a reference of the given bit
1097         vector object (after or before the incrementation, respectively).
1098
1099       · "--$vector", "$vector--"
1100
1101         This operator performs pre- and post-decrementation of the given bit
1102         vector.
1103
1104         The value returned by this term is a reference of the given bit
1105         vector object (after or before the decrementation, respectively).
1106
1107       · "($vector1 cmp $vector2)"
1108
1109         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
1113         This comparison assumes UNSIGNED bit vectors.
1114
1115       · "($vector1 eq $vector2)"
1116
1117         This term returns true ("1") if the contents of the two bit vector
1118         operands are the same and false ("0") otherwise.
1119
1120       · "($vector1 ne $vector2)"
1121
1122         This term returns true ("1") if the two bit vector operands differ
1123         and false ("0") otherwise.
1124
1125       · "($vector1 lt $vector2)"
1126
1127         This term returns true ("1") if "$vector1" is less than "$vector2",
1128         and false ("0") otherwise.
1129
1130         This comparison assumes UNSIGNED bit vectors.
1131
1132       · "($vector1 le $vector2)"
1133
1134         This term returns true ("1") if "$vector1" is less than or equal to
1135         "$vector2", and false ("0") otherwise.
1136
1137         This comparison assumes UNSIGNED bit vectors.
1138
1139       · "($vector1 gt $vector2)"
1140
1141         This term returns true ("1") if "$vector1" is greater than
1142         "$vector2", and false ("0") otherwise.
1143
1144         This comparison assumes UNSIGNED bit vectors.
1145
1146       · "($vector1 ge $vector2)"
1147
1148         This term returns true ("1") if "$vector1" is greater than or equal
1149         to "$vector2", and false ("0") otherwise.
1150
1151         This comparison assumes UNSIGNED bit vectors.
1152
1153       · "($vector1 <=> $vector2)"
1154
1155         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
1159         This comparison assumes SIGNED bit vectors.
1160
1161       · "($vector1 == $vector2)"
1162
1163         This term returns true ("1") if the contents of the two bit vector
1164         operands are the same and false ("0") otherwise.
1165
1166       · "($vector1 != $vector2)"
1167
1168         This term returns true ("1") if the two bit vector operands differ
1169         and false ("0") otherwise.
1170
1171       · "($vector1 < $vector2)"
1172
1173         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
1179         The latter comparison assumes SIGNED bit vectors.
1180
1181       · "($vector1 <= $vector2)"
1182
1183         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
1190         The latter comparison assumes SIGNED bit vectors.
1191
1192       · "($vector1 > $vector2)"
1193
1194         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
1200         The latter comparison assumes SIGNED bit vectors.
1201
1202       · "($vector1 >= $vector2)"
1203
1204         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
1211         The latter comparison assumes SIGNED bit vectors.
1212

SEE ALSO

1214       Bit::Vector(3), Bit::Vector::String(3).
1215

VERSION

1217       This man page documents "Bit::Vector::Overload" version 7.3.
1218

AUTHOR

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

LICENSE

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
1232       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
1236       Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
1237       "GNU_LGPL.txt" in this distribution for details!
1238

DISCLAIMER

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
1244       See the "GNU General Public License" for more details.
1245
1246
1247
1248perl v5.16.3                      2013-06-01          Bit::Vector::Overload(3)
Impressum