Collections and Maps: an Overview

---

Introduction

MSBN3 includes many collections and maps objects. Every model, for example, has a ModelNodes collection that contains all the nodes of that model. Similarly, every node has a Properties map that associates property types with a property values. This overview describes the common interfaces to MSBN3 collections and maps. Sample code, in Visual Basic, for this overview is available in Samples\VB\Collections.bas.

Visualizing Collections and Maps

Suppose we have a model called aModel with three nodes. Its ModelNodes collection can be thought of as a one-column table.

aModel.ModelNodes:

Item

EngineStart

SparkPlugs

Battery

where each item in the collection is a Model object.

A map can also be thought of as a table, specifically, a two-column table. For example, suppose a node called aNode has two properties.

aNode.Properties:

KeyObjects	Item
MS_category	"fixable"
MS_cost_fix	80.00

Finally, these two views can be unified by thinking of collections as maps in which the values in the KeyObjects column are the same as those in the Item column. In other words we can think of collections also as two-column tables:

aModel.ModelNodes (as a two-column table):

KeyObjects	Item
EngineStart	EngineStart
SparkPlugs	SparkPlugs
Battery	Battery

Accessing Collection Items

Individual items in a collection can be accessed three ways: with

• an 0-based integer:

  So the expression:

aModel.ModelNodes(0)

will retrieve the first item ModelNodes.

• a keyobject

  So, if ptCostFix is a PropertyType object with name "MS_cost_fix", the expression

aNode.Properties(ptCostFix)

will retrieve 80.00, the value of this property.

• a string, the name of a key object:

  So, this expression:

aModel.ModelNodes("Battery")

will retrieve node with name "Battery". And:

aNode.Properties("MS_cost_fix")

will retrieve 80.00.

Accessing Collection KeyObjects

KeyObjects can also be accessed three ways, by using the KeyObjects(index) property of collections.

So, these three expressions:

aNode.Properties.KeyObjects(1)

aNode.Properties.KeyObjects("MS_cost_fix")

aNode.Properties.KeyObjects(ptCostFix)

all return the PropertyType object with name "MS_cost_fix".

Enumerating Items and KeyObjects

All MSBN3 collections and maps support enumeration. For example, this code will print the names of all the nodes in model aModel:

Dim node2 As MSBN3Lib.Node
For Each node2 In aModel.ModelNodes
    Debug.Print node2.Name
Next node2

And, using the KeyObjects property of the main collection,  this code will print the names of all properties and values set on aNode:

Dim aPropertyType As MSBN3Lib.PropertyType
For Each aPropertyType In aNode.Properties.KeyObjects
    Debug.Print aPropertyType.Name, aNode.Properties(aPropertyType)
Next aPropertyType

Testing Membership with ExistingKey

Suppose you wish to know if aNode has a value for the "MS_cost_observe" property type. If you use the expression:

aNode.Properties("MS_cost_observe")

but the node doesn't have that property, MSBN3 will throw an exception. Instead, you should use the collection's ExistingKey property. The expression:

aNode.Properties.ExistingKey("MS_cost_observe")

will return true only if the node has that property set.

In general, ExistingKey takes any integer, string, or object and tells if it is a valid index into the collection or map.

Creating a String from a Collection or Map with Description

Sometimes, especially when debugging, it is useful to see the whole collection. The Description property of collections creates a string based on the contents of the collection. For example,

aModel.ModelNodes.Description

is "EngineStart,SparkPlugs,Battery". and

aNode.Properties.Description

is "MS_category->fixable,MS_cost_fix->80.".

The Keys And Indexes Collections

In addition to the KeyObjects property, every collection and map also has Keys and Indexes properties. Keys is a collection of the names of the KeyObjects. Indexes is a collection of all the valid integer indexes.

So, for example, this expression will find the index integer of the model named "SparkPlugs":

aModel.ModelNodes.Indexes("SparkPlugs")

and this will find the name of the node with index integer 1

aModel.ModelNodes.Keys(1)

The elements in the Keys and Indexes collections can also be enumerated.

Collections can now be thought of as three- or four-column tables like:

KeyObjects	Keys	Indexes	Item
EngineStart	"EngineStart"	0	EngineStart
SparkPlugs	"SparkPlugs"	1	SparkPlugs
Battery	"Battery"	2	Battery

(Internally, for efficiency, KeyObjects, Keys, Indexes are implemented as different COM interfaces to the main collection.)

The Count Property and Emptying a Collection

The number of items in a collection can be found with the Count property. For example:

aModel.ModelNodes.Count

returns 3.

To empty a collection, set it A collection Count property to 0. For example:

aNode.Properties.Count = 0

removes all the properties from the a node. The Count property can only be set to 0; setting to other numbers is not allowed.

Removing and Adding Items from a Collection

The Remove method removes an item from a collection and shifts the index integer of all later items. The item to remove can be specified by index integer, keyobject, or keyobject name. For example,

aModel.ModelNodes.Remove "SparkPlugs"

removes the node with name "SparkPlugs" from the collection. So, now aModel.ModelNodes (as a three-column table):

KeyObjects Indexes Item EngineStart 0 EngineStart SparkPlugs 1 SparkPlugs Battery 2 Battery

becomes

KeyObjects Indexes Item EngineStart 0 EngineStart Battery 1 Battery

 

Note that before the Remove, the index integer of the Battery node was 2 and after it is 1.

To add an item to a collection, the Add method is used. The details of Add vary from collection to collection. For details see:

• Add (Assignment)
  

• Add (Evidence)
  

• Add (ModelNodes)
  

• Add (Models)
  

• Add (ParentNodes)
  

• Add (Properties)
  

• Add (PropertyTypes)
  

• Add (SharedDomains)
  

• Add (States)

Usually, an Add with no parameters adds a new item with a generated name to the end of the collection. For example,

aModel.ModelNodes.Add

changes aModel.ModelNodes to:

KeyObjects	Indexes	Item
EngineStart	0	EngineStart
Battery	1	Battery
NewNode_1	2	NewNode_1

Most Add methods also allow you to detail what kind of item you'd like to add to the collection. For example, with the Add for the Properties collection, you specify a PropertyType and a variant value:

aNode.Properties.Add "MS_cost_fix", 100.0

Copying Items

In some collections, you can create a new item in a collection by applying Copy to one if its items. For example, this expression will create a new node with the same parents, states, and properties, as the Battery node:

aModel.ModelNodes("Battery").Copy

Other Editing Methods

In addition to Remove and Add, some collections also support editing with Set, the collect syntax, and Move. For details see:

• Collect (Evidence)
  

• Collect (Properties)
  

• Move
  

• Set (Assignment, Evidence)
  

• Set (Properties)

Sample Code

• Samples\VB\Collections.bas.

---