isequal

Determine array equality

Syntax

tf = isequal(A,B)

tf = isequal(A1,A2,...,An)

Description

tf = isequal(A,B) returns logical 1 (true) if A and B are equivalent; otherwise, it returns logical 0 (false). See the Input Arguments section for a definition of equivalence for each data type. NaN (Not a Number), NaT (Not a Time), undefined categorical elements, and <missing> values are considered to be unequal to other elements, as well as themselves.

To treat NaN, NaT, <undefined>, and <missing> values as equal to other such values, use isequaln.

tf = isequal(A1,A2,...,An) returns logical 1 (true) if all the inputs are equivalent.

Examples

Compare Two Numeric Matrices

Create two numeric matrices and compare them for equality.

A = zeros(3,3)+1e-20;
B = zeros(3,3);
tf = isequal(A,B)

tf = logical
   0

The function returns logical 0 (false) because the matrices differ by a very small amount and are not exactly equal.

Compare Two Structures

Create two structures and specify the fields in a different order.

A = struct('field1',0.005,'field2',2500);
B = struct('field2',2500,'field1',0.005);

Compare the structures for equality.

tf = isequal(A,B)

tf = logical
   1

Even though the ordering of the fields in each structure is different, isequal treats them as the same because the values are equal.

Comparing Numeric Values with Special Nonnumeric Values

Compare the logical value true to the double integer 1.

isequal(true,1)

ans = logical
   1

Notice that isequal does not consider data type when it tests for equality.

Similarly, compare 'A' to the ASCII-equivalent integer, 65.

isequal('A',65)

ans = logical
   1

The result is logical 1 (true) since double('A') equals 65.

Compare Vectors Containing NaN Values

Create three vectors containing NaN values.

A1 = [1 NaN NaN];
A2 = [1 NaN NaN];
A3 = [1 NaN NaN];

Compare the vectors for equality.

tf = isequal(A1,A2,A3)

tf = logical
   0

The result is logical 0 (false) because isequal does not treat NaN values as equal to each other.

Compare Two Datetime Values

Determine if midnight on January 13, 2013, in Anchorage, Alaska, is equal to 11 AM on the same date in Cairo.

t1 = datetime(2013,1,13,0,0,0,'TimeZone','America/Anchorage');
t2 = datetime(2013,1,13,11,0,0,'TimeZone','Africa/Cairo');
tf = isequal(t1,t2)

tf = logical
   1

Add 8 months to the date, and compare the datetime values for equality.

t1 = datetime(2013,9,13,0,0,0,'TimeZone','America/Anchorage');
t2 = datetime(2013,9,13,11,0,0,'TimeZone','Africa/Cairo');
tf = isequal(t1,t2)

tf = logical
   0

The datetime values are no longer equal since Cairo does not observe daylight saving time.

Compare Character Vector to String Scalar

Even though the sizes and data types are different, isequal returns logical 1 (true) when comparing a character vector and string scalar that contain the same sequence of characters.

isequal("foo",'foo')

ans = logical
   1

Input Arguments

A,B — Inputs to be compared (as separate arguments)

arrays

Inputs to be compared, specified as arrays.

In some cases, the types of the inputs do not have to match:

• Numeric inputs are equivalent if they are the same size and their contents are of equal value. The test compares real and imaginary parts of numeric arrays separately.

• Tables, timetables, structures, and cell arrays are equivalent only when all elements and properties are equal.

• String scalars and character vectors containing the same sequence of characters are equivalent.

• A categorical value is equivalent to a string scalar or character vector that names the same category.

• A datetime value is equivalent to a string scalar or character vector that represents the same point in time.

• A duration value is equivalent to a string scalar or character vector that represents the same length of time.

Some data type comparisons have special considerations involving metadata. If the inputs are all:

• Structures — Fields need not be in the same order as long as the contents are equal.

• Ordinal categorical arrays — Must have the same sets of categories, including their order.

• Categorical arrays that are not ordinal — Can have different sets of categories, and isequal compares the category names of each pair of elements.

• Datetime arrays — isequal ignores display format when it compares points in time. If the arrays are all associated with time zones, then isequal compares the instants in time rather than the clockface times (for example, 01-May-2018 09:00:00 EDT is the same instant as 01-May-2018 06:00:00 PDT, so isequal returns true even though the clockface times of 9:00 and 6:00 differ).

• Objects — isequal returns logical 1 (true) for objects of the same class with equal property values.

A1,A2,...,An — Series of inputs to be compared (as separate arguments)

arrays

Series of inputs to be compared, specified as arrays.

In some cases, the types of the inputs do not have to match:

• Numeric inputs are equivalent if they are the same size and their contents are of equal value. The test compares real and imaginary parts of numeric arrays separately.

• Tables, timetables, structures, and cell arrays are equivalent only when all elements and properties are equal.

• String scalars and character vectors containing the same sequence of characters are equivalent.

• A categorical value is equivalent to a string scalar or character vector that names the same category.

• A datetime value is equivalent to a string scalar or character vector that represents the same point in time.

• A duration value is equivalent to a string scalar or character vector that represents the same length of time.

Some data type comparisons have special considerations involving metadata. If the inputs are all:

• Structures — Fields need not be in the same order as long as the contents are equal.

• Ordinal categorical arrays — Must have the same sets of categories, including their order.

• Categorical arrays that are not ordinal — Can have different sets of categories, and isequal compares the category names of each pair of elements.

• Datetime arrays — isequal ignores display format when it compares points in time. If the arrays are all associated with time zones, then isequal compares the instants in time rather than the clockface times (for example, 01-May-2018 09:00:00 EDT is the same instant as 01-May-2018 06:00:00 PDT, so isequal returns true even though the clockface times of 9:00 and 6:00 differ).

• Objects — isequal returns logical 1 (true) for objects of the same class with equal property values.

Tips

• The equality of two function handles depends on how they are constructed. For more information, see Compare Function Handles.

• isequal returns logical 0 (false) for two objects with dynamic properties, even if the properties have the same names and values.

• isequal compares only stored (non-dependent) properties when testing two objects for equality.

• When comparing two handle objects, use == to test whether objects have the same handle. Use isequal to determine if two objects with different handles have equal property values.

• When comparing empty object arrays, isequal returns logical 1 (true) only when the arrays have the same size and class.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The isequal function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2022b: Equality of Empty Object Arrays

In previous releases, isequal considered two or more empty object arrays equal when they were the same size, but it did not take class into account. Starting in R2022b, isequal returns logical 1 (true) for empty object arrays only when the arrays have the same size and class.