bag(3)

Bag

Inherits from: Cltn

Class Description

Bag instances are unordered sets of objects, with possibly duplicate elements. A Bag can be thought of, as a Set , assigning to each element, a count of how many times that element was added ( multiplicity of the element).

The multiplicity of a particular element is returned by the occurrencesOf: message. Repeatedly adding the same (in the sense of hash and isEqual ) object, simply increases the multiplicity of the element. Sending remove: messages, will not remove the element until the multiplicity of the element is zero.

Adding Objects

The methods add: , addNTest: , filter: , replace: and add:ifDuplicate: are used to add objects to a Bag. The difference between these methods is the procedure used in adding, how duplicates are handled and what value is returned.

Difference with OrdCltn

Users should realize that, unlike OrdCltn , Bag does not preserve pointer equality (equality in the isSame sense). Bag's instance method eachElement will return a sequence of objects, possibly containing duplicate elements, but those so-called duplicates will simply be pointers to the same element. Also, since Bag is unordered, the order in which elements will be returned, is not the same as the order in which they were added.

Method types

Creation
    * new
    * new:
    * with:
    * with:with:
    * add:
    * copy
    * deepCopy
    * emptyYourself
    * freeContents
    * free

Interrogation
    * size
    * isEmpty
    * eachElement

Comparing
    * isEqual:

Adding
    * add:
    * addNTest:
    * filter:
    * add:ifDuplicate:
    * replace:

Removing
    * remove:
    * remove:ifAbsent:

Testing Contents
    * includesAllOf:
    * includesAnyOf:

Adding and Removing Contents
    * addAll:
    * addContentsOf:
    * addContentsTo:
    * removeAll:
    * removeContentsFrom:
    * removeContentsOf:

Combining
    * intersection:
    * union:
    * difference:

Converting
    * asSet
    * asOrdCltn

Using Blocks
    * detect:
    * detect:ifNone:
    * select:
    * reject:
    * collect:
    * count:

Making elements perform
    * elementsPerform:
    * elementsPerform:with:
    * elementsPerform:with:with:
    * elementsPerform:with:with:with:

Do Blocks
    * do:
    * do:until:

Locating
    * find:
    * contains:
    * includes:
    * occurrencesOf:

Printing
    * printOn:

Archiving
    * fileOutOn:
    * fileInFrom:
    * awakeFrom:

Methods

new
    + new

Returns a new empty Bag.

new:
    + new :(unsigned) n

Returns a new empty Bag, which can hold at least n different elements.

with:
    + with :(int) nArgs,...

Returns a new object with nArgs elements. For example,
    id aCltn = [OrdCltn with:2,anObject,otherObject];

creates a collection and adds anObject and otherObject to it. In a similar way, Set or SortCltn instances can be created like this.

with:with:
    + with : firstObject with : nextObject

This method is equivalent to with: 2, firstObject , nextObject .

add:
    + add : firstObject

This method is equivalent to with: 1, firstObject .

This (factory) method has the same name as the instance method add: and can be used as follows, in circumstances when the user does not want to allocate a collection unless it is actually used :
    aCltn = [ (aCltn)?aCltn:OrdCltn add:myObject ];

This shows that creation of the collection is delayed until it is actually needed. If the collection already exists, objects are simply added, using the instance method add: .

copy
    - copy

Returns a new copy of the Bag.

deepCopy
    - deepCopy

Returns a new copy of the Bag. The elements in the new Bag are deep copies of the elements in the original Bag.

emptyYourself
    - emptyYourself

Empties all the members of the Bag (without freeing them). Returns the receiver.

freeContents
    - freeContents

Removes and frees all the members of the Bag, but doesn't free the Bag itself. Returns the receiver.

free
    - free

Frees the Bag, but not its elements. Returns nil . Do :
    bag = [[bag freeContents] free];

if you want to free the Bag and its contents.

size
    - ( unsigned ) size

Returns the number of elements in the Bag.

If an Object was added twice, then size returns two, not one, although that the Bag internally stores only one occurence of the Object.

isEmpty
    - ( BOOL ) isEmpty

Whether the number of objects in the Bag is equal to zero.

eachElement
    - eachElement

Returns a sequence of elements in the Bag. If the multiplicity of an object in the Bag is greater than one, pointers to the same object will occur multiple times in the Sequence.
    aSeq = [aBag eachElement];
    while ((anElement = [aSeq next])) {
    /* do something */
    }
    aSeq = [aSeq free];

isEqual:
    - ( BOOL ) isEqual : bag

Returns YES if bag is a Bag, if bag has the same number of elements as the receiver, and if each member of the contents of bag is contained in the receiver's contents.

add:
    - add : anObject

Adds anObject to the Bag, and, if it's a duplicate, simply increases the multiplicity of the element. This method doesn't inform the caller about whether the Object was a duplicate, because the receiver is always returned.

addNTest:
    - addNTest : anObject

Adds anObject if it was not previously in the Bag, otherwise increases the multiplicity of the matching element. Returns anObject if it was not a duplicate, otherwise returns nil , but in either case adds the object to the Bag.

filter:
    - filter : anObject

The filter: method has a special purpose. If there is a matching object in the Bag, then anObject is freed, the multiplicity of the matching element is increased, and the matching object is returned. Otherwise, anObject is added and returned.

add:ifDuplicate:
    - add : anObject ifDuplicate : aBlock

Adds and returns anObject , if there was no duplicate previously in the Bag.

Otherwise, this method evalutes aBlock and returns the matching object (the object that was already in the Bag).

For example, the filter: method is equivalent to :
    [ Bag add: anObject ifDuplicate: { [anObject free] }];

replace:
    - replace : anObject

If a matching object is found, then anObject replaces that object, and the matching object is returned. If there is no matching object, anObject is added to the receiver, and nil is returned.

remove:
    - remove : oldObject

Removes oldObject or the element which matches it using isEqual: . Returns the removed entry, or nil if there is no matching entry.

Note: The remove: method of the OrdCltn class is implemented to remove an exact match. The Set class uses a match in the sense of isEqual: instead.

remove:ifAbsent:
    - remove : oldObject ifAbsent : exceptionBlock

Removes oldObject or the element which matches it using isEqual: . Returns the removed entry, or return value of exceptionBlock if there is no matching entry.

For example, the method remove: is equivalent to :
    [ aBag remove: oldObject ifAbsent: { nil } ];

Note: The remove: method of the OrdCltn class is implemented to remove an exact match. The Set class uses a match in the sense of isEqual: instead.

includesAllOf:
    - ( BOOL ) includesAllOf : aCltn

Answer whether all the elements of aCltn are in the receiver, by sending includes: for each individual element.

includesAnyOf:
    - ( BOOL ) includesAnyOf : aCltn

Answer whether any element of aCltn is in the receiver, by sending includes: for each individual element.

addAll:
    - addAll : aCltn

Adds each member of aCltn to the receiver. If aCltn is nil , no action is taken. The argument aCltn need not be a collection, so long as it responds to eachElement in the same way as collections do. Returns the receiver.

Note: If aCltn is the same object as the receiver, a addYourself message is sent to the object.

addContentsOf:
    - addContentsOf : aCltn

This method is equivalent to addAll: and is provided for Stepstone ICpak101 compatibility.

addContentsTo:
    - addContentsTo : aCltn

This method is equivalent to addAll: , but with argument and receiver interchanged, and is provided for Stepstone ICpak101 compatibility.

removeAll:
    - removeAll : aCltn

Removes all of the members of aCltn from the receiver. The argument aCltn need not be a collection, as long as it responds to eachElement as collections do. Returns the receiver.

Note: If aCltn is the same object as the receiver, it empties itself using emptyYourself and returns the receiver.

removeContentsFrom:
    - removeContentsFrom : aCltn

This method is equivalent to removeAll: , and is provided for compatibility with Stepstone ICpak101.

removeContentsOf:
    - removeContentsOf : aCltn

This method is equivalent to removeAll: , and is provided for compatibility with Stepstone ICpak101.

intersection:
    - intersection : bag

Returns a new Collection which is the intersection of the receiver and bag . The new Collection contains only those elements that were in both the receiver and bag . The argument bag need not be an actual Set or Bag instance, as long as it implements find: as Sets do.

union:
    - union : bag

Returns a new Collection which is the union of the receiver and bag . The new Collection returned has all the elements from both the receiver and bag . The argument bag need not be an actual Set or Bag instance, as long as it implements eachElement: as Sets and Bags do.

difference:
    - difference : bag

Returns a new Collection which is the difference of the receiver and bag . The new Collection returned has only those elements in the receiver that are not in bag .

asSet
    - asSet

Creates a Set instance and adds the contents of the object to the set.

asOrdCltn
    - asOrdCltn

Creates a OrdCltn instance and adds the contents of the object to the set.

detect:
    - detect : aBlock

This message returns the first element in the receiver for which aBlock evaluates to something that is non-nil . For example, the following :
    [ aCltn detect: { :each | [each isEqual:anObject] } ];

Returns nil if there's no element for which aBlock evaluates to something that non-nil.

detect:ifNone:
    - detect : aBlock ifNone : noneBlock

This message returns the first element in the receiver for which aBlock evaluates to something that is non-nil.

Evaluates noneBlock if there's no element for which aBlock evaluates to something that is non-nil, and returns the return value of that block. For example,
    [ aCltn detect: { :e | [e isEqual:anObject]} ifNone: {anObject} ];

select:
    - select : testBlock

This message will return a subset of the receiver containing all elements for which testBlock evaluates to an Object that is non-nil. For example,
    [ aCltn select: { :each | [each isEqual:anObject] } ];

Returns a new empty instance of the same class as the receiver, if there's no element for which testBlock evaluates to something that is non-nil.

reject:
    - reject : testBlock

Complement of select:

This message will return a subset of the receiver containing all elements for which testBlock evaluates to nil. For example,
    [ aCltn reject: { :each | [each isEqual:anObject] } ];

Returns a new empty instance of the same class as the receiver, if there's no element for which testBlock evaluates to nil.

collect:
    - collect : transformBlock

This message creates and returns a new collection of the same size and type as the receiver. The elements are the result of performing transformBlock on each element in the receiver (elements for which the Block would return nil are filtered out).

count:
    - ( unsigned ) count : aBlock

Evaluate aBlock with each of the receiver's elements as the argument. Return the number that answered a non- nil value.

elementsPerform:
    - elementsPerform :(SEL) aSelector

Send aSelector to all objects in the collection, starting from the object at offset 0 . For Stepstone compatibility. Producer uses this.

elementsPerform:with:
    - elementsPerform :(SEL) aSelector with : anObject

Send aSelector to all objects in the collection, starting from the object at offset 0 . For Stepstone compatibility. Producer uses this.

elementsPerform:with:with:
    - elementsPerform :(SEL) aSelector with : anObject with : otherObject

Send aSelector to all objects in the collection, starting from the object at offset 0 . For Stepstone compatibility. Producer uses this.

elementsPerform:with:with:with:
    - elementsPerform :(SEL) aSelector with : anObject with : otherObject with : thirdObj

Send aSelector to all objects in the collection, starting from the object at offset 0 . For Stepstone compatibility. ICpak201 uses this.

do:
    - do : aBlock

Evaluates aBlock for each element in the collection and returns self . aBlock must be a block taking one object (element) as argument; the return value of the block is ignored by this method.

Often, the Block would, as a side-effect, modify a variable, as in:
    int count = 0;
    [contents do: { :what | if (what == anObject) count++; }];

do:until:
    - do : aBlock until :(BOOL*) flag

Evaluates aBlock for each element in the collection, or until the variable pointed to by flag becomes true, and returns self . aBlock must be a block taking one object (element) as argument; the return value of the block is ignored by this method.

Typically the Block will modify the variable flag when some condition holds:
    BOOL found = NO;
    [contents do:{ :what | if (what == findObject) found=YES;} until:&found];
    if (found) { ... }

find:
    - find : anObject

Returns any element in the receiver which isEqual: to anObject . Otherwise, returns nil .

contains:
    - ( BOOL ) contains : anObject

Returns YES if the receiver contains anObject . Otherwise, returns NO. Implementation is in terms of the receiver's find: method (which uses isEqual: and hash to decide whether the object is contained in the Bag).

includes:
    - ( BOOL ) includes : anObject

This method is equivalent to contains: .

occurrencesOf:
    - ( unsigned ) occurrencesOf : anObject

Returns the multiplicity of anObject in the receiver, i.e. the number of Objects that are equal (in the sense of isEqual to anObject ), otherwise returns 0.

printOn:
    - printOn :(IOD) aFile

Prints a list of the objects in the Bag by sending each individual object a printOn: message. Returns the receiver.

fileOutOn:
    - fileOutOn : aFiler

Writes out non-nil objects in the Set on aFiler . Returns the receiver.

fileInFrom:
    - fileInFrom : aFiler

Reads in objects from aFiler . Returns the receiver, which is a Bag that is not yet usable (until the Bag gets the awakeFrom: message).

awakeFrom:
    - awakeFrom : aFiler

Rehashes the contents of the Bag, which was previously read from aFiler by the fileInFrom: method. The hash-values of the objects are possibly process or architecture dependent, so they are not stored on the filer. Rather, awakeFrom: recomputes the values.