This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

Dictionary.add(itemDict)


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

 Function  [other Function type actions]

 Item  [operators of similar scope]

 Dictionary, Set & List operations  [other Dictionary, Set & List operations operators]

 Baseline

 9.5.0


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).