Dictionary.extend(itemDict)

---

Dictionary.extend(itemDict)

This reads a Dictionary-type argument itemDict from which a key and a value are parsed. It adds the value string to the value(s) of a key.

If key does not exist, that key is created with a value of value.

If key exists, value is appended to key's existing value(s).

Assume $MyDictionary has no 'pear' key. Example:

$MyDictionary = $MyDictionary.extend({pear:fruit}); 

The key 'pear' is added and now has value 'fruit'. Next:

$MyDictionary = $MyDictionary.extend({pear:green}); 

The key 'pear' now has an additional new value 'green', but the overall value is now a list and the key:value pair is pear:fruit;green.

To set the new valueStr so it replaces all existing value(s) see Dictionary.add().

Note that quotes are not used around either/both the keyStr and valueStr. As from v9.5.2, the .extend() operator accepts quoted strings. The following expressions are equivalent:

$MyDictionary.extend({1:able}} 

$MyDictionary.extend("{1:able}"} 

But do not use either of the following example syntax:

$MyDictionary.extend({"1:able"}} WRONG!

$MyDictionary.extend({"1":"able"}} WRONG!

Dictionary.extend(keyStr, valueStr)

This adds the valueStr string to the value(s) of a keyStr.

If keyStr does not exist, that key is created with a value of valueStr.

If keyStr exists, valueStr is appended to keyStr's existing value(s).

Assume $MyDictionary has no 'pear' keyStr. Example:

$MyDictionary = $MyDictionary.extend("pear","fruit"); 

The keyStr 'pear' is added and now has valueStr 'fruit'. Next:

$MyDictionary = $MyDictionary.extend("pear","green"); 

The keyStr 'pear' now has an additional new valueStr 'green', but the overall value is now a list and the key:value air is pear:fruit;green.

To set the new valueStr so it replaces all existing value(s) see Dictionary.add().

Dictionary.extend(dictStr)

From v9.5.0, the Dictionary.extend() operator takes a single argument, a dictionary—using the new {} syntax of key:pair elements which will extend the current elements.

$MyDictionary = $MyDictionary.extend({pear:green}); 

Note that quotes are not used around either/both the keyStr and valueStr. As from v9.5.2, the .extend() operator accepts quoted strings. The following expressions are equivalent:

$MyDictionary.extend({1:able}} 

$MyDictionary.extend("{1:able}"} 

But do not use either of the following example syntax:

$MyDictionary.extend({"1:able"}} WRONG!

$MyDictionary.extend({"1":"able"}} WRONG!

Using offset addresses within itemDict

Either the keyStr or the valueStr may need to be calculated variable, for instance the valueStr might need to be the value of $MyString("Some note") or in a loop, $MyString(loopVar). These cannot be resolved within the .add() operator but itemDict can be a variable. Thus, in a loop, rather than:

vDict = vDict.extend({$Name(aState)+":"+$Color(aState)}); WRONG!

use:

	vList.each(aState){
		// Dict.extend() can't resolve attribute offset value
		// so store the complete string in a string
		// variable and pass a single var argument to .extend()
		var:string vPair = $Name(aState)+":"+$Color(aState);
		vDict = vDict.extend({vPair});
	};