Sway.utils and other helper functions

The framework contains some helper functions, mainly within the Sway.utils namespace. In particular, the Sway.utils.Dictionary() is extremely widely used within the framework.

7.1 Sway.utils.Dictionary()

The Sway.utils.Dictionary class is a dictionary/hashtable which is extremely widely used within the Sway Charts Pro framework. For example, the Sway.Instruments collection is a dictionary, and so is each Sway.Message which is sent to an OnMessage() handler.

The dictionary's properties and methods are as follows:

Object	Description
length	Property returning the number of items in the dictionary
set(key, object)	Sets a key/value pair in the dictionary
remove(key)	Removes a key/value pair from the dictionary. (Trying to remove a non-existent key is not an error; it just silently does nothing.)
get(key)	Returns a value from the dictionary based on its key, or null if the key is not present
has(key)	Tests whether a key exists in the dictionary
is(keyOrArray)	Can take either a single key as a parameter, or an array of keys. Passing a single key is simply equivalent to has(). Passing an array means "does the dictionary contain at least one of these keys?". In other words, using is() with an array does an is-any-of test.
keys()	Returns all the keys in the dictionary as an array
values()	Returns all the values in the dictionary as an array
clear()	Empties the dictionary
forEach(fn)	Iterator. See description below.

The dictionary's forEach() is similar to standard Javascript Array.forEach() except that it allows early exit, by returning a non-null from the iteration function. For example, you can scan the dictionary and terminate at the first match, avoiding unnecessary further iteration through the dictionary:

// See if there is any object in the dictionary which has some particular value

var bHasValueWithProperty = false;

myDictionary.forEach(function (key, object) {

if (object.someProperty == someValue) {

// Set flag

bHasValueWithProperty = true;

// Exit from iteration, and avoid unnecessary further looping

return true;

}

});

Any non-null return value which terminates the iteration is passed back as the return value from forEach(). Therefore, the following is possible:

// See if there is any object in the dictionary which has some particular value.

// On return, matchingObject will contain either null or the first matching item.

var matchingObject = myDictionary.forEach(function (key, object) {

if (object.someProperty == someValue) {

// Exit from iteration, and avoid unnecessary further looping.

// The non-null value becomes the return value from the forEach().

return object;

}

});

Note: it is safe to modify the contents of the dictionary during forEach() iteration. For example:

// Create a dictionary with 10 items

var x = new Sway.utils.Dictionary();

for (var i = 1; i <= 10; i++) x.set(i, i);

// Gets called 9 times because item 3 is removed on the first pass (where k = 1)

x.forEach (function (k, v) {

if (x.has(3)) x.remove(3); // Remove item 3 on first iteration

});

7.2 Sway.utils.Clone()

Sway.utils.Clone() is a simple function for doing a deep clone of an object, but excluding any functions within the object (making it safe for serialisation). The current internal implementation of Sway.utils.Clone(x) is simply JSON.parse(JSON.stringify(x)), but this may change in future if a faster alternative becomes available.

7.3 Sway.utils.IsEmpty()

Simple helper function which tests whether an object x is an empty object, {}. For example:

var bIsEmpty = Sway.utils.IsEmpty(someObject);

7.4 Sway.utils.GenerateGuid()

Sway.utils.GenerateGuid() creates an ID (32 hexadecimal characters) which is guaranteed to be unique within the current browser session, and is not guaranteed but is overwhelmingly likely to be globally unique.

7.5 Sway.utils.GenerateHash()

Sway.utils.GenerateHash(string) generates a hash of a string as a 32-bit integer. The hashing algorithm is subject to change, but is currently murmur32.

7.6 $$()

For widgets only – because scripts and UDIXes are web workers, and have no HTML document – the framework creates a $$() short-hand for accessing DOM nodes. For example:

$$("btnSave").disabled = true;

$$() is simply a short-hand alternative to document.getElementById(x), though its full functionality is slightly broader. If there is no DOM node with ID x, then $$() goes on to try document.getElementsByClassName(x). There are three possible results from getElementsByClassName():

· Empty array. $$() returns null.

· Array with single item. $$() returns that single item (not the array).

· Array with multiple items. $$() returns the array.

To put all that another way:

· If there is a single node with class=x, then $$(x) is equivalent to document.getElementsByClassName(x)[0]

· If there are multiple nodes with class=x, then $$(x) is equivalent to document.getElementsByClassName(x)