Unit classwork

Uses

Classes, Interfaces, Objects and Records

Variables

Description

This is a library of basic classes that are designed to serve as the foundation of other, larger projects. The classes and routines defined by the library are designed to work across multiple platforms and have (as of this writing) been tested on Windows 7 and Ubuntu.

This library continues to be refined. It presently defines classes and routines to handle:

basic object types: AnObject
streaming I/O: AStream and AFileStream and their descendants
exceptions: AnException and its descendants
linked lists: ANode, ALinkedList and their descendants
binary trees: ABinaryLeaf, ABinaryTree and their descendants
logging: ALoggedItem, ALog and their descendants
string handling: Charstring
iteration: CanIterate and AnIterator and its descendants
vectors: AVector and its descendants
basic application support: AnApplication and its descendants

All of this functionality routinely serves as the basis for my projects, and so I have now condensed what were several units into one for increased portability between projects.

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `MemorySpan`	This is a utility class that provides some helpful routines for quickly filling and copying stretches of memory.
Class `AnObject`	This class extends `TObject` to provide some additional functionality reminiscent of that provided by the base `Object` class in Objective C.
Class `AReferenceCountedObject`	This class represents a reference-counted object; that is, an object that maintains a count of the number of times it has been explicitly referenced.
Class `ASingleton`	This class represents a singleton, which is a class that can only have one instance throughout the lifetime of a program.
Class `AnIterator`	This class represents an abstract iterator.
Interface `CanIterate`	This iterface declares the methods that must be implemented by any class that supports iteration over its data.
Class `AStream`	The base stream type.
Interface `CanStream`	This interface declares the methods that must be implemented by any class that is capable of streaming its data.
Class `AStreamIterator`	This class can be used to iterate over the data in a stream.
Class `AStreamWrapper`	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.
Class `ATextInputStream`	This class serves as the basis for a class which wraps around other instances of AStream and provides the ability to treat the data read from the stream as text.
Class `ATextOutputStream`	This class serves as the basis for a class which wraps around other instances of AStream and provides the ability to treat the data to be written to the stream as text.
Interface `CanPrint`	This interface will be adopted by all classes that are able to produce string representations of themselves and their data, and which can also print those representations to an arbitrary stream.
Class `Charstring`	This class acts as a repository for some string functions that are used by various classes.
Class `APrintingObject`	An object that can produce and stream a string representation of itself.
Class `AnException`	A basic exception.
Class `ABufferedStream`	This class serves as the basis for a pair of classes that wrap around other streams and provide buffered input and output of those streams.
Class `ABufferedInputStream`	This class wraps around an input stream and buffers input from that stream.
Class `ABufferedOutputStream`	This class wraps around an output stream and buffers output to that stream.
Class `ABufferedStreamError`	This class represents an error that may occur when attempting to allocate the buffer for a buffered stream.
Class `AFileStream`	A file stream.
Class `AFileInputStream`	This class can be used for binary input from a file that can be accessed by the underlying file system.
Class `AFileOutputStream`	This class can be used for binary output to any file that is accessible to the underlying file system.
Class `AFileStreamOpenError`	An instance of this exception class is raised if the constructor for AFileInputStream fails to open the specified file for reading, or if the constructor for AFileOutputStream fails to open the specified file for writing.
Class `AFileStreamReadError`	An instance of this exception class is raised if AFileInputStream.read fails to retrieve data from the underlying file.
Class `AFileStreamWriteError`	An instance of this exception class is raised if AFileOutputStream.write fails to write data to the underlying file.
Class `AStandardOutputStream`	This class allows access to `stdout` as though it was a file stream.
Class `AStandardInputStream`	This class allows access to `stdin` as though it was a file stream.
Class `AStandardErrorStream`	This class allows access to `stderr` as though it was a file stream.
Class `AConsoleOutputStream`	This class can be used to wrap around an instance of AStandardOutputStream or one of its descendants so that ASCII and UTF-8 encoded text can be written to the stream.
Class `AConsoleInputStream`	This class can be used to wrap around an instance of AStandardInputStream or any of its descendants so that ASCII and UTF-8 encoded text can be read from the stream.
Class `AStringStream`	This class allows an `AnsiString` to be read from and written to as though it was a stream.
Class `ANode`	This class represents a single object in a hierarchical linked list.
Class `AVector`	This class represents a vector, which is a dynamically-allocated one-dimensional array that contains elements which are all the same size.
Class `AVectorError`	An instance of this exception class is raised whenever there is a fatal error within an instance of AVector.
Class `AVectorAllocationError`	An instance of this exception class is raised when allocating memory for the buffer fails in a call to AVector.allocateElements.
Class `APointerVector`	This class represents a vector of pointers.
Class `AnObjectVector`	This class represents an array that contains references to objects: descendants of AnObject.
Class `ABinaryLeaf`	This class represents a node in a binary tree.
Class `ABinaryTree`	This class represents a basic binary tree which contains nodes that are sorted by an integer key.
Class `ABinaryTreeDictionary`	This class represents a "dictionary" of binary trees, which is simply a binary tree of binary trees.
Class `ABinaryTreeIterator`	Instances of this class can be used to iterate through the nodes in ABinaryTree and its descendants, starting with the root node and proceeding toward ABinaryTree.YoungestNode.
Class `AStringLeaf`	This class represents a node in a binary tree that keeps the string used to define its sort key.
Class `AStringTree`	This class represents a binary tree that is comprised of instances of AStringLeaf.
Class `ALinkedList`	This class represents a doubly-linked list of nodes.
Class `AStringListItem`	This class represents a single entry in AStringList.
Class `AStringList`	This class represents a list of one or more strings.
Class `AVariantListItem`	This class represents a single item in a linked-list of items.
Class `AVariantList`	This class represents a list of one or more variant values.
Class `APointerListItem`	This class represents a single entry in APointerList.
Class `APointerList`	This class represents a list of one or more pointers.
Class `AnObjectListItem`	This class represents a single entry in AnObjectList.
Class `AnObjectList`	This class represents a list of one or more objects.
Class `ALinkedQueue`	This class alters the behavior of ALinkedList so that it can be used as a queue (first in, first out).
Class `AStringQueue`	This class alters the behavior of AStringList so that it can be used as a queue (first in, first out).
Class `AVariantQueue`	This class alters the behavior of AVariantList so that it can be used as a queue (first in, first out).
Class `APointerQueue`	This class alters the behavior of APointerList so that it can be used as a queue (first in, first out).
Class `AnObjectQueue`	This class alters the behavior of AnObjectList so that it can be used as a queue (first in, first out).
Class `AMappingEntry`	This class represents a mapping entry, which is an item that is indexed by a string key and which maps that key to a value.
Class `AMapping`	This class represents a mapping, which is a list of items that are indexed by a string key.
Class `AnObjectMappingEntry`	This class represents an entry in an object mapping, which is an object reference that is indexed by a string key.
Class `AnObjectMapping`	This class represents an object mapping, which is a list of object references that are index by string keys.
Class `ADictionaryEntry`	This class represents a dictionary entry, which is an item that is indexed by a string key.
Class `ADictionary`	This class represents a dictionary, which is a list of items that are indexed by a string key.
Class `AStreamBookmark`	This class represents a stream bookmark, which is a way of associating a name with a specific location in a stream.
Class `AStreamBookmarkSpan`	This class represents a string bookmark that specifies a span: that is, a block of bytes within a stream.
Class `AStreamBookmarkDictionary`	This class represents a dictionary of stream bookmarks, which is a collection of instances of AStreamBookmark.
Class `ABookmarkedStream`	This class represents a bookmarked stream, which is a stream that is capable of saving and reading its own list of bookmarks.
Class `ABookmarkedOutputStream`	This class represents a stream that is capable of recording bookmarks to a dictionary of bookmarks and then writing that dictionary to itself at a given position.
Class `ABookmarkedInputStream`	This class represents a stream that is capable of reading a dictionary of bookmarks from itself.
Class `ACounter`	This class represents a single named counter.
Class `ACounterOverageError`	An instance of this exception class is raised by ACounter.increment if all of the following are true: ACounter.limit has a value that is not zero, that value is exceeded by a call to ACounter.increment, and ACounter.notifyOnExcess is `True`.
Class `ACounterList`	This class is used by ALog and its descendants to manage a list of named counters: one for each type of message that can be logged.
Class `ALoggedItem`	This class represents a basic item that can be logged to an instance of ALog.
Class `ALoggedNote`	This class represents a simple note that is logged.
Class `ALoggedHint`	This class represents a hint that is logged.
Class `ALoggedWarning`	This class represents a warning that is logged.
Class `ALoggedError`	This class represents a error that is logged.
Class `ALoggedFatalError`	This class represents a hint that is logged.
Class `ALog`	This class represents a generic log, which can be used to output status and error messages to an assigned stream.
Class `AFileLog`	This class represents a log that will log to a file stream.
Class `AConsoleLog`	This class represents a log that will log to either `stdout` or `stderr`.
Class `ABufferedLog`	This class represents a log that will log to a string stream.
Class `ALoggingObject`	This class represents a generic object that is capable of logging items to a given log.
Class `AFileVersionInfoResource`	This class represents version information that is stored as a resource inside of an object file which represents the main executable of the current process.
record `TVSFixedFileInfo`	This structure defines the items in the version resource which are fixed: that is, their sizes and locations within the resource are predefined.
record `TTypicalVersionInfoHeader`	These elements exist at the beginning of every pseudo-structure.
Class `AnELFFileVersionInfoResource`	This class represents version information that is stored as a resource within the ELF object file that represents main code segment of the current process.
Class `AnApplication`	This class represents a single process (an application) in an object-oriented fashion.
Class `AConsoleApplication`	This class represents a single process running as a console application: a program that uses a terminal or console for standard input and output.
record `TMiniToken`	This type represents a token that is parsed by an instance of AMiniParser.
Class `AMiniScanner`	This class represents a miniature scanner.
Class `AMiniParser`	This class represents a miniature parser.

Functions and Procedures

procedure clamp(var value: longint; const min, max: longint); overload;

procedure clamp(var value: longword; const min, max: longword); overload;

procedure clamp(var value: int64; const min, max: int64); overload;

procedure clamp(var value: qword; const min, max: qword); overload;

procedure clamp(var value: real; const min, max: real); overload;

procedure clamp(var value: double; const min, max: double); overload;

function ioMessage(const ioCode: longword): string;

function TVarRecToVariant(const value: TVarRec): Variant;

function TVarRecToString(const item: TVarRec): string;

Types

ABinaryLeafPointer = ˆABinaryLeaf;

AMiniParserCallback = function(const Parser: AMiniParser; const token: PMiniToken; const prevToken: PMiniToken; var abortParsing: boolean): integer of object;

AMiniTokenType = (...);

AnObjectClass = class of AnObject;

ANodeClass = class of ANode;

ASingletonClass = class of ASingleton;

PMiniToken = ˆTMiniToken;

PTypicalVersionInfoHeader = ˆTTypicalVersionInfoHeader;

PVSFixedFileInfo = ˆTVSFixedFileInfo;

TCensus = int64;

TIndexAbsolute = qword;

TIndexRelative = int64;

TSortKey = int64;

TStreamBookmarkType = longword;

TStreamChecksum = int64;

TStreamIOSize = longword;

TStreamLength = int64;

TStreamOffset = int64;

Constants

APP_RUN_COMPLETE = 0;

APP_RUN_INCOMPLETE = -1;

bfstDefaultBufferSize = 4 * 1024;

bfstErrorAllocatingBuffer = 'failed to allocate the %d bytes needed to ' +
    'buffer data for %s';

bnlfStringRepresentation = '[%d]: %d';

bntrDefaultNodePrintingPrefix = #9;

bntrDefaultNodePrintingSuffix = lineEnding;

bntrDefaultPrintingSuffix = lineEnding;

bntrStringRepresentationPlural = '%s that contains %d nodes';

bntrStringRepresentationSingular = '%s that contains %d node';

boolValueFalseString = 'false';

boolValueTrueString = 'true';

charsBeginQuoteCharacter = '"';

charsDigits = '0123456789';

charsEndQuoteCharacter = '"';

charsEscapeSequenceDelimiter = '\';

charsLowercaseLetters = 'abcdefghijklmnopqrstuvwxyz';

charsUppercaseLetters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

cntrErrorLimitReached = 'the number of %s exceeds the limit of %d';

cntrStringRepresentation = '%s: %d';

ctlsDefaultPrintingPrefix = #9;

ctlsDefaultPrintingSuffix = lineEnding;

ctlsPrintedSummaryHeader = 'Total number of' + lineEnding;

errDefaultMessage = 'an error has occurred';

errStringRepresentation = '%s' + lineEnding;

errStringRepresentationWithCode = '(%d): %s' + lineEnding;

fserrInvalidFileName = 'an invalid file name was provided to the stream ' +
    'handler';

fserrOpenRead = 'failed to open "%s" for reading because %s';

fserrOpenWrite = 'failed to open "%s" for writing because %s';

fserrReading = 'failed to read from "%s" because %s';

fserrWriting = 'failed to write to "%s" because %s';

ioAccessDenied = 'access to the file was denied';

ioDataCheckFailed = 'the data integrity check failed';

ioDriveNotFound = 'the specified drive was not found';

ioDriveProtected = 'the drive is protected against writes';

ioDriveReadFailure = 'the drive could not be read';

ioDriveUnavailable = 'the drive is temporarily unable to handle the request';

ioDriveWriteFailure = 'writing to the drive failed';

ioFileNotFound = 'the specified file was not found';

ioFileNotOpen = 'the file must first be opened';

ioHardwareFailure = 'a hardware failure occurred';

ioIncorrectMedia = 'incorrect media is loaded in the drive';

ioInvalidDrive = 'the drive specified is invalid';

ioInvalidHandle = 'an invalid file handle was specified';

ioInvalidNumber = 'an invalid number was encountered';

ioInvalidOperation = 'an invalid operation was attempted';

ioNoFileHandle = 'a handle must first be assigned to the file';

ioPathNotFound = 'the specified path was not found';

ioPrinterPaper = 'the printer is out of paper';

ioReadError = 'reading from the device failed';

ioReadOnly = 'the file was opened for reading only';

ioRemovingDirectory = 'the current directory could not be removed';

ioRenamingFailed = 'the specified file could not be renamed';

ioSectorNotFound = 'the appropriate sector on disk was not found';

ioSeekFailure = 'the proper location on disk was not found';

ioSuccess = 'the operation was successful';

ioTooManyFiles = 'there are already too many open files';

ioUnknown = 'an unknown I/O error occurred';

ioUnknownCommand = 'the command is unrecognized';

ioUnknownDevice = 'the specified device is unknown';

ioWriteError = 'writing to the device failed';

ioWriteOnly = 'the file was opened for writing only';

lgerCounterName = 'errors';

lgerStringRepresentation = 'error: %s';

lgfeCounterName = 'fatal errors';

lgfeStringRepresentation = 'fatal: %s';

lghtCounterName = 'hints';

lghtStringRepresentation = 'hint: %s';

lgitCounterName = 'messages';

lgntCounterName = 'notes';

lgntStringRepresentation = 'note: %s';

lgwrCounterName = 'warnings';

lgwrStringRepresentation = 'warning: %s';

llstDefaultDelimiter = ',';

llstDefaultNodePrintingPrefix = #9;

llstDefaultNodePrintingSuffix = lineEnding;

llstDelimiterTabbedColumn = lineEnding + #9;

llstStringRepresentationPlural = '%s that contains %d nodes';

llstStringRepresentationSingular = '%s that contains %d node';

mapDefaultDelimiter = '=';

nodeStringRepresentationPlural = '%s with %d children';

nodeStringRepresentationSingular = '%s with %d child';

objErrorInitializing = 'failed to create and initialize an instance of "%s"';

plitStringRepresentation = '$%%.%dX';

sbspStringRepresentationPlural = '%s => from %d to %d (%d bytes)';

sbspStringRepresentationSingular = '%s => from %d to %d (%d byte)';

SBTYPE_BOOKMARK = 1;

SBTYPE_SPAN = 2;

stbmStringRepresentation = '%s => %d';

stlfStringRepresentation = '[%d]: "%s"';

striDefaultSize = sizeof(int64);

tosDefaultLineLength = 79;

tosWrapDefaultBreakCharacters: array[0..2] of string = (
    ' ', '-', System.lineEnding);

tosWrapDefaultPadCharacter = ' ';

vctrErrorAllocatingMemory = 'failed to allocate %d bytes to hold elements ' +
    'of %s';

vctrStringRepresentationPlural = '%s that contains %d items';

vctrStringRepresentationSingular = '%s that contains %d item';

vinfComments = 'Comments';

vinfCompanyName = 'CompanyName';

vinfFileDescription = 'FileDescription';

vinfFileVersion = 'FileVersion';

vinfInternalName = 'InternalName';

vinfLegalCopyright = 'LegalCopyright';

vinfLegalTrademarks = 'LegalTrademarks';

vinfOriginalFilename = 'OriginalFileName';

vinfPrivateBuild = 'PrivateBuild';

vinfProductName = 'ProductName';

vinfProductVersion = 'ProductVersion';

vinfSpecialBuild = 'SpecialBuild';

vsStringFileInfoKey: WideString = 'StringFileInfo';

vsVersionInfoKey: WideString = 'VS_VERSION_INFO';

VS_PADDING_ALIGNMENT = sizeof(longword);

VS_PADDING_INCREMENT = sizeof(word);