Class: Bag

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
• Instance protocol
  • Compatibility-Dolphin
  • accessing
  • adding & removing
  • bulk operations
  • comparing
  • converting
  • copying
  • enumerating
  • printing & storing
  • private
  • queries
  • testing

Inheritance:

   Object
   |
   +--Collection
      |
      +--Bag

Package:

stx:libbasic

Category:

Collections-Unordered

Version:

rev: 1.41 date: 2010/03/30 13:38:23

user: stefan

file: Bag.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Bag implements collections whose elements are unordered and have no
external key. Elements may occur more than once in a bag. There is no defined
order within a bag.
The default implementation uses a dictionary to store each objects occurrence
count, using the object itself as key (i.e. using = and hash for inclusion
tests).

There is also an instance creation variant (#identityNew:) creating a
bag which compares using #== and hashes using #identityHash.
(I'd say that an IdentityBag was a better thing to implement ...
 ... but for compatibility ... we do it here as well)

[Instance variables:]

    contents        <Dictionary>    for each element, the number of occurrences

Related information:

    Set
    IdentitySet
    Dictionary
    IdentityDictionary
    OrderedCollection
    Array

Class protocol:

 equalityNew: size

return a new empty Bag with initial space for size elements.
Elements will be compared using equality compare (i.e. #= not #== identity).

 identityNew

return a new empty Bag which compares for identity
Elements will be compared using identity compare (i.e. #== not #= equality).

 identityNew: size

return a new empty Bag with initial space for size elements.
Elements will be compared using identity compare (i.e. #== not #= equality).

 new

return a new empty Bag which compares for equality (i.e. not identity)

 new: size

return a new empty Bag with initial space for size elements.
Elements will be compared using equality compare (i.e. #= not #== identity).

Instance protocol:

 asAssociations

return the dictionary which associates occurrence-counts
to the bags elements.
Same as #contents for dolphin compatibility.

 at: index

report an error: at: is not allowed for Bags

 at: index put: anObject

report an error: at:put: is not allowed for Bags

 contents

return the dictionary which associates occurrence-counts
to the bags elements.

 add: newObject

add the argument, anObject to the receiver.
Returns the object.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 add: newObject withOccurrences: anInteger

add the argument, anObject anInteger times to the receiver.
Returns the object.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 remove: oldObject ifAbsent: anExceptionBlock

Remove oldObject from the collection.
If it was not present, return the value of the exceptionBlock;
otherwise return the removed object.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 removeAll

remove all objects from the receiver collection (i.e. make it empty).
Returns the receiver.

 removeAllOccurrencesOf: oldObject ifAbsent: anExceptionBlock

Remove all occurrences of oldObject from the collection.
If it was not present, return the value of the exceptionBlock;
otherwise return the number of removes.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 sum

sum up all elements; return 0 for an empty collection.
can be done easier, using bags knowledge.

 = aBag

Compare the receiver with the argument and return true if the
receiver is equal to the argument (i.e. has the same size and elements).
Otherwise return false.

 hash

return an integer useful for hashing on the receiver;
redefined since = is redefined here.

 asBag

return the receiver as a bag

 asSet

return the receiver as a set

 postCopy

must copy the contents as well

 do: aBlock

evaluate the block for all elements in the collection.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 valuesAndCounts

return an orderedCollection containing value->count associations

 valuesAndCountsDo: aTwoArgBlock

evaluate the block for all distinct elements in the collection,
passing both the element and the occurrence count as arguments.

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 printElementsDo: aBlock

 initContents

set the contents to be an empty Dictionary

 initContents: size

set the contents to be an empty Dictionary with initial size

 initContentsForIdentity

set the contents to be an empty IdentityDictionary

 initContentsForIdentity: size

set the contents to be an empty IdentityDictionary with initial size

 size

return the number of bag elements

 includes: anObject

return true, if anObject is in the receiver

 occurrencesOf: anObject

return how many times anObject is in the receiver