overload.pod

SinFP是一种新的识别对方计算机操作系统类型的工具

=head1 NAME

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

=head1 USAGE

Note that you do not need to "C<use Bit::Vector;>"
in addition to this module.

Simply "C<use Bit::Vector::Overload;>" B<INSTEAD>
of "C<use Bit::Vector;>". You can still use all the
methods from the "Bit::Vector" module in addition
to the overloaded operators and methods provided
here after that.

=head1 SYNOPSIS

  Configuration
      $config = Bit::Vector->Configuration();
      Bit::Vector->Configuration($config);
      $oldconfig = Bit::Vector->Configuration($newconfig);

  String Conversion
      $string = "$vector";             #  depending on configuration
      print "\$vector = '$vector'\n";

  Emptyness
      if ($vector)  #  if not empty (non-zero)
      if (! $vector)  #  if empty (zero)
      unless ($vector)  #  if empty (zero)

  Complement (one's complement)
      $vector2 = ~$vector1;
      $vector = ~$vector;

  Negation (two's complement)
      $vector2 = -$vector1;
      $vector = -$vector;

  Norm
      $norm = abs($vector);  #  depending on configuration

  Absolute
      $vector2 = abs($vector1);  #  depending on configuration

  Concatenation
      $vector3 = $vector1 . $vector2;
      $vector1 .= $vector2;
      $vector1 = $vector2 . $vector1;
      $vector2 = $vector1 . $scalar;  #  depending on configuration
      $vector2 = $scalar . $vector1;
      $vector .= $scalar;

  Duplication
      $vector2 = $vector1 x $factor;
      $vector x= $factor;

  Shift Left
      $vector2 = $vector1 << $bits;
      $vector <<= $bits;

  Shift Right
      $vector2 = $vector1 >> $bits;
      $vector >>= $bits;

  Union
      $vector3 = $vector1 | $vector2;
      $vector1 |= $vector2;
      $vector2 = $vector1 | $scalar;
      $vector |= $scalar;

      $vector3 = $vector1 + $vector2;  #  depending on configuration
      $vector1 += $vector2;
      $vector2 = $vector1 + $scalar;
      $vector += $scalar;

  Intersection
      $vector3 = $vector1 & $vector2;
      $vector1 &= $vector2;
      $vector2 = $vector1 & $scalar;
      $vector &= $scalar;

      $vector3 = $vector1 * $vector2;  #  depending on configuration
      $vector1 *= $vector2;
      $vector2 = $vector1 * $scalar;
      $vector *= $scalar;

  ExclusiveOr
      $vector3 = $vector1 ^ $vector2;
      $vector1 ^= $vector2;
      $vector2 = $vector1 ^ $scalar;
      $vector ^= $scalar;

  Set Difference
      $vector3 = $vector1 - $vector2;  #  depending on configuration
      $vector1 -= $vector2;
      $vector1 = $vector2 - $vector1;
      $vector2 = $vector1 - $scalar;
      $vector2 = $scalar - $vector1;
      $vector -= $scalar;

  Addition
      $vector3 = $vector1 + $vector2;  #  depending on configuration
      $vector1 += $vector2;
      $vector2 = $vector1 + $scalar;
      $vector += $scalar;

  Subtraction
      $vector3 = $vector1 - $vector2;  #  depending on configuration
      $vector1 -= $vector2;
      $vector1 = $vector2 - $vector1;
      $vector2 = $vector1 - $scalar;
      $vector2 = $scalar - $vector1;
      $vector -= $scalar;

  Multiplication
      $vector3 = $vector1 * $vector2;  #  depending on configuration
      $vector1 *= $vector2;
      $vector2 = $vector1 * $scalar;
      $vector *= $scalar;

  Division
      $vector3 = $vector1 / $vector2;
      $vector1 /= $vector2;
      $vector1 = $vector2 / $vector1;
      $vector2 = $vector1 / $scalar;
      $vector2 = $scalar / $vector1;
      $vector /= $scalar;

  Modulo
      $vector3 = $vector1 % $vector2;
      $vector1 %= $vector2;
      $vector1 = $vector2 % $vector1;
      $vector2 = $vector1 % $scalar;
      $vector2 = $scalar % $vector1;
      $vector %= $scalar;

  Exponentiation
      $vector3 = $vector1 ** $vector2;
      $vector1 **= $vector2;
      $vector2 = $vector1 ** $scalar;
      $vector2 = $scalar ** $vector1;
      $vector **= $scalar;

  Increment
      ++$vector;
      $vector++;

  Decrement
      --$vector;
      $vector--;

  Lexical Comparison (unsigned)
      $cmp = $vector1 cmp $vector2;
      if ($vector1 lt $vector2)
      if ($vector1 le $vector2)
      if ($vector1 gt $vector2)
      if ($vector1 ge $vector2)

      $cmp = $vector cmp $scalar;
      if ($vector lt $scalar)
      if ($vector le $scalar)
      if ($vector gt $scalar)
      if ($vector ge $scalar)

  Comparison (signed)
      $cmp = $vector1 <=> $vector2;
      if ($vector1 < $vector2)  #  depending on configuration
      if ($vector1 <= $vector2)
      if ($vector1 > $vector2)
      if ($vector1 >= $vector2)

      $cmp = $vector <=> $scalar;
      if ($vector < $scalar)  #  depending on configuration
      if ($vector <= $scalar)
      if ($vector > $scalar)
      if ($vector >= $scalar)

  Equality
      if ($vector1 eq $vector2)
      if ($vector1 ne $vector2)
      if ($vector eq $scalar)
      if ($vector ne $scalar)

      if ($vector1 == $vector2)
      if ($vector1 != $vector2)
      if ($vector == $scalar)
      if ($vector != $scalar)

  Subset Relationship
      if ($vector1 <= $vector2)  #  depending on configuration

  True Subset Relationship
      if ($vector1 < $vector2)  #  depending on configuration

  Superset Relationship
      if ($vector1 >= $vector2)  #  depending on configuration

  True Superset Relationship
      if ($vector1 > $vector2)  #  depending on configuration

=head1 IMPORTANT NOTES

=over 2

=item *

Boolean values

Boolean values in this module are always a numeric zero ("C<0>") for
"false" and a numeric one ("C<1>") for "true".

=item *

Negative numbers

Numeric factors (as needed for the "C<E<lt>E<lt>>", "C<E<gt>E<gt>>"
and "C<x>" operators) and bit numbers are always regarded as being
B<UNSIGNED>.

As a consequence, whenever you pass a negative number for such a factor
or bit number, it will be treated as a (usually very large) positive
number due to its internal two's complement binary representation, usually
resulting in malfunctions or an "index out of range" error message and
program abortion.

Note that this does not apply to "big integer" decimal numbers, which
are (usually) passed as strings, and which may of course be negative
(see also the section "Big integers" a little further below).

=item *

Overloaded operators configuration

Note that the behaviour of certain overloaded operators can be changed
in various ways by means of the "C<Configuration()>" method (for more
details, see the description of this method further below).

For instance, scalars (i.e., numbers and strings) provided as operands
to overloaded operators are automatically converted to bit vectors,
internally.

These scalars are thereby automatically assumed to be indices or to be
in hexadecimal, binary, decimal or enumeration format, depending on the
configuration.

Similarly, when converting bit vectors to strings using double quotes
(""), the output format will also depend on the previously chosen
configuration.

Finally, some overloaded operators may have different semantics depending
on the proper configuration; for instance, the operator "+" can be the
"union" operator from set theory or the arithmetic "add" operator.

In all cases (input, output and operator semantics), the defaults have
been chosen in such a way so that the behaviour of the module is backward
compatible with previous versions.

=item *

"Big integers"

As long as "big integers" (for "big integer" arithmetic) are small enough
so that Perl doesn't need scientific notation (exponents) to be able to
represent them internally, you can provide these "big integer" constants
to the overloaded operators of this module (or to the method "C<from_Dec()>")
in numeric form (i.e., either as a numeric constant or expression or as a
Perl variable containing a numeric value).

Note that you will get an error message (resulting in program abortion)
if your "big integer" numbers exceed that limit.

Because this limit is machine-dependent and not obvious to find out,
it is strongly recommended that you enclose B<ALL> your "big integer"
constants in your programs in (double or single) quotes.

Examples:

    $vector /= 10;  #  ok because number is small

    $vector /= -10;  #  ok for same reason

    $vector /= "10";  #  always correct

    $vector += "1152921504606846976";  #  quotes probably required here

All examples assume

    Bit::Vector->Configuration("input=decimal");

having been set beforehand.

Note also that this module does not support scientific notation (exponents)
for "big integer" decimal numbers because you can always make the bit vector
large enough for the whole number to fit without loss of precision (as it
would occur if scientific notation were used).

Finally, note that the only characters allowed in "big integer" constant
strings are the digits C<0..9> and an optional leading sign ("C<+>" or "C<->").

All other characters produce a syntax error.

=item *

Valid operands for overloaded operators

All overloaded operators expect at least one bit vector operand,
in order for the operator to "know" that not the usual operation
is to be carried out, but rather the overloaded variant.

This is especially true for all unary operators:

                    "$vector"
                    if ($vector)
                    if (!$vector)
                    ~$vector
                    -$vector
                    abs($vector)
                    ++$vector
                    $vector++
                    --$vector
                    $vector--

For obvious reasons the left operand (the "lvalue") of all
assignment operators is also required to be a bit vector:

                        .=
                        x=
                        <<=
                        >>=
                        |=
                        &=
                        ^=
                        +=
                        -=
                        *=
                        /=
                        %=
                       **=

In the case of three special operators, namely "C<E<lt>E<lt>>",
"C<E<gt>E<gt>>" and "C<x>", as well as their related assignment
variants, "C<E<lt>E<lt>=>", "C<E<gt>E<gt>=>" and "C<x=>", the
left operand is B<ALWAYS> a bit vector and the right operand is
B<ALWAYS> a number (which is the factor indicating how many times
the operator is to be applied).

In all truly binary operators, i.e.,

                        .
                        |
                        &
                        ^
                        +
                        -
                        *
                        /
                        %
                       **
                    <=>   cmp
                     ==    eq
                     !=    ne
                     <     lt
                     <=    le
                     >     gt
                     >=    ge

one of either operands may be replaced by a Perl scalar, i.e.,
a number or a string, either as a Perl constant, a Perl expression
or a Perl variable yielding a number or a string.

The same applies to the right side operand (the "rvalue") of the
remaining assignment operators, i.e.,

                        .=
                        |=
                        &=
                        ^=
                        +=
                        -=
                        *=
                        /=
                        %=
                       **=

Note that this Perl scalar should be of the correct type, i.e.,
numeric or string, for the chosen configuration, because otherwise
a warning message will occur if your program runs under the "C<-w>"
switch of Perl.

The acceptable scalar types for each possible configuration are
the following:

    input = bit indices    (default)  :    numeric
    input = hexadecimal               :    string
    input = binary                    :    string
    input = decimal                   :    string     (in general)
    input = decimal                   :    numeric    (if small enough)
    input = enumeration               :    string

NOTE ALSO THAT THESE SCALAR OPERANDS ARE CONVERTED TO BIT VECTORS OF
THE SAME SIZE AS THE BIT VECTOR WHICH IS THE OTHER OPERAND.

The only exception from this rule is the concatenation operator
("C<.>") and its assignment variant ("C<.=>"):

If one of the two operands of the concatenation operator ("C<.>") is
not a bit vector object but a Perl scalar, the contents of the remaining
bit vector operand are converted into a string (the format of which
depends on the configuration set with the "C<Configuration()>" method),
which is then concatenated in the proper order (i.e., as indicated by the
order of the two operands) with the Perl scalar (in other words, a string
is returned in such a case instead of a bit vector object!).

If the right side operand (the "rvalue") of the assignment variant
("C<.=>") of the concatenation operator is a Perl scalar, it is converted
internally to a bit vector of the same size as the left side operand provided
that the configuration states that scalars are to be regarded as indices,
decimal strings or enumerations.

If the configuration states that scalars are to be regarded as hexadecimal
or boolean strings, however, these strings are converted to bit vectors of
a size matching the length of the input string, i.e., four times the length
for hexadecimal strings (because each hexadecimal digit is worth 4 bits) and
once the length for binary strings.

If a decimal number ("big integer") is too large to be stored in a
bit vector of the given size, a "numeric overflow error" occurs.

If a bit index is out of range for the given bit vector, an "index
out of range" error occurs.

If a scalar operand cannot be converted successfully due to invalid
syntax, a fatal "input string syntax error" is issued.

If the two operands of the operator "C<E<lt>E<lt>>", "C<E<gt>E<gt>>"
or "C<x>" are reversed, a fatal "reversed operands error" occurs.

If an operand is neither a bit vector nor a scalar, then a fatal
"illegal operand type error" occurs.

=item *

Bit order

Note that bit vectors are stored least order bit and least order word first
internally.

I.e., bit #0 of any given bit vector corresponds to bit #0 of word #0 in the
array of machine words representing the bit vector.

(Where word #0 comes first in memory, i.e., it is stored at the least memory
address in the allocated block of memory holding the given bit vector.)