HelpSource/Classes/Symbol.schelp

   1 class::Symbol
   2 summary::unique name
   3 categories::Core
   4
   5 description::
   6 A Symbol is a name that is guaranteed to be unique. They can be used to represent
   7 symbolic constant values, link::Classes/Dictionary:: keys, etc.
   8
   9 Symbols are represented syntactically as literals which are described in link::Reference/Literals::
  10
  11 subsection::Creating a Symbol
  12
  13 A symbol can be written by surrounding characters by single quotes (may include whitespace):
  14
  15 code::'foo bar'::
  16
  17 Or by a preceeding backslash (then it may not include whitespace):
  18
  19 code::\foo::
  20
  21 A String can be converted into a symbol:
  22
  23 code::"arbeit".scramble.asSymbol;::
  24
  25 classmethods::
  26 private::new
  27
  28 instancemethods::
  29
  30 subsection::Testing
  31
  32 method::isClassName
  33
  34 Answer whether the symbol can be a class name. This does not say if the class exists.
  35
  36 code::
  37 \Array.isClassName;
  38 \Bauxite.isClassName;
  39 ::
  40
  41 method::isMetaClassName
  42
  43 Answer whether the symbol can be meta class name. This does not say if the class exists.
  44
  45 code::
  46 \Meta_Array.isMetaClassName;
  47 ::
  48
  49 method::isSetter
  50
  51 Answer whether the symbol has a trailing underscore.
  52
  53 code::
  54 'action_'.isSetter;
  55 ::
  56
  57 method::isPrimitiveName
  58
  59 Answer whether the symbol is a valid primitive name
  60
  61 code::
  62 '_SymbolIsClassName'.isPrimitiveName;
  63 ::
  64
  65 subsection::Conversion
  66
  67 method::asString
  68
  69 Convert to a String
  70
  71 method::asInteger
  72
  73 Convert to an Integer
  74
  75 method::asClass
  76
  77 Answer the Class named by the receiver.
  78
  79 method::asSetter
  80
  81 Return a symbol with a trailing underscore added.
  82
  83 method::asGetter
  84
  85 Return a symbol with a trailing underscore removed.
  86
  87 method::ascii
  88
  89 return the ascii codes as an array
  90
  91 method::asSpec
  92
  93 Convert to a ControlSpec
  94
  95 method::asTuning
  96
  97 Convert to a Tuning
  98
  99 method::asScale
 100
 101 Convert to a Scale
 102
 103 subsection::Environments
 104
 105 Symbols are used as keys to look up objects in dictionaries and environments, but also in arrays.
 106 See link::Classes/IdentityDictionary::, link::Classes/Environment::, link::Classes/Event::
 107 discussion::
 108 code::
 109 a = ();
 110 a.put(\commune, 1871);
 111 a.at(\commune);
 112 ::
 113
 114 method::envirPut
 115
 116 put a value to the current environment using receiver as key
 117
 118 method::envirGet
 119
 120 return a value from the current environment using receiver as key
 121 discussion::
 122 code::
 123 \foo.envirPut(100);
 124 \foo.envirGet;
 125 \foo.envirPut(nil);
 126 ::
 127
 128 subsection::Math
 129
 130 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.
 131
 132 code::Pseq([1, 3, \rest, 2, 4] + 8);::
 133
 134 method::applyTo
 135
 136 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).
 137 discussion::
 138 code::
 139 '%'.applyTo(2553, 345);
 140 ['+', '-', '*', { |a, b| a.rand + b.rand } ].choose.applyTo(2, 3);
 141 ::
 142
 143
 144 subsection::Synthesis
 145
 146 Inside SynthDefs and UGen functions, symbols can be used to conventiently specify control inputs of different rates and with lags (see:  NamedControl, ControlName, and Control).
 147
 148
 149 method::kr
 150
 151 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.
 152 discussion::
 153 code::
 154 a = { SinOsc.ar(\freq.kr(440, 1.2)) }.play;
 155 a.set(\freq, 330);
 156 a.release;
 157 a = { SinOsc.ar(\freq.kr([440, 460], 1.2)) }.play;
 158 a.setn(\freq, [330, 367]);
 159 a.release;
 160 ::
 161
 162 method::ar
 163
 164 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.
 165
 166 method::ir
 167
 168 Return an intitalization rate NamedControl input with a default value (val). If val is an array, the control will be multichannel.
 169
 170 method::tr
 171
 172 Return a TrigControl input with a default value (val). If val is an array, the control will be multichannel.
 173 discussion::
 174 code::
 175 a = { Ringz.ar(T2A.ar(\trig.tr), \freq.kr(500, 1), 0.8) }.play;
 176 a.set(\freq, 330, \trig, 1);
 177 a.set(\freq, 830, \trig, 1);
 178 a.release;
 179 ::
 180