A newer version of Max is available. Click here to access the latest version of this document.

coll

Store and edit a collection of different messages

Description

coll allows for the storage, organization, editing, and retrieval of different messages.

Arguments

Name Type Opt Description
filename any symbol opt Name of a file to be read into coll automatically when the patch is loaded. The information in the file must be in the correct format in order to be read in by coll. All coll objects which share the same name always share the same contents. You can use the file name as an identifier for the purpose of sharing data between multiple coll objects, without there needing to be an actual file with the specified name.

For information about using named objects in Max for Live, click here.

An optional second argument will cause the coll object not to search for a file with the named symbol.

Messages

bang Same effect as the next message.
int index [int]
The number refers to the address of a message stored in coll. If a message is stored at that address, the stored message is sent out the 1st outlet.
float index [float]
The number refers to the address of a message stored in coll. If a message is stored at that address, the stored message is sent out the 1st outlet.
list index and data [list]
The first number is used as the address (the storage location within coll) at which to store the remaining items in the list (coll can store a list of up to 32766 items). The address will always be stored as an int.
anything index [list]
Functions the same as with a symbol message.
assoc address name [symbol]
data index [int]
The word assoc, followed by a symbol and a number, associates the symbol with the address specified by the number, provided that the number address already exists. From then on, any reference to that symbol will be interpreted by coll as a reference to the number address. Each number address can have only one symbol associated with it, except 0, which cannot have an associated symbol. (Note: If the symbol was already being used as an address, or was already associated with a number address, the message that was stored at that address is removed.)
deassoc address name [symbol]
data index [int]
The word deassoc, followed by a symbol and a number, removes the association between the symbol and the number address. The symbol no longer has any meaning to coll.
delete index [list]
Functions similarly to the word remove, except that if the specified address is a number, all addresses of a greater number are decremented by 1.
clear Erases everything from the collection.
(mouse) Double-clicking with the mouse on the coll object displays the contents as text in an editing window which the user can modify.
dump Sends all of the stored addresses out the 2nd outlet and all of the stored messages out the 1st outlet, in the order in which they are stored. A bang is sent out the 4th outlet when the dump is completed.
end Sets the pointer (used by the goto, next, and prev messages) to the last address in the coll.
goto index [list]
The word goto, followed by a number or a symbol, sets a pointer at the address specified by the number or symbol. If no such address exists, the pointer is set at the beginning of the collection. The pointer is set at the beginning of the collection initially, by default. The data associated with the given number or symbol will be output in response to a subsequent bang, next, or prev message; the goto message sets the pointer, but does not cause output.
filetype filetype [symbol]
The word filetype, followed by a symbol, sets the file types which can be read and written into the coll object. File types are specified using the standard four-letter type code combination (e.g. filetype ffoo). The message filetype with no arguments restores the default file behavior. File types are mapped to filename extensions on Windows (or mac when no type is specified by OS) based on the messages to max contained in the file max-fileformats.txt in the init folder, which is loaded on startup. If you are defining your own filetype, you may want to include your own text file in the init folder in order to specify a mapping between an extension and your four-letter type code.
flags save-setting (0 or 1) [int]
save-setting (0 or 1) [int]
Normally, the contents of coll are not saved as part of the patch when the patcher window is closed. The message flags 1 0 sets the coll object to save its contents as part of the patcher that contains it. The message flags 0 0 causes the contents of the coll not to be saved with the patcher that contains it.
insert index and data [list]
The word insert, followed by a number and a message, inserts the message at the address specified by the number, incrementing all equal or greater addresses by 1 if necessary.
insert2 index and data [list]
The word insert2, followed by a number and a message, inserts the message at the address specified by the number, incrementing all equal or greater addresses by 1 if necessary.
length Counts the number of messages contained in coll and sends the number out the 1st outlet. This message works well in conjunction with the grab object.
next Sends the address pointed to by the pointer out the second outlet, and sends the message stored at that address out the 1st outlet, then sets the pointer to the next address. If the address is a symbol rather than a number, 0 is sent out the second outlet. If the pointer is currently at the last address in the collection, it wraps around to the first address. (Note: Number addresses are stored in ascending order. Symbol addresses are stored in the order in which they were added to the collection, after all of the number addresses.) If the message received immediately prior to next was prev, next sends out the value stored at the address one greater than the one that was just sent out.
nstore index and data [list]
The word nstore, followed by a number and a symbol (or a symbol and a number), followed by any other message, stores the message at the specified number address in the coll, with the specified symbol associated. (This has the same effect as storing the message at an int address, then using the assoc message to associate a symbol with that number.)
max maximum [int]
Determines the maximum single numerical value (i.e. not a list or symbol) stored in the coll and sends the number out the 1st outlet. This message works well in conjunction with the grab object.
merge index and data [list]
The word merge, followed by an address and a message, appends its message at the end of the message already stored at that address. If the address does not yet exist, it is created.
nth index and list-element-number [list]
The word nth, followed by an address and a number, gets the nth item (specified by the number) from the message at that address, and sends it out the 1st outlet. (Example: nth pgms 4 outputs the 4th item in the message stored at the address named pgms.)
nsub index and data [list]
The word nsub, followed by an address, an item number, and another number or symbol, replaces one item stored at the address. (Example: nsub pgms 4 7 puts the number 7 in place of the 4th item of the message stored at the address pgms.) Number values and symbols can both be substituted in this manner.
min minimum [int]
Determines the minimum single numerical value (i.e. not a list or symbol) stored in the coll and sends the number out the 1st outlet. This works well in conjunction with the grab object.
prev Causes the same output as the word next, but the pointer is then decremented rather than incremented. If the pointer is currently at the first address in the collection, it wraps around to the last address. If the message received immediately prior to prev was next, prev sends out the value stored at the address one less than the one that was just sent out.
open Causes a text edit window associated with the coll object to become visible. The window is also brought to the front.
separate data index [int]
The word separate, followed by a number that specifies the index for coll data, "separates" the contents of the coll by incrementing the numerical indices for all data whose index is greater than the number. Here's a before and after example for coll sent the message separate 2.

Before:
0, apple;
1, banana;
2, cherry;
3, durian;

After:
0, apple;
1, banana;
3, cherry;
4, durian
sort sorting flag (-1 or 1) [int]
sorting flag (-1 0 or 1) [int]
The sort message takes two arguments. If the first argument is -1, the items in the coll are sorted in ascending order. If the first argument is 1, the items in the coll are sorted in descending order.

The second argument specifies what is used to sort the contents of the coll. If the second argument is -1, the index (or symbol) associated with the data is used. If the second argument is not present or 0, the first item in the data is used. If the second argument is 1 or greater, the second (or greater) item in the data is used.
start Sets the pointer (used by the goto, next, and prev messages) to the first address in the coll.
store index and data [list]
The word store, followed by some symbol (usually a word), followed by a message, stores the message at an address named by the symbol. (Example: store triad 0 4 7 will store the list 0 4 7 at an address named triad.)
subsym new address name [symbol]
old address name [symbol]
Changes the symbol associated with data. The first argument to subsym is the new symbol to use, and the second argument is the symbol associator to replace. For instance, if the coll contains
jill, 40 50 60;
subsym jack jill will change the coll to
jack, 40 50 60;
swap pair of indices [list]
The swap message takes two symbols or two numbers as addresses, and exchanges the indices associated with each address. For example, if the coll contains
1, 400;
2, 700;
swap 1 2 would change the coll to
2, 400;
1, 700;
symbol index [symbol]
The symbol refers to the address of a message stored in coll. If a message is stored at the address named by the symbol, the message is sent out the 1st outlet. The symbol may, but need not necessarily, be preceded by the word symbol.
read filename [symbol]
The word read with no arguments puts up a standard Open Document dialog box for choosing a file to load into coll. If read is followed by a symbol filename argument, the named file is located and loaded into coll.
readagain Loads in the contents of the most recently read file. If no prior read or readagain message has been received by the coll, readagain is treated as a read message, and an Open Document dialog box is displayed.
refer referenced coll-object name [symbol]
The word refer, followed by the name of another coll object, changes the coll receiving the message to refer to the data in the named coll object.

In addition to reading messages in from another file and storing messages via the inlet, one can also enter messages in coll by typing. Double-clicking with the mouse on the coll object displays the contents as text in an editing window which the user can modify.

In order to edit a collection by hand or read in from another file, it is essential to know the correct text format for the contents of a coll object. Each message is stored in the coll object on a separate line. The format of each line is as follows: the address (an int or a symbol), any symbols associated with that address (if the address is an int), a comma (to separate the address from the data it contains), the data (anything), and a semicolon to indicate the end of each line. In a line such as
remove index [list]
The word remove, followed by a number or a symbol, removes that address and its contents from the collection.
sub index [list]
Same as nsub, except that the message stored at the specified address is sent out after the item has been substituted.
renumber data index [int]
Makes the numbers associated with the data in the coll object consecutive and increasing. An optional argument to the renumber message specifies the starting number address for the data. Here's a before and after example for coll sent the message renumber1.

Before:
4, apple;
6, banana;
3, cherry;
9, durian;

After:
1, apple;
2, banana;
3, cherry;
4, durian;
renumber2 data index [int]
The renumber2 message increments the indices associated with the data in the coll object by one. Here's a before and after example for coll sent the message renumber2.

Before:
2, apple;
4, banana;
6, cherry;
12, durian;

After:
3, apple;
5, banana;
7, cherry;
13, durian;
wclose Closes the window associated with the coll object.
write filename [symbol]
Calls up the standard Save As dialog box, enabling the user to save the contents of coll as a separate file. If the word write is followed by a symbol, the contents of the coll are saved immediately in a file, using the symbol as the filename.
writeagain Saves the contents of the coll into the most recently written file. If no prior write or writeagain message has been received by the coll, writeagain is treated as a write message, and a Save As dialog box is opened.

Attributes

Name Type g/s Description
embed int Toggles the ability to embed the contents of the coll you are using and save it as part of the main patch. This value can only be set using the Save Data with Patcher setting in the coll object's Inspector. The default behavior is 0 (don't save the data with the patch).

Information for box attributes common to all objects

Output

anything: Messages stored in coll are sent out the 1st outlet. If the message consists of only a single symbol, it will be preceded by the word symbol when it is sent out.
bang: Out 3rd outlet: Sent out when coll has finished loading in or writing a file of data.

Out 4th outlet: Sent out when coll has finished sending all of the stored addresses and messages in order out the 1st and 2nd outlets in response to a dump message.
int: Out 1st outlet: The number of messages contained in coll is sent out in response to the length message.
int or symbol: Out 2nd outlet: The address is sent out whenever a message out the 1st outlet is triggered by bang, dump, next, prev, or sub.

Examples

Complex messages can be recalled with a single number or word... Results for successive next and prev messages

See Also

Name Description
bag Store a collection of numbers
itable A table in a patcher window
jit.cellblock Two-dimensional storage and viewing
table Store and graphically edit an array of numbers
funbuff Store x,y pairs of numbers together
Max Basic Tutorial 18: Data Collections Max Basic Tutorial 18: Data Collections
Max Data Tutorial 3: Gesture Capture Max Data Tutorial 3: Gesture Capture