This blog describes the diverse functions for comparing the content of two input items, which can be atomic values of node structures. The result can be either a boolean value of “true” or “false”, or an integer for rating the comparison. These functions can be combined with other XPath based functions. The functions are:
The compare function compares two string-based input values from either source leaf nodes or from outputs of other, embedded functions. The result is an integer value, which represents the following values:
Furthermore an input value is greater than the other input value, if it has the same set of characters plus additional characters at the end. For example, “Salem cum pane” is greater than “Salem”.
It may be more convenient to use the comparison operators (See ##BLOG##), because these are just simple characters representing the operations. The exception is the collation of precise linguistic comparison such as the German “ß” and “ss”. If this is the case, it is necessary to use the compare function.
The first example returns -1, because the value of the first leaf node (D_4440) in the function is alphabetically lower than the value of the second node (D_4440_2) in the function.
Example input values, function and output:
Like shown in the following figure, the value of the first leaf node in the function is higher than the value of the second leaf node in the function in the alphabetical order.
Example input values, function and output:
The third example displays that both values are equal. Shown in the following figure, the result is 0.
Example input values, function and output:
The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.
The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.
The fifth example in Figure 5 uses the @collation attribute with the reference to UCA (Unicode Collation Algorithm) collation: http://www.w3.org/2013/collation/UCA?lang=de;strength=primary. The aim of UCA is to compare strings considering the variations of locals and languages such as the German specific character map (see also: https://www.saxonica.com/documentation/#!extensibility/config-extend/collation/UCA and https://unicode.org/reports/tr10/ ). By using the German locale, the comparison result is 0, because the character “ß” is the same as “ss” in German.
Example 4 input values, function and output:
Example 5 input values, function and output:
The contains function can be used for searching a substring in a longer input string. The substring could be anywhere in the longer input string. It returns a Boolean true, if the substring exists in any place of the longer input string.
Remark: The use of $collation is already explained in the chapter of function compare.
The following example shows two mapping elements with the function contains. Based on the set input text, first mapping element returns a true because the text of node D_4440_2 is in the input text of node D_4440. The second mapping element returns a false because the input text of node D_4440_3 is not a part of the text in node D_4440.
Example input values, function and output:
The function deep-equal compares the sequences of two input nodes for a deep equality. It also includes the substructures of the two input nodes. This function returns a boolean 'true', if the comparing sequences contain the same values in same order.
The use of deep-equal in Integration Advisor is limited, since Integration Advisor just allow the mapping and comparison of leaf nodes. Like the following example shows, it is possible to compare the content of a set of different source leaf nodes.
Remark: The use of $collation is already explained in the chapter of function compare.
Like in the following figure shown, the deep-equal can be used of the comparison of a number of source leaf nodes, which exists in different qualified groups. For example the first two leaf nodes of the first qualified group will be compared with the first two leaf nodes of the second qualified group. The first case shows the "true" case and the second case is the "false" case in where the example text of the last leaf node is different.
Example input values, function and output of case 1:
Example input values, function and output of case 2:
The function ends-with returs a boolean 'true', if the input string of the first argument ($arg1) has at the end the same sting like the input string of the second argument ($arg2).
Remark: The use of $collation is already explained in the chapter of function compare.
The following example displays two cases of the use of ends-with. The first case is the true case in where the string of second argument 'tenebat' matches to the end of the input string and the second case is the the false case in where this string does not match to the end of the input string.
Example input values, function and output of case 1:
Example input values, function and output of case 2:
The matches function is more comprehensive than starts-with and ends-with. It compares the input string of the first argument ($arg) with a regular expression ($pattern) and returns “true”, if the string matches the given regular expression. The regular expression is a very powerful feature in the context of XPath functions. It allows to define patterns of characters or spaces, which can be searched in specific positions of the input string. The blog ###BLOG### gives you further details of how to use the regular expression in Integration Advisor. This function supports collations, but it has an additional $flags argument, which optionally enforces the interpretation of a regular expression.
The example considers two cases. The first case can be compared with the ends-with function, because the $ character in the regular expression argument marks the end of a string and there is the string “tenebat” in front of this $ character. The second case gives an example about how the starts-with function can be expressed in a more powerful way.
Example input values, function and output for case 1:
Example input values, function and output for case 2:
The function can be used for testing, if an input string $arg1 starts with a specific substring $arg2. It returns a Boolean “true”, if this is the case.
The following example displays two cases of the use of starts-with. The first case is the true case in where the string of second argument 'Omnia' matches to the beginning of the input string and the second case is the the false case in where this string does not match to the beginning of the input string.
Example input values, function and output of case 1:
Example input values, function and output of case 2:
There are a number of functions for comparing two different input values. As I said, the use of the function "deep-equal" is limited while creating mapping element functions in a Mapping Guideline. But once, I will find further use cases I'm going to provide it to use via a further best-practice blog. Additionally, the function "matches" is very powerful, especially if you are familiar with the regular expression. A further blog ###BLOG### will give you some further details regarding the use of regular expressions in Integration Advisor. We also have concepts on our backlog, which allows a kind of comparison of input values without any coding. This works similar "String Processing" in where you have just give some comparison instructions via check boxes. If you like that the priority of this feature will be increased in the backlog, please go to the influence campaign of Integration Suite (https://influence.sap.com/sap/ino/#/campaign/2282) and either make a new improvement request or vote for it, if already exists.
Read the following blog posts for more information related to the MAG editor and the functions:
- compare compares two inputs and tells which of them is greater or if both are equal
- contains tells if one input string contains another, smaller, input string
- deep-equal compares the sequences of two input nodes for a deep equality
- ends-with tells if one input string ends with another, smaller, input string
- matches compares two inputs by using regular expression
- starts-withtells if one input string starts with another, smaller, input string
compare
compare($arg as string?, $arg2 as string?[, $collation as sting]?)The compare function compares two string-based input values from either source leaf nodes or from outputs of other, embedded functions. The result is an integer value, which represents the following values:
- -1 – If the first input value is in alphabetical and numerical order lower than the second input value.
- 0 – If the first input value is in alphabetical and numerical order equal to the second input value.
- 1 – If the first input value is in alphabetical and numerical order greater than the second input value.
Furthermore an input value is greater than the other input value, if it has the same set of characters plus additional characters at the end. For example, “Salem cum pane” is greater than “Salem”.
It may be more convenient to use the comparison operators (See ##BLOG##), because these are just simple characters representing the operations. The exception is the collation of precise linguistic comparison such as the German “ß” and “ss”. If this is the case, it is necessary to use the compare function.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | First string-based comparand |
| $arg2 | 1..1 | string? | Second string-based comparand |
| $collation | 0..1 | string | Defines the collation of a character map such as the German character ß might count as equal to ss. |
| Output | integer? |
Example 1
The first example returns -1, because the value of the first leaf node (D_4440) in the function is alphabetically lower than the value of the second node (D_4440_2) in the function.
Figure 1: First value is lower than second value
Example input values, function and output:
| Input | D_4440: 'Cogito, ergo sum' D_4440_2: 'Ego sum, qui sum' |
| Function | |
| Output | -1 |
Example 2
Like shown in the following figure, the value of the first leaf node in the function is higher than the value of the second leaf node in the function in the alphabetical order.
Figure 2: First value is higher than second value
Example input values, function and output:
| Input | D_4440_2: 'Ego sum, qui sum' D_4440_3: 'Cogito, ergo sum' |
| Function | |
| Output | 1 |
Example 3
The third example displays that both values are equal. Shown in the following figure, the result is 0.
Figure 3: First value is equal to second value
Example input values, function and output:
| Input | D_4440: 'Cogito, ergo sum' D_4440_3: 'Cogito, ergo sum' |
| Function | |
| Output | 0 |
Example 4 and 5
The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.
Figure 4: Comparison without @collation
The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.
Figure 5: Comparison with @collation
The fifth example in Figure 5 uses the @collation attribute with the reference to UCA (Unicode Collation Algorithm) collation: http://www.w3.org/2013/collation/UCA?lang=de;strength=primary. The aim of UCA is to compare strings considering the variations of locals and languages such as the German specific character map (see also: https://www.saxonica.com/documentation/#!extensibility/config-extend/collation/UCA and https://unicode.org/reports/tr10/ ). By using the German locale, the comparison result is 0, because the character “ß” is the same as “ss” in German.
Example 4 input values, function and output:
| Input | D_4440_4: 'Grosse Latinum Strasse' D_4440_5: 'Große Latinum Straße' |
| Function | |
| Output | -1 |
Example 5 input values, function and output:
| Input | D_4440_4: 'Grosse Latinum Strasse' D_4440_5: 'Große Latinum Straße' |
| Function | |
| Output | 0 |
contains
contains($arg as string?, $arg2 as string?[, $collation as sting]?)The contains function can be used for searching a substring in a longer input string. The substring could be anywhere in the longer input string. It returns a Boolean true, if the substring exists in any place of the longer input string.
Remark: The use of $collation is already explained in the chapter of function compare.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | First string-based comparand |
| $arg2 | 1..1 | string? | Second substring, which should be shorter than first string. |
| $collation | 0..1 | string | Defines the collation of a character map such as the German character ß might count as equal to ss. |
| Output | boolean | true|false |
Example
The following example shows two mapping elements with the function contains. Based on the set input text, first mapping element returns a true because the text of node D_4440_2 is in the input text of node D_4440. The second mapping element returns a false because the input text of node D_4440_3 is not a part of the text in node D_4440.
Figure 6: Function compare with true and false result.
Example input values, function and output:
| Input | D_4440: 'Hic tu qua laetitia perfruere' D_4440_2: 'laetitia' |
| Function | |
| Output | true |
| Input | D_4440: 'Hic tu qua laetitia perfruere' D_4440_3: 'caligo' |
| Function | |
| Output | false |
deep-equal
deep-equal($arg as item()*, $arg2 as item()*[, $collation as sting]?)The function deep-equal compares the sequences of two input nodes for a deep equality. It also includes the substructures of the two input nodes. This function returns a boolean 'true', if the comparing sequences contain the same values in same order.
The use of deep-equal in Integration Advisor is limited, since Integration Advisor just allow the mapping and comparison of leaf nodes. Like the following example shows, it is possible to compare the content of a set of different source leaf nodes.
Remark: The use of $collation is already explained in the chapter of function compare.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | First sequence comparand |
| $arg2 | 1..1 | string? | Second sequence comparand |
| $collation | 0..1 | string | Defines the collation of a character map such as the German character ß might count as equal to ss. |
| Output | boolean | true|false |
Example
Like in the following figure shown, the deep-equal can be used of the comparison of a number of source leaf nodes, which exists in different qualified groups. For example the first two leaf nodes of the first qualified group will be compared with the first two leaf nodes of the second qualified group. The first case shows the "true" case and the second case is the "false" case in where the example text of the last leaf node is different.
Figure 07: Possible use of deep-equal
Example input values, function and output of case 1:
| Input | Group 1 D_4440[1]: 'Hic tu qua laetitia perfruere' D_4440_2[1]: 'Similis simili gaudet.' Group 2 D_4440[2]: 'Hic tu qua laetitia perfruere' D_4440_2[2]: 'Similis simili gaudet.' |
| Function | |
| Output | true |
Example input values, function and output of case 2:
| Input | Group 1 D_4440_3[1]: 'Quaere et invenies' D_4440_4[1]: 'Quaere et invenies?' Group 2 D_4440[_32]: 'Quaere et invenies' D_4440_4[2]: 'Ne discere cessa' |
| Function | |
| Output | false |
ends-with
ends-with($arg as string?, $arg2 as string?[, $collation as sting]?)The function ends-with returs a boolean 'true', if the input string of the first argument ($arg1) has at the end the same sting like the input string of the second argument ($arg2).
Remark: The use of $collation is already explained in the chapter of function compare.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | First, longer string in which the second substring $arg should be at the end |
| $arg2 | 1..1 | string? | Second substring, which should be at the end of the first string of first argument ($arg) |
| $collation | 0..1 | string | Defines the collation of a character map such as the German character ß might count as equal to ss. |
| Output | boolean | true|false |
Example
The following example displays two cases of the use of ends-with. The first case is the true case in where the string of second argument 'tenebat' matches to the end of the input string and the second case is the the false case in where this string does not match to the end of the input string.
Figure 8: Use of function ends-with
Example input values, function and output of case 1:
| Input | D_4440: 'Omnia norat, omnium aditus tenebat' |
| Function | |
| Output | true |
Example input values, function and output of case 2:
| Input | D_4440_2: 'Atque ego, ut vidi, quos maximo furore’ |
| Function | |
| Output | false |
matches
matches($input as string?, $pattern as string)The matches function is more comprehensive than starts-with and ends-with. It compares the input string of the first argument ($arg) with a regular expression ($pattern) and returns “true”, if the string matches the given regular expression. The regular expression is a very powerful feature in the context of XPath functions. It allows to define patterns of characters or spaces, which can be searched in specific positions of the input string. The blog ###BLOG### gives you further details of how to use the regular expression in Integration Advisor. This function supports collations, but it has an additional $flags argument, which optionally enforces the interpretation of a regular expression.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | The input value string, which is matched against the regular expression |
| $pattern | 1..1 | string? | The regular expression, which expresses the matching pattern |
| $flags | 0..1 | string | This argument might have one or more values for controlling the further interpretation of the regular expression. It is possible to set several flags between single quotation marks. The values should be separated by a comma. The following values are supported:
. |
| Output | integer? |
Example
The example considers two cases. The first case can be compared with the ends-with function, because the $ character in the regular expression argument marks the end of a string and there is the string “tenebat” in front of this $ character. The second case gives an example about how the starts-with function can be expressed in a more powerful way.
Figure 9: Definitions of regular expressions in matches function
Example input values, function and output for case 1:
| Input | D_4440: 'Omnia norat, omnium aditus tenebat' |
| Function | |
| Output | true |
Example input values, function and output for case 2:
| Input | D_4440_2: 'Atque ego, ut vidi, quos maximo furore’ |
| Function | |
| Output | true |
starts-with
starts-with($arg as string?, $arg2 as string?[, $collation as sting]?)
The function can be used for testing, if an input string $arg1 starts with a specific substring $arg2. It returns a Boolean “true”, if this is the case.
| Input | Occur. | Base type | Description |
| $arg | 1..1 | string? | First, longer string in which the substring of the second argument ($arg2) should be at the beginning |
| $arg2 | 1..1 | string? | Second substring, which should be at the beginning in the string of the first argument ($arg) |
| $collation | 0..1 | string | Defines the collation of a character map such as the German character ß might count as equal to ss. |
| Output | integer? |
Example
The following example displays two cases of the use of starts-with. The first case is the true case in where the string of second argument 'Omnia' matches to the beginning of the input string and the second case is the the false case in where this string does not match to the beginning of the input string.
Figure 9: Use of starts-with function
Example input values, function and output of case 1:
| Input | D_4440: 'Omnia norat, omnium aditus tenebat' |
| Function | |
| Output | true |
Example input values, function and output of case 2:
| Input | D_4440_2: 'Atque ego, ut vidi, quos maximo furore' |
| Function | |
| Output | false |
Summary
There are a number of functions for comparing two different input values. As I said, the use of the function "deep-equal" is limited while creating mapping element functions in a Mapping Guideline. But once, I will find further use cases I'm going to provide it to use via a further best-practice blog. Additionally, the function "matches" is very powerful, especially if you are familiar with the regular expression. A further blog ###BLOG### will give you some further details regarding the use of regular expressions in Integration Advisor. We also have concepts on our backlog, which allows a kind of comparison of input values without any coding. This works similar "String Processing" in where you have just give some comparison instructions via check boxes. If you like that the priority of this feature will be increased in the backlog, please go to the influence campaign of Integration Suite (https://influence.sap.com/sap/ino/#/campaign/2282) and either make a new improvement request or vote for it, if already exists.
Further Reading
Read the following blog posts for more information related to the MAG editor and the functions:
- Integration Advisor – List of support XSLT elements and XPath functions
- integration content advisor: Create a mapping using MAG editor
- Integration Advisor – Quickly create your individual code value mappings in MAGs
- Integration Advisor: Functions at target side – Ordinal number for line items and segment count
- SAP Managed Tags:
