-
Notifications
You must be signed in to change notification settings - Fork 1
select_spec
Selection functions select_spec
- select_spec(spec, condition)
- select_spec(spec, src_tree_item, condition)
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.
| 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.
| 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.
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.
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 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; }
}
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.
- 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.
20.17.0
GeoDMS ©Object Vision BV. Source code distributed under GNU GPL-3. Documentation distributed under CC BY-SA 4.0.