DTWAIN_ArrayFindFloat

The DTWAIN_ArrayFindFloat function searches for a DTWAIN_FLOAT value in a DTWAIN_ARRAY.

LONG DTWAIN_ArrayFindFloat (

DTWAIN_ARRAY	Array,
DTWAIN_FLOAT	Value,
DTWAIN_FLOAT	Tolerance );

Parameters

Array

DTWAIN_ARRAY to search.

Value

DTWAIN_FLOAT value to search for

Tolerance

Tolerance level to use when determining equality.

Return Values

If the function succeeds, the zero-based position of the element is returned. Otherwise -1 is returned if the element cannot be found, or another error has been encountered.

Comments

DTWAIN_ArrayFindFloat is a specialized version of DTWAIN_ArrayFind for DTWAIN_FLOAT values.

The DTWAIN_ArrayFindFloat function searches the DTWAIN_ARRAY Array, and returns the position of the first element that is equal to Value. The Tolerance level is used to determine if the value that is being compared to in the DTWAIN_ARRAY is "close enough" to the search value Value. Usually this number is a very small floating point number. To use the default tolerance level, Tolerance should be DTWAIN_FLOATDELTA (approximately 10-8 or 0.00000001).

Due to the inexact nature of floating point values, DTWAIN_FLOATS are seldom exactly equal, therefore the tolerance level is used to determine if two floating-point values are "equal". Basically if 'x' is the number being searched, and 'y' is the value in the DTWAIN_ARRAY that is being compared:

if abs(x - y) <= Tolerance, then x and y are considered "equal" (the abs( ) is the absolute value).

This function will only work for DTWAIN_ARRAY's that can store DTWAIN_FLOAT values (i.e. the DTWAIN_ARRAY was created with the DTWAIN_ARRAYFLOAT style. See DTWAIN_ArrayCreate for more information).

Example:

/* Find an element in a DTWAIN_ARRAY */

void Func( )

{

DTWAIN_ARRAY Array;

DTWAIN_FLOAT i;

DTWAIN_FLOAT Position;

DTWAIN_FLOAT SearchVal;

/* Create a DTWAIN_ARRAY with 4 elements */

Array = DTWAIN_ArrayCreate(DTWAIN_ARRAYDTWAIN_FLOAT, 4);

/* Store the values 0, 2, 4, and 6 in the DTWAIN_ARRAY */

for ( i = 0; i < 4; i++ )

DTWAIN_ArraySetAtLong( Array, i, i*2 )

/* Search for 2 */

Position = DTWAIN_ArrayFindFloat( Array, 2, DTWAIN_FLOATDELTA );

/* Position should be a 1, since the '2' was stored at Array[1] */

/* Search for 6 */

Position = DTWAIN_ArrayFindFloat( Array, 6, DTWAIN_FLOATDELTA );

/* Position should be a 3, since the '6' was stored at Array[3] */

/* Destroy the array */

DTWAIN_ArrayDestroy( Array );

}

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize