RAD Studio |  |

Specifying the Stream Position and Size
Seeking to a specific position | Using Position and Size properties | See Also
Collapse All

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.

See Also

Using Streams to Read or Write Data

Copying Data from One Stream to Another

Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!