17.6 TStream

The TStream object is the ancestor for all streaming objects, i.e. objects that have the capability to store and retrieve data.

It defines a number of methods that are common to all objects that implement streaming, many of them are virtual, and are only implemented in the descendrnt types.

Programs should not instantiate objects of type TStream directly, but instead instantiate a descendant type, such as TDosStream, TMemoryStream.

This is the full declaration of the TStream object:

 TYPE
    TStream = OBJECT (TObject)
          Status    : Integer; { Stream status }
          ErrorInfo : Integer; { Stream error info }
          StreamSize: LongInt; { Stream current size }
          Position  : LongInt; { Current position }
       FUNCTION Get: PObject;
       FUNCTION StrRead: PChar;
       FUNCTION GetPos: Longint; Virtual;
       FUNCTION GetSize: Longint; Virtual;
       FUNCTION ReadStr: PString;
       PROCEDURE Open (OpenMode: Word); Virtual;
       PROCEDURE Close; Virtual;
       PROCEDURE Reset;
       PROCEDURE Flush; Virtual;
       PROCEDURE Truncate; Virtual;
       PROCEDURE Put (P: PObject);
       PROCEDURE StrWrite (P: PChar);
       PROCEDURE WriteStr (P: PString);
       PROCEDURE Seek (Pos: LongInt); Virtual;
       PROCEDURE Error (Code, Info: Integer); Virtual;
       PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
       PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
       PROCEDURE CopyFrom (Var S: TStream; Count: Longint);
    END;
    PStream = ^TStream;

TStream.Get

Declaration:: Function TStream.Get : PObject;
Description:: Get reads an object definition from a stream, and returns a pointer to an instance of this object.
Errors:: On error, TStream.Status is set, and NIL is returned.
See also:: Put (571)

Listing: objectex/ex9.pp

Program ex9;

{ Program to demonstrate TStream.Get and TStream.Put }

Uses Objects,MyObject;  { Definition and registration of TMyObject}

Var Obj : PMyObject;
    S : PStream;

begin
  Obj:=New(PMyObject,Init);
  Obj^.SetField($1111) ;
  Writeln ('Field value : ',Obj^.GetField);
  { Since Stream is an abstract type, we instantiate a TMemoryStream }
  S:=New(PMemoryStream,Init(100,10));
  S^.Put(Obj);
  Writeln ('Disposing object');
  S^.Seek(0);
  Dispose(Obj,Done);
  Writeln ('Reading object');
  Obj:=PMyObject(S^.Get);
  Writeln ('Field Value : ',Obj^.GetField);
  Dispose(Obj,Done);
end.

TStream.StrRead

Declaration:: Function TStream.StrRead: PChar;
Description:: StrRead reads a string from the stream, allocates memory for it, and returns a pointer to a null-terminated copy of the string on the heap.
Errors:: On error, Nil is returned.
See also:: StrWrite (572), ReadStr (569)

Listing: objectex/ex10.pp

Program ex10;

{
Program to demonstrate the TStream.StrRead TStream.StrWrite functions
}

Uses objects;

Var P : PChar;
    S : PStream;

begin
  P:='Constant Pchar string';
  Writeln ('Writing to stream : "',P,'"');
  S:=New(PMemoryStream,Init(100,10));
  S^.StrWrite(P);
  S^.Seek(0);
  P:=Nil;
  P:=S^.StrRead;
  DisPose (S,Done);
  Writeln ('Read from stream : "',P,'"');
  Freemem(P,Strlen(P)+1);
end.

TStream.GetPos

Declaration:: TSTream.GetPos : Longint; Virtual;
Description:: If the stream’s status is stOk, GetPos returns the current position in the stream. Otherwise it returns -1
Errors:: -1 is returned if the status is an error condition.
See also:: Seek (572), GetSize (568)

Listing: objectex/ex11.pp

Program ex11;

{ Program to demonstrate the TStream.GetPos function }

Uses objects;

Var L : String;
    S : PStream;

begin
  L:='Some kind of string';
  S:=New(PMemoryStream,Init(100,10));
  Writeln ('Stream position before write: ',S^.GetPos);
  S^.WriteStr(@L);
  Writeln ('Stream position after write : ',S^.GetPos);
  Dispose(S,Done);
end.

TStream.GetSize

Declaration:: Function TStream.GetSize: Longint; Virtual;
Description:: If the stream’s status is stOk then GetSize returns the size of the stream, otherwise it returns -1.
Errors:: -1 is returned if the status is an error condition.
See also:: Seek (572), GetPos (568)

Listing: objectex/ex12.pp

Program ex12;

{ Program to demonstrate the TStream.GetSize function }

Uses objects;

Var L : String;
    S : PStream;

begin
  L:='Some kind of string';
  S:=New(PMemoryStream,Init(100,10));
  Writeln ('Stream size before write: ',S^.GetSize);
  S^.WriteStr(@L);
  Writeln ('Stream size after write : ',S^.GetSize);
  Dispose(S,Done);
end.

TStream.ReadStr

Declaration:: Function TStream.ReadStr: PString;
Description:: ReadStr reads a string from the stream, copies it to the heap and returns a pointer to this copy. The string is saved as a pascal string, and hence is NOT null terminated.
Errors:: On error (e.g. not enough memory), Nil is returned.
See also:: StrRead (567)

Listing: objectex/ex13.pp

Program ex13;

{
Program to demonstrate the TStream.ReadStr TStream.WriteStr functions
}

Uses objects;

Var P : PString;
    L : String;
    S : PStream;

begin
  L:='Constant string line';
  Writeln ('Writing to stream : "',L,'"');
  S:=New(PMemoryStream,Init(100,10));
  S^.WriteStr(@L);
  S^.Seek(0);
  P:=S^.ReadStr;
  L:=P^;
  DisposeStr(P);
  DisPose (S,Done);
  Writeln ('Read from stream : "',L,'"');
end.

TStream.Open

Declaration:: Procedure TStream.Open (OpenMode: Word); Virtual;
Description:: Open is an abstract method, that should be overridden by descendent objects. Since opening a stream depends on the stream’s type this is not surprising.
Errors:: None.
See also:: Close (570), Reset (571)

For an example, see TDosStream.Open (580).

TStream.Close

Declaration:: Procedure TStream.Close; Virtual;
Description:: Close is an abstract method, that should be overridden by descendent objects. Since Closing a stream depends on the stream’s type this is not surprising.
Errors:: None.
See also:: Open (570), Reset (571)

for an example, see TDosStream.Open (580).

TStream.Reset

Declaration:: PROCEDURE TStream.Reset;
Description:: Reset sets the stream’s status to 0, as well as the ErrorInfo
Errors:: None.
See also:: Open (570), Close (570)

TStream.Flush

Declaration:: Procedure TStream.Flush; Virtual;
Description:: Flush is an abstract method that should be overridden by descendent objects. It serves to enable the programmer to tell streams that implement a buffer to clear the buffer.
Errors:: None.
See also:: Truncate (571)

for an example, see TBufStream.Flush (584).

TStream.Truncate

Declaration:: Procedure TStream.Truncate; Virtual;
Description:: Truncate is an abstract procedure that should be overridden by descendent objects. It serves to enable the programmer to truncate the size of the stream to the current file position.
Errors:: None.
See also:: Seek (572)

For an example, see TDosStream.Truncate (578).

TStream.Put

Declaration:: Procedure TStream.Put (P: PObject);
Description:: Put writes the object pointed to by P. P should be non-nil. The object type must have been registered with RegisterType (549).
After the object has been written, it can be read again with Get (566).
Errors:: No check is done whether P is Nil or not. Passing Nil will cause a run-time error 216 to be generated. If the object has not been registered, the status of the stream will be set to stPutError.
See also:: Get (566)

For an example, see TStream.Get (566);

TStream.StrWrite

Declaration:: Procedure TStream.StrWrite (P: PChar);
Description:: StrWrite writes the null-terminated string P to the stream. P can only be 65355 bytes long.
Errors:: None.
See also:: WriteStr (572), StrRead (567), ReadStr (569)

For an example, see TStream.StrRead (567).

TStream.WriteStr

Declaration:: Procedure TStream.WriteStr (P: PString);
Description:: StrWrite writes the pascal string pointed to by P to the stream.
Errors:: None.
See also:: StrWrite (572), StrRead (567), ReadStr (569)

For an example, see TStream.ReadStr (569).

TStream.Seek

Declaration:: PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
Description:: Seek sets the position to Pos. This position is counted from the beginning, and is zero based. (i.e. seeek(0) sets the position pointer on the first byte of the stream)
Errors:: If Pos is larger than the stream size, Status is set to StSeekError.
See also:: GetPos (568), GetSize (568)

For an example, see TDosStream.Seek (579).

TStream.Error

Declaration:: Procedure TStream.Error (Code, Info: Integer); Virtual;
Description:: Error sets the stream’s status to Code and ErrorInfo to Info. If the StreamError procedural variable is set, Error executes it, passing Self as an argument.
This method should not be called directly from a program. It is intended to be used in descendent objects.
Errors:: None.
See also:

TStream.Read

Declaration:: Procedure TStream.Read (Var Buf; Count: Sw_Word); Virtual;
Description:: Read is an abstract method that should be overridden by descendent objects.
Read reads Count bytes from the stream into Buf. It updates the position pointer, increasing it’s value with Count. Buf must be large enough to contain Count bytes.
Errors:: No checking is done to see if Buf is large enough to contain Count bytes.
See also:: Write (574), ReadStr (569), StrRead (567)

Listing: objectex/ex18.pp

program ex18;

{ Program to demonstrate the TStream.Read method }

Uses Objects;

Var Buf1,Buf2 : Array[1..1000] of Byte;
    I : longint;
    S : PMemorySTream;

begin
  For I:=1 to 1000 do
    Buf1[I]:=Random(1000);
  Buf2:=Buf1;
  S:=New(PMemoryStream,Init(100,10));
  S^.Write(Buf1,SizeOf(Buf1));
  S^.Seek(0);
  For I:=1 to 1000 do
    Buf1[I]:=0;
  S^.Read(Buf1,SizeOf(Buf1));
  For I:=1 to 1000 do
    If Buf1[I]<>buf2[i] then
      Writeln ('Buffer differs at position ',I);
  Dispose(S,Done);
end.

TStream.Write

Declaration:: Procedure TStream.Write (Var Buf; Count: Sw_Word); Virtual;
Description:: Write is an abstract method that should be overridden by descendent objects.
Write writes Count bytes to the stream from Buf. It updates the position pointer, increasing it’s value with Count.
Errors:: No checking is done to see if Buf actually contains Count bytes.
See also:: Read (573), WriteStr (572), StrWrite (572)

For an example, see TStream.Read (573).

TStream.CopyFrom

Declaration:: Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
Description:: CopyFrom reads Count bytes from stream S and stores them in the current stream. It uses the Read (573) method to read the data, and the Write (574) method to write in the current stream.
Errors:: None.
See also:: Read (573), Write (574)

Listing: objectex/ex19.pp

Program ex19;

{ Program to demonstrate the TStream.CopyFrom function }

Uses objects;

Var P : PString;
    L : String;
    S1,S2 : PStream;

begin
  L:='Constant string line';
  Writeln ('Writing to stream 1 : "',L,'"');
  S1:=New(PMemoryStream,Init(100,10));
  S2:=New(PMemoryStream,Init(100,10));
  S1^.WriteStr(@L);
  S1^.Seek(0);
  Writeln ('Copying contents of stream 1 to stream 2');
  S2^.Copyfrom(S1^,S1^.GetSize);
  S2^.Seek(0);
  P:=S2^.ReadStr;
  L:=P^;
  DisposeStr(P);
  Dispose (S1,Done);
  Dispose (S2,Done);
  Writeln ('Read from stream 2 : "',L,'"');
end.

[next] [prev] [prev-tail] [front] [up]