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::value
  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 method::keys
  94 Return a link::Classes/Set:: of all keys.
  95 code::
  96 d = (hello: 9, whello: "world");
  97 d.keys;
  98 ::
  99
 100 method::values
 101 Return a link::Classes/List:: of all values.
 102 code::
 103 d = (hello: 9, whello: "world");
 104 d.values;
 105 ::
 106
 107 method::atAll
 108 Return an link::Classes/Array:: of all values for the given keys.
 109 code::
 110 d = (hello: 9, whello: "world", z: 99, c: 0.33);
 111 d.atAll([\hello, \z, \hello, \c, \whello]);
 112 ::
 113
 114 method::getPairs
 115 Return an link::Classes/Array:: with all keys and values pairwise.
 116 code::
 117 d = (hello: 9, whello: 77, z: 99);
 118 d.getPairs;
 119 ::
 120
 121 method::associationAt
 122 Access the link::Classes/Association:: that has the given key.
 123 code::
 124 d = (robot: 99);
 125 d.associationAt(\robot);        // Get the value associated with key
 126 ::
 127
 128 method::findKeyForValue
 129 Try to find a given value and return its key.
 130 code::
 131 d = (hello: 1, whello: 1976);
 132 d.findKeyForValue(1);
 133 ::
 134
 135 method::matchAt
 136 The dictionary's keys are used as conditions against which the arbitrary item is matched. See: link::Reference/matchItem::
 137 note::
 138 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.
 139 ::
 140 list::
 141 ## If the key is an object, the item will be matched by identity (if key === item, the value will be returned).
 142 ## If the key is a collection, the item is matched if it's contained in the collection.
 143 ## 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.
 144 ::
 145 code::
 146 (
 147 d = (
 148         0: \zero,
 149         \abc: \alpha,
 150         [1, 2, 3, 5, 8, 13, 21]: \fibonacci,
 151         { |x| try { x.even } }: \even // try is needed because argument might not be a number
 152         );
 153 );
 154
 155 d.matchAt(0)
 156 d.matchAt(1)
 157 d.matchAt(2)    // matches both 'fibonacci' and 'even', either may be returned
 158 d.matchAt(4)
 159 d.matchAt(\abc)
 160 ::
 161
 162 method::trueAt
 163 Returns link::Classes/True:: if the item at the key is true, otherwise false. This method is also valid in link::Classes/Object::.
 164
 165 method::falseAt
 166 Returns link::Classes/False:: if the item at the key is not true, otherwise true. This method is inherited from link::Classes/Object::.
 167
 168 subsection::Iteration/Enumeration
 169 Most methods for iteration work analogously to Dictionary's superclasses, see e.g. link::Classes/Collection::.
 170
 171 method::do, collect, reject, select
 172 code::
 173 // do, collect, reject, select
 174 d = Dictionary[\a -> "hello", \b -> "robot", \c -> [1, 2, 3]];
 175 d = (a: "hello", b: "robot", c: [1, 2, 3]); // equivalent
 176 d.do { |item, i| [item, i].postln };
 177 d.collect { |item| item + 100 };
 178 d.reject { |item| item.size > 4 };
 179 d.select { |item| item.size > 4 };
 180 ::
 181
 182 method::keysValuesDo
 183 Iterate over the associations, and evaluate the function for each, passing key and value as argument.
 184 code::
 185 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 186 d.keysValuesDo { |key, value| postln("the key: " ++ key ++ " the value: " ++ value) };
 187 ::
 188
 189 method::keysValuesChange
 190 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::).
 191 code::
 192 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 193 d.keysValuesChange { |key, value| "the key: " ++ key ++ " the value: " ++ value };
 194 d;
 195 ::
 196
 197 method::keysDo
 198 Iterate over the associations, and evaluate the function for each, passing key as argument.
 199 code::
 200 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 201 d.keysDo { |key| postln("the key: " ++ key) };
 202 ::
 203
 204 method::associationsDo
 205 Iterate over the associations, and evaluate the function for each.
 206 code::
 207 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 208 d.associationsDo { |assoc| postln("the association: " ++ assoc) };
 209 ::
 210
 211 method::pairsDo
 212 Iterate over the associations, and evaluate the function for each, passing key and value as argument. Identical to link::#-keysValuesDo::
 213
 214 method::invert
 215 Return a new dictionary with all the values as keys and vice versa.
 216 code::
 217 d = (a: "hello", b: "robot", c: [1, 2, 3]);
 218 d.invert;
 219 ::
 220
 221 subsection::Other instance methods
 222
 223 method::order
 224 Return an array of keys which corresponds to the order of the values of the dictionary.
 225 code::
 226 d = (a: 5, b: 7, c: 1, d: 0);
 227 d.order;
 228 d.atAll(d.order);       // returns items in order
 229 ::
 230
 231 method::powerset
 232 Return the set of all subsets: here an array of all sub-dictionaries.
 233 code::
 234 d = (a: 5, b: 7, c: 1, d: 0);
 235 d.powerset;
 236 ::
 237
 238 method::merge
 239 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.
 240 code::
 241 d = (a: 5, b: 7, d: 0);
 242 e = (a: 3, b: -3, c: 1);
 243 merge(d, e, { |a, b| a + b });
 244 merge(d, e, { |a, b| a + b }, false);
 245 ::
 246 argument::that
 247 another dictionary.
 248 argument::func
 249 a link::Classes/Function::.
 250 argument::fill
 251 a link::Classes/Boolean::.
 252
 253 method::blend
 254 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.
 255 code::
 256 d = (a: 5, b: 7, d: 0);
 257 e = (a: 3, b: -3, c: 1);
 258 blend(d, e, 0.3);
 259 blend(d, e, 0.3, false);
 260
 261 d = (a: 500, b: 0.001);
 262 e = (a: 300, b: 0.1);
 263 blend(d, e, 0.3, specs: (a: \freq, b: \rq));
 264 ::
 265 argument::that
 266 another dictionary.
 267 argument::blend
 268 the blend ratio as a link::Classes/Float:: between 0.0 and 1.0.
 269 argument::fill
 270 a link::Classes/Boolean::.
 271 argument::specs
 272 a dictionary of link::Classes/Spec::s that are applied to each before blending.
 273
 274 method::asSortedArray
 275 Return the values in a sorted array of key value pairs.
 276 code::
 277 d = (a: 5, b: 7, c: 1, d: 0);
 278 d.asSortedArray;
 279 ::
 280
 281 method::asKeyValuePairs
 282 Return the values in an array of alternating key value pairs.
 283 code::
 284 d = (a: 5, b: 7, c: 1, d: 0);
 285 d.asKeyValuePairs;
 286 ::
 287
 288 method::embedInStream
 289 If the event is not nil, yields a copy, with all the elements of the receiver. See also link::Classes/Event::.
 290 code::
 291 // write a generator for dictionaries
 292 (
 293 d = (
 294         a: 5, b: 7, c: 1,
 295         rout: Routine { |inval|
 296                 inf.do { |i|
 297                         var event = d.copy.put(\count, i);
 298                         inval = event.embedInStream(inval);
 299                 }
 300         }
 301 );
 302 )
 303
 304 // draw new values
 305 d.rout.((z:999));
 306 d.rout.((z:1, a:0));
 307 d.rout.(());
 308
 309 // sound example
 310 // this also allows to use events or dictionaries in patterns directly:
 311 (
 312 d = (freq: 402, dur: 0.3);
 313         Pseq([
 314                 d,
 315                 (freq: 300, dur: 0.3),
 316                 d,
 317                 (freq: [400, 770, 800], dur: 1),
 318                 d,
 319                 (freq: 451, dur: 0.33)
 320         ], inf).play;
 321 );
 322
 323 d[\freq] = [900, 1002, 1102];
 324 d[\freq] = [200, 101, 1102];
 325 ::
 326
 327 SECTION::Overview
 328
 329 subsection::The Difference between Dictionary, IdentityDictionary, Environment, and Event
 330
 331 Often, the subclass link::Classes/Event:: is used as an IdentityDictionary, because there is a syntactical shortcut:
 332 code::
 333 a = (foo: 7);   // return a new Event.
 334 a.put(\foo, 2.718);
 335 a.at(\foo);
 336 a[\foo] = 3.5;  // different syntax for put
 337 ::
 338
 339 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.
 340 code::
 341 // preliminary identity and equality of strings and symbols
 342 "hello" == "hello";     // true, but
 343 "hello" === "hello";    // false. However:
 344 \hello === \hello;      // true
 345
 346 // compare
 347 Dictionary["hello" -> 0, "hello" -> 1]; // Dictionary[ (hello -> 1) ]
 348 ("hello": 0, "hello": 1); // ( "hello": 1, "hello": 0 )
 349
 350 // for symbols as keys, the behaviour is identical:
 351 Dictionary[\hello -> 1, \hello -> 0];
 352 ( \hello: 1, \hello: 0 );
 353 ::
 354
 355