collect_spec

Relational functions collect_spec

syntax

• collect_spec(spec, tree_item, selection domain unit, org_rel or condition)

definition

collect_spec(spec, ...) collects the subitems of tree_item onto the selection domain unit, configured by the spec argument instead of by the function name. It is the collect_attr_by_org_rel / collect_attr_by_cond pair with its choices made explicit, plus the collection scopes that have no named form.

The spec is a string of ;-separated words; order does not matter.

word	meaning
by_org_rel	the 4th argument is an org_rel relation, used in a lookup
by_cond	the 4th argument is a condition, used in a collect_by_cond
ref	also collect through the referred-item chain
sub	also collect from sub-containers, mirroring them in the result

One of by_org_rel / by_cond is required: the last argument is read as one or the other, and guessing would silently produce a different result. An unknown word is reported where the item is defined.

equivalences

named function	collect_spec
collect_attr_by_org_rel	collect_spec('by_org_rel', C, dom, org_rel)
collect_attr_by_cond	collect_spec('by_cond', C, dom, cond)

Prefer the named function when one exists; reach for collect_spec when you need ref or sub.

example

unit<uint32> Stops := Network/Stops;          // a reference: no sub-items of its own

container attrs := collect_spec('by_org_rel;ref', Stops, Selection, Selection/org_rel);

Without ref, Stops has nothing to collect and the call only warns. ref reaches the attributes of Network/Stops through the reference — the same chain that makes Stops/name resolve.

With by_cond the last argument is a condition on the source domain instead, exactly as collect_attr_by_cond takes it:

container attrs := collect_spec('by_cond', City, ZHCities, City/RegionCode == 200);

sub

sub mirrors a sub-container into the collected result. For a City that keeps its coordinates in a sub-container:

unit<uint32> City
{
   attribute<string> name;
   container geo { attribute<point_rd> point (City); }
}

container attrs := collect_spec('by_org_rel;sub', City, ZHCities, ZHCities/org_rel);

gives attrs/name and attrs/geo/point. Note that an attribute in a sub-container needs its domain unit spelled out — it is not a direct sub-item of the unit, so there is nothing to infer it from.

ref and sub mean exactly what they mean for select_spec; see that page for the shadowing rule and for the scopes in full.

applies to

• spec a parameter of value type string; usually a literal
• tree_item can be any tree item, but usually a unit or container
• selection domain unit a unit with a value type of the group CanbeDomainUnit
• org_rel a relation from the selection domain unit toward the domain of the collected attributes; condition a boolean attribute on that domain

since version

20.17.0

see also

• select_spec
• collect_attr_by_org_rel
• collect_attr_by_cond