const type: lsbInBitStream

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 a lsbInBitStream 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: msbInBitStream

Type to read bitwise data starting with the most significant bit. This is used by the Huffman compression used for JPEG files. In a msbInBitStream 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: lsbOutBitStream

Type to write bitwise data starting with the least significant bit. In a lsbOutBitStream the write direction is from LSB (least significant bit) to MSB (most significant bit). For the bit position in a byte (bitPos) holds: 0 = LSB, 7 = MSB. The bits are stored in a string of bytes. The byte string can be obtained with the function getBytes(). The function flush() can be used to add a partially filled byte to the byte string. This bit encoding 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.

const type: msbOutBitStream

Type to write bitwise data starting with the most significant bit. In a msbOutBitStream the write direction is from MSB (most significant bit) to LSB (least significant bit). For the bit position in a byte (bitSize) holds: 0 = MSB, 7 = LSB. The bits are stored in a string of bytes. The byte string can be obtained with the function getBytes(). The function flush() can be used to add a partially filled byte to the byte string. This bit encoding is used by the Huffman compression used for JPEG files.

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 lsbInBitStream: openLsbInBitStream (in file: inFile)

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

const func lsbInBitStream: openLsbInBitStream (in string: stri)

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

const proc: close (inout lsbInBitStream: inBitStream)

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

const func integer: getBit (inout lsbInBitStream: 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 := openLsbInBitStream("\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 lsbInBitStream: 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 := openLsbInBitStream("\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 lsbInBitStream: 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 := openLsbInBitStream("\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 lsbInBitStream: inBitStream, in integer: bitWidth)

Advance the bit position of inBitStream by bitWidth bits.

aBitStream := openLsbInBitStream("\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 boolean: eof (in lsbInBitStream: inBitStream)

Determine if at least one bit beyond the bit stream has been read. The EOF condition is also met if skipBits() skips at least one bit beyond the bit stream.

Parameters:

inBitStream - MSB orderd bit stream which is checked for EOF.

const func string: gets (inout lsbInBitStream: 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 := openLsbInBitStream("\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 msbInBitStream: openMsbInBitStream (in file: inFile)

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

const func msbInBitStream: openMsbInBitStream (in string: stri)

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

const proc: close (inout msbInBitStream: inBitStream)

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

const func integer: getBit (inout msbInBitStream: 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 := openMsbInBitStream("\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 msbInBitStream: 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 := openMsbInBitStream("\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 msbInBitStream: 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 := openMsbInBitStream("\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 msbInBitStream: inBitStream, in integer: bitWidth)

Advance the bit position of inBitStream by bitWidth bits.

aBitStream := openMsbInBitStream("\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 boolean: eof (in msbInBitStream: inBitStream)

Determine if at least one bit beyond the bit stream has been read. The EOF condition is also met if skipBits() skips at least one bit beyond the bit stream.

Parameters:

inBitStream - MSB orderd bit stream which is checked for EOF.

const func string: gets (inout msbInBitStream: 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 := openMsbInBitStream("\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: putBit (inout lsbOutBitStream: outBitStream, in integer: bit)

Append one bit in LSB-First order to outBitStream. The append direction is from LSB (least significant bit) to MSB (most significant bit).

# Stream data:   "\2#0101011;"  and  bitPos = 7
#                   ^
#                current
#               position
putBit(aBitStream, 2#1)
# Stream data:  "\2#10101011;"  and  bitPos = 0
#                   1
#                appended
#                  bit
putBit(aBitStream, 2#1)
# Stream data:  "\2#10101011;\2#1;"  and  bitPos = 1
#                               1
#                            appended
#                              bit

Parameters:

outBitStream - Bit stream to which the bit is appended.

bit - Bit to be appended to outBitStream.

const proc: putBits (inout lsbOutBitStream: outBitStream, in integer: bits, in integer: bitWidth)

Append bitWidth bits in LSB-First order to outBitStream. The append direction is from LSB (least significant bit) to MSB (most significant bit). If necessary additional bytes are added to stristri.

# Stream data:     "\2#01011;"  and  bitPos = 5
#                     ^
#                  current
#                 position
putBits(aBitStream, 2#10011, 5);
# Stream data:  "\2#01101011;\2#10;"  and  bitPos = 2
#                   011         10
#                appended    appended
#               lower bits  higher bits

Parameters:

outBitStream - Bit stream to which the bits are appended.

bits - Bits to be appended to outBitStream.

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

const func integer: length (in lsbOutBitStream: outBitStream)

Obtain the length of the given outBitStream. The bit stream length is measured in bits.

Parameters:

outBitStream - Bit stream from which the length is obtained.

Returns:

the length of the bit stream.

const proc: truncate (inout lsbOutBitStream: outBitStream, in integer: length)

Truncate outBitStream to the given length. If the bit stream previously was larger than length, the extra data is lost. If the bit stream previously was shorter, it is extended, and the extended part is filled with zero bits.

Parameters:

outBitStream - Bit stream to be truncated.

length - Requested length of outBitStream in bits.

Raises:

RANGE_ERROR - The requested length is negative.

const proc: flush (inout lsbOutBitStream: outBitStream)

Complete a partially filled byte and add it to the byte string. If outBitStream has a partially filled byte it is filled with zero bits and added to the byte string. If outBitStream has not a partially filled byte nothing is done.

Parameters:

outBitStream - Bit stream where the partially filled byte is added.

const func string: getBytes (inout lsbOutBitStream: outBitStream)

Obtain the byte string created from the bits written to outBitStream. The returned byte string is removed from outBitStream. A partially filled byte is not part of the returned byte string. The function flush() can be called in advance to add a partially filled byte to the byte string.

Parameters:

outBitStream - Bit stream from which the byte string is obtained.

Returns:

a string of completely filled bytes from outBitStream.

const proc: write (inout lsbOutBitStream: outBitStream, in string: stri)

Add the given string stri to the byte string of outBitStream. The outBitStream is flushed before adding stri.

Parameters:

outBitStream - Bit stream to which stri is added.

stri - String to be added to outBitStream.

const proc: putBit (inout msbOutBitStream: outBitStream, in integer: bit)

Append one bit in MSB-First order to outBitStream. The append direction is from MSB (most significant bit) to LSB (least significant bit).

# Stream data:  "\2#01011100;"  and  bitPos = 7
#                          ^
#                       current
#                       position
putBit(aBitStream, 2#1)
# Stream data:  "\2#01011101;"  and  bitPos = 0
#                          1
#                       appended
#                         bit
putBit(aBitStream, 2#1)
# Stream data:  "\2#01011101;\2#10000000;"  and  bitPos = 1
#                               1
#                            appended
#                              bit

Parameters:

outBitStream - Bit stream to which the bit is appended.

bit - Bit to be appended to outBitStream.

const proc: putBits (inout msbOutBitStream: outBitStream, in integer: bits, in integer: bitWidth)

Append bitWidth bits in MSB-First order to outBitStream. The append direction is from MSB (most significant bit) to LSB (least significant bit). If necessary additional bytes are added to outBitStream.

# Stream data:  "\2#01011000;"  and  bitPos = 5
#                        ^
#                     current
#                    position
putBitsMsb(stri, bitPos, 2#10011, 5);
# Stream data:  "\2#01011100;\2#11000000;"  and  bitPos = 2
#                        100    11
#                    appended  appended
#                 higher bits  lower bits

Parameters:

outBitStream - Bit stream to which the bits are appended.

bits - Bits to be appended to outBitStream.

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

const func integer: length (in msbOutBitStream: outBitStream)

Obtain the length of the given outBitStream. The bit stream length is measured in bits.

Parameters:

outBitStream - Bit stream from which the length is obtained.

Returns:

the length of the bit stream.

const proc: truncate (inout msbOutBitStream: outBitStream, in integer: length)

Truncate outBitStream to the given length. If the bit stream previously was larger than length, the extra data is lost. If the bit stream previously was shorter, it is extended, and the extended part is filled with zero bits.

Parameters:

outBitStream - Bit stream to be truncated.

length - Requested length of outBitStream in bits.

Raises:

RANGE_ERROR - The requested length is negative.

const proc: flush (inout msbOutBitStream: outBitStream)

Complete a partially filled byte and add it to the byte string. If outBitStream has a partially filled byte it is filled with zero bits and added to the byte string. If outBitStream has not a partially filled byte nothing is done.

Parameters:

outBitStream - Bit stream where the partially filled byte is added.

const func string: getBytes (inout msbOutBitStream: outBitStream)

Obtain the byte string created from the bits written to outBitStream. The returned byte string is removed from outBitStream. A partially filled byte is not part of the returned byte string. The function flush() can be called in advance to add a partially filled byte to the byte string.

Parameters:

outBitStream - Bit stream from which the byte string is obtained.

Returns:

a string of completely filled bytes from outBitStream.

const proc: write (inout msbOutBitStream: outBitStream, in string: stri)

Add the given string stri to the byte string of outBitStream. The outBitStream is flushed before adding stri.

Parameters:

outBitStream - Bit stream to which stri is added.

stri - String to be added to outBitStream.

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.