causerie

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class AStreamWrapper

DescriptionHierarchyFieldsMethodsProperties

Unit

classwork

Declaration

type AStreamWrapper = class(AStream)

Description

This class represents a wrapper around an instance of AStream; that is, it defines the basis for a class which can manipulate and extend the capabilities of an arbitrary stream by acting as a stream itself. The read and write methods are passed on to the underlying stream.

The functionality provided by this class is fairly basic; it allows the caller to specify whether or not the wrapper inherits ownership of the stream being wrapped, which means the class being wrapped will be freed when the wrapper is freed. The base class defined here does not implement the abstract read and write methods defined by AStream; that is for descendant classes to do.

Hierarchy

Overview

Fields

Protected MyTarget: AStream;
Protected myOwnTarget: boolean;

Methods

Public constructor around(const Target: AStream; const takeOwnershipOfTarget: boolean = true); virtual;
Public function init: boolean; override;
Public destructor destroy; override;
Public function read(const count: TStreamIOSize; var dest): TStreamIOSize; override;
Public function write(const count: TStreamIOSize; const source): TStreamIOSize; override;
Public function name: string; override;
Public function shallowCopyFrom(const Other: AnObject): boolean; override;
Public function position: TStreamOffset; override;
Public function setPosition(newPosition: TStreamOffset): TStreamOffset; override;
Public function length: TStreamLength; override;
Public function Target: AStream; virtual;
Public function SetTarget(const NewTarget: AStream): AStream; virtual;
Public function ownsTarget: boolean; virtual;
Public function setOwnsTarget(const flag: boolean): boolean; virtual;

Description

Fields

Protected MyTarget: AStream;

Refers to the target stream, around which this object wraps

Protected myOwnTarget: boolean;

Indicates whether or not the wrapper owns its target

Methods

Public constructor around(const Target: AStream; const takeOwnershipOfTarget: boolean = true); virtual;

Construct a new stream wrapper that will wrap around the specified stream.

If takeOwnershipOfTarget is True, then the stream wrapper will assume ownership of Target and will free the stream when it is, itself, freed. Otherwise, the caller is responsible for freeing Target when it is no longer needed and after the stream wrapper is freed.

Public function init: boolean; override;

Initializer

Public destructor destroy; override;

Destroy the wrapper.

If AStreamWrapper.ownsTarget is True, then this method will also free the instance of the stream that it has wrapped. Otherwise, it is for the calling routine to dispose of that instance when it is no longer required.

Public function read(const count: TStreamIOSize; var dest): TStreamIOSize; override;

Read count bytes from the stream and store the resulting data in dest.

This method fails silently and returns zero (0). It is for descendant classes to override the method if they support reading.

Returns

The total number of bytes read from the stream. This will always be zero if called on an instance of AStreamWrapper.

Public function write(const count: TStreamIOSize; const source): TStreamIOSize; override;

Write count bytes from source to the stream.

This method fails silently and returns zero (0). It is for descendant classes to override the method if they support writing.

Returns

The total number of bytes written to the stream. This will always be zero if called on an instance of AStreamWrapper.

Public function name: string; override;

Retrieve the name of the stream.

This method overrides the behavior inherited from AStream: it calls AStream.name on the target stream and returns that value. This means that if the wrapper is working with an instance of AFileStream, then calling this method will return the name of the file being streamed – handy!

Public function shallowCopyFrom(const Other: AnObject): boolean; override;

Construct a shallow copy of the other object.

This method overrides the behavior inherited from AnObject.shallowCopyFrom: it calls that method, then checks to see whether Other is an instance of AStreamWrapper. If so, it copies the value of AStreamWrapper.Target from Other to Self, overwriting any current values in Self.

This method does NOT copy the value of AStreamWrapper.ownsTarget from Other; it always sets that value to False for itself.

Public function position: TStreamOffset; override;

Retrieve the current position within the stream.

This method simply calls the corresponding method on the target stream and returns the value received to the caller. Descendant classes may override this method to introduce different behavior.

Returns

The current position within the stream, as an offset in bytes from the beginning of the stream, which is always at offset zero (0).

Public function setPosition(newPosition: TStreamOffset): TStreamOffset; override;

Set the current position within the stream.

This method simply calls the corresponding method on the target stream and returns the value received to the caller. Descendant classes may override this method to introduce different behavior. For more information on what values newPosition may contain, see AStream.setPosition.

Returns

The previous position within the stream, as an offset in bytes from the beginning of the stream, which is always at offset zero (0).

Public function length: TStreamLength; override;

Retrieve the current size of the stream, in bytes.

This method simply calls the corresponding method on the target stream and returns the value received to the caller. Descendant classes may override this method to introduce different behavior.

Returns

The current size of the stream, in bytes.

Public function Target: AStream; virtual;

Retrieve a reference to the target stream. The target stream is the stream for which the contents are being buffered.

The reference returned by this function should NOT be freed by the caller. If AStreamWrapper.ownsTarget is True, then the buffered stream instance will free the target stream when it is itself freed.

Public function SetTarget(const NewTarget: AStream): AStream; virtual;

Set the target stream. The target stream is the stream for which the contents are being buffered.

This method should be used with care. Descendant classes may override the behavior of this method so that the target stream cannot be arbitrarily changed after the stream wrapper is constructed; consult the documentation for those classes.

If this method is used to alter the target stream, the caller should also call AStreamWrapper.setOwnsTarget to indicate whether or not the wrapper assumes ownership of the new target. By default, this method sets AStreamWrapper.ownsTarget to False when it is called.

Returns

The previous target, if any. If this method does not return Nil, then it is the caller's responsibility to free the previous target stream in order to avoid memory leaks.

Public function ownsTarget: boolean; virtual;

Determine whether or not the buffered stream instance owns its target.

If the buffered stream instance owns its target, then it will free the target stream when it is itself freed. Otherwise, it is up to the routine that constructed the buffered stream instance to free the target stream.

Public function setOwnsTarget(const flag: boolean): boolean; virtual;

Set whether or not the buffered stream instance owns its target.

If the buffered stream instance owns its target, then it will free the target stream when it is itself freed. Otherwise, it is up to the routine that constructed the buffered stream instance to free the target stream when it is no longer needed.

Returns

Whether or not the buffered stream instance previously owned its target.

Generated by PasDoc 0.13.0 on 2015-01-10 17:13:18