                    =====================================
                      Package "Bit::Vector" Version 5.6
                    =====================================


            Copyright (c) 1995, 1996, 1997, 1998 by Steffen Beyer.
                             All rights reserved.


What's new in version 5.6:
--------------------------

The leading zeros in the output of "to_Hex()" have been suppressed.

A warning produced by some compilers on line 2067 of "BitVector.c" has been fixed.


Migration strategy to version 5.6:
----------------------------------

Step 1:
-------

If your application(s) still use(s) "Set::IntegerFast" version 3.x,
or if your application(s) still use(s) method names that are considered
deprecated since "Bit::Vector" version 4.0, you will have to upgrade to
"Bit::Vector" version 4.2 first by using the tool "upgrade_BV42.pl" from
the "tools" subdirectory in this distribution.

To do so, simply invoke this utility as follows:

    > perl ./tools/upgrade_BV42.pl  app1.pl  app2.pl  app3.pl  ...
or
    > perl .\tools\upgrade_BV42.pl  app1.pl  app2.pl  app3.pl  ...

Note that this utility renames the original file "app<i>.pl" to
"app<i>.pl.bak" before creating a fresh copy of this file (again
named "app<i>.pl"), and before applying any changes to that copy.

Be cautious to keep this backup copy (or better still, another copy
of the original file) in a safe place!

Beware that (at least under UNIX) this backup file will get overwritten
WITHOUT WARNING if you don't save it to a different place and if you run
the upgrade utility MORE THAN ONCE on the same application!

(Note though that running the upgrade utility more than once on the same
application is harmless as far as the RESULTING file is concerned.)

Beware also that this utility is not fool-proof:

It is theoretically impossible for a patch program such as this one,
which uses regular expressions to analyze your application(s), to handle
all possible cases correctly.

It would not only need to know about Perl syntax and how to parse it,
but it would also need to actually perform some of the Perl statements
(like "use") in order to know about methods that have been imported.

This is of course unfeasible, which is the reason why this utility can
only handle the most common cases.

Actually it might convert MORE than you might want; you will have to
either correct these cases manually after the conversion, or to adapt
the corresponding regular expressions to your special case beforehand.

The substitutions performed by this upgrade utility are the following:

          Set::IntegerFast     ==>  Bit::Vector
          use Bit::Vector 3.x  ==>  use Bit::Vector 4.2
          = new Bit::Vector    ==>  = Bit::Vector->new
          Empty_Interval       ==>  Interval_Empty
          Fill_Interval        ==>  Interval_Fill
          Flip_Interval        ==>  Interval_Flip
          Delete               ==>  Bit_Off
          Insert               ==>  Bit_On
          flip                 ==>  bit_flip
          ->in                 ==>  ->contains
          inclusion            ==>  subset

Step 2:
-------

To upgrade your application(s) from "Bit::Vector" version 4.x
to "Bit::Vector" version 5.6, simply issue the following command:

    > perl ./tools/upgrade_BV56.pl  app1.pl  app2.pl  app3.pl  ...
or
    > perl .\tools\upgrade_BV56.pl  app1.pl  app2.pl  app3.pl  ...

Note that this utility renames the original file "app<i>.pl" to
"app<i>.pl.bak" before creating a fresh copy of this file (again
named "app<i>.pl"), and before applying any changes to that copy.

Be cautious to keep this backup copy (or better still, another copy
of the original file) in a safe place!

Beware that (at least under UNIX) this backup file will get overwritten
WITHOUT WARNING if you don't save it to a different place and if you run
the upgrade utility MORE THAN ONCE on the same application!

(Note though that running the upgrade utility more than once on the same
application is harmless as far as the RESULTING file is concerned.)

Beware also that this utility is far from fool-proof:

For instance, method calls may not span over multiple lines, or
the upgrade utility will not work!

Moreover, the upgrade utility assumes that method calls use the
arrow ("->") -- other forms of method calls that are legal in Perl
are not supported.

Some examples of things this upgrade utility can't handle properly:

        ('10110110' + $vector1)->lexorder($vector2)

(The bit vector object for which the method is invoked (you could call
it the "lvalue" of the method call) must start with a dollar sign. This
means that "($vec1 + $vec2)->" instead of "('10110110' + $vector1)->"
would actually work, but this is not recommended, either. You always
risk parentheses at the wrong places after the upgrade. See below for
how to circumvent this problem!)

        $vector[$index]->lexorder($vector[int($index/2)+1])

(Nested parentheses cannot be parsed with regular expressions.
Therefore, parentheses in the method's arguments cannot be
resolved properly, leading to parentheses in the wrong places
after the upgrade.)

You will need to fix these cases manually.

The best method for doing so is to simplify this kind of statement
BEFORE upgrading your application. A sure way to go is to store such
intermediate results in a temporary variable which is then used in
the method call.

For example:

        $temp = '10110110' + $vector1;
        $temp->lexorder($vector2)

        $temp = int($index/2)+1;
        $vector[$index]->lexorder($vector[$temp])

Note also that in most cases, the upgrade utility assumes that all
method calls have parentheses, even though this is not absolutely
required by Perl syntax.

Spaces before and after the method invocation arrow ("->") and between
the method name and the opening parenthesis are optional, though.

The substitutions performed by this upgrade utility are the following:

          use Bit::Vector 4.x  ==>                 use Bit::Vector 5.6
          to_ASCII             ==>                 to_Enum
          from_ASCII           ==>                 from_Enum
          to_String            ==>                 to_Hex
    ... ->from_string( ... )   ==>  ( eval { ... ->from_Hex( ... ); !$@; } )
          from_string          ==>                 from_Hex
    ... ->lexorder( ... )      ==>         ( ... ->Lexicompare( ... ) <= 0)
          lexorder             ==>                 Lexicompare
    ... = Bit::Vector->new_from_String( ... )
                               ==>
    ... = Bit::Vector->new_Hex(length( ... ) << 2, ... )
          new_from_String      ==>                 new_Hex

Step 3:
-------

BEWARE that the semantics of the method "Compare()" have changed:

While previously it assumed its two bit vector arguments to be UNSIGNED,
it now assumes them to be SIGNED.

If you want to perform a comparison assuming UNSIGNED bit vectors, use
the new method "Lexicompare()" instead!


Version history:
----------------

Version 5.6   02.11.98

 +  Removed the leading zeros from the output of "to_Hex()".
 +  Fixed compiler warning on line 2067 of "BitVector.c".

Version 5.5   21.09.98

 +  Fixed the bug of the uninitialized return code in method "Multiply()".
 +  Fixed the failure of tests 96-131 of test script "t/01________new.t"
    under HP-UX 10.

Version 5.4   07.09.98

 +  Fixed the bug of the uninitialized return code in method "Divide()".
 +  Introduced an additional header "Preface" in the POD documentation to
    avoid clobbering of the information displayed by CPAN.pm et al.
 +  Added the new attributes to "Makefile.PL" for ActiveState's port
    of Perl 5.005 to the Win32 platform.

Version 5.3   12.05.98

    Changed "Norm()" to become still a bit more efficient.
    Ported the "upgrade_BV52" utility to Perl ("upgrade_BV53.pl"),
    making it faster, more flexible and easier to read and maintain.
    Added "upgrade_BV42.pl".
    Enhanced support for Windows NT/95.
    Complete rewrite of this "CHANGES.txt" document.

Version 5.2   31.03.98

    Changed "Norm()", "<<" and ">>" to become more efficient.
    Added "new_Hex()", "new_Bin()", "new_Dec()" and "new_Enum()".
    Made the exception handling in "Vector.pm" more elegant.

Version 5.1   09.03.98

    Added systematic exception handling to "Vector.pm".

Version 5.0   01.03.98

 +  "Outsourced" all example modules (now available separately).
 +  Added: Word_Bits(), Long_Bits(), Concat(), Concat_List(), Primes(),
    Reverse(), Interval_Reverse(), Interval_Copy(), Interval_Substitute(),
    Lexicompare(), to_Bin(), from_Bin(), to_Dec(), from_Dec(), Bit_Copy(),
    LSB(), MSB(), lsb(), msb(), Insert(), Delete(), add(), subtract(),
    Negate(), Absolute(), Sign(), Multiply(), Divide(), GCD(), Block_Store(),
    Block_Read(), Word_Size(), Word_Store(), Word_Read(), Word_List_Store(),
    Word_List_Read(), Word_Insert(), Word_Delete(), Chunk_Store(),
    Chunk_Read(), Chunk_List_Store(), Chunk_List_Read(), Index_List_Remove(),
    Index_List_Store(), Index_List_Read(), Transpose().
 +  Ported to C: "Version()", "Shadow()", "Clone()", "to_Enum()",
    "from_Enum()".
 +  Changed: "Compare()" (now assumes bit vectors are SIGNED).
 +  Renamed: "to_String()" ==> "to_Hex()", "from_string()" ==> "from_Hex()",
    "to_ASCII()" ==> "to_Enum()", "from_ASCII()" ==> "from_Enum()"
    (aliases are still available but deprecated).
 +  Dropped: "lexorder()", "new_from_String()".
 +  Dropped: Module "Set::IntegerFast" (replaced by "Bit::Vector").
 +  Definitely abandoned the possibility for subclassing because it doesn't
    make any sense in this module (use embedding instead!).
 +  Fixed: Module "Set::IntegerRange" version 4.2 broke with "Bit::Vector"
    version 5.0. Issued quick fix "Set::IntRange" version 5.0. More
    thorough implementation is under construction.

Version 4.2   16.07.97

    Added "is_empty()" and "is_full()".

Version 4.1   30.06.97

    Added "Move_Left()" and "Move_Right()".
    Changed "<<" and ">>" to call "Move_Left()" and "Move_Right()" instead.
    Added "increment()" and "decrement()".
    Changed "++" and "--" to call "increment()" and "decrement()" instead.
    Added "Resize()", "Interval_Scan_inc()", "Interval_Scan_dec()" and
    "BitVector()" to "Set::IntegerRange".

Version 4.0   23.04.97

 +  Complete rewrite of the "Set::IntegerFast" module.
 +  Renamed "Set::IntegerFast" to "Bit::Vector".
 +  United the separate C cores and XS files for sets, matrices of booleans
    and bit shift operations in a single module.
 +  Abandoned the individual version numbers.
 +  Dropped the separate "Makefile.PL"s, adopted the solution using
    a "lib" subdirectory.
 +  Added: Flip(), Interval_Scan_inc(), Interval_Scan_dec(), rotate_left(),
    rotate_right(), shift_left(), shift_right(), to_String(), from_string(),
    Multiplication(), Closure(), Shadow(), Clone(), new_from_String(),
    to_ASCII(), from_ASCII().
 +  Added overloaded operators for: emptyness, equality, lexical comparison,
    shift register, rotate register, string conversion, union, intersection,
    difference, exclusive-or, complement, subset relationship, true subset
    relationship, superset relationship, true superset relationship, norm.

Version 3.2   04.02.97

    Added "Empty_Interval()", "Fill_Interval()", "Flip_Interval()" and
    "Size()" to "Set::IntegerFast" and "Set::IntegerRange".
    "Set::IntegerFast" and "Set::IntegerRange" both switched to version
    number 3.0.
    Improved the "Math::MatrixBool" module (new version number: 2.0) to
    use C routines for matrix multiplication and closure and fixed some
    bugs in these methods at the same time.
    Added "new_from_string()" and "Dim()" to "Math::MatrixBool".
    Fixed a severe bug in the "kleene()" method of "Math::MatrixReal"
    (new version number: 1.1).

Version 3.1   21.01.97

    Fixed a bug that caused the initialization routine of the module to fail
    on 64 bit machines due to a wrong conditional expression (type "int" and
    "size_t" do not necessarily have the same size!).
    "Set::IntegerFast" switched to version number 2.2.

Version 3.0   12.01.97

    Added "flip()" to "Set::IntegerFast" and "Set::IntegerRange".
    Transformed the "kruskal" demo program to a Perl module "Graph::Kruskal".
    Added new companion modules: "Math::MatrixBool", "Math::MatrixReal" and
    "DFA::Kleene", all with separate "Makefile.PL"s.
    Added introductory article about theory behind Kleene's algorithm.
    Introduced independent version numbers for all modules:
    "Set::IntegerFast" ==> version 2.1, "Set::IntegerRange" ==> version 2.0.
    Added overloaded operators to "Set::IntegerRange".
    Bugfix: Changed "gv_stashpv(class,0)" to "gv_stashpv(class,1)" in the
    XS file (caused core dumps in previous versions when "new()" was called
    with a nonexistent class name and subclassing enabled).

Version 2.0   14.12.96

    Changed "Create()" to "new()".
    Now supports "$set = new Set::IntegerFast($elements);" instead of
    "$set = Set::IntegerFast::Create($elements);".
    Changed "Destroy()" to "DESTROY()", which doesn't need to (and
    shouldn't!) be called explicitly anymore.
    Fixed the "bad free() ignored" warnings caused by "Destroy()" in
    version 1.1 (in conjunction with Perl version 5.002) which led some
    of the tests in "make test" to fail.
    Complete rewrite of the XS part.
    Changed "lexorder()" and "Compare()" to become more efficient
    (complexity n/b instead of n/8).
    Changed parameters visible externally from "word"/"unit" to "N_int"
    in the C core.
    Complete rewrite of the documentation, now in POD format.
    Added a new (wrapper) module named "Set::IntegerRange".

Version 1.1   08.01.96

    Added "Resize()".
    Changed "Create()", "Empty()", "Fill()" and "Copy()" to have complexity
    n/b rather than n/8.
    Made interfaces in C core more consistent: Pointer to a set object is
    now always the first parameter.
    Added new paragraphs to the documentation.
    Added "ExclusiveOr()" (for symmetric difference X = (Y + Z) \ (Y * Z)).

Version 1.0   14.12.95   First version under UNIX (with Perl module).

    Initial release as a C library and Perl module.

Version 0.9   01.11.93   First version of C library under MS-DOS.

    Ported the Pascal code to C because I thought sets of arbitrary sizes
    are always useful to have.

Version 0.1   ??.??.89   First version in Turbo Pascal under CP/M.

    I first wrote this library (on my Apple ][+) because I needed more bits
    in a set than Turbo Pascal would support in order to calculate "first",
    "follow" and "look-ahead" character sets for a compiler-compiler.

----------------------------------------------------------------------------

