causerie

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class AFileStream

DescriptionHierarchyFieldsMethodsProperties

Unit

classwork

Declaration

type AFileStream = class(AStream, CanPrint)

Description

A file stream.

It is unlikely that you will directly instantiate this class, since it is incapable of performing read or write operations; these operations are instead delegated to one of its descendants: AFileInputStream or AFileOutputStream.

Hierarchy

Overview

Fields

Protected myFile: file;
Protected myFileName: string;
Protected myHandleIsValid: boolean;

Methods

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 procedure close; virtual;
Public function hasEnded: boolean; override;
Public function name: string; override;
Public function toString: string; override;
Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;
Public function position: TStreamOffset; override;
Public function setPosition(newPosition: TStreamOffset): TStreamOffset; override;
Public function length: TStreamLength; override;
Public function handle: pointer; virtual;
Public function fileName: string; virtual;
Public function handleIsValid: boolean; virtual;

Description

Fields

Protected myFile: file;

Stores the handle used to represent the file

Protected myFileName: string;

Stores the name of the file

Protected myHandleIsValid: boolean;

Indicates whether or not the file handle is valid

Methods

Public function init: boolean; override;

Initializes the instance.

Public destructor destroy; override;

Destroys the instance.

This routine is called by TObject.free. It calls AFileStream.close automatically, to ensure that the file stream is closed and all buffers are flushed to disk before the stream is destroyed.

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

Reads count bytes from the stream into dest and returns the total number of bytes read.

It is the caller's responsibility to ensure that dest has space sufficient for storing all of the data that will be read from the stream; failure to do so will likely destabilize your program and crash your code.

This method may throw an exception if the read fails, but it should NOT throw an exception if the end of the stream is encountered; instead, it should simply return the total number of bytes that were read before the end of the stream was reached.

As implemented in AFileStream, this routine does nothing and returns zero (0). It is for those descendants that support reading from a file to implement this method; see AFileInputStream.read.

Returns

The total number of bytes read from the stream. If the end of the stream is reached while reading, this value may be less than count.

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

Writes count bytes from source to the stream and returns the total number of bytes written.

It is the caller's responsibility to ensure that source has at least count bytes ready to be written; failure to do so will likely cause your code to crash.

This method may throw an exception if the write operation fails.

As implemented in AFileStream, this routine does nothing and returns zero (0). It is for those descendant that support writing to a file to implement this method; see AFileOutputStream.write.

Returns

The total number of bytes written to the stream.

Public procedure close; virtual;

Flushes any buffered data to the underlying file and then closes the file.

It is unlikely that you will call this routine directly; it is called automatically when the file stream is destroyed.

Public function hasEnded: boolean; override;

Determines whether or not the end of the stream has been reached.

This method calls System.eof on the underlying file and returns True if the end of the file has been reached, and False otherwise.

Public function name: string; override;

Returns the name of the file being streamed.

Public function toString: string; override;

Constructs and returns a string representation of the class.

The base implementation of this method for AFileStream simply returns the name of the underlying file represented by the stream; descendant classes may override this routine to return something different instead.

Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;

Prints a string representation of the class to the specified stream.

The base implementation of this method for AFileStream calls AFileStream.toString and prints the resulting representation to Dest. Descendant classes may override this routine to produce different behavior.

Returns

The total number of bytes written to Dest.

Public function position: TStreamOffset; override;

Retrieves the current position within the stream. This is the location at which the next read or write operation on the stream will take place.

The value returned by this routine is always measured in bytes from the beginning of the stream. The first byte in the stream is always at offset zero (0).

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

Sets the current position within the stream. This is the location at which the next read or write operation on the stream will take place.

newPosition may be either a positive or negative value. If positive, then it represents a position in the stream relative to the beginning of the stream. The first byte in the stream is always at offset zero (0).

If newPosition is a negative value, then it represents a position in the stream relative to the end of the stream. In this case, the last byte in the stream is always located at offset -1.

This method should not throw an exception if the underlying mechanism does not support repositioning; it should instead fail silently and return the current, unchanged position within the stream.

Returns

The previous position within the stream.

Public function length: TStreamLength; override;

Retrieves the current length of the stream; this is the current size of the underlying file, measured in bytes.

For streams that support write operations, this value will change as more data is written to the stream.

Public function handle: pointer; virtual;

Retrieve the handle of the underlying file.

In the base implementation of AFileStream, the handle returned by this routine will simply be a reference to the Pascal file object that represents the file on disk.

Public function fileName: string; virtual;

Retrieve the name of the file being streamed.

Public function handleIsValid: boolean; virtual;

Return whether or not the file handle returned by a call to AFileStream.handle is valid.

If the attempt to open or create the file named by AFileStream.fileName fails, then this routine will return False. Otherwise, it will return True.

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