coll

Store and edit a collection of data

Description

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

Examples

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

Arguments

name [symbol]

Optional

Determines the named context of the coll object. All coll objects that share the same name share their contents. When a patch containing a named coll is loaded, Max will search for a file that matches the name; if found, the file is automatically loaded.

Optional

An optional nonzero value as a second argument will prevent the coll object from searching for a file with the named symbol.

Attributes

embed [int]

Toggles the ability to embed the contents of the coll as part of the main. This value can only be set using the Save Data with Patcher setting in the Object Inspector. The default behavior is 0 (don't save the data with the patch).

Common Box Attributes

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points).

Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [float]

Sets the color for the object's text in RGBA format.

textjustification [int]

Text Justification

Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Messages

bang

See the next listing.

int

Arguments

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

float

Arguments

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

list

Arguments

index [int]
data [list]
The first value is used as the address (the storage location within coll) at which to store the remaining items in the list. The address will always be stored as an int.

anything

Arguments

index [any]
See the symbol listing.

assoc

Arguments

address name [symbol]
data index [int]
Associates a symbol with the numeric address, provided that the number address already exists. After association, any reference to that symbol will be interpreted as a reference to the number address. Each number address can have only one symbol associated with it.

deassoc

Arguments

address name [symbol]
data index [int]
Removes the association between a symbol and the number address. The symbol will no longer have any meaning to coll.

delete

Arguments

index [any]
Removes the data at the address provided. If the specified address is numeric, all higher numbered addresses are decremented by 1.

clear

Clear all data

(mouse)

Double-click on the coll object to display the contents as text in an editing window. The data can be manually edited within this editor.

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 (as used by the goto, next, and prev messages) to the last address.

goto

Arguments

index [list]
Sets the pointer (as used by the goto, next, and prev messages) at a specific address, but does not trigger output. If the specified address does not exist, the pointer is set at the beginning of the collection. Data will be output in response to a subsequent bang, next, or prev message.

filetype

Arguments

filetype [symbol]
Sets the file types which can be read and written into the coll object. The message filetype with no arguments restores the default file behavior.

flags

Arguments

save-setting [int]
unused [int]
Sets the flags used to save its contents within the patch that contains it. The message flags 1 0 notifies the object to save its contents as part of the patcher file. The message flags 0 0 causes the contents not to be saved.

insert

Arguments

index [int]
data [list]
Inserts the message at the address specified by the number, incrementing all equal or greater addresses by 1 if necessary.

insert2

Arguments

index [int]
data [list]
See the insert listing.

length

Counts the number of entries contained in the coll and sends the number out the 1st outlet.

next

Sends the address and data stored at the current address, then sets the pointer to the next address. If the pointer is currently at the last address in the collection, it wraps around to the first address. If the address is a symbol rather than a number, 0 is sent out the second outlet.

nstore

Arguments

index [int]
association [symbol]
data [list]
Stores the message at the specified number address, 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

Arguments

element [int]
Gets the highest value in any entry. An optional integer argument (defaults to '1') specifies an element position to use.

merge

Arguments

index [int]
data [list]
Appends data at the end of the data found at the specified index. If the address does not yet exist, it is created.

nth

Arguments

index [int]
position [int]
Returns the data element found at a specific position in the stored list and send it out the first outlet. As an example, nth 75 2 will output the second item in the list stored at address 75.

nsub

Arguments

index [int]
position [int]
data [any]
Replaces a data element with a new value. As an example, nsub 2 4 7 replaces the fourth element of address 2 with the value 7. Number values and symbols can both be substituted in this manner.

min

Arguments

element [int]
Gets the lowest value in any entry. An optional integer argument (defaults to '1') specifies an element position to use.

prev

Sends the address and data stored at the current address, then sets the pointer to the previous address. If the pointer is currently at the first address in the collection, it wraps around to the last address. If the address is a symbol rather than a number, 0 is sent out the second outlet.

open

Opens a data editing window for the current data and bring it into focus.

separate

Arguments

data index [int]
Increments the numerical indices for all data whose index is greater than the provided. This creates an open 'slot' for a subsequent add.

sort

Arguments

sort order (-1 or 1) [int]
entry (-1, 0, or 1) [int]
Sorts the data into a specified order. If the first argument is -1, the items are sorted in ascending order. If the first argument is 1, the items are sorted in descending order.
The second argument specifies what data is used to sort the contents. If the second argument is -1, the index (either number or symbol) associated with the data is used. If the second argument is not present or is 0, the first item in the data is used. If the second argument is 1 or greater, that data elements is used for the sorting order.

start

Sets the pointer (used by the goto, next, and prev messages) to the first address in the coll.

store

Arguments

index [symbol]
data [list]
Stores the message at an address named by the provided symbol. As an example, store triad 0 4 7 will store 0 4 7 at an address named triad.

subsym

Arguments

new name [symbol]
old name [symbol]
Changes the symbol associated with data. The first argument is the new symbol to use, the second argument is the symbol associator to replace.

swap

Arguments

index [int]
index [int]
Exchanges the indices associated with two addresses. The data is unchanged, but the indexes that they use are swapped.

symbol

Arguments

index [symbol]
Retrieves a message stored at the address named by the symbol. If no address is associated with the symbol, no output is produced.

read

Arguments

filename [symbol]
With no arguments, read puts up a standard Open Document dialog box to choose a file to load. If an argument is provided, the named file is loaded.

readagain

Loads the contents of the most recently read file. If no prior file load has occurred, the request is treated like a read message.

refer

Arguments

object name [symbol]
Changes the reference to the data in another named coll object. Changes to the data stored in any referenced coll will be shared by all other similarly named objects.

remove

Arguments

index [any]
Removes that address and its contents from the collection.

sub

Arguments

index [int]
position [int]
data [list]
Same as nsub, except that the message stored at the specified address is sent out after the item has been substituted.

renumber

Arguments

data index [int]
Renumbers data entries as consecutive and in increasing order. The optional argument specifies the starting number address for the data.

renumber2

Arguments

data index [int]
Increment indices by one

wclose

Close the data editing window

write

Arguments

filename [symbol]
With no arguments, write puts up a standard Open Document dialog box to choose a filename to write. If an argument is provided, the name is used as a filename for storage.

writeagain

Saves the contents to the most recently written file. If no prior file write has occurred, the request is treated like a write message.

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 reading in 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.

See Also

Name Description
bag Store a collection of numbers
itable Data table editor
jit.cellblock Edit rows and columns of data
table Store and edit an array of numbers
funbuff Store pairs of numbers
Max Basic Tutorial 18: Data Collections Max Basic Tutorial 18: Data Collections
Max Data Tutorial 3: Gesture Capture Max Data Tutorial 3: Gesture Capture