Class: Bag

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

Inheritance:

   Object
   |
   +--Collection
      |
      +--Bag
         |
         +--IdentityBag
         |
         +--SmallBag

Package:

stx:libbasic

Category:

Collections-Unordered

Version:

rev: 1.60 date: 2019/05/27 13:04:23

user: cg

file: Bag.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Bags are collections where the 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 object's occurrence count, 
using the object itself as key 
(i.e. using = and hash for inclusion tests).

There is also an instance creation variant (#identityNew:) which creats a
bag which compares using #== and hashes using #identityHash.
(I'd say that instantiating an IdentityBag explicitly is better,
 ... 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:

 contentsClass

the default class to use for the underlying contents array,
used when instantiated with new/new:

 equalityNew

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

 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 Identity-Bag.
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).

 newWithCapacity: size

return a new empty Collection with capacity for n elements.

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.

usage example(s):

Bag new add:'abc'; add:'def'; add:'ghi'; add:'abc'; add:'def'; add:'abc'; add:'abc'; contents

 sortedCounts

Answer with a collection of counts associated to elements, sorted by decreasing count.

usage example(s):

Bag new add:'abc'; add:'def'; add:'ghi'; add:'abc'; add:'def'; add:'abc'; add:'abc'; sortedCounts

 valuesSortedByCounts

Answer with a collection of values, sorted by decreasing count.
Count informtion is lost in the result

usage example(s):

Bag new add:'abc'; add:'def'; add:'ghi'; add:'abc'; add:'def'; add:'abc'; add:'abc'; valuesSortedByCounts

 add: newObject

add the argument, anObject to the receiver.
Returns the object (sigh).

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 one occurrence of 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.

usage example(s):

TestCase assert:((Bag new add:1; add:2; add:3; add:1; add:2; add:1; yourself) sum = 10).

 = 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.

 keysAndValuesDo: 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.

 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.

 valuesAndCountsSelect: aTwoArgBlock

evaluate the block for all distinct elements in the collection,
passing both the element and the occurrence count as arguments.
If that returns true, add the element to the OrderedCollection.
Answer the OrderedCollection.

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

usage example(s):

#(10 20 20 30 40) asBag valuesAndCountsSelect:[:eachValue :eachCount | eachCount > 1]

 inspectorExtraAttributes
( an extension from the stx:libtool package )

extra (pseudo instvar) entries to be shown in an inspector.

 printElementsDo: aBlock

 grow: newSize

ignored here

 initContents

set the contents to be an empty Dictionary.
This is the default method for initialization, which can be redefined in subclasses.

 initContents: size

set the contents to be an empty Dictionary with initial size.
This is the default method for initialization, which can be redefined in subclasses.

 initContentsForEquality

set the contents to be an empty Dictionary

 initContentsForEquality: 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

 includes: anObject

return true, if anObject is in the receiver

 occurrencesOf: anObject

return how many times anObject is in the receiver

 size

return the number of bag elements

 variance

compute the variance over a complete data set (and not of a sample)

usage example(s):

TestCase assert:( #(1 1 1 2 2 2 1 1 1 2 2 2) asBag variance = #(1 1 1 2 2 2 1 1 1 2 2 2) variance). TestCase assert:( #(1 1 1 1 1 0 0 0 0 0) asBag variance = #(1 1 1 1 1 0 0 0 0 0) variance).

 isFixedSize

return true if the receiver cannot grow

 isOrdered

return true, if the receiver's elements are ordered.
Redefined to return false here, because the order of keys and values
may change due to rehashing, when elements are added/removed