# Compare Text

This function is used to compare two text values. The source may be a field value, a property value, a named variable's value, a track variable's value or a text string. The compare against field can be a text string, the contents of a named variable or the contents of a track variable.

When specifying named variables or text you may use any of the escape sequences described in Escape Sequences.

The function can test if the source and against strings are equal, if the source contains the against text, if the source starts or ends with the against text, if the source is like the against text, do a variety of relational tests or do a fuzzy comparison.

You can specify that the test should ignore alphabetic case, diacritical marks and you may negate the result of the test.

When testing for contains, starts with or ends with you can specify Match words. In this mode you match whole words only. For the purposes of this function a match whole word test fails if:

> the first character in the source is alphanumeric and the character preceding the match is alphanumeric.
> or if:
> the last character in the source is alphanumeric and the character following the match is alphanumeric.

When using the like operator, the character * will match 0 or more characters and ? will match exactly 1 character. Unlike the starts, ends and contains tests, like must specify a pattern to match the entire field. Unless you want your test to be anchored at the end of the against text, you might need a trailing *.

When the regular expression operator is specified, the text field can contain track and named variable escape sequences. All other Yate escape sequences will be ignored and passed through to the regular expression parser. If you want to disable all Yate escaping, prefix the expression with a \L. Content inserted from track and named variable escape sequences is properly escaped so as not to be treated as special sequences by the regular expression parser. If for any reason you want to insert regular expression sequences from track or named variables, enable the Do not escape inserted variable contents setting.

You can test the validity of a regular expression via the Validate button. This simply tests if the regular expression can be compiled. Any referenced track or named variables are treated as being a single space.

You can actually test the regular expression against sample text and variable contents via the preview button. A panel will be displayed which allows for the testing and the setting of all pertinent values of this statement. Note that the test values are retained as long as the action is open. More information on the regular expression test panel can be found here.

The fuzzy test uses Yate's fuzzy comparison logic to compare the two text strings. Various factors are used in a fuzzy comparison. Regardless of the value of the case insensitive option, the test always ignores alphabetic case, punctuation characters, diacritical marks and Unicode width differences. The Weight Exception Set is used to determine a set of words to be ignored. A fuzzy test returns a percentage representing the success of the comparison. By default this function returns a true value for a success of 80 or higher. You can change the threshold of the test by setting the named variable Fuzzy Threshold to an integer value in the range of 1-100.

The fuzzy test can be further configured to ignore the position of words when comparing. To force non positional testing, set the named variable Fuzzy Threshold to a negative number in the range of -1 to -100. The actual threshold used is the absolute value of the specified number. Using a negative threshold will result in a comparison of "John and Bill" being a 100% match to "Bill and John".

If the named variable Fuzzy Threshold is set to a value less than -100, 0, or greater than 100, the default of 80 will be used.

In order that you can determine which threshold values make sense for you, the fuzzy test always stores the actual result as an integer, in the range of 0-100, to the named variable Fuzzy %.

The Is the Same Path test is used to compare two paths. The paths are standardized (remove ~, ., .. and empty components). An attempt is made to resolve symbolic links. If after these steps either of the modified paths does not start with / the result of a case sensitive compare is returned. If both paths seem valid and only differ in alphabetic case an attempt is made to determine if the volume supports case sensitivity. This is done as follows: If both paths exist a rigorous test is performed to determine if they represent the same file and the result is returned. If at least one file exists and its containing volume supports case sensitivity the test returns false. Otherwise the test returns true. Basically this means that if a determination that the paths represent the same file cannot be made and the effective paths only differ in alphabetic case they are considered to be equal. It is better to err on the side of caution when the test might be used to determine if an operation on one path would overwrite the file at the other.

Regardless of the test type you can elect to ignore leading and trailing whitespace and/or newline characters via the Trim whitespace characters and Trim newline characters settings.

If you specify a result of Set, the action's test state will be set to True or False depending on the result of the test. If you specify a result of And, the action's test state will be set to false if the result of the test is false. If you specify result of Or, the action's test state will be set to true is the result of the test is true.

In stepwise execution mode the following holds:

- If the source is a named variable, the compare function is only performed once.
- If the source is a not a named variable, the compare function is interpreted as for all files unless the Any option is selected.
- A source of text is performed over every file unless the Once option is selected.

You can choose to save the per file results of the test to a track variable. This is not supported when comparing against a named variable or a text string and Once is specified. It is also not supported when comparing a text source and Once is selected. When setting a track variable, the Set, And, Or semantics are applied, therefore cumulative tests will be saved as expected. The result stored to a track variable will always be a 0 or 1. The Run statement can selectively choose which files are to be executed based on the True or False value of a track variable.