Skip to content

TPJStreamWrapper-Seek.md

Latest commit

 

History

History
68 lines (41 loc) · 3.39 KB

TPJStreamWrapper-Seek.md

File metadata and controls

68 lines (41 loc) · 3.39 KB

Seek method

Project: Stream Extension Classes

Unit: PJStreamWrapper

Class: TPJStreamWrapper

Applies to: ~>3.0

[~>3.0]

function Seek(Offset: Longint; Origin: Word): Longint; override;

[~>3.1] [1]

function Seek(const Offset: Int64; Origin: TSeekOrigin): Int64; override;

Description

Seek moves the wrapped stream's position a specified number of bytes relative to a given origin.

[~>3.1] There are two overloaded versions of the method: one that takes a 32 bit offset and one that takes a 64 bit offset [1].

Parameters:

  • Offset -- The number of bytes to move the wrapped stream's position from the origin specified by the Origin parameter.
  • Origin -- The origin from which to offset the stream's position. Possible values are:
    • Where Origin has type Word:
      • soFromBeginning (=0): seek from the start of the stream (Offset should be positive).
      • soFromCurrent (=1): seek from the current stream position (use a positive value of Offset to seek forwards and a negative value to seek backwards).
      • soFromEnd (=2): seek from the end of the stream (Offset should be negative) [2]
    • Where Origin has type TSeekOrigin:
      • soBeginning: seek from the start of the stream (Offset should be positive).
      • soCurrent: seek from the current stream position (use a positive value of Offset to seek forwards and a negative value to seek backwards).
      • soEnd: seek from the end of the stream (Offset should be negative) [2].

Returns:

  • New position of the wrapped stream.

    [~>3.1] The type of the return value can be either a 32 bit or a 64 bit integer, depending on which of the overloaded versions of the method was called.

Remarks

This operation may cause an exception if the underlying stream does not support seeking.

The affect of attempting to seek beyond the end of the stream is dependent on the type of the wrapped stream. Attempts to seek before the beginning of the stream result in the stream position being set to the start of the wrapped stream.

[~>3.1] Some wrapped streams may not support 64 bit seek offsets and give unexpected results.

Footnotes

Footnote 1

The version of Seek with the 64 bit integer Offset parameter is included in TPJStreamWrapper only if the library is compiled with Delphi 6 or later. This is because the version of TStream shipped with Delphi 5 and earlier did not include this method.

Footnote 2

Versions of TStringStream compiled from non-Unicode versions of the Classes unit do not handle the soFromEnd / soEnd origin variation of the Seek method correctly - offsets are negated and work in the opposite way expected.

[~>3.0.0] TPJStreamWrapper simply passes the seek request through unchanged to the wrapped class. This means that such errors will be replicated in wrapped classes.

[~>3.1] By default TPJStreamWrapper traps requests for seeks with soFromEnd / soEnd origins and processes them so that any errors in handling them in wrapped streams are fixed. This behaviour can be reverted to that in earlier versions by un-defining the FIX_TSTRINGSTREAM_SEEK_ERROR symbol in the PJStreamWrapper unit.