Class: Bag

• Inheritance
• Description
• 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.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:

 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.

 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:

 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.

 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)

 sortedCounts

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

 sortedElements

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

 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.

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

 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.

 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.

 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

Usage example(s):

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

 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

 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]

 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

 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

(comment from inherited method)
perform aBlock (1 arg) for all elements.
Used in #printOn:.
Subclasses (e.g. Dictionary) may redefine this.

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

 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

 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

 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