mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-04-12 03:48:55 +02:00
356a3d1609
* provided local copies or required styles since debian does not
supply the listings.sty anymore
2531 lines
76 KiB
TeX
2531 lines
76 KiB
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}
|
|
|
|
|