SuperCollider CLASSES

Bag

Unordered collection of objects
Inherits from: Collection : Object
Subclasses: IdentityBag

Description

A Bag is an unordered collection of objects. In some languages it is referred to as a counted set. A Bag keeps track of the number of times objects are inserted and requires that objects be removed the same number of times. There is only one instance of an object in a Bag even if the object has been added to the Bag multiple times (test is for equality)

Most of Bag's methods are inherited from Collection. The contents of a Bag are unordered. You must not depend on the order of items in a set.

Class Methods

*new (n: 4)

Creates a Bag with an initial capacity for n objects.

Inherited class methods

Instance Methods

-contents

Returns the dictionary that stores the objects in pairs (obj -> numberOfObjects)

Bag["a", "b", "c", "c"].contents;

Returns:

-itemCount (item)

Count the number of items.

Bag[1, 2, 2, 3, 300, 2].itemCount(2);

Adding and Removing

-add (item, count: 1)

Add an object to the Bag. A Bag may contain multiple entries of the same object.

Bag[1, 2, 3].add(4).postln;

Bag[1, 2, 3].add(3).postln;

Bag["abc", "def", "ghi"].add("jkl").postln;

Bag["abc", "def", "ghi"].add("def").postln;

-remove (item, count: 1)

Remove an object from the Bag.

Bag[1, 2, 3].remove(3).postln;

Iteration

-do (function)

Evaluates function for each item in the Bag. The function is passed two arguments, the item and an integer index.

Bag[1, 2, 3, 300].do({ arg item, i; item.postln });

Bag[1, 2, 2, 3, 300].do({ arg item, i; item.postln });

Arguments:

function

args to function: item, i

-countsDo (function)

Evaluates function for each unique item in the Bag along with that item's count. The function is passed two arguments, the item, the quantity of that item in the Bag and an integer index.

Bag[1, 2, 3, 300].countsDo({ arg item, count, i; [item,count].postln });

Bag[1, 2, 2, 3, 300].countsDo({ arg item, count, i; [item,count].postln });

Testing

-includes (item)

Answer whether an object is contained in the Bag.

Bag[1, 2, 3, 4].includes(3);

Returns:

Inherited instance methods

Undocumented instance methods

-asBag

-at

-atFail

-choose

-put

-take

-wchoose

Examples

Difference between Bag and IdentityBag:

// the two strings are equal, but not identical
"something" == "something"; // true
"something" === "something" // false

a = Bag.new;
a.add("something");
a.add("something");
a.contents; // only one object in the bag really

a = IdentityBag.new;
a.add("something");
a.add("something");
a.contents; // two objects in the bag