Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

IXPostingSet

	Inherits From:	Object
	Conforms To:	IXPostingExchange IXPostingOperations
	Declared In:	btree/IXPostingSet.h

Class Description

An IXPostingSet stores sets of postings in memory.  An IXPostingSet can be loaded from any object that conforms to the IXPostingExchange protocol such as IXPostingCursor, IXPostingList, or another IXPostingSet; it can also forms set unions, intersections, and differences with the postings stored in such an object.  IXPostingSet is particularly well suited to building up query results for databases. The following example shows how an IXPostingSet might be used to find all of the records in an IXRecordManager whose value for some string valued attribute matches some prefix:

IXPostingSet *matchPrefix(IXRecordManager *aSource,
const char *attributeName, const char *thePrefix)
{
IXPostingSet    *theSet;
IXPostingCursor *aCursor;
char            *theKey;
unsigned        keyLength;
unsigned        theLength;

// get a cursor for the attribute
aCursor = [aSource cursorForAttributeNamed:attributeName];
if (aCursor == nil) return nil;

// create an empty posting set
theSet = [[IXPostingSet alloc] initCount:0 andPostings:NULL];

// iterate over the keys while there's a match
theLength = strlen(thePrefix);
[aCursor setKey:thePrefix andLength:theLength];
while ([aCursor getKey:(void **)&theKey andLength:&keyLength])
{
// check for key out of bounds
if (keyLength < theLength || bcmp(theKey, thePrefix,
theLength) break;

// add the postings for this key to the set and move cursor
[theSet formUnionWithPostingsIn:aCursor];
[aCursor setNext];
}

[aCursor free];

// free set if empty
return [theSet count] ? theSet : [theSet free];
}

Instance Variables

unsigned int thisElement; unsigned int numElements; unsigned int maxElements; IXPosting *postings;

	thisElement	The position of the selected posting.
	numElements	The number of postings in the set.
	maxElements	The maximum allowable number of postings in the set.
	postings	The postings.

Adopted Protocols

IXPostingExchange

setCount:andPostings:

getCount:andPostings:

IXPostingOperations

addHandle:withWeight:

removeHandle: count empty setFirstHandle setNextHandle setHandle: getHandle:andWeight:

Method Types

Initializing instances

initCount:andPostings:

initWithPostingsIn:

	Setting the postings	setCount:andPostings:byCopy:
	Accessing postings by position	setPosition:
	Performing set operations	formUnionWithPostingsIn:

formIntersectionWithPostingsIn: subtractPostingsIn:

Instance Methods

formIntersectionWithPostingsIn:

formIntersectionWithPostingsIn:(id <IXPostingExchange>)anObject

Combines the postings in the IXPostingSet with those in anObject, so that on return the IXPostingSet will contain only those postings that were in both objects; that is, it performs a logical AND on the two sets of postings.  If each set has a posting with the same handle, but different weights, the weights are averaged.  anObject is unaffected by this method.  Returns self. See also:  formUnionWithPostingsIn:, subtractPostingsIn:

formUnionWithPostingsIn:

formUnionWithPostingsIn:(id <IXPostingExchange>)anObject

Combines the postings in the IXPostingSet with those in anObject, so that on return the IXPostingSet will contain all postings that were in either object (duplicates are reduced to a single posting); that is, it performs a logical OR on the two sets of postings.  If each set has a posting with the same handle, the weights are averaged.  anObject is unaffected by this method. Returns self. See also:  formIntersectionWithPostingsIn:, subtractPostingsIn:

initCount:andPostings:

initCount:(unsigned int)count andPostings:(const IXPosting *)postings

Initializes the IXPostingSet with count postings, copied from postings.  This is the designated initializer for IXPostingSet objects. See also:  initWithPostingsIn:, setCount:andPostings:byCopy:

initWithPostingsIn:

initWithPostingsIn:(id <IXPostingExchange>)anObject

Initializes the IXPostingSet with the postings in anObject.  anObject should conform to the IXPostingExchange protocol. Returns self. See also:  initCount:andPostings:

setCount:andPostings:byCopy:

setCount:(unsigned int)count

andPostings:(const IXPosting *)postings byCopy:(BOOL)flag

Sets the count and postings in the IXPostingSet, replacing and deallocating any previous contents.  If flag is YES, a copy of postings is made and set to be the IXPostingSet's postings; if flag is NO, then the IXPostingSet assumes responsibility for the set of postings, and will free them when they are replaced or when the IXPostingSet is freed.  Returns self. See also:  initCount:andPostings:

setPosition:

(unsigned int)setPosition:(unsigned int)index

Selects a posting by position in the posting set, and returns that posting's handle.  Your code can use this method to quickly access a handle based on its position. See also:  setHandle: (IXPostingSetOperations protocol)

subtractPostingsIn:

subtractPostingsIn:(id <IXPostingExchange>)anObject

Removes from the IXPostingSet those postings that are also in anObject; that is, it performs a logical AND NOT between the two sets of postings.  anObject is unaffected by this method.  Returns self. See also:  formUnionWithPostingsIn:, formIntersectionWithPostingsPostingsIn: