Main Content

matlab.unittest.constraints.StringComparator Class

Namespace: matlab.unittest.constraints

Comparator for string arrays, character arrays, or cell arrays of character arrays

expand all in page

Description

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

Creation

Description

c = matlab.unittest.constraints.StringComparator creates a comparator for string arrays, character arrays, or cell arrays of character arrays. The comparator is satisfied if the actual and expected values are textual values with the same class and size, and their corresponding elements are equal.

example

c = matlab.unittest.constraints.StringComparator(Name,Value) sets additional options using one or more name-value arguments. For example, c = matlab.unittest.constraints.StringComparator("IgnoringCase",true) creates a comparator that is insensitive to case.

example

Input Arguments

expand all

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.

Example: c = matlab.unittest.constraints.StringComparator(IgnoringCase=true)

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

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

Whether to ignore case, specified as a numeric or logical 0 (false) or 1 (true). By default, the comparator is sensitive to case.

This argument sets the IgnoreCase property.

Whether to ignore white space, specified as a numeric or logical 0 (false) or 1 (true). By default, the comparator is sensitive to white-space characters. White-space characters consist of space (' '), form feed ('\f'), new line ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v').

This argument sets the IgnoreWhitespace property.

Properties

expand all

Whether to ignore case, returned as a logical 0 (false) or 1 (true). By default, the comparator is sensitive to case.

This property is set by the IgnoringCase name-value argument.

Attributes:

GetAccess
public
SetAccess
private

Whether to ignore white space, returned as a logical 0 (false) or 1 (true). By default, the comparator is sensitive to white-space characters.

This property is set by the IgnoringWhitespace name-value argument.

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Open Script

Compare actual and expected values using the StringComparator class.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a StringComparator instance to compare the string "Milky Way" to itself. The test passes.

testCase.verifyThat("Milky Way",IsEqualTo("Milky Way", ...
    "Using",StringComparator))

Verification passed.

Change the actual value to 'Milky Way'. The test fails because the actual and expected values do not have the same class.

testCase.verifyThat('Milky Way',IsEqualTo("Milky Way", ...
    "Using",StringComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StringComparator failed.
        --> Classes do not match.
            
            Actual Class:
                char
            Expected Class:
                string
        
        Actual char:
            Milky Way
        Expected Value:
            "Milky Way"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingStringComparatorExample.m (CompareValuesUsingStringComparatorExample) at 22

Compare "Milky way " to "Milky Way". The test fails because the values are not equal.

testCase.verifyThat("Milky way ",IsEqualTo("Milky Way", ...
    "Using",StringComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StringComparator failed.
        --> The strings are not equal.
        
        Actual Value:
            "Milky way "
        Expected Value:
            "Milky Way"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingStringComparatorExample.m (CompareValuesUsingStringComparatorExample) at 27

For the test to pass, use a comparator that ignores case and white-space characters.

testCase.verifyThat("Milky way ",IsEqualTo("Milky Way", ...
    "Using",StringComparator( ...
    "IgnoringCase",true,"IgnoringWhitespace",true)))

Verification passed.

Tips

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

    Use a StringComparator instance when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when actual and expected values are not textual, include a StringComparator instance in your test. You also can use StringComparator to restrict the values contained in cell arrays, structures, dictionaries, tables, and public properties of MATLAB® object arrays. In this example, MATLAB throws an error because the actual and expected values are numeric arrays.

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

testCase = TestCase.forInteractiveUse;    
exp = magic(5); 
act = exp;
testCase.verifyThat(act,IsEqualTo(exp,"Using",StringComparator))

Version History

Introduced in R2013a

See Also

| | |