IDL

ARRAY_EQUAL

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(A NE B), 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 ...

Syntax


Result = ARRAY_EQUAL( Op1 , Op2, /NOT_EQUAL, /NO_TYPECONV, /QUIET )

Return Value


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

Arguments


Op1

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

Op2

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

Keywords


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 is useful if you want to make sure that an array does not contain a certain value. If ARRAY_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 don't 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.

Version History


5.4

Introduced

8.4

Added NOT_EQUAL and QUIET keywords

See Also


WHERE, IDL_Variable::Equals, IDL_Variable::HasValue

Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions