NestedWithin Property
      
 

Description

The feature index of the surrounding region if any.

Property type

A Variant value.  

Syntax

object.NestedWithin([Selector])

The NestedWithin Property syntax has these parts:

PartDescription
objectAn expression evaluating to an object of type McRegions.
SelectorOptional. A Variant value.

An empty variant, a single negative value, a single index value, or an array of zero or more index values (negative index values are legal but will be ignored).

If the Selector argument is a non-negative scalar value, then feature index of any surrounding region of the indicated feature from the collection is exposed as a scalar Long value.

If the Selector argument is missing, or any negative scalar value, then the feature index of any surrounding region of all features are returned as an array of Long values. The number of elements in the array will be equal to the Count property. This is the default way that NestedWithin is exposed.

If Selector is an array, then zero or positive values are treated as indices into the features collection, negative values are legal but ignored. In this case, the feature index of any surrounding region will be returned as an array of Long values equal to the length of the number of non-negative elements in the Selector array. Index values greater or equal to the Count property are illegal.

Remarks

A nested region feature is one whose boundary is enclosed by another feature's boundary. The enclosing feature is the “nesting parent”, while the enclosed feature is a “nested child”. A feature may have at most one nesting parent (which may in turn have its own nesting parent), but may have from zero to many nested children. The measurements mRgnNestingDepth, miRgnNestedWithinIndex, mRgnNestedChildrenCount and mvRgnNestedChildIndices expose aspects of the nesting relationships (e.g., the miRgnNestedWithinIndex measurement is basically a copy of the NestedWithin property).

A nested feature is not the same as a “hole”. The concept of a “hole” is one inherently related to a bit mask, or “blob”, representation of regions (see Holes).

The property is exposed as either a scalar or array of Long feature index values. For outermost features (ones that have no nesting parent), the NestedWithin feature index is returned as -1.

Nesting is based on boundary polygon computations where it is assumed that boundaries are either completely enclosed or not enclosed at all. For regions that overlap without being completely nested, the nesting relationship is ambiguous: either feature may be considered the parent or they may be considered not nested at all.