LeftOverByteCount abstract method

Project: I/O Utility Classes

Unit: PJPipeFilters

Class: TPJPipeFilter

Applies to: ~>1.0

function LeftOverByteCount(const RawData: TBytes): Integer; virtual; abstract;

Description

Returns the number of bytes at end of the given byte array that cannot be processed yet.

The single parameter, RawData is a byte array containing raw unprocessed data that has yet to be filtered. The data formats used by some filters are multi-byte and RawData may be not contain a complete meaningful sequence of bytes at the end of the array. In these cases the meaningless bytes are carried forward until the next pipe read when they are prepended to the next chunk of data read from the pipe.

Implementations must calculate the maximum amount data from the byte array that can be processed and therefore work out how many bytes are to be carried forward. That number must be returned from the function.

Remarks

The type of the RawData byte array parameter is TBytes. In versions of Delphi that do not defined TBytes in SysUtils the PJPipeFilters unit defines TBytes as array of Byte.

Examples

TPJUnicodeBMPPipeFilter reads Unicode strings comprising characters from the Basic Multilingual Plane, which means that that each character always occupies two bytes.

Therefore if RawData has an odd number of bytes the last byte is meaningless until more data is read and so this last byte needs to be carried forward. In this case 1 is returned from the function. If an even number of bytes is read then all the bytes encode characters and can be processed, so 0 is returned.

Here is the implementation of this method in TPJUnicodeBMPPipeFilter:

function TPJUnicodeBMPPipeFilter.LeftOverByteCount(
  const RawData: TBytes): Integer;
begin
  Result := Length(RawData) mod SizeOf(WideChar);
end;

The implementation in TPJAnsiSBCSPipeFilter is simpler. Because the class reads single byte character sets, where every byte represents a different character, it can always process all the bytes in RawData. Therefore the implementation of this method in TPJAnsiSBCSPipeFilter is simply:

function TPJAnsiSBCSPipeFilter.LeftOverByteCount(
  const RawData: TBytes): Integer;
begin
  Result := 0;
end;