Compares two strings using either the Mode Compare or Windows Regional setting.
% = StrComp(string1, string2 [, mode])
% = StrCmp(string1, string2) % = StrCmpI(string1, string2)
%= LStrCmp(string1, string2) %= LStrCmpI(string1, string2)
| string1, string2 | : string values |
| %, mode | : integer values |
All these functions compare two strings and return a value accordingly to whether they are greater, lesser or equal to each other.
StrComp returns an integer value to indicate the result of a string comparison. If string1 is less than string2, the return value is -1, greater than string2, the return value is +1, or equal, the return value is zero. The default comparison is according the current Mode Compare setting; however, StrComp has a third parameter into which a 'one-time only' comparison mode can be entered and this can take any numeric (not string) value Mode Compare can take.
Trace StrComp("Hello", "hallo") // With Current Mode Compare Setting
Trace StrComp("Hello", "hallo", 0) // Binary Compare
Trace StrComp("Hello", "hallo", 1) // Text Compare
Debug.Show
LStrCmp and LStrCmpI work in a very similar way to StrComp with the same return values, the main difference being that these function will sort according to Windows Regional settings rather than the Mode Compare setting. LStrCmp carries out a case-sensitive comparison, while LStrCmpI is non case-senstive and converts all letters to lower case before comparing the two strings. Note: in reality, on standard Windows settings, both of these functions provide the same result regardless of case; the same seems to be true of their built-in Window API equivalents, _lstrcmp and _lstrcmpi.
Trace LStrCmp("K", "j") // Returns 1 but -1 is expected here...
Trace LStrCmpI("K", "j")
Trace _lstrcmp("K", "j") // ...but it is the same with the Windows function as well
Trace _lstrcmpi("K", "j")
Debug.Show
Finally, StrCmp and StrCmpI perform the same task - the comparison made by StrCmp being case-sensitive and by StrCmpI non case-sensitive - with the main difference being that the result, which uses the current Mode Compare setting, is not restricted to -1, 0 or 1, but is the distance in between the first characters which do not match in the compared strings according to the ANSI table.
Trace StrCmp("Hello", "hallo")
Trace StrCmpI("Hello", "hallo")
Trace StrCmp("C", "*")
Trace StrCmpI("C", "*") // Note: StrCmpI converts the 'C' to 'c' before the comparison
Debug.Show
These functions perform the same tasks as the <, > and = operators and can, in some instances, be much faster, while in others, not so (GFA Basic uses these functions internally to parse these operators, so speed differences on straight comparisons should be negligible), as shown in the following example:
Local n%, r%, r1?, t#
t# = Timer
For n% = 1 To 10000 : r% = StrComp("Hello", "hallo") : Next n%
Debug "StrComp time:" & Timer - t#
t# = Timer
For n% = 1 To 10000 : r% = Iif("Hello" > "hallo", 1, Iif("Hello" < "hallo", -1, 0)) : Next n%
Debug "Iif Comparison time:" & Timer - t#
Debug.Print
t# = Timer
For n% = 1 To 10000 : r1? = (StrComp("Hello", "hallo") = 1) : Next n%
Debug "StrComp time:" & Timer - t#
t# = Timer
For n% = 1 To 10000 : r1? = ("Hello" > "hallo") : Next n%
Debug "Straight Comparison time:" & Timer - t#
Debug.Show
The first comparison should always be up to twice as fast, whereas the second is sometimes just faster and sometimes just slower.
{Created by Sjouke Hamstra; Last updated: 02/03/2017 by James Gaite}