HelpSource/Classes/Dictionary.schelp

   1 CLASS::Dictionary
   2 summary::associative collection mapping keys to values
   3 related::Classes/Environment, Classes/Event
   4 categories::Collections>Unordered
   5
   6 DESCRIPTION::
   7 A Dictionary is an associative collection mapping keys to values.
   8 Two keys match if they are strong::equal::. (i.e. == returns true.)
   9
  10 The contents of a Dictionary are strong::unordered::. You must not depend on the order of items in a Dictionary.
  11 You must only rely on equality for the keys (e.g. symbols are ok, strings not). For identity matching see: link::Classes/IdentityDictionary::.
  12
  13 CLASSMETHODS::
  14
  15 method::new
  16 Creates a Dictionary with an initial capacity for strong::n:: key value mappings.
  17
  18 method::newFrom
  19 Creates a new Dictionary from another collection.
  20 code::
  21 d= Dictionary.newFrom(List[\a, 1, \b, 2, \c, 4]);
  22 ::
  23 argument::aCollection
  24 any Object that responds to keysValuesDo (usually a List or an Array).
  25
  26 INSTANCEMETHODS::
  27
  28 subsection::Adding and Removing
  29
  30 method::add
  31 Add strong::anAssociation:: to the Dictionary. If the key value pair already exists in the Dictionary, the key's value will be replaced.
  32 code::
  33 (
  34 d = Dictionary.new;
  35 d.add(\monkey -> 0).postln;
  36 d.add(\robot -> 1).postln;      // Add robot as a key with a value of 1
  37 d.add(\monkey -> 2).postln;     // Replaces the value for the key monkey with 2
  38 )
  39 ::
  40
  41 method::put
  42 Associate two objects and add them to the Dictionary.
  43 code::
  44 d = Dictionary.new;
  45 d.put("abc", 10);
  46
  47 // using an event:
  48 d = ();
  49 d.put("abc", 10);
  50 ::
  51 argument::key
  52 key to associate with object. This can be any objects, but is often a link::Classes/Symbol::.
  53 argument::obj
  54 an object
  55
  56 method::removeAt
  57 Remove the key and the value associated with it from the Dictionary.
  58 code::
  59 d = (monkey: 99);
  60 d.removeAt(\monkey);
  61 ::
  62
  63 method::putAll
  64 Add all items of each argument to the dictionary.
  65 code::
  66 d = ();
  67 d.putAll(Dictionary[\hello -> 9, \whello -> "world"], Dictionary["abd" -> 6]);
  68 ::
  69 argument::dictionaries
  70 any Object that responds to keysValuesDo (usually a Dictionary).
  71
  72 method::putPairs
  73 Add all items to the dictionary, using them as key and value pairwise.
  74 code::
  75 d = ();
  76 d.putPairs([\hello, 10, \whello, "lord", "abc", 7]);
  77 ::
  78
  79 subsection::Accessing
  80
  81 method::at
  82 Access the value associated with the key.
  83 code::
  84 d = (robot: 99);
  85 d.at(\robot);   // Get the value associated with key
  86 d[\robot];      // different syntax, same behaviour
  87 d.at(\monkey);  // Key doesn't exist: return Nil
  88 ::
  89
  90 method::atFail
  91 Access the value associated with the key. If the key does not exist, return the result of teletype::function::.
  92 ::
  93
  94 method::keys
  95 Return a link::Classes/Set:: of all keys.
  96 code::
  97 d = (hello: 9, whello: "world");
  98 d.keys;
  99 ::
 100
 101 method::values
 102 Return a link::Classes/List:: of all values.
 103 code::
 104 d = (hello: 9, whello: "world");
 105 d.values;
 106 ::
 107
 108 method::atAll
 109 Return an link::Classes/Array:: of all values for the given keys.
 110 code::
 111 d = (hello: 9, whello: "world", z: 99, c: 0.33);
 112 d.atAll([\hello, \z, \hello, \c, \whello]);
 113 ::
 114
 115 method::getPairs
 116 Return an link::Classes/Array:: with all keys and values pairwise.
 117 code::
 118 d = (hello: 9, whello: 77, z: 99);
 119 d.getPairs;
 120 ::
 121
 122 method::associationAt
 123 Access the link::Classes/Association:: that has the given key.
 124 code::
 125 d = (robot: 99);
 126 d.associationAt(\robot);        // Get the value associated with key
 127 ::
 128
 129 method::findKeyForValue
 130 Try to find a given value and return its key.
 131 code::
 132 d = (hello: 1, whello: 1976);
 133 d.findKeyForValue(1);
 134 ::
 135
 136 method::matchAt
 137 The dictionary's keys are used as conditions against which the arbitrary item is matched. See: link::Reference/matchItem::
 138 note::
 139 if an item matches multiple criteria, the value returned is arbitrary. This is because a dictionary is an unordered collection. It's the user's responsibility to make sure that criteria are mutually exclusive.
 140 ::
 141 list::
 142 ## If the key is an object, the item will be matched by identity (if key === item, the value will be returned).
 143 ## If the key is a collection, the item is matched if it's contained in the collection.
 144 ## If the key is a function, the function is evaluated with the item as an argument and the item is matched if the function returns true.
 145 ::
 146 code::
 147 (
 148 d = (
 149         0: \zero,
 150         \abc: \alpha,
 151         [1, 2, 3, 5, 8, 13, 21]: \fibonacci,
 152         { |x| try { x.even } }: \even // try is needed because argument might not be a number
 153         );
 154 );
 155
 156 d.matchAt(0)
 157 d.matchAt(1)
 158 d.matchAt(2)    // matches both 'fibonacci' and 'even', either may be returned
 159 d.matchAt(4)
 160 d.matchAt(\abc)
 161 ::
 162
 163 method::trueAt
 164 Returns link::Classes/True:: if the item at the key is true, otherwise false. This method is also valid in link::Classes/Object::.
 165
 166 method::falseAt
 167 Returns link::Classes/False:: if the item at the key is not true, otherwise true. This method is inherited from link::Classes/Object::.
 168
 169 subsection::Iteration/Enumeration
 170 Most methods for iteration work analogously to Dictionary's superclasses, see e.g. link::Classes/Collection::.
 171
 172 method::do, collect, reject, select
 173 code::
 174 // do, collect, reject, select
 175 d = Dictionary[\a -> "hello", \b -> "robot", \c -> [1, 2, 3]];
 176 d = (a: "hello", b: "robot", c: [1, 2, 3]); // equivalent
 177 d.do { |item, i| [item, i].postln };
 178 d.collect { |item| item + 100 };
 179 d.reject { |item| item.size > 4 };
 180 d.select { |item| item.size > 4 };
 181 ::
 182
 183 method::keysValuesDo
 184 Iterate over the associations, and evaluate the function for each, passing key and value as argument.
 185 code::
 186 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 187 d.keysValuesDo { |key, value| postln("the key: " ++ key ++ " the value: " ++ value) };
 188 ::
 189
 190 method::keysValuesChange
 191 Iterate over the associations, and evaluate the function for each, passing key and value as argument. Replace the value with the return value from the function (similar to link::#-collect::, but modifies the dictionary strong::in place::).
 192 code::
 193 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 194 d.keysValuesChange { |key, value| "the key: " ++ key ++ " the value: " ++ value };
 195 d;
 196 ::
 197
 198 method::keysDo
 199 Iterate over the associations, and evaluate the function for each, passing key as argument.
 200 code::
 201 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 202 d.keysDo { |key| postln("the key: " ++ key) };
 203 ::
 204
 205 method::associationsDo
 206 Iterate over the associations, and evaluate the function for each.
 207 code::
 208 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 209 d.associationsDo { |assoc| postln("the association: " ++ assoc) };
 210 ::
 211
 212 method::pairsDo
 213 Iterate over the associations, and evaluate the function for each, passing key and value as argument. Identical to link::#-keysValuesDo::
 214
 215 method::invert
 216 Return a new dictionary with all the values as keys and vice versa.
 217 code::
 218 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 219 d.invert;
 220 ::
 221
 222 subsection::Other instance methods
 223
 224 method::order
 225 Return an array of keys which corresponds to the order of the values of the dictionary.
 226 code::
 227 d = (a: 5, b: 7, c: 1, d: 0);
 228 d.order;
 229 d.atAll(d.order);       // returns items in order
 230 ::
 231
 232 method::powerset
 233 Return the set of all subsets: here an array of all sub-dictionaries.
 234 code::
 235 d = (a: 5, b: 7, c: 1, d: 0);
 236 d.powerset;
 237 ::
 238
 239 method::merge
 240 Combine two dictionaries into a new one by applying a function to each value. If strong::fill:: is true (default: true), values missing from one of them are kept as they are.
 241 code::
 242 d = (a: 5, b: 7, d: 0);
 243 e = (a: 3, b: -3, c: 1);
 244 merge(d, e, { |a, b| a + b });
 245 merge(d, e, { |a, b| a + b }, false);
 246 ::
 247 argument::that
 248 another dictionary.
 249 argument::func
 250 a link::Classes/Function::.
 251 argument::fill
 252 a link::Classes/Boolean::.
 253
 254 method::blend
 255 Blend two dictionaries into a new one by interpolating each value. If strong::fill:: is true (default: true), values missing from one of them are kept as they are.
 256 code::
 257 d = (a: 5, b: 7, d: 0);
 258 e = (a: 3, b: -3, c: 1);
 259 blend(d, e, 0.3);
 260 blend(d, e, 0.3, false);
 261
 262 d = (a: 500, b: 0.001);
 263 e = (a: 300, b: 0.1);
 264 blend(d, e, 0.3, specs: (a: \freq, b: \rq));
 265 ::
 266 argument::that
 267 another dictionary.
 268 argument::blend
 269 the blend ratio as a link::Classes/Float:: between 0.0 and 1.0.
 270 argument::fill
 271 a link::Classes/Boolean::.
 272 argument::specs
 273 a dictionary of link::Classes/Spec::s that are applied to each before blending.
 274
 275 method::asSortedArray
 276 Return the values in a sorted array of key value pairs.
 277 code::
 278 d = (a: 5, b: 7, c: 1, d: 0);
 279 d.asSortedArray;
 280 ::
 281
 282 method::asKeyValuePairs
 283 Return the values in an array of alternating key value pairs.
 284 code::
 285 d = (a: 5, b: 7, c: 1, d: 0);
 286 d.asKeyValuePairs;
 287 ::
 288
 289 method::embedInStream
 290 If the event is not nil, yields a copy, with all the elements of the receiver. See also link::Classes/Event::.
 291 code::
 292 // write a generator for dictionaries
 293 (
 294 d = (
 295         a: 5, b: 7, c: 1,
 296         rout: Routine { |inval|
 297                 inf.do { |i|
 298                         var event = d.copy.put(\count, i);
 299                         inval = event.embedInStream(inval);
 300                 }
 301         }
 302 );
 303 )
 304
 305 // draw new values
 306 d.rout.((z:999));
 307 d.rout.((z:1, a:0));
 308 d.rout.(());
 309
 310 // sound example
 311 // this also allows to use events or dictionaries in patterns directly:
 312 (
 313 d = (freq: 402, dur: 0.3);
 314         Pseq([
 315                 d,
 316                 (freq: 300, dur: 0.3),
 317                 d,
 318                 (freq: [400, 770, 800], dur: 1),
 319                 d,
 320                 (freq: 451, dur: 0.33)
 321         ], inf).play;
 322 );
 323
 324 d[\freq] = [900, 1002, 1102];
 325 d[\freq] = [200, 101, 1102];
 326 ::
 327
 328 SECTION::Overview
 329
 330 subsection::The Difference between Dictionary, IdentityDictionary, Environment, and Event
 331
 332 Often, the subclass link::Classes/Event:: is used as an IdentityDictionary, because there is a syntactical shortcut:
 333 code::
 334 a = (foo: 7);   // return a new Event.
 335 a.put(\foo, 2.718);
 336 a.at(\foo);
 337 a[\foo] = 3.5;  // different syntax for put
 338 ::
 339
 340 Event, Environment and IdentityDictionary differ mainly insofar from Dictionary as the strong::keys:: are taken to be identical (===) objects (see IdentityDictionary), instead of equal (==) objects. By consequence, the subclasses are also faster for indexing. Apart from this, the subclasses add specific functionality only. Because of its very common usage, the examples often use the shortcut for the subclass Event.
 341 code::
 342 // preliminary identity and equality of strings and symbols
 343 "hello" == "hello";     // true, but
 344 "hello" === "hello";    // false. However:
 345 \hello === \hello;      // true
 346
 347 // compare
 348 Dictionary["hello" -> 0, "hello" -> 1]; // Dictionary[ (hello -> 1) ]
 349 ("hello": 0, "hello": 1); // ( "hello": 1, "hello": 0 )
 350
 351 // for symbols as keys, the behaviour is identical:
 352 Dictionary[\hello -> 1, \hello -> 0];
 353 ( \hello: 1, \hello: 0 );
 354 ::
 355
 356