VLMATCHFLOAT(3dm)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.
Page 1
VLMATCHFLOAT(3dm)VLMATCHFLOAT(3dm)
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.
Page 2
VLMATCHFLOAT(3dm)VLMATCHFLOAT(3dm)
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.
Page 3
