classwork.pp

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class ADictionary

DescriptionHierarchyFieldsMethodsProperties

Unit

classwork

Declaration

type ADictionary = class(AMapping)

Description

This class represents a dictionary, which is a list of items that are indexed by a string key. The overall functionality of the dictionary is similar to that provided by Python and other languages that implement such objects; however, the dictionary is implemented as a binary tree rather than a table of hashed objects.

As with instances of ABinaryTree, the dictionary is capable of looking up entries and streaming those entries to and from arbitrary streams. The dictionary also supports condensing itself into a delimited string and iterating over its keys and values.

Hierarchy

Overview

Methods

Public constructor fromDelimitedList(const thisList: AnsiString; const pairsDelimiter: string = ''; const keyValueDelimiter: string = ''); virtual;
Public function init: boolean; override;
Public function explode(thisList: AnsiString; pairsDelimiter: string = ''; keyValueDelimiter: string = ''): TCensus; virtual;
Public function Values: AVariantList; virtual;
Public function Add(const thisKey: string; const thisValue: Variant): ADictionaryEntry; reintroduce; virtual;
Public function valueOf(const key: string): Variant; virtual;
Public function valueOf(const key: string; const defaultValue: Variant): Variant; virtual;
Public function setValueOf(const key: string; const thisValue: Variant): Variant; virtual;
Public function valueAt(const thisIndex: TIndexAbsolute): Variant; virtual;
Public function setValueAt(const thisIndex: TIndexAbsolute; const newValue: Variant): Variant; virtual;
Public function setSeveral(const keyValuePairs: array of const): TCensus; virtual;

Description

Methods

Public constructor fromDelimitedList(const thisList: AnsiString; const pairsDelimiter: string = ''; const keyValueDelimiter: string = ''); virtual;

Construct a new dictionary instance that will parse the given string to populate its entries.

thisList must be a doubly-delimited string: each key and value pair must be separated from the next by pairsDelimiter, and the keys themselves must be separated from their associated values by keyValueDelimiter.

If pairsDelimiter is not specified by the caller, or if it is an empty string, then the value of llstDefaultDelimiter is used; likewise, if keyValueDelimiter is not specified by the caller, or if it is an empty string, then the value of mapDefaultDelimiter is used.

See ADictionary.explode for more information.

Public function init: boolean; override;

Initializer

Public function explode(thisList: AnsiString; pairsDelimiter: string = ''; keyValueDelimiter: string = ''): TCensus; virtual;

Parse the given string to add new entries to the dictionary.

thisList must be a doubly-delimited string: each key and value pair must be separated from the next by pairsDelimiter, and the keys themselves must be separated from their associated values by keyValueDelimiter.

If pairsDelimiter is not specified by the caller, or if it is an empty string, then the value of llstDefaultDelimiter is used; likewise, if keyValueDelimiter is not specified by the caller, or if it is an empty string, then the value of mapDefaultDelimiter is used.

An example of a string that would be successfully parsed by this routine is shown below: 

        const
          simpleList: string = 'firstItem=1,secondItem=second,thirdItem=42';

The above string would result in three mapping entries when passed to this routine: the first named firstItem with a value of 1; the second named secondItem with a value of second; and the third named thirdItem with a value of 42.

This method iterates through the key/value pairs in the list, constructing new instances of the class specified by Self.LeafType and then calling ADictionaryEntry.fromDelimitedString to have the key/value parsed. If, for some reason, Self.LeafType does not refer to a descendant of ADictionaryEntry, this this routine does nothing.

Returns

The total number of items added to the mapping.

Public function Values: AVariantList; virtual;

Construct a list of all entry values in the dictionary.

This method proceeds sequentially through all entries in the dictionary, obtaining the value of each. The values are inserted into an instance of AVariantList which is constructed for this purpose.

Returns

An instance of AVariantList that contains the values of all dictionary entries. This list should be freed by the caller when it is no longer required. If there are no entries in the dictionary, an empty variant list is returned.

Public function Add(const thisKey: string; const thisValue: Variant): ADictionaryEntry; reintroduce; virtual;

Add the specified key and value to the dictionary.

As with other instances of ABinaryTree, ADictionary does not allow duplicate entries; consequently, if thisKey already exists in the dictionary, its value will be updated with thisValue. Otherwise, a new entry is created.

Returns

A reference to the dictionary entry that has been created and inserted or, if the entry already existed, the existing entry. The caller should NOT attempt to free this reference; that will be done when the dictionary is destroyed.

Public function valueOf(const key: string): Variant; virtual;

Retrieve the value of the named item.

This method retrieves the instance of ADictionaryEntry that has the specified key; it then returns the value obtained by calling ADictionaryEntry.value on that entry.

If no entry that matches key is found in the dictionary, this routine returns Variants.null.

Public function valueOf(const key: string; const defaultValue: Variant): Variant; virtual;

Retrieve the value of the named item.

This method retrieves the instance of ADictionaryEntry that has the specified key; it then returns the value obtained by calling ADictionaryEntry.value on that entry.

If no entry that matches key is found in the dictionary, this routine returns defaultValue.

Public function setValueOf(const key: string; const thisValue: Variant): Variant; virtual;

Set the value of the named item.

This method retrieves the instance of ADictionaryEntry that has the specified key; it then sets the value by calling ADictionaryEntry.setValue on that entry.

If no entry that matches key is found in the dictionary, then this method will add a new item.

Returns

The previous value of the specified item, if it was found; Variants.null otherwise.

Public function valueAt(const thisIndex: TIndexAbsolute): Variant; virtual;

Retrieves the value at the specified index in the dictionary.

Internally, this method calls ABinaryTree.LeafAtIndex on itself; if that method returns a node, then ADictionaryEntry.value is called on it.

Returns

The value of the node at the specified index, if found; Variants.null otherwise.

Public function setValueAt(const thisIndex: TIndexAbsolute; const newValue: Variant): Variant; virtual;

Set the value of the entry at the specified index in the dictionary.

Internally, this method calls ABinaryTree.LeafAtIndex on itself; if that method returns a node, then ADictionaryEntry.setValue is called on it.

Returns

The previous value of the node at the specified index, if found; Variants.null otherwise.

Public function setSeveral(const keyValuePairs: array of const): TCensus; virtual;

Set the values of multiple entries at once.

This method expects that keyValuePairs will be an even-numbered array of variant parameters representing a string key paired with a value. It calls Self.setValue for each pair in the array, passing the even-numbered item of the pair as the string key and the odd-numbered item of the pair as the value.

The even-numbered element in each pair is converted to a string by means of a call to TVarRecToString. It is then combined with the odd-numbered element of the pair and Self.setValueOf is called. If the array does not contain an even number of items, then the last item is ignored.

If one of the keys in keyValuePairs specifies a key that already exists in the dictionary (even if it was just added by a previous pair in the array), then the value of that item is updated. If the key does not exist, it is added to the dictionary.

Returns

The number of items successfully added to the dictionary.

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