compare_characters

The compare_characters function compares two TEXTs. It will return a 0 when the texts are the same. If the first parameter is smaller than the second parameter, the function will return a value <0. If the first parameter turns out to be bigger than the second parameter, the function will return a value >0.

The compare_characters function will attempt to convert characters to their Unicode equivalent internally before comparing them. This conversion will not modify the parameters.

compare_characters ( text_one; text_two )

This function yields a value of type NUMBER.

The function compare_characters has two parameters:

1. Text_one, type TEXT. Text value that will be compared to the second parameter.
2. Text_two, type TEXT. Text value that will be compared to the first parameter.

Note

Comparing two text values with an operator (=, <=, >, < etcetera) can fail if you try to compare two text values that are encoded using a different system. It is better to use the function compare_characters in these cases to avoid problems.

The table below shows how to achieve the same result with the compare_characters function as was intended with the operator comparison.

Comparisons with an operator (do not use)	Comparisons with the compare_characters function
X = Y	compare_characters( X ; Y ) = 0
X <= Y	compare_characters ( X ; Y ) <= 0
X < Y	compare_characters ( X ; Y ) < 0
X >= Y	compare_characters ( X ; Y ) >= 0
X > Y	compare_characters ( X ; Y ) > 0
X <> Y	compare_characters ( X ; Y ) <> 0

Examples:

@( compare_characters("abc"; "abc") )
Result: 0

compare_characters ("a"; "b")

Result: -1 ("a" is smaller than "b")

compare_characters ("123"; "123")  

Result: 0
Note that the word processor instructions used to layout the "2" is ignored by the function.

The function compare_characters will ignore word processor instructions.

Due to differing encoding schemes, it is not possible to compare Unicode data from the database against Unicode characters in the model document using the regular comparison operators. To ensure correct comparisons, use the compare_characters function.

Comparisons between database fields and characters in the model document are only safe if both arguments consist of single-byte characters only. Comparisons between Unicode database fields and Unicode text in the model document can also fail due to different encoding systems. Use the function compare_characters to safely compare text values that possibly use a different encoding system.