Docs/Native/Hash.md

   1 Native: Hash {#Hash}
   2 ====================
   3
   4 A custom Object ({}) implementation which does not account for prototypes when setting, getting, or iterating.
   5 Useful because in JavaScript, we cannot use Object.prototype. Instead, we can use Hash.prototype!
   6
   7
   8 Hash Method: constructor {#Hash:constructor}
   9 --------------------------------------------
  10
  11 ### Syntax:
  12
  13         var myHash = new Hash([object]);
  14
  15 ### Arguments:
  16
  17 1. object - (*mixed*) A hash or object to implement.
  18
  19 ### Returns:
  20
  21 * (*hash*) A new Hash instance.
  22
  23 ### Examples:
  24
  25         var myHash = new Hash({
  26                 aProperty: true,
  27                 aMethod: function(){
  28                         return true;
  29                 }
  30         });
  31         alert(myHash.has('aMethod')); //Returns true.
  32
  33
  34
  35 Hash Method: each {#Hash:each}
  36 -------------------------------
  37
  38 Calls a function for each key-value pair in the object.
  39
  40 ### Syntax:
  41
  42         myHash.each(fn[, bind]);
  43
  44 ### Arguments:
  45
  46 1. fn   - (*function*) The function which should be executed on each item in the Hash. This function is passed the item and its key in the Hash.
  47 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information, see [Function:bind][].
  48
  49 #### Argument: fn
  50
  51 ##### Syntax:
  52
  53         fn(value, key, hash)
  54
  55 ##### Arguments:
  56
  57 1. value - (*mixed*) The current value in the hash.
  58 2. key   - (*string*) The current value's key in the hash.
  59 3. hash  - (*hash*) The actual hash.
  60
  61 ### Examples:
  62
  63         var hash = new Hash({first: "Sunday", second: "Monday", third: "Tuesday"});
  64         hash.each(function(value, key){
  65                 alert("the " + key + " day of the week is " + value);
  66         }); //Alerts "the first day of the week is Sunday", "the second day of the week is Monday", etc.
  67
  68
  69
  70 Hash Method: has {#Hash:has}
  71 ----------------------------
  72
  73 Tests for the presence of a specified key in the Hash.
  74
  75 ### Syntax:
  76
  77         var inHash = myHash.has(item);
  78
  79 ### Arguments:
  80
  81 1. key - (*string*) The key to search for in the Hash.
  82
  83 ### Returns:
  84
  85 * (*boolean*) If the Hash has a defined value for the specified key, returns true. Otherwise, returns false.
  86
  87 ### Examples:
  88
  89         var hash = new Hash({'a': 'one', 'b': 'two', 'c': 'three'});
  90         hash.has('a'); //returns true
  91         hash.has('d'); //returns false
  92
  93
  94 ### Notes:
  95
  96 - Testing for a Hash prototype will never return true. Only testing the actual properties of the Hash will return true.
  97
  98
  99
 100 Hash Method: keyOf {#Hash:keyOf}
 101 --------------------------------
 102
 103 Returns the key of the specified value. Synonymous with [Array:indexOf][].
 104
 105 ### Syntax:
 106
 107         var key = myHash.keyOf(item);
 108
 109 ### Arguments:
 110
 111 1. item - (*mixed*) The item to search for in the Hash.
 112
 113 ### Returns:
 114
 115 * (*string*) If the Hash has a the specified item in it, returns the key of that item.
 116 * (*boolean*) Otherwise, returns false.
 117
 118 ### Examples:
 119
 120         var hash = new Hash({'a': 'one', 'b': 'two', 'c': 3});
 121         hash.keyOf('two'); //returns 'b'
 122         hash.keyOf(3); //returns 'c'
 123         hash.keyOf('four') //returns false
 124
 125 ### Notes:
 126
 127 - Testing for a Hash prototype will never return its key. Only the actual properties of the Hash will return their associated key.
 128
 129
 130
 131 Hash Method: hasValue {#Hash:hasValue}
 132 --------------------------------------
 133
 134 Tests for the presence of a specified value in the Hash.
 135
 136 ### Syntax:
 137
 138         var inHash = myHash.hasValue(value);
 139
 140 ### Arguments:
 141
 142 1. value - (*mixed*) The value to search for in the Hash.
 143
 144 ### Returns:
 145
 146 * (*boolean*) If the Hash has the passed in value in any of the keys, returns true. Otherwise, returns false.
 147
 148 ### Examples:
 149
 150         var hash = new Hash({'a': 'one', 'b': 'two', 'c': 'three'});
 151         hash.hasValue('one'); //returns true
 152         hash.hasValue('four'); //returns false
 153
 154
 155 Hash Method: extend {#Hash:extend}
 156 ----------------------------------
 157
 158 Extends this Hash with the key-value pairs from the object passed in.
 159
 160 ### Syntax:
 161
 162         myHash.extend(properties);
 163
 164 ### Arguments:
 165
 166 1. properties - (*object*) The object whose items should be extended into this Hash
 167
 168 ### Returns:
 169
 170 * (*hash*) This Hash, extended.
 171
 172 ### Examples:
 173
 174         var hash = new Hash({
 175                 'name': 'John',
 176                 'lastName': 'Doe'
 177         });
 178         var properties = {
 179                 'age': '20',
 180                 'sex': 'male',
 181                 'lastName': 'Dorian'
 182         };
 183         hash.extend(properties);
 184         //hash now holds an object containing: { 'name': 'John', 'lastName': 'Dorian', 'age': '20', 'sex': 'male' };
 185
 186
 187
 188 Hash Method: combine {#Hash:combine}
 189 --------------------------------
 190
 191 Combines this Hash with the key-value pairs of the object passed in. Does not allow duplicates (old values are **not** overwritten by new ones) and is case and type sensitive.
 192
 193 ### Syntax:
 194
 195         myHash.combine(properties);
 196
 197 ### Arguments:
 198
 199 1. properties - (*object*) The object whose items should be combined into this Hash.
 200
 201 ### Returns:
 202
 203 * (*hash*) This Hash, combined with the new key-value pairs.
 204
 205 ### Examples:
 206
 207         var hash = new Hash({
 208                 'name': 'John',
 209                 'lastName': 'Doe'
 210         });
 211         var properties = {
 212                 'name': 'Jane'
 213                 'age': '20',
 214                 'sex': 'male',
 215                 'lastName': 'Dorian'
 216         };
 217         hash.combine(properties);
 218         //hash now holds an object containing: { 'name': 'John', 'lastName': 'Doe', 'age': '20', 'sex': 'male' };
 219
 220
 221
 222 Hash Method: erase {#Hash:erase}
 223 ----------------------------------
 224
 225 Removes the specified key from the Hash.
 226
 227 ### Syntax:
 228
 229         myHash.erase(key);
 230
 231 ### Arguments:
 232
 233 1. key - (*string*) The key to search for in the Hash.
 234
 235 ### Returns:
 236
 237 * (*hash*) This Hash with the specified key and its value removed.
 238
 239 ### Examples:
 240
 241         var hash = new Hash({
 242                 'name': 'John',
 243                 'lastName': 'Doe'
 244         });
 245         hash.erase('lastName');
 246         //hash now holds an object containing: { 'name': 'John' };
 247
 248
 249
 250 Hash Method: get {#Hash:get}
 251 ----------------------------
 252
 253 Retrieves a value from the hash.
 254
 255 ### Syntax:
 256
 257         myHash.get(key);
 258
 259 ### Arguments:
 260
 261 1. key - (*string*) The key to retrieve in the Hash.
 262
 263 ### Returns:
 264
 265 * (*mixed*) Returns the value that corresponds to the key if found.
 266 * (*false*) null if the key doesn't exist
 267
 268 ### Examples:
 269
 270         var hash = new Hash({
 271                 'name': 'John',
 272                 'lastName': 'Doe'
 273         });
 274         hash.get('name'); //returns 'John'
 275
 276
 277
 278 Hash Method: set {#Hash:set}
 279 ----------------------------
 280
 281 Adds a key-value pair to the hash or replaces a previous value associated with the specified key.
 282
 283 ### Syntax:
 284
 285         myHash.set(key, value);
 286
 287 ### Arguments:
 288
 289 1. key   - (*string*) The key to insert or modify in the Hash.
 290 2. value - (*mixed*) The value to associate with the specified key in the Hash.
 291
 292 ### Returns:
 293
 294 * (*hash*) This Hash with the specified key set to the specified value.
 295
 296 ### Examples:
 297
 298         var hash = new Hash({
 299                 'name': 'John',
 300                 'lastName': 'Doe'
 301         });
 302         hash.set('name', 'Michelle'); //hash.name is now 'Michelle'
 303
 304
 305
 306 Hash Method: empty {#Hash:empty}
 307 --------------------------------
 308
 309 Empties the hash.
 310
 311 ### Syntax:
 312
 313         myHash.empty();
 314
 315 ### Examples:
 316
 317         var hash = new Hash({
 318                 'name': 'John',
 319                 'lastName': 'Doe'
 320         });
 321         hash.empty();
 322         //hash now holds an empty object: {}
 323
 324
 325
 326 Hash Method: include {#Hash:include}
 327 ------------------------------------
 328
 329 Includes the specified key-value pair in the Hash if the key doesn't already exist.
 330
 331 ### Syntax:
 332
 333         myHash.include(key, value);
 334
 335 ### Arguments:
 336
 337 1. key   - (*string*) The key to insert into the Hash.
 338 2. value - (*mixed*) The value to associate with the specified key in the Hash.
 339
 340 ### Returns:
 341
 342 * (*hash*) This Hash with the specified key included if it did not previously exist.
 343
 344 ### Examples:
 345
 346         var hash = new Hash({
 347                 'name': 'John',
 348                 'lastName': 'Doe'
 349         });
 350         hash.include('name', 'Michelle'); //hash is unchanged
 351         hash.include('age', 25); //hash.age is now 25
 352
 353
 354
 355 Hash Method: map {#Hash:map}
 356 ----------------------------
 357
 358 Creates a new map with the results of calling a provided function on every value in the map.
 359
 360 ### Syntax:
 361
 362         var mappedHash = myHash.map(fn[, bind]);
 363
 364 ### Arguments:
 365
 366 1. fn   - (*function*) The function to produce an element of the new Hash from an element of the current one.
 367 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 368
 369 #### Argument: fn
 370
 371 ##### Syntax:
 372
 373         fn(value, key, hash)
 374
 375 ##### Arguments:
 376
 377 1. value - (mixed) The current value in the hash.
 378 2. key   - (string) The current value's key in the hash.
 379 3. hash  - (hash) The actual hash.
 380
 381 ### Returns:
 382
 383 * (*hash*) The new mapped hash.
 384
 385 ### Examples:
 386
 387         var timesTwo = new Hash({a: 1, b: 2, c: 3}).map(function(item, index){
 388                 return item * 2;
 389         }); //timesTwo now holds an object containing: {a: 2, b: 4, c: 6};
 390
 391
 392
 393 Hash Method: filter {#Hash:filter}
 394 ----------------------------------
 395
 396 Creates a new Hash with all of the elements of the Hash for which the provided filtering function returns true.
 397
 398 ### Syntax:
 399
 400         var filteredHash = myHash.filter(fn[, bind]);
 401
 402 ### Arguments:
 403
 404 1. fn   - (*function*) The function to test each element of the Hash. This function is passed the value and its key in the Hash.
 405 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 406
 407 #### Argument: fn
 408
 409 ##### Syntax:
 410
 411         fn(value, key, hash)
 412
 413 ##### Arguments:
 414
 415 1. value - (*mixed*) The current value in the hash.
 416 2. key   - (*string*) The current value's key in the hash.
 417 3. hash  - (*hash*) The actual hash.
 418
 419 ### Returns:
 420
 421 * (*hash*) The new filtered hash.
 422
 423 ### Examples:
 424
 425         var biggerThanTwenty = new Hash({a: 10, b: 20, c: 30}).filter(function(value, key){
 426                 return value > 20;
 427         }); //biggerThanTwenty now holds an object containing: {c: 30}
 428
 429
 430 Hash Method: every {#Hash:every}
 431 --------------------------------
 432
 433 Returns true if every value in the object satisfies the provided testing function.
 434
 435 ### Syntax:
 436
 437         var allPassed = myHash.every(fn[, bind]);
 438
 439 ### Arguments:
 440
 441 1. fn   - (*function*) The function to test each element of the Hash. This function is passed the value and its key in the Hash.
 442 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind].
 443
 444 #### Argument: fn
 445
 446 ##### Syntax:
 447
 448         fn(value, key, hash)
 449
 450 ##### Arguments:
 451
 452 1. value - (*mixed*) The current value in the hash.
 453 2. key   - (*string*) The current value's key in the hash.
 454 3. hash  - (*hash*) The actual hash.
 455
 456 ### Returns:
 457
 458 * (*boolean*) If every value in the Hash satisfies the provided testing function, returns true. Otherwise, returns false.
 459
 460 ### Examples:
 461
 462         var areAllBigEnough = ({a: 10, b: 4, c: 25, d: 100}).every(function(value, key){
 463                 return value > 20;
 464         }); //areAllBigEnough = false
 465
 466
 467 Hash Method: some {#Hash:some}
 468 ------------------------------
 469
 470 Returns true if at least one value in the object satisfies the provided testing function.
 471
 472 ### Syntax:
 473
 474         var anyPassed = myHash.any(fn[, bind]);
 475
 476 ### Arguments:
 477
 478 1. fn   - (*function*) The function to test each element of the Hash. This function is passed the value and its key in the Hash.
 479 2. bind - (*object*, optional) The object to use as 'this' in the function. For more information see [Function:bind][].
 480
 481 #### Argument: fn
 482
 483 ##### Syntax:
 484
 485         fn(value, key, hash)
 486
 487
 488 ##### Arguments:
 489
 490 1. value - (*mixed*) The current value in the hash.
 491 2. key   - (*string*) The current value's key in the hash.
 492 3. hash  - (*hash*) The actual hash.
 493
 494 ### Returns:
 495
 496 * (*boolean*) If any value in the Hash satisfies the provided testing function, returns true. Otherwise, returns false.
 497
 498 ### Examples:
 499
 500         var areAnyBigEnough = ({a: 10, b: 4, c: 25, d: 100}).some(function(value, key){
 501                 return value > 20;
 502         }); //isAnyBigEnough = true
 503
 504
 505
 506 Hash Method: getClean {#Hash:getClean}
 507 --------------------------------------
 508
 509 Returns a a clean object from an Hash.
 510
 511 ### Syntax:
 512
 513         myHash.getClean();
 514
 515 ### Returns:
 516
 517 * (*object*) a clean object
 518
 519 ### Examples:
 520
 521         var hash = new Hash({
 522                 'name': 'John',
 523                 'lastName': 'Doe'
 524         });
 525         hash = hash.getClean(); // hash doesnt contain Hash prototypes anymore
 526         hash.each() //error!
 527
 528
 529
 530 Hash Method: getKeys {#Hash:getKeys}
 531 ------------------------------------
 532
 533 Returns an array containing all the keys, in the same order as the values returned by [Hash:getValues][].
 534
 535 ### Syntax:
 536
 537         var keys = myHash.getKeys();
 538
 539 ### Returns:
 540
 541 * (*array*) An array containing all the keys of the hash.
 542
 543
 544
 545 Hash Method: getValues {#Hash:getValues}
 546 ----------------------------------------
 547
 548 Returns an array containing all the values, in the same order as the keys returned by [Hash:getKeys][].
 549
 550 ### Syntax:
 551
 552         var values = myHash.getValues();
 553
 554 ### Returns:
 555
 556 * (*array*) An array containing all the values of the hash.
 557
 558
 559
 560 Hash Method: getLength {#Hash:getLength}
 561 ----------------------------------------
 562
 563 Returns the number of keys in the Hash.
 564
 565 ### Syntax:
 566
 567         var length = myHash.getLength();
 568
 569 ### Returns:
 570
 571 * (*number*) The length of the Hash.
 572
 573 ### Examples:
 574
 575         var hash = new Hash({
 576                 'name': 'John',
 577                 'lastName': 'Doe'
 578         });
 579         hash.getLength(); // returns 2
 580
 581
 582
 583 Hash Method: toQueryString {#Hash:toQueryString}
 584 ------------------------------------------------
 585
 586 Generates a query string from key/value pairs in an object and URI encodes the values.
 587
 588 ### Syntax:
 589
 590         var queryString = myHash.toQueryString();
 591
 592 ### Arguments:
 593
 594 1. source - (*object*) The object to generate the query string from.
 595
 596 ### Returns:
 597
 598 * (*string*) The query string.
 599
 600 ### Examples:
 601
 602 #### Using Hash generic:
 603
 604         Hash.toQueryString({apple: "red", lemon: "yellow"}); //returns "apple=red&lemon=yellow"
 605
 606 #### Using Hash instance:
 607
 608         var myHash = new Hash({apple: "red", lemon: "yellow"});
 609         myHash.toQueryString(); //returns "apple=red&lemon=yellow"
 610
 611
 612 Utility Functions {#Utility}
 613 ============================
 614
 615 Function: $H {#H}
 616 -----------------
 617
 618 Shortcut for the new [Hash](/Core/#Hash).
 619
 620 ### See Also:
 621
 622 - [Hash][]
 623
 624
 625 [Hash]: #Hash
 626 [Array:indexOf]: /Native/Array/#Array:indexOf
 627 [Hash:getKeys]: #Hash:getKeys
 628 [Hash:getValues]: #Hash:getValues
 629 [Function:bind]: Native/Function#Function:bind