IXComparisonSetting

IXComparisonSetting

Adopted By: IXBTree

Declared In: btree/protocols.h

Protocol Description

The IXComparisonSetting protocol is implemented by objects that compare data elements of unknown type using a comparison format that encodes the types of the data elements. The comparison format is a string containing an Objective C type encoding.
An object implementing this protocol compares two arrays of Objective C scalar values: signed and unsigned short and long integers, signed and unsigned bytes (characters), and single- and double-precision floating-point numbers. Based on the comparison format, an object implementing this protocol iteratively compares the elements of the two arrays until it finds an element that isn't equal to its counterpart in the other array, or until it exhausts the elements of one or both arrays. If the two arrays are otherwise equal, the shorter one is considered the lesser of the two.

Comparison Format Interpretation
A comparison format is simply a string containing an Objective C type encoding for the arrays to be compared. For example, to compare data items as arrays of long integers, the comparison format would be "[5I]" (the number specified in the array is currently ignored).
There are two classes and one function in the Indexing Kit that interpret comparison formats: IXRecordManager, IXPostingList and IXFormatComparator(). A given comparison format may be interpreted differently by all three, due to differences in the physical representation of the data. The following table summarizes the general interpretation policy as implemented by IXFormatComparator():

Code Meaning

c A char

i An int

s A short int

l A long int

C An unsigned char

I An unsigned int

S An unsigned short int

L An unsigned long int

f A float

d A double

* A character string (char *, null-terminated)

@ treated as an unsigned long int

# treated as an unsigned long int

: treated as an character string

^type A pointer to valid type

[ ignored (count is stripped)

] ignored if balanced by start of array

IXFormatComparator() doesn't follow pointers, since the data is assumed to be serialized. Also, since IXFormatComparator() uses the other comparator functions to perform its comparisons, only the first valid component is used, except that the following pairs are legal:

Format String Comparator used

"I*" IXCompareUnsignedAndStrings()

"L*" IXCompareUnsignedAndStrings()

"*I" or "*L" IXCompareStringAndUnsigneds()

IXRecordManager derives comparison formats automatically from the return types of its attributes' selectors. Pointers are followed, and class references ("@") are treated as name ("*") followed by version ("I"), and IXCompareStringAndUnsigneds() is used.
IXPostingList also derives comparison formats from the return types of the selectors used to sort its contents. Pointers are followed to arbitrary depth.

Instance Methods

comparisonFormat

(const char *)comparisonFormat

Returns a character string containing an Objective C type encoding describing data elements compared by the receiver.

setComparisonFormat:

setComparisonFormat:(const char *)format

Records a character string containing an Objective C type encoding describing data elements compared by the receiver. Returns self.

	Code	Meaning

	c	A char
	i	An int
	s	A short int
	l	A long int
	C	An unsigned char
	I	An unsigned int
	S	An unsigned short int
	L	An unsigned long int
	f	A float
	d	A double
	*	A character string (char *, null-terminated)
	@	treated as an unsigned long int
	#	treated as an unsigned long int
	:	treated as an character string
	^type	A pointer to valid type
	[	ignored (count is stripped)
	]	ignored if balanced by start of array

	Format String	Comparator used

	"I*"	IXCompareUnsignedAndStrings()
	"L*"	IXCompareUnsignedAndStrings()
	"I" or "L"	IXCompareStringAndUnsigneds()