vlmatchfloat(3dm)

NAME
     vlMatchFloat, vlMatchFraction, vlFractionCount, vlMatchFractionInList,
     vlFractionList - VL fraction list utility functions

SYNOPSIS
     #include <dmedia/vl.h>

     VLBoolean vlMatchFloat (
         double given              /* in: the floating point value */,
         VLFractionRange *ranges   /* in: the range list to compare with */,
         int nranges               /* in: the number of ranges in the list */,
         VLFraction *lower         /* out: the closest lower fraction */,
         VLFraction *higher        /* out: the closest higher fraction */
     );
     VLBoolean vlMatchFraction (
         VLFraction *given         /* in: the fraction to compare */,
         VLFractionRange *ranges   /* in: the range list to compare with */,
         int nranges               /* in: the number of ranges in the list */,
         VLFraction *lower         /* out: the closest lower fraction */,
         VLFraction *higher        /* out: the closest higher fraction */
     );
     int vlFractionCount (
         VLFractionRange *ranges,
         int nranges
     );
     VLBoolean vlMatchFractionInList (
         VLFraction *given      /* in: the fraction to find */,
         VLFraction *ranges          /* in: the list to search */,
         int count                 /* in: length of list */,
         VLFraction *lower         /* out: nearest lower fraction */,
         VLFraction *higher        /* out: nearest higher fraction */,
         int *index_return         /* out: index of lower */
     );
     VLFraction * vlFractionList(
         VLFractionRange *range ,
         int nranges ,
         int *length_return
     );

PARAMETERS
     given          Specifies the fraction to be checked.  In the case of
                    vlMatchFloat it is a double, and in the others it is a
                    pointer to a fraction.

     ranges         Specifies the fraction range list to be compared against.

     nranges        Specifies the number of fraction ranges in the list.

     lower          Returns the nearest lower or equivalent fraction in the
                    range.
     higher         Returns the nearest higher or equivalent fraction in the
                    range.

     index_return   Returns the index of lower.

DESCRIPTION
     If successful, vlMatchFraction and vlMatchFloat return TRUE if given is
     numerically equal to a fraction in one of the fraction ranges in ranges,
     in which case lower and higher are returned numerically equal to given,
     with the smallest values for numerator and denominator within range.  For
     example, if given is 22/33, lower and higher could be 2/3 even if 22/33
     is also in range.

     vlMatchFraction and vlMatchFloat return FALSE otherwise. If given is
     between the highest and lowest fractions in all the fraction ranges in
     ranges, then lower is the closest fraction in ranges of less value and
     higher is the closest fraction in ranges of greater value.  If given is
     below the lowest fraction in ranges, both lower and higher are that
     lowest fraction, while if above both are the highest.

     One use of this function is to make sure a source and drain match
     according to the VL_SIZE control ranges, so that the size of the window
     can match the available ranges.

     In the case of vlMatchFloat the fraction is limited in precision, and may
     not match fractions with denominators with ranges greater than 10,000
     elements.

     vlMatchFractionInList returns TRUE if given is numerically equal to a
     fraction in list, in which case lower and higher are both some fraction
     that is numerically equivalent to given.

     vlMatchFractionInList returns FALSE otherwise.  If given is between the
     highest and lowest fractions in list, then lower is the closest fraction
     of less value and higher is the closest fraction of greater value.  If
     given is below the lowest fraction in list, both lower and higher are
     that lowest fraction ( index_return is 0).  If given is above the highest
     fraction in list, both lower and higher are that highest fraction
     (index_return is count - 1).

     vlFractionList returns a list of fractions, with 0 occurring at most
     once.  The list is in numerical order, least first, with numerically
     equivalent fractions in no particular order.

     This function is intended for use with small fraction ranges, such as may
     be found in the VL_RATE control description.  Fraction ranges in the
     ranges of VL_WINDOW controls or control structures can be too large for
     this function, which allocates the memory for the list.  If in doubt, use
     vlFractionCount to see how big the list will be before using this
     function.
     To free the data returned by this function, use free(3C).

     vlFractionCount returns the number of fractions in the list of fraction
     ranges, which can be used to determine whether to use vlFractionList,
     above.

     In all functions, a value of FALSE indicates an error.