Math

Math#

Arithmetic, comparison, conversion, scaling and analysis of numbers.

69 objects. Every entry is pulled directly from the engine registry, which reads the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects. Links into the patcher guide (messages, time, data, files, …) lead to the libYSE documentation, which also has this category’s page.

`.!-`#

Subtracts the left operand from the right one and sends right - left as a float: .- with the operands the other way round.

Dart:: Obj.gReverseSubtract
Kind:: Control-rate

Use it when the value that should trigger the calculation is the one being subtracted:

[.!- 100]   30 -> left inlet  =>  70

The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand, the value subtracted; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	right - left.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.!/`#

Divides the right operand by the left one and sends right / left as a float: ./ with the operands the other way round. A left operand of 0 sends 0.

Dart:: Obj.gReverseDivide
Kind:: Control-rate

Use it when the value that should trigger the calculation is the divisor. A left operand of 0 sends 0.

[.!/ 1]   4 -> left inlet  =>  0.25

The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand, the divisor; sends the result. 0 makes the result 0.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	right / left, or 0 when left is 0.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.!=`#

Sends 1 when the left operand differs from the right one, otherwise 0.

Dart:: Obj.gNotEqual
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left != right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.%`#

Sends the remainder of dividing the left operand by the right one, as an int. The remainder has the sign of the left operand, and a divisor of 0 sends 0.

Dart:: Obj.gModulo
Kind:: Control-rate

Works on whole numbers: a float on either inlet is truncated toward zero first, so 7.9 counts as 7. The remainder has the sign of the left operand, so -1 stays -1 rather than wrapping round:

[.% 12]   14  =>  2
[.% 12]   -1  =>  -1

To wrap a number that can go negative into a range, use .pong with mode 2 (.pong 0 12 2), which sends 11 for -1. A divisor of 0 sends 0. .div sends the quotient that goes with the remainder. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Dividend; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Divisor, stored for the next result. Floats are truncated toward zero; 0 makes the result 0.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The remainder of left / right, or 0 when right is 0.

Parameters

Name	Default	Range	Description
right	0	any int	Starting divisor.

`.&`#

Bitwise AND of two integers, sent as an int. Floats are truncated toward zero first.

Dart:: Obj.gBitAnd
Kind:: Control-rate

The bitwise objects

.&, .|, .<< and .>> work on 32-bit whole numbers and send an int. A float on either inlet is truncated toward zero first.

.& keeps the bits set in both operands, so .& 15 keeps the lowest four bits: 300 gives 12.
.| keeps the bits set in either operand.
.<< shifts bits up: .<< 4 turns 3 into 48. Bits shifted past the top are lost, and a count of 32 or more gives 0.
.>> shifts bits down and keeps the sign, so -8 shifted by 1 is -4. A count of 32 or more gives -1 for a negative number and 0 for any other.

A shift count below 0 shifts nothing. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Left operand; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Right operand, stored for the next result. Floats are truncated toward zero.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The bitwise AND of both operands.

Parameters

Name	Default	Range	Description
right	0	any int	Starting right operand.

`.&&`#

Logical AND: sends 1 when both operands are non-zero, otherwise 0.

Dart:: Obj.gLogicalAnd
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when both operands are non-zero, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.*`#

Multiplies two numbers and sends the product as a float.

Dart:: Obj.gMultiply
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left * right.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.+`#

Adds two numbers. A number on the left inlet is added to the stored right operand, and the sum is sent as a float.

Dart:: Obj.gAdd
Kind:: Control-rate

Hot and cold inlets

The left inlet is hot: a number there is stored and the result is sent at once. Every other inlet is cold: it stores its number for the next result and sends nothing. The creation argument sets the right operand, which is 0 until it is given.

[.+ 10]   5 -> left inlet                    =>  15
3 -> right inlet, then 5 -> left inlet       =>  8

Every math object with more than one inlet works this way unless its notes say otherwise.

To set both operands from one message, update the cold inlet first: .trigger sends from its rightmost outlet to its leftmost, so wire its right outlet to the cold inlet and its left outlet to the hot one. .swap sends a pair in that order, and .!- and .!/ are .- and ./ with the operands the other way round.

Numbers

Ints and floats are both accepted. A bang, a list or a word is ignored, so to calculate again, send the left value again.

.+, .-, .*, ./, .!- and .!/ calculate in floats and send a float, even for two ints. A float holds whole numbers exactly only up to 16,777,216; above that, ints lose precision. Dividing by 0 sends 0. Use .% and .div for whole-number division.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left + right.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.-`#

Subtracts the right operand from the left one and sends the difference as a float.

Dart:: Obj.gSubtract
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left - right.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`./`#

Divides the left operand by the right one and sends the quotient as a float. Dividing by 0 sends 0.

Dart:: Obj.gDivide
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Dividend; sends the result.
1	right	FLOAT, INT	any float	Divisor, stored for the next result. 0 makes the result 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left / right, or 0 when right is 0.

Parameters

Name	Default	Range	Description
right	0	any float	Starting divisor.

`.<`#

Sends 1 when the left operand is less than the right one, otherwise 0.

Dart:: Obj.gLess
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left < right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.<<`#

Shifts the bits of the left operand left by the right operand. A count below 0 shifts nothing, and a count of 32 or more gives 0.

Dart:: Obj.gShiftLeft
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Left operand; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Right operand, stored for the next result. Floats are truncated toward zero.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The left operand shifted left by the right operand.

Parameters

Name	Default	Range	Description
right	0	any int	Starting right operand.

`.<=`#

Sends 1 when the left operand is less than or equal to the right one, otherwise 0.

Dart:: Obj.gLessEqual
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left <= right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.==`#

Sends 1 when the left operand equals the right one, otherwise 0.

Dart:: Obj.gEqual
Kind:: Control-rate

The comparison and logic objects

.==, .!=, .<, .<=, .>, .>=, .&& and .|| send 1 when their test holds and 0 when it does not, as an int. Ints and floats are compared by value, so 3 equals 3.0.

The test is exact. A value that ought to be 1 but arrives as 0.9999999 after some arithmetic is not equal to 1; send it through .round first. .&& and .|| treat any number other than 0 as true, including negative numbers and fractions such as 0.5.

The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left == right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.>`#

Sends 1 when the left operand is greater than the right one, otherwise 0.

Dart:: Obj.gGreater
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left > right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.>=`#

Sends 1 when the left operand is greater than or equal to the right one, otherwise 0.

Dart:: Obj.gGreaterEqual
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when left >= right, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`.>>`#

Shifts the bits of the left operand right by the right operand, keeping the sign. A count below 0 shifts nothing; past 31, a negative number gives -1 and any other 0.

Dart:: Obj.gShiftRight
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Left operand; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Right operand, stored for the next result. Floats are truncated toward zero.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The left operand shifted right by the right operand.

Parameters

Name	Default	Range	Description
right	0	any int	Starting right operand.

`.abs`#

Sends the absolute value of a number, as a float.

Dart:: Obj.gAbs
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0 or higher	The absolute value of the input.

`.accum`#

Stores a number you can replace, add to and multiply. A number on the left inlet replaces it and sends it; the middle inlet adds to it and the right inlet multiplies it, without sending.

Dart:: Obj.gAccum
Kind:: Control-rate

The middle and right inlets change the stored value without sending it, unlike the cold inlets of the other math objects, which only store an operand.

Messages

a number on the left inlet: replace the stored value and send it.
bang: send the stored value.
set <n>: replace the stored value without sending it.
add <n>: add without sending, as the middle inlet does. ft1 <n> is another spelling of the same message.
mult <n>: multiply without sending, as the right inlet does.
reset: go back to the creation argument without sending. On an .accum 1 that is 1, not 0.

A word without a number after it is ignored.

[.accum 1]   mult 2, mult 2, bang  =>  4

The stored value is a float; there is no whole-number mode, so put .round after the outlet to get whole numbers. The value never becomes infinite: it stops at about plus or minus 3.4e38, and a later multiply brings it back. An infinite or undefined number (NaN) changes nothing when it is added or multiplied, and counts as 0 when it replaces the stored value.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	any float	Number: replace the stored value and send it. Bang: send the stored value. ‘set <n>’, ‘add <n>’, ‘mult <n>’: replace, add or multiply without sending. ‘reset’: go back to the starting value.
1	add	FLOAT, INT	any float	Number added to the stored value, without sending.
2	mult	FLOAT, INT	any float	Number the stored value is multiplied by, without sending.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The stored value.

Parameters

Name	Default	Range	Description
initial	0	any float	Starting value: what a bang sends before anything changes it, and what ‘reset’ returns to.

`.acos`#

Sends the arc-cosine of a number, in radians. Numbers outside -1 to 1 send 0.

Dart:: Obj.gAcos
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	-1.0 to 1.0	Number; sends the result. Numbers outside -1 to 1 send 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0 to pi	The arc-cosine of the input, in radians.

`.acosh`#

Sends the hyperbolic arc-cosine of a number. Numbers below 1 send 0.

Dart:: Obj.gAcosh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	1.0 or higher	Number; sends the result. Numbers below 1 send 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0 or higher	The hyperbolic arc-cosine of the input.

`.anal`#

Counts how often each number follows the one before it, and sends ‘<previous> <current> <count>’ for every pair it counts. Wire it into .prob to make .prob play in the style of what it heard.

Dart:: Obj.gAnal
Kind:: Control-rate

Every number after the first is counted as a pair with the number before it, and the pair leaves with its new count. The first number only becomes the one the next number is paired with.

60, 62, 60, 62  =>  60 62 1,  62 60 1,  60 62 2

Numbers are limited to 0 to limit, and floats are truncated, so with the default of 128 MIDI note numbers arrive unchanged.

Wire the outlet into .prob: each list sets the weight of that transition in .prob to the count, so .prob learns which numbers follow which and can play in the same style.

Messages

clear: forget the counts, but keep the last number, so the next number still forms a pair with it.
reset: forget the last number but keep the counts, so the next number starts a new phrase.
dump: send every stored pair with its count, in the order the pairs were first seen. Use it to teach a .prob created later.

Limits

At most 1024 different pairs are stored. Once the table is full, pairs already in it keep counting, and a new pair is not stored: outlet 1 bangs instead. A count stops growing at 1,048,576.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	0 to limit	Number: count it as following the previous number. ‘clear’: forget the counts. ‘reset’: forget the previous number. ‘dump’: send every stored pair.

Outlets

#	Label	Type	Range	Description
0	pair	LIST	—	‘<previous> <current> <count>’: how often this pair has been seen.
1	full	BANG	—	Bang when a new pair cannot be stored because 1024 different pairs already are.

Parameters

Name	Default	Range	Description
limit	128	1-16384	Highest number accepted; numbers are limited to 0 to limit. Clamped to 1-16384.

`.asin`#

Sends the arc-sine of a number, in radians. Numbers outside -1 to 1 send 0.

Dart:: Obj.gAsin
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	-1.0 to 1.0	Number; sends the result. Numbers outside -1 to 1 send 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-pi/2 to pi/2	The arc-sine of the input, in radians.

`.asinh`#

Sends the hyperbolic arc-sine of a number.

Dart:: Obj.gAsinh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The hyperbolic arc-sine of the input.

`.atan`#

Sends the arc-tangent of a number, in radians. Use .atan2 for an angle around the full circle.

Dart:: Obj.gAtan
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-pi/2 to pi/2	The arc-tangent of the input, in radians.

`.atan2`#

Sends the angle of the point (x, y) in radians, measured from the positive x axis, from -pi to pi. The left inlet takes y and the right inlet x.

Dart:: Obj.gAtan2
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	y	FLOAT, INT	any float	y coordinate; sends the result.
1	x	FLOAT, INT	any float	x coordinate, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-pi to pi	The angle of (x, y) in radians.

Parameters

Name	Default	Range	Description
x	0	any float	Starting x coordinate.

`.atanh`#

Sends the hyperbolic arc-tangent of a number. Numbers at or beyond -1 and 1 send 0.

Dart:: Obj.gAtanh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	greater than -1.0 and less than 1.0	Number; sends the result. Numbers at or beyond -1 and 1 send 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The hyperbolic arc-tangent of the input.

`.atodb`#

Converts a linear amplitude to decibels on the engine’s scale, where an amplitude of 1 is 100 dB and nothing goes below 0 dB. Subtract 100 for decibels relative to full scale.

Dart:: Obj.gAtodb
Kind:: Control-rate

The engine’s decibel scale

.atodb and .dbtoa use the scale the engine uses for its own volume levels: an amplitude of 1 is 100 dB, and every halving of the amplitude is about 6 dB less. An amplitude of 0.00001 and anything quieter gives 0, so the result never goes negative.

  =>  100
5  =>  93.98
1  =>  80

Subtract 100 to read the result as decibels relative to full scale, and add 100 to such a value before sending it to .dbtoa.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	0.0 and up	Linear amplitude; sends the result. 0 and below send 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0-485 dB	The amplitude in decibels; 100 dB is an amplitude of 1.

`.cartopol`#

Converts the point (x, y) to polar form: its distance from the origin on the left outlet and its angle in radians on the right one.

Dart:: Obj.gCartopol
Kind:: Control-rate

Both outlets send on every calculation, the angle first, so an object that takes both values already has the angle when the distance arrives. The angle is measured counterclockwise from the positive x axis, from -pi to pi. .poltocar converts back. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	x	FLOAT, INT	any float	x coordinate; sends the result.
1	y	FLOAT, INT	any float	y coordinate, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	amplitude	FLOAT	0 or higher	Distance of (x, y) from the origin. Sent after the angle.
1	angle	FLOAT	-pi to pi	Angle of (x, y) in radians, measured from the positive x axis.

Parameters

Name	Default	Range	Description
y	0	any float	Starting y coordinate.

`.change`#

Passes a number on only when it differs from the previous one. Two more outlets report when the value leaves 0 and when it returns to 0.

Dart:: Obj.gChange
Kind:: Control-rate

The first number is compared with the creation argument, 0 by default. A bare .change therefore ignores a first 0, and .change 5 stays silent until the value moves away from 5, so loading a patch does not report a parameter that has not moved.

The comparison is exact: 0.5 and 0.5000001 are different numbers. To ignore small changes, put .round in front.

Outlets

left: the number, when it differs from the previous one.
middle: 1 when the value changes from 0 to anything else.
right: 1 when the value changes from anything else to 0.

The outlets send from right to left, so whatever the number triggers already has the 0 reports. .togedge reports the same two changes as bangs.

Modes

mode +: send 1 when the number is greater than the previous one.
mode -: send -1 when the number is less than the previous one.
mode: back to sending numbers that differ.

A + or - after the creation argument starts the object in that mode. In every mode the previous number is the last one received, whether it was sent or not: a .change + fed 5, 3, 4 sends 1 (5 is above the starting 0), nothing, then 1.

Messages

set <n>: store n as the previous number without sending anything, for when the value was changed by another route.
reset: go back to the creation value and mode without sending.

A list counts as its first number. A bang, a word and an infinite or undefined number (NaN) are ignored.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	any float	Number to compare with the previous one. ‘set <n>’: store n without sending. ‘mode +’, ‘mode -’, ‘mode’: choose what counts as a change. ‘reset’: go back to the creation arguments.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The number, when it differs from the previous one. In mode + it sends 1 for a rise, and in mode - it sends -1 for a fall.
1	rising	INT	1	1 when the value changes from 0 to anything else.
2	falling	INT	1	1 when the value changes from anything else to 0.

Parameters

Name	Default	Range	Description
initial mode	0	a float, optionally followed by + or -	The value the first number is compared with, 0 by default, optionally followed by + or - to start in that mode.

`.clip`#

Limits a number to the range low to high and sends it as a float. A number inside the range passes unchanged; any other becomes the nearest limit.

Dart:: Obj.gClip
Kind:: Control-rate

The limits may be given in either order: .clip 1 -1 clips like .clip -1 1. An undefined number (NaN) becomes 0 before it is clipped, so the result is always inside the range. ~clip does the same to an audio signal. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	Number to limit; sends the result.
1	low	FLOAT, INT	any float	Lower limit, stored for the next result.
2	high	FLOAT, INT	any float	Upper limit, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	low to high	The number limited to the range.

Parameters

Name	Default	Range	Description
low	-1	any float	Lower limit.
high	1	any float	Upper limit.

`.cos`#

Sends the cosine of an angle in radians, as a float.

Dart:: Obj.gCos
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float (radians)	Angle in radians; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-1.0 to 1.0	The cosine of the input.

`.cosh`#

Sends the hyperbolic cosine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent.

Dart:: Obj.gCosh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	1.0 or higher	The hyperbolic cosine of the input.

`.counter`#

Counts bangs. Each bang adds the step to the count and sends the new count as an int; an int on the left inlet sets the count and sends it.

Dart:: Obj.gCounter
Kind:: Control-rate

The first bang sends the start value plus the step, so .counter 0 1 sends 1, 2, 3 and so on. Create it as .counter -1 to send 0 first.

An int on the left inlet sets the count and sends it; the next bang adds the step to that. reset goes back to the start value without sending. Floats are ignored on both inlets.

The count has no limit and does not wrap. To make it loop, send it through .% or .pong, or reset it.

Inlets

#	Label	Accepts	Range	Description
0	control	INT, BANG, LIST	any int	Bang: add the step and send the count. Int: set the count and send it. ‘reset’: go back to the start value without sending. Floats are ignored.
1	step	INT	any int	Step added on each bang. Floats are ignored.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The count.

Parameters

Name	Default	Range	Description
startValue	0	any int	The count before the first bang, and the count ‘reset’ returns to. The first bang sends it plus the step.
step	1	any int	Starting step; may be negative to count down.

`.dbtoa`#

Converts decibels on the engine’s scale to a linear amplitude: 100 dB is an amplitude of 1, and 0 dB or less gives 0. The inverse of .atodb.

Dart:: Obj.gDbtoa
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	0-485 dB	Decibels; sends the result. 0 and below send 0; above 485 counts as 485.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0.0 and up	The linear amplitude; 1 means 100 dB.

`.div`#

Integer division: divides the left operand by the right one and sends the whole quotient as an int, truncated toward zero. A divisor of 0 sends 0.

Dart:: Obj.gIntDivide
Kind:: Control-rate

The quotient is truncated toward zero, so -7 divided by 2 is -3, and floats are truncated before the division. .% sends the matching remainder. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Dividend; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Divisor, stored for the next result. Floats are truncated toward zero; 0 makes the result 0.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	left / right truncated toward zero, or 0 when right is 0.

Parameters

Name	Default	Range	Description
right	0	any int	Starting divisor.

`.expr`#

Evaluates a C-style expression such as ‘$f1 * 2 + $f2’. The placeholders $i1-$i9 and $f1-$f9 create the inlets; the left inlet calculates and sends the result.

Dart:: Obj.gExpr
Kind:: Control-rate

Placeholders

$i1 to $i9 read an inlet as an int, truncated toward zero; $f1 to $f9 read it as a float. The number is the inlet, counted from 1 at the left. The object has as many inlets as the highest placeholder, and an inlet that is skipped, such as inlet 2 in $f1 + $f3, is there but unused. An inlet that has not received a number reads 0.

Types

Types follow C:

+, -, *, / and % on two ints give an int, so $i1 / $i2 is whole-number division. With a float on either side, the result is a float.
Comparisons (< <= > >= == !=), logic (&& || !) and bitwise operators (& | ^ << >> ~) give an int. ^ is exclusive or, not a power: use pow().
The result leaves as an int or a float to match.

[.expr ($f1 - 32) * 5 / 9]   212  =>  100, a float
[.expr $i1 / 2]              7    =>  3, an int

Functions

min, max, abs, int, float, pow, sqrt, exp, ln and log (both the natural logarithm), log10, sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, fact (factorial), round, floor and ceil. int, float, abs, min and max keep ints as ints; the others return a float.

Division by 0, and any result that is not a finite number, give 0.

Input

A list on the left inlet fills the inlets from the left and calculates. Items past the ninth are ignored, and inlets the list does not reach keep their numbers. A bang calculates again with the stored numbers. The other inlets take single numbers.

Errors

An expression that cannot be read is reported in the log when the object is created, and the object then sends 0. Random numbers (random, noise) and table functions (size, sum, avg, store and $s placeholders) are not supported and are reported the same way; use .random for random numbers.

The expression is read once, when the object is created, so evaluating it is cheap and safe on the audio thread.

Inlets

#	Label	Accepts	Range	Description
0	$1	FLOAT, INT, BANG, LIST	any float	Value for $i1 and $f1; sends the result. Bang: calculate again. List: fill the inlets from the left, then calculate.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any float	The result: an int when the expression’s type is int, otherwise a float.

Parameters

Name	Default	Range	Description
expression	—	any expression	The expression, for example “($f1 * 0.5) + pow($f2, 2)”. Its placeholders decide how many inlets there are.

`.ftom`#

Converts a frequency in Hz to a MIDI note number, with 440 Hz (A4) at note 69. The result is fractional, so a detuned pitch keeps its offset.

Dart:: Obj.frequencyToMidi
Kind:: Control-rate

The scale is equal temperament with 12 notes per octave: 440 Hz is 69, 880 Hz is 81, and 450 Hz is about 69.39. A frequency of 0 or below has no note, so it gives -1500, which .mtof turns back into a frequency of almost 0.

Inlets

#	Label	Accepts	Range	Description
0	freq	FLOAT, INT	0-20000 Hz	Frequency in Hz; sends the result. 0 Hz or below gives -1500.

Outlets

#	Label	Type	Range	Description
0	midi	FLOAT	any float	MIDI note number, with a fractional part.

`.histo`#

Counts how often each number arrives and sends ‘<number> <count>’ each time. The right inlet reports a number’s count without counting it.

Dart:: Obj.gHisto
Kind:: Control-rate

Numbers from 0 to size - 1 are counted; floats are truncated. A number outside that range is not counted: outlet 1 bangs instead. With the default size of 128, MIDI note numbers fit.

Inlets and messages

a number on the left inlet: count it and send it with its new count.
a number on the right inlet: send it with its count, without counting it.
bang: send the last counted number and its count again; 0 0 before anything was counted.
clear: set every count to 0. The last number is kept, so a bang then reports it with a count of 0.
dump: send every number with a count above 0, lowest first.

Changing the size argument clears the counts. A count stops growing at 1,073,741,824.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	0 to size-1	Number: count it and send its count. Bang: send the count of the last counted number again. ‘clear’: set every count to 0. ‘dump’: send every number counted so far.
1	query	FLOAT, INT	0 to size-1	Number: send its count without counting it.

Outlets

#	Label	Type	Range	Description
0	count	LIST	—	‘<number> <count>’: how often this number has been counted.
1	reject	BANG	—	Bang when a number is outside 0 to size-1; it is not counted.

Parameters

Name	Default	Range	Description
size	128	1-4096	How many numbers can be counted: 0 to size-1. Clamped to 1-4096.

`.linedrive`#

Maps a number onto an exponential curve: inputMax gives outputMax, and each step below it divides the output by the curve. Lets a linear control, such as a MIDI controller, drive a frequency or a gain evenly.

Dart:: Obj.gLinedrive
Kind:: Control-rate

The output is outputMax * curve ^ (value - inputMax). With the defaults, a 0-127 controller covers a wide range evenly:

[.linedrive 127 1 1.06]   127  =>  1
                          64   =>  about 0.025
                          0    =>  about 0.0006

Values above inputMax give more than outputMax; nothing is limited, so add .clip when that matters. A curve below 1 mirrors the response, so the output grows as the value falls, and a curve of 1 always sends outputMax. A curve of 0 or below, or a result too large for a float, sends 0. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	Number to map; sends the result.
1	inputMax	FLOAT, INT	any float	Input that gives outputMax, stored for the next result.
2	outputMax	FLOAT, INT	any float	Output at inputMax, stored for the next result.
3	curve	FLOAT, INT	greater than 0	Curve base, stored for the next result. Larger is steeper; 1 gives a constant outputMax; 0 or below sends 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The number mapped onto the curve.

Parameters

Name	Default	Range	Description
inputMax	127	any float	Input that gives outputMax.
outputMax	1	any float	Output at inputMax.
curve	1.06	greater than 0	Curve base. Larger is steeper; 1 gives a constant outputMax.

`.maximum`#

Sends the larger of a number and a stored value. The right inlet sets the stored value; a list sends its largest item.

Dart:: Obj.gMaximum
Kind:: Control-rate

Numbers on the left inlet are compared with the stored value but never change it. For the largest number received so far, use .peak.

Messages

a number: send the larger of it and the stored value.
bang: send the last result again. Before the first result, that is the creation argument.
a list of two or more numbers: send the largest item. The stored value takes no part, and afterwards the second largest item becomes the stored value. Up to 256 items are read; a one-item list counts as a number.

[.maximum 0.1]   0.05  =>  0.1
                 0.3   =>  0.3
                 3 9 4 =>  9, and 4 is now the stored value

With a control on the right inlet, .maximum is a lower limit that can move. The result is always a float. An infinite or undefined number (NaN) counts as 0.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number: send the larger of it and the stored value. Bang: send the last result again. List: send its largest item, and store the second largest.
1	compare	FLOAT, INT	any float	Value to compare with, stored without sending.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The larger of the input and the stored value.

Parameters

Name	Default	Range	Description
initial	0	any float	Starting value to compare with, and what a bang sends before the first result.

`.mean`#

Sends the average of every number received so far, and how many numbers that is. A list sends the average of its own items and starts the average over.

Dart:: Obj.gMean
Kind:: Control-rate

The count leaves before the average, so whatever the average triggers already has the matching count.

Messages

a number: add it and send the new average.
bang: send the average and count again; 0 and 0 before any number.
a list: send the average of its items (up to 256) and start over from them. Numbers that arrive later are averaged with the list’s items.
clear or reset: start over without sending.

Every number counts the same however long the average runs; the sum is kept in double precision, so it stays accurate over billions of numbers. An infinite or undefined number (NaN) counts as 0 and is still counted. The count outlet stops at 2,147,483,647, but the average stays correct. For an average that forgets old numbers, use .slide, or .array.stream with .array.mean.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number: add it to the average and send. Bang: send the average again. List: average its items, forgetting earlier numbers. ‘clear’ or ‘reset’: start over without sending.

Outlets

#	Label	Type	Range	Description
0	mean	FLOAT	between the smallest and largest input	The average; 0 before any number has arrived.
1	count	INT	0 and up	How many numbers the average includes. Sent before the average.

`.minimum`#

Sends the smaller of a number and a stored value. The right inlet sets the stored value; a list sends its smallest item.

Dart:: Obj.gMinimum
Kind:: Control-rate

Works like .maximum with the comparison reversed: a list sends its smallest item, and the second smallest becomes the stored value.

The stored value starts at 0, so a bare .minimum sends 0 for every positive number. Give it an argument, or a number on the right inlet.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number: send the smaller of it and the stored value. Bang: send the last result again. List: send its smallest item, and store the second smallest.
1	compare	FLOAT, INT	any float	Value to compare with, stored without sending.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The smaller of the input and the stored value.

Parameters

Name	Default	Range	Description
initial	0	any float	Starting value to compare with, and what a bang sends before the first result.

`.mtof`#

Converts a MIDI note number to a frequency in Hz, with note 69 (A4) at 440 Hz. Fractional note numbers give the frequencies in between.

Dart:: Obj.midiToFrequency
Kind:: Control-rate

The scale is equal temperament with 12 notes per octave: 69 is 440 Hz, 60 (middle C) is about 261.63 Hz, and 69.5 is a quarter tone above A4. Note numbers outside 0-127 work too, from -1500 to 1499: a higher note is treated as 1499, and a lower one gives 0 Hz.

Inlets

#	Label	Accepts	Range	Description
0	midi	FLOAT, INT	0-127	MIDI note number, fractional values included; sends the result.

Outlets

#	Label	Type	Range	Description
0	freq	FLOAT	8.18-12543 Hz	Frequency in Hz.

`.past`#

Sends a bang when a number rises to or above a threshold, then stays silent until the number drops below it again. With several thresholds, each item of a list must reach its own.

Dart:: Obj.gPast
Kind:: Control-rate

A number has reached its threshold when it is equal to it or above. The object bangs when the number reaches the threshold after being below it, and is ready again only once the number drops strictly below:

[.past 100]   80, 110, 120, 90, 105  =>  bang at 110, bang at 105
[.past 5]     10, 5, 10              =>  one bang, at the first 10

A new object bangs on the first number that reaches the threshold.

Several thresholds

.past 60 100 compares a list item by item: the first item with 60, the second with 100. It bangs when every item has reached its threshold. A list with fewer items updates only those positions, a number is the first item, and items past the last threshold are ignored. At most 256 thresholds are held.

Messages

clear: forget the past, so the next number that reaches the thresholds bangs again. The thresholds are kept.
set <numbers>: change the thresholds. This does not clear: a threshold that is changed continually does not cause a bang for every message above it. Positions the new list adds start below their threshold.
reset: go back to the creation thresholds and clear.

None of them sends anything. A bang is ignored, and an infinite or undefined number (NaN) counts as 0, in the input and in the thresholds.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	any list of floats	Number or list to compare with the thresholds. ‘clear’: let the next crossing bang again. ‘set <thresholds>’: change the thresholds. ‘reset’: go back to the creation thresholds.

Outlets

#	Label	Type	Range	Description
0	cross	BANG	bang	Bang when every item has reached its threshold, having not done so before.

Parameters

Name	Default	Range	Description
thresholds	0	any list of floats	The thresholds, one per list position. A single 0 by default; at most 256.

`.peak`#

Keeps the largest number received so far and sends it only when a new number beats it. Two more outlets report whether each number set a new peak.

Dart:: Obj.gPeak
Kind:: Control-rate

Inlets and messages

a number on the left inlet: when it is greater than the peak, it becomes the peak and is sent. A number equal to the peak is not a new peak.
a number on the right inlet: it becomes the peak and is sent, and counts as new even when it is lower.
bang: send the peak from the left outlet only.
a list <number> <peak>: set the peak as the right inlet does, then offer the number. Items past the second are ignored.
set <n>: set the peak without sending.
reset: go back to the creation argument without sending.

Every number sends the two flag outlets, right before middle, and then the new peak if there is one.

[.peak]   3, 5, 4, 9  =>  3, 5, (nothing), 9

The peak starts at 0, so negative numbers never beat it. For data below 0, give a lower start, such as .peak -1000. The result is always a float, and an infinite or undefined number (NaN) counts as 0.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number: send it if it beats the peak. Bang: send the peak. List ‘<number> <peak>’: set the peak, then offer the number. ‘set <n>’: set the peak without sending. ‘reset’: go back to the starting peak without sending.
1	seed	FLOAT, INT	any float	Number that becomes the new peak and is sent, always reported as a new record.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The new peak. Silent when a number does not beat it.
1	new	INT	0 or 1	1 when the number just received set a new record, otherwise 0.
2	same	INT	0 or 1	The opposite of the ‘new’ outlet: 0 for a new record, otherwise 1.

Parameters

Name	Default	Range	Description
initial	0	any float	Starting peak, and the peak ‘reset’ returns to.

`.poltocar`#

Converts a polar point, a distance from the origin and an angle in radians, to its x and y coordinates. The inverse of .cartopol.

Dart:: Obj.gPoltocar
Kind:: Control-rate

Both outlets send on every calculation, y first, so an object that takes both values already has y when x arrives. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	amplitude	FLOAT, INT	any float	Distance from the origin; sends the result.
1	angle	FLOAT, INT	any float	Angle in radians from the positive x axis, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	x	FLOAT	any float	x coordinate of the point. Sent after y.
1	y	FLOAT	any float	y coordinate of the point.

Parameters

Name	Default	Range	Description
angle	0	any float	Starting angle in radians.

`.pong`#

Keeps a number inside the range low to high by folding it back from the limits, the default, by wrapping it around to the other side, or by clipping it. Sends the result as a float.

Dart:: Obj.gPong
Kind:: Control-rate

Modes

The third argument sets the mode:

3, fold (the default): a number past a limit is reflected back, as many times as needed. With the range 0 to 10, 12 gives 8 and -3 gives 3.
2, wrap: a number past a limit comes back in from the other side. The range includes low but not high, so 10 gives 0, 12 gives 2 and -3 gives 7. Fed from a counter, this cycles through the range, negative counts included.
1, clip: as .clip.
0: the number passes unchanged.

Any other mode folds. The limits may be given in either order, and when they are equal the result is always that value. An infinity goes to the nearest limit, and an undefined number (NaN) counts as 0. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	Number to keep in range; sends the result.
1	low	FLOAT, INT	any float	Lower limit, stored for the next result.
2	high	FLOAT, INT	any float	Upper limit, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	low to high	The number folded, wrapped or clipped into the range.

Parameters

Name	Default	Range	Description
low	-1	any float	Lower limit.
high	1	any float	Upper limit.
mode	3	0 to 3	0 passes numbers through, 1 clips, 2 wraps, 3 folds.

`.pow`#

Raises the left operand to the power of the right one and sends the result as a float. Combinations with no finite real result, such as a negative base with a fractional exponent, send 0.

Dart:: Obj.gPow
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	base	FLOAT, INT	any float	Base; sends the result.
1	exponent	FLOAT, INT	any float	Exponent, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	base to the power of exponent, or 0 when that has no finite value.

Parameters

Name	Default	Range	Description
exponent	0	any float	Starting exponent.

`.round`#

Rounds a number to the nearest multiple of the step and sends it as a float: a step of 1, the default, rounds to whole numbers and 0.5 to halves. Halfway values round away from zero; a step of 0 passes the number unchanged.

Dart:: Obj.gRound
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number to round; sends the result.
1	step	FLOAT, INT	any float	Step to round to, stored for the next result. 0 turns rounding off.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The input rounded to the nearest multiple of the step.

Parameters

Name	Default	Range	Description
step	1	any float	Starting step. 0 passes numbers through unchanged.

`.scale`#

Maps a number from the input range onto the output range and sends it as a float. An exponent other than 1 bends the mapping into a curve; numbers outside the input range map past the output range unless clip is 1.

Dart:: Obj.gScale
Kind:: Control-rate

The mapping is

n   = (value - inLow) / (inHigh - inLow)
out = outLow + (outHigh - outLow) * n ^ exponent

so an exponent above 1 starts slowly and ends fast, and one below 1 does the opposite. Below inLow, where n is negative, the curve is mirrored.

[.scale 0 127 0 1]     64  =>  0.504
[.scale 0 127 0 1 2]   64  =>  0.254

A number outside the input range maps past the output range. Set the sixth argument, clip, to 1 to limit the result to the output range instead, or use .zmap, which always limits and is always a straight line.

Either range may run from high to low. When inLow equals inHigh, the result is outLow. A result that is not a finite number sends 0. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	Number to map; sends the result.
1	inLow	FLOAT, INT	any float	Input value that maps to outLow, stored for the next result.
2	inHigh	FLOAT, INT	any float	Input value that maps to outHigh, stored for the next result.
3	outLow	FLOAT, INT	any float	Output for inLow, stored for the next result.
4	outHigh	FLOAT, INT	any float	Output for inHigh, stored for the next result.
5	exponent	FLOAT, INT	any float	Curve exponent, stored for the next result. 1 is a straight line.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The number mapped onto the output range.

Parameters

Name	Default	Range	Description
inLow	0	any float	Input value that maps to outLow.
inHigh	127	any float	Input value that maps to outHigh.
outLow	0	any float	Output for inLow.
outHigh	1	any float	Output for inHigh.
exponent	1	any float	Curve exponent; 1 is a straight line.
clip	0	0 or 1	1 limits the result to the output range; 0 lets numbers outside the input range map past it.

`.sin`#

Sends the sine of an angle in radians, as a float.

Dart:: Obj.gSin
Kind:: Control-rate

The single-input functions

.sin, .cos, .tan, .asin, .acos, .atan, .sinh, .cosh, .tanh, .asinh, .acosh, .atanh, .abs and .sqrt have one inlet. A number there, int or float, sends the result at once as a float.

Angles are in radians: a full circle is 2 pi, about 6.2832. To use degrees, multiply by 0.017453 (pi / 180) first:

[.* 0.017453] -> [.sin]   90  =>  1

Where a function has no finite result, for a number outside its range or a result too large for a float, it sends 0. When 0 is also a meaningful result, check the range of the input first.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float (radians)	Angle in radians; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-1.0 to 1.0	The sine of the input.

`.sinh`#

Sends the hyperbolic sine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent.

Dart:: Obj.gSinh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The hyperbolic sine of the input.

`.slide`#

Smooths a stream of numbers. Each number moves the output part of the way towards it: 1/slideUp of the distance when rising, 1/slideDown when falling. A slide of 1 passes numbers straight through.

Dart:: Obj.gSlide
Kind:: Control-rate

Each number moves the output (number - output) / slide closer to it. A slide of 1 jumps straight to the number; a slide of 10 covers a tenth of the remaining distance per number. The output starts at 0.

[.slide 4 4]   100, 100, 100  =>  25, 43.75, 57.81

The smoothing counts numbers, not time, so it depends on how often numbers arrive. For a ramp over a set time, use .line or ~line.

A slide below 1 counts as 1. Once the output is within a millionth of the number, it lands exactly on it. An infinite or undefined number (NaN) counts as 0.

Messages

bang: take another step towards the last number. Repeated bangs glide the output to it.
set <n>: make n the number to move towards, without sending. Follow it with bangs.
reset: set the output to 0 without sending. The number to move towards is kept.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	any float	Number: take one step towards it and send the output. Bang: take another step towards the last number. ‘set <n>’: set the target without sending. ‘reset’: set the output to 0 without sending.
1	slideUp	FLOAT, INT	1+	Slide used while the output rises. Below 1 counts as 1.
2	slideDown	FLOAT, INT	1+	Slide used while the output falls. Below 1 counts as 1.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	between the previous output and the input	The smoothed value.

Parameters

Name	Default	Range	Description
slideUp	1	1+	Starting slide while rising. Below 1 counts as 1.
slideDown	1	1+	Starting slide while falling. Below 1 counts as 1.

`.sqrt`#

Sends the square root of a number, as a float. A negative number sends 0.

Dart:: Obj.gSqrt
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result. A negative number sends 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0 or higher	The square root of the input, or 0 when the input is negative.

`.swap`#

Sends two numbers out in swapped order. A number on the left inlet leaves the right outlet, then the number stored on the right inlet leaves the left outlet.

Dart:: Obj.gSwap
Kind:: Control-rate

Use it when two values arrive in the wrong order for the hot and cold rule (see .+). The right outlet always sends first, and everything connected to it finishes before the left outlet sends, so wire the right outlet to a cold inlet and the left outlet to the hot one:

[.swap 100]  right outlet -> right inlet of [.-]
             left outlet  -> left inlet of [.-]
x -> left inlet of [.swap]  =>  [.-] sends 100 - x

Each number keeps its type: an int leaves as an int and a float as a float. The argument’s spelling sets its type: .swap 5 holds the int 5 and .swap 5. the float 5.

Messages

a number on the left inlet: store it and send the pair.
bang: send the pair again unchanged. Before anything has arrived, that is 0 and the argument.
a list: the first number goes to the left inlet’s slot and the second to the right’s, then the pair is sent. A single number leaves the right slot alone. Reading stops at the first word, and a list that starts with a word is ignored.

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT, BANG, LIST	any number	Number: store it and send the pair. Bang: send the pair again. List of two numbers: store both and send. Leaves on the right outlet.
1	right	FLOAT, INT	any number	Number for the left outlet, stored without sending.

Outlets

#	Label	Type	Range	Description
0	fromRight	ANY	any number	The number from the right inlet, as the int or float it arrived as. Sent second.
1	fromLeft	ANY	any number	The number from the left inlet, as the int or float it arrived as. Sent first.

Parameters

Name	Default	Range	Description
right	0	any number	Starting number for the left outlet. Written as 5 it is an int; written as 5. or 5e0 it is a float.

`.tan`#

Sends the tangent of an angle in radians, as a float. Where the result would be infinite, it sends 0.

Dart:: Obj.gTan
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float (radians)	Angle in radians; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The tangent of the input.

`.tanh`#

Sends the hyperbolic tangent of a number: a smooth S-curve between -1 and 1, often used for soft saturation.

Dart:: Obj.gTanh
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT	any float	Number; sends the result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	-1.0 to 1.0	The hyperbolic tangent of the input.

`.togedge`#

Bangs the left outlet when a value becomes non-zero and the right outlet when it returns to 0, and stays silent in between. A bang flips the value between zero and non-zero.

Dart:: Obj.gTogedge
Kind:: Control-rate

Only transitions are reported: 5 followed by 9 sends nothing, and neither does 0 followed by 0. The two outlets therefore take turns, never banging twice in a row from the same side, which makes them a reliable pair of note-on and note-off triggers.

0, 0.2, 0.8, 0.3, 0  =>  left bang at 0.2, right bang at the last 0

The value starts at 0, so the first non-zero number bangs the left outlet and a first 0 sends nothing. Any number other than 0 counts, fractions such as 0.5 included.

Messages

bang: flip the value between zero and non-zero, and bang the matching outlet. A stream of bangs alternates left, right, left. After a number such as 5, a bang flips to 0 and bangs the right outlet.
reset: set the value to 0 without sending, so the gate is closed again without a right-outlet bang.

A list counts as its first number. Words and infinite or undefined numbers (NaN) are ignored. .change reports the same transitions as 1s, next to the value.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number to watch. Bang: flip between zero and non-zero, and report it. ‘reset’: set the value to 0 without sending.

Outlets

#	Label	Type	Range	Description
0	rising	BANG	bang	Bang when the value changes from 0 to non-zero.
1	falling	BANG	bang	Bang when the value changes from non-zero to 0.

`.trough`#

Keeps the smallest number received so far and sends it only when a new number goes below it. Two more outlets report whether each number set a new minimum.

Dart:: Obj.gTrough
Kind:: Control-rate

Works like .peak with the comparison reversed: a number below the minimum becomes the new minimum and is sent.

The minimum starts at 128, so MIDI values can go below it. For larger data, give a higher start, such as .trough 100000.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any float	Number: send it if it is below the minimum. Bang: send the minimum. List ‘<number> <minimum>’: set the minimum, then offer the number. ‘set <n>’: set the minimum without sending. ‘reset’: go back to the starting minimum without sending.
1	seed	FLOAT, INT	any float	Number that becomes the new minimum and is sent, always reported as a new record.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The new minimum. Silent when a number does not go below it.
1	new	INT	0 or 1	1 when the number just received set a new record, otherwise 0.
2	same	INT	0 or 1	The opposite of the ‘new’ outlet: 0 for a new record, otherwise 1.

Parameters

Name	Default	Range	Description
initial	128	any float	Starting minimum, and the minimum ‘reset’ returns to. 128 by default, so that ordinary numbers can go below it.

`.vexpr`#

Evaluates an expression for every item of a list, as .expr does for single numbers, and sends the results as a list. A single number on an inlet is used for every item.

Dart:: Obj.gVexpr
Kind:: Control-rate

The language is that of .expr: placeholders, operators, types, functions and errors work as described there.

Every inlet holds a list, and a single number is a one-item list. The expression runs once per position, up to the length of the shortest list among the inlets it uses. An inlet that holds one item supplies it to every position.

[.vexpr $f1 * $f2]   0.5 -> right inlet, then 60 64 67 -> left  =>  30 32 33.5
[.vexpr $i1 + $i2]   0 4 7 -> right inlet, then 60 -> left      =>  60 64 67

A single result leaves as an int or a float rather than a list. Every inlet takes lists, of up to 256 items; items past that are dropped. A list without numbers is ignored, a bang calculates again, and an inlet that has received nothing reads as a single 0.

Inlets

#	Label	Accepts	Range	Description
0	$1	FLOAT, INT, BANG, LIST	any list of floats	List for $i1 and $f1; sends the results. A single number counts as a one-item list. Bang: calculate again.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any list of floats	One result per item, as a list; a single result as an int or a float.

Parameters

Name	Default	Range	Description
expression	—	any expression	The expression to evaluate for every item, for example “$f1 * $f2”. Its placeholders decide how many inlets there are.

`.zmap`#

Maps a number from the input range onto the output range, in a straight line, and sends it as a float. A number outside the input range gives the nearest output limit, so the result never leaves the output range.

Dart:: Obj.gZmap
Kind:: Control-rate

The mapping is the straight-line .scale, always limited to the output range. A number outside the input range, an infinity included, gives the nearest output limit:

[.zmap 0 127 0 1]   200  =>  1
                    -5   =>  0

Either range may run from high to low. When inLow equals inHigh, the result is outLow. The inlets work as described under .+.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	Number to map; sends the result.
1	inLow	FLOAT, INT	any float	Input value that maps to outLow, stored for the next result.
2	inHigh	FLOAT, INT	any float	Input value that maps to outHigh, stored for the next result.
3	outLow	FLOAT, INT	any float	Output for inLow, stored for the next result.
4	outHigh	FLOAT, INT	any float	Output for inHigh, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	The number mapped onto the output range, limited to it.

Parameters

Name	Default	Range	Description
inLow	0	any float	Input value that maps to outLow.
inHigh	127	any float	Input value that maps to outHigh.
outLow	0	any float	Output for inLow.
outHigh	1	any float	Output for inHigh.

`.|`#

Bitwise OR of two integers, sent as an int. Floats are truncated toward zero first.

Dart:: Obj.gBitOr
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any int	Left operand; sends the result. Floats are truncated toward zero.
1	right	FLOAT, INT	any int	Right operand, stored for the next result. Floats are truncated toward zero.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	The bitwise OR of both operands.

Parameters

Name	Default	Range	Description
right	0	any int	Starting right operand.

`.||`#

Logical OR: sends 1 when either operand is non-zero, otherwise 0.

Dart:: Obj.gLogicalOr
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand; sends the result.
1	right	FLOAT, INT	any float	Right operand, stored for the next result.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	1 when either operand is non-zero, 0 otherwise.

Parameters

Name	Default	Range	Description
right	0	any float	Starting right operand.

`~*`#

Multiplies an audio signal by another audio signal or by a float: a gain stage, or a ring modulator.

Dart:: Obj.dMultiply
Kind:: DSP (audio-rate)

The audio-rate operators

~+, ~-, ~* and ~/ share these rules:

The left inlet takes the audio signal. Nothing comes out while no audio reaches it.
The right inlet takes an audio signal or a number, int or float. While audio is connected there, it is used sample by sample; otherwise the last number is used, or the argument until a number arrives.
A new number takes effect at the next audio block and is not smoothed, so a large jump can click. Ramp it with ~line instead.
When no argument is given, ~+ and ~- use 0 and ~* and ~/ use 1, so a bare object passes the signal through unchanged.

[~* 0.5]   halves the signal's level

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Audio signal.
1	right	BUFFER, FLOAT, INT	any float	Audio signal, or a number used while no audio is connected.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left * right.

Parameters

Name	Default	Range	Description
right	1.0	any float	Float used while no audio is connected to the right inlet.

`~+`#

Adds two audio signals, or adds a float to an audio signal.

Dart:: Obj.dAdd
Kind:: DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Audio signal.
1	right	BUFFER, FLOAT, INT	any float	Audio signal, or a number used while no audio is connected.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left + right.

Parameters

Name	Default	Range	Description
right	0	any float	Float used while no audio is connected to the right inlet.

`~-`#

Subtracts an audio signal, or a float, from an audio signal.

Dart:: Obj.dSubtract
Kind:: DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Audio signal.
1	right	BUFFER, FLOAT, INT	any float	Audio signal, or a number used while no audio is connected.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left - right.

Parameters

Name	Default	Range	Description
right	0	any float	Float used while no audio is connected to the right inlet.

`~/`#

Divides an audio signal by another audio signal or by a float. A float of 0 leaves the signal unchanged.

Dart:: Obj.dDivide
Kind:: DSP (audio-rate)

A number of 0 on the right inlet leaves the signal unchanged. An audio divisor that reaches 0 produces infinite samples, so keep it away from 0. The other rules are described under ~*.

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Audio signal.
1	right	BUFFER, FLOAT, INT	any non-zero float	Audio signal, or a number used while no audio is connected. A number of 0 leaves the signal unchanged.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left / right.

Parameters

Name	Default	Range	Description
right	1.0	any non-zero float	Float used while no audio is connected to the right inlet. 0 leaves the signal unchanged.

`~clip`#

Hard clipper: limits every sample of an audio signal to the range low to high. Use it to tame stray peaks, or as a distortion stage.

Dart:: Obj.dClip
Kind:: DSP (audio-rate)

The low and high inlets take ints and floats. When low is above high, every sample becomes high. New limits take effect at the next audio block.

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	any float	Audio signal.
1	low	FLOAT, INT	any float	Lower limit, as an int or a float.
2	high	FLOAT, INT	any float	Upper limit, as an int or a float.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	low to high	The signal limited to low to high.

Parameters

Name	Default	Range	Description
low	-1.0	any float	Starting lower limit.
high	1.0	any float	Starting upper limit.

Math

Contents

Math#