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.74 date: 2024/02/28 15:42:43
user: cg
file: Bag.st directory: libbasic
module: stx stc-classLibrary: libbasic

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


copyright
COPYRIGHT (c) 1991 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

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.

o  withValuesAndOccurrences: aSequenceableCollection
return a new instance where the values and number of values are taken from alternating
elements of aSequenceableCollection.

This method was added at 2022-09-21.
Do not use it for #storeOn: until you know that backward compatibility will no be and issue!

Usage example(s): 

     Bag withValuesAndOccurrences:#(element1 1 element2 2 element3 3)

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.

o  cumulativeCounts
Answer with a collection of cumulative percents covered by elements so far.

Usage example(s): 

     #(10 20 30 10 20 30 40 50 60 70) asBag cumulativeCounts  => #(20.0->30 40.0->20 60.0->10 70.0->60 80.0->50 90.0->40 100.0->70)

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

o  sortedElements
Answer with a collection of elements with counts, sorted by element.

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.

Usage example(s): 

     |b|

     b := Bag new.
     b add:1; add:2; add:3; add:2; add:1.
     Transcript showCR:b.

     b removeAll.

     Transcript showCR:b

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.

o  testAndAdd: newObject
Test, if the element is present in the receiver.
Answer true, if the element was already in the collection.
Whether or not the element does exist, add it to the collection
or increment the element count.
This saves an extra #findKeyOrNil: search against sending #includes: and add:.

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

Usage example(s): 

     |b|

     b := Bag new.
     b add:1; add:2; add:3; add:1; add:1.
     b asSet.

copying-private
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  valuesAndCountsCollect: aTwoArgBlock
evaluate the block for all distinct elements in the collection,
passing both the element and the occurrence count as arguments.
Collect the results from the block.

Usage example(s): 

     #(10 20 20 30 40) asBag
        valuesAndCountsCollect:[:eachValue :eachCount | eachValue->eachCount]

o  valuesAndCountsDetect: aTwoArgBlock ifNone: exceptionValue
evaluate the block for all distinct elements in the collection,
passing both the element and the occurrence count as arguments.
If any returns true, return an association consisting of value and occurrence count.
If not, return the value from exceptionValue.

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
        valuesAndCountsDetect:[:eachValue :eachCount | eachCount > 1]
        ifNone:nil     

     #(10 20 20 30 40) asBag
        valuesAndCountsDetect:[:eachValue :eachCount | eachCount > 3]
        ifNone:nil

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
(comment from inherited method)
perform aBlock (1 arg) for all elements.
Used in #printOn:.
Subclasses (e.g. Dictionary) may redefine this.

o  storeOn: aStream
output a printed representation onto the argument, aStream.
The text can be re-read to reconstruct (a copy of) the receiver.
Recursive (i.e. cyclic) collections cannot be stored correctly
(use storeBinaryOn: to handle those).

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

o  storeNamedInstvarsOn: aStream
store the named instvars of the receiver on aStream;
i.e. print expressions which will set the instvars using instVarAt:put:.
Will not store nil values;
you may need a #yourself at the end
(returns true, if any expression was generated; which implies that a #yourself is needed)
This is a helper/code saver for storeOn:, not meant for public use

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

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

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


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 00:41:16 GMT