overload.pod

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

Note however that machine words can be stored least order byte first or last,
depending on your system's implementation.

Note further that whenever bit vectors are converted to and from (binary or
hexadecimal) strings, the B<RIGHTMOST> bit is always the B<LEAST SIGNIFICANT>
one, and the B<LEFTMOST> bit is always the B<MOST SIGNIFICANT> bit.

This is because in our western culture, numbers are always represented in this
way (least significant to most significant digits go from right to left).

Of course this requires an internal reversion of order, which the corresponding
conversion methods perform automatically (without any additional overhead, it's
just a matter of starting the internal loop at the bottom or the top end).

=item *

Matching sizes

In general, for methods involving several bit vectors at the same time, all
bit vector arguments must have identical sizes (number of bits), or a fatal
"size mismatch" error will occur.

Exceptions from this rule are the methods "C<Concat()>", "C<Concat_List()>",
"C<Copy()>", "C<Interval_Copy()>" and "C<Interval_Substitute()>", where no
conditions at all are imposed on the size of their bit vector arguments.

In method "C<Multiply()>", all three bit vector arguments must in principle
obey the rule of matching sizes, but the bit vector in which the result of
the multiplication is to be stored may be larger than the two bit vector
arguments containing the factors for the multiplication.

In method "C<Power()>", the bit vector for the result must be the same
size or greater than the base of the exponentiation term. The exponent
can be any size.

The same applies to the corresponding overloaded operators.

=item *

Index ranges

All indices for any given bits must lie between "C<0>" and
"C<$vector-E<gt>Size()-1>", or a fatal "index out of range"
error will occur.

=back

=head1 DESCRIPTION

=over 2

=item *

C<$config = Bit::Vector-E<gt>Configuration();>

=item *

C<Bit::Vector-E<gt>Configuration($config);>

=item *

C<$oldconfig = Bit::Vector-E<gt>Configuration($newconfig);>

This method serves to alter the semantics (i.e., behaviour) of certain
overloaded operators (which are all implemented in Perl, by the way).

It does not have any effect whatsoever on anything else. In particular,
it does not affect the methods implemented in C.

The method accepts an (optional) string as input in which certain keywords
are expected, which influence some or almost all of the overloaded operators
in several possible ways.

The method always returns a string (which you do not need to take care of,
i.e., to store, in case you aren't interested in keeping it) which is a
complete representation of the current configuration (i.e., B<BEFORE>
any modifications are applied) and which can be fed back to this method
later in order to restore the previous configuration.

There are three aspects of the way certain overloaded operators behave which
can be controlled with this method:

  +  the way scalar operands (replacing one of the two
     bit vector object operands) are automatically
     converted internally into a bit vector object of
     their own,

  +  the operation certain overloaded operators perform,
     i.e., an operation with sets or an arithmetic
     operation,

  +  the format to which bit vectors are converted
     automatically when they are enclosed in double
     quotes.

The input string may contain any number of assignments, each of which
controls one of these three aspects.

Each assignment has the form "C<E<lt>whichE<gt>=E<lt>valueE<gt>>".

"C<E<lt>whichE<gt>>" and "C<E<lt>valueE<gt>>" thereby consist of letters
(C<[a-zA-Z]>) and white space.

Multiple assignments have to be separated by one or more comma (","),
semi-colon (";"), colon (":"), vertical bar ("|"), slash ("/"),
newline ("\n"), ampersand ("&"), plus ("+") or dash ("-").

Empty lines or statements (only white space) are allowed but will be
ignored.

"C<E<lt>whichE<gt>>" has to contain one or more keywords from one of
three groups, each group representing one of the three aspects that
the "C<Configuration()>" method controls:

  +  "^scalar", "^input", "^in$"

  +  "^operator", "^semantic", "^ops$"

  +  "^string", "^output", "^out$"

The character "^" thereby denotes the beginning of a word, and "$"
denotes the end. Case is ignored (!).

Using these keywords, you can build any phrase you like to select one
of the three aspects (see also examples given below).

The only condition is that no other keyword from any of the other two
groups may match - otherwise a syntax error will occur (i.e., ambiguities
are forbidden). A syntax error also occurs if none of the keywords
matches.

This same principle applies to "C<E<lt>valueE<gt>>":

Depending on which aspect you specified for "C<E<lt>whichE<gt>>",
there are different groups of keywords that determine the value
the selected aspect will be set to:

  +  "<which>" = "^scalar", "^input", "^in$":

       "<value>" =

       *  "^bit$", "^index", "^indice"
       *  "^hex"
       *  "^bin"
       *  "^dec"
       *  "^enum"

  +  "<which>" = "^operator", "^semantic", "^ops$":

       "<value>" =

       *  "^set$"
       *  "^arithmetic"

  +  "<which>" = "^string", "^output", "^out$":

       "<value>" =

       *  "^hex"
       *  "^bin"
       *  "^dec"
       *  "^enum"

Examples:

  "Any scalar input I provide should be considered to be = a bit index"

  "I want to have operator semantics suitable for = arithmetics"

  "Any bit vector in double quotes is to be output as = an enumeration"

B<SCALAR INPUT:>

In the case of scalar input, "C<^bit$>", "C<^index>", or "C<^indice>"
all cause scalar input to be considered to represent a bit index, i.e.,
"C<$vector ^= 5;>" will flip bit #5 in the given bit vector (this is
essentially the same as "C<$vector-E<gt>bit_flip(5);>").

Note that "bit indices" is the default setting for "scalar input".

The keyword "C<^hex>" will cause scalar input to be considered as being in
hexadecimal, i.e., "C<$vector ^= 5;>" will flip bit #0 and bit #2 (because
hexadecimal "C<5>" is binary "C<0101>").

(Note though that hexadecimal input should always be enclosed in quotes,
otherwise it will be interpreted as a decimal number by Perl! The example
relies on the fact that hexadecimal C<0-9> and decimal C<0-9> are the same.)

The keyword "C<^bin>" will cause scalar input to be considered as being in
binary format. All characters except "C<0>" and "C<1>" are forbidden in
this case (i.e., produce a syntax error).

"C<$vector ^= '0101';>", for instance, will flip bit #0 and bit #2.

The keyword "C<^dec>" causes scalar input to be considered as integers
in decimal format, i.e., "C<$vector ^= 5;>" will flip bit #0 and bit #2
(because decimal "C<5>" is binary "C<0101>").

(Note though that all decimal input should be enclosed in quotes, because
for large numbers, Perl will use scientific notation internally for
representing them, which produces a syntax error because scientific
notation is neither supported by this module nor needed.)

Finally, the keyword "C<^enum>" causes scalar input to be considered
as being a list ("enumeration") of indices and ranges of (contiguous)
indices, i.e., "C<$vector |= '2,3,5,7-13,17-23';>" will cause bits #2,
#3, #5, #7 through #13 and #17 through #23 to be set.

B<OPERATOR SEMANTICS:>

Several overloaded operators can have two distinct functions depending
on this setting.

The affected operators are: "C<+>", "C<->", "C<*>", "C<E<lt>>", "C<E<lt>=>",
"C<E<gt>>" and "C<E<gt>=>".

With the default setting, "set operations", these operators perform:

  +       set union                           ( set1  u   set2 )
  -       set difference                      ( set1  \   set2 )
  *       set intersection                    ( set1  n   set2 )
  <       true subset relationship            ( set1  <   set2 )
  <=      subset relationship                 ( set1  <=  set2 )
  >       true superset relationship          ( set1  >   set2 )
  >=      superset relationship               ( set1  >=  set2 )

With the alternative setting, "arithmetic operations", these operators
perform:

  +       addition                            ( num1  +   num2 )
  -       subtraction                         ( num1  -   num2 )
  *       multiplication                      ( num1  *   num2 )
  <       "less than" comparison              ( num1  <   num2 )
  <=      "less than or equal" comparison     ( num1  <=  num2 )
  >       "greater than" comparison           ( num1  >   num2 )
  >=      "greater than or equal" comparison  ( num1  >=  num2 )

Note that these latter comparison operators ("C<E<lt>>", "C<E<lt>=>",
"C<E<gt>>" and "C<E<gt>=>") regard their operands as being B<SIGNED>.

To perform comparisons with B<UNSIGNED> operands, use the operators
"C<lt>", "C<le>", "C<gt>" and "C<ge>" instead (in contrast to the
operators above, these operators are B<NOT> affected by the
"operator semantics" setting).

B<STRING OUTPUT:>

There are four methods which convert the contents of a given bit vector
into a string: "C<to_Hex()>", "C<to_Bin()>", "C<to_Dec()>" and "C<to_Enum()>"
(not counting "C<Block_Read()>", since this method does not return a
human-readable string).

(For conversion to octal, see the description of the method
"C<Chunk_List_Read()>".)

Therefore, there are four possible formats into which a bit vector can
be converted when it is enclosed in double quotes, for example:

  print "\$vector = '$vector'\n";
  $string = "$vector";

Hence you can set "string output" to four different values: To "hex"
for hexadecimal format (which is the default), to "bin" for binary
format, to "dec" for conversion to decimal numbers and to "enum"
for conversion to enumerations (".newsrc" style sets).

B<BEWARE> that the conversion to decimal numbers is inherently slow;
it can easily take up several seconds for a single large bit vector!

Therefore you should store the decimal strings returned to you
rather than converting a given bit vector again.

B<EXAMPLES:>

The default setting as returned by the method "C<Configuration()>"
is:

        Scalar Input       = Bit Index
        Operator Semantics = Set Operators
        String Output      = Hexadecimal

Performing a statement such as:

  Bit::Vector->Configuration("in=bin,ops=arithmetic,out=bin");
  print Bit::Vector->Configuration(), "\n";

yields the following output:

        Scalar Input       = Binary
        Operator Semantics = Arithmetic Operators
        String Output      = Binary

Note that you can always feed this output back into the "C<Configuration()>"
method to restore that setting later.

This also means that you can enter the same given setting with almost any
degree of verbosity you like (as long as the required keywords appear and
no ambiguities arise).

Note further that any aspect you do not specify is not changed, i.e.,
the statement

  Bit::Vector->Configuration("operators = arithmetic");

leaves all other aspects unchanged.

=item *

C<"$vector">

Remember that variables enclosed in double quotes are always
interpolated in Perl.

Whenever a Perl variable containing the reference of a "Bit::Vector"
object is enclosed in double quotes (either alone or together with
other text and/or variables), the contents of the corresponding
bit vector are converted into a printable string.

Since there are several conversion methods available in this module
(see the description of the methods "C<to_Hex()>", "C<to_Bin()>",
"C<to_Dec()>" and "C<to_Enum()>"), it is of course desirable to
be able to choose which of these methods should be applied in this
case.

This can actually be done by changing the configuration of this
module using the method "C<Configure()>" (see the previous chapter,
immediately above).

The default is conversion to hexadecimal.

=item *

C<if ($vector)>

It is possible to use a Perl variable containing the reference of a
"Bit::Vector" object as a boolean expression.

The condition above is true if the corresponding bit vector contains
at least one set bit, and it is false if B<ALL> bits of the corresponding
bit vector are cleared.

=item *

C<if (!$vector)>

Since it is possible to use a Perl variable containing the reference of a
"Bit::Vector" object as a boolean expression, you can of course also negate
this boolean expression.

The condition above is true if B<ALL> bits of the corresponding bit vector
are cleared, and it is false if the corresponding bit vector contains at
least one set bit.

Note that this is B<NOT> the same as using the method "C<is_full()>",
which returns true if B<ALL> bits of the corresponding bit vector are
B<SET>.

=item *

C<~$vector>

This term returns a new bit vector object which is the one's complement
of the given bit vector.

This is equivalent to inverting all bits.

=item *

C<-$vector> (unary minus)

This term returns a new bit vector object which is the two's complement
of the given bit vector.

This is equivalent to inverting all bits and incrementing the result by one.

(This is the same as changing the sign of a number in two's complement
binary representation.)

=item *

C<abs($vector)>

Depending on the configuration (see the description of the method
"C<Configuration()>" for more details), this term either returns
the number of set bits in the given bit vector (this is the same
as calculating the number of elements which are contained in the
given set) - which is the default behaviour, or it returns a new
bit vector object which contains the absolute value of the number
stored in the given bit vector.

=item *

C<$vector1 . $vector2>

This term usually returns a new bit vector object which is the
result of the concatenation of the two bit vector operands.

The left operand becomes the most significant, and the right operand
becomes the least significant part of the new bit vector object.

If one of the two operands is not a bit vector object but a Perl scalar,
however, 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!

=item *

C<$vector x $factor>

This term returns a new bit vector object which is the concatenation
of as many copies of the given bit vector operand (the left operand)
as the factor (the right operand) specifies.

If the factor is zero, a bit vector object with a length of zero bits
is returned.

If the factor is one, just a new copy of the given bit vector is
returned.

Note that a fatal "reversed operands error" occurs if the two operands
are swapped.

=item *

C<$vector E<lt>E<lt> $bits>

This term returns a new bit vector object which is a copy of the given
bit vector (the left operand), which is then shifted left (towards the
most significant bit) by as many places as the right operand, "C<$bits>",
specifies.

This means that the "C<$bits>" most significant bits are lost, all other
bits move up by "C<$bits>" positions, and the "C<$bits>" least significant
bits that have been left unoccupied by this shift are all set to zero.

If "C<$bits>" is greater than the number of bits of the given bit vector,
this term returns an empty bit vector (i.e., with all bits cleared) of
the same size as the given bit vector.

Note that a fatal "reversed operands error" occurs if the two operands
are swapped.

=item *

C<$vector E<gt>E<gt> $bits>

This term returns a new bit vector object which is a copy of the given
bit vector (the left operand), which is then shifted right (towards the
least significant bit) by as many places as the right operand, "C<$bits>",
specifies.