eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Bag':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Bag


Inheritance:

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

Package:
stx:libbasic
Category:
Collections-Unordered
Version:
rev: 1.58 date: 2017/10/10 16:06:26
user: stefan
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:

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

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

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

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

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

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

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

o  newWithCapacity: size
return a new empty Collection with capacity for n elements.


Instance protocol:

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

accessing
o  at: index
report an error: at: is not allowed for Bags

o  at: index put: anObject
report an error: at:put: is not allowed for Bags

o  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

o  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

o  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   

adding & removing
o  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.

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

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

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

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

bulk operations
o  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).

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

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

converting
o  asBag
return the receiver as a bag

o  asSet
return the receiver as a set

copying
o  postCopy
must copy the contents as well

enumerating
o  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.

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

o  valuesAndCounts
return an orderedCollection containing value->count associations

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

o  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] 

inspecting
o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

printing & storing
o  printElementsDo: aBlock

private
o  grow: newSize
ignored here

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

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

o  initContentsForEquality
set the contents to be an empty Dictionary

o  initContentsForEquality: size
set the contents to be an empty Dictionary with initial size

o  initContentsForIdentity
set the contents to be an empty IdentityDictionary

o  initContentsForIdentity: size
set the contents to be an empty IdentityDictionary with initial size

queries
o  size
return the number of bag elements

statistical functions
o  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).

testing
o  includes: anObject
return true, if anObject is in the receiver

o  isFixedSize
return true if the receiver cannot grow

o  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

o  occurrencesOf: anObject
return how many times anObject is in the receiver



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Tue, 20 Nov 2018 15:48:18 GMT