Class AStreamIterator

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type AStreamIterator = class(AnIterator)

Description

This class can be used to iterate over the data in a stream.

It is possible to process the data contained by the stream in chunks of an arbitrary size (from one byte to 8 bytes) by calling AStreamIterator.setSize.

AStream and its descendants make use of this class to produce CRC checksums of stream data when AStream.checksum is called, as shown below:


    // Calculate a checksum for the stream
    function AStream.checksum: TStreamChecksum;

    var
      // Stores the size of the stream
      streamSize: TStreamLength;
      // Stores the position in the stream before the checksum was calculated
      previousPosition: TStreamOffset;
      // Used to iterate over the stream
      Element: AStreamIterator;

    begin
      result := 0;
      streamSize := Self.length;
      if streamSize > 0 then
      begin
        // Store the current position
        previousPosition := Self.position;

        Element := AStreamIterator(Self.iterator);
        result := crc64(0, nil, 0);

        while Element.continues do
        begin
          result := crc64(result, Element.value, Element.size);
          Element.next;
        end;

        Element.free;
        // Seek the previous position
        Self.setPosition(previousPosition);
      end;
    end;
    

Hierarchy

Overview

Fields

Protected MyStream: AStream;
Protected myValue: qword;
Protected myValueSize: TStreamIOSize;

Methods

Public constructor over(const ThisStream: AStream);
Public function init: boolean; override;
Public procedure next; override;
Public function continues: boolean; override;
Public function shallowCopyFrom(const Other: AnObject): boolean; override;
Public function Stream: AStream; virtual;
Public function value: pointer; virtual;
Public function size: TStreamIOSize; virtual;
Public function setSize(const newSize: TStreamIOSize): TStreamIOSize; virtual;

Description

Fields

Protected MyStream: AStream;

Refers to the stream over which the iterator will iterate

Protected myValue: qword;

Stores the most recent value read from the stream

Protected myValueSize: TStreamIOSize;

Stores the size of the value read from the stream

Methods

Public constructor over(const ThisStream: AStream);

Construct an instance of AStreamIterator that can be used to process the data in ThisStream.

The iterator will begin processing data at the current position in the given stream; this means that if ThisStream has already reached its end, the instance of AStreamIterator returned by this constructor may be useless until the underlying stream position pointer is reset.

It is unlikely that you will call this routine directly; it is called automatically by AStream.iterator.

Public function init: boolean; override;

Initializes the iterator instance

Public procedure next; override;

Retrieves the next element from the stream.

The size of the element read from the stream may be from one to eight bytes; this is determined by AStreamIterator.size and can be changed by calling AStreamIterator.setSize before calling this routine. The value retrieved from the stream can be accessed by calling AStreamIterator.value.

Public function continues: boolean; override;

Determines whether or not there are more items to retrieve from the underlying stream.

If the underlying stream has reached its end, this routine will return False; otherwise, it returns True.

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

Construct a shallow copy of the given object.

This method overrides the behavior inherited from AnObject.shallowCopyFrom; it calls that routine, then ascertains whether Other is an instance of AStreamIterator. If it is, then it copies the current values of:

from Other to Self, overriding any current values in Self before it returns True. Otherwise it returns False.

Public function Stream: AStream; virtual;

Retrieves a reference to the stream which is being traversed by the iterator.

Public function value: pointer; virtual;

Retrieves the most recent value read from the stream.

This function returns a generic pointer to the most recent value read; this pointer can be cast to the appropriate type by the caller. This value is volatile, which means it will be overwritten by the next call to AStreamIterator.next.

Public function size: TStreamIOSize; virtual;

Retrieves the size of values read from the stream.

The value returned by this function will be from one to eight, indicating the number of bytes read from the underlying stream by each call to AStreamIterator.next. It is possible to change this value by calling AStreamIterator.setSize.

By default, instances of AStreamIterator read eight bytes of data at a time from the stream.

Public function setSize(const newSize: TStreamIOSize): TStreamIOSize; virtual;

Sets the size of the values read from the stream.

newSize may be a value from one to eight, indicating that the iterator should read from one to eight bytes on the next call to AStreamIterator.next. Any other values are ignored.

Returns

The previous value of AStreamIterator.size.


Generated by PasDoc 0.13.0 on 2015-06-23 19:40:11