select_spec

syntax

select_spec(spec, condition)
select_spec(spec, src_tree_item, condition)

definition

select_spec(spec, …) results in a new Domain unit, configured by the spec Argument instead of by the function name. The spec is a string of ;-separated words; order does not matter and an empty spec is allowed.

The named selection functions each pin one fixed combination — select_spec reaches the same combinations, and the ones that have no name of their own.

The second form, with a src_tree_item, applies when the spec contains attr.

the spec words

word	meaning
`uint8` `uint16` `uint32` `uint64`	the Value type of the result domain; omitted, it is derived from the domain of the condition
`org_rel`	also produce an org_rel relation to the original domain
`attr`	collect the subitems of src_tree_item whose domain matches the condition
`use_org_rel`	collect those attributes through the org_rel rather than through the condition; implies `org_rel`, and requires `attr`
`ref`	when collecting, also follow the referred-item chain; requires `attr`
`sub`	when collecting, also descend into sub-containers, mirroring them in the result; requires `attr`

An unknown word is reported where the item is defined, listing what is accepted.

equivalences

named function	select_spec
select	`select_spec('', cond)`
select_uint32	`select_spec('uint32', cond)`
select_with_org_rel	`select_spec('org_rel', cond)`
select_with_attr_by_cond	`select_spec('attr', C, cond)`
select_with_org_rel_with_attr_by_cond	`select_spec('org_rel;attr', C, cond)`
select_with_attr_by_org_rel	`select_spec('use_org_rel;attr', C, cond)`

Prefer the named function when one exists: it is cacheable, whereas select_spec is resolved per instantiation. Reach for select_spec when you need ref or sub, which have no named form.

ref — collecting through a linked unit

A Unit configured as a reference to another unit — most importantly a Case parameter of a Template — has no sub-items of its own. Its attributes live on the unit it is bound to.

References are followed when a name is looked up, which is why a condition such as inStops/nTransfers resolves without trouble. They were not followed when sub-items were enumerated, so collecting found nothing and reported

no sub-items found with a domain that is compatible with the domain of the given condition

ref makes the enumeration follow the same chain the lookup follows, so the two agree:

Template StaticNetsCreator
{
   // begin case parameters
   unit<uint32> inStops;
   unit<uint32> inLinks;
   // end case parameters

   unit<uint32> TransferFromStops := select_spec('use_org_rel;attr;ref', inStops, inStops/nTransfers > 0);
}

container Case1 := StaticNetsCreator(Network/Stops, Network/Links);

Case1/TransferFromStops now carries the attributes of Network/Stops.

shadowing

If the container declares a sub-item with the same name as one further down the chain, the nearest one wins and the shadowed one is not collected — the same rule name resolution uses, so {container}/{name} and the collected attribute always refer to the same item. A name shadowed by an item that is not itself collectable is still hidden, not silently replaced by the deeper one.

sub — collecting from sub-containers

sub descends into sub-containers and mirrors their structure in the result. For

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

unit<uint32> ZHCities := select_spec('attr;sub', City, City/RegionCode == 200);

the result carries ZHCities/name, ZHCities/RegionCode and ZHCities/geo/point.

Units, templates and functions among the sub-items are not descended into; only containers are. As at the top level, sub-items whose Domain unit does not match are skipped.

An attribute inside a sub-container needs its Domain unit spelled out — attribute<point_rd> point (City) — because it is not a direct sub-item of the unit and there is nothing to infer the domain from. Without it the attribute has no domain to match and is skipped.

applies to

spec a Parameter of Value type string; usually a literal
src_tree_item can be any Tree item, but usually a Unit or Container
condition must be a boolean attribute or Subexpression resulting in boolean values

Every scope collects sub-items of the container argument. Attributes that are merely visible from it — through a Parent item or a Using namespace — are not sub-items of it and are not collected.

since version

20.17.0