Name

curvematch — Return a reference to curve definition that fully or partially matches to the provided arguments.

Syntax

curvematch(split, args...)
              

The CURVEMATCH function has the following argument:

split

A character that is used to split the curve labels in to parts that are then matched against the provided arguments.

args...

One or more arguments that are to be matched against the split components of the curve labels.

Description

Retrieve a curve element using a series of arguments that can partially or fully match with the curve label. Each curve is examined in sequence in the order in which it was read in to the MatrixBuilder, and the first curve with a matching label is returned.

Each curve label being examined is first split in to component parts using the split character as a separator. The arguments are compared to the curve label components, and matches occur when the values are equal when tested with a case insensitive string comparison, or if the component part from the curve label is '?'. The first occurring curve where there is a match with all components is returned.

This method may be used to perform hierarchical pattern matching where exactly matching curves are used when available, and otherwise strata-based curves are used as a back up. To use this technique include the most specific curves first in the curve file, and the generic curves in later positions in the input file. Multiple generic curves with varying degrees of specificity may be used.

This function only operates in the context of the Matrix Builder.

If no curve can be found that matches to the pattern then an undefined attribute exception will occur. If the 'ignoremissing' condition has been set to true then the function will return a zero value curve. Otherwise, an error condition will be raised and the Matrix Builder will terminate.

Examples

Formula

Description

Result

curvematch(':', au, siteclass, silv, spp)

Search the curve library for an element with a label of 'au:siteclass:silv:spp' (where the arguments names have been substituted with the appropriate values). Return the first matching curve, accepting curves with component part values of '?' as also matching.Curve

curvematch(':', 'pjmx1', '2', 'lfn', 'pj') where the curve library includes the following labels:

 'pjmx1:1:plnt:pj'
 'pjmx1:2:plnt:pj'
 'pjmx1:2:plnt_thin:pj'
 'pjmx1:2:?:pj'
 'pjmx1:?:?:pj'
The function will return the curve 'pjmx1:2:?:pj' which is the first label that makes a partial match to the arguments that have been provided.Curve 'pjmx1:2:?:pj'