Class TPeekCharStream

Unit

KambiClassUtils

Declaration

type TPeekCharStream = class(TStream)

Description

This is a purely sequential read-only stream. This means that calling Write, Seek (changing Position) or setting Size will always cause an exception with appropriate descendant class of EStreamNotImplemented.

Getting Size and Position is allowed. Getting Size is simply implemented by getting SourceStream.Size. Position works correctly, i.e. it always returns the number of characters *read* from underlying stream. This means that peeking (using PeekChar) never changes position, also using read buffer (see TBufferedReadStream) do not affect Position. Position returns you position in *this stream*, not your "real" position in underlying SourceStream.

In exchange, you get the ability to use PeekChar routine: you can always peek ahead one char in the stream, without reading it (i.e. next time you will call Read or ReadBuffer you will still get that char). This way even SourceStream may be purely sequential read-only stream (if you're sure that your SourceStream allows always to set Position than you could simply use Position := Position - 1; instead of using this class...).

Notes about Read method overriden by this class descendants:

This tries to read next Count bytes from SourceStream, making sure that even character that you obtained by PeekChar will be returned here. In other words, this just implements Read method of TStream :)

This may call SourceStream.Read, and any exceptions that may be raised in SourceStream.Read are propagated higher from this method.

Hierarchy

• TStream
• TPeekCharStream

Overview

Methods

	function GetSize: Int64; override;
	procedure SetSize(NewSize: Longint); override;
	function Seek(const Offset: Int64; Origin: TSeekOrigin): Int64; override;
	function Write(const Buffer; Count: Longint): Longint; override;
	function PeekChar: Integer; virtual; abstract;
	function ReadChar: Integer; virtual; abstract;
	function ReadUpto(const EndingChars: TSetOfChars): string; virtual; abstract;
	constructor Create(ASourceStream: TStream; AOwnsSourceStream: boolean);
	destructor Destroy; override;

Properties

	property SourceStream: TStream read FSourceStream;
	property OwnsSourceStream: boolean read FOwnsSourceStream write FOwnsSourceStream;

Description

Methods

	function GetSize: Int64; override;
Returns SourceStream.Size

	procedure SetSize(NewSize: Longint); override;
All other versions of SetSize also call this. Exceptions raised EStreamNotImplementedSetSize always

	function Seek(const Offset: Int64; Origin: TSeekOrigin): Int64; override;
SetPosition and all other versions of Seek also call this. Exceptions raised EStreamNotImplementedSeek always (well, actually with FPC 1.9.8 raises some other thing ("Seek not implemented"), but it's temporary)

	function Write(const Buffer; Count: Longint): Longint; override;
WriteBuffer also calls this. Exceptions raised EStreamNotImplementedWrite always

function PeekChar: Integer; virtual; abstract;

Peeks next char from the stream but doesn't treat it as "already read", i.e. the next call to Read or ReadBuffer will return this char. Subsequent calls to PeekChar (without any Read/ReadBuffer between) will always return the same value. Returns -1 if stream ended, otherwise returns Ord or given char. This may call SourceStream.Read, and any exceptions that may be raised in SourceStream.Read are propagated higher from this method.

	function ReadChar: Integer; virtual; abstract;
This is somehow a shortcut for Read(c, 1), but it returns -1 if eof is reached. So it's consistent with PeekChar. Sometimes it's also more comfortable, and it's a little faster.

	function ReadUpto(const EndingChars: TSetOfChars): string; virtual; abstract;
Whole PeekChar is not one of EndingChars (and it's not eof) it reads chars from stream and appends them to Result. This means that Result is guaranteed to not contain any char from EndingChars.

	constructor Create(ASourceStream: TStream; AOwnsSourceStream: boolean);

	destructor Destroy; override;

Properties

	property SourceStream: TStream read FSourceStream;
Underlying stream.

	property OwnsSourceStream: boolean read FOwnsSourceStream write FOwnsSourceStream;
If true then at the destruction it will free FSourceStream.