Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Text /
Chapter 5 - Text Utilities / Text Utilities Reference
Routines / Determining Sorting Order for Strings in the Same Language


RelString

The RelString function compares two Pascal strings using the string comparison rules of the Macintosh file system and returns a value that indicates the sorting order of the first string relative to the second string. This function does not make use of any script or language information; it assumes the original Macintosh character set only. RelString uses the sorting rules that are described in Table 5-2 on page 5-17.

FUNCTION RelString (aStr, bStr: Str255;
                    caseSens, diacSens: Boolean): Integer;
aStr
One of the Pascal strings to be compared.
bStr
The other Pascal string to be compared.
caseSens
A flag that indicates how to handle case-sensitive information during the comparison. If the value of caseSens is TRUE, uppercase characters are distinguished from the corresponding lowercase characters. If it is FALSE, case information is ignored.
diacSens
A flag that indicates how to handle information about diacritical marks during the string comparison. If the value of diacSens is TRUE, characters with diacritical marks are distinguished from the corresponding characters without diacritical marks during the comparison. If it is FALSE, diacritical marks are ignored.
DESCRIPTION
RelString returns -1 if the first string is less than the second string, 0 if the two strings are equal, and 1 if the first string is greater than the second string. It compares the two strings in the same manner as does the EqualString function, by simply looking at the ASCII values of their characters. However, RelString provides more information about the two strings--it indicates their relationship to each other, rather than determining if they are exactly equal.

If the value of the diacSens parameter is FALSE, RelString ignores diacritical marks and strips them as shown in the appendix "International Resources" in this book.

If the value of the caseSens parameter is FALSE, the comparison is not case-sensitive; RelString performs a conversion from lowercase to uppercase characters.

SPECIAL CONSIDERATIONS
The RelString function is not localizable and does not work properly with non-Roman script systems.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the RelString function are
Trap macroSelector
_RelString$A050

The trap macro for the RelString function can take optional arguments, each of which changes the default setting used by the macro when it is called without arguments. Each of these arguments corresponds to the Boolean parameters that are used with the Pascal function call. The various permutations of this trap macro are shown below; you must type each exactly as it is shown. The syntax shown here applies to the MPW Assembler; if you are using another development system, be sure to consult its documentation for the proper syntax.
Macro permutation
Value of
diacSens
Value of
caseSens
_RelStringFALSEFALSE
_RelString ,MARKSTRUEFALSE
_RelString ,CASEFALSETRUE
_RelString ,MARKS,CASETRUETRUE

The registers on entry and exit for this routine are
Registers on entry
A0pointer to first character of the first string
A1pointer to first character of the second string
D0high-order word: number of bytes in the first string
low-order word: number of bytes in the second string
Registers on exit
D0long word result: -1 if first string is less than second,
0 if equal, 1 if first string is greater than second


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996