substitute

Substitute a symbol for another symbol in a message

Description

substitute will take any message, attempt to match it to its own arguments specifying a match-to-substitute pair, and whenever it finds a match, will make the appropriate substitution for the matched message.

Arguments

Name Type Opt Description
match anything opt The first number or symbol specifies the match, which identifies what should be replaced in an incoming message. The default match value is 0.
replacement anything opt The second number or symbol specifies the replacement for the match. The default replacement value is 0.
replace-message-only-mode anything opt Any third number or symbol sets the "replace message only" mode of the substitute object. Only the first instance of the specified match will be replaced.

Messages

bang Same as anything.
int input [int]
Same as anything.
float input [float]
Same as anything.
list match or match-replacement-pair [list]
Same as anything.
anything input [list]
In left inlet: The input is echoed to the output, but if the message received contains an element matching the match symbol or number, the element is replaced by the replacement symbol or number when the message is repeated to the output.

In right inlet: The substitute object accepts a message of two numbers or symbols in its right inlet. The first number or symbol specifies the match, which identifies what should be replaced in an incoming message.
set match or match-replacement-pair [list]
In left inlet: Same as anything.
In right inlet: Same as anything, except that the word set is ignored.

Information for box attributes common to all objects

Output

anything: Out left outlet: The input message is echoed to the output with elements matching the match symbol or number replaced by the replacement number or symbol.
bang: Out right outlet: If no substitution occurred when sending out the incoming message, a bang is sent.

Examples

substitute can translate messages output by one object to what's expected by another object

See Also

Name Description
route Selectively pass the output out a specific outlet
sprintf Format a message of words and numbers
zl Multi-purpose list processing