Docs/Types/Object.md

   1 Type: Object {#Object}
   2 ======================
   3
   4 A collection of Object functions.
   5
   6 ### See Also:
   7
   8 - [MDC Object][]
   9
  10 Function: Object.each {#Object:Object-each}
  11 ------------------------------------
  12
  13 Used to iterate through an object.
  14
  15 ### Syntax:
  16
  17         Object.each(obj, fn[, bind]);
  18
  19 ### Arguments:
  20
  21 1. obj          - (*object*) The object to iterate through.
  22 2. fn       - (*function*) The function to test for each element.
  23 3. bind     - (*object*, optional) The object to use as 'this' within the function. For more information see [Function:bind][].
  24
  25 #### Argument: fn
  26
  27 ##### Syntax:
  28
  29         fn(item, index, object)
  30
  31 ##### Arguments:
  32
  33 1. item   - (*mixed*) The current item in the array.
  34 2. index  - (*number*) The current item's key.
  35 3. object - (*mixed*) The actual array/object.
  36
  37 ### Example:
  38
  39     // alerts 'The first day of the week is Sunday', 'The second day of the week is Monday', etc.:
  40         Object.each({first: 'Sunday', second: 'Monday', third: 'Tuesday'}, function(value, key){
  41                 alert('The ' + key + ' day of the week is ' + value);
  42         });
  43
  44 ### Notes:
  45
  46 This method is an object-specific equivalent of *$each* from MooTools 1.2.
  47
  48
  49
  50 Function: Object.merge {#Object:Object-merge}
  51 --------------------------------------
  52
  53 Merges any number of objects recursively without referencing them or their sub-objects.
  54
  55 ### Syntax:
  56
  57         var merged = Object.merge(obj1, obj2[, obj3[, ...]]);
  58
  59 ### Arguments:
  60
  61 1. (objects) Any number of objects.
  62
  63 ### Returns:
  64
  65 * (*object*) The object that is created as a result of merging all the objects passed in.
  66
  67 ### Examples:
  68
  69         var obj1 = {a: 0, b: 1};
  70         var obj2 = {c: 2, d: 3};
  71         var obj3 = {a: 4, d: 5};
  72         var merged = Object.merge(obj1, obj2, obj3); // returns {a: 4, b: 1, c: 2, d: 5}, (obj2, and obj3 are unaltered)
  73
  74         merged === obj1; // true, obj1 gets altered and returned as merged object
  75
  76         var nestedObj1 = {a: {b: 1, c: 1}};
  77         var nestedObj2 = {a: {b: 2}};
  78         var nested = Object.merge(nestedObj1, nestedObj2); // returns: {a: {b: 2, c: 1}}
  79
  80
  81 Function: Object.clone {#Object:Object-clone}
  82 --------------------------------------
  83
  84 Returns a copy of an object.
  85
  86 ### Syntax:
  87
  88         var clone = Object.clone(obj);
  89
  90 ### Arguments:
  91
  92 1. (obj) The object to clone
  93
  94 ### Returns:
  95
  96 * (*object*) A copy of the passed object
  97
  98 ### Example:
  99
 100         var obj1 = {a: 0, b: 1};
 101         var obj2 = Object.clone(obj1);
 102
 103         obj1.a = 42;
 104         alert(obj1.a);  // alerts '42'
 105         alert(obj2.a);  // alerts '0'
 106
 107 ### Notes:
 108
 109 This is an object-specific equivalent of *$unlink* from MooTools 1.2.
 110
 111
 112
 113 Function: Object.append {#Object:Object-append}
 114 ----------------------------------------
 115
 116 Copies all the properties from the second object passed in to the first object passed in.
 117
 118 ### Syntax:
 119
 120         Object.append(original, extension);
 121
 122 ### Arguments:
 123
 124 1. original  - (*object*) The object to be extended.
 125 2. extension - (*object*) The object whose properties will be copied to original.
 126
 127 ### Returns:
 128
 129 * (*object*) The first object passed in, extended.
 130
 131 ### Examples:
 132
 133         var firstObj = {
 134                 name: 'John',
 135                 lastName: 'Doe'
 136         };
 137         var secondObj = {
 138                 age: '20',
 139                 sex: 'male',
 140                 lastName: 'Dorian'
 141         };
 142         Object.append(firstObj, secondObj);
 143         //firstObj is now: {name: 'John', lastName: 'Dorian', age: '20', sex: 'male'};
 144
 145 ### Notes:
 146
 147 This method is an object-specific equivalent of *$extend* from MooTools 1.2.
 148
 149
 150 Function: Object.subset {#Object:Object-subset}
 151 ----------------------------------------
 152
 153 Get a subset of an object.
 154
 155 ### Syntax:
 156
 157         Object.subset(object, keys);
 158
 159 ### Arguments:
 160
 161 1. object - (*object*) The object.
 162 2. keys - (*array*) An array with the keys.
 163
 164 ### Returns:
 165
 166 * (*object*) The subset of the Object.
 167
 168 ### Examples:
 169
 170         var object = {
 171                 a: 'one',
 172                 b: 'two',
 173                 c: 'three'
 174         };
 175         Object.subset(object, ['a', 'c']); // returns {a: 'one', c: 'three'}
 176
 177
 178
 179 Function: Object.map {#Object:Object-map}
 180 ----------------------------
 181
 182 Creates a new map with the results of calling a provided function on every value in the map.
 183
 184 ### Syntax:
 185
 186         var mappedObject = Object.map(object, fn[, bind]);
 187
 188 ### Arguments:
 189
 190 1. object - (*object*) The object.
 191 2. fn   - (*function*) The function to produce an element of the Object from an element of the current one.
 192 3. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 193
 194 #### Argument: fn
 195
 196 ##### Syntax:
 197
 198         fn(value, key, object)
 199
 200 ##### Arguments:
 201
 202 1. value - (*mixed*) The current value in the object.
 203 2. key   - (*string*) The current value's key in the object.
 204 3. object - (*object*) The actual object.
 205
 206 ### Returns:
 207
 208 * (*object*) The new mapped object.
 209
 210 ### Examples:
 211
 212         var myObject = {a: 1, b: 2, c: 3};
 213         var timesTwo = Object.map(timesTwo, function(value, key){
 214                 return value * 2;
 215         }); // timesTwo now holds an object containing: {a: 2, b: 4, c: 6};
 216
 217
 218
 219 Function: Object.filter {#Object:Object-filter}
 220 ----------------------------------
 221
 222 Creates a new object with all of the elements of the object for which the provided filtering function returns true.
 223
 224 ### Syntax:
 225
 226         var filteredObject = Object.filter(object, fn[, bind]);
 227
 228 ### Arguments:
 229
 230 1. object - (*object*) The object.
 231 2. fn   - (*function*) The function to test each element of the Object. This function is passed the value and its key in the Object.
 232 3. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 233
 234 #### Argument: fn
 235
 236 ##### Syntax:
 237
 238         fn(value, key, object)
 239
 240 ##### Arguments:
 241
 242 1. value - (*mixed*) The current value in the object.
 243 2. key   - (*string*) The current value's key in the object.
 244 3. object - (*object*) The actual object.
 245
 246 ### Returns:
 247
 248 * (*object*) The new filtered object.
 249
 250 ### Examples:
 251
 252         var myObject = {a: 10, b: 20, c: 30};
 253         var biggerThanTwenty = Object.filter(myObject, function(value, key){
 254                 return value > 20;
 255         }); // biggerThanTwenty now holds an object containing: {c: 30}
 256
 257
 258
 259 Function: Object.every {#Object:Object-every}
 260 --------------------------------
 261
 262 Returns true if every value in the object satisfies the provided testing function.
 263
 264 ### Syntax:
 265
 266         var allPassed = Object.every(object, fn[, bind]);
 267
 268 ### Arguments:
 269
 270 1. object - (*object*) The object.
 271 2. fn   - (*function*) The function to test each element of the Object. This function is passed the value and its key in the Object.
 272 3. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 273
 274 #### Argument: fn
 275
 276 ##### Syntax:
 277
 278         fn(value, key, object)
 279
 280 ##### Arguments:
 281
 282 1. value - (*mixed*) The current value in the object.
 283 2. key   - (*string*) The current value's key in the object.
 284 3. object  - (*object*) The actual object.
 285
 286 ### Returns:
 287
 288 * (*boolean*) If every value in the Object satisfies the provided testing function, returns true. Otherwise, returns false.
 289
 290 ### Examples:
 291
 292         var myObject = {a: 10, b: 4, c: 25, d: 100};
 293         var areAllBigEnough = Object.every(myObject, function(value, key){
 294                 return value > 20;
 295         }); // areAllBigEnough = false
 296
 297
 298
 299 Function: Object.some {#Object:Object-some}
 300 ------------------------------
 301
 302 Returns true if at least one value in the object satisfies the provided testing function.
 303
 304 ### Syntax:
 305
 306         var anyPassed = Object.some(object, fn[, bind]);
 307
 308 ### Arguments:
 309
 310 1. object - (*object*) The object.
 311 2. fn   - (*function*) The function to test each element of the object. This function is passed the value and its key in the object.
 312 3. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 313
 314 #### Argument: fn
 315
 316 ##### Syntax:
 317
 318         fn(value, key, object)
 319
 320
 321 ##### Arguments:
 322
 323 1. value - (*mixed*) The current value in the object.
 324 2. key   - (*string*) The current value's key in the object.
 325 3. object  - (*object*) The actual object.
 326
 327 ### Returns:
 328
 329 * (*boolean*) If any value in the object satisfies the provided testing function, returns true. Otherwise, returns false.
 330
 331 ### Examples:
 332
 333         var myObject = {a: 10, b: 4, c: 25, d: 100};
 334         var areAnyBigEnough = Object.some(myObject, function(value, key){
 335                 return value > 20;
 336         }); //isAnyBigEnough = true
 337
 338
 339
 340 Function: Object.keys {#Object:Object-keys}
 341 ------------------------------------
 342
 343 Returns an array containing all the keys, in the same order as the values returned by [Object:values][].
 344
 345 ### Syntax:
 346
 347         var keys = Object.keys(object);
 348
 349 ### Arguments:
 350
 351 1. object - (*object*) The object.
 352
 353 ### Returns:
 354
 355 * (*array*) An array containing all the keys of the object.
 356
 357
 358
 359 Function: Object.values {#Object:Object-values}
 360 ----------------------------------------
 361
 362 Returns an array containing all the values, in the same order as the keys returned by [Object:keys][].
 363
 364 ### Syntax:
 365
 366         var values = Object.values(object);
 367
 368 ### Arguments:
 369
 370 1. object - (*object*) The object.
 371
 372 ### Returns:
 373
 374 * (*array*) An array containing all the values of the object.
 375
 376
 377
 378 Function: Object.getLength {#Object:Object-getLength}
 379 ----------------------------------------
 380
 381 Returns the number of keys in the object.
 382
 383 ### Syntax:
 384
 385         var length = Object.getLength(object);
 386
 387 ### Arguments:
 388
 389 1. object - (*object*) The object.
 390
 391 ### Returns:
 392
 393 * (*number*) The length of the object.
 394
 395 ### Examples:
 396
 397         var myObject = {
 398                 name: 'John',
 399                 lastName: 'Doe'
 400         });
 401         Object.getLength(myObject); // returns 2
 402
 403
 404
 405 Function: Object.keyOf {#Object:Object-keyOf}
 406 --------------------------------
 407
 408 Returns the key of the specified value. Synonymous with [Array:indexOf][].
 409
 410 ### Syntax:
 411
 412         var key = Object.keyOf(object);
 413
 414 ### Arguments:
 415
 416 1. object - (*object*) The object.
 417 2. item - (*mixed*) The item to search for in the object.
 418
 419 ### Returns:
 420
 421 * (*string*) If the object has a the specified item in it, returns the key of that item.
 422 * (*boolean*) Otherwise, returns false.
 423
 424 ### Examples:
 425
 426         var myObject = {a: 'one', b: 'two', c: 3};
 427         Object.keyOf(myObject,'two'); // returns 'b'
 428         Object.keyOf(myObject,3); // returns 'c'
 429         Object.keyOf(myObject,'four'); // returns false
 430
 431
 432
 433 Function: Object.contains {#Object:Object-contains}
 434 --------------------------------------
 435
 436 Tests for the presence of a specified value in the object.
 437
 438 ### Syntax:
 439
 440         var inObject = Object.contains(object, value);
 441
 442 ### Arguments:
 443
 444 1. object - (*object*) The object.
 445 2. value - (*mixed*) The value to search for in the Object.
 446
 447 ### Returns:
 448
 449 * (*boolean*) If the object has the passed in value in any of the keys, returns true. Otherwise, returns false.
 450
 451 ### Examples:
 452
 453         var myObject = {a: 'one', b: 'two', c: 'three'};
 454         Object.contains(myObject, 'one'); // returns true
 455         Object.contains(myObject, 'four'); // returns false
 456
 457
 458
 459 Function: Object.toQueryString {#Object:Object-toQueryString}
 460 ------------------------------------------------
 461
 462 Generates a query string from key/value pairs in an object and URI encodes the values.
 463
 464 ### Syntax:
 465
 466         var queryString = Object.toQueryString(object);
 467
 468 ### Arguments:
 469
 470 1. object - (*object*) The object.
 471 2. source - (*object*) The object to generate the query string from.
 472
 473 ### Returns:
 474
 475 * (*string*) The query string.
 476
 477 ### Examples:
 478
 479         Object.toQueryString({apple: 'red', lemon: 'yellow'}); // returns 'apple=red&lemon=yellow'
 480
 481
 482 Deprecated Functions {#Deprecated-Functions}
 483 ============================================
 484
 485 Type: Hash {#Deprecated-Functions:Hash}
 486 --------------------------------------
 487
 488 Hash has been deprecated. Each Hash method has a similar Object method or a Vanilla JS equivalent.
 489
 490 Hash Method: has {#Deprecated-Functions:Hash:has}
 491 -------------------------------------------------
 492
 493 You could simply use `myObject.myKey != undefined`
 494
 495 Hash Method: keyOf {#Deprecated-Functions:Hash:keyOf}
 496 -----------------------------------------------------
 497
 498 Use [Object.keyOf](#Object:Object-keyOf)
 499
 500
 501 Hash Method: hasValue {#Deprecated-Functions:Hash:hasValue}
 502 ------------------------------------------------------------
 503
 504 Use [Object.contains](#Object:Object-contains)
 505
 506
 507 Hash Method: extend {#Deprecated-Functions:Hash:extend}
 508 --------------------------------------------------------
 509
 510 Use [Object.append](#Object:Object-append)
 511
 512
 513 Hash Method: combine {#Deprecated-Functions:Hash:combine}
 514 ---------------------------------------------------------
 515
 516 Use [Object.merge](#Object:Object-merge)
 517
 518
 519 Hash Method: erase {#Deprecated-Functions:Hash:erase}
 520 -----------------------------------------------------
 521
 522 Use `delete myObject.a`
 523
 524 Hash Method: get {#Deprecated-Functions:Hash:get}
 525 -------------------------------------------------
 526
 527 Use `myObject.myKey`
 528
 529
 530 Hash Method: set {#Deprecated-Functions:Hash:set}
 531 -------------------------------------------------
 532
 533 Use `myObject.myKey = value`
 534
 535
 536 Hash Method: empty {#Deprecated-Functions:Hash:empty}
 537 -----------------------------------------------------
 538
 539 Use `myObject = {}`
 540
 541
 542 Hash Method: include {#Deprecated-Functions:Hash:include}
 543 ---------------------------------------------------------
 544
 545 Use `if(myObject.myKey == undefined) myObject.myKey = value`
 546
 547
 548 Hash Method: map {#Deprecated-Functions:Hash:map}
 549 -------------------------------------------------
 550
 551 Use [Object.map](#Object:Object-map)
 552
 553
 554 Hash Method: filter {#Deprecated-Functions:Hash:filter}
 555 -------------------------------------------------------
 556
 557 Use [Object.filter](#Object:Object-filter)
 558
 559
 560 Hash Method: every {#Deprecated-Functions:Hash:every}
 561 -----------------------------------------------------
 562
 563 Use [Object.every](#Object:Object-every)
 564
 565
 566 Hash Method: some {#Deprecated-Functions:Hash:some}
 567 -------------------------------------------------------
 568
 569 Use [Object.some](#Object:Object-some)
 570
 571
 572 Hash Method: getKeys {#Deprecated-Functions:Hash:getKeys}
 573 -------------------------------------------------------
 574
 575 Use [Object.keys](#Object:Object-keys)
 576
 577
 578 Hash Method: getValues {#Deprecated-Functions:Hash:getValues}
 579 ------------------------------------------------------------
 580
 581 Use [Object.values](#Object:Object-values)
 582
 583
 584 Hash Method: toQueryString {#Deprecated-Functions:Hash:toQueryString}
 585 -------------------------------------------------------
 586
 587 Use [Object.toQueryString](#Object:Object-toQueryString)
 588
 589
 590
 591
 592 [MDC Object]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Object
 593 [Object]: #Object
 594 [Array:indexOf]: /core/Types/Array/#Array:indexOf
 595 [Object:values]: #Object:values
 596 [Object:keys]: #Object:keys
 597 [Function:bind]: /core/Types/Function#Function:bind