Main Content

matlab.unittest.constraints.CellComparator class

Package: matlab.unittest.constraints

Comparator for cell arrays


The CellComparator compares cell arrays.


CellComparator creates a comparator for cell arrays.

CellComparator(compObj) indicates a comparator, compObj, that defines the comparator used to compare values contained in the cell array. By default, a cell comparator supports only empty cell arrays.

CellComparator(compObj,Name,Value) provides a comparator with additional options specified by one or more Name,Value pair arguments.

CellComparator(Name,Value) provides a comparator for empty cell arrays with additional options specified by one or more Name,Value pair arguments.

Input Arguments


Comparator object

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.


Indicator of whether comparator operates recursively, specified as false or true (logical 0 or 1). When this value is false, the comparator does not operate recursively on its data.

When the value is true, the data types the cell comparator supports are fully supported in recursion. For example:

comp1 = CellComparator(StringComparator)
comp2 = CellComparator(StringComparator,'Recursively', true)
Both comp1 and comp2 support cell arrays of strings and character arrays. However, only comp2 supports cell arrays that recursively contain either cell arrays or strings as their elements.

Default: false



Indicator of whether comparator operates recursively, specified in the name-value pair argument, 'Recursively'

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.


collapse all

Create a test case for interactive testing.

import matlab.unittest.TestCase;
import matlab.unittest.constraints.CellComparator
import matlab.unittest.constraints.StringComparator
import matlab.unittest.constraints.IsEqualTo

testCase = TestCase.forInteractiveUse;

Use a CellComparator to test that two cell arrays are equal to each other.

actual = {'abc','def'};
expected = {'abc','def'};
testCase.verifyThat(actual, IsEqualTo(expected,...
    'Using', CellComparator(StringComparator)))
Interactive verification passed.

By default, the CellComparator supports only comparison of empty cell arrays. Therefore, it is necessary to pass it a StringComparator.

Change the actual value and compare it to the expected value. To satisfy the constraint, construct it to ignore case and whitespace characters.

actual = {'ABC','D E F'};
testCase.verifyThat(actual, IsEqualTo(expected, 'Using', ...
    CellComparator(StringComparator), 'IgnoringWhitespace', ...
    true, 'IgnoringCase',true))
Interactive verification passed.

Test nested cell arrays of character vectors by constructing the comparator to operate recursively.

actual = {'abc',{'def','ghi'}};
expected = {'abc',{'def','ghi'}};

testCase.verifyThat(actual, IsEqualTo(expected, 'Using', ...
    CellComparator(StringComparator, 'Recursively', true)))
Interactive verification passed.


  • In most cases, you are not required to use a CellComparator object. The IsEqualTo class creates a constraint to test for equality between data of various types, including cell arrays.

    Use a CellComparator object when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when cell arrays include nonnumeric values, include a CellComparator object in your test. In this example, MATLAB® throws an exception because C1 and C2 contain nonnumeric values.

    import matlab.unittest.constraints.IsEqualTo
    import matlab.unittest.constraints.CellComparator
    import matlab.unittest.constraints.NumericComparator
    C1 = {1,2,{3},'abc'}; 
    C2 = C1;
    testCase = matlab.unittest.TestCase.forInteractiveUse;

Version History

Introduced in R2013a