matlab.unittest.constraints.StructComparator class

Package: matlab.unittest.constraints

Comparator for MATLAB structure arrays

Construction

StructComparator creates a comparator for MATLAB^® structure arrays.

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

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

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

Input Arguments

compObj

Comparator object A comparator is passed into the StructComparator to support data types during recursion. By default, the StructComparator supports only empty structure arrays.

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

IgnoringFields — Fields to ignore during struct comparison

cell array of character vectors | string array

Fields to ignore during struct comparison, specified as a cell array of character vectors or a string array.

Recursively — Setting for whether comparator operates recursively

false (default) | true

Setting for whether the 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 StructComparator supports are fully supported in recursion. For example:

comp1 = StructComparator(NumericComparator);
comp2 = StructComparator(NumericComparator, 'Recursively', true);

Both comp1 and comp2 support structures that contain numeric values as their fields. However, only comp2 supports structures that recursively contain either structures or numeric values as their fields.

Properties

IgnoredFields	Fields to ignore during struct comparison, specified in the name-value pair argument, 'IgnoringFields'.
Recursive	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.

Examples

Compare Numeric Structures

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Create two equal structures.

s1 = struct('id',7,'score',7.3);
s2 = s1;

Test that the structures are equal. By default, the StructComparator supports only empty structures, so you need to configure the comparator with a NumericComparator.

testCase.verifyThat(s1, IsEqualTo(s2, 'Using', ...
    StructComparator(NumericComparator)))

Verification passed.

Change the score of s2 and compare the structures again.

s2.score = 7.6;
testCase.verifyThat(s1, IsEqualTo(s2, 'Using', ...
    StructComparator(NumericComparator)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.score
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> Failure table:
                    Actual    Expected    Error       RelativeError   
                    ______    ________    _____    ___________________
                     7.3        7.6       -0.3     -0.0394736842105263
            
            Actual Value:
               7.300000000000000
            Expected Value:
               7.600000000000000
    
    Actual Value:
      struct with fields:
    
           id: 7
        score: 7.300000000000000
    Expected Value:
      struct with fields:
    
           id: 7
        score: 7.600000000000000

Specify an absolute tolerance for the comparison.

testCase.verifyThat(s1, IsEqualTo(s2, 'Using', ...
    StructComparator(NumericComparator), 'Within', ...
    AbsoluteTolerance(0.5)))

Verification passed.

Compare Character Structures

Create a test case for interactive testing.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.StructComparator
import matlab.unittest.constraints.StringComparator

testCase = TestCase.forInteractiveUse;

Create two structures. Make one of the fields a nested structure.

e1 = struct('name', struct('first','sam','last','smith'), ...
    'location','Building A');
e2 = e1;

Verify that the two structures are equal. Since the struct contains a nested structure, configure the constraint to operate recursively.

testCase.verifyThat(e1, IsEqualTo(e2, 'Using', ...
    StructComparator(StringComparator, 'Recursively', true)))

Verification passed.

Change the first name field of the e2 structure and repeat the comparison.

e2.name.first = ' SAM';
testCase.verifyThat(e1, IsEqualTo(e2, 'Using', ...
    StructComparator(StringComparator, 'Recursively', true)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.name.first
        --> StringComparator failed.
            --> The character arrays are not equal.
            
            Actual char:
                sam
            Expected char:
                 SAM
    
    Actual Value:
      struct with fields:
    
            name: [1×1 struct]
        location: 'Building A'
    Expected Value:
      struct with fields:
    
            name: [1×1 struct]
        location: 'Building A'

Configure the comparator to ignore case and whitespace characters.

testCase.verifyThat(e1, IsEqualTo(e2, 'Using', ...
    StructComparator(StringComparator, 'Recursively', true), ...
    'IgnoringCase', true, 'IgnoringWhitespace', true))

Verification passed.

Tips

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

  Use a StructComparator object when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when structures include nonnumeric values, include a StructComparator object in your test. In this example, MATLAB throws an exception because s1 and s2 contain nonnumeric values.

  import matlab.unittest.constraints.IsEqualTo
  import matlab.unittest.constraints.StructComparator
  import matlab.unittest.constraints.NumericComparator
     
  s1 = struct('f1',zeros(1,10),'f2','a','f3',{'b','c'});
  s2 = s1;
  
  testCase = matlab.unittest.TestCase.forInteractiveUse;
  testCase.verifyThat(s2,IsEqualTo(s1,'Using',StructComparator(NumericComparator)))