Functions and Directives

Function SetLexRule() Foundation

Defines or returns lexical rules for the comparison of one or more characters.

SetLexRule( <aLexRule> )         --> aOldRule
SetLexRule( [<aMultipleRules>] ) --> aCollationTable
<aLexRule> := { <cFromChar> , [<cToChar>] }
<aLexRule> is a two-element array. The first element <cFromChar> is a character expression of one or more characters for which a lexical comparison rule is to be defined.
The second element <cToChar> is a character expression of one or more characters which are considered identical to <cFromChar> in lexical comparisons. If <cToChar> has the value NIL, an existing comparison rule is voided.
<aMultipleRules> := { [<aLexRule1>] [, <aLexRuleN...> ] }
Multiple comparison rules can be defined with one call to SetLexRule() if the rules are specified as a two dimensional array. Each element must contain a two-element array as described above. In this case, all existing comparison rules are discarded and the those defined with <aMultipleRules> become active. If an empty array is passed, the comparison rules defined with SET COLLATION TO become active.

The return value of SetLexRule() depends on the passed arguments. If the function is called with no arguments or if a two-dimensional array is passed, it returns the present comparison table for characters as a two-column array.

When a two-element array is passed, the function returns the previously defined comparison rule for <cFromChar> as a two-element array.


In Xbase++, character strings can be compared with one another on the basis of lexical rules. These rules are based on the country-specific language support of the operating system and can be extended in any way by the function SetLexRule(). This results in a powerful tool for sorting, searching and comparing character strings.

SetLexRule() defines lexical rules for the comparison of character strings. Character strings whose lexical meaning is identical although their actual characters are different can be compared with one another. This is especially useful in the definition of lexical comparison rules for language-specific special characters like the German umlaut or the German 'ß'. In terms of lexical meanings, the following four character strings are identical: "Müllerstraße", "Muellerstraße", "Müller-Strasse" and "MUELLERSTRASSE".

Two kinds of lexical comparison rules can be defined with SetLexRule(): character rules and string rules. The first 256 comparison rules determine the rules for each individual ASCII character. All subsequent rules relate to strings. Only one comparison rule can be defined for a specific string.

The lexical comparison mode for character strings is turned on or off by the command SET LEXICAL ON | OFF or by the call of Set(_SET_LEXICAL,.T.|.F.). The lexical comparison is performed only when the simple comparison operators (=, >=, <=, <>) are used. The exact equality operator == always performs a comparison on the basis of the individual characters (binary comparison).

// In the example, various lexical comparison rules are 
// defined and then the effect of SET LEXICAL is displayed. 


   SetLexRule({ {"ü", "ue"}, ;        // ü  -> ue 
                {"ö", "oe"}, ;        // ö  -> oe 
                {"s",  "S"}, ;        // s  -> S 
                {"ß", "ss"}, ;        // ß  -> ss 
                {"tz", "z"}, ;        // tz -> z 
                {"." ,  ""}, ;        // period       -> "" 
                {"-" ,  ""}, ;        // hyphen       -> "" 
                {" " ,  "" }  } )     // blank space  -> "" 


   ? "Dr.Müller"    = "Dr Mueller"    // result: .F. 
   ? "Görtz Straße" = "Goerz-Strasse" // result: .F. 


   ? "Dr.Müller"  = "Dr Mueller"      // result: .T. 
   ? "Dr. Müller" = "Dr.Mueller"      // result: .T. 
   ? "Dr. Müller" = "Dr Mueller"      // result: .T. 

   ? "Görtz Straße" = "Goerz-Strasse" // result: .T. 
   ? "Görtz-str.  " = "Goerz Str"     // result: .T. 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.