Class Hash

Introduction

This class providess a high-performance associative array for Synergy/DE. It only supports alphanumeric keys and does not automatically box primitives. It also only supports one object per key, and treats ^null as not set. For an associative array that breaks these limitations (albeit at a performance cost) see ls.

Contents

  1. Introduction
  2. Contents
  3. Explanation of symbols used
  4. Member reference
    1. CaseSensitive - case-sensitivity of keys
    2. Count - number of non-null objects
    3. Dispose - release resources
    4. Indexer - array-style member access
    5. Iterator - iterator class
      1. (constructor) - create a Hash iterator
      2. First - return the first item
      3. Last - return the last item
      4. Next - return the next item
      5. Prev - return the previous item
      6. Sorted - control order of iteration

Explanation of symbols used

Words in italics indicate an instance of a class. The word corresponds to the class name, except where more than one instance is represented in the same statement. In that case a number (2, 3, etc.) is appended to the class name.

Words in normal typeface are to be taken literally (required punctuation, class name in a static reference, method name, etc.)

The symbol => is used to separate an expression (on the left) from its return value (on the right).

An ellipsis (...) indicates that the previous argument may be repeated any number of times. The description will indicate whether one instance is required.

Member reference

property CaseSensitive

hash.CaseSensitive => boolean
hash.CaseSensitive = boolean
This property controls whether keys that differ only by case are considered unique. If you change this property after any items have been added, an exception will be thrown. This property is false by default.

property Count

hash.Count => int
This read-only property returns the number of non-null objects referenced by hash.

method Dispose

hash.Dispose()
This method releases the internal resources used for maintaining the key => value associations. It is called automatically by the destructor, but on .NET you may wish to call it explicitly to ensure that resources are released before the program stops. If it is called more than once, no error occurs.

indexer

hash[a] => object
hash[a] = object
This indexer references the object associated with the key a. When assigning, any previous object associated with the key is no longer associated. When accessing, if there is no such key, ^null is returned. Therefore, assign ^null to remove an association. Note, though, that every key ever assigned remains in the internal symbol table, even if it is assigned a null reference.

class Iterator

This class provides a way to iterate over the members of a Hash. Members include:

constructor

new Hash.Iterator(hash) => iterator
new Hash.Iterator(hash, boolean) => iterator
Creates a new iterator for hash. If boolean is passed, it specifies whether the iteration should be sorted in key order. This can be modified later using the Sorted property.

method First

iterator).First() => object
iterator).First(a) => object
Returns the first non-null object in the hash, according to the order specified by the Sorted property. If a is passed, it must be a variable into which the item's hash key will be returned. If the hash contains no objects, ^null is returned.

method Last

iterator).Last() => object
iterator).Last(a) => object
Returns the last non-null object in the hash, according to the order specified by the Sorted property. If a is passed, it must be a variable into which the item's hash key will be returned. If the hash contains no objects, ^null is returned.

method Next

iterator).Next() => object
iterator).Next(a) => object
Returns the next non-null object in the hash, according to the order specified by the Sorted property. If a is passed, it must be a variable into which the item's hash key will be returned. If the hash contains no objects, or the previously obtained object was the last one, ^null is returned. If no object has been previously obtained, this method returns the first one.

method Prev

iterator).Prev() => object
iterator).Prev(a) => object
Returns the previous non-null object in the hash, according to the order specified by the Sorted property. If a is passed, it must be a variable into which the item's hash key will be returned. if the hash contains no objects, or the previously obtained object was the first one, or no object was previously obtained, ^null is returned.

property Sorted

iterator).Sorted => boolean
iterator).Sorted = boolean
If this property is true, the iteration will proceed in alphanumeric key order. If false, the order in which objects were added will be used instead. If you modify this property, a call to Next will return the first item in the new order.