TP-Compatible basic Objects.

This document documents the 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 Private part of an object declaration have been left out of this documentation.

Stream error codes: No error Stream error codes: Access error Stream error codes: Initialize error Stream error codes: Stream read error Stream error codes: Stream write error Stream error codes: Get object error Stream error codes: Put object error Stream error codes: Seek error in stream Stream error codes: Error opening stream Stream initialization mode: Create new file Stream initialization mode: Read access only Stream initialization mode: Write access only Stream initialization mode: Read/write access Collection list error: Index out of range Collection list error: Overflow Maximum data size (in bytes) Maximum data size (in words) Maximum data size (in pointers) Maximum data that can be read from a stream (not used) Maximum collection size (in items) Is the default stream content TP compatible This variable determines whether the default stream is filled or read in a TP compatible way. The TPCompatible field can be set on a per-stream basis, and is initialized with the DefaulTPCompatible value. Default stream record for the object. Default stream record for the object. Default stream record for the object. Default stream record for the object. Default stream record for the object. Pointer to default stream error handler. Size of the VMT header in an object (not used). Maximum collection size (in items, same value as in TP) Generic set of characters type. Pointer to . Array with maxmimum allowed number of bytes. Pointer to Array with maxmimum allowed number of words. Pointer to Array with maxmimum allowed number of pointers Pointer to Pointer to a shortstring. Filename - null terminated array of characters. Filename - shortstring version. Alias for Cardinal Alias for longint Record describing a Word (in bytes) High byte of a word Low byte of a word Record describing a longint (in Words) Lower word of longint High word of longint Record describing a pointer to a memory location. Pointer offset Pointer segment Pointer to Record used in streaming mechanism. TSreamRec is used by the Objects unit streaming mechanism: when an object is registered, a TStreamRec record is added to a list of records. This list is used when objects need to be streamed from/streamed to a stream. It contains all the information needed to stream the object. Unique identifier for this object type. Pointer to object VMT Procedure to call when object must be loaded from a stream Procedure to call when object must be stored in a stream. Next item in list Pointer to record. Record describing a point in a 2 dimensional plane. X coordinate Y coordinate Pointer array type used in a Pointer array type used in a Record type used in a to store the strings String key value String character count String offset in stream Allocate a copy of a shortstring on the heap.

NewStr makes a copy of the string S on the heap, and returns a pointer to this copy. If the string is empty then Nil is returned.

The allocated memory is not based on the declared size of the string passed to NewStr, but is baed on the actual length of the string.

If not enough memory is available, an 'out of memory' error will occur. Allocate a copy of a shortstring on the heap.

SetStr makes a copy of the string S on the heap and returns the pointer to this copy in P. If P pointed to another string (i.e. was not Nil, the memory is released first. Contrary to , if the string is empty then a pointer to an empty string is returned.

The allocated memory is not based on the declared size of the string passed to NewStr, but is based on the actual length of the string.

If not enough memory is available, an 'out of memory' error will occur. Dispose of a shortstring which was allocated on the heap.

DisposeStr removes a dynamically allocated string from the heap.

For an example, see .

None. Abstract error handler.

When implementing abstract methods, do not declare them as abstract. Instead, define them simply as virtual. In the implementation of such abstract methods, call the Abstract procedure. This allows explicit control of what happens when an abstract method is called.

The current implementation of Abstract terminates the program with a run-time error 211.

None. Register standard objects.

RegisterObjects registers the following objects for streaming:

TCollection, see .
TStringCollection, see .
TStrCollection, see .

None. Register new object for streaming.

RegisterType registers a new type for streaming. An object cannot be streamed unless it has been registered first. The stream record S needs to have the following fields set:

ObjType: Sw_Word: This should be a unique identifier. Each possible type should have it's own identifier.
VmtLink: pointer: This should contain a pointer to the VMT (Virtual Method Table) of the object you try to register.
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 PStream type variable.
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 PStream type variable.

The VMT of the object can be retrieved with the following expression:


  VmtLink: Ofs(TypeOf(MyType)^);

In case of error (if a object with the same ObjType) is already registered), run-time error 212 occurs. Overflow safe multiply. LongMul multiplies X with Y. The result is of type Longint. This avoids possible overflow errors you would normally get when multiplying X and Y that are too big. None. Overflow safe divide LongDiv divides X by Y. The result is of type Integer instead of type Longint, as you would get normally. If Y is zero, a run-time error will be generated. Describes a rectangular region in a plane. Top left corner of rectangle Bottom right corner of rectangle Is the surface of the rectangle zero Empty returns True if the rectangle defined by the corner points A, B has zero or negative surface. None. Do the corners of the rectangles match

Equals returns True if the rectangle has the same corner points A,B as the rectangle R, and False otherwise.

For an example, see

None. Determine if a point is inside the rectangle Contains returns True if the point P is contained in the rectangle (including borders), False otherwise. None. Copy cornerpoints from another rectangle. Assigns the rectangle R to the object. After the call to Copy, the rectangle R has been copied to the object that invoked Copy. None. Enlarges rectangle to encompas another rectangle. Union enlarges the current rectangle so that it becomes the union of the current rectangle with the rectangle R. None. Reduce rectangle to intersection with another rectangle Intersect makes the intersection of the current rectangle with R. If the intersection is empty, then the rectangle is set to the empty rectangle at coordinate (0,0). None. Move rectangle along a vector. Move moves the current rectangle along a vector with components (ADX,ADY). It adds ADX to the X-coordinate of both corner points, and ADY to both end points. None. Expand rectangle with certain size.

Grow expands the rectangle with an amount ADX in the 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 ADY in the Y direction (both on the top and the bottom side of the rectangle, adding a length 2*ADY to the height of the rectangle.

ADX and ADY can be negative. If the resulting rectangle is empty, it is set to the empty rectangle at (0,0).

None. Set rectangle corners.

Assign sets the corner points of the rectangle to (XA,YA) and (Xb,Yb).

For an example, see .

None. Basis of all objects This type serves as the basic object for all other objects in the Objects unit. Construct (initialize) a new object

Instantiates a new object of type TObject. It fills the instance up with Zero bytes.

For an example, see Free

None. Destroy an object and release all memory. Free calls the destructor of the object, and releases the memory occupied by the instance of the object. No checking is performed to see whether self is nil and whether the object is indeed allocated on the heap. Destroy an object.

Done, the destructor of TObject does nothing. It is mainly intended to be used in the method.

The destructore Done does not free the memory occupied by the object.

None. Check whether a pointer points to an object. Is_Object returns True if the pointer P points to an instance of a TObject descendent, it returns false otherwise. Base stream class

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

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

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

Pointer type to Constructor for TStream instance Init initializes a TStream instance. Descendent streams should always call the inherited Init. Current stream status Additional error info when there is an error. Current size of the stream Current Stream position If set to True streamed data is written in a TP compatible format. Read an object definition from the stream. Get reads an object definition from a stream, and returns a pointer to an instance of this object. On error, is set, and NIL is returned. Read a null-terminated string from the stream. 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. On error, Nil is returned. Return current position in the stream If the stream's status is stOk, GetPos returns the current position in the stream. Otherwise it returns -1 -1 is returned if the status is an error condition. Return the size of the stream. If the stream's status is stOk then GetSize returns the size of the stream, otherwise it returns -1. -1 is returned if the status is an error condition. Read a shortstring from the stream. 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. On error (e.g. not enough memory), Nil is returned. Open the stream

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.

For an example, see .

None. Close the stream

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.

for an example, see .

None. Reset the stream Reset sets the stream's status to 0, as well as the ErrorInfo None. Flush the stream data from the buffer, if any.

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.

for an example, see .

None. Truncate the stream size on current position.

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.

For an example, see .

None. Write an object to the stream.

Put writes the object pointed to by P. P should be non-nil. The object type must have been registered with .

After the object has been written, it can be read again with Get.

For an example, see ;

No check is done whether P is Nil or not. Passing Nil will cause a run-time error 216 to be generated. If the object has not been registered, the status of the stream will be set to stPutError. Write a null-terminated string to the stream.

StrWrite writes the null-terminated string P to the stream. P can only be 65355 bytes long.

For an example, see .

None. Write a pascal string to the stream.

StrWrite writes the pascal string pointed to by P to the stream.

For an example, see .

None. Set stream position.

Seek sets the position to Pos. This position is counted from the beginning, and is zero based. (i.e. seeek(0) sets the position pointer on the first byte of the stream)

For an example, see .

If Pos is larger than the stream size, Status is set to StSeekError. Set stream status

Error sets the stream's status to Code and ErrorInfo to Info. If the StreamError procedural variable is set, Error executes it, passing Self as an argument.

This method should not be called directly from a program. It is intended to be used in descendent objects.

None. Read data from stream to buffer.

Read is an abstract method that should be overridden by descendent objects.

Read reads Count bytes from the stream into Buf. It updates the position pointer, increasing it's value with Count. Buf must be large enough to contain Count bytes.

No checking is done to see if Buf is large enough to contain Count bytes. Write a number of bytes to the stream.

Write is an abstract method that should be overridden by descendent objects.

Write writes Count bytes to the stream from Buf. It updates the position pointer, increasing it's value with Count.

For an example, see .

No checking is done to see if Buf actually contains Count bytes. Copy data from another stream. CopyFrom reads Count bytes from stream S and stores them in the current stream. It uses the Read method to read the data, and the Write method to write in the current stream. None. Read Write DOS file stream

TDosStream is a stream that stores it's contents in a file. it overrides a couple of methods of for this.

In addition to the fields inherited from TStream (see ), 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 TDosStream. All data are written directly to the file. For a stream that buffers in memory, see .

OS file handle for stream File name Instantiate a new instance of TDosStream.

Init instantiates an instance of TDosStream. The name of the file that contains (or will contain) the data of the stream is given in FileName. The 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:

stCreate: Creates a new file.
stOpenRead: Read access only.
stOpenWrite: Write access only.
stOpen: Read and write access.

For an example, see .

On error, Status is set to stInitError, and ErrorInfo is set to the dos error code. Closes the file and cleans up the instance.

Done closes the file if it was open and cleans up the instance of TDosStream.

for an example, see e.g. .

None. Close the file.

Close closes the file if it was open, and sets Handle to -1. Contrary to Done it does not clean up the instance of TDosStream

For an example, see .

None. Truncate the file on the current position. If the status of the stream is stOK, then Truncate tries to truncate the stream size to the current file position. If an error occurs, the stream's status is set to stError and ErrorInfo is set to the OS error code. Set file position. If the stream's status is stOK, then Seek sets the file position to Pos. Pos is a zero-based offset, counted from the beginning of the file. In case an error occurs, the stream's status is set to stSeekError, and the OS error code is stored in ErrorInfo. Open the file stream If the stream's status is stOK, and the stream is closed then Open re-opens the file stream with mode OpenMode. This call can be used after a Close call. If an error occurs when re-opening the file, then Status is set to stOpenError, and the OS error code is stored in ErrorInfo Read data from the stream to a buffer.

If the Stream is open and the stream status is stOK then Read will read Count bytes from the stream and place them in Buf.

For an example, see .

In case of an error, Status is set to StReadError, and ErrorInfo gets the OS specific error, or 0 when an attempt was made to read beyond the end of the stream. Write data from a buffer to the stream.

If the Stream is open and the stream status is stOK then Write will write Count bytes from Buf and place them in the stream.

For an example, see .

In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS specific error. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to object. Pointer to array. Pointer to object. Buffered file stream

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.

link id Last file open mode Size of buffer Pointer to current position in buffer End of data in buffer. Actual buffer Initialize an instance of TBufStream and open the file.

Init instantiates an instance of TBufStream. The name of the file that contains (or will contain) the data of the stream is given in FileName. The 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:

stCreate: Creates a new file.
stOpenRead: Read access only.
stOpenWrite: Write access only.
stOpen: Read and write access.

The Size parameter determines the size of the buffer that will be created. It should be different from zero.

For an example see .

On error, Status is set to stInitError, and ErrorInfo is set to the dos error code. Close the file and cleans up the instance.

Done flushes and closes the file if it was open and cleans up the instance of TBufStream.

For an example see .

None. Flush data and Close the file.

Close flushes and closes the file if it was open, and sets Handle to -1. Contrary to Done it does not clean up the instance of TBufStream

For an example see .

None. FLush data from buffer, and write it to stream. 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. Write errors may occur if the file was in write mode. see Write for more info on the errors. Flush buffer, and truncate the file at current position.

If the status of the stream is stOK, then Truncate tries to flush the buffer, and then truncates the stream size to the current file position.

For an example, see .

Errors can be those of Flush or . Set current position in file.

If the stream's status is stOK, then Seek sets the file position to Pos. Pos is a zero-based offset, counted from the beginning of the file.

For an example, see ;

In case an error occurs, the stream's status is set to stSeekError, and the OS error code is stored in ErrorInfo. Open the file if it is closed.

If the stream's status is stOK, and the stream is closed then Open re-opens the file stream with mode OpenMode. This call can be used after a Close call.

For an example, see .

If an error occurs when re-opening the file, then Status is set to stOpenError, and the OS error code is stored in ErrorInfo Read data from the file to a buffer in memory.

If the Stream is open and the stream status is stOK then Read will read Count bytes from the stream and place them in Buf.

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.

For an example, see .

In case of an error, Status is set to StReadError, and ErrorInfo gets the OS specific error, or 0 when an attempt was made to read beyond the end of the stream. Write data to the file from a buffer in memory.

If the Stream is open and the stream status is stOK then Write will write Count bytes from Buf and place them in the stream.

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.

For an example, see .

In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS specific error. Stream which keeps data in memory.

The 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.

Number of allocated memory blocks Size of one memory block Total memory size Pointer to list of allocated blocks. Initialize memory stream, reserves memory for stream data.

Init instantiates a new TMemoryStream object. The memorystreamobject will initially allocate at least ALimit bytes memory, divided into memory blocks of size ABlockSize. The number of blocks needed to get to 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.

For an example, see e.g .

If the stream cannot allocate the initial memory needed for the memory blocks, then the stream's status is set to stInitError. Clean up memory and destroy the object instance.

Done releases the memory blocks used by the stream, and then cleans up the memory used by the stream object itself.

For an example, see e.g .

None. Set the stream size to the current position. 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. If an error occurs during memory de-allocation, the stream's status is set to stError Read data from the stream to a location in memory.

Read reads Count bytes from the stream to Buf. It updates the position of the stream.

For an example, see .

If there is not enough data available, no data is read, and the stream's status is set to stReadError. Write data to the stream.

Write copies Count bytes from Buf to the stream. It updates the position of the stream.

If not enough memory is available to hold the extra Count bytes, then the stream will try to expand, by allocating as much blocks with size BlkSize (as specified in the constuctor call Init) as needed.

For an example, see .

If the stream cannot allocate more memory, then the status is set to stWriteError Manage a collection of pointers of objects

The 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.

Pointer to list of items. Current count of items Max number of items Number of pointers to allocate when adding items. Instantiate a new collection.

Init initializes a new instance of a collection. It sets the (initial) maximum number of items in the collection to ALimit. ADelta is the increase size : The number of memory places that will be allocated in case ALimit is reached, and another element is added to the collection.

For an example, see .

None. Initialize a new collection and load collection from a stream. Load initializes a new instance of a collection. It reads from stream S the item count, the item limit count, and the increase size. After that, it reads the specified number of items from the stream. Errors returned can be those of GetItem. Clean up collection, release all memory.

Done frees all objects in the collection, and then releases all memory occupied by the instance.

For an example, see .

None. Return the item at a certain index. At returns the item at position Index. If Index is less than zero or larger than the number of items in the collection, seepl{Error}{TCollection.Error} is called with coIndexError and Index as arguments, resulting in a run-time error. Find the position of a certain item. IndexOf returns the index of Item in the collection. If Item isn't present in the collection, -1 is returned. If the item is not present, -1 is returned. Read one item off the stream. GetItem reads a single item off the stream S, and returns a pointer to this item. This method is used internally by the Load method, and should not be used directly. Possible errors are the ones from . , Return last item which matches a test. This function returns the last item in the collection for which Test returns a non-nil result. Test is a function that accepts 1 argument: a pointer to an object, and that returns a pointer as a result. None. Return first item which matches a test. This function returns the first item in the collection for which Test returns a non-nil result. Test is a function that accepts 1 argument: a pointer to an object, and that returns a pointer as a result. None. Remove all >Nil pointers from the collection. Pack removes all Nil pointers from the collection, and adjusts Count to reflect this change. No memory is freed as a result of this call. In order to free any memory, you can call SetLimit with an argument of Count after a call to Pack. None. Release all objects from the collection. 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 Count to zero. Delete all elements from the collection. Objects are not destroyed. DeleteAll deletes all elements from the collection. It just sets the Count variable to zero. Contrary to FreeAll, DeletAll doesn't call the destructor of the objects. None. Free item from collection, calling it's destructor. Free Deletes Item from the collection, and calls the destructor Done of the object. If the Item is not in the collection, Error will be called with coIndexError. Insert a new item in the collection at the end. Insert inserts Item in the collection. TCollection inserts this item at the end, but descendent objects may insert it at another place. None. Delete an item from the collection, but does not destroy it. Delete deletes Item from the collection. It doesn't call the item's destructor, though. For this the Free call is provided. If the Item is not in the collection, Error will be called with coIndexError. Free an item at the indicates position, calling it's destructor. AtFree deletes the item at position Index in the collection, and calls the item's destructor if it is not Nil. If Index isn't valid then Error is called with CoIndexError. Destroy a non-nil item.

FreeItem calls the destructor of Item if it is not nil.

This function is used internally by the TCollection object, and should not be called directly. None. Delete item at certain position. AtDelete deletes the pointer at position Index in the collection. It doesn't call the object's destructor. If Index isn't valid then Error is called with CoIndexError. Execute procedure for each item in the list.

ForEach calls Action for each element in the collection, and passes the element as an argument to Action.

Action is a procedural type variable that accepts a pointer as an argument.

None. Set maximum number of elements in the collection.

SetLimit sets the maximum number of elements in the collection. ALimit must not be less than Count, and should not be larger than MaxCollectionSize

For an example, see Pack.

None. Set error code.

Error is called by the various TCollection methods in case of an error condition. The default behaviour is to make a call to RunError with an error of 212-Code.

This method can be overridden by descendent objects to implement a different error-handling.

Set collection item, overwriting an existing value.

AtPut sets the element at position Index in the collection to Item. Any previous value is overwritten.

For an example, see Pack.

If Index isn't valid then Error is called with CoIndexError. Insert an element at a certain position in the collection. AtInsert inserts Item in the collection at position Index, shifting all elements by one position. In case the current limit is reached, the collection will try to expand with a call to SetLimit If Index isn't valid then Error is called with CoIndexError. If the collection fails to expand, then coOverFlow is passd to Error. Write collection to a stream.

Store writes the collection to the stream S. It does this by writeing the current Count, Limit and 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 Load.

For an example, see .

Errors returned are those by . Put one item on the stream PutItem writes Item to stream S. This method is used internaly by the TCollection object, and should not be called directly. Errors are those returned by . Store GetItem Abstract sorted collection.

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

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

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

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

The example below defines a descendent of TSortedCollection which is used in the examples.

If True duplicate strings are allowed in the collection. Instantiates a new instance of a TSortedCollection

Init calls the inherited constuctor (see ) and sets the Duplicates flag to false.

You should not call this method directly, since TSortedCollection is a abstract class. Instead, the descendent classes should call it via the inherited keyword.

None. Instantiates a new instance of a TSortedCollection and loads it from stream.

Load calls the inherited constuctor (see ) and reads the Duplicates flag from the stream..

You should not call this method directly, since TSortedCollection is a abstract class. Instead, the descendent classes should call it via the inherited keyword.

For an example, see .

None. Return the key of an item

KeyOf returns the key associated with Item. 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).

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.

None. Return index of an item in the collection.

IndexOf returns the index of 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 Item.

In case Item is not found in the collection, -1 is returned.

For an example, see

None. Compare two items in the collection.

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 Search method and in the Insert method to determine the ordering of the objects.

The function should compare the two keys of items and return the following function results:

Result < 0: If Key1 is logically before Key2 (Key1<Key2)
Result = 0: If Key1 and Key2 are equal. (Key1=Key2)
Result > 0: If Key1 is logically after Key2 (Key1>Key2)

An 'abstract run-time error' will be generated if you call TSortedCollection.Compare directly. Search for item with given key.

Search looks for the item with key Key and returns the position of the item (if present) in the collection in Index.

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

If the item is found, Search returns True, otherwise False is returned.

None. Insert new item in collection.

Insert inserts an item in the collection at the correct position, such that the collection is ordered at all times. You should never use Atinsert, since then the collection ordering is not guaranteed.

If Item is already present in the collection, and Duplicates is False, the item will not be inserted.

None. Write the collection to the stream.

Store writes the collection to the stream S. It does this by calling the inherited , and then writing the Duplicates flag to the stream.

After a Store, the collection can be loaded from the stream with the constructor Load

For an example, see .

Errors can be those of . Collection of pascal strings.

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

Get string from the stream.

GetItem reads a string from the stream 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.

The errors returned are those of . Compare two strings in the collection.

TStringCollection overrides the 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:

-1: if the first string is alphabetically earlier than the second string.
0: if the two strings are equal.
1: if the first string is alphabetically later than the second string.

None. Dispose a string in the collection from memory. TStringCollection overrides FreeItem so that the string pointed to by Item is disposed from memory. None. Write a string to the stream.

PutItem writes the string pointed to by Item to the stream S.

This method is primarily used in the Load and Store methods, and should not be used directly.

Errors are those of . Collection of null-terminated strings

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

Read a null-terminated string from the stream.

GetItem reads a null-terminated string from the stream 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.

The errors returned are those of . Compare two strings in the collection.

TStrCollection overrides the Compare function so it compares the two keys as if they were pointers to strings. The compare is done case sensitive. It returns

-1: if the first string is alphabetically earlier than the second string.
0: if the two strings are equal.
1: if the first string is alphabetically later than the second string.

None. Free null-terminated string from the collection. TStrCollection overrides FreeItem so that the string pointed to by Item is disposed from memory. None. Write a null-terminated string to the stream.

PutItem writes the string pointed to by Item to the stream S.

This method is primarily used in the Load and Store methods, and should not be used directly.

Errors are those of . Unsorted string collection

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

Take care, the Search and IndexOf methods will not work on an unsorted string collection.

Insert a new string in the collection. Insert inserts a string at the end of the collection, instead of on it's alphabetical place, resulting in an unsorted collection of strings. None. Collection of resource names

A 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:


TYPE
   TResourceItem = packed RECORD
      Posn: LongInt;
      Size: LongInt;
      Key : String;
   End;
   PResourceItem = ^TResourceItem;

It overrides some methods of TStringCollection in order to accomplish this.

Remark that the TResourceCollection manages the names of the resources and their assiciated positions and sizes, it doesn't manage the resources themselves. Return the key of an item in the collection. KeyOf returns the key of an item in the collection. For resources, the key is a pointer to the string with the resource name. None. Read an item from the stream.

GetItem reads a resource item from the stream 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 method.

Errors returned are those by Release memory occupied by item.

FreeItem releases the memory occupied by Item. It de-allocates the name, and then the resourceitem record.

It does NOT remove the item from the collection.

None. Write an item to the stream.

PutItem writes Item to the stream 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 Store method.

Errors returned are those by . Resource file represents the resources in a binary file image. Actual file stream contains the (file) stream that has the executable image and the resources. It can be initialized by the Init constructor call. Have resources changed ? Modified is set to True if one of the resources has been changed. It is set by the SwitchTo, Delete and Put methods. Calling Flush will clear the Modified flag. Instantiate a new instance.

Init instantiates a new instance of a TResourceFile object. If AStream is not nil then it is considered as a stream describing an executable image on disk.

Init will try to position the stream on the start of the resources section, and read all resources from the stream.

None. Destroy the instance and remove it from memory. Done cleans up the instance of the TResourceFile Object. If Stream was specified at initialization, then Stream is disposed of too. None. Number of resources in the file Count returns the number of resources. If no resources were read, zero is returned. None. Return the key of the item at a certain position. KeyAt returns the key (the name) of the I-th resource. In case I is invalid, TCollection.Error will be executed. Return a resource by key name. Get returns a pointer to a instance of a resource identified by Key. If Key cannot be found in the list of resources, then Nil is returned. Errors returned may be those by TStream.Get Write resources to a new stream.

SwitchTo switches to a new stream to hold the resources in. AStream will be the new stream after the call to SwitchTo.

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

The return value is the value of the original stream: Stream.

The Modified flag is set as a consequence of this call.

Errors returned can be those of and . Writes the resources to the stream. If the Modified flag is set to True, then Flush writes the resources to the stream Stream. It sets the Modified flag to true after that. Errors can be those by and . Delete a resource from the file Delete deletes the resource identified by Key from the collection. It sets the Modified flag to true. None. Set a resource by key name. Put sets the resource identified by Key to Item. If no such resource exists, a new one is created. The item is written to the stream. Errors returned may be those by and TStream.Seek Get Collection of strings

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

Load stringlist from stream. The Load constructor reads the TStringList object from the stream S. It also reads the descriptions of the strings from the stream. The string descriptions are stored as an array of TstrIndexrec records, where each record describes a string on the stream. These records are kept in memory. If an error occurs, a stream error is triggered. Clean up the instance The Done destructor frees the memory occupied by the string descriptions, and destroys the object. None. Load Return a string by key name Get reads the string with key 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. If no string with key Key is found, an empty string is returned. A stream error may result if the stream doesn't contain the needed strings. Generate a stream with strings, readable by

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

Instantiate a new instance of TStrListMaker

The Init constructor creates a new instance of the TstrListMaker object. It allocates AStrSize bytes on the heap to hold all the strings you wish to store. It also allocates enough room for AIndexSize key description entries (of the type TStrIndexrec).

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 AIndexSize : maximally AIndexSize strings can be written to the stream.

None. Clean up the instance and free all related memory. The Done destructor de-allocates the memory for the index description records and the string data, and then destroys the object. None. Add a new string to the list with associated key. Put adds they string S with key 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 Store method. None. Write the strings to the stream. Store writes the collection of strings to the stream S. The collection can then be read with the TStringList object. A stream error may occur when writing the strings to the stream. Value for invalid handle. Initial value for file stream handles or when the stream is closed. Call a constructor with no arguments

CallVoidConstructor calls the constructor of an object. Ctor is the address of the constructor, Obj is a pointer to the instance. If it is Nil, then a new instance is allocated. VMT is a pointer to the object's VMT. The return value is a pointer to the instance.

Note that this can only be used on constructors that require no arguments.

If the constructor expects arguments, the stack may be corrupted. Call a constructor with a pointer argument.

Note that this can only be used on constructors that require a pointer as the sole argument. It can also be used to call a constructor with a single argument by reference.

If the constructor expects other arguments than a pointer, the stack may be corrupted. Call an object method CallVoidMethod calls the method with address Method for instance Obj. It returns a pointer to the instance. If the method expects parameters, the stack may become corrupted. Call a method with a single pointer argument CallPointerMethod calls the method with address Method for instance Obj. It passes Param1 to the method as the single argument. It returns a pointer to the instance. If the method expects other parameters than a single pointer, the stack may become corrupted. Call a local nested procedure. CallVoidLocal calls the local procedure with address Func, where Frame is the frame of the wrapping function. If the local function expects parameters, the stack may become corrupted. Call a local nested function with a pointer argument CallPointerLocal calls the local procedure with address Func, where Frame is the frame of the wrapping function. It passes Param1 to the local function. If the local function expects other parameters than a pointer, the stack may become corrupted. Call a local procedure of a method CallVoidMethodLocal calls the local procedure with address Func, where Frame is the frame of the wrapping method. If the local function expects parameters, the stack may become corrupted. Call a local procedure of a method with a pointer argument CallPointerMethodLocal calls the local procedure with address Func, where Frame is the frame of the wrapping method. It passes Param1 to the local function. If the local function expects other parameters than a pointer, the stack may become corrupted. Default value for tstream.tpcompatible DefaultTPCompatible is used to initialize tstream.tpcompatible.