Docs/Core/Core.md

   1 Core {#Core}
   2 ============
   3
   4 Core contains an handful of common sense functions used in [MooTools](http://mootools.net).
   5 It also contains some basic [Hash][] and [Array][] methods.
   6
   7 Function: $chk {#chk}
   8 ---------------------
   9
  10 Checks to see if a value exists or is 0. Useful for allowing 0.
  11
  12 ### Syntax:
  13
  14         $chk(item);
  15
  16 ### Arguments:
  17
  18 1. item - (*mixed*) The item to inspect.
  19
  20 ### Returns:
  21
  22 * (*boolean*) If the object passed in exists or is 0, returns true. Otherwise, returns false.
  23
  24 ### Example:
  25
  26         function myFunction(arg){
  27                 if($chk(arg)) alert('The object exists or is 0.');
  28                 else alert('The object is either null, undefined, false, or ""');
  29         }
  30
  31
  32
  33 Function: $clear {#clear}
  34 -------------------------
  35
  36 Clears a Timeout or an Interval. Useful when working with [Function:delay][] and [Function:periodical][].
  37
  38 ### Syntax:
  39
  40         $clear(timer);
  41
  42 ### Arguments:
  43
  44 1. timer - (*number*) The identifier of the setInterval (periodical) or setTimeout (delay) to clear.
  45
  46 ### Returns:
  47
  48 * (*false*) returns null.
  49
  50 ### Example:
  51
  52         var myTimer = myFunction.delay(5000); //Waits 5 seconds then executes myFunction.
  53         myTimer = $clear(myTimer); //Cancels myFunction.
  54
  55 ### See also:
  56
  57 - [Function:delay][]
  58 - [Function:periodical][]
  59
  60
  61
  62 Function: $defined {#defined}
  63 -----------------------------
  64
  65 Checks to see if a value is defined.
  66
  67 ### Syntax:
  68
  69         $defined(obj);
  70
  71 ### Arguments:
  72
  73 1. obj - (*mixed*) The object to inspect.
  74
  75 ### Returns:
  76
  77 * (*boolean*) If the object passed is not null or undefined, returns true. Otherwise, returns false.
  78
  79 ### Example:
  80
  81         function myFunction(arg){
  82                 if($defined(arg)) alert('The object is defined.');
  83                 else alert('The object is null or undefined.');
  84         }
  85
  86
  87
  88 Function: $arguments {#arguments}
  89 ---------------------------------
  90
  91 Creates a function which returns the passed argument according to the index (i) passed.
  92
  93 ### Syntax:
  94
  95         var argument = $arguments(i);
  96
  97 ### Arguments
  98
  99 1. i - (*number*) The index of the argument to return.
 100
 101 ### Returns
 102
 103 * (*function*) The function that returns a certain argument from the function's arguments.
 104
 105 ### Example:
 106
 107         var secondArgument = $arguments(1);
 108         alert(secondArgument('a','b','c')); //Alerts "b".
 109
 110
 111
 112 Function: $empty {#empty}
 113 -------------------------
 114
 115 An empty function, that's it. Typically used for as a placeholder inside event methods of classes.
 116
 117 ### Syntax:
 118
 119         var emptyFn = $empty;
 120
 121 ### Example:
 122
 123         var myFunc = $empty;
 124
 125 Function: $lambda {#lambda}
 126 -------------------------
 127
 128 Creates an empty function which does nothing but return the value passed.
 129
 130 ### Syntax:
 131
 132         var returnTrue = $lambda(true);
 133
 134 ### Arguments
 135
 136 1. value - (*mixed*) The value for the created function to return.
 137
 138 ### Returns
 139
 140 * (*function*) A function which returns the desired value.
 141
 142 ### Example:
 143
 144         myLink.addEvent('click', $lambda(false)); //Prevents a link Element from being clickable.
 145
 146
 147 Function: $extend {#extend}
 148 ---------------------------
 149
 150 Copies all the properties from the second object passed in to the first object passed in.
 151
 152 ### Syntax:
 153
 154         $extend(original, extended);
 155
 156 ### Arguments:
 157
 158 1. original  - (*object*) The object to be extended.
 159 2. extension - (*object*) The object whose properties will be copied to original.
 160
 161 ### Returns:
 162
 163 * (*object*) The first object passed in, extended.
 164
 165 ### Examples:
 166
 167         var firstObj = {
 168                 'name': 'John',
 169                 'lastName': 'Doe'
 170         };
 171         var secondObj = {
 172                 'age': '20',
 173                 'sex': 'male',
 174                 'lastName': 'Dorian'
 175         };
 176         $extend(firstObj, secondObj);
 177         //firstObj is now: {'name': 'John', 'lastName': 'Dorian', 'age': '20', 'sex': 'male'};
 178
 179
 180
 181 Function: $merge {#merge}
 182 -------------------------
 183
 184 Merges any number of objects recursively without referencing them or their sub-objects.
 185
 186 ### Syntax:
 187
 188         var merged = $merge(obj1, obj2[, obj3[, ...]]);
 189
 190 ### Arguments:
 191
 192 1. (objects) Any number of objects.
 193
 194 ### Returns:
 195
 196 * (*object*) The object that is created as a result of merging all the objects passed in.
 197
 198 ### Examples:
 199
 200         var obj1 = {a: 0, b: 1};
 201         var obj2 = {c: 2, d: 3};
 202         var obj3 = {a: 4, d: 5};
 203         var merged = $merge(obj1, obj2, obj3); //returns {a: 4, b: 1, c: 2, d: 5}, (obj1, obj2, and obj3 are unaltered)
 204
 205         var nestedObj1 = {a: {b: 1, c: 1}};
 206         var nestedObj2 = {a: {b: 2}};
 207         var nested = $merge(nestedObj1, nestedObj2); //returns: {a: {b: 2, c: 1}}
 208
 209 Function: $each {#each}
 210 -----------------------
 211
 212 Used to iterate through iterables that are not regular arrays, such as built in getElementsByTagName calls, arguments of a function, or an object.
 213
 214 ### Syntax:
 215
 216         $each(iterable, fn[, bind]);
 217
 218 ### Arguments:
 219
 220 1. iterable - (*object* or *array*) The object or array to iterate through.
 221 2. fn       - (*function*) The function to test for each element.
 222 3. bind     - (*object*, optional) The object to use as 'this' within the function. For more information see [Function:bind][].
 223
 224 #### Argument: fn
 225
 226 ##### Syntax:
 227
 228         fn(item, index, object)
 229
 230 ##### Arguments:
 231
 232 1. item   - (*mixed*) The current item in the array.
 233 2. index  - (*number*) The current item's index in the array. In the case of an object, it is passed the key of that item rather than the index.
 234 3. object - (*mixed*) The actual array/object.
 235
 236 ### Examples:
 237
 238 #### Array Example:
 239
 240         $each(['Sun','Mon','Tue'], function(day, index){
 241                 alert('name:' + day + ', index: ' + index);
 242         }); //Alerts "name: Sun, index: 0", "name: Mon, index: 1", etc.
 243
 244
 245 #### Object Example:
 246
 247     //Alerts "The first day of the week is Sunday", "The second day of the week is Monday", etc:
 248         $each({first: "Sunday", second: "Monday", third: "Tuesday"}, function(value, key){
 249                 alert("The " + key + " day of the week is " + value);
 250         });
 251
 252
 253 Function: $pick {#pick}
 254 -----------------------
 255
 256 Returns the first defined argument passed in, or null.
 257
 258 ### Syntax:
 259
 260         var picked = $pick(var1[, var2[, var3[, ...]]]);
 261
 262 ### Arguments:
 263
 264 * (*mixed*) Any number of variables.
 265
 266 ### Returns:
 267
 268 * (*mixed*) The first variable that is defined.
 269 * (*false*) If all variables passed in are null or undefined, returns null.
 270
 271 ### Example:
 272
 273         function say(infoMessage, errorMessage){
 274                 alert($pick(errorMessage, infoMessage, 'There was no message supplied.'));
 275         }
 276         say(); //Alerts "There was no message supplied."
 277     say("This is an info message."); //Alerts "This is an info message."
 278     say("This message will be ignored.", "This is the error message."); //Alerts "This is the error message."
 279
 280
 281
 282 Function: $random {#random}
 283 ---------------------------
 284
 285 Returns a random integer between the two passed in values.
 286
 287 ### Syntax:
 288
 289         var random = $random(min, max);
 290
 291 ### Arguments:
 292
 293 1. min - (*number*) The minimum value (inclusive).
 294 2. max - (*number*) The maximum value (inclusive).
 295
 296 ### Returns:
 297
 298 * (*number*) A random number between min and max.
 299
 300 ### Example:
 301
 302         alert($random(5, 20)); //Alerts a random number between 5 and 20.
 303
 304
 305
 306 Function: $splat {#splat}
 307 -------------------------
 308
 309 Converts the argument passed in to an array if it is defined and not already an array.
 310
 311 ### Syntax:
 312
 313         var splatted = $splat(obj);
 314
 315 ### Arguments:
 316
 317 1. obj - (*mixed*) Any type of variable.
 318
 319 ### Returns:
 320
 321 * (*array*) If the variable passed in is an array, returns the array. Otherwise, returns an array with the only element being the variable passed in.
 322
 323 ### Example:
 324
 325         $splat('hello'); //Returns ['hello'].
 326         $splat(['a', 'b', 'c']); //Returns ['a', 'b', 'c'].
 327
 328
 329
 330 Function: $time {#time}
 331 -----------------------
 332
 333 Returns the current time as a timestamp.
 334
 335 ### Syntax:
 336
 337         var time = $time();
 338
 339 ### Returns:
 340
 341 * (*number*) - The current timestamp.
 342
 343
 344
 345 Function: $try {#try}
 346 ---------------------
 347
 348 Tries to execute a number of functions. Returns immediately the return value of the first non-failed function without executing successive functions, or null.
 349
 350 ### Syntax:
 351
 352         $try(fn[, fn, fn, fn, ...]);
 353
 354 ### Arguments:
 355
 356 * fn   - (*function*) The function to execute.
 357
 358 ### Returns:
 359
 360 * (*mixed*) Standard return of the called function.
 361 * (*null*) `null` if all the passed functions fail.
 362
 363 ### Examples:
 364
 365         var result = $try(function(){
 366                 return some.made.up.object;
 367         }, function(){
 368                 return jibberish.that.doesnt.exists;
 369         }, function(){
 370                 return false;
 371         });
 372
 373         //result is false
 374
 375         var failure, success;
 376
 377         $try(function(){
 378                 some.made.up.object = 'something';
 379                 success = true;
 380         }, function(){
 381                 failure = true;
 382         });
 383
 384         if (success) alert('yey!');
 385
 386 Function: $type {#type}
 387 -----------------------
 388
 389 Returns the type of object that matches the element passed in.
 390
 391 ### Syntax:
 392
 393         $type(obj);
 394
 395 ### Arguments:
 396
 397 1. obj - (*object*) The object to inspect.
 398
 399 ### Returns:
 400
 401 * 'element'    - (*string*) If object is a DOM element node.
 402 * 'textnode'   - (*string*) If object is a DOM text node.
 403 * 'whitespace' - (*string*) If object is a DOM whitespace node.
 404 * 'arguments'  - (*string*) If object is an arguments object.
 405 * 'array'      - (*string*) If object is an array.
 406 * 'object'     - (*string*) If object is an object.
 407 * 'string'     - (*string*) If object is a string.
 408 * 'number'     - (*string*) If object is a number.
 409 * 'date'       - (*string*) If object is a date.
 410 * 'boolean'    - (*string*) If object is a boolean.
 411 * 'function'   - (*string*) If object is a function.
 412 * 'regexp'     - (*string*) If object is a regular expression.
 413 * 'class'      - (*string*) If object is a Class (created with new Class, or the extend of another class).
 414 * 'collection' - (*string*) If object is a native htmlelements collection, such as childNodes, getElementsByTagName, etc.
 415 * 'window'     - (*string*) If object is the window object.
 416 * 'document'   - (*string*) If object is the document object.
 417 * false        - (*boolean*) If object is undefined, null, NaN or none of the above.
 418
 419 ### Example:
 420
 421         var myString = 'hello';
 422         $type(myString); //Returns "string".
 423
 424
 425 [Hash]: /Native/Hash
 426 [Array]: /Native/Array
 427 [Function:bind]: /Native/Function/#Function:bind
 428 [Function:delay]: /Native/Function/#Function:delay
 429 [Function:periodical]: /Native/Function/#Function:periodical