|
DTWAIN_RangeExpand |
Top Previous Next |
|
The DTWAIN_RangeExpand function generates all of the values defined by a DTWAIN_RANGE
DTWAIN_BOOL DTWAIN_RangeExpand (
Parameters Range A valid DTWAIN_RANGE type.
pArray A pointer to a DTWAIN_ARRAY (LPDTWAIN_ARRAY) that will contain the expanded range values on return.
Return Values If the function succeeds, TRUE is returned pArray contains the expanded denoting the expanded range is returned. If the function fails, FALSE is returned.
Comments The DTWAIN_RangeExpand function generates (expands) all of the numbers defined by the DTWAIN_RANGE Range, and returns the numbers in the pointer to the DTWAIN_ARRAY, pArray.
Range expansion is the act of taking a range and generating all of the numbers that the range defines. The minimum, maximum, and step sizes determine the expanded numbers. For example if the DTWAIN_RANGE has the following characteristics:
Minimum Value = -10 Maximum Value = 10 Step size = 2
The expanded range will consist of the following values
-10, -8, -6, -4, -2, 0, 2, 4, 6, 8, 10
In the example above, if the DTWAIN_RANGE is defined as above (-10 is min., 10 is max., with a step of 2) the returned DTWAIN_ARRAY will store all of the expanded values.
Note: Care must be taken in that the DTWAIN_RANGE may define many values. For example, a DTWAIN_RANGE defined as -1000.0 min, 1000.0 max, with a step size of 0.1, will generate a DTWAIN_ARRAY that will hold over 20,000 values! The DTWAIN_RangeExpand can be very memory intensive if not careful! The DTWAIN_RangeGetCount can be used to get the count of the total number of expanded values before attempting to call DTWAIN_RangeExpand.
If only a few values are required from an expanded range, use the DTWAIN_RangeGetExpValue function instead, since the DTWAIN_RangeGetExpValue function does not expand the range in memory.
Even though all DTWAIN_ARRAYs are destroyed by the call to DTWAIN_SysDestroy, the programmer should destroy the returned DTWAIN_ARRAY using DTWAIN_ArrayDestroy if it is no longer needed (because of the memory issues defined above).
Example:
DTWAIN_ARRAY Expanded; DTWAN_RANGE Range; //... // Expand range into "Expanded" - Note the address of the DTWAIN_ARRAY is used for Expanded DTWAIN_RangeExpand(Range, &Expanded);
. TWAIN State Transitions None.
Prerequisite Function Call(s)
See Also |