BitMan v1.0                Documentation of BitMan16.TPU *
Copyright 1998, Top Speed Software - All rights reserved *
**********************************************************

Introduction:
-------------

BitMan is a Turbo Pascal unit that allows the user to manipulate single
bits in arrays. This is very useful when writing e.g. compression
programs. 
All procedures and functions in this package are coded in Inline
assembly, which makes them *really* fast (up to 10 times faster than
concurrent products ;) )

BitMan is Shareware. This means you may use it for PRIVATE
purposes, and freely distribute it. For institutional, educational or
commercial usage (which includes use in shareware/freeware
products), REGISTRATION is required. This costs $10 (see below).
All registered users will receive a copy of the source code.     

Instructions:
-------------

There are 2 versions of this unit: a 16-bit one and a 32-bit one. Both
versions will work with the ordinary TP6 or TP7, in the ordinary
16-bit mode. The only restriction is that the 32-bit version only works
on 386 or higher.

*** Important ***
-----------------

Before you proceed any further, read the following notes carefully:
- If you use this unit, this is *entirely* at your OWN risk. The author
  will NOT take ANY responsibility for the (mis)use of this package.
- This unit is designed for speed, and pure speed. For speed's sake,
  ALL ERROR/RANGE CHECKING IS OMITTED. This means it is
  entirely your responsibility to use the procedures and functions
  correctly. Not doing this will easily cause the computer to hang or
  give other unpredictable results, and again, the author is NOT
  responsible for any possible harm caused by this.
Keep this in mind.

The following instructions apply to the 16-bit version. 
Note that the 16-bit version has some restrictions which the 32-bit
version doesn't have; however, the 16-bit version is faster, about 30 to 40 %.

If you use Turbo Pascal 6, unzip the file TP6UNITS.ZIP to the TP
directory. For Turbo Pascal 7, use TP7UNITS.ZIP.
Programs that use BitMan must have the following line included:

    uses BitMan16;  

An array of bytes (or words / longints) has to be defined, like this:

    var ByteArray: array[1..1000] of byte;  { equals 8000 bits  }
        WordArray: array[1..4000] of word;  { equals 64000 bits }    

The array length that can be covered is restricted to 65530 bits (which
means 8191 bytes!). In the 32 bit version, the maximum array length is 
approx. 65500 bytes (Turbo Pascal's limit). 
All arrays used by BitMan must reside in the Data segment (not
addressed with pointers).

Listing of procedures and functions (the Interface part of the unit):
*********************************************************************

Interface

var BitCount: word;

procedure AssignBitArray(Parray: pointer);
procedure AssignBoolArray(PArray: pointer);

procedure SetBit(BitNo: word);
procedure SetCurrentBit;
procedure ClearBit(BitNo: word);
procedure ClearCurrentBit;
procedure ToggleBit(BitNo: word);
procedure ToggleCurrentBit;
function  GetBit(BitNo: word): boolean;
function  GetCurrentBit: boolean;

procedure PutValue(BitNo, value, NumBits: word);
function  GetValue(BitNo, NumBits: word): word;

procedure BoolToBit(BoolArrayLength: word);
procedure BitToBool(BitArrayLength: word);

******************************************************

Explanation:
------------

Let's take an array[1..1000] of byte.

    var BitArray: array[1..1000] of byte; { equals 8000 bits }

Within this unit, these bits are numbered from 1 to 8000. This is
independent from the numbers used to define your array, so if you have
an array[10..12] of byte (24 bits long), the bits will
still be numbered from 1 to 24. Note that bit #0 is ILLEGAL, as well
as bit #65535, and, in the case of BitArray, all other numbers above 8000. 
Trying to access these bits will cause 'strange' results, since NO range 
checking is performed.
First of all, the array *must* be assigned, letting the unit know the
place in memory of the array you want to use:

    AssignBitArray(@BitArray);
    (@Bitarray means the Pointer to BitArray)

Procedure SetBit sets a desired bit (gives it the value '1'); for example:

    SetBit(256);

will set the value of bit #256 to '1' (turns it 'on').
In the same way, 

    ClearBit(256);

will set the value of bit #256 to '0' (turns it 'off'), and:

    ToggleBit(256);

will toggle bit #256 (if it had the value '1', it becomes '0' and vice
versa).
If you want to check the value of a bit, you would use the GetBit
function, which returns a boolean type variable (TRUE if the bit has
value '1', FALSE if the value is '0'), for example:

    If GetBit(256) then writeln('Bit #256 has the value 1') 
                           else writeln('Bit #256 has the value 0');

There is another way of manipulating bits. When you want to
manipulate a number of bits in succession, this is an alternative:

    for BitCount:=1 to 4000 do SetCurrentBit;

This sets the first 4000 bits in the array. 
The procedures SetCurrentBit, ClearCurrentBit, ToggleCurrentBit
and the function GetCurrentBit look at the value of BitCount to know
which bit to handle. This is faster than using Setbit(BitNumber), etc.
Another example:

    for BitCount:=1 to 32 do if GetCurrentBit then write('1) else
    write('0');

This writes the value stored in the first 32 bits of the array (e.g. by
PutValue, see below) to the screen, in binary. 

(Note: the bits in the array are ordered as follows:

BYTE 1                          | BYTE 2
#8 #7 #6 #5 #4 #3 #2 #1 | #16 #15 #14 #13 #12 #11 #10 #9 etc.

This is done for speed's sake. The order 1,2,3,4,5,6,7,8 etc. would be
slower to handle)

If you are writing e.g. compression programs, you may want to insert
values of a varying number of bits into the array. For example:

    (var MyVal: word;)    
    PutValue(100, MyVal, 12);

This inserts the value of MyVal into the array, starting at bit #100, and
using 12 bits.
Note that, when using 12 bits, the value of MyVal has to be in the
range of 0..2^12 (2 to the power of 12 = 4096). 
You can use any amount of bits, with 16 as a maximum. 
If you want to restore a value of n bits from the array, starting at bit
#100, you would do for example:

    (var n, MyVal: word;)
    n:=NumberOfBits; { range 0..16 }
    MyVal:=GetValue(100, n); 

It is possible to store all the bits in the array into an array of Boolean
for more convenient handling.
This array of Boolean must be assigned first. Example:

    var BitArray: array[1..1000] of byte; { equals 8000 bits }
    var BoolArray: array[1..8000] of boolean; 
    
    begin
    AssignBitArray(@BitArray);
    AssignBoolArray(@BoolArray);
    {... some code ...}
    BitToBool(1000);
    {... some more code ...}
    BoolToBit(8000);
    end.

This stores the 8000 bits in BitArray, as booleans in BoolArray, and
back again. Note that you have to pass the number of bytes of BitArray 
to the procedure BitToBool, and the number of bytes of BoolArray to BoolToBit. 
For an exact copy, the array holding the Booleans must be exactly 8 times 
larger than the array holding the bits. Beware of the sizes of the arrays 
(remember - no range checking!).

Registration:
-------------

The registration costs US $10. I also accept DM 20 or Hfl 15 (Dutch
Guilders - preferred and cheaper!). No other currencies please.
To register, please send an e-mail to:

    E-mail: SpeedSoftware@iname.com

It should contain the following information: your FULL name, FULL address,
E-mail address, company name (if applicable), and a description of WHERE
you obtained this package.
As soon as I receive this, I will send the address to which the money
(in cash) has to be sent.

All routines in this unit have been tested thoroughly, with TP7 running
both under Win95 and in native DOS mode (TP6 in DOS mode only). However, 
IF you find a bug, please report it to the E-mail address above!
Questions, comments, critics, suggestions etc. are welcome too.
All registered users receive a copy of the source code and all further
updates (if there will be any).
If you use BitMan, please support the Shareware concept and REGISTER.
Remember, if you use BitMan for ANY other than private purposes
(such as commercial, institutional or educational use, or use in
shareware/freeware products), you are OBLIGED to register.

**************
Copyright Info
**************

BitMan is Copyright, 1998 by Top Speed Software. All rights reserved.
This package is Shareware. It may be distributed freely, as long as NO
modifications are made to ANY of the files contained in this package.










