Dictionary.add(itemDict)

---

Dictionary.add(itemDict)

This reads a Dictionary-type argument itemDict from which a key and a value are parsed.

$MyDictionary = $MyDictionary.add({apple:green}); 

Note that quotes are not needed around the key and value.

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

If key exists, key is given value value. This replaces any/all existing values for this key.

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

$MyDictionary = $MyDictionary.add({apple:fruit}); 

The key 'apple' is added and now has value 'fruit'

$MyDictionary = $MyDictionary.add({apple:green}); 

The key 'apple' now has a new value 'green'. Now assume the 'apple' key has multiple values of 'fruit;green;red':

$MyDictionary = $MyDictionary.add({apple:pie}); 

Now the value is just 'pie' because an .add() operator replaces all existing value(s).

This operator is also equivalent to:

Dictionary["key"] = "value"; 

To add an additional value(s) to existing value(s), see Dictionary.extend().

To remove a key—and any value(s) it has—from the Dictionary, there is no operator but instead the key string is deleted using a minus operator: see 'Deleting key:value pairs' here.

As from v9.5.2, the .add() operator accepts quoted strings. The following expressions are equivalent:

$MyDictionary.add({1:able}} 

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

But do not use either of the following example syntax:

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

$MyDictionary.add({"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.add({$Name(aState)+":"+$Color(aState)}); WRONG!

use:

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

Legacy form (pre-v9.5.0)

Dictionary.add(keyStr, valueStr)

This sets a keyStr to the valueStr.

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

If keyStr exists, keyStr is given value valueStr. This replaces any/all existing values for this key.

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

$MyDictionary = $MyDictionary.add("apple","fruit"); 

The keyStr 'apple' is added and now has valueStr 'fruit'

$MyDictionary = $MyDictionary.add("apple","green"); 

The keyStr 'apple' now has a new value 'green'. Now assume the 'apple' key has multiple values of 'fruit;green;red':

$MyDictionary = $MyDictionary.add("apple","pie"); 

Now the value is just 'pie' because an .add() operator replaces all existing valueStr(s).