class::Symbol
summary::unique name
categories::Core

description::
A Symbol is a name that is guaranteed to be unique. They can be used to represent
symbolic constant values, link::Classes/Dictionary:: keys, etc.

Symbols are represented syntactically as literals which are described in link::Reference/Literals#Symbols::.

subsection::Creating a Symbol

A symbol can be written by surrounding characters by single quotes (may include whitespace):

code::'foo bar'::

Or by a preceding backslash (then it may not include whitespace):

code::\foo::

A String can be converted into a symbol:

code::"arbeit".scramble.asSymbol;::

classmethods::
private::new

instancemethods::

subsection::Testing

method::isClassName

Answer whether the symbol can be a class name. This does not say if the class exists.

code::
\Array.isClassName;
\Bauxite.isClassName;
::

method::isMetaClassName

Answer whether the symbol can be meta class name. This does not say if the class exists.

code::
\Meta_Array.isMetaClassName;
::

method::isSetter

Answer whether the symbol has a trailing underscore.

code::
'action_'.isSetter;
::

method::isPrimitiveName

Answer whether the symbol is a valid primitive name

code::
'_SymbolIsClassName'.isPrimitiveName;
::

subsection::Conversion

method::asString

Convert to a String

method::asInteger

Convert to an Integer

method::asClass

Answer the Class named by the receiver.

method::asSetter

Return a symbol with a trailing underscore added.

method::asGetter

Return a symbol with a trailing underscore removed.

method::ascii

return the ascii codes as an array

method::asSpec

Convert to a ControlSpec

method::asTuning

Convert to a Tuning

method::asScale

Convert to a Scale

subsection::Environments

Symbols are used as keys to look up objects in dictionaries and environments, but also in arrays.
See link::Classes/IdentityDictionary::, link::Classes/Environment::, link::Classes/Event::

code::
a = ();
a.put(\commune, 1871);
a.at(\commune);
::

method::envirPut

put a value to the current environment using receiver as key

method::envirGet

return a value from the current environment using receiver as key
discussion::
code::
\foo.envirPut(100);
\foo.envirGet;
\foo.envirPut(nil);
::

subsection::Math

Symbols respond to all unary and binary math operations by returning themselves. The result of any math operation between a Number or other math object and a Symbol is to return the Symbol. This allows for example operations on lists of notes which contain 'rest's to preserve the rests.

code::Pseq([1, 3, \rest, 2, 4] + 8);::

method::applyTo

Use the symbol as a method selector and perform the message on firstArg, with args as arguments. This is used for mixing functions with method selectors (see also: Function).
discussion::
code::
'%'.applyTo(2553, 345);
['+', '-', '*', { |a, b| a.rand + b.rand } ].choose.applyTo(2, 3);
::


subsection::Synthesis

Inside SynthDefs and UGen functions, symbols can be used to conveniently specify control inputs of different rates and with lags (see:  NamedControl, ControlName, and Control).


method::kr

Return a control rate NamedControl input with a default value (val), and if supplied, with a lag. If val is an array, the control will be multichannel.
discussion::
code::
a = { SinOsc.ar(\freq.kr(440, 1.2)) }.play;
a.set(\freq, 330);
a.release;
a = { SinOsc.ar(\freq.kr([440, 460], 1.2)) }.play;
a.setn(\freq, [330, 367]);
a.release;
::

method::ar

Return an audio rate NamedControl input with a default value (val), and if supplied, with a lag. If val is an array, the control will be multichannel.

method::ir

Return an initialization rate NamedControl input with a default value (val). If val is an array, the control will be multichannel.

method::tr

Return a TrigControl input with a default value (val). If val is an array, the control will be multichannel.
discussion::
code::
a = { Ringz.ar(T2A.ar(\trig.tr), \freq.kr(500, 1), 0.8) }.play;
a.set(\freq, 330, \trig, 1);
a.set(\freq, 830, \trig, 1);
a.release;
::