Public interfaces for String Comparison and related operations. More...

#include <MacTypes.h>
#include <MixedMode.h>
#include <TextCommon.h>
#include <Script.h>
#include <TypeSelect.h>

Macros
#define	CompareText(aPtr, bPtr, aLen, bLen, itl2Handle) IUMagPString(aPtr, bPtr, aLen, bLen, itl2Handle)

#define	IdenticalString(aStr, bStr, itl2Handle) IUEqualPString(aStr, bStr, itl2Handle)

#define	IdenticalText(aPtr, bPtr, aLen, bLen, itl2Handle) IUMagIDPString(aPtr, bPtr, aLen, bLen, itl2Handle)

#define	StringOrder(aStr, bStr, aScript, bScript, aLang, bLang) IUStringOrder(aStr, bStr, aScript, bScript, aLang, bLang)

#define	TextOrder(aPtr, bPtr, aLen, bLen, aScript, bScript, aLang, bLang) IUTextOrder(aPtr, bPtr, aLen, bLen, aScript, bScript, aLang, bLang)

#define	LanguageOrder(language1, language2) IULangOrder(language1, language2)

Enumerations
enum	{ systemCurLang = -2 , systemDefLang = -3 , currentCurLang = -4 , currentDefLang = -5 , scriptCurLang = -6 , scriptDefLang = -7 }

enum	{ iuSystemCurLang = systemCurLang , iuSystemDefLang = systemDefLang , iuCurrentCurLang = currentCurLang , iuCurrentDefLang = currentDefLang , iuScriptCurLang = scriptCurLang , iuScriptDefLang = scriptDefLang }

Functions
short	MacReplaceText (Handle baseText, Handle substitutionText, Str15 key)

short	ScriptOrder (ScriptCode script1, ScriptCode script2)

short	MacCompareString (ConstStr255Param aStr, ConstStr255Param bStr, Handle itl2Handle)

short	IdenticalString (ConstStr255Param aStr, ConstStr255Param bStr, Handle itl2Handle)

short	StringOrder (ConstStr255Param aStr, ConstStr255Param bStr, ScriptCode aScript, ScriptCode bScript, LangCode aLang, LangCode bLang)

short	CompareText (const void aPtr, const void bPtr, short aLen, short bLen, Handle itl2Handle)

short	IdenticalText (const void aPtr, const void bPtr, short aLen, short bLen, Handle itl2Handle)

short	TextOrder (const void aPtr, const void bPtr, short aLen, short bLen, ScriptCode aScript, ScriptCode bScript, LangCode aLang, LangCode bLang)

short	LanguageOrder (LangCode language1, LangCode language2)

short	IUMagPString (const void aPtr, const void bPtr, short aLen, short bLen, Handle itl2Handle)

short	IUMagIDPString (const void aPtr, const void bPtr, short aLen, short bLen, Handle itl2Handle)

short	IUTextOrder (const void aPtr, const void bPtr, short aLen, short bLen, ScriptCode aScript, ScriptCode bScript, LangCode aLang, LangCode bLang)

short	IULangOrder (LangCode language1, LangCode language2)

short	IUScriptOrder (ScriptCode script1, ScriptCode script2)

short	IUMagString (const void aPtr, const void bPtr, short aLen, short bLen)

short	IUMagIDString (const void aPtr, const void bPtr, short aLen, short bLen)

short	IUCompPString (ConstStr255Param aStr, ConstStr255Param bStr, Handle itl2Handle)

short	IUEqualPString (ConstStr255Param aStr, ConstStr255Param bStr, Handle itl2Handle)

short	IUStringOrder (ConstStr255Param aStr, ConstStr255Param bStr, ScriptCode aScript, ScriptCode bScript, LangCode aLang, LangCode bLang)

short	IUCompString (ConstStr255Param aStr, ConstStr255Param bStr)

short	IUEqualString (ConstStr255Param aStr, ConstStr255Param bStr)

short	iucomppstring (const char aStr, const char bStr, Handle intlHandle)

short	iuequalpstring (const char aStr, const char bStr, Handle intlHandle)

short	iustringorder (const char aStr, const char bStr, ScriptCode aScript, ScriptCode bScript, LangCode aLang, LangCode bLang)

short	iucompstring (const char aStr, const char bStr)

short	iuequalstring (const char aStr, const char bStr)

short	RelString (ConstStr255Param str1, ConstStr255Param str2, Boolean caseSensitive, Boolean diacSensitive)

	EqualString (strA, strB, FALSE, FALSE)

If then both strings are treated as if they had been upshifted with UprString(though the original contents are not modified) .The RelString function[128K ROMs] is more flexible in that its return code identifies which string is higher or lower in the collating sequence.The IUEqualString and IUCompString functions take into consideration special spelling conventions used in foreign languages.</pre > *@par Copyright short	relstring (const char str1, const char str2, Boolean caseSensitive, Boolean diacSensitive)

Boolean	equalstring (const char str1, const char str2, Boolean caseSensitive, Boolean diacSensitive)

Variables
If	caseSens = FALSE

Detailed Description

Public interfaces for String Comparison and related operations.

Introduced In: Mac OS 8

Avaliable From: Universal Interfaces 3.4.1

Copyright: � 1985-2001 by Apple Computer, Inc., all rights reserved.

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Here are the current System 7 routine names and the translations to the older forms. Please use the newer forms in all new code and migrate the older names out of existing code as maintenance permits.

NEW NAME OLD NAME OBSOLETE FORM (no handle)

CompareString (Str255) IUCompPString (hp only) IUCompString (hp only) CompareText (ptr/len) IUMagPString IUMagString IdenticalString (Str255) IUEqualPString (hp only) IUEqualString (hp only) IdenticalText (ptr/len) IUMagIDPString IUMagIDString LanguageOrder IULangOrder ScriptOrder IUScriptOrder StringOrder (Str255) IUStringOrder (hp only) TextOrder (ptr/len) IUTextOrder

RelString CmpString (a only) EqualString (hp only)

ReplaceText

Carbon only supports the new names. The old names are undefined for Carbon targets.

InterfaceLib always has exported the old names. For C macros have been defined to allow the use of the new names. For Pascal and Assembly using the new names will result in link errors.

Function Documentation

◆ CompareText()

short CompareText	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		Handle	itl2Handle
	)

CompareText()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ equalstring()

Boolean equalstring	(	const char *	str1,
		const char *	str2,
		Boolean	caseSensitive,
		Boolean	diacSensitive
	)

equalstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ EqualString()

EqualString	(	strA	,
		strB	,
		FALSE	,
		FALSE
	)

\brief See if two Pascal-style strings are equal

<pre>EqualString compares two pascal-style length-prefixed strings (optionally

ignoring case and/or diacritical marks), and returns an indication of whether or not they are equal. strAand . . . strBare addresses of Pascal-style length-prefixed strings. caseSens specifies whether or not the comparison should be case-sensitive. It must be one of: FALSEignore character case when comparing ('A' == 'a') TRUEcharacter case is significant ('A' != 'a') diacSens specifies whether or not the comparison should be sensitive to diacritical marks. It must be one of: FALSEignore diacritical marks when comparing (' å' == 'a') TRUEdiacritical marks are significant (' å' != 'a')

Returns

a Boolean; it indicates whether the strings are equal, considering
the case- and diacritical sensitivity. It is one of:
FALSEnot equal
TRUEequal

Note

Since EqualString compares pascal-style strings directly, it is handier
than converting to C-style strings and using strcmp. Examples:
Str255 strA="\pAbcDef";
Str255 strB="\p åbcdef";
EqualString ( strA,strB, TRUE,TRUE); /* Returns FALSE

◆ IdenticalString()

short IdenticalString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		Handle	itl2Handle
	)

IdenticalString()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ IdenticalText()

short IdenticalText	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		Handle	itl2Handle
	)

IdenticalText()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ iucomppstring()

short iucomppstring	(	const char *	aStr,
		const char *	bStr,
		Handle	intlHandle
	)

iucomppstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUCompPString()

short IUCompPString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		Handle	itl2Handle
	)

IUCompPString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ iucompstring()

short iucompstring	(	const char *	aStr,
		const char *	bStr
	)

iucompstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUCompString()

short IUCompString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr
	)

\brief Compare p-strings for international sorting

<pre>IUCompString compares two pascal-style strings and indicates which is

greater or if they are equal. It takes into consideration such international characteristics as diacritical marks and ligatures. It DOES differentiate between upper- and lowercase. strAand . . . strBare the addresses of pascal-style length-prefixed strings to be compared.

Returns

a signed integer; it describes the collation relationship of strA and
strB. It is one of:
-1 strA is less than strB
0 strA and strB are equal
1 strA is greater than strB

Note

The return code is the same as used by the familiar C strcmp function. As
with strcmp, a short string is always seen as less than a long string.
IUCompString may be overkill for your application. It is less efficient
than a direct ASCII compare, as it has to look up the "collating weight" of
each character of each string.
This actually ends up calling IUMagString , which does not require
length-prefixed strings.
For case-insensitive equality testing (as when matching file names), use
IUEqualString or EqualString .
The actual comparison function is stored in the itl2 resource.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ iuequalpstring()

short iuequalpstring	(	const char *	aStr,
		const char *	bStr,
		Handle	intlHandle
	)

iuequalpstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUEqualPString()

short IUEqualPString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		Handle	itl2Handle
	)

IUEqualPString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ iuequalstring()

short iuequalstring	(	const char *	aStr,
		const char *	bStr
	)

iuequalstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUEqualString()

short IUEqualString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr
	)

IUEqualString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IULangOrder()

short IULangOrder	(	LangCode	language1,
		LangCode	language2
	)

IULangOrder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUMagIDPString()

short IUMagIDPString	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		Handle	itl2Handle
	)

IUMagIDPString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUMagIDString()

short IUMagIDString	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen
	)

IUMagIDString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUMagPString()

short IUMagPString	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		Handle	itl2Handle
	)

These routines are available in InterfaceLib with old names. Macros are provided for C to allow source code use to the new names. IUMagPString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUMagString()

short IUMagString	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen
	)

IUMagString()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUScriptOrder()

short IUScriptOrder	(	ScriptCode	script1,
		ScriptCode	script2
	)

IUScriptOrder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ iustringorder()

short iustringorder	(	const char *	aStr,
		const char *	bStr,
		ScriptCode	aScript,
		ScriptCode	bScript,
		LangCode	aLang,
		LangCode	bLang
	)

iustringorder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUStringOrder()

short IUStringOrder	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		ScriptCode	aScript,
		ScriptCode	bScript,
		LangCode	aLang,
		LangCode	bLang
	)

IUStringOrder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ IUTextOrder()

short IUTextOrder	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		ScriptCode	aScript,
		ScriptCode	bScript,
		LangCode	aLang,
		LangCode	bLang
	)

IUTextOrder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ LanguageOrder()

short LanguageOrder	(	LangCode	language1,
		LangCode	language2
	)

LanguageOrder()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ MacCompareString()

short MacCompareString	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		Handle	itl2Handle
	)

[Mac]CompareString()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ MacReplaceText()

short MacReplaceText	(	Handle	baseText,
		Handle	substitutionText,
		Str15	key
	)

These routines are available in Carbon with the new names. [Mac]ReplaceText()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ relstring()

If then both strings are treated as if they had been upshifted with UprString (though the original contents are not modified) .The RelString function[128K ROMs] is more flexible in that its return code identifies which string is higher or lower in the collating sequence.The IUEqualString and IUCompString functions take into consideration special spelling conventions used in foreign languages.</ pre> * @par Copyright short relstring	(	const char *	str1,
		const char *	str2,
		Boolean	caseSensitive,
		Boolean	diacSensitive
	)

relstring()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ RelString()

short RelString	(	ConstStr255Param	str1,
		ConstStr255Param	str2,
		Boolean	caseSensitive,
		Boolean	diacSensitive
	)

\brief Compare two Pascal-style strings for sort order

<pre>RelString compares two Pascal-style length-prefixed strings (optionally

ignoring case and/or diacritical marks), and returns an indication of which comes first in the ASCII collating sequence. strAand . . . strBare addresses of Pascal-style length-prefixed strings. caseSens specifies whether or not the comparison should be case-sensitive. It must be one of: FALSEignore character case when comparing ('A' == 'a') TRUEcharacter case is significant ('A' != 'a') diacSens specifies whether or not the comparison should be sensitive to diacritical marks. It must be one of: FALSEignore diacritical marks when comparing (' å' == 'a') TRUEdiacritical marks are significant (' å' != 'a')

Returns

a signed integer; it indicates the relative collating value of the
strings, considering the case- and diacritical-sensitivity. Using the
same values as with the familiar strcmp() library function, it is one
of:
-1strA is less than strB
0strA is equal to strB
+1strA is greater than strB

Note

Since RelString compares Pascal-style strings directly, it is handier
than converting to C-style strings and using strcmp.
If caseSens =FALSE, then both strings are treated as if they had been
upshifted with UprString (though the original contents are not modified).
For 64K ROMs, the EqualString function can be used to test if two
strings are the same. The IUEqualString and IUCompString functions
take into consideration special spelling conventions used in foreign
languages.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ ScriptOrder()

short ScriptOrder	(	ScriptCode	script1,
		ScriptCode	script2
	)

ScriptOrder()

Availability:

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ StringOrder()

short StringOrder	(	ConstStr255Param	aStr,
		ConstStr255Param	bStr,
		ScriptCode	aScript,
		ScriptCode	bScript,
		LangCode	aLang,
		LangCode	bLang
	)

StringOrder()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

◆ TextOrder()

short TextOrder	(	const void *	aPtr,
		const void *	bPtr,
		short	aLen,
		short	bLen,
		ScriptCode	aScript,
		ScriptCode	bScript,
		LangCode	aLang,
		LangCode	bLang
	)

TextOrder()

Availability:

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

Macros

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ CompareText()

◆ equalstring()

◆ EqualString()

◆ IdenticalString()

◆ IdenticalText()

◆ iucomppstring()

◆ IUCompPString()

◆ iucompstring()

◆ IUCompString()

◆ iuequalpstring()

◆ IUEqualPString()

◆ iuequalstring()

◆ IUEqualString()

◆ IULangOrder()

◆ IUMagIDPString()

◆ IUMagIDString()

◆ IUMagPString()

◆ IUMagString()

◆ IUScriptOrder()

◆ iustringorder()

◆ IUStringOrder()

◆ IUTextOrder()

◆ LanguageOrder()

◆ MacCompareString()

◆ MacReplaceText()

◆ relstring()

◆ RelString()

◆ ScriptOrder()

◆ StringOrder()

◆ TextOrder()