Selector operator in a path property
The provide operator guarantees, that the requested instance will be provided for the referenced property. I.e., an instance with the defined key will be created, when not yet existing.
Persons['P00001"].children
will provide a person with the person number (pid) P00001, i.e. it will be read or created, when not yet existing.
Typically, the provide operator is used for single reference or relationship properties in order to create required instances on the fly. Considering the development resource instances, which are linked to a documentation topic (DSC_Topic) via a resource reference (SDB_ResourceRef), one may want to generate titles for functions. Resource references and documentation topics are created on demand, i.e. you can never be sure, that they already exist. The example below shows, how this can be handled simply by using the provide operator.
The example automatically creates resource reference and topic on the path, when titles do not yet exist or are empty (!title).
// using path property
void UpdateTitle(PropertyHandle &class_ph) {
PropertyHandle functions(&class_ph, "pfunctions");
PropertyHandle title(&functions, "resource_ref[0].topic[0].definition.definition.name");
functions.ToTop();
while ( functions.Next() )
// assign function name to title if title is empty
if ( !title )
title = functions.GetString("sys_ident");
}
// using base property hierarchy -
// produces the same same result as the example above
void UpdateTitle(PropertyHandle &class_ph) {
PropertyHandle functions(&class_ph, "pfunctions");
PropertyHandle resource_ref(&functions, "resource_ref");
PropertyHandle topic(&resource_ref, "topic");
PropertyHandle title(&topic, "definition.definition.name");
functions.ToTop();
while ( functions.Next() )
if ( !resource_ref.Provide(0) )
if ( !topic.Provide(0) )
// assign function name to title if title is empty
if ( !title.IsTrue() )
title = functions.GetString("sys_ident");
}