const type: lsbBitStream

Type to read bitwise data starting with the least significant bit. This is used by the Huffman compression (as part of the deflate compression) used for ZIP and GZIP files. It is also used by the Lempel-Ziv-Welch compression used for GIF files. In an lsbBitStream the read direction is from LSB (least significant bit) to MSB (most significant bit). For the bit position in a byte holds: 0 = LSB, 7 = MSB.

const type: msbBitStream

Type to read bitwise data starting with the most significant bit. This is used by the Huffman compression used for JPEG files. In an msbBitStream the read direction is from MSB (most significant bit) to LSB (least significant bit). For the bit position in a byte holds: 0 = MSB, 7 = LSB.

const type: reverseBitStream

Type describing a stream of bits that is read backwards. The bits are read from the most significant bit of the last byte to the least significant bit of the first byte.

const array array integer: reverseBits

Array to reverse the bits of small numbers. The first index is the number of bits to be reversed (between 2 and 9). The second index is the number for which the bits should be reversed.

reverseBits[2][2#10]      returns  2#1
reverseBits[4][2#1101]    returns  2#1011
reverseBits[6][2#110101]  returns  2#101011

const func lsbBitStream: openLsbBitStream (in file: inFile)

Open an LSB bit stream from the file inFile for reading. In an lsbBitStream the read direction is from LSB (least significant bit) to MSB (most significant bit).

const func lsbBitStream: openLsbBitStream (in string: stri)

Open an LSB bit stream from the string stri for reading. In an lsbBitStream the read direction is from LSB (least significant bit) to MSB (most significant bit).

const proc: close (inout lsbBitStream: inBitStream)

Close an LSB bit stream and position the underlying file at the next byte.

const func integer: getBit (inout lsbBitStream: inBitStream)

Get one bit in LSB-First order from inBitStream. The bit is read at the current byte and bit position. Afterwards byte and bit position are advanced by one bit. The read direction is from LSB (least significant bit) to MSB (most significant bit).

aBitStream := openLsbBitStream("\2#01101011;\2#11001110;");
skipBits(aBitStream, 5);
# Original data:  "\2#01101011;\2#11001110;"
#                       ^
#                    current
#                   position
getBit(aBitStream)  returns  2#1
# Original data:  "\2#01101011;\2#11001110;"
#                       1
#                    bit of
#                  the result
# Now aBitStream is at bytePos=1 and bitPos=6 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                      ^
#                   current
#                  position

Parameters:

inBitStream - LSB orderd bit stream from which the bit is read.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const func integer: getBits (inout lsbBitStream: inBitStream, in integer: bitWidth)

Get bitWidth bits in LSB-First order from inBitStream. The bits are read at the current byte and bit position. Afterwards byte and bit position are advanced by bitWidth bits. The read direction is from LSB (least significant bit) to MSB (most significant bit). If bits from the next byte(s) are read a byte order of little-endian is used.

aBitStream := openLsbBitStream("\2#01101011;\2#11001110;");
skipBits(aBitStream, 5);
# Original data:  "\2#01101011;\2#11001110;"
#                       ^
#                    current
#                   position
getBits(aBitStream, 5)  returns  2#10011
# Original data:  "\2#01101011;\2#11001110;"
#                     011               10
#                 lower bits        higher bits
#                  of result         of result
# Now aBitStream is at bytePos=2 and bitPos=2 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                                      ^
#                                   current
#                                   position

Parameters:

inBitStream - LSB orderd bit stream from which the bits are read.

bitWidth - Number of bits requested.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const func integer: peekBits (inout lsbBitStream: inBitStream, in integer: bitWidth)

Peek bitWidth bits in LSB-First order from inBitStream. The bits are read at the current byte and bit position. Byte and bit position remain unchanged. The read direction is from LSB (least significant bit) to MSB (most significant bit). If bits from the next byte(s) are read a byte order of little-endian is used.

aBitStream := openLsbBitStream("\2#01101011;\2#10101101;");
skipBits(aBitStream, 5);
# Original data:  "\2#01101011;\2#10101101;"
#                       ^
#                    current
#                   position
peekBits(aBitStream, 6)  returns  2#101011
# Original data:  "\2#01101011;\2#10101101;"
#                     011              101
#                 lower bits        higher bits
#                  of result         of result
# BytePos and bitPos of aBitStream have not changed.

Parameters:

inBitStream - LSB orderd bit stream from which the bits are peeked.

bitWidth - Number of bits requested.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const proc: skipBits (inout lsbBitStream: inBitStream, in integer: bitWidth)

Advance the bit position of inBitStream by bitWidth bits.

aBitStream := openLsbBitStream("\2#01101011;\2#11001110;");
# Now aBitStream has bytePos=1 and bitPos=0 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                            ^
#                         current
#                        position
skipBits(aBitStream, 5);
# Now aBitStream is at bytePos=1 and bitPos=5 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                       ^
#                    current
#                   position

Parameters:

inBitStream - LSB orderd bit stream from which the bits are skipped.

bitWidth - Number of bits to be skipped.

const func string: gets (inout lsbBitStream: inBitStream, in integer: maxLength)

Get up to maxLength bytes from inBitStream. The function returns bytes from the original data. If the current byte of inBitStream is partially used, it is not considered, and the bytes are read beginning with the next byte from the original data. After the data is read, the position of inBitStream is advanced to the beginning of the next byte. A maxLength of 0 sets the position to the beginning of the next byte and returns an empty string.

aBitStream := openLsbBitStream("\2#01101011;\2#1001111;\2#1001011;\2#1101;");
skipBits(aBitStream, 5);
# Original data:  "\2#01101011;\2#1001111;\2#1001011;\2#1101;"
#                       ^
#                    current
#                   position
gets(aBitStream, 2)  returns "\2#1001111;\2#1001011;" (="OK")

Parameters:

inBitStream - LSB orderd bit stream from which the bytes are read.

maxLength - The maximum number of bytes to be read.

Raises:

RANGE_ERROR - The parameter maxLength is negative.

const func msbBitStream: openMsbBitStream (in file: inFile)

Open an MSB bit stream from the file inFile for reading. In an msbBitStream the read direction is from MSB (most significant bit) to LSB (least significant bit).

const func msbBitStream: openMsbBitStream (in string: stri)

Open an MSB bit stream from the string stri for reading. In an msbBitStream the read direction is from MSB (most significant bit) to LSB (least significant bit).

const proc: close (inout msbBitStream: inBitStream)

Close an MSB bit stream and position the underlying file at the next byte.

const func integer: getBit (inout msbBitStream: inBitStream)

Get one bit in MSB-First order from inBitStream. The bits are read at the current byte and bit position. Afterwards byte and bit position are advanced by bitWidth bits. The read direction is from MSB (most significant bit) to LSB (least significant bit). If bits from the next byte(s) are read a byte order of big-endian is used.

aBitStream := openMsbBitStream("\2#01011100;\2#11010110;");
skipBits(aBitStream, 5);
# Original data:  "\2#01011100;\2#11010110;";
#                          ^
#                       current
#                      position
getBit(aBitStream)  returns  2#1
# Original data:  "\2#01011100;\2#11010110;";
#                          1
#                       bit of
#                     the result
# Now aBitStream is at bytePos=1 and bitPos=6 of the original data.
# Original data:  "\2#01011100;\2#11010110;";
#                           ^
#                        current
#                       position

Parameters:

inBitStream - MSB orderd bit stream from which the bits are peeked.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const func integer: getBits (inout msbBitStream: inBitStream, in integer: bitWidth)

Get bitWidth bits in MSB-First order from inBitStream. The bits are read at the current byte and bit position. Afterwards byte and bit position are advanced by bitWidth bits. The read direction is from MSB (most significant bit) to LSB (least significant bit). If bits from the next byte(s) are read a byte order of big-endian is used.

aBitStream := openMsbBitStream("\2#01011100;\2#11010110;");
skipBits(aBitStream, 5);
# Original data:  "\2#01011100;\2#11010110;";
#                          ^
#                       current
#                      position
getBits(aBitStream, 5)  returns  2#10011
# Original data:  "\2#01011100;\2#11010110;";
#                          100    11
#                   higher bits  lower bits
#                    of result    of result
# Now aBitStream is at bytePos=2 and bitPos=2 of the original data.
# Original data:  "\2#01011100;\2#11010110;";
#                                   ^
#                                current
#                                position

Parameters:

inBitStream - MSB orderd bit stream from which the bits are peeked.

bitWidth - Number of bits requested.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const func integer: peekBits (inout msbBitStream: inBitStream, in integer: bitWidth)

Peek bitWidth bits in MSB-First order from inBitStream. The bits are read at the current byte and bit position. Byte and bit position remain unchanged. The read direction is from MSB (most significant bit) to LSB (least significant bit). If bits from the next byte(s) are read a byte order of big-endian is used.

aBitStream := openMsbBitStream("\2#01011100;\2#11010110;");
skipBits(aBitStream, 5);
# Original data:  "\2#01011100;\2#11010110;";
#                          ^
#                       current
#                      position
peekBits(aBitStream, 6)  returns  2#100110
# Original data:  "\2#01011100;\2#11010110;";
#                          100    110
#                   higher bits  lower bits
#                    of result    of result
# BytePos and bitPos of aBitStream have not changed.

Parameters:

inBitStream - MSB orderd bit stream from which the bits are read.

bitWidth - Number of bits requested.

Raises:

RANGE_ERROR - If the end of inBitStream has been reached.

const proc: skipBits (inout msbBitStream: inBitStream, in integer: bitWidth)

Advance the bit position of inBitStream by bitWidth bits.

aBitStream := openMsbBitStream("\2#01101011;\2#11001110;");
# Now aBitStream has bytePos=1 and bitPos=0 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                     ^
#                  current
#                 position
skipBits(aBitStream, 5);
# Now aBitStream is at bytePos=1 and bitPos=5 of the original data.
# Original data:  "\2#01101011;\2#11001110;"
#                          ^
#                       current
#                      position

Parameters:

inBitStream - MSB orderd bit stream from which the bits are skipped.

bitWidth - Number of bits to be skipped.

const func string: gets (inout msbBitStream: inBitStream, in integer: maxLength)

Get up to maxLength bytes from inBitStream. The function returns bytes from the original data. If the current byte of inBitStream is partially used, it is not considered, and the bytes are read beginning with the next byte from the original data. After the data is read, the position of inBitStream is advanced to the beginning of the next byte. A maxLength of 0 sets the position to the beginning of the next byte and returns an empty string.

aBitStream := openMsbBitStream("\2#01101011;\2#1001111;\2#1001011;\2#1101;");
skipBits(aBitStream, 5);
# Original data:  "\2#01101011;\2#1001111;\2#1001011;\2#1101;"
#                       ^
#                    current
#                   position
gets(aBitStream, 2)  returns "\2#1001111;\2#1001011;" (="OK")

Parameters:

inBitStream - MSB orderd bit stream from which the bytes are read.

maxLength - The maximum number of bytes to be read.

Raises:

RANGE_ERROR - The parameter maxLength is negative.

const proc: putBitLsb (inout string: stri, inout integer: bitPos, in integer: bit)

Append one bit in LSB-First order to stri. The bit is appended to stri at the current bit position. Afterwards the bit position is advanced by one bit. The append direction is from LSB (least significant bit) to MSB (most significant bit). If necessary stri is enlarged.

Parameters:

stri - String of bytes to which the bit is appended.

bitPos - Current bit position between 0 (=LSB) and 7 (=MSB).

bit - Bit to be appended to stri.

const proc: putBitsLsb (inout string: stri, inout integer: bitPos, in var integer: bits, in var integer: bitWidth)

Append bitWidth bits in LSB-First order to stri. The bits are appended to stri at the current bit position. Afterwards the bit position is advanced by bitWidth bits. The append direction is from LSB (least significant bit) to MSB (most significant bit). If necessary stri is enlarged with bytes in little-endian byte order.

stri := "\2#01011;"; bitPos := 5;
putBitsLsb(stri, bitPos, 2#10011, 5);
# Now holds:  stri = "\2#01101011;\2#10;"  and  bitPos = 2
#                        011         10
#                     appended    appended
#                    lower bits  higher bits

Parameters:

stri - String of bytes to which the bits are appended.

bitPos - Current bit position between 0 (=LSB) and 7 (=MSB).

bits - Bits to be appended to stri.

bitWidth - Number of bits to be appended (width of bits).

const proc: putBitMsb (inout string: stri, inout integer: bitPos, in integer: bit)

Append one bit in MSB-First order to stri. The bit is appended to stri at the current bit position. Afterwards the bit position is advanced by one bit. The append direction is from MSB (most significant bit) to LSB (least significant bit). If necessary stri is enlarged.

Parameters:

stri - String of bytes to which the bit is appended.

bitPos - Current bit position between 0 (=MSB) and 7 (=LSB).

bit - Bit to be appended to stri.

const proc: putBitsMsb (inout string: stri, inout integer: bitPos, in var integer: bits, in var integer: bitWidth)

Append bitWidth bits in MSB-First order to stri. The bits are appended to stri at the current bit position. Afterwards the bit position is advanced by bitWidth bits. The append direction is from MSB (most significant bit) to LSB (least significant bit). If necessary stri is enlarged with bytes in big-endian byte order.

stri := "\2#01011000;";
putBitsMsb(stri, bitPos, 2#10011, 5);
# Now holds  stri = "\2#01011100;\2#11000000;"  and  bitPos = 2
#                            100    11
#                        appended  appended
#                     higher bits  lower bits

Parameters:

stri - String of bytes to which the bits are appended.

bitPos - Current bit position between 0 (=MSB) and 7 (=LSB).

bits - Bits to be appended to stri.

bitWidth - Number of bits to be appended (width of bits).

const proc: putBitLsb (inout file: outFile, inout integer: bitPos, in integer: bit)

Write one bit in LSB-First order to outFile. The bit is appended to outFile at the current bit position. Afterwards the bit position is advanced by one bit. The append direction is from LSB (least significant bit) to MSB (most significant bit). Bits are cached in outFile.bufferChar until a complete byte is present. Complete bytes in outFile.bufferChar are written to outFile.

Parameters:

outFile - File of bytes to which the bit is written.

bitPos - Current bit position between 0 (=LSB) and 7 (=MSB).

bit - Bit to be written to outFile.

const proc: putBitsLsb (inout file: outFile, inout integer: bitPos, in var integer: bits, in var integer: bitWidth)

Write bitWidth bits in LSB-First order to outFile. The bits are appended to outFile at the current bit position. Afterwards the bit position is advanced by bitWidth bits. The append direction is from LSB (least significant bit) to MSB (most significant bit). Bits are cached in outFile.bufferChar until a complete byte is present. Complete bytes in outFile.bufferChar are written to outFile.

Parameters:

outFile - File of bytes to which the bits is written.

bitPos - Current bit position between 0 (=LSB) and 7 (=MSB).

bits - Bits to be written to outFile.

bitWidth - Number of bits to be written (width of bits).

const proc: putBitMsb (inout file: outFile, inout integer: bitPos, in integer: bit)

Write one bit in MSB-First order to outFile. The bit is appended to outFile at the current bit position. Afterwards the bit position is advanced by one bit. The append direction is from MSB (most significant bit) to LSB (least significant bit). Bits are cached in outFile.bufferChar until a complete byte is present. Complete bytes in outFile.bufferChar are written to outFile.

Parameters:

outFile - File of bytes to which the bit is written.

bitPos - Current bit position between 0 (=MSB) and 7 (=LSB).

bit - Bit to be written to outFile.

const proc: putBitsMsb (inout file: outFile, inout integer: bitPos, in var integer: bits, in var integer: bitWidth)

Write bitWidth bits in MSB-First order to outFile. The bits are appended to outFile at the current bit position. Afterwards the bit position is advanced by bitWidth bits. The append direction is from MSB (most significant bit) to LSB (least significant bit). Bits are cached in outFile.bufferChar until a complete byte is present. Complete bytes in outFile.bufferChar are written to outFile.

Parameters:

outFile - File of bytes to which the bits is written.

bitPos - Current bit position between 0 (=MSB) and 7 (=LSB).

bits - Bits to be written to outFile.

bitWidth - Number of bits to be written (width of bits).

const func reverseBitStream: reverseBitStream (inout file: inFile, in integer: length)

Create a reverse bit stream from length bytes read from inFile.

const func integer: bitsStillInStream (in reverseBitStream: inBitStream)

Return the number of bits still present in the given reverse inBitStream. Note that it is possible to read beyond the end fo the stream. In this case negative values are returned.

const func integer: bitsRead (in reverseBitStream: inBitStream)

Return the number of bits read from the given reverse inBitStream. Note that it is possible to read beyond the end fo the stream. So the function might return more bits than actually present.

const func integer: getBits (inout reverseBitStream: inBitStream, in integer: bitWidth)

Get bitWidth bits from the given reverse inBitStream. The bits are read from the most significant bit of the last byte to the least significant bit of the first byte. It is possible to read beyond the end of the stream. In this case the stream is assumed to consist of zero bytes.