Specifying the Stream Position and Size

In addition to methods for reading and writing, streams permit applications to seek to an arbitrary position in the stream or change the size of the stream. Once you seek to a specified position, the next read or write operation starts reading from or writing to the stream at that position.

Seeking to a specific position

The Seek method is the most general mechanism for moving to a particular position in the stream. There are two overloads for the Seek method:

Copy Code

function Seek(Offset: Longint; Origin: Word): Longint;
function Seek(const Offset: Int64; Origin: TSeekOrigin): Int64;

Copy Code

virtual int __fastcall Seek(int Offset, Word Origin);
virtual __int64 __fastcall Seek(const __int64 Offset, TSeekOrigin Origin);

Both overloads work the same way. The difference is that one version uses a 32-bit integer to represent positions and offsets, while the other uses a 64-bit integer.

The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Values for the Origin parameter

Value	Meaning
soFromBeginning	Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
soFromCurrent	Offset is from the current position in the resource. Seek moves to Position + Offset.
soFromEnd	Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek resets the current stream position, moving it by the indicated offset. Seek returns the new current position in the stream.

Using Position and Size properties

All streams have properties that hold the current position and size of the stream. These are used by the Seek method, as well as all the methods that read from or write to the stream.

The Position property indicates the current offset, in bytes, into the stream (from the beginning of the streamed data). The declaration for Position is:

Copy Code

property Position: Int64;

Copy Code

__property __int64 Position = {read=GetPosition, write=SetPosition, nodefault};

The Size property indicates the size of the stream in bytes. It can be used to determine the number of bytes available for reading, or to truncate the data in the stream. The declaration for Size is:

Copy Code

property Size: Int64;

Copy Code

__property __int64 Size = {read=GetSize, write=SetSize64, nodefault};

Size is used internally by routines that read and write to and from the stream.

Setting the Size property changes the size of the data in the stream. For example, on a file stream, setting Size inserts an end of file marker to truncate the file. If the Size of the stream cannot be changed, an exception is raised. For example, trying to change the Size of a read-only file stream raises an exception.