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 only supports empty structure arrays.

StructComparator(___,Name,Value) provides a comparator with additional options specified by one or more Name,Value pair arguments. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

compObj

Comparator object

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

Name-Value Pair 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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'IgnoringCase'

Indicator if the comparator is insensitive to case, specified as false or true (logical 0 or 1). When it is false, the comparator is sensitive to case. The comparator only uses this name-value pair if the contents being compared are strings.

Default: false

'IgnoringWhitespace'

Indicator if the comparator is insensitive to whitespace, specified as false or true (logical 0 or 1). When it is false, the comparator is sensitive to whitespace. Whitespace characters are space, form feed, new line, carriage return, horizontal tab, and vertical tab. The comparator only uses this name-value pair if the contents being compared are strings.

Default: false

'Recursively'

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 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 a structures that recursively contain either structures or numeric values as their fields.

Default: false

'Within'

Tolerance to use for numerical comparison, specified as a matlab.unittest.constraints.Tolerance object. This name-value pair is applicable to contents that are a numeric type.

Default: (empty)

Properties

IgnoreCase

Indicator if the comparator is insensitive to case, specified in the name-value pair argument, 'IgnoringCase'.

IgnoreWhitespace

Indicator if the comparator is insensitive to whitespace, specified in the name-value pair argument, 'IgnoringWhitespace'.

Recursive

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

Tolerance

Specific tolerance used in construction of the comparator, specified as a matlab.unittest.constraints.Tolerance object in the name-value pair argument, 'Within'.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

expand all

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 only supports empty structures, so you need to configure the comparator with a NumericComparator.

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

Change the score of s2 and compare the structures again.

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

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

Actual struct:
           id: 7
        score: 7.300000000000000
Expected struct:
           id: 7
        score: 7.600000000000000

Specify an absolute tolerance for the comparison.

testCase.verifyThat(s1, IsEqualTo(s2, 'Using', ...
    StructComparator(NumericComparator, 'Within', ...
    AbsoluteTolerance(0.5))))
Interactive 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. One of the fields is 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 struct, configure the constraint to operate recursively.

testCase.verifyThat(e1, IsEqualTo(e2, 'Using', ...
    StructComparator(StringComparator, 'Recursively', true)))
Interactive 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)))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> StringComparator failed.
    Path to failure: <Value>.name.first
    --> The strings are not equal
    
    Actual String:
        sam
    Expected String:
         SAM

Actual struct:
            name: [1x1 struct]
        location: 'Building A'
Expected struct:
            name: [1x1 struct]
        location: 'Building A'

Configure the comparator to ignore case and whitespace.

testCase.verifyThat(e1, IsEqualTo(e2, 'Using', ...
    StructComparator(StringComparator, 'Recursively', true, ...
    'IgnoringCase', true, 'IgnoringWhitespace', true)))
Interactive verification passed.
Was this topic helpful?