Unit BitUtils;

// D. Rosseel
// Original: 10-08-2008
// Latest update: 24-03-2011

 
// interface

type TBit = byte;

//  ------------ "Bit" functions ----------------
  // The two following functions translate a byte expression into a "bit" Value (1 or 0).
  function Bit_(B: byte)   : TBit;        // returns the "bit" Value of B
  function NotBit(B: byte) : TBit;        // returns the inverted "bit" Value of B


//  ------------  Bit "Mask" functions ------------

  function BitMaskByte(Bitno: byte): byte;
  // Returns 2 to the power "Bitno": e.g. "BitMask[2]" equals "4".
  // Used to perform and and or functions to test, set or clear certain bits in a byte bits variable,
  // e.g. Var1 := Var1 or BitMaskByte(7); // set bit 7 in Var1
  
  function BitMaskWord(BitNo: byte): word;
  // Returns 2 to the power "Bitno": e.g. "BitMask[2]" equals "4".
  // Used to perform and and or functions to test, set or clear certain bits in a word variable,
  // e.g. Var1 := Var1 or BitMaskWord(12); // set bit 12 in Var1

  function BitMaskDWord(BitNo: byte): Dword;
  // Returns 2 to the power "Bitno": e.g. "BitMask[2]" equals "4".
  // Used to perform and and or functions to test, set or clear certain bits in a word variable,
  // e.g. Var1 := Var1 or BitMaskDword(20); // set bit 20 in Var1

  // The three following functions return the inverted Value with respect to the three above
  function BitMaskByteNot(Bitno: byte): byte;
  function BitMaskWordNot(BitNo: byte): word;
  function BitMaskDWordNot(BitNo: byte): Dword;
  
  
//  ------------  Bit "Stuff" functions ------------
  procedure StuffBits(var Bte: byte; Value, BitNr, Size: byte);
  // Sets the bits in "Bte", starting with "BitNr" and "Size" bits wide, to the Value "Value"
  
  procedure ClearBits(var Bte: byte; BitNr, Size: byte);
  // Clears (set to 0) the bits in Bte, starting with "BitNr" and "Size" bits wide.
  
  procedure SetBits  (var Bte: byte; BitNr, Size: byte);
  // Sets (set to 1) the bits in Bte, starting with "BitNr" and "Size" bits wide.
  
  function GetBits   (Bte, BitNr, Size: byte): byte;
  // Returns the Value of the bits in Bte, starting with "BitNr" and "Size" bits wide.


//  ------------  Bit "Array" functions ------------
  // These functions enable to create something like arrays of bits.
  // The bits are embedded in a byte array ("Arr" below).
  // The number of bits N is 8 * the number of bytes. The bits are numbered from 0..(N-1)
  // It is the reponsibility of the user to check that bitnumbers (or boolnumbers) are
  // always inside the byte array "Arr". No check is done for that.

  procedure Set_Bit(var Arr: array[10] of byte; Nr: byte; Value: byte);
  // Sets bit "Nr" to "1" in the array "Arr" if "Value" is "true", and
  // sets bit "Nr" to "0" in the array "Arr" if "Value" is "false".
  // "Nr" is the BITnumber in the array Arr (ranges from 0 to ((8 * SizeOf(Arr)) - 1))

  function  Get_Bit(var Arr: array[10] of byte; Nr: byte): byte;
  // Returns "True" if bit "Nr" in the array "Arr" is "1", and
  // returns "false" if bit "Nr" in the array "Arr" is "0".
  // "Nr" is the BITnumber in the array Arr (ranges from 0 to ((8 * SizeOf(Arr)) - 1))
  
  function Get_Bits(var Arr: array[16] of byte; Start, Stop: byte): Dword;
  // Returns a number representing the bits between the "Start" and "Stop" bitnumbers (both included)
  // in "Arr".
  // This function is the quivalent of "GetBits" but for an array in stead of a byte
  
//  ------------  Boolean "Array" functions ------------
  // These functions use a virtual array of bits (as above) as a Boolean array.
  // Only 1 bit per boolean value is needed.
  // The bits are embedded in a byte array ("Arr" below).
  // It is the reponsibility of the user to check that bitnumbers (or boolnumbers) are
  // always inside the byte array "Arr". No check is done for that.

  procedure SetBool(var Arr: array[10] of byte; Nr: byte; Value: boolean);
  // Sets bit "Nr" to "1" in the array "Arr" if "Value" is "true", and
  // sets bit "Nr" to "0" in the array "Arr" if "Value" is "false".
  // "Nr" is the BITnumber in the array Arr (ranges from 0 to ((8 * SizeOf(Arr)) - 1))
  
  function  GetBool(var Arr: array[10] of byte; Nr: byte): boolean;
  // Returns "True" if bit "Nr" in the array "Arr" is "1", and
  // returns "false" if bit "Nr" in the array "Arr" is "0".
  // "Nr" is the BITnumber in the array Arr (ranges from 0 to ((8 * SizeOf(Arr)) - 1))