tame/core/numeric/convert.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<package xmlns="http://www.lovullo.com/rater"
  xmlns:c="http://www.lovullo.com/calc"
  xmlns:t="http://www.lovullo.com/rater/apply-template"
  core="true"
  desc="Converts scalars to another type">

  <import package="../base" />

  <!-- for template applications -->
  <import package="common" export="true" />
  <import package="round" export="true" />


  <!-- even more trivial, but again, cuts down on code -->
  <template name="_scalarToAccum_" desc="Simply accumulates a scalar">
    <param name="@scalar@" desc="Scalar to accumulate" />
    <param name="@accum@" desc="Accumulator to accumulate into" />

    <!-- this is useless, but required -->
    <param name="@yields@" desc="Value to yield into, since it's required (useless)">
      <text>__accum_</text>
      <param-value name="@accum@" />
      <text>_</text>
      <param-value name="@scalar@" />
    </param>

    <param name="@type@" desc="Accumulation method">
      <text>all</text>
    </param>

    <rate yields="@yields@">
      <accumulate into="@accum@" type="@type@" />
      <c:value-of name="@scalar@" />
    </rate>
  </template>



  <template name="_ptor_" desc="Percent to rational number">
    <param name="@name@" desc="Percentage to convert" />
    <param name="@index@" desc="Index" />

    <param name="@value@" desc="Constant (instead of named value)" />
    <param name="@desc@" desc="Optional description for constant value">
      <text>Percent to convert</text>
    </param>

    <param name="@difference@" desc="Whether to perform a percent
                                     difference (default false)">
      <text>false</text>
    </param>

    <c:sum>
      <if name="@difference@" eq="true">
        <c:const value="1"
                 desc="Perform percent difference" />
      </if>

      <c:quotient>
        <if name="@name@">
          <c:value-of name="@name@" index="@index@" />
        </if>
        <unless name="@name@">
          <c:const value="@value@" type="float" desc="@desc@" />
        </unless>
        <c:const value="100" type="integer" desc="Convert to rational number" />
      </c:quotient>
    </c:sum>
  </template>


  <template name="_ptor-each_" desc="Each percent to real number">
    <param name="@name@" desc="Percentage to convert" />
    <param name="@generates@" desc="Value to generate into" />

    <param name="@difference@" desc="Whether to perform a percent
                                     difference (default false)">
      <text>false</text>
    </param>

    <rate yields="_{@generates@}">
      <c:sum of="@name@" index="k" generates="@generates@" desc="Real representation of {@name@}">
        <t:ptor difference="@difference@"
                name="@name@" index="k" />
      </c:sum>
    </rate>
  </template>


  <!--
    Yields a total percent as an integer and rational number. The integer is
    useful for displaying a total percent (e.g. for credits/surcharges) and the
    rational number is useful for using for multiplication in an equation.

    Example:

      <t:total-percent class="foo" to_int="fooPercentTotal" to_rat="fooTotal" index="k">
        <with-param name="@values@">
          <c:value-of name="fooA" index="k" />
          <c:value-of name="fooB" index="k" />
        </with-param>
      </t:total-percent>

    Let fooA = 5, fooB = -7

    will yield:
      - fooPercentTotal = -2
      - fooTotal        = 0.98
  -->
  <template name="_total-percent_" desc="Generates a total percentage as an integer and a rational number">
    <!-- for use by @values@ -->
    <param name="@index@" desc="Index variable" />

    <param name="@class@" desc="Classification match" />
    <param name="@to_int@" desc="Integer total to yield" />
    <param name="@to_rat@" desc="Rational number to yield" />

    <param name="@values@" desc="Value nodes" />

    <param name="@yields_int@" desc="Yields for integer total">
      <text>_</text>
      <param-value name="@to_int@" />
    </param>
    <param name="@yields_rat@" desc="Yields for rational total">
      <text>_</text>
      <param-value name="@to_rat@" />
    </param>


    <!-- percent total (e.g. 7 for 7%) -->
    <rate-each class="@class@" yields="@yields_int@" generates="@to_int@" index="@index@">
      <c:sum>
        <param-copy name="@values@" />
      </c:sum>
    </rate-each>

    <!-- as a rational number (to multiply by; e.g. 1.07 for 7%, 0.93 for -7%) -->
    <rate-each class="@class@" yields="@yields_rat@" generates="@to_rat@" index="k">
      <c:sum>
        <c:const value="1" desc="Relative percent" />
        <t:ptor name="@to_int@" index="k" />
      </c:sum>
    </rate-each>
  </template>


  <!--
    This template is useful for, say, when a coverage is partially included, but
    additional coverage may be purchased. For example, if 10% of coverage X is
    included, but you can purchase more Y if 10% is insufficient, then we can
    simply reduce coverage Y by 10% of coverage X.

    If the initial value is insufficient, then the value 0 will be produced.
  -->
  <template name="_percent-reduction_" desc="Reduces a set of values by a percentage of another set of values">
    <param name="@index@" desc="Value index" />

    <param name="@reduce@"    desc="Vector to reduce values of" />
    <param name="@percentof@" desc="Vector to reduce values by a percentage of" />
    <param name="@percent@"   desc="Percent reduction (as a float)" />
    <param name="@minval@"    desc="Minimum value to reduce by (optional)" />
    <param name="@condition@" desc="Boolean conditions (vector for each index) under which reduction should be applied" />

    <param name="@desc@" desc="Optional description">
      <text>Percent to reduce by</text>
    </param>

    <param name="@label@" desc="Label for max() application">
      <text>Reduced </text>
      <param-value name="@reduce@" />
      <text> by </text>
      <param-value name="@percent@" />
      <text>*</text>
      <param-value name="@percentof@" />
      <text> (cannot fall below 0)</text>
    </param>


    <c:apply name="max" label="@label@">
      <!-- if the reduction produces a value less than 0, then simply return 0 -->
      <c:arg name="max1">
        <c:const value="0" type="float" desc="0 will be returned if the reduction is too great" />
      </c:arg>

      <c:arg name="max2">
        <c:sum>
          <c:value-of name="@reduce@" index="@index@" label="Initial value" />

          <c:let>
            <c:values>
              <c:value name="reduce" type="float" desc="Value to reduce by, should condition be met">
                <c:product>
                  <c:const value="@percent@" type="float" desc="@desc@" />
                  <c:value-of name="@percentof@" index="@index@" />
                </c:product>
              </c:value>
            </c:values>

            <t:negate>
              <c:product label="Conditional reduction">
                <if name="@condition@">
                  <c:when name="@condition@" index="@index@">
                    <c:eq>
                      <c:value-of name="TRUE" />
                    </c:eq>
                  </c:when>
                </if>

                <if name="@minval@">
                  <c:apply name="max" max1="reduce">
                    <c:arg name="max2">
                      <c:const value="@minval@" type="float" desc="Minimum value to reduce by" />
                    </c:arg>
                  </c:apply>
                </if>
                <unless name="@minval@">
                  <c:value-of name="reduce" label="Value to reduce by" />
                </unless>
              </c:product>
            </t:negate>
          </c:let>
        </c:sum>
      </c:arg>
    </c:apply>
  </template>


  <template name="_percent-of-set_" desc="Returns the percent of a set of given values">
    <param name="@class@"     desc="Class match" />
    <param name="@of@"        desc="Vector of values to take the percent of" />
    <param name="@percent@"   desc="Percent reduction (as a float)" />
    <param name="@generates@" desc="Value to generate" />

    <param name="@yields@" desc="Yield">
      <param-value name="@generates@" />
      <text>Total</text>
    </param>


    <rate-each class="@class@" yields="@yields@" generates="@generates@" index="k">
      <c:apply name="round">
        <c:arg name="roundval">
          <c:apply name="max">
            <!-- if the reduction produces a value less than 0, then simply return 0 -->
            <c:arg name="max1">
              <c:const value="0" type="float" desc="0 will be returned if the reduction is too great" />
            </c:arg>

            <c:arg name="max2">
              <c:product label="Percent value">
                <c:const value="@percent@" type="float" desc="Percent to reduce by" />
                <c:value-of name="@of@" index="k" label="Value to take percentage of" />
              </c:product>
            </c:arg>
          </c:apply>
        </c:arg>
      </c:apply>
    </rate-each>
  </template>


  <!--
    Map values falling within adjacent intervals

    Interval endpoints are defined using `_endpoint_` nodes.  The
    first interval is defined as [-∞,@start@), and the last endpoint
    as (end,∞], where `end` is the value of the final `_endpoint_`.
    The default maps for these two implicit intervals default to 0,
    but may be changed with, respectively, @low@ and @high@.

    Permitted children:
      - _endpoint_* - Endpoint definition.
  -->
  <template name="_map-interval_"
            desc="Map adjacent, closed intervals to scalars">
    <param name="@values@" desc="Interval definitions" />
    <param name="@name@"   desc="Reference value" />

    <param name="@start@"
           desc="Left endpoint of first interval (constant)" />

    <param name="@index@"
           desc="Reference value index">
      <text></text>
    </param>

    <param name="@low@"
           desc="Default value when less than @start@">
      <text>#0</text>
    </param>
    <param name="@lowindex@"
           desc="Low value index">
      <text></text>
    </param>

    <param name="@high@"
           desc="Default value when greater than final endpoint value">
      <text>#0</text>
    </param>
    <param name="@highindex@"
           desc="High value index">
      <text></text>
    </param>


    <c:let>
      <!-- c:when does not support shorthand constants (yet); this is
           a workaround -->
      <c:values>
        <c:value name="__intval"
                 type="float"
                 desc="Interval reference value">
          <c:value-of name="@name@" index="@index@" />
        </c:value>
      </c:values>


      <c:cases>
        <c:case>
          <c:when name="__intval">
            <c:lt>
              <c:const value="@start@"
                       type="float"
                       desc="First interval left endpoint" />
            </c:lt>
          </c:when>

          <c:value-of name="@low@" index="@lowindex@" />
        </c:case>

        <param-copy name="@values@" />

        <c:otherwise>
          <c:value-of name="@high@" index="@highindex@" />
        </c:otherwise>
      </c:cases>
    </c:let>
  </template>


  <!--
    Adjacent endpoint definition

    A value that falls within range of the associated interval will be
    mapped to the value @map@.

    The first endpoint defined is the right endpoint of the interval
    defined by [start,@value@], where `start` is defined by the parent
    `_map-interval_`.

    All other endpoints define the interval (prev,@value@].
  -->
  <template name="_endpoint_"
            desc="Define an interval endpoint for _map-interval_">
    <param name="@value@"
           desc="Right endpoint of previous interval" />
    <param name="@map@"
           desc="Value to which interval is mapped" />

    <param name="@mapindex@"
           desc="Map value index">
      <text></text>
    </param>


    <c:case>
      <c:when name="__intval">
        <c:lte>
          <c:const value="@value@"
                   type="float"
                   desc="Previous interval right endpoint" />
        </c:lte>
      </c:when>

      <c:value-of name="@map@"
                  index="@mapindex@" />
    </c:case>
  </template>
</package>