BandMap

A BandMap is a structure to map a numerical value to one of a set of non-overlapping bands of values and hence to attributes of that band (? is there an established name for this structure which is an ordinal to nominal map?)

A bandMap can be used to model such structures as salary scales, the windspeeds on the Beaufort Scale, honours classification and bulk discounts.

There are a number of ways a bandMap can be implemented - by both min and max for each band with no band sequencing, or by just the max or min of the band with bands in sequence. The later removes the redundancy of matching max and min on adjacent bands. Here I've chosen to represent a band by its minimum value which defines an interval closed at the lower end, open at the upper end. The highest band includes infinity. Values below the lowest limit are mapped to null.

A band is required to have an attribute 'min' castable to xs:decimal, and may have any other attributes or child elements. Bands must be in ascending order of min. Although an XML Schema could go some way to defining a valid bandMap, a better language would be Schematron, but that is not yet integrated into eXist. In this example, the validation is performed by an XQuery function.

Chris Wallace (: functions to define the behaviour of a BandMap structure :) declare function local:band-for($bandmap,$v as xs:decimal ) { ($bandmap/band[ $v >= xs:decimal(@min) ])[last()] }; declare function local:is-bandMap($bandmap) as xs:boolean { (: invariant for a bandMap :) (: there are at least 2 band elements :) count($bandmap/band) >= 2 and (: all band elements have an attribute 'min' castable to xs:decimal :) (every $band in $bandmap/band satisfies $band/@min castable as xs:decimal ) and (: the band mins are strictly ascending :) (every $i in (1 to count($bandmap/band) -1 ) satisfies (xs:decimal($bandmap/band[$i]/@min) < xs:decimal($bandmap/band[$i + 1]/@min)) ) }; declare function local:safe-band-for($bandmap, $v) { (: wrapper for local:band-for which checks pre-conditions and post-conditions, returning an error if a violation has occured :) if ( local:is-bandMap($bandmap) and $v castable as xs:decimal and xs:decimal($v)>= xs:decimal( $bandmap/band[1]/@min)) then let $band := local:band-for($bandmap,$v) return if ($band = $bandmap/band and xs:decimal($v) >= xs:decimal($band/@min) and (every $higher in $bandmap/band[. is $band]/following-sibling::band satisfies xs:decimal($v) < xs:decimal($higher/@min) ) and (every $lower in $bandmap/band[. is $band]/preceding-sibling::band satisfies xs:decimal($v) > xs:decimal($lower/@min) ) ) then $band else <error>Post-condition failed</error> else <error>Pre-condition failed</error> }; (: define a Band map from waiting times to colours :) declare variable $wait := <bandMap> <band min="0" colour="red"/> <band min="6" colour="orange"/> <band min="10" colour="green"/> </bandMap> ; Compute band colour from 0 to 12

for $i in (0 to 12)
return string(local:band-for($wait,$i)/@colour)

red red red red red red orange orange orange orange green green green Check return 12 string(local:band-for($wait,12)/@colour) green Check return below min is null string(local:band-for($wait,-1)/@colour) Check that $wait is a valid bandSet local:is-bandMap($wait) true Check assertion fails if min not in order

let $bad :=
<bandMap>
   <band min="0" colour="black"/>
  <band min="15" colour="red"/>
  <band min="10" colour="orange"/>
  <band min="999999" colour="green"/>
</bandMap>
return
 local:is-bandMap($bad)

false Check assertion fails if not enough bands

let $bad :=
<bandMap>  
   <band min="0" colour="black"/>
</bandMap>
return
 local:is-bandMap($bad)

false Check assertion fails if each band does not have min attribute

let $bad :=
<bandMap>  
   <band min="0" colour="black"/>
   <band max="15" min='10' colour="red"/>
   <band min="10" colour="orange"/>
   <band max="999999" colour="green"/>
</bandMap>
return
 local:is-bandMap($bad)

false Check assertion fails if a band min is not castable to xs:decimal

let $bad :=
<bandMap>  
   <band min="0" colour="black"/>
   <band min="15" colour="red"/>
   <band min="ten" colour="orange"/>
   <band min="999999" colour="green"/>
</bandMap>
return
 local:is-bandMap($bad)

false Use bandMap for the Beaufort scale - just force 0 to 4 to return the wind force if the wind speed is 7 knots

let $beaufort :=
<bandMap>  
   <band min="0" force="0">Calm</band>
   <band min="1" force="1">Light airs</band>
   <band min="4" force="2">Light Breeze</band>
   <band min="7" force="3">Gentle Breeze</band>
   <band min="11" force="4">Moderate Breeze</band>
</bandMap>
return
 local:band-for($beaufort,7)/text()

Gentle Breeze Check safe access with valid pre and post conditions local:safe-band-for($wait,5) Check safe access with valid pre and post conditions local:safe-band-for($wait,7) Check safe access with valid pre and post conditions local:safe-band-for($wait,10) Check safe access with invalid pre-condition

let $bad :=
<bandMap>  
   <band min="0" colour="black"/>
   <band min="15" colour="red"/>
   <band min="ten" colour="orange"/>
   <band min="999999" colour="green"/>
</bandMap>
return
 local:safe-band-for($bad,5)

Pre-condition failed