freepascal.compiler/docs/objects.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1998, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
\chapter{The Objects unit.}
\label{ch:objectsunit}

\FPCexampledir{objectex}
This chapter documents the \file{objects} unit. The unit was implemented by
many people, and was mainly taken from the FreeVision sources. It has been 
ported to all supported platforms.

The methods and fields that are in a \var{Private} part of an object
declaration have been left out of this documentation.

\section{Constants}
The following constants are error codes, returned by the various stream
objects.

\begin{verbatim}
CONST
   stOk         =  0; { No stream error }
   stError      = -1; { Access error }
   stInitError  = -2; { Initialize error }
   stReadError  = -3; { Stream read error }
   stWriteError = -4; { Stream write error }
   stGetError   = -5; { Get object error }
   stPutError   = -6; { Put object error }
   stSeekError  = -7; { Seek error in stream }
   stOpenError  = -8; { Error opening stream }
\end{verbatim}
These constants can be passed to constructors of file streams:
\begin{verbatim}
CONST
   stCreate    = $3C00; { Create new file }
   stOpenRead  = $3D00; { Read access only }
   stOpenWrite = $3D01; { Write access only }
   stOpen      = $3D02; { Read/write access }
\end{verbatim}

The following constants are error codes, returned by the collection list
objects:
\begin{verbatim}
CONST
   coIndexError = -1; { Index out of range }
   coOverflow   = -2; { Overflow }
\end{verbatim}

Maximum data sizes (used in determining how many data can be used.

\begin{verbatim}
CONST
   MaxBytes = 128*1024*1024;                          { Maximum data size }
   MaxWords = MaxBytes DIV SizeOf(Word);              { Max word data size }
   MaxPtrs = MaxBytes DIV SizeOf(Pointer);            { Max ptr data size }
   MaxCollectionSize = MaxBytes DIV SizeOf(Pointer);  { Max collection size }
\end{verbatim}

\section{Types}
The follwing auxiliary types are defined:
\begin{verbatim}
TYPE
   { Character set }
   TCharSet = SET Of Char;                            
   PCharSet = ^TCharSet;

   { Byte array }
   TByteArray = ARRAY [0..MaxBytes-1] Of Byte;        
   PByteArray = ^TByteArray;

   { Word array }
   TWordArray = ARRAY [0..MaxWords-1] Of Word;        
   PWordArray = ^TWordArray;

   { Pointer array }
   TPointerArray = Array [0..MaxPtrs-1] Of Pointer;   
   PPointerArray = ^TPointerArray; 

   { String pointer }
   PString = ^String;

   { Filename array }
   AsciiZ = Array [0..255] Of Char;

   Sw_Word    = Cardinal;
   Sw_Integer = LongInt;
\end{verbatim}
The following records are used internaly for easy type conversion:
\begin{verbatim}
TYPE
   { Word to bytes}
   WordRec = packed RECORD
     Lo, Hi: Byte;     
   END;

   { LongInt to words }
   LongRec = packed RECORD
     Lo, Hi: Word;
   END;

  { Pointer to words }
   PtrRec = packed RECORD
     Ofs, Seg: Word;
   END;
\end{verbatim}

The following record is used when streaming objects:

\begin{verbatim}
TYPE
   PStreamRec = ^TStreamRec;
   TStreamRec = Packed RECORD
      ObjType: Sw_Word;
      VmtLink: pointer;
      Load : Pointer;
      Store: Pointer;
      Next : PStreamRec;
   END;
\end{verbatim}

The \var{TPoint} basic object is used in the \var{TRect} object (see
\sees{TRect}):
\begin{verbatim}
TYPE
   PPoint = ^TPoint;
   TPoint = OBJECT
      X, Y: Sw_Integer;
   END;
\end{verbatim}

\section{Procedures and Functions}

\begin{function}{NewStr}
\Declaration
Function NewStr (Const S: String): PString;
\Description
\var{NewStr} makes a copy of the string \var{S} on the heap,
and returns a pointer to this copy.

The allocated memory is not based on the declared size of the string passed
to \var{NewStr}, but is baed on the actual length of the string.
\Errors
If not enough memory is available, an 'out of memory' error will occur.
\SeeAlso
\seep{DisposeStr}
\end{function}

\FPCexample{ex40}

\begin{procedure}{DisposeStr}
\Declaration
Procedure DisposeStr (P: PString);
\Description
\var{DisposeStr} removes a dynamically allocated string from the heap.
\Errors
None.
\SeeAlso
\seef{NewStr}
\end{procedure}

For an example, see \seef{NewStr}.

\begin{procedure}{Abstract}
\Declaration
Procedure Abstract;
\Description
When implementing abstract methods, do not declare them as \var{abstract}.
Instead, define them simply as \var{virtual}. In the implementation of such
abstract methods, call the \var{Abstract} procedure. This allows explicit
control of what happens when an abstract method is called.

The current implementation of \var{Abstract} terminates the program with 
a run-time error 211.
\Errors
None.
\SeeAlso Most abstract types.
\end{procedure}

\begin{procedure}{RegisterObjects}
\Declaration
Procedure RegisterObjects;
\Description
\var{RegisterObjects} registers the following objects for streaming:
\begin{enumerate}
\item \var{TCollection}, see \sees{TCollection}.
\item \var{TStringCollection}, see \sees{TStringCollection}.
\item \var{TStrCollection}, see \sees{TStrCollection}.
\end{enumerate}
\Errors
None.
\SeeAlso
\seep{RegisterType}
\end{procedure}

\begin{procedure}{RegisterType}
\Declaration
Procedure RegisterType (Var S: TStreamRec);
\Description
\var{RegisterType} registers a new type for streaming. An object cannot
be streamed unless it has been registered first. 
The stream record \var{S} needs to have the following fields set:

\begin{description}
\item[ObjType: Sw\_Word] This should be a unique identifier. Each possible
type should have it's own identifier. 
\item[VmtLink: pointer] This should contain a pointer to the VMT (Virtual
Method Table) of the object you try to register. You can get it with the
following expression:
\begin{verbatim}
     VmtLink: Ofs(TypeOf(MyType)^);
\end{verbatim}
\item[Load : Pointer] is a pointer to a method that initializes an instance
of that object, and reads the initial values from a stream. This method
should accept as it's sole argument a \var{PStream} type variable.
\item[Store: Pointer]is a pointer to a method that stores an instance of the
object to a stream. This method should accept as it's sole argument
 a \var{PStream} type variable.
\end{description}
\Errors
In case of error (if a object with the same \var{ObjType}) is already
registered), run-time error 212 occurs.
\end{procedure}

\FPCexample{myobject}

\begin{function}{LongMul}
\Declaration
Function LongMul (X, Y: Integer): LongInt;
\Description
\var{LongMul} multiplies \var{X} with \var{Y}. The result is of
type \var{Longint}. This avoids possible overflow errors you would normally
get when multiplying \var{X} and \var{Y} that are too big.
\Errors
None.
\SeeAlso
\seef{LongDiv}
\end{function}

\begin{function}{LongDiv}
\Declaration
Function LongDiv (X: Longint; Y: Integer): Integer;
\Description
\var{LongDiv} divides \var{X} by \var{Y}. The result is of
type \var{Integer} instead of type \var{Longint}, as you would get 
normally. 
\Errors
If Y is zero, a run-time error will be generated.
\SeeAlso
\seef{LongMul}
\end{function}

\section{TRect}
\label{se:TRect}

The \var{TRect} object is declared as follows:
\begin{verbatim}
   TRect = OBJECT
      A, B: TPoint;
      FUNCTION Empty: Boolean;
      FUNCTION Equals (R: TRect): Boolean;
      FUNCTION Contains (P: TPoint): Boolean;
      PROCEDURE Copy (R: TRect);
      PROCEDURE Union (R: TRect);
      PROCEDURE Intersect (R: TRect);
      PROCEDURE Move (ADX, ADY: Sw_Integer);
      PROCEDURE Grow (ADX, ADY: Sw_Integer);
      PROCEDURE Assign (XA, YA, XB, YB: Sw_Integer);
   END;
\end{verbatim}

\begin{function}{TRect.Empty}
\Declaration
Function TRect.Empty: Boolean;
\Description
\var{Empty} returns \var{True} if the rectangle defined by the corner points 
\var{A}, \var{B} has zero or negative surface.
\Errors
None.
\SeeAlso
\seef{TRect.Equals}, \seef{TRect.Contains}
\end{function}

\FPCexample{ex1}

\begin{function}{TRect.Equals}      
\Declaration
Function TRect.Equals (R: TRect): Boolean;
\Description
\var{Equals} returns \var{True} if the rectangle has the 
same corner points \var{A,B} as the rectangle R, and \var{False}
otherwise.
\Errors
None.
\SeeAlso
\seefl{Empty}{TRect.Empty}, \seefl{Contains}{TRect.Contains}
\end{function}

For an example, see \seef{TRect.Empty}

\begin{function}{TRect.Contains}
\Declaration
Function TRect.Contains (P: TPoint): Boolean;
\Description
\var{Contains} returns \var{True} if the point \var{P} is contained
in the rectangle (including borders), \var{False} otherwise.
\Errors
None.
\SeeAlso
\seepl{Intersect}{TRect.Intersect}, \seefl{Equals}{TRect.Equals}
\end{function}

\begin{procedure}{TRect.Copy}
\Declaration     
Procedure TRect.Copy (R: TRect);
\Description
Assigns the rectangle R to the object. After the call to \var{Copy}, the
rectangle R has been copied to the object that invoked \var{Copy}.
\Errors
None.
\SeeAlso
\seepl{Assign}{TRect.Assign}
\end{procedure}

\FPCexample{ex2}

\begin{procedure}{TRect.Union}
\Declaration
Procedure TRect.Union (R: TRect);
\Description
\var{Union} enlarges the current rectangle so that it becomes the union
of the current rectangle with the rectangle \var{R}.
\Errors
None.
\SeeAlso
\seepl{Intersect}{TRect.Intersect}
\end{procedure}

\FPCexample{ex3}

\begin{procedure}{TRect.Intersect}
\Declaration
Procedure TRect.Intersect (R: TRect);
\Description
\var{Intersect} makes the intersection of the current rectangle with
\var{R}. If the intersection is empty, then the rectangle is set to the empty
rectangle at coordinate (0,0).
\Errors
None.
\SeeAlso
\seepl{Union}{TRect.Union}
\end{procedure}

\FPCexample{ex4}

\begin{procedure}{TRect.Move}
\Declaration
Procedure TRect.Move (ADX, ADY: Sw\_Integer);
\Description
\var{Move} moves the current rectangle along a vector with components
\var{(ADX,ADY)}. It adds \var{ADX} to the X-coordinate of both corner
points, and \var{ADY} to both end points.
\Errors
None.
\SeeAlso
\seepl{Grow}{TRect.Grow}
\end{procedure}

\FPCexample{ex5}

\begin{procedure}{TRect.Grow}
\Declaration
Procedure TRect.Grow (ADX, ADY: Sw\_Integer);
\Description
\var{Grow} expands the rectangle with an amount \var{ADX} in the \var{X}
direction (both on the left and right side of the rectangle, thus adding a 
length 2*ADX to the width of the rectangle), and an amount \var{ADY} in 
the \var{Y} direction (both on the top and the bottom side of the rectangle,
adding a length 2*ADY to the height of the rectangle. 

\var{ADX} and \var{ADY} can be negative. If the resulting rectangle is empty, it is set 
to the empty rectangle at \var{(0,0)}.
\Errors
None.
\SeeAlso
\seepl{Move}{TRect.Move}.
\end{procedure}


\FPCexample{ex6}

\begin{procedure}{TRect.Assign}
\Declaration
Procedure Trect.Assign (XA, YA, XB, YB: Sw\_Integer);
\Description
\var{Assign} sets the corner points of the rectangle to \var{(XA,YA)} and 
\var{(Xb,Yb)}.
\Errors
None.
\SeeAlso
\seepl{Copy}{TRect.Copy}
\end{procedure}

For an example, see \seep{TRect.Copy}.

\section{TObject}
\label{se:TObject}

The full declaration of the \var{TObject} type is:
\begin{verbatim}
TYPE
   TObject = OBJECT
      CONSTRUCTOR Init;
      PROCEDURE Free;
      DESTRUCTOR Done;Virtual;
   END;
   PObject = ^TObject;
\end{verbatim}
\begin{procedure}{TObject.Init}
\Declaration
Constructor TObject.Init;
\Description
Instantiates a new object of type \var{TObject}. It fills the instance up
with Zero bytes.
\Errors
None.
\SeeAlso
\seepl{Free}{TObject.Free}, \seepl{Done}{TObject.Done}
\end{procedure}

For an example, see \seepl{Free}{TObject.Free}

\begin{procedure}{TObject.Free}
\Declaration
Procedure TObject.Free;
\Description
\var{Free} calls the destructor of the object, and releases the memory
occupied by the instance of the object.
\Errors
No checking is performed to see whether \var{self} is \var{nil} and whether
the object is indeed allocated on the heap.
\SeeAlso
\seepl{Init}{TObject.Init}, \seepl{Done}{TObject.Done}
\end{procedure}

\FPCexample{ex7}

\begin{procedure}{TObject.Done}
\Declaration
Destructor TObject.Done;Virtual;
\Description
\var{Done}, the destructor of \var{TObject} does nothing. It is mainly
intended to be used in the \seep{TObject.Free} method.

The destructore Done does not free the memory occupied by the object.
\Errors
None.
\SeeAlso
\seepl{Free}{TObject.Free}, \seepl{Init}{TObject.Init}
\end{procedure}

\FPCexample{ex8}

\section{TStream}
\label{se:TStream}

The \var{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 \var{TDosStream},
\var{TMemoryStream}.

This is the full declaration of the \var{TStream} object:
\begin{verbatim}
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;
\end{verbatim}

\begin{function}{TStream.Get}
\Declaration
Function TStream.Get : PObject;
\Description
\var{Get} reads an object definition  from a stream, and returns
a pointer to an instance of this object.
\Errors
On error, \var{TStream.Status} is set, and NIL is returned.
\SeeAlso 
\seepl{Put}{TStream.Put}
\end{function}

\FPCexample{ex9}

\begin{function}{TStream.StrRead}
\Declaration
Function TStream.StrRead: PChar;
\Description
\var{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, \var{Nil} is returned.
\SeeAlso
\seepl{StrWrite}{TStream.StrWrite}, \seefl{ReadStr}{TStream.ReadStr}
\end{function}

\FPCexample{ex10}


\begin{function}{TStream.GetPos}
\Declaration 
TSTream.GetPos : Longint; Virtual;
\Description
If the stream's status is \var{stOk}, \var{GetPos} returns the current 
position in the stream. Otherwise it returns \var{-1}
\Errors
\var{-1} is returned if the status is an error condition.
\SeeAlso
\seepl{Seek}{TStream.Seek}, \seefl{GetSize}{TStream.GetSize}
\end{function}

\FPCexample{ex11}


\begin{function}{TStream.GetSize}
\Declaration
Function TStream.GetSize: Longint; Virtual;
\Description
If the stream's status is \var{stOk} then \var{GetSize} returns
the size of the stream, otherwise it returns \var{-1}.
\Errors
\var{-1} is returned if the status is an error condition.
\SeeAlso
\seepl{Seek}{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
\end{function}

\FPCexample{ex12}


\begin{function}{TStream.ReadStr}
\Declaration
Function TStream.ReadStr: PString;
\Description
\var{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), \var{Nil} is returned.
\SeeAlso
\seefl{StrRead}{TStream.StrRead}
\end{function}

\FPCexample{ex13}


\begin{procedure}{TStream.Open}
\Declaration
Procedure TStream.Open (OpenMode: Word); Virtual;
\Description
\var{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.
\SeeAlso
\seepl{Close}{TStream.Close}, \seepl{Reset}{TStream.Reset}
\end{procedure}

For an example, see \seep{TDosStream.Open}.

\begin{procedure}{TStream.Close}
\Declaration
Procedure TStream.Close; Virtual;
\Description
\var{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.
\SeeAlso
\seepl{Open}{TStream.Open}, \seepl{Reset}{TStream.Reset}
\end{procedure}

for an example, see \seep{TDosStream.Open}.

\begin{procedure}{TStream.Reset}
\Declaration
PROCEDURE TStream.Reset;
\Description
\var{Reset} sets the stream's status to \var{0}, as well as the ErrorInfo
\Errors
None.
\SeeAlso
\seepl{Open}{TStream.Open}, \seepl{Close}{TStream.Close}
\end{procedure}

\begin{procedure}{TStream.Flush}
\Declaration 
Procedure TStream.Flush; Virtual;
\Description
\var{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.
\SeeAlso
\seepl{Truncate}{TStream.Truncate}
\end{procedure}

for an example, see \seep{TBufStream.Flush}.

\begin{procedure}{TStream.Truncate}
\Declaration
Procedure TStream.Truncate; Virtual;
\Description
\var{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.
\SeeAlso
\seepl{Seek}{TStream.Seek}
\end{procedure}

For an example, see \seep{TDosStream.Truncate}.

\begin{procedure}{TStream.Put}
\Declaration
Procedure TStream.Put (P: PObject);
\Description
\var{Put} writes the object pointed to by \var{P}. \var{P} should be
non-nil. The object type must have been registered with \seep{RegisterType}.

After the object has been written, it can be read again with \seefl{Get}{TStream.Get}.
\Errors
No check is done whether P is \var{Nil} or not. Passing \var{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 \var{stPutError}.
\SeeAlso
\seefl{Get}{TStream.Get}
\end{procedure}

For an example, see \seef{TStream.Get};

\begin{procedure}{TStream.StrWrite}
\Declaration
Procedure TStream.StrWrite (P: PChar);
\Description
\var{StrWrite} writes the null-terminated string \var{P} to the stream.
\var{P} can only be 65355 bytes long.
\Errors
None.
\SeeAlso
\seepl{WriteStr}{TStream.WriteStr}, \seefl{StrRead}{TStream.StrRead},
\seefl{ReadStr}{TStream.ReadStr}
\end{procedure}

For an example, see \seef{TStream.StrRead}.

\begin{procedure}{TStream.WriteStr}
\Declaration
Procedure TStream.WriteStr (P: PString);
\Description
\var{StrWrite} writes the pascal string pointed to by \var{P} to the stream.
\Errors
None.
\SeeAlso
\seepl{StrWrite}{TStream.StrWrite}, \seefl{StrRead}{TStream.StrRead},
\seefl{ReadStr}{TStream.ReadStr}
\end{procedure}

For an example, see \seef{TStream.ReadStr}.

\begin{procedure}{TStream.Seek}
\Declaration      
PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
\Description
Seek sets the position to \var{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 \var{Pos} is larger than the stream size, \var{Status} is set to
\var{StSeekError}.
\SeeAlso
\seefl{GetPos}{TStream.GetPos}, \seefl{GetSize}{TStream.GetSize}
\end{procedure}


For an example, see \seep{TDosStream.Seek}.

\begin{procedure}{TStream.Error}
\Declaration
Procedure TStream.Error (Code, Info: Integer); Virtual;
\Description
\var{Error} sets the stream's status to \var{Code} and \var{ErrorInfo}
to \var{Info}. If the \var{StreamError} procedural variable is set,
\var{Error} executes it, passing \var{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.
\SeeAlso
\end{procedure}

\begin{procedure}{TStream.Read}
\Declaration
Procedure TStream.Read (Var Buf; Count: Sw\_Word); Virtual;
\Description
\var{Read} is an abstract method that should be overridden by descendent
objects.

\var{Read} reads \var{Count} bytes from the stream into \var{Buf}.
It updates the position pointer, increasing it's value with \var{Count}. 
\var{Buf} must be large enough to contain \var{Count} bytes.
\Errors
No checking is done to see if \var{Buf} is large enough to contain
\var{Count} bytes. 
\SeeAlso
\seepl{Write}{TStream.Write}, \seefl{ReadStr}{TStream.ReadStr},
\seefl{StrRead}{TStream.StrRead}
\end{procedure}

\FPCexample{ex18}


\begin{procedure}{TStream.Write}
\Declaration
Procedure TStream.Write (Var Buf; Count: Sw\_Word); Virtual;
\Description
\var{Write} is an abstract method that should be overridden by descendent
objects.

\var{Write} writes \var{Count} bytes to the stream from \var{Buf}.
It updates the position pointer, increasing it's value with \var{Count}. 
\Errors
No checking is done to see if \var{Buf} actually contains \var{Count} bytes. 
\SeeAlso
\seepl{Read}{TStream.Read}, \seepl{WriteStr}{TStream.WriteStr},
\seepl{StrWrite}{TStream.StrWrite}
\end{procedure}

For an example, see \seep{TStream.Read}.

\begin{procedure}{TStream.CopyFrom}
\Declaration
Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
\Description
\var{CopyFrom} reads Count bytes from stream \var{S} and stores them
in the current stream. It uses the \seepl{Read}{TStream.Read} method
to read the data, and the \seepl{Write}{TStream.Write} method to
write in the current stream.
\Errors
None.
\SeeAlso
\seepl{Read}{TStream.Read}, \seepl{Write}{TStream.Write}
\end{procedure}

\FPCexample{ex19}


\section{TDosStream}
\label{se:TDosStream}

\var{TDosStream} is a stream that stores it's contents in a file.
it overrides a couple of methods of \var{TSteam} for this.

In addition to the fields inherited from \var{TStream} (see \sees{TStream}),
there are some extra fields, that describe the file. (mainly the name and
the OS file handle)

No buffering in memory is done when using \var{TDosStream}. 
All data are written directly to the file. For a stream that buffers 
in memory, see \sees{TBufStream}.

Here is the full declaration of the \var{TDosStream} object:
\begin{verbatim}
TYPE
   TDosStream = OBJECT (TStream)
         Handle: THandle; { DOS file handle }
         FName : AsciiZ;  { AsciiZ filename }
      CONSTRUCTOR Init (FileName: FNameStr; Mode: Word);
      DESTRUCTOR Done; Virtual;
      PROCEDURE Close; Virtual;
      PROCEDURE Truncate; Virtual;
      PROCEDURE Seek (Pos: LongInt); Virtual;
      PROCEDURE Open (OpenMode: Word); Virtual;
      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
   END;
   PDosStream = ^TDosStream;
\end{verbatim}

\begin{procedure}{TDosStream.Init}
\Declaration
Constructor Init (FileName: FNameStr; Mode: Word);
\Description
\var{Init} instantiates an instance of \var{TDosStream}. The name of the 
file that contains (or will contain) the data of the stream is given in
\var{FileName}. The \var{Mode} parameter determines whether a new file 
should be created and what access rights you have on the file. 
It can be one of the following constants:
\begin{description}
\item[stCreate] Creates a new file.
\item[stOpenRead] Read access only.
\item[stOpenWrite] Write access only.
\item[stOpen] Read and write access.
\end{description}
\Errors
On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
is set to the \dos error code.
\SeeAlso
\seepl{Done}{TDosStream.Done}
\end{procedure}

For an example, see \seep{TDosStream.Truncate}.

\begin{procedure}{TDosStream.Done}
\Declaration
Destructor TDosStream.Done; Virtual;
\Description
\var{Done} closes the file if it was open and cleans up the 
instance of \var{TDosStream}. 
\Errors
None.
\SeeAlso
\seepl{Init}{TDosStream.Init},
\seepl{Close}{TDosStream.Close}
\end{procedure}

for an example, see e.g. \seep{TDosStream.Truncate}.

\begin{procedure}{TDosStream.Close}
\Declaration
Pocedure TDosStream.Close; Virtual;
\Description
\var{Close} closes the file if it was open, and sets \var{Handle} to -1. 
Contrary to \seepl{Done}{TDosStream.Done} it does not clean up the instance
of \var{TDosStream}
\Errors
None.
\SeeAlso
\seep{TStream.Close}, \seepl{Init}{TDosStream.Init},
\seepl{Done}{TDosStream.Done}
\end{procedure}

For an example, see \seep{TDosStream.Open}.

\begin{procedure}{TDosStream.Truncate}
\Declaration
Procedure TDosStream.Truncate; Virtual;
\Description
If the status of the stream is \var{stOK}, then \var{Truncate} tries to
truncate the stream size to the current file position.
\Errors
If an error occurs, the stream's status is set to \var{stError} and
\var{ErrorInfo} is set to the OS error code.
\SeeAlso
\seep{TStream.Truncate}, \seefl{GetSize}{TStream.GetSize}
\end{procedure}

\FPCexample{ex16}


\begin{procedure}{TDosStream.Seek}
\Declaration
Procedure TDosStream.Seek (Pos: LongInt); Virtual;
\Description
If the stream's status is \var{stOK}, then \var{Seek} sets the 
file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
the beginning of the file.
\Errors
In case an error occurs, the stream's status is set to \var{stSeekError},
and the OS error code is stored in \var{ErrorInfo}.
\SeeAlso
\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
\end{procedure}

\FPCexample{ex17}


\begin{procedure}{TDosStream.Open}
\Declaration
Procedure TDosStream.Open (OpenMode: Word); Virtual;
\Description
If the stream's status is \var{stOK}, and the stream is closed then
\var{Open} re-opens the file stream with mode \var{OpenMode}.
This call can be used after a \seepl{Close}{TDosStream.Close} call.
\Errors
If an error occurs when re-opening the file, then \var{Status} is set
to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
\SeeAlso
\seep{TStream.Open}, \seepl{Close}{TDosStream.Close}
\end{procedure}

\FPCexample{ex14}


\begin{procedure}{TDosStream.Read}
\Declaration
Procedure TDosStream.Read (Var Buf; Count: Sw\_Word); Virtual;
\Description
If the Stream is open and the stream status is \var{stOK} then 
\var{Read} will read \var{Count} bytes from the stream and place them
in  \var{Buf}.
\Errors
In case of an error, \var{Status} is set to \var{StReadError}, and
\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
made to read beyond the end of the stream.
\SeeAlso
\seep{TStream.Read}, \seepl{Write}{TDosStream.Write}
\end{procedure}

For an example, see \seep{TStream.Read}.

\begin{procedure}{TDosStream.Write}
\Declaration
Procedure TDosStream.Write (Var Buf; Count: Sw\_Word); Virtual;
\Description
If the Stream is open and the stream status is \var{stOK} then 
\var{Write} will write \var{Count} bytes from \var{Buf} and place them
in the stream.
\Errors
In case of an error, \var{Status} is set to \var{StWriteError}, and
\var{ErrorInfo} gets the OS specific error.
\SeeAlso
\seep{TStream.Write}, \seepl{Read}{TDosStream.Read}
\end{procedure}

For an example, see \seep{TStream.Read}.

\section{TBufStream}
\label{se:TBufStream}

\var{Bufstream} implements a buffered file stream. That is, all data written
to the stream is written to memory first. Only when the buffer is full, or
on explicit request, the data is written to disk.

Also, when reading from the stream, first the buffer is checked if there is
any unread data in it. If so, this is read first. If not the buffer is
filled again, and then the data is read from the buffer.

The size of the buffer is fixed and is set when constructing the file.

This is useful if you need heavy throughput for your stream, because it
speeds up operations.

\begin{verbatim}
TYPE
   TBufStream = OBJECT (TDosStream)
         LastMode: Byte;       { Last buffer mode }
         BufSize : Sw_Word;    { Buffer size }
         BufPtr  : Sw_Word;    { Buffer start }
         BufEnd  : Sw_Word;    { Buffer end }
         Buffer  : PByteArray; { Buffer allocated }
      CONSTRUCTOR Init (FileName: FNameStr; Mode, Size: Word);
      DESTRUCTOR Done; Virtual;
      PROCEDURE Close; Virtual;
      PROCEDURE Flush; Virtual;
      PROCEDURE Truncate; Virtual;
      PROCEDURE Seek (Pos: LongInt); Virtual;
      PROCEDURE Open (OpenMode: Word); Virtual;
      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
   END;
   PBufStream = ^TBufStream;
\end{verbatim}

\begin{procedure}{TBufStream.Init}
\Declaration
Constructor Init (FileName: FNameStr; Mode,Size: Word);
\Description
\var{Init} instantiates an instance of \var{TBufStream}. The name of the 
file that contains (or will contain) the data of the stream is given in
\var{FileName}. The \var{Mode} parameter determines whether a new file 
should be created and what access rights you have on the file. 
It can be one of the following constants:
\begin{description}
\item[stCreate] Creates a new file.
\item[stOpenRead] Read access only.
\item[stOpenWrite] Write access only.
\item[stOpen] Read and write access.
\end{description}
The \var{Size} parameter determines the size of the buffer that will be
created. It should be different from zero.
\Errors
On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
is set to the \dos error code.
\SeeAlso
\seep{TDosStream.Init}, \seepl{Done}{TBufStream.Done}
\end{procedure}

For an example see \seep{TBufStream.Flush}.

\begin{procedure}{TBufStream.Done}
\Declaration
Destructor TBufStream.Done; Virtual;
\Description
\var{Done} flushes and closes the file if it was open and cleans up the 
instance of \var{TBufStream}. 
\Errors
None.
\SeeAlso
\seep{TDosStream.Done}, \seepl{Init}{TBufStream.Init},
\seepl{Close}{TBufStream.Close}
\end{procedure}

For an example see \seep{TBufStream.Flush}.

\begin{procedure}{TBufStream.Close}
\Declaration
Pocedure TBufStream.Close; Virtual;
\Description
\var{Close} flushes and closes the file if it was open, and sets \var{Handle} to -1. 
Contrary to \seepl{Done}{TBufStream.Done} it does not clean up the instance
of \var{TBufStream}
\Errors
None.
\SeeAlso
\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
\seepl{Done}{TBufStream.Done}
\end{procedure}

For an example see \seep{TBufStream.Flush}.

\begin{procedure}{TBufStream.Flush}
\Declaration
Pocedure TBufStream.Flush; Virtual;
\Description
When the stream is in write mode, the contents of the buffer are written to
disk, and the buffer position is set to zero.

When the stream is in read mode, the buffer position is set to zero.
\Errors
Write errors may occur if the file was in write mode.
see \seepl{Write}{TBufStream.Write} for more info on the errors.
\SeeAlso
\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
\seepl{Done}{TBufStream.Done}
\end{procedure}

\FPCexample{ex15}


\begin{procedure}{TBufStream.Truncate}
\Declaration
Procedure TBufStream.Truncate; Virtual;
\Description
If the status of the stream is \var{stOK}, then \var{Truncate} tries to
flush the buffer, and then truncates the stream size to the current 
file position.
\Errors
Errors can be those of \seepl{Flush}{TBufStream.Flush} or
\seep{TDosStream.Truncate}.
\SeeAlso
\seep{TStream.Truncate}, \seep{TDosStream.Truncate},
\seefl{GetSize}{TStream.GetSize}
\end{procedure}

For an example, see \seep{TDosStream.Truncate}.

\begin{procedure}{TBufStream.Seek}
\Declaration
Procedure TBufStream.Seek (Pos: LongInt); Virtual;
\Description
If the stream's status is \var{stOK}, then \var{Seek} sets the 
file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
the beginning of the file.
\Errors
In case an error occurs, the stream's status is set to \var{stSeekError},
and the OS error code is stored in \var{ErrorInfo}.
\SeeAlso
\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
\end{procedure}

For an example, see \seep{TStream.Seek};

\begin{procedure}{TBufStream.Open}
\Declaration
Procedure TBufStream.Open (OpenMode: Word); Virtual;
\Description
If the stream's status is \var{stOK}, and the stream is closed then
\var{Open} re-opens the file stream with mode \var{OpenMode}.
This call can be used after a \seepl{Close}{TBufStream.Close} call.
\Errors
If an error occurs when re-opening the file, then \var{Status} is set
to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
\SeeAlso
\seep{TStream.Open}, \seepl{Close}{TBufStream.Close}
\end{procedure}

For an example, see \seep{TDosStream.Open}.

\begin{procedure}{TBufStream.Read}
\Declaration
Procedure TBufStream.Read (Var Buf; Count: Sw\_Word); Virtual;
\Description
If the Stream is open and the stream status is \var{stOK} then 
\var{Read} will read \var{Count} bytes from the stream and place them
in  \var{Buf}.

\var{Read} will first try to read the data from the stream's internal
buffer. If insufficient data is available, the buffer will be filled before
contiunuing to read. This process is repeated until all needed data 
has been read.

\Errors
In case of an error, \var{Status} is set to \var{StReadError}, and
\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
made to read beyond the end of the stream.
\SeeAlso
\seep{TStream.Read}, \seepl{Write}{TBufStream.Write}
\end{procedure}

For an example, see \seep{TStream.Read}.

\begin{procedure}{TBufStream.Write}
\Declaration
Procedure TBufStream.Write (Var Buf; Count: Sw\_Word); Virtual;
\Description
If the Stream is open and the stream status is \var{stOK} then 
\var{Write} will write \var{Count} bytes from \var{Buf} and place them
in the stream.

\var{Write} will first try to write the data to the stream's internal
buffer. When the internal buffer is full, then the contents will be written 
to disk. This process is repeated until all data has been written.
\Errors
In case of an error, \var{Status} is set to \var{StWriteError}, and
\var{ErrorInfo} gets the OS specific error.
\SeeAlso
\seep{TStream.Write}, \seepl{Read}{TBufStream.Read}
\end{procedure}

For an example, see \seep{TStream.Read}.

\section{TMemoryStream}
\label{se:TMemoryStream}

The \var{TMemoryStream} object implements a stream that stores it's data
in memory. The data is stored on the heap, with the possibility to specify
the maximum amout of data, and the the size of the memory blocks being used.
 
\begin{verbatim}
TYPE
   TMemoryStream = OBJECT (TStream)
         BlkCount: Sw_Word;       { Number of segments }
         BlkSize : Word;          { Memory block size  }
         MemSize : LongInt;       { Memory alloc size  }
         BlkList : PPointerArray; { Memory block list  }
      CONSTRUCTOR Init (ALimit: Longint; ABlockSize: Word);
      DESTRUCTOR Done;                                               Virtual;
      PROCEDURE Truncate;                                            Virtual;
      PROCEDURE Read (Var Buf; Count: Sw_Word);                      Virtual;
      PROCEDURE Write (Var Buf; Count: Sw_Word);                     Virtual;
   END;
   PMemoryStream = ^TMemoryStream;
\end{verbatim}

\begin{procedure}{TMemoryStream.Init}
\Declaration
Constructor TMemoryStream.Init (ALimit: Longint; ABlockSize: Word);
\Description
\var{Init} instantiates a new \var{TMemoryStream} object. The
memorystreamobject will initially allocate at least \var{ALimit} bytes memory, 
divided into memory blocks of size \var{ABlockSize}. 
The number of blocks needed to get to \var{ALimit} bytes is rounded up.

By default, the number of blocks is 1, and the size of a block is 8192. This
is selected if you specify 0 as the blocksize.
\Errors
If the stream cannot allocate the initial memory needed for the memory blocks, then
the stream's status is set to \var{stInitError}.
\SeeAlso
\seepl{Done}{TMemoryStream.Done}
\end{procedure}

For an example, see e.g \seep{TStream.CopyFrom}.

\begin{procedure}{TMemoryStream.Done}
\Declaration
Destructor TMemoryStream.Done; Virtual;
\Description
\var{Done} releases the memory blocks used by the stream, and then cleans up
the memory used by the stream object itself.
\Errors
None.
\SeeAlso
\seepl{Init}{TMemoryStream.Init}
\end{procedure}

For an example, see e.g \seep{TStream.CopyFrom}.

\begin{procedure}{TMemoryStream.Truncate}
\Declaration
Procedure TMemoryStream.Truncate; Virtual;
\Description
\var{Truncate} sets the size of the memory stream equal to the current
position. It de-allocates any memory-blocks that are no longer needed, so
that the new size of the stream is the current position in the stream,
rounded up to the first multiple of the stream blocksize.
\Errors 
If an error occurs during memory de-allocation, the stream's status is set
to \var{stError}
\SeeAlso
\seep{TStream.Truncate}
\end{procedure}

\FPCexample{ex20}


\begin{procedure}{TMemoryStream.Read}
\Declaration
Procedure Read (Var Buf; Count: Sw\_Word); Virtual;
\Description
\var{Read} reads \var{Count} bytes from the stream to \var{Buf}. It updates
the position of the stream.
\Errors
If there is not enough data available, no data is read, and the stream's
status is set to \var{stReadError}.
\SeeAlso
\var{TStream.Read}, \seepl{Write}{TMemoryStream.Write}
\end{procedure}

For an example, see \seep{TStream.Read}.

\begin{procedure}{TMemoryStream.Write}
\Declaration
Procedure Write (Var Buf; Count: Sw\_Word); Virtual;
\Description
\var{Write} copies \var{Count} bytes from \var{Buf} to the stream. It
updates the position of the stream. 

If not enough memory is available to hold the extra \var{Count} bytes, 
then the stream will try to expand, by allocating as much blocks with 
size \var{BlkSize} (as specified in the constuctor call
\seepl{Init}{TMemoryStream.Init}) as needed. 
\Errors
If the stream cannot allocate more memory, then the status is set to
\var{stWriteError}
\SeeAlso
\seep{TStream.Write}, \seepl{Read}{TMemoryStream.Read}
\end{procedure}

For an example, see \seep{TStream.Read}.

\section{TCollection}
\label{se:TCollection}

The \var{TCollection} object manages a collection of pointers or objects. 
It also provides a series of methods to manipulate these pointers or 
objects.

Whether or not objects are used depends on the kind of calls you use.
ALl kinds come in 2 flavors, one for objects, one for pointers.

This is the full declaration of the \var{TCollection} object:

\begin{verbatim}
TYPE
   TItemList = Array [0..MaxCollectionSize - 1] Of Pointer;
   PItemList = ^TItemList;

   TCollection = OBJECT (TObject)
         Items: PItemList;  { Item list pointer }
         Count: Sw_Integer; { Item count }
         Limit: Sw_Integer; { Item limit count }
         Delta: Sw_Integer; { Inc delta size }
      Constructor Init (ALimit, ADelta: Sw_Integer);
      Constructor Load (Var S: TStream);
      Destructor Done; Virtual;
      Function At (Index: Sw_Integer): Pointer;
      Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
      Function GetItem (Var S: TStream): Pointer; Virtual;
      Function LastThat (Test: Pointer): Pointer;
      Function FirstThat (Test: Pointer): Pointer;
      Procedure Pack;
      Procedure FreeAll;
      Procedure DeleteAll;
      Procedure Free (Item: Pointer);
      Procedure Insert (Item: Pointer); Virtual;
      Procedure Delete (Item: Pointer);
      Procedure AtFree (Index: Sw_Integer);
      Procedure FreeItem (Item: Pointer); Virtual;
      Procedure AtDelete (Index: Sw_Integer);
      Procedure ForEach (Action: Pointer);
      Procedure SetLimit (ALimit: Sw_Integer); Virtual;
      Procedure Error (Code, Info: Integer); Virtual;
      Procedure AtPut (Index: Sw_Integer; Item: Pointer);
      Procedure AtInsert (Index: Sw_Integer; Item: Pointer);
      Procedure Store (Var S: TStream);
      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
   END;
   PCollection = ^TCollection;
\end{verbatim}


\begin{procedure}{TCollection.Init}
\Declaration
Constructor TCollection.Init (ALimit, ADelta: Sw\_Integer);
\Description
\var{Init} initializes a new instance of a collection. It sets the (initial) maximum number
of items in the collection to \var{ALimit}. \var{ADelta} is the increase
size : The number of memory places that will be allocatiod in case \var{ALimit} is reached, 
and another element is added to the collection.
\Errors
None. 
\SeeAlso
\seepl{Load}{TCollection.Load}, \seepl{Done}{TCollection.Done}
\end{procedure}

For an example, see \seep{TCollection.ForEach}.

\begin{procedure}{TCollection.Load}
\Declaration
Constructor TCollection.Load (Var S: TStream);
\Description
\var{Load} initializes a new instance of a collection. It reads from stream
\var{S} the item count, the item limit count, and the increase size. After
that, it reads the specified number of items from the stream. 

% Do not call this method if you intend to use only pointers in your collection.
\Errors
Errors returned can be those of \seefl{GetItem}{TCollection.GetItem}.
\SeeAlso
\seepl{Init}{TCollection.Init}, \seefl{GetItem}{TCollection.GetItem},
\seepl{Done}{TCollection.Done}.
\end{procedure}

\FPCexample{ex22}


\begin{procedure}{TCollection.Done}
\Declaration
Destructor TCollection.Done; Virtual;
\Description
\var{Done} frees all objects in the collection, and then releases all memory
occupied by the instance.

% Do not call this method if you intend to use only pointers in your collection.
\Errors
None.
\SeeAlso
\seepl{Init}{TCollection.Init}, \seepl{FreeAll}{TCollection.FreeAll}
\end{procedure}

For an example, see \seep{TCollection.ForEach}.

\begin{function}{TCollection.At}
\Declaration
Function TCollection.At (Index: Sw\_Integer): Pointer;
\Description
\var{At} returns the item at position \var{Index}.
\Errors
If \var{Index} is less than zero or larger than the number of items
in the collection, seepl{Error}{TCollection.Error} is called with
\var{coIndexError} and \var{Index} as arguments, resulting in a run-time
error.
\SeeAlso
\seepl{Insert}{TCollection.Insert}
\end{function}

\FPCexample{ex23}


\begin{function}{TCollection.IndexOf}
\Declaration
Function TCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
\Description
\var{IndexOf} returns the index of \var{Item} in the collection. 
If \var{Item} isn't present in the collection, -1 is returned.
\Errors
\SeeAlso
\end{function}

\FPCexample{ex24}


\begin{function}{TCollection.GetItem}
\Declaration
Function TCollection.GetItem (Var S: TStream): Pointer; Virtual;
\Description
\var{GetItem} reads a single item off the stream \var{S}, and
returns a pointer to this item. This method is used internally by the Load
method, and should not be used directly.
\Errors
Possible errors are the ones from \seef{TStream.Get}.
\SeeAlso
\seef{TStream.Get}, seepl{Store}{TCollection.Store}
\end{function}

\begin{function}{TCollection.LastThat}
\Declaration
Function TCollection.LastThat (Test: Pointer): Pointer;
\Description
This function returns the last item in the collection for which \var{Test}
returns a non-nil result. \var{Test} is a function that accepts 1 argument:
a pointer to an object, and that returns a pointer as a result.
\Errors
None.
\SeeAlso
\seefl{FirstThat}{TCollection.FirstThat}
\end{function}

\FPCexample{ex25}


\begin{function}{TCollection.FirstThat}
\Declaration
Function TCollection.FirstThat (Test: Pointer): Pointer;
\Description
This function returns the first item in the collection for which \var{Test}
returns a non-nil result. \var{Test} is a function that accepts 1 argument:
a pointer to an object, and that returns a pointer as a result.
\Errors
None.
\SeeAlso
\seefl{LastThat}{TCollection.LastThat}
\end{function}

\FPCexample{ex26}


\begin{procedure}{TCollection.Pack}
\Declaration
Procedure TCollection.Pack;
\Description
\var{Pack} removes all \var{Nil} pointers from the collection, and adjusts
\var{Count} to reflect this change. No memory is freed as a result of this
call. In order to free any memory, you can call \var{SetLimit} with an
argument of \var{Count} after a call to \var{Pack}.
\Errors
None.
\SeeAlso
\seepl{SetLimit}{TCollection.SetLimit}
\end{procedure}

\FPCexample{ex26}


\begin{procedure}{TCollection.FreeAll}
\Declaration
Procedure TCollection.FreeAll;
\Description
\var{FreeAll} calls the destructor of each object in the collection.
It doesn't release any memory occumpied by the collection itself, but it
does set \var{Count} to zero.
\Errors
\SeeAlso
\seepl{DeleteAll}{TCollection.DeleteAll}, \seepl{FreeItem}{TCollection.FreeItem}
\end{procedure}

\FPCexample{ex28}


\begin{procedure}{TCollection.DeleteAll}
\Declaration
Procedure TCollection.DeleteAll;
\Description
\var{DeleteAll} deletes all elements from the collection. It just sets 
the \var{Count} variable to zero. Contrary to
\seepl{FreeAll}{TCollection.FreeAll}, \var{DeletAll} doesn't call the
destructor of the objects.
\Errors
None.
\SeeAlso
\seepl{FreeAll}{TCollection.FreeAll}, \seepl{Delete}{TCollection.Delete}
\end{procedure}

\FPCexample{ex29}


\begin{procedure}{TCollection.Free}
\Declaration
Procedure TCollection.Free (Item: Pointer);
\Description
\var{Free} Deletes \var{Item} from the collection, and calls the destructor
\var{Done} of the object.
\Errors
If the \var{Item} is not in the collection, \var{Error} will be called with
\var{coIndexError}.
\SeeAlso
\seepl{FreeItem}{TCollection.FreeItem},
\end{procedure}

\FPCexample{ex30}


\begin{procedure}{TCollection.Insert}
\Declaration
Procedure TCollection.Insert (Item: Pointer); Virtual;
\Description
\var{Insert} inserts \var{Item} in the collection. \var{TCollection}
inserts this item at the end, but descendent objects may insert it at
another place.
\Errors
None.
\SeeAlso
\seepl{AtInsert}{TCollection.AtInsert}, \seepl{AtPut}{TCollection.AtPut},
\end{procedure}


\begin{procedure}{TCollection.Delete}
\Declaration
Procedure TCollection.Delete (Item: Pointer);
\Description
\var{Delete} deletes \var{Item} from the collection. It doesn't call the
item's destructor, though. For this the \seepl{Free}{TCollection.Free}
call is provided.
\Errors
If the \var{Item} is not in the collection, \var{Error} will be called with
\var{coIndexError}.
\SeeAlso
\seepl{AtDelete}{TCollection.AtDelete},\seepl{Free}{TCollection.Free}
\end{procedure}

\FPCexample{ex31}


\begin{procedure}{TCollection.AtFree}
\Declaration
Procedure TCollection.AtFree (Index: Sw\_Integer);
\Description
\var{AtFree} deletes the item at position \var{Index} in the collection,
and calls the item's destructor if it is not \var{Nil}. 
\Errors
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
with \var{CoIndexError}.
\SeeAlso
\seepl{Free}{TCollection.Free}, \seepl{AtDelete}{TCollection.AtDelete}
\end{procedure}

\FPCexample{ex32}


\begin{procedure}{TCollection.FreeItem}
\Declaration
Procedure TCollection.FreeItem (Item: Pointer); Virtual;
\Description
\var{FreeItem} calls the destructor of \var{Item} if it is not nil.

This function is used internally by the TCollection object, and should not be
called directly.
\Errors
None.
\SeeAlso
\seepl{Free}{TCollection.AtFree}, seepl{AtFree}{TCollection.AtFree}
\end{procedure}


\begin{procedure}{TCollection.AtDelete}
\Declaration
Procedure TCollection.AtDelete (Index: Sw\_Integer);
\Description
\var{AtDelete} deletes the pointer at position \var{Index} in the
collection. It doesn't call the object's destructor.
\Errors
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
with \var{CoIndexError}.
\SeeAlso
\seepl{Delete}{TCollection.Delete}
\end{procedure}


\FPCexample{ex33}


\begin{procedure}{TCollection.ForEach}
\Declaration
Procedure TCollection.ForEach (Action: Pointer);
\Description
\var{ForEach} calls \var{Action} for each element in the collection,
and passes the element as an argument to \var{Action}.

\var{Action} is a procedural type variable that accepts a pointer as an 
argument.
\Errors
None.
\SeeAlso
\seefl{FirstThat}{TCollection.FirstThat}, \seefl{LastThat}{TCollection.LastThat}
\end{procedure}

\FPCexample{ex21}


\begin{procedure}{TCollection.SetLimit}
\Declaration
Procedure TCollection.SetLimit (ALimit: Sw\_Integer); Virtual;
\Description
\var{SetLimit} sets the maximum number of elements in the collection.
\var{ALimit} must not be less than \var{Count}, and should not be larger
than \var{MaxCollectionSize}
\Errors
None.
\SeeAlso
\seepl{Init}{TCollection.Init}
\end{procedure}

For an example, see \seepl{Pack}{TCollection.Pack}.

\begin{procedure}{TCollection.Error}
\Declaration
Procedure TCollection.Error (Code, Info: Integer); Virtual;
\Description
\var{Error} is called by the various \var{TCollection} methods
in case of an error condition. The default behaviour is to make
a call to \var{RunError} with an error of \var{212-Code}.

This method can be overridden by descendent objects to implement
a different error-handling.
\Errors
\SeeAlso
\seep{Abstract}
\end{procedure}

\begin{procedure}{TCollection.AtPut}
\Declaration
Procedure TCollection.AtPut (Index: Sw\_Integer; Item: Pointer);
\Description
\var{AtPut} sets the element at position \var{Index} in the collection
to \var{Item}. Any previous value is overwritten.
\Errors
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
with \var{CoIndexError}.
\SeeAlso
\end{procedure}

For an example, see \seepl{Pack}{TCollection.Pack}.

\begin{procedure}{TCollection.AtInsert}
\Declaration
Procedure TCollection.AtInsert (Index: Sw\_Integer; Item: Pointer);
\Description
\var{AtInsert} inserts \var{Item} in the collection at position \var{Index},
shifting all elements by one position. In case the current limit is reached,
the collection will try to expand with a call to \var{SetLimit}
\Errors
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
with \var{CoIndexError}. If the collection fails to expand, then
\var{coOverFlow} is passd to \var{Error}.
\SeeAlso
\seepl{Insert}{TCollection.Insert}
\end{procedure}

\FPCexample{ex34}


\begin{procedure}{TCollection.Store}
\Declaration
Procedure TCollection.Store (Var S: TStream);
\Description
\var{Store} writes the collection to the stream \var{S}. It does
this by writeing the current \var{Count}, \var{Limit} and \var{Delta}
to the stream, and then writing each item to the stream.

The contents of the stream are then suitable for instantiating another
collection with \seepl{Load}{TCollection.Load}.
\Errors
Errors returned are those by \seep{TStream.Put}.
\SeeAlso
\seepl{Load}{TCollection.Load}, \seepl{PutItem}{TCollection.PutItem}
\end{procedure}

For an example, see seepl{Load}{TCollection.Load}.

\begin{procedure}{TCollection.PutItem}
\Declaration
Procedure TCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
\Description
\var{PutItem} writes \var{Item} to stream \var{S}. This method is used
internaly by the \var{TCollection} object, and should not be called
directly.
\Errors
Errors are those returned by \seep{TStream.Put}.
\SeeAlso
\seepl{Store}{TCollection.Store}, \seefl{GetItem}{TCollection.GetItem}.
\end{procedure}

\section{TSortedCollection}
\label{se:TSortedCollection}

\var{TSortedCollection} is an abstract class, implementing a sorted
collection. You should never use an instance of \var{TSortedCollection}
directly, instead you should declare a descendent type, and override the
\seefl{Compare}{TSortedCollection.Compare} method.

Because the collection is ordered, \var{TSortedCollection} overrides some
\var{TCollection} methods, to provide faster routines for lookup.

The \seefl{Compare}{TSortedCollection.Compare} method decides how elements 
in the collection should be ordered. Since \var{TCollection} has no way
of knowing how to order pointers, you must override the compare method.

Additionally, \var{TCollection} provides a means to filter out duplicates.
if you set \var{Duplicates} to \var{False} (the default) then duplicates
will not be allowed.

Here is the complete declaration of \var{TSortedCollection}

\begin{verbatim}
TYPE
   TSortedCollection = OBJECT (TCollection)
         Duplicates: Boolean; { Duplicates flag }
      Constructor Init (ALimit, ADelta: Sw_Integer);
      Constructor Load (Var S: TStream);
      Function KeyOf (Item: Pointer): Pointer; Virtual;
      Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
      Function Search (Key: Pointer; Var Index: Sw_Integer): Boolean;Virtual;
      Procedure Insert (Item: Pointer); Virtual;
      Procedure Store (Var S: TStream);
   END;
   PSortedCollection = ^TSortedCollection;
\end{verbatim}

In the subsequent examples, the following descendent of
\var{TSortedCollection} is used:

\FPCexample{mysortc}


\begin{procedure}{TSortedCollection.Init}
\Declaration
Constructor TSortedCollection.Init (ALimit, ADelta: Sw\_Integer);
\Description
\var{Init} calls the inherited constuctor (see \seep{TCollection.Init}) and
sets the \var{Duplicates} flag to false.

You should not call this method directly, since \var{TSortedCollection} is a
abstract class. Instead, the descendent classes should call it via the
\var{inherited} keyword.
\Errors
None.
\SeeAlso 
\seepl{Load}{TSortedCollection.Load}, \seepl{Done}{TCollection.Done}
\end{procedure}

For an example, see 

\begin{procedure}{TSortedCollection.Load}
\Declaration
Constructor Load (Var S: TStream);
\Description
\var{Load} calls the inherited constuctor (see \seep{TCollection.Load}) and
reads the \var{Duplicates} flag from the stream..

You should not call this method directly, since \var{TSortedCollection} is a
abstract class. Instead, the descendent classes should call it via the
\var{inherited} keyword.
\Errors
None.
\SeeAlso 
\seepl{Init}{TSortedCollection.Init}, \seepl{Done}{TCollection.Done}
\end{procedure}

For an example, see \seep{TCollection.Load}.

\begin{function}{TSortedCollection.KeyOf}
\Declaration
Function TSortedCollection.KeyOf (Item: Pointer): Pointer; Virtual;
\Description
\var{KeyOf} returns the key associated with \var{Item}.
\var{TSortedCollection} returns the item itself as the key, descendent
objects can override this method to calculate a (unique) key based on the
item passed (such as hash values).

\var{Keys} are used to sort the objects, they are used to search and sort
the items in the collection. If descendent types override this method then
it allows possibly for faster search/sort methods based on keys rather than
on the objects themselves.
\Errors
None.
\SeeAlso
\seefl{IndexOf}{TSortedCollection.IndexOf},
\seefl{Compare}{TSortedCollection.Compare}.
\end{function}

\begin{function}{TSortedCollection.IndexOf}
\Declaration
Function TSortedCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
\Description
\var{IndexOf} returns the index of \var{Item} in the collection. It searches
for the object based on it's key. If duplicates are allowed, then it returns 
the index of last object that matches \var{Item}.

In case \var{Item} is not found in the collection, -1 is returned.
\Errors
None.
\SeeAlso
\seefl{Search}{TSortedCollection.Search},
\seefl{Compare}{TSortedCollection.Compare}.
\end{function}

For an example, see \seef{TCollection.IndexOf}

\begin{function}{TSortedCollection.Compare}
\Declaration
Function TSortedCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
\Description
\var{Compare} is an abstract method that should be overridden by descendent
objects in order to compare two items in the collection. This method is used
in the \seefl{Search}{TSortedCollection.Search} method and in the
\seepl{Insert}{TSortedCollection.Insert} method to determine the ordering of
the objects.

The function should compare the two keys of items and return the following
function results:
\begin{description}
\item [Result < 0] If \var{Key1} is logically before \var{Key2}
(\var{Key1<Key2})
\item [Result = 0] If \var{Key1} and \var{Key2} are equal. (\var{Key1=Key2})
\item [Result > 0] If \var{Key1} is logically after \var{Key2}
(\var{Key1>Key2})
\end{description}
\Errors
An 'abstract run-time error' will be generated if you call
\var{TSortedCollection.Compare} directly.
\SeeAlso
\seefl{IndexOf}{TSortedCollection.IndexOf},
\seefl{Search}{TSortedCollection.Search}
\end{function}

\FPCexample{mysortc}


\begin{function}{TSortedCollection.Search}
\Declaration
Function TSortedCollection.Search (Key: Pointer; Var Index: Sw\_Integer): Boolean;Virtual;
\Description
\var{Search} looks for the item with key \var{Key} and returns the position 
of the item (if present) in the collection in \var{Index}.

Instead of a linear search as \var{TCollection} does, \var{TSortedCollection}
uses a binary search based on the keys of the objects. It uses the
\seefl{Compare}{TSortedCollection.Compare} function to implement this
search. 

If the item is found, \var{Search} returns \var{True}, otherwise \var{False}
is returned.
\Errors
None.
\SeeAlso
\seefl{IndexOf}{TCollection.IndexOf}.
\end{function}

\FPCexample{ex36}


\begin{procedure}{TSortedCollection.Insert}
\Declaration
Procedure TSortedCollection.Insert (Item: Pointer); Virtual;
\Description
\var{Insert} inserts an item in the collection at the correct position, such
that the collection is ordered at all times. You should never use
\seepl{Atinsert}{TCollection.AtInsert}, since then the collection ordering
is not guaranteed.

If \var{Item} is already present in the collection, and \var{Duplicates} is
\var{False}, the item will not be inserted.
\Errors
None.
\SeeAlso
\seepl{AtInsert}{TCollection.AtInsert}
\end{procedure}

\FPCexample{ex35}


\begin{procedure}{TSortedCollection.Store}
\Declaration
Procedure TSortedCollection.Store (Var S: TStream);
\Description
\var{Store} writes the collection to the stream \var{S}. It does this by
calling the inherited \seep{TCollection.Store}, and then writing the
\var{Duplicates} flag to the stream.

After a \var{Store}, the collection can be loaded from the stream with the 
constructor \seepl{Load}{TSortedCollection.Load}
\Errors
Errors can be those of \seep{TStream.Put}.
\SeeAlso
\seepl{Load}{TSortedCollection.Load}
\end{procedure}

For an example, see \seep{TCollection.Load}.

\section{TStringCollection}
\label{se:TStringCollection}

The \var{TStringCollection} object manages a sorted collection of pascal 
strings. 
To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
method of \var{TSortedCollection}, and it introduces methods to read/write
strings from a stream.

Here is the full declaration of the \var{TStringCollection} object:
\begin{verbatim}
TYPE
   TStringCollection = OBJECT (TSortedCollection)
      Function GetItem (Var S: TStream): Pointer; Virtual;
      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
      Procedure FreeItem (Item: Pointer); Virtual;
      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
   END;
   PStringCollection = ^TStringCollection;
\end{verbatim}

\begin{function}{TStringCollection.GetItem}
\Declaration
Function TStringCollection.GetItem (Var S: TStream): Pointer; Virtual;
\Description
\var{GetItem} reads a string from the stream \var{S} and returns a pointer 
to it. It doesn't insert the string in the collection.

This method is primarily introduced to be able to load and store the
collection from and to a stream.
\Errors
The errors returned are those of \seef{TStream.ReadStr}.
\SeeAlso
\seepl{PutItem}{TStringCollection.PutItem}
\end{function}

\begin{function}{TStringCollection.Compare}
\Declaration
Function TStringCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
\Description
\var{TStringCollection} overrides the \var{Compare} function so it compares 
the two keys as if they were pointers to strings. The compare is done case
sensitive. It returns the following results:
\begin{description}
\item[-1] if the first string is alphabetically earlier  than the second
string.
\item[0] if the two strings are equal.
\item[1] if the first string is alphabetically later than the second string.
\end{description}
\Errors
None.
\SeeAlso
\seef{TSortedCollection.Compare}
\end{function}

\FPCexample{ex37}


\begin{procedure}{TStringCollection.FreeItem}
\Declaration
Procedure TStringCollection.FreeItem (Item: Pointer); Virtual;
\Description
\var{TStringCollection} overrides \var{FreeItem} so that the string pointed
to by \var{Item} is disposed from memory.
\Errors
None.
\SeeAlso
\seep{TCollection.FreeItem}
\end{procedure}

\begin{procedure}{TStringCollection.PutItem}
\Declaration
Procedure TStringCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
\Description
\var{PutItem} writes the string pointed to by \var{Item} to the stream
\var{S}. 

This method is primarily used in the \var{Load} and \var{Store} methods, 
and should not be used directly.
\Errors
Errors are those of \seep{TStream.WriteStr}.
\SeeAlso
\seefl{GetItem}{TStringCollection.GetItem}
\end{procedure}


\section{TStrCollection}
\label{se:TStrCollection}

The \var{TStrCollection} object manages a sorted collection
of null-terminated strings (pchar strings).  
To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
method of \var{TSortedCollection}, and it introduces methods to read/write
strings from a stream.

Here is the full declaration of the \var{TStrCollection} object:

\begin{verbatim}
TYPE
   TStrCollection = OBJECT (TSortedCollection)
      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
      Function GetItem (Var S: TStream): Pointer; Virtual;
      Procedure FreeItem (Item: Pointer); Virtual;
      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
   END;
   PStrCollection = ^TStrCollection;
\end{verbatim}

\begin{function}{TStrCollection.GetItem}
\Declaration
Function TStrCollection.GetItem (Var S: TStream): Pointer; Virtual;
\Description
\var{GetItem} reads a null-terminated string from the stream \var{S} 
and returns a pointer  to it. It doesn't insert the string in the 
collection.

This method is primarily introduced to be able to load and store the
collection from and to a stream.
\Errors
The errors returned are those of \seef{TStream.StrRead}.
\SeeAlso
\seepl{PutItem}{TStrCollection.PutItem}
\end{function}

\begin{function}{TStrCollection.Compare}
\Declaration
Function TStrCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
\Description
\var{TStrCollection} overrides the \var{Compare} function so it compares 
the two keys as if they were pointers to strings. The compare is done case
sensitive. It returns
\begin{description}
\item[-1] if the first string is alphabetically earlier  than the second
string.
\item[0] if the two strings are equal.
\item[1] if the first string is alphabetically later than the second string.
\end{description}
\Errors
None.
\SeeAlso
\seef{TSortedCollection.Compare}
\end{function}

\FPCexample{ex38}


\begin{procedure}{TStrCollection.FreeItem}
\Declaration
Procedure TStrCollection.FreeItem (Item: Pointer); Virtual;
\Description
\var{TStrCollection} overrides \var{FreeItem} so that the string pointed
to by \var{Item} is disposed from memory.
\Errors
None.
\SeeAlso
\seep{TCollection.FreeItem}
\end{procedure}

\begin{procedure}{TStrCollection.PutItem}
\Declaration
Procedure TStrCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
\Description
\var{PutItem} writes the string pointed to by \var{Item} to the stream
\var{S}. 

This method is primarily used in the \var{Load} and \var{Store} methods, 
and should not be used directly.
\Errors
Errors are those of \seep{TStream.StrWrite}.
\SeeAlso
\seefl{GetItem}{TStrCollection.GetItem}
\end{procedure}

\section{TUnSortedStrCollection}
\label{se:TUnSortedStrCollection}

The \var{TUnSortedStrCollection} object manages an unsorted list of strings.
To this end, it overrides the \seep{TStringCollection.Insert} method to add
strings at the end of the collection, rather than in the alphabetically
correct position.

Take care, the \seefl{Search}{TSortedCollection.Search} and
\seefl{IndexOf}{TCollection.IndexOf} methods will not work on an unsorted
string collection.

Here is the full declaration of the {TUnsortedStrCollection} object:
\begin{verbatim}
TYPE
   TUnSortedStrCollection = OBJECT (TStringCollection)
      Procedure Insert (Item: Pointer); Virtual;
   END;
   PUnSortedStrCollection = ^TUnSortedStrCollection;
\end{verbatim}

\begin{procedure}{TUnSortedStrCollection.Insert}
\Declaration
Procedure TUnSortedStrCollection.Insert (Item: Pointer); Virtual;
\Description
\var{Insert} inserts a string at the end of the collection, instead
of on it's alphabetical place, resulting in an unsorted collection of
strings. 
\Errors
\SeeAlso
\end{procedure}

\FPCexample{ex39}


\section{TResourceCollection}
\label{se:TResourceCollection}

A \var{TResourceCollection} manages a collection of resource names. 
It stores the position and the size of a resource, as well as the name of
the resource. It stores these items in records that look like this:
\begin{verbatim}
TYPE
   TResourceItem = packed RECORD
      Posn: LongInt;
      Size: LongInt;
      Key : String;
   End;
   PResourceItem = ^TResourceItem;
\end{verbatim}

It overrides some methods of \var{TStringCollection} in order to accomplish
this. 

Remark that the \var{TResourceCollection} manages the names of the
resources and their assiciated positions and sizes, it doesn't manage
the resources themselves.

Here is the full declaration of the \var{TResourceCollection} object:
\begin{verbatim}
TYPE
   TResourceCollection = OBJECT (TStringCollection)
      Function KeyOf (Item: Pointer): Pointer; Virtual;
      Function GetItem (Var S: TStream): Pointer; Virtual;
      Procedure FreeItem (Item: Pointer); Virtual;
      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
   END;
   PResourceCollection = ^TResourceCollection;
\end{verbatim}

\begin{function}{TResourceCollection.KeyOf}
\Declaration
Function TResourceCollection.KeyOf (Item: Pointer): Pointer; Virtual;
\Description
\var{KeyOf} returns the key of an item in the collection. For resources, the
key is a pointer to the string with the resource name.
\Errors
None.
\SeeAlso
\seef{TStringCollection.Compare}
\end{function}

\begin{function}{TResourceCollection.GetItem}
\Declaration
Function TResourceCollection.GetItem (Var S: TStream): Pointer; Virtual;
\Description
\var{GetItem} reads a resource item from the stream \var{S}. It reads the
position, size and name from the stream, in that order. It DOES NOT read the
resource itself from the stream.

The resulting item is not inserted in the collection. This call is manly for
internal use by the \seep{TCollection.Load} method.
\Errors
Errors returned are those by \seep{TStream.Read}
\SeeAlso
\seep{TCollection.Load}, \seep{TStream.Read}
\end{function}

\begin{procedure}{TResourceCollection.FreeItem}
\Declaration
Procedure TResourceCollection.FreeItem (Item: Pointer); Virtual;
\Description
\var{FreeItem} releases the memory occupied by \var{Item}. It de-allocates
the name, and then the resourceitem record.

It does NOT remove the item from the collection.
\Errors
None.
\SeeAlso
\seep{TCollection.FreeItem}
\end{procedure}

\begin{procedure}{TResourceCollection.PutItem}
\Declaration
Procedure TResourceCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
\Description
\var{PutItem} writes \var{Item} to the stream \var{S}. It does this by
writing the position and size and name of the resource item to the stream.

This method is used primarily by the \seepl{Store}{TCollection.Store}
method.
\Errors
Errors returned are those by \seep{TStream.Write}.
\SeeAlso
\seepl{Store}{TCollection.Store}
\end{procedure}


\section{TResourceFile}
\label{se:TResourceFile}

\begin{verbatim}
TYPE
   TResourceFile = OBJECT (TObject)
         Stream  : PStream; { File as a stream }
         Modified: Boolean; { Modified flag }
      Constructor Init (AStream: PStream);
      Destructor Done; Virtual;
      Function Count: Sw_Integer;
      Function KeyAt (I: Sw_Integer): String;
      Function Get (Key: String): PObject;
      Function SwitchTo (AStream: PStream; Pack: Boolean): PStream;
      Procedure Flush;
      Procedure Delete (Key: String);
      Procedure Put (Item: PObject; Key: String);
   END;
   PResourceFile = ^TResourceFile;
\end{verbatim}

\subsection{TResourceFile Fields}

\var{TResourceFile} has the following fields:
\begin{description}
\item[Stream] contains the (file) stream that has the executable image and
the resources. It can be initialized by the \seepl{Init}{TResourceFile.Init}
constructor call.
\item[Modified] is set to \var{True} if one of the resources has been changed.
It is set by the \seepl{SwitchTo}{TResourceFile.Init},
\seepl{Delete}{TResourceFile.Delete} and \seepl{Put}{TResourceFile.Put}
methods. Calling \seepl{Flush}{TResourceFile.Flush} will clear the
\var{Modified} flag.
\end{description}

\begin{procedure}{TResourceFile.Init}
\Declaration
Constructor TResourceFile.Init (AStream: PStream);
\Description
\var{Init} instantiates a new instance of a \var{TResourceFile} object.
If \var{AStream} is not nil then it is considered as a stream describing an
executable image on disk. 

\var{Init} will try to position the stream on the start of the resources section,
and read all resources from the stream.
\Errors
None.
\SeeAlso
\seepl{Done}{TResourceFile.Done}
\end{procedure}

\begin{procedure}{TResourceFile.Done}
\Declaration
Destructor TResourceFile.Done; Virtual;
\Description
\var{Done} cleans up the instance of the \var{TResourceFile} Object. 
If \var{Stream} was specified at initialization, then \var{Stream} is 
disposed of too.
\Errors
None.
\SeeAlso
\seepl{Init}{TResourceFile.Init}
\end{procedure}

\begin{function}{TResourceFile.Count}
\Declaration
Function TResourceFile.Count: Sw\_Integer;
\Description
\var{Count} returns the number of resources. If no resources were
read, zero is returned.
\Errors
None.
\SeeAlso
\seepl{Init}{TResourceFile.Init}
\end{function}

\begin{function}{TResourceFile.KeyAt}
\Declaration
Function TResourceFile.KeyAt (I: Sw\_Integer): String;
\Description
\var{KeyAt} returns the key (the name) of the \var{I}-th resource.
\Errors
In case \var{I} is invalid, \var{TCollection.Error} will be executed.
\SeeAlso
\seefl{Get}{TResourceFile.Get}
\end{function}

\begin{function}{TResourceFile.Get}
\Declaration
Function TResourceFile.Get (Key: String): PObject;
\Description
\var{Get} returns a pointer to a instance of a resource identified by
\var{Key}. If \var{Key} cannot be found in the list of resources, then
\var{Nil} is returned.
\Errors
Errors returned may be those by \var{TStream.Get}
\SeeAlso
\end{function}

\begin{function}{TResourceFile.SwitchTo}
\Declaration
Function TResourceFile.SwitchTo (AStream: PStream; Pack: Boolean): PStream;
\Description
\var{SwitchTo} switches to a new stream to hold the resources in.
\var{AStream} will be the new stream after the call to \var{SwitchTo}.

If \var{Pack} is true, then all the known resources will be copied from 
the current stream to the new stream (\var{AStream}). If \var{Pack} is 
\var{False}, then only the current resource is copied.

The return value is the value of the original stream: \var{Stream}.

The \var{Modified} flag is set as a consequence of this call.
\Errors
Errors returned can be those of \seep{TStream.Read} and
\seep{TStream.Write}.
\SeeAlso
\seepl{Flush}{TResourceFile.Flush}
\end{function}

\begin{procedure}{TResourceFile.Flush}
\Declaration
Procedure TResourceFile.Flush;
\Description
If the \var{Modified} flag is set to \var{True}, then \var{Flush} 
writes the resources to the stream \var{Stream}. It sets the \var{Modified}
flag to true after that.
\Errors
Errors can be those by \seep{TStream.Seek} and \seep{TStream.Write}.
\SeeAlso
\seefl{SwitchTo}{TResourceFile.SwitchTo}
\end{procedure}

\begin{procedure}{TResourceFile.Delete}
\Declaration
Procedure TResourceFile.Delete (Key: String);
\Description
\var{Delete} deletes the resource identified by \var{Key} from the
collection. It sets the \var{Modified} flag to true.
\Errors
None.
\SeeAlso
\seepl{Flush}{TResourceFile.Flush}
\end{procedure}

\begin{procedure}{TResourceFile.Put}
\Declaration
Procedure TResourceFile.Put (Item: PObject; Key: String);
\Description
\var{Put} sets the resource identified by \var{Key} to \var{Item}.
If no such resource exists, a new one is created. The item is written
to the stream.
\Errors
Errors returned may be those by \seep{TStream.Put} and \var{TStream.Seek}
\SeeAlso
\seefl{Get}{TResourceFile.Get}
\end{procedure}

\section{TStringList}
\label{se:TStringList}

A \var{TStringList} object can be used to read a collection of strings
stored in a stream. If you register this object with the \seep{RegisterType}
function, you cannot register the \var{TStrListMaker} object.

This is the public declaration of the \var{TStringList} object:
\begin{verbatim}
TYPE
   TStrIndexRec = Packed RECORD
      Key, Count, Offset: Word;
   END;

   TStrIndex = Array [0..9999] Of TStrIndexRec;
   PStrIndex = ^TStrIndex;

   TStringList = OBJECT (TObject)
      Constructor Load (Var S: TStream);
      Destructor Done; Virtual;
      Function Get (Key: Sw_Word): String;
   END;
   PStringList = ^TStringList;
\end{verbatim}

\begin{procedure}{TStringList.Load}
\Declaration
Constructor TstringList.Load (Var S: TStream);
\Description
The \var{Load} constructor reads the \var{TStringList} object from the
stream \var{S}. It also reads the descriptions of the strings from the
stream. The string descriptions are stored as an array of 
\var{TstrIndexrec} records, where each record describes a string on the
stream. These records are kept in memory.
\Errors
If an error occurs, a stream error is triggered.
\SeeAlso
\seepl{Done}{TStringList.Done}
\end{procedure}

\begin{procedure}{TStringList.Done}
\Declaration
Destructor TstringList.Done; Virtual;
\Description
The \var{Done} destructor frees the memory occupied by the string
descriptions, and destroys the object.
\Errors
None.
\SeeAlso
\seepl{Load}{TStringList.Load}, \seep{TObject.Done}
\end{procedure}

\begin{function}{TStringList.Get}
\Declaration
Function TStringList.Get (Key: Sw\_Word): String;
\Description
\var{Get} reads the string with key \var{Key} from the list of strings on the
stream, and returns this string. If there is no string with such a key, an
empty string is returned.
\Errors
If no string with key \var{Key} is found, an empty string is returned.
A stream error may result if the stream doesn't contain the needed strings.
\SeeAlso
\seep{TStrListMaker.Put}
\end{function}
\section{TStrListMaker}
\label{se:TStrListMaker}

The \var{TStrListMaker} object can be used to generate a stream with
strings, which can be read with the \var{TStringList} object.
If you register this object with the \seep{RegisterType}
function, you cannot register the \var{TStringList} object.

This is the public declaration of the \var{TStrListMaker} object:
\begin{verbatim}
TYPE
   TStrListMaker = OBJECT (TObject)
      Constructor Init (AStrSize, AIndexSize: Sw_Word);
      Destructor Done; Virtual;
      Procedure Put (Key: SwWord; S: String);
      Procedure Store (Var S: TStream);
   END;
   PStrListMaker = ^TStrListMaker;
\end{verbatim}

\begin{procedure}{TStrListMaker.Init}
\Declaration
Constructor TStrListMaker.Init (AStrSize, AIndexSize: SwWord);
\Description
The \var{Init} constructor creates a new instance of the \var{TstrListMaker}
object. It allocates \var{AStrSize} bytes on the heap to hold all the
strings you wish to store. It also allocates enough room for 
\var{AIndexSize} key description entries (of the type \var{TStrIndexrec}).

\var{AStrSize} must be large enough to contain all the strings you wish to
store. If not enough memory is allocated, other memory will be overwritten.
The same is true for \var{AIndexSize} : maximally \var{AIndexSize} strings
can be written to the stream.
\Errors
None.
\SeeAlso
\seep{TObject.Init}, \seepl{Done}{TStrListMaker.Done}
\end{procedure}

\begin{procedure}{TStrListMaker.Done}
\Declaration
Destructor TStrListMaker.Done; Virtual;
\Description
The \var{Done} destructor de-allocates the memory for the index description
records and the string data, and then destroys the object. 
\Errors
None.
\SeeAlso
\seep{TObject.Done}, \seepl{Init}{TStrListMaker.Init}
\end{procedure}

\begin{procedure}{TStrListMaker.Put}
\Declaration
Procedure TStrListMaker.Put (Key: Sw\_Word; S: String);
\Description
\var{Put} adds they string \var{S} with key \var{Key} to the collection of
strings. This action doesn't write the string to a stream. To write the
strings to the stream, see the \seepl{Store}{TStrListMaker.Store} method.
\Errors
None.
\SeeAlso
\seepl{Store}{TStrListMaker.Store}.
\end{procedure}

\begin{procedure}{TStrListMaker.Store}
\Declaration
Procedure TStrListMaker.Store (Var S: TStream);
\Description
\var{Store} writes the collection of strings to the stream \var{S}.
The collection can then be read with the \var{TStringList} object.
\Errors
A stream error may occur when writing the strings to the stream.
\SeeAlso
\seep{TStringList.Load}, \seepl{Put}{TStrListMaker.Put}.
\end{procedure}