2
% $Id: objects.tex,v 1.3 2003/03/16 15:22:18 peter Exp $
3
% This file is part of the FPC documentation.
4
% Copyright (C) 1998, by Michael Van Canneyt
6
% The FPC documentation is free text; you can redistribute it and/or
7
% modify it under the terms of the GNU Library General Public License as
8
% published by the Free Software Foundation; either version 2 of the
9
% License, or (at your option) any later version.
11
% The FPC Documentation is distributed in the hope that it will be useful,
12
% but WITHOUT ANY WARRANTY; without even the implied warranty of
13
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
% Library General Public License for more details.
16
% You should have received a copy of the GNU Library General Public
17
% License along with the FPC documentation; see the file COPYING.LIB. If not,
18
% write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19
% Boston, MA 02111-1307, USA.
21
\chapter{The Objects unit.}
22
\label{ch:objectsunit}
24
\FPCexampledir{objectex}
25
This chapter documents the \file{objects} unit. The unit was implemented by
26
many people, and was mainly taken from the FreeVision sources. It has been
27
ported to all supported platforms.
29
The methods and fields that are in a \var{Private} part of an object
30
declaration have been left out of this documentation.
33
The following constants are error codes, returned by the various stream
38
stOk = 0; { No stream error }
39
stError = -1; { Access error }
40
stInitError = -2; { Initialize error }
41
stReadError = -3; { Stream read error }
42
stWriteError = -4; { Stream write error }
43
stGetError = -5; { Get object error }
44
stPutError = -6; { Put object error }
45
stSeekError = -7; { Seek error in stream }
46
stOpenError = -8; { Error opening stream }
48
These constants can be passed to constructors of file streams:
51
stCreate = $3C00; { Create new file }
52
stOpenRead = $3D00; { Read access only }
53
stOpenWrite = $3D01; { Write access only }
54
stOpen = $3D02; { Read/write access }
57
The following constants are error codes, returned by the collection list
61
coIndexError = -1; { Index out of range }
62
coOverflow = -2; { Overflow }
65
Maximum data sizes (used in determining how many data can be used.
69
MaxBytes = 128*1024*1024; { Maximum data size }
70
MaxWords = MaxBytes DIV SizeOf(Word); { Max word data size }
71
MaxPtrs = MaxBytes DIV SizeOf(Pointer); { Max ptr data size }
72
MaxCollectionSize = MaxBytes DIV SizeOf(Pointer); { Max collection size }
76
The follwing auxiliary types are defined:
80
TCharSet = SET Of Char;
84
TByteArray = ARRAY [0..MaxBytes-1] Of Byte;
85
PByteArray = ^TByteArray;
88
TWordArray = ARRAY [0..MaxWords-1] Of Word;
89
PWordArray = ^TWordArray;
92
TPointerArray = Array [0..MaxPtrs-1] Of Pointer;
93
PPointerArray = ^TPointerArray;
99
AsciiZ = Array [0..255] Of Char;
102
Sw_Integer = LongInt;
104
The following records are used internaly for easy type conversion:
108
WordRec = packed RECORD
113
LongRec = packed RECORD
118
PtrRec = packed RECORD
123
The following record is used when streaming objects:
127
PStreamRec = ^TStreamRec;
128
TStreamRec = Packed RECORD
137
The \var{TPoint} basic object is used in the \var{TRect} object (see
147
\section{Procedures and Functions}
149
\begin{function}{NewStr}
151
Function NewStr (Const S: String): PString;
153
\var{NewStr} makes a copy of the string \var{S} on the heap,
154
and returns a pointer to this copy.
156
The allocated memory is not based on the declared size of the string passed
157
to \var{NewStr}, but is baed on the actual length of the string.
159
If not enough memory is available, an 'out of memory' error will occur.
166
\begin{procedure}{DisposeStr}
168
Procedure DisposeStr (P: PString);
170
\var{DisposeStr} removes a dynamically allocated string from the heap.
177
For an example, see \seef{NewStr}.
179
\begin{procedure}{Abstract}
183
When implementing abstract methods, do not declare them as \var{abstract}.
184
Instead, define them simply as \var{virtual}. In the implementation of such
185
abstract methods, call the \var{Abstract} procedure. This allows explicit
186
control of what happens when an abstract method is called.
188
The current implementation of \var{Abstract} terminates the program with
189
a run-time error 211.
192
\SeeAlso Most abstract types.
195
\begin{procedure}{RegisterObjects}
197
Procedure RegisterObjects;
199
\var{RegisterObjects} registers the following objects for streaming:
201
\item \var{TCollection}, see \sees{TCollection}.
202
\item \var{TStringCollection}, see \sees{TStringCollection}.
203
\item \var{TStrCollection}, see \sees{TStrCollection}.
211
\begin{procedure}{RegisterType}
213
Procedure RegisterType (Var S: TStreamRec);
215
\var{RegisterType} registers a new type for streaming. An object cannot
216
be streamed unless it has been registered first.
217
The stream record \var{S} needs to have the following fields set:
220
\item[ObjType: Sw\_Word] This should be a unique identifier. Each possible
221
type should have it's own identifier.
222
\item[VmtLink: pointer] This should contain a pointer to the VMT (Virtual
223
Method Table) of the object you try to register. You can get it with the
224
following expression:
226
VmtLink: Ofs(TypeOf(MyType)^);
228
\item[Load : Pointer] is a pointer to a method that initializes an instance
229
of that object, and reads the initial values from a stream. This method
230
should accept as it's sole argument a \var{PStream} type variable.
231
\item[Store: Pointer]is a pointer to a method that stores an instance of the
232
object to a stream. This method should accept as it's sole argument
233
a \var{PStream} type variable.
236
In case of error (if a object with the same \var{ObjType}) is already
237
registered), run-time error 212 occurs.
240
\FPCexample{myobject}
242
\begin{function}{LongMul}
244
Function LongMul (X, Y: Integer): LongInt;
246
\var{LongMul} multiplies \var{X} with \var{Y}. The result is of
247
type \var{Longint}. This avoids possible overflow errors you would normally
248
get when multiplying \var{X} and \var{Y} that are too big.
255
\begin{function}{LongDiv}
257
Function LongDiv (X: Longint; Y: Integer): Integer;
259
\var{LongDiv} divides \var{X} by \var{Y}. The result is of
260
type \var{Integer} instead of type \var{Longint}, as you would get
263
If Y is zero, a run-time error will be generated.
271
The \var{TRect} object is declared as follows:
275
FUNCTION Empty: Boolean;
276
FUNCTION Equals (R: TRect): Boolean;
277
FUNCTION Contains (P: TPoint): Boolean;
278
PROCEDURE Copy (R: TRect);
279
PROCEDURE Union (R: TRect);
280
PROCEDURE Intersect (R: TRect);
281
PROCEDURE Move (ADX, ADY: Sw_Integer);
282
PROCEDURE Grow (ADX, ADY: Sw_Integer);
283
PROCEDURE Assign (XA, YA, XB, YB: Sw_Integer);
287
\begin{function}{TRect.Empty}
289
Function TRect.Empty: Boolean;
291
\var{Empty} returns \var{True} if the rectangle defined by the corner points
292
\var{A}, \var{B} has zero or negative surface.
296
\seef{TRect.Equals}, \seef{TRect.Contains}
301
\begin{function}{TRect.Equals}
303
Function TRect.Equals (R: TRect): Boolean;
305
\var{Equals} returns \var{True} if the rectangle has the
306
same corner points \var{A,B} as the rectangle R, and \var{False}
311
\seefl{Empty}{TRect.Empty}, \seefl{Contains}{TRect.Contains}
314
For an example, see \seef{TRect.Empty}
316
\begin{function}{TRect.Contains}
318
Function TRect.Contains (P: TPoint): Boolean;
320
\var{Contains} returns \var{True} if the point \var{P} is contained
321
in the rectangle (including borders), \var{False} otherwise.
325
\seepl{Intersect}{TRect.Intersect}, \seefl{Equals}{TRect.Equals}
328
\begin{procedure}{TRect.Copy}
330
Procedure TRect.Copy (R: TRect);
332
Assigns the rectangle R to the object. After the call to \var{Copy}, the
333
rectangle R has been copied to the object that invoked \var{Copy}.
337
\seepl{Assign}{TRect.Assign}
342
\begin{procedure}{TRect.Union}
344
Procedure TRect.Union (R: TRect);
346
\var{Union} enlarges the current rectangle so that it becomes the union
347
of the current rectangle with the rectangle \var{R}.
351
\seepl{Intersect}{TRect.Intersect}
356
\begin{procedure}{TRect.Intersect}
358
Procedure TRect.Intersect (R: TRect);
360
\var{Intersect} makes the intersection of the current rectangle with
361
\var{R}. If the intersection is empty, then the rectangle is set to the empty
362
rectangle at coordinate (0,0).
366
\seepl{Union}{TRect.Union}
371
\begin{procedure}{TRect.Move}
373
Procedure TRect.Move (ADX, ADY: Sw\_Integer);
375
\var{Move} moves the current rectangle along a vector with components
376
\var{(ADX,ADY)}. It adds \var{ADX} to the X-coordinate of both corner
377
points, and \var{ADY} to both end points.
381
\seepl{Grow}{TRect.Grow}
386
\begin{procedure}{TRect.Grow}
388
Procedure TRect.Grow (ADX, ADY: Sw\_Integer);
390
\var{Grow} expands the rectangle with an amount \var{ADX} in the \var{X}
391
direction (both on the left and right side of the rectangle, thus adding a
392
length 2*ADX to the width of the rectangle), and an amount \var{ADY} in
393
the \var{Y} direction (both on the top and the bottom side of the rectangle,
394
adding a length 2*ADY to the height of the rectangle.
396
\var{ADX} and \var{ADY} can be negative. If the resulting rectangle is empty, it is set
397
to the empty rectangle at \var{(0,0)}.
401
\seepl{Move}{TRect.Move}.
407
\begin{procedure}{TRect.Assign}
409
Procedure Trect.Assign (XA, YA, XB, YB: Sw\_Integer);
411
\var{Assign} sets the corner points of the rectangle to \var{(XA,YA)} and
416
\seepl{Copy}{TRect.Copy}
419
For an example, see \seep{TRect.Copy}.
424
The full declaration of the \var{TObject} type is:
430
DESTRUCTOR Done;Virtual;
434
\begin{procedure}{TObject.Init}
436
Constructor TObject.Init;
438
Instantiates a new object of type \var{TObject}. It fills the instance up
443
\seepl{Free}{TObject.Free}, \seepl{Done}{TObject.Done}
446
For an example, see \seepl{Free}{TObject.Free}
448
\begin{procedure}{TObject.Free}
450
Procedure TObject.Free;
452
\var{Free} calls the destructor of the object, and releases the memory
453
occupied by the instance of the object.
455
No checking is performed to see whether \var{self} is \var{nil} and whether
456
the object is indeed allocated on the heap.
458
\seepl{Init}{TObject.Init}, \seepl{Done}{TObject.Done}
463
\begin{procedure}{TObject.Done}
465
Destructor TObject.Done;Virtual;
467
\var{Done}, the destructor of \var{TObject} does nothing. It is mainly
468
intended to be used in the \seep{TObject.Free} method.
470
The destructore Done does not free the memory occupied by the object.
474
\seepl{Free}{TObject.Free}, \seepl{Init}{TObject.Init}
482
The \var{TStream} object is the ancestor for all streaming objects, i.e.
483
objects that have the capability to store and retrieve data.
485
It defines a number of methods that are common to all objects that implement
486
streaming, many of them are virtual, and are only implemented in the
489
Programs should not instantiate objects of type TStream directly, but
490
instead instantiate a descendant type, such as \var{TDosStream},
493
This is the full declaration of the \var{TStream} object:
496
TStream = OBJECT (TObject)
497
Status : Integer; { Stream status }
498
ErrorInfo : Integer; { Stream error info }
499
StreamSize: LongInt; { Stream current size }
500
Position : LongInt; { Current position }
501
FUNCTION Get: PObject;
502
FUNCTION StrRead: PChar;
503
FUNCTION GetPos: Longint; Virtual;
504
FUNCTION GetSize: Longint; Virtual;
505
FUNCTION ReadStr: PString;
506
PROCEDURE Open (OpenMode: Word); Virtual;
507
PROCEDURE Close; Virtual;
509
PROCEDURE Flush; Virtual;
510
PROCEDURE Truncate; Virtual;
511
PROCEDURE Put (P: PObject);
512
PROCEDURE StrWrite (P: PChar);
513
PROCEDURE WriteStr (P: PString);
514
PROCEDURE Seek (Pos: LongInt); Virtual;
515
PROCEDURE Error (Code, Info: Integer); Virtual;
516
PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
517
PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
518
PROCEDURE CopyFrom (Var S: TStream; Count: Longint);
523
\begin{function}{TStream.Get}
525
Function TStream.Get : PObject;
527
\var{Get} reads an object definition from a stream, and returns
528
a pointer to an instance of this object.
530
On error, \var{TStream.Status} is set, and NIL is returned.
532
\seepl{Put}{TStream.Put}
537
\begin{function}{TStream.StrRead}
539
Function TStream.StrRead: PChar;
541
\var{StrRead} reads a string from the stream, allocates memory
542
for it, and returns a pointer to a null-terminated copy of the string
545
On error, \var{Nil} is returned.
547
\seepl{StrWrite}{TStream.StrWrite}, \seefl{ReadStr}{TStream.ReadStr}
553
\begin{function}{TStream.GetPos}
555
TSTream.GetPos : Longint; Virtual;
557
If the stream's status is \var{stOk}, \var{GetPos} returns the current
558
position in the stream. Otherwise it returns \var{-1}
560
\var{-1} is returned if the status is an error condition.
562
\seepl{Seek}{TStream.Seek}, \seefl{GetSize}{TStream.GetSize}
568
\begin{function}{TStream.GetSize}
570
Function TStream.GetSize: Longint; Virtual;
572
If the stream's status is \var{stOk} then \var{GetSize} returns
573
the size of the stream, otherwise it returns \var{-1}.
575
\var{-1} is returned if the status is an error condition.
577
\seepl{Seek}{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
583
\begin{function}{TStream.ReadStr}
585
Function TStream.ReadStr: PString;
587
\var{ReadStr} reads a string from the stream, copies it to the heap
588
and returns a pointer to this copy. The string is saved as a pascal
589
string, and hence is NOT null terminated.
591
On error (e.g. not enough memory), \var{Nil} is returned.
593
\seefl{StrRead}{TStream.StrRead}
599
\begin{procedure}{TStream.Open}
601
Procedure TStream.Open (OpenMode: Word); Virtual;
603
\var{Open} is an abstract method, that should be overridden by descendent
604
objects. Since opening a stream depends on the stream's type this is not
609
\seepl{Close}{TStream.Close}, \seepl{Reset}{TStream.Reset}
612
For an example, see \seep{TDosStream.Open}.
614
\begin{procedure}{TStream.Close}
616
Procedure TStream.Close; Virtual;
618
\var{Close} is an abstract method, that should be overridden by descendent
619
objects. Since Closing a stream depends on the stream's type this is not
624
\seepl{Open}{TStream.Open}, \seepl{Reset}{TStream.Reset}
627
for an example, see \seep{TDosStream.Open}.
629
\begin{procedure}{TStream.Reset}
631
PROCEDURE TStream.Reset;
633
\var{Reset} sets the stream's status to \var{0}, as well as the ErrorInfo
637
\seepl{Open}{TStream.Open}, \seepl{Close}{TStream.Close}
640
\begin{procedure}{TStream.Flush}
642
Procedure TStream.Flush; Virtual;
644
\var{Flush} is an abstract method that should be overridden by descendent
645
objects. It serves to enable the programmer to tell streams that implement
646
a buffer to clear the buffer.
650
\seepl{Truncate}{TStream.Truncate}
653
for an example, see \seep{TBufStream.Flush}.
655
\begin{procedure}{TStream.Truncate}
657
Procedure TStream.Truncate; Virtual;
659
\var{Truncate} is an abstract procedure that should be overridden by
660
descendent objects. It serves to enable the programmer to truncate the
661
size of the stream to the current file position.
665
\seepl{Seek}{TStream.Seek}
668
For an example, see \seep{TDosStream.Truncate}.
670
\begin{procedure}{TStream.Put}
672
Procedure TStream.Put (P: PObject);
674
\var{Put} writes the object pointed to by \var{P}. \var{P} should be
675
non-nil. The object type must have been registered with \seep{RegisterType}.
677
After the object has been written, it can be read again with \seefl{Get}{TStream.Get}.
679
No check is done whether P is \var{Nil} or not. Passing \var{Nil} will cause
680
a run-time error 216 to be generated. If the object has not been registered,
681
the status of the stream will be set to \var{stPutError}.
683
\seefl{Get}{TStream.Get}
686
For an example, see \seef{TStream.Get};
688
\begin{procedure}{TStream.StrWrite}
690
Procedure TStream.StrWrite (P: PChar);
692
\var{StrWrite} writes the null-terminated string \var{P} to the stream.
693
\var{P} can only be 65355 bytes long.
697
\seepl{WriteStr}{TStream.WriteStr}, \seefl{StrRead}{TStream.StrRead},
698
\seefl{ReadStr}{TStream.ReadStr}
701
For an example, see \seef{TStream.StrRead}.
703
\begin{procedure}{TStream.WriteStr}
705
Procedure TStream.WriteStr (P: PString);
707
\var{StrWrite} writes the pascal string pointed to by \var{P} to the stream.
711
\seepl{StrWrite}{TStream.StrWrite}, \seefl{StrRead}{TStream.StrRead},
712
\seefl{ReadStr}{TStream.ReadStr}
715
For an example, see \seef{TStream.ReadStr}.
717
\begin{procedure}{TStream.Seek}
719
PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
721
Seek sets the position to \var{Pos}. This position is counted
722
from the beginning, and is zero based. (i.e. seeek(0) sets the position
723
pointer on the first byte of the stream)
725
If \var{Pos} is larger than the stream size, \var{Status} is set to
728
\seefl{GetPos}{TStream.GetPos}, \seefl{GetSize}{TStream.GetSize}
732
For an example, see \seep{TDosStream.Seek}.
734
\begin{procedure}{TStream.Error}
736
Procedure TStream.Error (Code, Info: Integer); Virtual;
738
\var{Error} sets the stream's status to \var{Code} and \var{ErrorInfo}
739
to \var{Info}. If the \var{StreamError} procedural variable is set,
740
\var{Error} executes it, passing \var{Self} as an argument.
742
This method should not be called directly from a program. It is intended to
743
be used in descendent objects.
749
\begin{procedure}{TStream.Read}
751
Procedure TStream.Read (Var Buf; Count: Sw\_Word); Virtual;
753
\var{Read} is an abstract method that should be overridden by descendent
756
\var{Read} reads \var{Count} bytes from the stream into \var{Buf}.
757
It updates the position pointer, increasing it's value with \var{Count}.
758
\var{Buf} must be large enough to contain \var{Count} bytes.
760
No checking is done to see if \var{Buf} is large enough to contain
763
\seepl{Write}{TStream.Write}, \seefl{ReadStr}{TStream.ReadStr},
764
\seefl{StrRead}{TStream.StrRead}
770
\begin{procedure}{TStream.Write}
772
Procedure TStream.Write (Var Buf; Count: Sw\_Word); Virtual;
774
\var{Write} is an abstract method that should be overridden by descendent
777
\var{Write} writes \var{Count} bytes to the stream from \var{Buf}.
778
It updates the position pointer, increasing it's value with \var{Count}.
780
No checking is done to see if \var{Buf} actually contains \var{Count} bytes.
782
\seepl{Read}{TStream.Read}, \seepl{WriteStr}{TStream.WriteStr},
783
\seepl{StrWrite}{TStream.StrWrite}
786
For an example, see \seep{TStream.Read}.
788
\begin{procedure}{TStream.CopyFrom}
790
Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
792
\var{CopyFrom} reads Count bytes from stream \var{S} and stores them
793
in the current stream. It uses the \seepl{Read}{TStream.Read} method
794
to read the data, and the \seepl{Write}{TStream.Write} method to
795
write in the current stream.
799
\seepl{Read}{TStream.Read}, \seepl{Write}{TStream.Write}
806
\label{se:TDosStream}
808
\var{TDosStream} is a stream that stores it's contents in a file.
809
it overrides a couple of methods of \var{TSteam} for this.
811
In addition to the fields inherited from \var{TStream} (see \sees{TStream}),
812
there are some extra fields, that describe the file. (mainly the name and
815
No buffering in memory is done when using \var{TDosStream}.
816
All data are written directly to the file. For a stream that buffers
817
in memory, see \sees{TBufStream}.
819
Here is the full declaration of the \var{TDosStream} object:
822
TDosStream = OBJECT (TStream)
823
Handle: THandle; { DOS file handle }
824
FName : AsciiZ; { AsciiZ filename }
825
CONSTRUCTOR Init (FileName: FNameStr; Mode: Word);
826
DESTRUCTOR Done; Virtual;
827
PROCEDURE Close; Virtual;
828
PROCEDURE Truncate; Virtual;
829
PROCEDURE Seek (Pos: LongInt); Virtual;
830
PROCEDURE Open (OpenMode: Word); Virtual;
831
PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
832
PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
834
PDosStream = ^TDosStream;
837
\begin{procedure}{TDosStream.Init}
839
Constructor Init (FileName: FNameStr; Mode: Word);
841
\var{Init} instantiates an instance of \var{TDosStream}. The name of the
842
file that contains (or will contain) the data of the stream is given in
843
\var{FileName}. The \var{Mode} parameter determines whether a new file
844
should be created and what access rights you have on the file.
845
It can be one of the following constants:
847
\item[stCreate] Creates a new file.
848
\item[stOpenRead] Read access only.
849
\item[stOpenWrite] Write access only.
850
\item[stOpen] Read and write access.
853
On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
854
is set to the \dos error code.
856
\seepl{Done}{TDosStream.Done}
859
For an example, see \seep{TDosStream.Truncate}.
861
\begin{procedure}{TDosStream.Done}
863
Destructor TDosStream.Done; Virtual;
865
\var{Done} closes the file if it was open and cleans up the
866
instance of \var{TDosStream}.
870
\seepl{Init}{TDosStream.Init},
871
\seepl{Close}{TDosStream.Close}
874
for an example, see e.g. \seep{TDosStream.Truncate}.
876
\begin{procedure}{TDosStream.Close}
878
Pocedure TDosStream.Close; Virtual;
880
\var{Close} closes the file if it was open, and sets \var{Handle} to -1.
881
Contrary to \seepl{Done}{TDosStream.Done} it does not clean up the instance
886
\seep{TStream.Close}, \seepl{Init}{TDosStream.Init},
887
\seepl{Done}{TDosStream.Done}
890
For an example, see \seep{TDosStream.Open}.
892
\begin{procedure}{TDosStream.Truncate}
894
Procedure TDosStream.Truncate; Virtual;
896
If the status of the stream is \var{stOK}, then \var{Truncate} tries to
897
truncate the stream size to the current file position.
899
If an error occurs, the stream's status is set to \var{stError} and
900
\var{ErrorInfo} is set to the OS error code.
902
\seep{TStream.Truncate}, \seefl{GetSize}{TStream.GetSize}
908
\begin{procedure}{TDosStream.Seek}
910
Procedure TDosStream.Seek (Pos: LongInt); Virtual;
912
If the stream's status is \var{stOK}, then \var{Seek} sets the
913
file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
914
the beginning of the file.
916
In case an error occurs, the stream's status is set to \var{stSeekError},
917
and the OS error code is stored in \var{ErrorInfo}.
919
\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
925
\begin{procedure}{TDosStream.Open}
927
Procedure TDosStream.Open (OpenMode: Word); Virtual;
929
If the stream's status is \var{stOK}, and the stream is closed then
930
\var{Open} re-opens the file stream with mode \var{OpenMode}.
931
This call can be used after a \seepl{Close}{TDosStream.Close} call.
933
If an error occurs when re-opening the file, then \var{Status} is set
934
to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
936
\seep{TStream.Open}, \seepl{Close}{TDosStream.Close}
942
\begin{procedure}{TDosStream.Read}
944
Procedure TDosStream.Read (Var Buf; Count: Sw\_Word); Virtual;
946
If the Stream is open and the stream status is \var{stOK} then
947
\var{Read} will read \var{Count} bytes from the stream and place them
950
In case of an error, \var{Status} is set to \var{StReadError}, and
951
\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
952
made to read beyond the end of the stream.
954
\seep{TStream.Read}, \seepl{Write}{TDosStream.Write}
957
For an example, see \seep{TStream.Read}.
959
\begin{procedure}{TDosStream.Write}
961
Procedure TDosStream.Write (Var Buf; Count: Sw\_Word); Virtual;
963
If the Stream is open and the stream status is \var{stOK} then
964
\var{Write} will write \var{Count} bytes from \var{Buf} and place them
967
In case of an error, \var{Status} is set to \var{StWriteError}, and
968
\var{ErrorInfo} gets the OS specific error.
970
\seep{TStream.Write}, \seepl{Read}{TDosStream.Read}
973
For an example, see \seep{TStream.Read}.
976
\label{se:TBufStream}
978
\var{Bufstream} implements a buffered file stream. That is, all data written
979
to the stream is written to memory first. Only when the buffer is full, or
980
on explicit request, the data is written to disk.
982
Also, when reading from the stream, first the buffer is checked if there is
983
any unread data in it. If so, this is read first. If not the buffer is
984
filled again, and then the data is read from the buffer.
986
The size of the buffer is fixed and is set when constructing the file.
988
This is useful if you need heavy throughput for your stream, because it
989
speeds up operations.
993
TBufStream = OBJECT (TDosStream)
994
LastMode: Byte; { Last buffer mode }
995
BufSize : Sw_Word; { Buffer size }
996
BufPtr : Sw_Word; { Buffer start }
997
BufEnd : Sw_Word; { Buffer end }
998
Buffer : PByteArray; { Buffer allocated }
999
CONSTRUCTOR Init (FileName: FNameStr; Mode, Size: Word);
1000
DESTRUCTOR Done; Virtual;
1001
PROCEDURE Close; Virtual;
1002
PROCEDURE Flush; Virtual;
1003
PROCEDURE Truncate; Virtual;
1004
PROCEDURE Seek (Pos: LongInt); Virtual;
1005
PROCEDURE Open (OpenMode: Word); Virtual;
1006
PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
1007
PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
1009
PBufStream = ^TBufStream;
1012
\begin{procedure}{TBufStream.Init}
1014
Constructor Init (FileName: FNameStr; Mode,Size: Word);
1016
\var{Init} instantiates an instance of \var{TBufStream}. The name of the
1017
file that contains (or will contain) the data of the stream is given in
1018
\var{FileName}. The \var{Mode} parameter determines whether a new file
1019
should be created and what access rights you have on the file.
1020
It can be one of the following constants:
1022
\item[stCreate] Creates a new file.
1023
\item[stOpenRead] Read access only.
1024
\item[stOpenWrite] Write access only.
1025
\item[stOpen] Read and write access.
1027
The \var{Size} parameter determines the size of the buffer that will be
1028
created. It should be different from zero.
1030
On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
1031
is set to the \dos error code.
1033
\seep{TDosStream.Init}, \seepl{Done}{TBufStream.Done}
1036
For an example see \seep{TBufStream.Flush}.
1038
\begin{procedure}{TBufStream.Done}
1040
Destructor TBufStream.Done; Virtual;
1042
\var{Done} flushes and closes the file if it was open and cleans up the
1043
instance of \var{TBufStream}.
1047
\seep{TDosStream.Done}, \seepl{Init}{TBufStream.Init},
1048
\seepl{Close}{TBufStream.Close}
1051
For an example see \seep{TBufStream.Flush}.
1053
\begin{procedure}{TBufStream.Close}
1055
Pocedure TBufStream.Close; Virtual;
1057
\var{Close} flushes and closes the file if it was open, and sets \var{Handle} to -1.
1058
Contrary to \seepl{Done}{TBufStream.Done} it does not clean up the instance
1063
\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
1064
\seepl{Done}{TBufStream.Done}
1067
For an example see \seep{TBufStream.Flush}.
1069
\begin{procedure}{TBufStream.Flush}
1071
Pocedure TBufStream.Flush; Virtual;
1073
When the stream is in write mode, the contents of the buffer are written to
1074
disk, and the buffer position is set to zero.
1076
When the stream is in read mode, the buffer position is set to zero.
1078
Write errors may occur if the file was in write mode.
1079
see \seepl{Write}{TBufStream.Write} for more info on the errors.
1081
\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
1082
\seepl{Done}{TBufStream.Done}
1088
\begin{procedure}{TBufStream.Truncate}
1090
Procedure TBufStream.Truncate; Virtual;
1092
If the status of the stream is \var{stOK}, then \var{Truncate} tries to
1093
flush the buffer, and then truncates the stream size to the current
1096
Errors can be those of \seepl{Flush}{TBufStream.Flush} or
1097
\seep{TDosStream.Truncate}.
1099
\seep{TStream.Truncate}, \seep{TDosStream.Truncate},
1100
\seefl{GetSize}{TStream.GetSize}
1103
For an example, see \seep{TDosStream.Truncate}.
1105
\begin{procedure}{TBufStream.Seek}
1107
Procedure TBufStream.Seek (Pos: LongInt); Virtual;
1109
If the stream's status is \var{stOK}, then \var{Seek} sets the
1110
file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
1111
the beginning of the file.
1113
In case an error occurs, the stream's status is set to \var{stSeekError},
1114
and the OS error code is stored in \var{ErrorInfo}.
1116
\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
1119
For an example, see \seep{TStream.Seek};
1121
\begin{procedure}{TBufStream.Open}
1123
Procedure TBufStream.Open (OpenMode: Word); Virtual;
1125
If the stream's status is \var{stOK}, and the stream is closed then
1126
\var{Open} re-opens the file stream with mode \var{OpenMode}.
1127
This call can be used after a \seepl{Close}{TBufStream.Close} call.
1129
If an error occurs when re-opening the file, then \var{Status} is set
1130
to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
1132
\seep{TStream.Open}, \seepl{Close}{TBufStream.Close}
1135
For an example, see \seep{TDosStream.Open}.
1137
\begin{procedure}{TBufStream.Read}
1139
Procedure TBufStream.Read (Var Buf; Count: Sw\_Word); Virtual;
1141
If the Stream is open and the stream status is \var{stOK} then
1142
\var{Read} will read \var{Count} bytes from the stream and place them
1145
\var{Read} will first try to read the data from the stream's internal
1146
buffer. If insufficient data is available, the buffer will be filled before
1147
contiunuing to read. This process is repeated until all needed data
1151
In case of an error, \var{Status} is set to \var{StReadError}, and
1152
\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
1153
made to read beyond the end of the stream.
1155
\seep{TStream.Read}, \seepl{Write}{TBufStream.Write}
1158
For an example, see \seep{TStream.Read}.
1160
\begin{procedure}{TBufStream.Write}
1162
Procedure TBufStream.Write (Var Buf; Count: Sw\_Word); Virtual;
1164
If the Stream is open and the stream status is \var{stOK} then
1165
\var{Write} will write \var{Count} bytes from \var{Buf} and place them
1168
\var{Write} will first try to write the data to the stream's internal
1169
buffer. When the internal buffer is full, then the contents will be written
1170
to disk. This process is repeated until all data has been written.
1172
In case of an error, \var{Status} is set to \var{StWriteError}, and
1173
\var{ErrorInfo} gets the OS specific error.
1175
\seep{TStream.Write}, \seepl{Read}{TBufStream.Read}
1178
For an example, see \seep{TStream.Read}.
1180
\section{TMemoryStream}
1181
\label{se:TMemoryStream}
1183
The \var{TMemoryStream} object implements a stream that stores it's data
1184
in memory. The data is stored on the heap, with the possibility to specify
1185
the maximum amout of data, and the the size of the memory blocks being used.
1189
TMemoryStream = OBJECT (TStream)
1190
BlkCount: Sw_Word; { Number of segments }
1191
BlkSize : Word; { Memory block size }
1192
MemSize : LongInt; { Memory alloc size }
1193
BlkList : PPointerArray; { Memory block list }
1194
CONSTRUCTOR Init (ALimit: Longint; ABlockSize: Word);
1195
DESTRUCTOR Done; Virtual;
1196
PROCEDURE Truncate; Virtual;
1197
PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
1198
PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
1200
PMemoryStream = ^TMemoryStream;
1203
\begin{procedure}{TMemoryStream.Init}
1205
Constructor TMemoryStream.Init (ALimit: Longint; ABlockSize: Word);
1207
\var{Init} instantiates a new \var{TMemoryStream} object. The
1208
memorystreamobject will initially allocate at least \var{ALimit} bytes memory,
1209
divided into memory blocks of size \var{ABlockSize}.
1210
The number of blocks needed to get to \var{ALimit} bytes is rounded up.
1212
By default, the number of blocks is 1, and the size of a block is 8192. This
1213
is selected if you specify 0 as the blocksize.
1215
If the stream cannot allocate the initial memory needed for the memory blocks, then
1216
the stream's status is set to \var{stInitError}.
1218
\seepl{Done}{TMemoryStream.Done}
1221
For an example, see e.g \seep{TStream.CopyFrom}.
1223
\begin{procedure}{TMemoryStream.Done}
1225
Destructor TMemoryStream.Done; Virtual;
1227
\var{Done} releases the memory blocks used by the stream, and then cleans up
1228
the memory used by the stream object itself.
1232
\seepl{Init}{TMemoryStream.Init}
1235
For an example, see e.g \seep{TStream.CopyFrom}.
1237
\begin{procedure}{TMemoryStream.Truncate}
1239
Procedure TMemoryStream.Truncate; Virtual;
1241
\var{Truncate} sets the size of the memory stream equal to the current
1242
position. It de-allocates any memory-blocks that are no longer needed, so
1243
that the new size of the stream is the current position in the stream,
1244
rounded up to the first multiple of the stream blocksize.
1246
If an error occurs during memory de-allocation, the stream's status is set
1249
\seep{TStream.Truncate}
1255
\begin{procedure}{TMemoryStream.Read}
1257
Procedure Read (Var Buf; Count: Sw\_Word); Virtual;
1259
\var{Read} reads \var{Count} bytes from the stream to \var{Buf}. It updates
1260
the position of the stream.
1262
If there is not enough data available, no data is read, and the stream's
1263
status is set to \var{stReadError}.
1265
\var{TStream.Read}, \seepl{Write}{TMemoryStream.Write}
1268
For an example, see \seep{TStream.Read}.
1270
\begin{procedure}{TMemoryStream.Write}
1272
Procedure Write (Var Buf; Count: Sw\_Word); Virtual;
1274
\var{Write} copies \var{Count} bytes from \var{Buf} to the stream. It
1275
updates the position of the stream.
1277
If not enough memory is available to hold the extra \var{Count} bytes,
1278
then the stream will try to expand, by allocating as much blocks with
1279
size \var{BlkSize} (as specified in the constuctor call
1280
\seepl{Init}{TMemoryStream.Init}) as needed.
1282
If the stream cannot allocate more memory, then the status is set to
1285
\seep{TStream.Write}, \seepl{Read}{TMemoryStream.Read}
1288
For an example, see \seep{TStream.Read}.
1290
\section{TCollection}
1291
\label{se:TCollection}
1293
The \var{TCollection} object manages a collection of pointers or objects.
1294
It also provides a series of methods to manipulate these pointers or
1297
Whether or not objects are used depends on the kind of calls you use.
1298
ALl kinds come in 2 flavors, one for objects, one for pointers.
1300
This is the full declaration of the \var{TCollection} object:
1304
TItemList = Array [0..MaxCollectionSize - 1] Of Pointer;
1305
PItemList = ^TItemList;
1307
TCollection = OBJECT (TObject)
1308
Items: PItemList; { Item list pointer }
1309
Count: Sw_Integer; { Item count }
1310
Limit: Sw_Integer; { Item limit count }
1311
Delta: Sw_Integer; { Inc delta size }
1312
Constructor Init (ALimit, ADelta: Sw_Integer);
1313
Constructor Load (Var S: TStream);
1314
Destructor Done; Virtual;
1315
Function At (Index: Sw_Integer): Pointer;
1316
Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
1317
Function GetItem (Var S: TStream): Pointer; Virtual;
1318
Function LastThat (Test: Pointer): Pointer;
1319
Function FirstThat (Test: Pointer): Pointer;
1322
Procedure DeleteAll;
1323
Procedure Free (Item: Pointer);
1324
Procedure Insert (Item: Pointer); Virtual;
1325
Procedure Delete (Item: Pointer);
1326
Procedure AtFree (Index: Sw_Integer);
1327
Procedure FreeItem (Item: Pointer); Virtual;
1328
Procedure AtDelete (Index: Sw_Integer);
1329
Procedure ForEach (Action: Pointer);
1330
Procedure SetLimit (ALimit: Sw_Integer); Virtual;
1331
Procedure Error (Code, Info: Integer); Virtual;
1332
Procedure AtPut (Index: Sw_Integer; Item: Pointer);
1333
Procedure AtInsert (Index: Sw_Integer; Item: Pointer);
1334
Procedure Store (Var S: TStream);
1335
Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
1337
PCollection = ^TCollection;
1341
\begin{procedure}{TCollection.Init}
1343
Constructor TCollection.Init (ALimit, ADelta: Sw\_Integer);
1345
\var{Init} initializes a new instance of a collection. It sets the (initial) maximum number
1346
of items in the collection to \var{ALimit}. \var{ADelta} is the increase
1347
size : The number of memory places that will be allocatiod in case \var{ALimit} is reached,
1348
and another element is added to the collection.
1352
\seepl{Load}{TCollection.Load}, \seepl{Done}{TCollection.Done}
1355
For an example, see \seep{TCollection.ForEach}.
1357
\begin{procedure}{TCollection.Load}
1359
Constructor TCollection.Load (Var S: TStream);
1361
\var{Load} initializes a new instance of a collection. It reads from stream
1362
\var{S} the item count, the item limit count, and the increase size. After
1363
that, it reads the specified number of items from the stream.
1365
% Do not call this method if you intend to use only pointers in your collection.
1367
Errors returned can be those of \seefl{GetItem}{TCollection.GetItem}.
1369
\seepl{Init}{TCollection.Init}, \seefl{GetItem}{TCollection.GetItem},
1370
\seepl{Done}{TCollection.Done}.
1376
\begin{procedure}{TCollection.Done}
1378
Destructor TCollection.Done; Virtual;
1380
\var{Done} frees all objects in the collection, and then releases all memory
1381
occupied by the instance.
1383
% Do not call this method if you intend to use only pointers in your collection.
1387
\seepl{Init}{TCollection.Init}, \seepl{FreeAll}{TCollection.FreeAll}
1390
For an example, see \seep{TCollection.ForEach}.
1392
\begin{function}{TCollection.At}
1394
Function TCollection.At (Index: Sw\_Integer): Pointer;
1396
\var{At} returns the item at position \var{Index}.
1398
If \var{Index} is less than zero or larger than the number of items
1399
in the collection, seepl{Error}{TCollection.Error} is called with
1400
\var{coIndexError} and \var{Index} as arguments, resulting in a run-time
1403
\seepl{Insert}{TCollection.Insert}
1409
\begin{function}{TCollection.IndexOf}
1411
Function TCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
1413
\var{IndexOf} returns the index of \var{Item} in the collection.
1414
If \var{Item} isn't present in the collection, -1 is returned.
1422
\begin{function}{TCollection.GetItem}
1424
Function TCollection.GetItem (Var S: TStream): Pointer; Virtual;
1426
\var{GetItem} reads a single item off the stream \var{S}, and
1427
returns a pointer to this item. This method is used internally by the Load
1428
method, and should not be used directly.
1430
Possible errors are the ones from \seef{TStream.Get}.
1432
\seef{TStream.Get}, seepl{Store}{TCollection.Store}
1435
\begin{function}{TCollection.LastThat}
1437
Function TCollection.LastThat (Test: Pointer): Pointer;
1439
This function returns the last item in the collection for which \var{Test}
1440
returns a non-nil result. \var{Test} is a function that accepts 1 argument:
1441
a pointer to an object, and that returns a pointer as a result.
1445
\seefl{FirstThat}{TCollection.FirstThat}
1451
\begin{function}{TCollection.FirstThat}
1453
Function TCollection.FirstThat (Test: Pointer): Pointer;
1455
This function returns the first item in the collection for which \var{Test}
1456
returns a non-nil result. \var{Test} is a function that accepts 1 argument:
1457
a pointer to an object, and that returns a pointer as a result.
1461
\seefl{LastThat}{TCollection.LastThat}
1467
\begin{procedure}{TCollection.Pack}
1469
Procedure TCollection.Pack;
1471
\var{Pack} removes all \var{Nil} pointers from the collection, and adjusts
1472
\var{Count} to reflect this change. No memory is freed as a result of this
1473
call. In order to free any memory, you can call \var{SetLimit} with an
1474
argument of \var{Count} after a call to \var{Pack}.
1478
\seepl{SetLimit}{TCollection.SetLimit}
1484
\begin{procedure}{TCollection.FreeAll}
1486
Procedure TCollection.FreeAll;
1488
\var{FreeAll} calls the destructor of each object in the collection.
1489
It doesn't release any memory occumpied by the collection itself, but it
1490
does set \var{Count} to zero.
1493
\seepl{DeleteAll}{TCollection.DeleteAll}, \seepl{FreeItem}{TCollection.FreeItem}
1499
\begin{procedure}{TCollection.DeleteAll}
1501
Procedure TCollection.DeleteAll;
1503
\var{DeleteAll} deletes all elements from the collection. It just sets
1504
the \var{Count} variable to zero. Contrary to
1505
\seepl{FreeAll}{TCollection.FreeAll}, \var{DeletAll} doesn't call the
1506
destructor of the objects.
1510
\seepl{FreeAll}{TCollection.FreeAll}, \seepl{Delete}{TCollection.Delete}
1516
\begin{procedure}{TCollection.Free}
1518
Procedure TCollection.Free (Item: Pointer);
1520
\var{Free} Deletes \var{Item} from the collection, and calls the destructor
1521
\var{Done} of the object.
1523
If the \var{Item} is not in the collection, \var{Error} will be called with
1526
\seepl{FreeItem}{TCollection.FreeItem},
1532
\begin{procedure}{TCollection.Insert}
1534
Procedure TCollection.Insert (Item: Pointer); Virtual;
1536
\var{Insert} inserts \var{Item} in the collection. \var{TCollection}
1537
inserts this item at the end, but descendent objects may insert it at
1542
\seepl{AtInsert}{TCollection.AtInsert}, \seepl{AtPut}{TCollection.AtPut},
1546
\begin{procedure}{TCollection.Delete}
1548
Procedure TCollection.Delete (Item: Pointer);
1550
\var{Delete} deletes \var{Item} from the collection. It doesn't call the
1551
item's destructor, though. For this the \seepl{Free}{TCollection.Free}
1554
If the \var{Item} is not in the collection, \var{Error} will be called with
1557
\seepl{AtDelete}{TCollection.AtDelete},\seepl{Free}{TCollection.Free}
1563
\begin{procedure}{TCollection.AtFree}
1565
Procedure TCollection.AtFree (Index: Sw\_Integer);
1567
\var{AtFree} deletes the item at position \var{Index} in the collection,
1568
and calls the item's destructor if it is not \var{Nil}.
1570
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
1571
with \var{CoIndexError}.
1573
\seepl{Free}{TCollection.Free}, \seepl{AtDelete}{TCollection.AtDelete}
1579
\begin{procedure}{TCollection.FreeItem}
1581
Procedure TCollection.FreeItem (Item: Pointer); Virtual;
1583
\var{FreeItem} calls the destructor of \var{Item} if it is not nil.
1585
This function is used internally by the TCollection object, and should not be
1590
\seepl{Free}{TCollection.AtFree}, seepl{AtFree}{TCollection.AtFree}
1594
\begin{procedure}{TCollection.AtDelete}
1596
Procedure TCollection.AtDelete (Index: Sw\_Integer);
1598
\var{AtDelete} deletes the pointer at position \var{Index} in the
1599
collection. It doesn't call the object's destructor.
1601
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
1602
with \var{CoIndexError}.
1604
\seepl{Delete}{TCollection.Delete}
1611
\begin{procedure}{TCollection.ForEach}
1613
Procedure TCollection.ForEach (Action: Pointer);
1615
\var{ForEach} calls \var{Action} for each element in the collection,
1616
and passes the element as an argument to \var{Action}.
1618
\var{Action} is a procedural type variable that accepts a pointer as an
1623
\seefl{FirstThat}{TCollection.FirstThat}, \seefl{LastThat}{TCollection.LastThat}
1629
\begin{procedure}{TCollection.SetLimit}
1631
Procedure TCollection.SetLimit (ALimit: Sw\_Integer); Virtual;
1633
\var{SetLimit} sets the maximum number of elements in the collection.
1634
\var{ALimit} must not be less than \var{Count}, and should not be larger
1635
than \var{MaxCollectionSize}
1639
\seepl{Init}{TCollection.Init}
1642
For an example, see \seepl{Pack}{TCollection.Pack}.
1644
\begin{procedure}{TCollection.Error}
1646
Procedure TCollection.Error (Code, Info: Integer); Virtual;
1648
\var{Error} is called by the various \var{TCollection} methods
1649
in case of an error condition. The default behaviour is to make
1650
a call to \var{RunError} with an error of \var{212-Code}.
1652
This method can be overridden by descendent objects to implement
1653
a different error-handling.
1659
\begin{procedure}{TCollection.AtPut}
1661
Procedure TCollection.AtPut (Index: Sw\_Integer; Item: Pointer);
1663
\var{AtPut} sets the element at position \var{Index} in the collection
1664
to \var{Item}. Any previous value is overwritten.
1666
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
1667
with \var{CoIndexError}.
1671
For an example, see \seepl{Pack}{TCollection.Pack}.
1673
\begin{procedure}{TCollection.AtInsert}
1675
Procedure TCollection.AtInsert (Index: Sw\_Integer; Item: Pointer);
1677
\var{AtInsert} inserts \var{Item} in the collection at position \var{Index},
1678
shifting all elements by one position. In case the current limit is reached,
1679
the collection will try to expand with a call to \var{SetLimit}
1681
If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
1682
with \var{CoIndexError}. If the collection fails to expand, then
1683
\var{coOverFlow} is passd to \var{Error}.
1685
\seepl{Insert}{TCollection.Insert}
1691
\begin{procedure}{TCollection.Store}
1693
Procedure TCollection.Store (Var S: TStream);
1695
\var{Store} writes the collection to the stream \var{S}. It does
1696
this by writeing the current \var{Count}, \var{Limit} and \var{Delta}
1697
to the stream, and then writing each item to the stream.
1699
The contents of the stream are then suitable for instantiating another
1700
collection with \seepl{Load}{TCollection.Load}.
1702
Errors returned are those by \seep{TStream.Put}.
1704
\seepl{Load}{TCollection.Load}, \seepl{PutItem}{TCollection.PutItem}
1707
For an example, see seepl{Load}{TCollection.Load}.
1709
\begin{procedure}{TCollection.PutItem}
1711
Procedure TCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
1713
\var{PutItem} writes \var{Item} to stream \var{S}. This method is used
1714
internaly by the \var{TCollection} object, and should not be called
1717
Errors are those returned by \seep{TStream.Put}.
1719
\seepl{Store}{TCollection.Store}, \seefl{GetItem}{TCollection.GetItem}.
1722
\section{TSortedCollection}
1723
\label{se:TSortedCollection}
1725
\var{TSortedCollection} is an abstract class, implementing a sorted
1726
collection. You should never use an instance of \var{TSortedCollection}
1727
directly, instead you should declare a descendent type, and override the
1728
\seefl{Compare}{TSortedCollection.Compare} method.
1730
Because the collection is ordered, \var{TSortedCollection} overrides some
1731
\var{TCollection} methods, to provide faster routines for lookup.
1733
The \seefl{Compare}{TSortedCollection.Compare} method decides how elements
1734
in the collection should be ordered. Since \var{TCollection} has no way
1735
of knowing how to order pointers, you must override the compare method.
1737
Additionally, \var{TCollection} provides a means to filter out duplicates.
1738
if you set \var{Duplicates} to \var{False} (the default) then duplicates
1739
will not be allowed.
1741
Here is the complete declaration of \var{TSortedCollection}
1745
TSortedCollection = OBJECT (TCollection)
1746
Duplicates: Boolean; { Duplicates flag }
1747
Constructor Init (ALimit, ADelta: Sw_Integer);
1748
Constructor Load (Var S: TStream);
1749
Function KeyOf (Item: Pointer): Pointer; Virtual;
1750
Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
1751
Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
1752
Function Search (Key: Pointer; Var Index: Sw_Integer): Boolean;Virtual;
1753
Procedure Insert (Item: Pointer); Virtual;
1754
Procedure Store (Var S: TStream);
1756
PSortedCollection = ^TSortedCollection;
1759
In the subsequent examples, the following descendent of
1760
\var{TSortedCollection} is used:
1762
\FPCexample{mysortc}
1765
\begin{procedure}{TSortedCollection.Init}
1767
Constructor TSortedCollection.Init (ALimit, ADelta: Sw\_Integer);
1769
\var{Init} calls the inherited constuctor (see \seep{TCollection.Init}) and
1770
sets the \var{Duplicates} flag to false.
1772
You should not call this method directly, since \var{TSortedCollection} is a
1773
abstract class. Instead, the descendent classes should call it via the
1774
\var{inherited} keyword.
1778
\seepl{Load}{TSortedCollection.Load}, \seepl{Done}{TCollection.Done}
1783
\begin{procedure}{TSortedCollection.Load}
1785
Constructor Load (Var S: TStream);
1787
\var{Load} calls the inherited constuctor (see \seep{TCollection.Load}) and
1788
reads the \var{Duplicates} flag from the stream..
1790
You should not call this method directly, since \var{TSortedCollection} is a
1791
abstract class. Instead, the descendent classes should call it via the
1792
\var{inherited} keyword.
1796
\seepl{Init}{TSortedCollection.Init}, \seepl{Done}{TCollection.Done}
1799
For an example, see \seep{TCollection.Load}.
1801
\begin{function}{TSortedCollection.KeyOf}
1803
Function TSortedCollection.KeyOf (Item: Pointer): Pointer; Virtual;
1805
\var{KeyOf} returns the key associated with \var{Item}.
1806
\var{TSortedCollection} returns the item itself as the key, descendent
1807
objects can override this method to calculate a (unique) key based on the
1808
item passed (such as hash values).
1810
\var{Keys} are used to sort the objects, they are used to search and sort
1811
the items in the collection. If descendent types override this method then
1812
it allows possibly for faster search/sort methods based on keys rather than
1813
on the objects themselves.
1817
\seefl{IndexOf}{TSortedCollection.IndexOf},
1818
\seefl{Compare}{TSortedCollection.Compare}.
1821
\begin{function}{TSortedCollection.IndexOf}
1823
Function TSortedCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
1825
\var{IndexOf} returns the index of \var{Item} in the collection. It searches
1826
for the object based on it's key. If duplicates are allowed, then it returns
1827
the index of last object that matches \var{Item}.
1829
In case \var{Item} is not found in the collection, -1 is returned.
1833
\seefl{Search}{TSortedCollection.Search},
1834
\seefl{Compare}{TSortedCollection.Compare}.
1837
For an example, see \seef{TCollection.IndexOf}
1839
\begin{function}{TSortedCollection.Compare}
1841
Function TSortedCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
1843
\var{Compare} is an abstract method that should be overridden by descendent
1844
objects in order to compare two items in the collection. This method is used
1845
in the \seefl{Search}{TSortedCollection.Search} method and in the
1846
\seepl{Insert}{TSortedCollection.Insert} method to determine the ordering of
1849
The function should compare the two keys of items and return the following
1852
\item [Result < 0] If \var{Key1} is logically before \var{Key2}
1854
\item [Result = 0] If \var{Key1} and \var{Key2} are equal. (\var{Key1=Key2})
1855
\item [Result > 0] If \var{Key1} is logically after \var{Key2}
1859
An 'abstract run-time error' will be generated if you call
1860
\var{TSortedCollection.Compare} directly.
1862
\seefl{IndexOf}{TSortedCollection.IndexOf},
1863
\seefl{Search}{TSortedCollection.Search}
1866
\FPCexample{mysortc}
1869
\begin{function}{TSortedCollection.Search}
1871
Function TSortedCollection.Search (Key: Pointer; Var Index: Sw\_Integer): Boolean;Virtual;
1873
\var{Search} looks for the item with key \var{Key} and returns the position
1874
of the item (if present) in the collection in \var{Index}.
1876
Instead of a linear search as \var{TCollection} does, \var{TSortedCollection}
1877
uses a binary search based on the keys of the objects. It uses the
1878
\seefl{Compare}{TSortedCollection.Compare} function to implement this
1881
If the item is found, \var{Search} returns \var{True}, otherwise \var{False}
1886
\seefl{IndexOf}{TCollection.IndexOf}.
1892
\begin{procedure}{TSortedCollection.Insert}
1894
Procedure TSortedCollection.Insert (Item: Pointer); Virtual;
1896
\var{Insert} inserts an item in the collection at the correct position, such
1897
that the collection is ordered at all times. You should never use
1898
\seepl{Atinsert}{TCollection.AtInsert}, since then the collection ordering
1901
If \var{Item} is already present in the collection, and \var{Duplicates} is
1902
\var{False}, the item will not be inserted.
1906
\seepl{AtInsert}{TCollection.AtInsert}
1912
\begin{procedure}{TSortedCollection.Store}
1914
Procedure TSortedCollection.Store (Var S: TStream);
1916
\var{Store} writes the collection to the stream \var{S}. It does this by
1917
calling the inherited \seep{TCollection.Store}, and then writing the
1918
\var{Duplicates} flag to the stream.
1920
After a \var{Store}, the collection can be loaded from the stream with the
1921
constructor \seepl{Load}{TSortedCollection.Load}
1923
Errors can be those of \seep{TStream.Put}.
1925
\seepl{Load}{TSortedCollection.Load}
1928
For an example, see \seep{TCollection.Load}.
1930
\section{TStringCollection}
1931
\label{se:TStringCollection}
1933
The \var{TStringCollection} object manages a sorted collection of pascal
1935
To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
1936
method of \var{TSortedCollection}, and it introduces methods to read/write
1937
strings from a stream.
1939
Here is the full declaration of the \var{TStringCollection} object:
1942
TStringCollection = OBJECT (TSortedCollection)
1943
Function GetItem (Var S: TStream): Pointer; Virtual;
1944
Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
1945
Procedure FreeItem (Item: Pointer); Virtual;
1946
Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
1948
PStringCollection = ^TStringCollection;
1951
\begin{function}{TStringCollection.GetItem}
1953
Function TStringCollection.GetItem (Var S: TStream): Pointer; Virtual;
1955
\var{GetItem} reads a string from the stream \var{S} and returns a pointer
1956
to it. It doesn't insert the string in the collection.
1958
This method is primarily introduced to be able to load and store the
1959
collection from and to a stream.
1961
The errors returned are those of \seef{TStream.ReadStr}.
1963
\seepl{PutItem}{TStringCollection.PutItem}
1966
\begin{function}{TStringCollection.Compare}
1968
Function TStringCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
1970
\var{TStringCollection} overrides the \var{Compare} function so it compares
1971
the two keys as if they were pointers to strings. The compare is done case
1972
sensitive. It returns the following results:
1974
\item[-1] if the first string is alphabetically earlier than the second
1976
\item[0] if the two strings are equal.
1977
\item[1] if the first string is alphabetically later than the second string.
1982
\seef{TSortedCollection.Compare}
1988
\begin{procedure}{TStringCollection.FreeItem}
1990
Procedure TStringCollection.FreeItem (Item: Pointer); Virtual;
1992
\var{TStringCollection} overrides \var{FreeItem} so that the string pointed
1993
to by \var{Item} is disposed from memory.
1997
\seep{TCollection.FreeItem}
2000
\begin{procedure}{TStringCollection.PutItem}
2002
Procedure TStringCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
2004
\var{PutItem} writes the string pointed to by \var{Item} to the stream
2007
This method is primarily used in the \var{Load} and \var{Store} methods,
2008
and should not be used directly.
2010
Errors are those of \seep{TStream.WriteStr}.
2012
\seefl{GetItem}{TStringCollection.GetItem}
2016
\section{TStrCollection}
2017
\label{se:TStrCollection}
2019
The \var{TStrCollection} object manages a sorted collection
2020
of null-terminated strings (pchar strings).
2021
To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
2022
method of \var{TSortedCollection}, and it introduces methods to read/write
2023
strings from a stream.
2025
Here is the full declaration of the \var{TStrCollection} object:
2029
TStrCollection = OBJECT (TSortedCollection)
2030
Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
2031
Function GetItem (Var S: TStream): Pointer; Virtual;
2032
Procedure FreeItem (Item: Pointer); Virtual;
2033
Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
2035
PStrCollection = ^TStrCollection;
2038
\begin{function}{TStrCollection.GetItem}
2040
Function TStrCollection.GetItem (Var S: TStream): Pointer; Virtual;
2042
\var{GetItem} reads a null-terminated string from the stream \var{S}
2043
and returns a pointer to it. It doesn't insert the string in the
2046
This method is primarily introduced to be able to load and store the
2047
collection from and to a stream.
2049
The errors returned are those of \seef{TStream.StrRead}.
2051
\seepl{PutItem}{TStrCollection.PutItem}
2054
\begin{function}{TStrCollection.Compare}
2056
Function TStrCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
2058
\var{TStrCollection} overrides the \var{Compare} function so it compares
2059
the two keys as if they were pointers to strings. The compare is done case
2060
sensitive. It returns
2062
\item[-1] if the first string is alphabetically earlier than the second
2064
\item[0] if the two strings are equal.
2065
\item[1] if the first string is alphabetically later than the second string.
2070
\seef{TSortedCollection.Compare}
2076
\begin{procedure}{TStrCollection.FreeItem}
2078
Procedure TStrCollection.FreeItem (Item: Pointer); Virtual;
2080
\var{TStrCollection} overrides \var{FreeItem} so that the string pointed
2081
to by \var{Item} is disposed from memory.
2085
\seep{TCollection.FreeItem}
2088
\begin{procedure}{TStrCollection.PutItem}
2090
Procedure TStrCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
2092
\var{PutItem} writes the string pointed to by \var{Item} to the stream
2095
This method is primarily used in the \var{Load} and \var{Store} methods,
2096
and should not be used directly.
2098
Errors are those of \seep{TStream.StrWrite}.
2100
\seefl{GetItem}{TStrCollection.GetItem}
2103
\section{TUnSortedStrCollection}
2104
\label{se:TUnSortedStrCollection}
2106
The \var{TUnSortedStrCollection} object manages an unsorted list of strings.
2107
To this end, it overrides the \seep{TStringCollection.Insert} method to add
2108
strings at the end of the collection, rather than in the alphabetically
2111
Take care, the \seefl{Search}{TSortedCollection.Search} and
2112
\seefl{IndexOf}{TCollection.IndexOf} methods will not work on an unsorted
2115
Here is the full declaration of the {TUnsortedStrCollection} object:
2118
TUnSortedStrCollection = OBJECT (TStringCollection)
2119
Procedure Insert (Item: Pointer); Virtual;
2121
PUnSortedStrCollection = ^TUnSortedStrCollection;
2124
\begin{procedure}{TUnSortedStrCollection.Insert}
2126
Procedure TUnSortedStrCollection.Insert (Item: Pointer); Virtual;
2128
\var{Insert} inserts a string at the end of the collection, instead
2129
of on it's alphabetical place, resulting in an unsorted collection of
2138
\section{TResourceCollection}
2139
\label{se:TResourceCollection}
2141
A \var{TResourceCollection} manages a collection of resource names.
2142
It stores the position and the size of a resource, as well as the name of
2143
the resource. It stores these items in records that look like this:
2146
TResourceItem = packed RECORD
2151
PResourceItem = ^TResourceItem;
2154
It overrides some methods of \var{TStringCollection} in order to accomplish
2157
Remark that the \var{TResourceCollection} manages the names of the
2158
resources and their assiciated positions and sizes, it doesn't manage
2159
the resources themselves.
2161
Here is the full declaration of the \var{TResourceCollection} object:
2164
TResourceCollection = OBJECT (TStringCollection)
2165
Function KeyOf (Item: Pointer): Pointer; Virtual;
2166
Function GetItem (Var S: TStream): Pointer; Virtual;
2167
Procedure FreeItem (Item: Pointer); Virtual;
2168
Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
2170
PResourceCollection = ^TResourceCollection;
2173
\begin{function}{TResourceCollection.KeyOf}
2175
Function TResourceCollection.KeyOf (Item: Pointer): Pointer; Virtual;
2177
\var{KeyOf} returns the key of an item in the collection. For resources, the
2178
key is a pointer to the string with the resource name.
2182
\seef{TStringCollection.Compare}
2185
\begin{function}{TResourceCollection.GetItem}
2187
Function TResourceCollection.GetItem (Var S: TStream): Pointer; Virtual;
2189
\var{GetItem} reads a resource item from the stream \var{S}. It reads the
2190
position, size and name from the stream, in that order. It DOES NOT read the
2191
resource itself from the stream.
2193
The resulting item is not inserted in the collection. This call is manly for
2194
internal use by the \seep{TCollection.Load} method.
2196
Errors returned are those by \seep{TStream.Read}
2198
\seep{TCollection.Load}, \seep{TStream.Read}
2201
\begin{procedure}{TResourceCollection.FreeItem}
2203
Procedure TResourceCollection.FreeItem (Item: Pointer); Virtual;
2205
\var{FreeItem} releases the memory occupied by \var{Item}. It de-allocates
2206
the name, and then the resourceitem record.
2208
It does NOT remove the item from the collection.
2212
\seep{TCollection.FreeItem}
2215
\begin{procedure}{TResourceCollection.PutItem}
2217
Procedure TResourceCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
2219
\var{PutItem} writes \var{Item} to the stream \var{S}. It does this by
2220
writing the position and size and name of the resource item to the stream.
2222
This method is used primarily by the \seepl{Store}{TCollection.Store}
2225
Errors returned are those by \seep{TStream.Write}.
2227
\seepl{Store}{TCollection.Store}
2231
\section{TResourceFile}
2232
\label{se:TResourceFile}
2236
TResourceFile = OBJECT (TObject)
2237
Stream : PStream; { File as a stream }
2238
Modified: Boolean; { Modified flag }
2239
Constructor Init (AStream: PStream);
2240
Destructor Done; Virtual;
2241
Function Count: Sw_Integer;
2242
Function KeyAt (I: Sw_Integer): String;
2243
Function Get (Key: String): PObject;
2244
Function SwitchTo (AStream: PStream; Pack: Boolean): PStream;
2246
Procedure Delete (Key: String);
2247
Procedure Put (Item: PObject; Key: String);
2249
PResourceFile = ^TResourceFile;
2252
\subsection{TResourceFile Fields}
2254
\var{TResourceFile} has the following fields:
2256
\item[Stream] contains the (file) stream that has the executable image and
2257
the resources. It can be initialized by the \seepl{Init}{TResourceFile.Init}
2259
\item[Modified] is set to \var{True} if one of the resources has been changed.
2260
It is set by the \seepl{SwitchTo}{TResourceFile.Init},
2261
\seepl{Delete}{TResourceFile.Delete} and \seepl{Put}{TResourceFile.Put}
2262
methods. Calling \seepl{Flush}{TResourceFile.Flush} will clear the
2263
\var{Modified} flag.
2266
\begin{procedure}{TResourceFile.Init}
2268
Constructor TResourceFile.Init (AStream: PStream);
2270
\var{Init} instantiates a new instance of a \var{TResourceFile} object.
2271
If \var{AStream} is not nil then it is considered as a stream describing an
2272
executable image on disk.
2274
\var{Init} will try to position the stream on the start of the resources section,
2275
and read all resources from the stream.
2279
\seepl{Done}{TResourceFile.Done}
2282
\begin{procedure}{TResourceFile.Done}
2284
Destructor TResourceFile.Done; Virtual;
2286
\var{Done} cleans up the instance of the \var{TResourceFile} Object.
2287
If \var{Stream} was specified at initialization, then \var{Stream} is
2292
\seepl{Init}{TResourceFile.Init}
2295
\begin{function}{TResourceFile.Count}
2297
Function TResourceFile.Count: Sw\_Integer;
2299
\var{Count} returns the number of resources. If no resources were
2300
read, zero is returned.
2304
\seepl{Init}{TResourceFile.Init}
2307
\begin{function}{TResourceFile.KeyAt}
2309
Function TResourceFile.KeyAt (I: Sw\_Integer): String;
2311
\var{KeyAt} returns the key (the name) of the \var{I}-th resource.
2313
In case \var{I} is invalid, \var{TCollection.Error} will be executed.
2315
\seefl{Get}{TResourceFile.Get}
2318
\begin{function}{TResourceFile.Get}
2320
Function TResourceFile.Get (Key: String): PObject;
2322
\var{Get} returns a pointer to a instance of a resource identified by
2323
\var{Key}. If \var{Key} cannot be found in the list of resources, then
2324
\var{Nil} is returned.
2326
Errors returned may be those by \var{TStream.Get}
2330
\begin{function}{TResourceFile.SwitchTo}
2332
Function TResourceFile.SwitchTo (AStream: PStream; Pack: Boolean): PStream;
2334
\var{SwitchTo} switches to a new stream to hold the resources in.
2335
\var{AStream} will be the new stream after the call to \var{SwitchTo}.
2337
If \var{Pack} is true, then all the known resources will be copied from
2338
the current stream to the new stream (\var{AStream}). If \var{Pack} is
2339
\var{False}, then only the current resource is copied.
2341
The return value is the value of the original stream: \var{Stream}.
2343
The \var{Modified} flag is set as a consequence of this call.
2345
Errors returned can be those of \seep{TStream.Read} and
2346
\seep{TStream.Write}.
2348
\seepl{Flush}{TResourceFile.Flush}
2351
\begin{procedure}{TResourceFile.Flush}
2353
Procedure TResourceFile.Flush;
2355
If the \var{Modified} flag is set to \var{True}, then \var{Flush}
2356
writes the resources to the stream \var{Stream}. It sets the \var{Modified}
2357
flag to true after that.
2359
Errors can be those by \seep{TStream.Seek} and \seep{TStream.Write}.
2361
\seefl{SwitchTo}{TResourceFile.SwitchTo}
2364
\begin{procedure}{TResourceFile.Delete}
2366
Procedure TResourceFile.Delete (Key: String);
2368
\var{Delete} deletes the resource identified by \var{Key} from the
2369
collection. It sets the \var{Modified} flag to true.
2373
\seepl{Flush}{TResourceFile.Flush}
2376
\begin{procedure}{TResourceFile.Put}
2378
Procedure TResourceFile.Put (Item: PObject; Key: String);
2380
\var{Put} sets the resource identified by \var{Key} to \var{Item}.
2381
If no such resource exists, a new one is created. The item is written
2384
Errors returned may be those by \seep{TStream.Put} and \var{TStream.Seek}
2386
\seefl{Get}{TResourceFile.Get}
2389
\section{TStringList}
2390
\label{se:TStringList}
2392
A \var{TStringList} object can be used to read a collection of strings
2393
stored in a stream. If you register this object with the \seep{RegisterType}
2394
function, you cannot register the \var{TStrListMaker} object.
2396
This is the public declaration of the \var{TStringList} object:
2399
TStrIndexRec = Packed RECORD
2400
Key, Count, Offset: Word;
2403
TStrIndex = Array [0..9999] Of TStrIndexRec;
2404
PStrIndex = ^TStrIndex;
2406
TStringList = OBJECT (TObject)
2407
Constructor Load (Var S: TStream);
2408
Destructor Done; Virtual;
2409
Function Get (Key: Sw_Word): String;
2411
PStringList = ^TStringList;
2414
\begin{procedure}{TStringList.Load}
2416
Constructor TstringList.Load (Var S: TStream);
2418
The \var{Load} constructor reads the \var{TStringList} object from the
2419
stream \var{S}. It also reads the descriptions of the strings from the
2420
stream. The string descriptions are stored as an array of
2421
\var{TstrIndexrec} records, where each record describes a string on the
2422
stream. These records are kept in memory.
2424
If an error occurs, a stream error is triggered.
2426
\seepl{Done}{TStringList.Done}
2429
\begin{procedure}{TStringList.Done}
2431
Destructor TstringList.Done; Virtual;
2433
The \var{Done} destructor frees the memory occupied by the string
2434
descriptions, and destroys the object.
2438
\seepl{Load}{TStringList.Load}, \seep{TObject.Done}
2441
\begin{function}{TStringList.Get}
2443
Function TStringList.Get (Key: Sw\_Word): String;
2445
\var{Get} reads the string with key \var{Key} from the list of strings on the
2446
stream, and returns this string. If there is no string with such a key, an
2447
empty string is returned.
2449
If no string with key \var{Key} is found, an empty string is returned.
2450
A stream error may result if the stream doesn't contain the needed strings.
2452
\seep{TStrListMaker.Put}
2454
\section{TStrListMaker}
2455
\label{se:TStrListMaker}
2457
The \var{TStrListMaker} object can be used to generate a stream with
2458
strings, which can be read with the \var{TStringList} object.
2459
If you register this object with the \seep{RegisterType}
2460
function, you cannot register the \var{TStringList} object.
2462
This is the public declaration of the \var{TStrListMaker} object:
2465
TStrListMaker = OBJECT (TObject)
2466
Constructor Init (AStrSize, AIndexSize: Sw_Word);
2467
Destructor Done; Virtual;
2468
Procedure Put (Key: SwWord; S: String);
2469
Procedure Store (Var S: TStream);
2471
PStrListMaker = ^TStrListMaker;
2474
\begin{procedure}{TStrListMaker.Init}
2476
Constructor TStrListMaker.Init (AStrSize, AIndexSize: SwWord);
2478
The \var{Init} constructor creates a new instance of the \var{TstrListMaker}
2479
object. It allocates \var{AStrSize} bytes on the heap to hold all the
2480
strings you wish to store. It also allocates enough room for
2481
\var{AIndexSize} key description entries (of the type \var{TStrIndexrec}).
2483
\var{AStrSize} must be large enough to contain all the strings you wish to
2484
store. If not enough memory is allocated, other memory will be overwritten.
2485
The same is true for \var{AIndexSize} : maximally \var{AIndexSize} strings
2486
can be written to the stream.
2490
\seep{TObject.Init}, \seepl{Done}{TStrListMaker.Done}
2493
\begin{procedure}{TStrListMaker.Done}
2495
Destructor TStrListMaker.Done; Virtual;
2497
The \var{Done} destructor de-allocates the memory for the index description
2498
records and the string data, and then destroys the object.
2502
\seep{TObject.Done}, \seepl{Init}{TStrListMaker.Init}
2505
\begin{procedure}{TStrListMaker.Put}
2507
Procedure TStrListMaker.Put (Key: Sw\_Word; S: String);
2509
\var{Put} adds they string \var{S} with key \var{Key} to the collection of
2510
strings. This action doesn't write the string to a stream. To write the
2511
strings to the stream, see the \seepl{Store}{TStrListMaker.Store} method.
2515
\seepl{Store}{TStrListMaker.Store}.
2518
\begin{procedure}{TStrListMaker.Store}
2520
Procedure TStrListMaker.Store (Var S: TStream);
2522
\var{Store} writes the collection of strings to the stream \var{S}.
2523
The collection can then be read with the \var{TStringList} object.
2525
A stream error may occur when writing the strings to the stream.
2527
\seep{TStringList.Load}, \seepl{Put}{TStrListMaker.Put}.
added
removed
docs/objects.tex
