Main Content

matlab.unittest.constraints.CellComparator Class

Namespace: matlab.unittest.constraints

Comparator for cell arrays

expand all in page

Description

The matlab.unittest.constraints.CellComparator class provides a comparator for cell arrays. To use this comparator in your tests, create a CellComparator instance, and specify it as the value of the Using name-value argument of the IsEqualTo constraint constructor.

Creation

Description

c = matlab.unittest.constraints.CellComparator creates a comparator for empty cell arrays. The comparator is satisfied if the actual and expected values are empty cell arrays with the same size.

example

c = matlab.unittest.constraints.CellComparator(comp) uses the specified comparators comp to compare the values contained in the cell arrays. When you use this syntax, the comparator is satisfied if the actual and expected values are cell arrays with the same size, and the corresponding cell array elements satisfy any of the comparators in comp.

example

c = matlab.unittest.constraints.CellComparator(___,"Recursively",tf) also specifies whether to operate recursively when comparing the values contained in the cell arrays. If tf is true, the recursion continues until all nested values are examined for equality. You can use this syntax with any of the input argument combinations in the previous syntaxes.

example

Input Arguments

expand all

Comparators used to compare the values contained in the cell arrays, specified as an object array of classes in the matlab.unittest.constraints namespace that are classified as comparators.

Example: matlab.unittest.constraints.NumericComparator

Example: matlab.unittest.constraints.StringComparator("IgnoringCase",true)

Example: [matlab.unittest.constraints.LogicalComparator matlab.unittest.constraints.NumericComparator]

Whether to operate recursively, specified as a numeric or logical 0 (false) or 1 (true).

When the value is true, the elements of the actual and expected cell arrays also can be cell arrays, and the comparator recursively compares these elements. When the value is false, all elements of the actual and expected cell arrays must have a type that is supported by comp. For example, in the following code, both c1 and c2 can compare cell arrays of numeric values. However, only c2 can compare cell arrays that contain either cell arrays or numeric values as their elements.

import matlab.unittest.constraints.CellComparator
import matlab.unittest.constraints.NumericComparator

c1 = CellComparator(NumericComparator);
c2 = CellComparator(NumericComparator,"Recursively",true);

This argument sets the Recursive property.

Properties

expand all

Whether to operate recursively, returned as a logical 0 (false) or 1 (true).

This property is set by the tf input argument.

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Open Script

Compare actual and expected values using the CellComparator class.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.CellComparator
import matlab.unittest.constraints.NumericComparator
import matlab.unittest.constraints.AbsoluteTolerance

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a CellComparator instance to compare two empty cell arrays. The test fails because the sizes do not match.

testCase.verifyThat({},IsEqualTo(cell(0,2),"Using",CellComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> CellComparator failed.
        --> Sizes do not match.
            
            Actual size:
                 0     0
            Expected size:
                 0     2
        
        Actual Value:
          0×0 empty cell array
        Expected Value:
          0×2 empty cell array
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingCellComparatorExample.m (CompareValuesUsingCellComparatorExample) at 19

To compare nonempty cell arrays, pass an appropriate comparator to the CellComparator constructor. For example, compare a cell array of numeric values to itself. The test passes.

testCase.verifyThat({1,2,4},IsEqualTo({1,2,4}, ...
    "Using",CellComparator(NumericComparator)))

Verification passed.

Compare {1,2,3} to {1,2,4}. For the test to pass, specify that corresponding elements must be equal within an absolute tolerance of 1.

testCase.verifyThat({1,2,3},IsEqualTo({1,2,4}, ...
    "Using",CellComparator(NumericComparator( ...
    "Within",AbsoluteTolerance(1)))))

Verification passed.

Compare nested cell arrays of numeric values by instructing the comparator to operate recursively. The test fails because the nested cell arrays are not the same.

testCase.verifyThat({1,2,{4,8}},IsEqualTo({1,2,{4,16}}, ...
    "Using",CellComparator(NumericComparator,"Recursively",true)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>{3}{2}
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> Failure table:
                    Actual    Expected    Error    RelativeError
                    ______    ________    _____    _____________
                                                                
                      8          16        -8          -0.5     
            
            Actual Value:
                 8
            Expected Value:
                16
    
    Actual Value:
      1×3 cell array
    
        {[1]}    {[2]}    {1×2 cell}
    Expected Value:
      1×3 cell array
    
        {[1]}    {[2]}    {1×2 cell}
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingCellComparatorExample.m (CompareValuesUsingCellComparatorExample) at 36

Tips

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

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

    import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.CellComparator
import matlab.unittest.constraints.NumericComparator

testCase = TestCase.forInteractiveUse;
exp = {1,2,{3},'abc'}; 
act = exp;
testCase.verifyThat(act,IsEqualTo(exp,"Using",CellComparator(NumericComparator)))

Version History

Introduced in R2013a

See Also

|

Topics