How to write filters that extend the functionality of the TStream classes

Why do it?

In Java there are various predefined stream classes that provide filters for other stream classes. The filter classes essentially "wrap" the streams they operate on and can often be applied to further filters. This article demonstrates how we can do this in Delphi in a way that is extendable – i.e. we can wrap filters around other filters.

How it's done

First of all, let's look at why we want to do this. Well, say you want to write some data primitives as text to a stream and for the text to be formatted to fit on a page, word wrapping properly. Then, if we can wrap a filter that formats the primitives around another that formats the text and this filter is wrapped round a file stream object, then all we have to do is access the methods of the first class and the rest of the process happens automatically.

The approach I've taken is to define a class, TStreamWrapper, that provides a base class for any filters that we want to define. Any TStreamWrapper performs it's i/o using another TStream object – the wrapped object. The key point is that TStreamWrapper is itself derived from TStream, so that it can also wrap other TSteamWrapper objects – giving the extensibility we need. TSteamWrapper can also cause a wrapped stream to be freed when it is itself freed – allowing the wrapped streams to be created "on the fly" when the TSteamWrapper constructor is called.

There is no additional functionality built in to TSteamWrapper – this is to be provided by derived classes. A small example class is demonstrated here.

First we look at TSteamWrapper. Here's the class declaration:

  1type

  2  TStreamWrapper = class(TStream)

  3  private

  4    FBaseStream: TStream;

  5      {The wrapped stream}

  6    FCloseStream: Boolean;

  7      {Free wrapped stream on destruction?}

  8  protected

  9    procedure SetSize(NewSize: Longint); override;

 10      {Sets the size of the stream to the given value

 11      if the operation is supported by the underlying stream}

 12    property BaseStream: TStream read FBaseStream;

 13      {Gives access to the underlying stream to descended

 14      classes}

 15  public

 16    constructor Create(const Stream: TStream;

 17      const CloseStream: Boolean = False); virtual;

 18      {If CloseStream is true the given underlying stream is

 19      freed when this object is freed}

 20    destructor Destroy; override;

 21    // Implementation of abstract methods of TStream

 22    function Read(var Buffer; Count: Longint): Longint;

 23      override;

 24    function Write(const Buffer; Count: Longint): Longint;

 25      override;

 26    function Seek(Offset: Longint; Origin: Word): Longint;

 27      override;

 28  end;

Listing 1

and the implementation is:

  1constructor TStreamWrapper.Create(const Stream: TStream;

  2  const CloseStream: Boolean);

  3begin

  4  inherited Create;

  5  // Record wrapped stream and if we free it on destruction

  6  FBaseStream := Stream;

  7  FCloseStream := CloseStream;

  8end;

 10destructor TStreamWrapper.Destroy;

 11begin

 12  // Close wrapped stream if required

 13  if FCloseStream then

 14    FBaseStream.Free;

 15  inherited Destroy;

 16end;

 18function TStreamWrapper.Read(var Buffer;

 19  Count: Integer): Longint;

 20begin

 21  // Simply call underlying stream's Read method

 22  Result := FBaseStream.Read(Buffer, Count);

 23end;

 25function TStreamWrapper.Seek(Offset: Integer;

 26  Origin: Word): Longint;

 27begin

 28  // Simply call the same method in the wrapped stream

 29  Result := FBaseStream.Seek(Offset, Origin);

 30end;

 32procedure TStreamWrapper.SetSize(NewSize: Integer);

 33begin

 34  // Set the size property of the wrapped stream

 35  FBaseStream.Size := NewSize;

 36end;

 38function TStreamWrapper.Write(const Buffer;

 39  Count: Integer): Longint;

 40begin

 41  // Simply call the same method in the wrapped stream

 42  Result := FBaseStream.Write(Buffer, Count);

 43end;

Listing 2

We can now derive a small filter class – TStrStream. As it stands it's not particularly useful, but does demonstrate the techniques. The class reads and writes strings (which are preceded by their lengths) from and to any stream. The declaration is:

  1type

  2  TStrStream = class(TStreamWrapper)

  3  public

  4    procedure WriteString(AString: string);

  5    function ReadString: string;

  6  end;

Listing 3

The class is implemented as follows:

  1function TStrStream.ReadString: string;

  2var

  3  StrLen: Integer;    // the length of the string

  4  PBuf: PChar;        // buffer to hold the string that is read

  5begin

  6  // Get length of string (as 32 bit integer)

  7  ReadBuffer(StrLen, SizeOf(Integer));

  8  // Now get string

  9  // allocate enough memory to hold string

 10  GetMem(PBuf, StrLen);

 11  try

 12    // read chars into buffer and set resulting string

 13    ReadBuffer(PBuf^, StrLen);

 14    SetString(Result, PBuf, StrLen);

 15  finally

 16    // deallocate buffer

 17    FreeMem(PBuf, StrLen);

 18  end;

 19end;

 21procedure TStrStream.WriteString(AString: string);

 22var

 23  Len: Integer;     // length of string

 24begin

 25  // Write out length of string as 32 bit integer

 26  Len := Length(AString);

 27  WriteBuffer(Len, SizeOf(Integer));

 28  // Now write out the string's characters

 29  WriteBuffer(PChar(AString)^, Len);

 30end;

Listing 4

The following code should demonstrate how to write a string to a file and read it back in again. Here we use a file stream that is created on the fly and automatically closed when we are done. Of course you could use any stream type and handle its lifetime yourself.

  1procedure WriteText(const Txt: string);

  2var

  3  TS: TTextStream;

  4begin

  5  // This opens stream on a file stream that will

  6  // be closed when this stream closes

  7  TS := TTextStream.Create(

  8    TFileStream.Create('test.dat', fmCreate), True);

  9  TS.WriteString(Txt);

 10  TS.Free;  // this also closes wrapped file stream

 11end;

 13function ReadText: string;

 14var

 15  TS: TTextStream;

 16begin

 17  TS := TTextStream.Create(

 18    TFileStream.Create('test.dat', fmCreate), True);

 19  Result := TS.ReadString;

 20  TS.Free;

 21end;

Listing 5

The filter in this example provides additional methods to those in TSteamWrapper. We can also provide filters that override the Read and Write methods to alter the way that files are written.

Demo Code

A demo program to accompany this article can be found in the delphidabbler/article-demos Git repository on GitHub.

You can view the code in the article-05 sub-directory. Alternatively download a zip file containing all the available demos by going to the repository's landing page and clicking the Clone or download button and selecting Download ZIP.

The demo project is a Delphi 4 project that writes out some user provided strings to a file using the TStrStream class, and reads them back in again.

This source code is merely a proof of concept and is intended only to illustrate this article. It is not designed for use in its current form in finished applications. The code is provided on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.

The demo is open source. See the demo's LICENSE.md file for licensing details.

Real Life Example

My Stream Extension Classes provide an example of the techniques described here.

Feedback

I hope you found this article useful.

If you have any observations, comments, or have found any errors there are two places you can report them.

For anything to do with the article content, but not the downloadable demo code, please use this website's Issues page on GitHub. Make sure you mention that the issue relates to "article #5".
For bugs in the demo code see the article-demo project's README.md file for details of how to report them.