ARRAY_EQUAL

Tip: See also the IDL_Variable::Equals and IDL_Variable::HasValue methods, which provide similar functionality but with an object-oriented interface.

The ARRAY_EQUAL function is a fast way to compare data for equality in situations where the index of the elements that differ are not of interest. This operation is much faster than using TOTAL(X ne Y), because it stops the comparison as soon as the first inequality is found, an intermediate array is not created, and only one pass is made through the data.

Arrays may be compared to scalars, in which case each element in the array is compared to the scalar. For two arrays to be equal, they must have the same number of elements. If the types of the operands differ, the type of the least precise is converted to that of the most precise, unless the NO_TYPECONV keyword is specified to prevent it. This function works on all numeric types, strings, pointer references, and object references. In the case of pointer and object references, ARRAY_EQUAL compares the references (which are long integers), not the heap variables to which the references point.

Tip: If you are comparing an array to a scalar, you should make sure that the scalar has the same data type as the array. Otherwise, if the scalar is a more precise data type, then ARRAY_EQUAL will convert the entire array to that type before doing the comparison.

Examples

; Return True (1) if all elements of a are equal to a 0 byte:

IF ARRAY_EQUAL(a, 0b) THEN ...

; Return True (1) if all elements of a are equal all elements of b:

IF ARRAY_EQUAL(a, b) THEN ...

; Returns True

ARRAY_EQUAL([1.0, 2.0, 3.0], [1.1, 2.1, 2.9], TOLERANCE=0.15)

Syntax

Result = ARRAY_EQUAL( X , Y, /DIFFERENT_LENGTHS, /NAN, /NOT_EQUAL, /NO_TYPECONV, /QUIET, TOLERANCE=value )

Return Value

Returns 1 (true) if, and only if, all elements of X are equal to Y; returns 0 (false) at the first instance of inequality.

Arguments

X

The first variable to be compared. X may be an array or a scalar.

Y

The second variable to be compared. Y may be an array or a scalar.

Keywords

DIFFERENT_LENGTHS

By default, ARRAY_EQUAL returns 0 if the two variables are arrays but have a different number of elements. Set the DIFFERENT_LENGTHS keyword to evaluate only the first n elements, where n is the length of the smaller array.

Note: The ARRAY_EQUAL function uses 1-D indexing when traversing the variables, so comparing multidimensional arrays will not use multidimensional subsetting.

NAN

The definition of NaN is that it is a floating point value not equal to any other number, including another NaN. By default, ARRAY_EQUAL follows this definition, returning 0 if the two variables have NaN values at the same indices and are otherwise equal. Set the NAN keyword to treat NaN values as being equal.

NOT_EQUAL

By default, ARRAY_EQUAL determines if every element of the two variables are equal. Set the NOT_EQUAL keyword to determine if every element of the two variables are not equal.

Tip: The NOT_EQUAL keyword helps to ensure that an array does not contain a certain value. If ARRAY_EQUAL with /NOT_EQUAL returns 1 (true) then you know that your array does not contain that value. If it returns 0 (false) then you know that the value exists somewhere within the array.

NO_TYPECONV

By default, ARRAY_EQUAL converts operands of different types to a common type before performing the equality comparison. Set NO_TYPECONV to disallow this implicit type conversion. If NO_TYPECONV is specified, operands of different types are never considered to be equal, even if their numeric values are the same.

QUIET

By default, ARRAY_EQUAL will throw errors or warnings if the data types do not match and one of the variables cannot be converted to the other type. For example, if you try to compare 5.0 with "abc" or compare an object or pointer to any other type then IDL will issue an error. Set the QUIET keyword to quietly return 0 (false) in all cases where the data cannot be converted.

TOLERANCE

By default, ARRAY_EQUAL will return true if the corresponding elements in each operand are exactly equal. Set the TOLERANCE keyword to a non-zero number to instead treat values as being equal if they are within the tolerance value from each other. If the type of the tolerance variable is not the same as the input arguments, it will be converted to the appropriate type. For each pair of elements, X_i and Y_i, the pair is considered equal if |X_i − Y_i| <= |T|, where |T| is the absolute value of the tolerance.

Note: The TOLERANCE keyword is not allowed for input arguments of type string, pointer reference, or object reference.

Note: Setting TOLERANCE=0 is the same as not specifying the keyword.

Note: If the NOT_EQUAL keyword is set, then ARRAY_EQUAL will return true only if the absolute value of the difference between each of the corresponding elements is greater than the tolerance value.

Version History

5.4	Introduced
8.4	Added NOT_EQUAL and QUIET keywords
8.8	Added DIFFERENT_LENGTHS and NAN keywords
8.8.3	Added TOLERANCE keyword