review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 # lang #
   2
   3 Language Utilities. Easier inheritance, scope handling, type checks.
   4
   5
   6
   7 ## clone(val):*
   8
   9 Clone native types like Object, Array, RegExp, Date and primitives.
  10
  11 This method will not clone values that are referenced within `val`. It will
  12 only copy the value reference to the new value. If the value is not a plain
  13 object but is an object, it will return the value unchanged.
  14
  15 ### Example
  16
  17 ```js
  18 var a = { foo: 'bar' };
  19 var b = clone(a);
  20 console.log(a === b); // false
  21 console.log(a.foo === b.foo); // true
  22
  23 var c = [1, 2, 3];
  24 var d = clone(b);
  25 console.log(c === d); // false
  26 console.log(c); // [1, 2, 3]
  27 ```
  28
  29 See: [`deepClone()`](#deepClone)
  30
  31
  32
  33 ## createObject(parent, [props]):Object
  34
  35 Create Object using prototypal inheritance and setting custom properties.
  36
  37 Mix between [Douglas Crockford Prototypal Inheritance](http://javascript.crockford.com/prototypal.html) and [`object/mixIn`](./object.html#mixIn).
  38
  39 ### Arguments
  40
  41  1. `parent` (Object)  : Parent Object
  42  2. `[props]` (Object) : Object properties
  43
  44 ### Example
  45
  46 ```js
  47 var base = {
  48     trace : function(){
  49         console.log(this.name);
  50     }
  51 };
  52
  53 var myObject = createObject(base, {
  54     name : 'Lorem Ipsum'
  55 });
  56
  57 myObject.trace(); // "Lorem Ipsum"
  58 ```
  59
  60
  61
  62 ## ctorApply(constructor, args):Object
  63
  64 Do `Function.prototype.apply()` on a constructor while maintaining prototype
  65 chain.
  66
  67 ```js
  68 function Person(name, surname) {
  69     this.name = name;
  70     this.surname = surname;
  71 }
  72
  73 Person.prototype.walk = function(){
  74     console.log(this.name +' is walking');
  75 };
  76
  77 var args = ['John', 'Doe'];
  78
  79 // "similar" effect as calling `new Person("John", "Doe")`
  80 var john = ctorApply(Person, args);
  81 john.walk(); // "John is walking"
  82 ```
  83
  84
  85
  86 ## deepClone(val, [instanceClone]):*
  87
  88 Deep clone native types like Object, Array, RegExp, Date and primitives.
  89
  90 The `instanceClone` function will be invoked to clone objects that are not
  91 "plain" objects (as defined by [`isPlainObject`](#isPlainObject)) if it is
  92 provided. If `instanceClone` is not specified, it will not attempt to clone
  93 non-plain objects, and will copy the object reference.
  94
  95 ### Example
  96
  97 ```js
  98 var a = {foo:'bar', obj: {a:1, b:2}};
  99 var b = deepClone(a); // {foo:'bar', obj: {a:1, b:2}}
 100 console.log( a === b ); // false
 101 console.log( a.obj === b.obj ); // false
 102
 103 var c = [1, 2, [3, 4]];
 104 var d = deepClone(c); // [1, 2, [3, 4]]
 105 var e = c.concat(); // [1, 2, [3, 4]]
 106
 107 console.log( c[2] === d[2] ); // false
 108 // concat doesn't do a deep clone, arrays are passed by reference
 109 console.log( e[2] === d[2] ); // true
 110
 111 function Custom() { }
 112 function cloneCustom(x) { return new Custom(); }
 113 var f = { test: new Custom() };
 114 var g = deepClone(f, cloneCustom);
 115 g.test === f.test // false, since new Custom instance will be created
 116 ```
 117
 118 See: [`clone()`](#clone)
 119
 120
 121
 122 ## deepEquals(a, b, [callback]):Boolean
 123
 124 Recursively tests whether two values contains the same keys and values.
 125
 126 `callback` specifies the equality comparison function used to compare
 127 non-object values. It defaults to using the [`is()`](#is) function.
 128
 129 If the values are both an object or array, it will recurse into both values,
 130 checking if their keys/values are equal. It will only check the keys and values
 131 contained by the objects; it will not check the objects' prototypes.  If either
 132 of the values are not objects, they will be checked using the `callback`
 133 function.
 134
 135 Example:
 136
 137 ```js
 138 deepEquals({ a: 1 }, { a: 1 }); // true
 139 deepEquals({ value: { a: 1 } }, { value: { a: 1 } }); // true
 140 deepEquals({ value: { a: 1 } }, { value: { a: 2 } }); // false
 141 deepEquals({ value: { a: 1 } }, { value: { a: 1, b: 2 } }); // false
 142 deepEquals({}, null); // false
 143 deepEquals(null, null); // true
 144 deepEquals(
 145     { a: { b: 1 } },
 146     { a: { b: '1' } },
 147     function(a, b) { return a == b; }); // true
 148 ```
 149
 150 See: [object/equals](object.html#equals), [array/equals](array.html#equals)
 151
 152
 153
 154 ## defaults(val, ...defaults):void
 155
 156 Return first value that isn't `null` or `undefined`.
 157
 158     function doSomethingAwesome(foo, bar) {
 159         // default arguments
 160         foo = defaults(foo, 'lorem');
 161         bar = defaults(bar, 123);
 162         // ...
 163     }
 164
 165
 166
 167 ## GLOBAL:Object
 168
 169 Reference to the global context (`window` inside a browser, `global` on
 170 node.js). Works on ES3 and ES5 strict-mode.
 171
 172
 173
 174 ## inheritPrototype(childCtor, parentCtor):Object
 175
 176 Inherit the prototype methods from one constructor into another.
 177
 178 Similar to [node.js util/inherits](http://nodejs.org/docs/latest/api/util.html#util_util_inherits_constructor_superconstructor).
 179
 180 It returns the the `childCtor.prototype` for convenience.
 181
 182 ```js
 183 function Foo(name){
 184     this.name = name;
 185 }
 186 Foo.prototype = {
 187     getName : function(){
 188         return this.name;
 189     }
 190 };
 191
 192 function Bar(name){
 193     Foo.call(this, name);
 194 }
 195 //should be called before calling constructor
 196 var proto = inheritPrototype(Bar, Foo);
 197
 198 // for convenience we return the new prototype object
 199 console.log(proto === Bar.prototype); // true
 200
 201 var myObj = new Bar('lorem ipsum');
 202 myObj.getName(); // "lorem ipsum"
 203
 204 console.log(myObj instanceof Foo); // true
 205
 206 // you also have access to the "super" constructor
 207 console.log(Bar.super_ === Foo); // true
 208 ```
 209
 210
 211 ## is(x, y):Boolean
 212
 213 Check if both values are identical/egal.
 214
 215 ```js
 216 // wtfjs
 217 NaN === NaN; // false
 218 -0 === +0;   // true
 219
 220 is(NaN, NaN); // true
 221 is(-0, +0);   // false
 222 is('a', 'b'); // false
 223 ```
 224
 225 See: [`isnt()`](#isnt)
 226
 227
 228
 229 ## isnt(x, y):Boolean
 230
 231 Check if both values are not identical/egal.
 232
 233 ```js
 234 // wtfjs
 235 NaN === NaN; // false
 236 -0 === +0;   // true
 237
 238 isnt(NaN, NaN); // false
 239 isnt(-0, +0);   // true
 240 isnt('a', 'b'); // true
 241 ```
 242
 243 See: [`is()`](#is)
 244
 245
 246
 247
 248 ## isArguments(val):Boolean
 249
 250 If value is an "Arguments" object.
 251
 252
 253
 254 ## isArray(val):Boolean
 255
 256 If value is an Array. Uses native ES5 `Array.isArray()` if available.
 257
 258
 259
 260 ## isBoolean(val):Boolean
 261
 262 If value is a Boolean.
 263
 264
 265
 266 ## isDate(val):Boolean
 267
 268 If value is a Date.
 269
 270
 271
 272 ## isEmpty(val):Boolean
 273
 274 Checks if Array/Object/String is empty.
 275
 276 Will return `true` for any object that doesn't contain enumerable properties
 277 and also to any type of value that isn't considered a collection (boolean,
 278 null, undefined, function, etc).
 279
 280 ```js
 281 isEmpty('');         // true
 282 isEmpty('bar');      // false
 283 isEmpty([]);         // true
 284 isEmpty([1, 2]);     // false
 285 isEmpty({});         // true
 286 isEmpty({a:1, b:2}); // false
 287 // null, undefined, booleans, numbers are considered as "empty" values
 288 isEmpty(null);       // true
 289 isEmpty(undefined);  // true
 290 isEmpty(123);        // true
 291 isEmpty(true);       // true
 292 ```
 293
 294
 295 ## isFinite(val):Boolean
 296
 297 Checks if value is Finite.
 298
 299 **IMPORTANT:** This is not the same as native `isFinite`, which will return
 300 `true` for values that can be coerced into finite numbers. See
 301 http://es5.github.com/#x15.1.2.5.
 302
 303 ```js
 304 isFinite(123);      // true
 305 isFinite(Infinity); // false
 306
 307 // this is different than native behavior
 308 isFinite('');   // false
 309 isFinite(true); // false
 310 isFinite([]);   // false
 311 isFinite(null); // false
 312 ```
 313
 314
 315 ## isFunction(val):Boolean
 316
 317 If value is a Function.
 318
 319
 320
 321 ## isKind(val, kind):Boolean
 322
 323 If value is of "kind". (used internally by some of the *isSomething* checks).
 324
 325 Favor the other methods since strings are commonly mistyped and also because
 326 some "kinds" can only be accurately checked by using other methods (e.g.
 327 `Arguments`), some of the other checks are also faster.
 328
 329 ```js
 330 isKind([1,2], 'Array'); // true
 331 isKind(3, 'Array');     // false
 332 isKind(3, 'Number');    // true
 333 ```
 334
 335 See: [`kindOf()`](#kindOf)
 336
 337
 338
 339 ## isInteger(val):Boolean
 340
 341 Check if value is an integer.
 342
 343 ```js
 344 isInteger(123);    // true
 345 isInteger(123.45); // false
 346 isInteger({});     // false
 347 isInteger('foo');  // false
 348 isInteger('123');  // false
 349 ```
 350
 351
 352
 353 ## isNaN(val):Boolean
 354
 355 Check if value is not a number.
 356
 357 It doesn't coerce value into number before doing the check, giving better
 358 results than native `isNaN`. Returns `true` for everything besides numeric
 359 values.
 360
 361 **IMPORTANT:** behavior is very different than the native `isNaN` and way more
 362 useful!!! See: http://es5.github.io/#x15.1.2.4
 363
 364 ```js
 365 isNaN(123);       // false
 366
 367 isNaN(NaN);       // true
 368 isNaN({});        // true
 369 isNaN(undefined); // true
 370 isNaN([4,5]);     // true
 371
 372 // these are all "false" on native isNaN and main reason why this module exists
 373 isNaN('');    // true
 374 isNaN(null);  // true
 375 isNaN(true);  // true
 376 isNaN(false); // true
 377 isNaN("123"); // true
 378 isNaN([]);    // true
 379 isNaN([5]);   // true
 380 ```
 381
 382
 383
 384 ## isNull(val):Boolean
 385
 386 If value is `null`.
 387
 388
 389
 390 ## isNumber(val):Boolean
 391
 392 If value is a Number.
 393
 394
 395
 396 ## isObject(val):Boolean
 397
 398 If value is an Object.
 399
 400
 401
 402 ## isPlainObject(val):Boolean
 403
 404 If the value is an Object created by the Object constructor.
 405
 406
 407
 408 ## isRegExp(val):Boolean
 409
 410 If value is a RegExp.
 411
 412
 413
 414 ## isString(val):Boolean
 415
 416 If value is a String.
 417
 418
 419
 420 ## isUndefined(val):Boolean
 421
 422 If value is `undefined`.
 423
 424
 425
 426 ## kindOf(val):String
 427
 428 Gets kind of value (e.g. "String", "Number", "RegExp", "Null", "Date").
 429 Used internally by `isKind()` and most of the other *isSomething* checks.
 430
 431 ```js
 432 kindOf([1,2]); // "Array"
 433 kindOf('foo'); // "String"
 434 kindOf(3);     // "Number"
 435 ```
 436
 437 See: [`isKind()`](#isKind)
 438
 439
 440 ## toArray(val):Array
 441
 442 Convert array-like object into Array or wrap value into Array.
 443
 444 ```js
 445 toArray({
 446     "0" : "foo",
 447     "1" : "bar",
 448     "length" : 2
 449 });                              // ["foo", "bar"]
 450
 451 function foo(){
 452     return toArray(arguments);
 453 }
 454 foo("lorem", 123);               // ["lorem", 123]
 455
 456 toArray("lorem ipsum");          // ["lorem ipsum"]
 457 toArray(window);                 // [window]
 458 toArray({foo:"bar", lorem:123}); // [{foo:"bar", lorem:123}]
 459 ```
 460
 461 See: object/values()
 462
 463
 464
 465 ## toNumber(val):Number
 466
 467 Convert value into number.
 468
 469 ```js
 470 // numeric values are typecasted as Number
 471 toNumber('123');     // 123
 472 toNumber(-567);      // -567
 473
 474 // falsy values returns zero
 475 toNumber('');        // 0
 476 toNumber(null);      // 0
 477 toNumber(undefined); // 0
 478 toNumber(false);     // 0
 479
 480 // non-numeric values returns NaN
 481 toNumber('asd');     // NaN
 482 toNumber({});        // NaN
 483 toNumber([]);        // NaN
 484
 485 // Date objects return milliseconds since epoch
 486 toNumber(new Date(1985, 6, 23)); // 490935600000
 487 ```
 488
 489
 490
 491 ## toString(val):String
 492
 493 Convert any value to its string representation.
 494
 495 Will return an empty string for `undefined` or `null`, otherwise will convert
 496 the value to its string representation.
 497
 498 ```js
 499 // null and undefined are converted into empty strings
 500 toString(null);      // ""
 501 toString(undefined); // ""
 502
 503 toString(1);       // "1"
 504 toString([1,2,3]); // "1,2,3"
 505 toString(false);   // "false"
 506
 507 // uses `val.toString()` to convert value
 508 toString({toString:funtion(){ return 'foo'; }}); // "foo"
 509 ```
 510
 511
 512
 513 -------------------------------------------------------------------------------
 514
 515 For more usage examples check specs inside `/tests` folder. Unit tests are the
 516 best documentation you can get...