**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

### DIFFERENT_LENGTHS

By default, ARRAY_EQUAL returns 0 if the two variables are arrays with different numbers of elements. Set the DIFFERENT_LENGTHS keyword to evaluate the elements of the two variables with indices valid in 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 two 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 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.

## Version History

5.4 |
Introduced |

8.4 |
Added NOT_EQUAL and QUIET keywords |

8.8 | Added DIFFERENT_LENGTHS and NAN keywords |