compareStrings
compareStrings ( aString : string , bString : string { , options : integer } ) : integer
| Parameter | Type | Description | |
|---|---|---|---|
| aString | string | -> | String to compare |
| bString | string | -> | String to compare |
| options | integer | -> | Comparison rule(s) |
| Result | integer | <- | Result of string comparison |
Description
The compareStrings command returns a negative, zero, or positive value depending on if aString is evaluated as lower, equal, or higher than bString..
In the aString parameter, pass a string value.
In the bString parameter, pass a string value to be compared to aString.
By default, compareStrings functions as if the "<" (less than) operator is used. This can be modified with the options parameter. You can pass one or a combination of the following constants:
| Constant | Comment |
|---|---|
| kCaseInsensitive | Strings are compared according to the current data language with no consideration of capitalization differences. Note that diacritical marks are taken into consideration. For example, "A" is considered the same as "a", however "a" is not considered the same as "à" . By default, Qodly string comparison is case insensitive. Can be combined with:
This constant implies the use of the following constants (which can also be combined for improved readability):
|
| kCharCodes | Strings are compared according to character codes. Current data language settings are not taken into account during the comparison.
Can be combined with: kCaseInsensitive Only for "a-z" or "A-Z" ranges. (e.g., Alpha = alpha, but Alpha # âlphà) |
| kDiacriticInsensitive | Strings are compared according to the current data language, however the diacritical mark (e.g., accent or symbol) of letters is ignored. For example, "a" is considered the same as "à". Can be combined with:
This constant implies the use of the following constants (which can also be combined for improved readability):
|
| kKanaInsensitive | For Japanese language. Controls the distinction between Hiragana and Katakana syllables. From a semantic point of view, the difference between Hiragana and Katakana is usually significant, but to capture as many results as possible, the default mode in Qodly is to ignore the difference (kana insensitive). For example, "あ" is considered the same as "ア". The kStrict option performs a kana sensitive comparison. kKanaInsensitive can be used to partially relax the rule to be kana insensitive. Note: The data language must be set to Japanese to use this option. For all other languages, the option is ignored and Can be combined with:
|
| kStrict | Strings are compared for exact matches according to the current data language. In most cases, capitalization and diacritical marks of letters are taken into account during the comparison. Can be combined with:
This constant implies the use of the following constant (which can also be combined for improved readability):
|
| kWidthInsensitive | For Japanese language. Corresponds to the "East Asian Width" Unicode standard, as defined in Unicode Standard Annex #11. From a semantic point of view, the difference between a "narrow" and "wide" character or a "full width" and "half width" character is usually insignificant, which is the default mode in Qodly. For example, "ｱ" is considered the same as "ア". The kStrict option performs a width sensitive comparison. Note: The data language must be set to Japanese to use this option. For all other languages, the option is ignored and Can be combined with:
This constant implies the use of the following constant (which can also be combined for improved readability):
|
You cannot use the @ wildcard character with compareStrings. For example, if you pass "abc@" in aString or bString the command will actually evaluate the "abc@" string and not an "abc" string plus any character.
Returned value
The command returns the following integer values:
| Value | Description |
|---|---|
| -1 | aString is lower than bString |
| 0 | aString is equal to bString |
| 1 | aString is higher bString |
Example 1
You want to compare the following strings:
var string1, string2 : string
var myResult : integer
string1 = "alpha Bravo charlie Delta Echo Fox-Trot"
string2 = "Alpha Bravo Charlie Delta Echo Fox-Trot"
//compare the strings using the character code
myResult = compareStrings(string1,string2,kCharCodes)
// myResult = 1
//compare the strings using the character code but ignoring any capitalization
myResult = compareStrings(string1,string2,kCharCodes+kCaseInsensitive)
// myResult = 0
Example 2
The following examples illustrate the specific impact of options in Japanese data language context:
var myResult : integer
//default is kana insensitive
myResult = compareStrings("イロハ","いろは") // equal
myResult = compareStrings("イロハ","いろは",kStrict) // not equal
result = compareStrings("イロハ","いろは",kKanaInsensitive) // equal
var myResult : integer
//default is case insensitive
myResult = compareStrings("さつき","さっき") // equal
myResult = compareStrings("さつき","さっき",kStrict) // not equal
myResult = compareStrings("さつき","さっき",kCaseInsensitive) // equal
var myResult : integer
//default is diacritic sensitive when the data language is set to Japanese (different to all other languages)
myResult = compareStrings("ete","été") // equal in non-Japanese data language
myResult = compareStrings("ete","été") // not equal in Japanese data language
myResult = compareStrings("うがい","うかい") // not equal
myResult = compareStrings("うがい","うかい",kStrict) // not equal
myResult = compareStrings("うがい","うかい",kDiacriticInsensitive) // equal
The "Sorting order appropriate for searching" setting has an impact on the compareStrings command. In particular, the "Katakana-Hiragana Prolonged Sound Mark" or "長音記号" will be interpreted differently. The setting also has an impact on "Japanese Iteration Marks" such as "ゝ" or "ゞ".
For example:
var myResult : integer
myResult = compareStrings("いすず","いすゞ") // equal if setting is disabled
myResult = compareStrings("いすず","いすゞ") // not equal if setting is enabled
myResult = compareStrings("ラーメン","ﾗｰﾒﾝ") // equal if setting is enabled
myResult = compareStrings("ラーメン",&NBSP,"ﾗｰﾒﾝ") // not equal if setting is disabled