title:: Generic Collectors
categories:: Language, Common methods
summary:: Methods that incrementally build up collections from nothing

You can see which classes implement a specific method by clicking on the method name.

There are a number of methods that incrementally build up (or reduce down) collections like arrays or events. Nil responds by creating a collection, so that variables do not need to be initialized. Nil is just the "ground" (default case) from which the rest is bootstrapped.

method::add
Returns an array with the value. This makes it unnecessary to initialize when adding to a variable.
code::
x = nil;
x = x.add(8);  // returns an array
x = x.add(7); // appends to the array
::

method::addAll
Returns an array with all the values. This makes it unnecessary to initialize when adding to a variable.
code::
x = nil;
x = x.addAll([0, 2, 1, 2]);  // returns an array
x = x.addAll(7); // single objects are converted to an array and appended
::

method::remove
For nil, it just returns nil. This makes it unnecessary to initialize when removing from a variable and adding to it again.
code::
x = nil;
x.remove(1); // stays nil, returns nil
x = x.addAll([0, 2, 1]);  // returns an array
x.remove(1); // returns 1
x;
::

method::++
Returns an array with all the values. This makes it unnecessary to initialize when adding to a variable.
code::
x = nil;
x = x ++ [7, 8, 9]; // returns the receiver
x = x ++ [3, 0, 1, 2]; // adds to the array
::
note:: Note that, unlike with addAll, the second operand must be a collection in order to function in this way.::

method::addFunc
Returns a function or a FunctionList.
This method is used to add multiple functions to already existing ones.
code::
f = nil;
f = f.addFunc { "----------****".scramble };
f = f.addFunc { 1.0.rand };
f.value;

// a typical use case for addFunc is where you have to add functionality to an already existing one.
(
w = Window("move me", Rect(300, 300, 600, 40)).front; w.addFlowLayout;
a = Slider(w, Rect(0, 0, 580, 30));
a.action = a.action.addFunc { "I am moved".postln };
)
a.action = a.action.addFunc { "I am so very moved".postln };
a.addFuncTo(\action, { "Now, I am finally really moved".postln }); // shorter alternative
::

method::removeFunc
This method is used to remove multiple functions from already existing ones. For Nil, it just returns itself.

code::
f = { 1.0.rand };
g = { "you have produced a random value".postln };
f = f.addFunc(g);
f.value;
f.removeFunc(g);
f.value;
::


method::transformEvent
This method is used to operate on events which are passed through the system as an argument.

code::
// for Nil: return the argument unmodified (an event).
nil.transformEvent((x: 8));
// for Dictionary (and thus for Event): add to the argument.
(y: 100, z: 1).transformEvent((x: 8));
// for Association: add the association to the event
(\a -> \x).transformEvent((x: 8));
// for Function: use the function receive the event as argument.
{ |event| event.use { ~x = ~x + 1 }; event }.transformEvent((x: 8));
::