Docs/Core/Core.md

   1 # Type: Core {#Core}
   2
   3 Core contains common functions used in [MooTools][].
   4
   5 ## Function: typeOf {#Core:typeOf}
   6
   7 Returns the type of an object.
   8
   9 ### Syntax:
  10
  11         typeOf(obj);
  12
  13 ### Arguments:
  14
  15 1. obj - (*object*) The object to inspect.
  16
  17 ### Returns:
  18
  19 * 'element'    - (*string*) If object is a DOM element node.
  20 * 'elements'   - (*string*) If object is an instance of [Elements][].
  21 * 'textnode'   - (*string*) If object is a DOM text node.
  22 * 'whitespace' - (*string*) If object is a DOM whitespace node.
  23 * 'arguments'  - (*string*) If object is an arguments object.
  24 * 'array'      - (*string*) If object is an array.
  25 * 'object'     - (*string*) If object is an object.
  26 * 'string'     - (*string*) If object is a string.
  27 * 'number'     - (*string*) If object is a number.
  28 * 'date'       - (*string*) If object is a date.
  29 * 'boolean'    - (*string*) If object is a boolean.
  30 * 'function'   - (*string*) If object is a function.
  31 * 'regexp'     - (*string*) If object is a regular expression.
  32 * 'class'      - (*string*) If object is a [Class][] (created with new Class or the extend of another class).
  33 * 'collection' - (*string*) If object is a native HTML elements collection, such as childNodes or getElementsByTagName.
  34 * 'window'     - (*string*) If object is the window object.
  35 * 'document'   - (*string*) If object is the document object.
  36 * 'domevent'   - (*string*) If object is an event.
  37 * 'null'       - (*string*) If object is undefined, null, NaN or none of the above.
  38
  39 ### Example:
  40
  41         var myString = 'hello';
  42         typeOf(myString); // returns "string"
  43
  44 ### Note:
  45
  46 This method is equivalent to *$type* from MooTools 1.2, with the exception that undefined and null values now return 'null' as a string, instead of false.
  47
  48 ## Function: instanceOf {#Core:instanceOf}
  49
  50 Checks if an object is an instance of a particular type.
  51
  52 ### Syntax:
  53
  54         instanceOf(item, object)
  55
  56 ### Arguments:
  57
  58 1. item - (*mixed*) The item to check.
  59 2. object - (*mixed*) The type to compare it with.
  60
  61 ### Returns:
  62
  63 * (*boolean*) Whether or not the item is an instance of the object.
  64
  65 ### Examples:
  66
  67         var foo = [];
  68         instanceOf(foo, Array) // returns true
  69         instanceOf(foo, String) // returns false
  70
  71         var myClass = new Class();
  72         var bar = new myClass();
  73         instanceOf(bar, myClass) // returns true
  74
  75 ### Type {#Type}
  76
  77 MooTools extends native types, like string, array or number to make them even more useful.
  78
  79 The types MooTools uses are:
  80
  81 - String
  82 - Array
  83 - Number
  84 - Function
  85 - RegExp
  86 - Date
  87 - Boolean
  88
  89 Custom MooTools types are:
  90
  91 - Element
  92 - Elements
  93 - Event
  94
  95 ## Type method: implement {#Type:implement}
  96
  97 This method implements a new method to the type's prototype.
  98
  99 ### Syntax:
 100
 101         myType.implement(name, method);
 102
 103 **or**
 104
 105         myType.implement(methods);
 106
 107 ### Arguments:
 108
 109 1. name - (*string*) The method name.
 110 2. method - (*function*) The method function.
 111
 112 **or**
 113
 114 1. methods - (*object*) An object with key-value pairs. The key is the method name, the value is the method function.
 115
 116 ### Returns:
 117
 118 * (*object*) The type.
 119
 120 ### Examples:
 121
 122         Array.implement('limitTop', function(top){
 123                 for (var i = 0, l = this.length; i < l; i++){
 124                         if (this[i] > top) this[i] = top;
 125                 }
 126                 return this;
 127         });
 128
 129         [1, 2, 3, 4, 5, 6].limitTop(4); // returns [1, 2, 3, 4, 4, 4]
 130
 131 It is also possible to pass an object of methods:
 132
 133         String.implement({
 134                 repeat: function(times){
 135                         var string = '';
 136                         while (times--) string += this;
 137                         return string;
 138                 },
 139                 ftw: function(){
 140                         return this + ' FTW!';
 141                 }
 142         });
 143
 144         'moo! '.repeat(3); // returns "moo! moo! moo! "
 145         'MooTools'.ftw(); // returns "MooTools FTW!"
 146         ('MooTools'.ftw() + ' ').repeat(2); // returns "MooTools FTW! MooTools FTW! "
 147
 148 ## Type method: extend {#Type:extend}
 149
 150 Adds one or more functions to the type. These are static functions that accept for example other types to parse them into the type, or other utility functions that belong to the certain type.
 151
 152 ### Syntax:
 153
 154         myType.extend(name, method);
 155
 156 **or**
 157
 158         myType.extend(methods);
 159
 160 ### Arguments:
 161
 162 1. name - (*string*) The method name.
 163 2. method - (*function*) The method function.
 164
 165 **or**
 166
 167 1. methods - (*object*) An object with key-value pairs. The key is the method name, the value is the method function.
 168
 169 ### Returns:
 170
 171 * (*object*) The type.
 172
 173 ### Examples:
 174
 175         RegExp.extend('from', function(regexp, flags){
 176                 return new RegExp(regexp, flags);
 177         });
 178
 179         Number.extend('parseCurrency', function(currency){
 180                 // takes a string and transforms it into a number to
 181                 // do certain calculations
 182         });
 183
 184 ## Generics {#Type:generics}
 185
 186 Most methods of types can be used as generic functions. These are the already existing JavaScript methods, methods MooTools adds, or methods you [implemented][implement] yourself.
 187
 188 ### Example:
 189
 190         var everyArgBiggerThanTwo = function(){
 191                 // Instead of this
 192                 return Array.prototype.every.call(arguments, someFunction);
 193                 // you can use
 194                 return Array.every(arguments, someFunction);
 195         };
 196
 197 This is useful if methods of a certain type should be used as function of another type.
 198  As the example above, it is used for the Arguments type, which is not a real array, so `arguments.every(fn)` would not work. However, `Array.every(arguments, fn)` does work in MooTools.
 199
 200 ### Syntax:
 201
 202         Type.methodName(thisArg[, arg1, arg2, ...]);
 203
 204 ### Arguments:
 205
 206 1. thisArg - (*mixed*) This is the subject, which is usually `thisArg.method([arg1, arg2, ...]);`.
 207 2. arg1, arg2, ... - (*mixed*) Additional arguments which will be passed as method arguments.
 208
 209 ### Returns:
 210
 211 - (*mixed*) Anything the method usually returns.
 212
 213 [Class]: /core/Class/Class
 214 [Elements]: /core/Element/Element
 215 [implement]: core/Core/Core#Type:implement
 216 [MooTools]: http://mootools.net
 217
 218 ---
 219
 220 Deprecated Functions {#Deprecated-Functions}
 221 ============================================
 222
 223
 224 Function: $chk {#Deprecated-Functions:chk}
 225 ---------------------
 226
 227 This method has been deprecated and will have no equivalent in MooTools 1.3.
 228
 229 If you really need this function you can implement it like so:
 230
 231 ### Example:
 232
 233         var $chk = function(obj){
 234                 return !!(obj || obj === 0);
 235         };
 236
 237
 238
 239 Function: $clear {#Deprecated-Functions:clear}
 240 -------------------------
 241
 242 This method has been deprecated. Please use *clearInterval* or *clearTimeout* instead.
 243
 244 ### See Also:
 245
 246 - [MDN clearTimeout][], [MDN clearInterval][]
 247
 248
 249 Function: $defined {#Deprecated-Functions:defined}
 250 -----------------------------
 251
 252 This method has been deprecated.
 253
 254 If you really need this function you can implement it like so:
 255
 256 ### Example:
 257
 258         var $defined = function(obj){
 259                 return (obj != undefined);
 260         };
 261
 262         // or just use it like this:
 263         if(obj != undefined){
 264                 // do something
 265         }
 266
 267
 268 Function: $arguments {#Deprecated-Functions:arguments}
 269 ---------------------------------
 270
 271 This method has been deprecated and will have no equivalent in MooTools 1.3.
 272
 273 If you really need this function you can implement it like so:
 274
 275 ### Example:
 276
 277         var $arguments = function(i){
 278                 return function(){
 279                         return arguments[i];
 280                 };
 281         };
 282
 283
 284
 285 Function: $empty {#Deprecated-Functions:empty}
 286 -------------------------
 287
 288 This method has been deprecated. Use [Function.convert](/core/Types/Function#Function:Function:convert) instead.
 289
 290 ### Example:
 291
 292         var myFunc = Function.convert();
 293         // or better:
 294         var myFunc = function(){};
 295
 296
 297
 298 Function: $lambda {#Deprecated-Functions:lambda}
 299 ---------------------------
 300
 301 This method has been deprecated. Use [Function.convert](/core/Types/Function#Function:Function:convert) instead.
 302
 303 ### Example:
 304
 305         myLink.addEvent('click', Function.convert(false)); // prevents a link Element from being clickable
 306
 307
 308
 309 Function: $extend {#Deprecated-Functions:extend}
 310 ---------------------------
 311
 312 This method has been deprecated. Please use [Object.append](/core/Types/Object#Object:Object-append) instead.
 313
 314
 315
 316 Function: $merge {#Deprecated-Functions:merge}
 317 -------------------------
 318
 319 This method has been deprecated. Please use [Object.merge](/core/Types/Object#Object:Object-merge) instead.
 320
 321
 322
 323 Function: $each {#Deprecated-Functions:each}
 324 -----------------------
 325
 326 This method has been deprecated. Please use [Array.each](/core/Types/Array#Array:Array-each) or [Object.each](/core/Types/Object#Object:Object-each) instead.
 327
 328
 329
 330 Function: $pick {#Deprecated-Functions:pick}
 331 -----------------------
 332
 333 This method has been deprecated. Please use [Array.pick](/core/Types/Array#Array:pick) instead.
 334
 335
 336
 337 Function: $random {#Deprecated-Functions:random}
 338 ---------------------------
 339
 340 This method has been deprecated. Please use [Number.random](/core/Types/Number#Number:Number-random) instead.
 341
 342
 343
 344 Function: $splat {#Deprecated-Functions:splat}
 345 -------------------------
 346
 347 This method has been deprecated. Please use [Array.convert](/core/Types/Array#Array:Array:convert) instead.
 348 However `$splat` does *not* transform Array-like objects such as NodeList or FileList in arrays, `Array.convert` does.
 349
 350
 351 Function: $time {#Deprecated-Functions:time}
 352 -----------------------
 353
 354 This method has been deprecated. Please use *Date.now()* instead.
 355
 356 ### Syntax:
 357
 358         var time = Date.now();
 359
 360 ### Returns:
 361
 362 * (*number*) - The current timestamp.
 363
 364
 365
 366 Function: $try {#Deprecated-Functions:try}
 367 ---------------------
 368
 369 This method has been deprecated. Please use [Function.attempt](/core/Types/Function#Function:Function-attempt) instead.
 370
 371
 372
 373 Function: $type {#Deprecated-Functions:type}
 374 -----------------------
 375
 376 This method has been deprecated. Please use [typeOf](#Core:typeOf) instead.
 377
 378
 379
 380 [Array]: /core/Types/Array
 381 [Function:bind]: /core/Types/Function/#bind
 382 [Function:delay]: /core/Types/Function/#delay
 383 [Function:periodical]: /core/Types/Function/#periodical
 384 [MDN clearInterval]: https://developer.mozilla.org/en/DOM/window.clearInterval
 385 [MDN clearTimeout]: https://developer.mozilla.org/en/DOM/window.clearTimeout