git.r.bdr.sh - rbdr/dotfiles/blob

   1 # es5-ext
   2 ## ECMAScript 5 extensions
   3 ### (with respect to ECMAScript 6 standard)
   4
   5 Shims for upcoming ES6 standard and other goodies implemented strictly with ECMAScript conventions in mind.
   6
   7 It's designed to be used in compliant ECMAScript 5 or ECMAScript 6 environments. Older environments are not supported, although most of the features should work with correct ECMAScript 5 shim on board.
   8
   9 When used in ECMAScript 6 environment, native implementation (if valid) takes precedence over shims.
  10
  11 ### Installation
  12
  13         $ npm install es5-ext
  14
  15 To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: [Browserify](http://browserify.org/), [Webmake](https://github.com/medikoo/modules-webmake) or [Webpack](http://webpack.github.io/)
  16
  17 ### Usage
  18
  19 #### ECMAScript 6 features
  20
  21 You can force ES6 features to be implemented in your environment, e.g. following will assign `from` function to `Array` (only if it's not implemented already).
  22
  23 ```javascript
  24 require('es5-ext/array/from/implement');
  25 Array.from('foo'); // ['f', 'o', 'o']
  26 ```
  27
  28 You can also access shims directly, without fixing native objects. Following will return native `Array.from` if it's available and fallback to shim if it's not.
  29
  30 ```javascript
  31 var aFrom = require('es5-ext/array/from');
  32 aFrom('foo'); // ['f', 'o', 'o']
  33 ```
  34
  35 If you want to use shim unconditionally (even if native implementation exists) do:
  36
  37 ```javascript
  38 var aFrom = require('es5-ext/array/from/shim');
  39 aFrom('foo'); // ['f', 'o', 'o']
  40 ```
  41
  42 ##### List of ES6 shims
  43
  44 It's about properties introduced with ES6 and those that have been updated in new spec.
  45
  46 - `Array.from` -> `require('es5-ext/array/from')`
  47 - `Array.of` -> `require('es5-ext/array/of')`
  48 - `Array.prototype.concat` -> `require('es5-ext/array/#/concat')`
  49 - `Array.prototype.copyWithin` -> `require('es5-ext/array/#/copy-within')`
  50 - `Array.prototype.entries` -> `require('es5-ext/array/#/entries')`
  51 - `Array.prototype.fill` -> `require('es5-ext/array/#/fill')`
  52 - `Array.prototype.filter` -> `require('es5-ext/array/#/filter')`
  53 - `Array.prototype.find` -> `require('es5-ext/array/#/find')`
  54 - `Array.prototype.findIndex` -> `require('es5-ext/array/#/find-index')`
  55 - `Array.prototype.keys` -> `require('es5-ext/array/#/keys')`
  56 - `Array.prototype.map` -> `require('es5-ext/array/#/map')`
  57 - `Array.prototype.slice` -> `require('es5-ext/array/#/slice')`
  58 - `Array.prototype.splice` -> `require('es5-ext/array/#/splice')`
  59 - `Array.prototype.values` -> `require('es5-ext/array/#/values')`
  60 - `Array.prototype[@@iterator]` -> `require('es5-ext/array/#/@@iterator')`
  61 - `Math.acosh` -> `require('es5-ext/math/acosh')`
  62 - `Math.asinh` -> `require('es5-ext/math/asinh')`
  63 - `Math.atanh` -> `require('es5-ext/math/atanh')`
  64 - `Math.cbrt` -> `require('es5-ext/math/cbrt')`
  65 - `Math.clz32` -> `require('es5-ext/math/clz32')`
  66 - `Math.cosh` -> `require('es5-ext/math/cosh')`
  67 - `Math.exmp1` -> `require('es5-ext/math/expm1')`
  68 - `Math.fround` -> `require('es5-ext/math/fround')`
  69 - `Math.hypot` -> `require('es5-ext/math/hypot')`
  70 - `Math.imul` -> `require('es5-ext/math/imul')`
  71 - `Math.log1p` -> `require('es5-ext/math/log1p')`
  72 - `Math.log2` -> `require('es5-ext/math/log2')`
  73 - `Math.log10` -> `require('es5-ext/math/log10')`
  74 - `Math.sign` -> `require('es5-ext/math/sign')`
  75 - `Math.signh` -> `require('es5-ext/math/signh')`
  76 - `Math.tanh` -> `require('es5-ext/math/tanh')`
  77 - `Math.trunc` -> `require('es5-ext/math/trunc')`
  78 - `Number.EPSILON` -> `require('es5-ext/number/epsilon')`
  79 - `Number.MAX_SAFE_INTEGER` -> `require('es5-ext/number/max-safe-integer')`
  80 - `Number.MIN_SAFE_INTEGER` -> `require('es5-ext/number/min-safe-integer')`
  81 - `Number.isFinite` -> `require('es5-ext/number/is-finite')`
  82 - `Number.isInteger` -> `require('es5-ext/number/is-integer')`
  83 - `Number.isNaN` -> `require('es5-ext/number/is-nan')`
  84 - `Number.isSafeInteger` -> `require('es5-ext/number/is-safe-integer')`
  85 - `Object.assign` -> `require('es5-ext/object/assign')`
  86 - `Object.keys` -> `require('es5-ext/object/keys')`
  87 - `Object.setPrototypeOf` -> `require('es5-ext/object/set-prototype-of')`
  88 - `RegExp.prototype.match` -> `require('es5-ext/reg-exp/#/match')`
  89 - `RegExp.prototype.replace` -> `require('es5-ext/reg-exp/#/replace')`
  90 - `RegExp.prototype.search` -> `require('es5-ext/reg-exp/#/search')`
  91 - `RegExp.prototype.split` -> `require('es5-ext/reg-exp/#/split')`
  92 - `RegExp.prototype.sticky` -> Implement with `require('es5-ext/reg-exp/#/sticky/implement')`, use as function with `require('es5-ext/reg-exp/#/is-sticky')`
  93 - `RegExp.prototype.unicode` -> Implement with `require('es5-ext/reg-exp/#/unicode/implement')`, use as function with `require('es5-ext/reg-exp/#/is-unicode')`
  94 - `String.fromCodePoint` -> `require('es5-ext/string/from-code-point')`
  95 - `String.raw` -> `require('es5-ext/string/raw')`
  96 - `String.prototype.codePointAt` -> `require('es5-ext/string/#/code-point-at')`
  97 - `String.prototype.contains` -> `require('es5-ext/string/#/contains')`
  98 - `String.prototype.endsWith` -> `require('es5-ext/string/#/ends-with')`
  99 - `String.prototype.normalize` -> `require('es5-ext/string/#/normalize')`
 100 - `String.prototype.repeat` -> `require('es5-ext/string/#/repeat')`
 101 - `String.prototype.startsWith` -> `require('es5-ext/string/#/starts-with')`
 102 - `String.prototype[@@iterator]` -> `require('es5-ext/string/#/@@iterator')`
 103
 104 #### Non ECMAScript standard features
 105
 106 __es5-ext__ provides also other utils, and implements them as if they were proposed for a standard. It mostly offers methods (not functions) which can directly be assigned to native prototypes:
 107
 108 ```javascript
 109 Object.defineProperty(Function.prototype, 'partial', { value: require('es5-ext/function/#/partial'),
 110   configurable: true, enumerable: false, writable: true });
 111 Object.defineProperty(Array.prototype, 'flatten', { value: require('es5-ext/array/#/flatten'),
 112   configurable: true, enumerable: false, writable: true });
 113 Object.defineProperty(String.prototype, 'capitalize', { value: require('es5-ext/string/#/capitalize'),
 114   configurable: true, enumerable: false, writable: true });
 115 ```
 116
 117 See [es5-extend](https://github.com/wookieb/es5-extend#es5-extend), a great utility that automatically will extend natives for you.
 118
 119 __Important:__ Remember to __not__ extend natives in scope of generic reusable packages (e.g. ones you intend to publish to npm). Extending natives is fine __only__ if you're the _owner_ of the global scope, so e.g. in final project you lead development of.
 120
 121 When you're in situation when native extensions are not good idea, then you should use methods indirectly:
 122
 123
 124 ```javascript
 125 var flatten = require('es5-ext/array/#/flatten');
 126
 127 flatten.call([1, [2, [3, 4]]]); // [1, 2, 3, 4]
 128 ```
 129
 130 for better convenience you can turn methods into functions:
 131
 132
 133 ```javascript
 134 var call = Function.prototype.call
 135 var flatten = call.bind(require('es5-ext/array/#/flatten'));
 136
 137 flatten([1, [2, [3, 4]]]); // [1, 2, 3, 4]
 138 ```
 139
 140 You can configure custom toolkit (like [underscorejs](http://underscorejs.org/)), and use it throughout your application
 141
 142 ```javascript
 143 var util = {};
 144 util.partial = call.bind(require('es5-ext/function/#/partial'));
 145 util.flatten = call.bind(require('es5-ext/array/#/flatten'));
 146 util.startsWith = call.bind(require('es5-ext/string/#/starts-with'));
 147
 148 util.flatten([1, [2, [3, 4]]]); // [1, 2, 3, 4]
 149 ```
 150
 151 As with native ones most methods are generic and can be run on any type of object.
 152
 153 ## API
 154
 155 ### Global extensions
 156
 157 #### global _(es5-ext/global)_
 158
 159 Object that represents global scope
 160
 161 ### Array Constructor extensions
 162
 163 #### from(arrayLike[, mapFn[, thisArg]]) _(es5-ext/array/from)_
 164
 165 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.from).
 166 Returns array representation of _iterable_ or _arrayLike_. If _arrayLike_ is an instance of array, its copy is returned.
 167
 168 #### generate([length[, …fill]]) _(es5-ext/array/generate)_
 169
 170 Generate an array of pre-given _length_ built of repeated arguments.
 171
 172 #### isPlainArray(x) _(es5-ext/array/is-plain-array)_
 173
 174 Returns true if object is plain array (not instance of one of the Array's extensions).
 175
 176 #### of([…items]) _(es5-ext/array/of)_
 177
 178 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.of).
 179 Create an array from given arguments.
 180
 181 #### toArray(obj) _(es5-ext/array/to-array)_
 182
 183 Returns array representation of `obj`. If `obj` is already an array, `obj` is returned back.
 184
 185 #### validArray(obj) _(es5-ext/array/valid-array)_
 186
 187 Returns `obj` if it's an array, otherwise throws `TypeError`
 188
 189 ### Array Prototype extensions
 190
 191 #### arr.binarySearch(compareFn) _(es5-ext/array/#/binary-search)_
 192
 193 In __sorted__ list search for index of item for which _compareFn_ returns value closest to _0_.
 194 It's variant of binary search algorithm
 195
 196 #### arr.clear() _(es5-ext/array/#/clear)_
 197
 198 Clears the array
 199
 200 #### arr.compact() _(es5-ext/array/#/compact)_
 201
 202 Returns a copy of the context with all non-values (`null` or `undefined`) removed.
 203
 204 #### arr.concat() _(es5-ext/array/#/concat)_
 205
 206 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype.concat).
 207 ES6's version of `concat`. Supports `isConcatSpreadable` symbol, and returns array of same type as the context.
 208
 209 #### arr.contains(searchElement[, position]) _(es5-ext/array/#/contains)_
 210
 211 Whether list contains the given value.
 212
 213 #### arr.copyWithin(target, start[, end]) _(es5-ext/array/#/copy-within)_
 214
 215 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.copywithin).
 216
 217 #### arr.diff(other) _(es5-ext/array/#/diff)_
 218
 219 Returns the array of elements that are present in context list but not present in other list.
 220
 221 #### arr.eIndexOf(searchElement[, fromIndex]) _(es5-ext/array/#/e-index-of)_
 222
 223 _egal_ version of `indexOf` method. [_SameValueZero_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) logic is used for comparision
 224
 225 #### arr.eLastIndexOf(searchElement[, fromIndex]) _(es5-ext/array/#/e-last-index-of)_
 226
 227 _egal_ version of `lastIndexOf` method. [_SameValueZero_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) logic is used for comparision
 228
 229 #### arr.entries() _(es5-ext/array/#/entries)_
 230
 231 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype.entries).
 232 Returns iterator object, which traverses the array. Each value is represented with an array, where first value is an index and second is corresponding to index value.
 233
 234 #### arr.exclusion([…lists]]) _(es5-ext/array/#/exclusion)_
 235
 236 Returns the array of elements that are found only in one of the lists (either context list or list provided in arguments).
 237
 238 #### arr.fill(value[, start, end]) _(es5-ext/array/#/fill)_
 239
 240 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.fill).
 241
 242 #### arr.filter(callback[, thisArg]) _(es5-ext/array/#/filter)_
 243
 244 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.filter).
 245 ES6's version of `filter`, returns array of same type as the context.
 246
 247 #### arr.find(predicate[, thisArg]) _(es5-ext/array/#/find)_
 248
 249 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.find).
 250 Return first element for which given function returns true
 251
 252 #### arr.findIndex(predicate[, thisArg]) _(es5-ext/array/#/find-index)_
 253
 254 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.findindex).
 255 Return first index for which given function returns true
 256
 257 #### arr.first() _(es5-ext/array/#/first)_
 258
 259 Returns value for first defined index
 260
 261 #### arr.firstIndex() _(es5-ext/array/#/first-index)_
 262
 263 Returns first declared index of the array
 264
 265 #### arr.flatten() _(es5-ext/array/#/flatten)_
 266
 267 Returns flattened version of the array
 268
 269 #### arr.forEachRight(cb[, thisArg]) _(es5-ext/array/#/for-each-right)_
 270
 271 `forEach` starting from last element
 272
 273 #### arr.group(cb[, thisArg]) _(es5-ext/array/#/group)_
 274
 275 Group list elements by value returned by _cb_ function
 276
 277 #### arr.indexesOf(searchElement[, fromIndex]) _(es5-ext/array/#/indexes-of)_
 278
 279 Returns array of all indexes of given value
 280
 281 #### arr.intersection([…lists]) _(es5-ext/array/#/intersection)_
 282
 283 Computes the array of values that are the intersection of all lists (context list and lists given in arguments)
 284
 285 #### arr.isCopy(other) _(es5-ext/array/#/is-copy)_
 286
 287 Returns true if both context and _other_ lists have same content
 288
 289 #### arr.isUniq() _(es5-ext/array/#/is-uniq)_
 290
 291 Returns true if all values in array are unique
 292
 293 #### arr.keys() _(es5-ext/array/#/keys)_
 294
 295 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype.keys).
 296 Returns iterator object, which traverses all array indexes.
 297
 298 #### arr.last() _(es5-ext/array/#/last)_
 299
 300 Returns value of last defined index
 301
 302 #### arr.lastIndex() _(es5-ext/array/#/last)_
 303
 304 Returns last defined index of the array
 305
 306 #### arr.map(callback[, thisArg]) _(es5-ext/array/#/map)_
 307
 308 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.map).
 309 ES6's version of `map`, returns array of same type as the context.
 310
 311 #### arr.remove(value[, …valuen]) _(es5-ext/array/#/remove)_
 312
 313 Remove values from the array
 314
 315 #### arr.separate(sep) _(es5-ext/array/#/separate)_
 316
 317 Returns array with items separated with `sep` value
 318
 319 #### arr.slice(callback[, thisArg]) _(es5-ext/array/#/slice)_
 320
 321 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.slice).
 322 ES6's version of `slice`, returns array of same type as the context.
 323
 324 #### arr.someRight(cb[, thisArg]) _(es5-ext/array/#/someRight)_
 325
 326 `some` starting from last element
 327
 328 #### arr.splice(callback[, thisArg]) _(es5-ext/array/#/splice)_
 329
 330 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.splice).
 331 ES6's version of `splice`, returns array of same type as the context.
 332
 333 #### arr.uniq() _(es5-ext/array/#/uniq)_
 334
 335 Returns duplicate-free version of the array
 336
 337 #### arr.values() _(es5-ext/array/#/values)_
 338
 339 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype.values).
 340 Returns iterator object which traverses all array values.
 341
 342 #### arr[@@iterator] _(es5-ext/array/#/@@iterator)_
 343
 344 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype-@@iterator).
 345 Returns iterator object which traverses all array values.
 346
 347 ### Boolean Constructor extensions
 348
 349 #### isBoolean(x) _(es5-ext/boolean/is-boolean)_
 350
 351 Whether value is boolean
 352
 353 ### Date Constructor extensions
 354
 355 #### isDate(x) _(es5-ext/date/is-date)_
 356
 357 Whether value is date instance
 358
 359 #### validDate(x) _(es5-ext/date/valid-date)_
 360
 361 If given object is not date throw TypeError in other case return it.
 362
 363 ### Date Prototype extensions
 364
 365 #### date.copy(date) _(es5-ext/date/#/copy)_
 366
 367 Returns a copy of the date object
 368
 369 #### date.daysInMonth() _(es5-ext/date/#/days-in-month)_
 370
 371 Returns number of days of date's month
 372
 373 #### date.floorDay() _(es5-ext/date/#/floor-day)_
 374
 375 Sets the date time to 00:00:00.000
 376
 377 #### date.floorMonth() _(es5-ext/date/#/floor-month)_
 378
 379 Sets date day to 1 and date time to 00:00:00.000
 380
 381 #### date.floorYear() _(es5-ext/date/#/floor-year)_
 382
 383 Sets date month to 0, day to 1 and date time to 00:00:00.000
 384
 385 #### date.format(pattern) _(es5-ext/date/#/format)_
 386
 387 Formats date up to given string. Supported patterns:
 388
 389 * `%Y` - Year with century, 1999, 2003
 390 * `%y` - Year without century, 99, 03
 391 * `%m` - Month, 01..12
 392 * `%d` - Day of the month 01..31
 393 * `%H` - Hour (24-hour clock), 00..23
 394 * `%M` - Minute, 00..59
 395 * `%S` - Second, 00..59
 396 * `%L` - Milliseconds, 000..999
 397
 398 ### Error Constructor extensions
 399
 400 #### custom(message/*, code, ext*/) _(es5-ext/error/custom)_
 401
 402 Creates custom error object, optinally extended with `code` and other extension properties (provided with `ext` object)
 403
 404 #### isError(x) _(es5-ext/error/is-error)_
 405
 406 Whether value is an error (instance of `Error`).
 407
 408 #### validError(x) _(es5-ext/error/valid-error)_
 409
 410 If given object is not error throw TypeError in other case return it.
 411
 412 ### Error Prototype extensions
 413
 414 #### err.throw() _(es5-ext/error/#/throw)_
 415
 416 Throws error
 417
 418 ### Function Constructor extensions
 419
 420 Some of the functions were inspired by [Functional JavaScript](http://osteele.com/sources/javascript/functional/) project by Olivier Steele
 421
 422 #### constant(x) _(es5-ext/function/constant)_
 423
 424 Returns a constant function that returns pregiven argument
 425
 426 _k(x)(y)  =def  x_
 427
 428 #### identity(x) _(es5-ext/function/identity)_
 429
 430 Identity function. Returns first argument
 431
 432 _i(x)  =def  x_
 433
 434 #### invoke(name[, …args]) _(es5-ext/function/invoke)_
 435
 436 Returns a function that takes an object as an argument, and applies object's
 437 _name_ method to arguments.
 438 _name_ can be name of the method or method itself.
 439
 440 _invoke(name, …args)(object, …args2)  =def  object\[name\]\(…args, …args2\)_
 441
 442 #### isArguments(x) _(es5-ext/function/is-arguments)_
 443
 444 Whether value is arguments object
 445
 446 #### isFunction(arg) _(es5-ext/function/is-function)_
 447
 448 Wether value is instance of function
 449
 450 #### noop() _(es5-ext/function/noop)_
 451
 452 No operation function
 453
 454 #### pluck(name) _(es5-ext/function/pluck)_
 455
 456 Returns a function that takes an object, and returns the value of its _name_
 457 property
 458
 459 _pluck(name)(obj)  =def  obj[name]_
 460
 461 #### validFunction(arg) _(es5-ext/function/valid-function)_
 462
 463 If given object is not function throw TypeError in other case return it.
 464
 465 ### Function Prototype extensions
 466
 467 Some of the methods were inspired by [Functional JavaScript](http://osteele.com/sources/javascript/functional/) project by Olivier Steele
 468
 469 #### fn.compose([…fns]) _(es5-ext/function/#/compose)_
 470
 471 Applies the functions in reverse argument-list order.
 472
 473 _f1.compose(f2, f3, f4)(…args)  =def  f1(f2(f3(f4(…arg))))_
 474
 475 #### fn.copy() _(es5-ext/function/#/copy)_
 476
 477 Produces copy of given function
 478
 479 #### fn.curry([n]) _(es5-ext/function/#/curry)_
 480
 481 Invoking the function returned by this function only _n_ arguments are passed to the underlying function. If the underlying function is not saturated, the result is a function that passes all its arguments to the underlying function.
 482 If _n_ is not provided then it defaults to context function length
 483
 484 _f.curry(4)(arg1, arg2)(arg3)(arg4)  =def  f(arg1, args2, arg3, arg4)_
 485
 486 #### fn.lock([…args]) _(es5-ext/function/#/lock)_
 487
 488 Returns a function that applies the underlying function to _args_, and ignores its own arguments.
 489
 490 _f.lock(…args)(…args2)  =def  f(…args)_
 491
 492 _Named after it's counterpart in Google Closure_
 493
 494 #### fn.not() _(es5-ext/function/#/not)_
 495
 496 Returns a function that returns boolean negation of value returned by underlying function.
 497
 498 _f.not()(…args)  =def !f(…args)_
 499
 500 #### fn.partial([…args]) _(es5-ext/function/#/partial)_
 501
 502 Returns a function that when called will behave like context function called with initially passed arguments. If more arguments are suplilied, they are appended to initial args.
 503
 504 _f.partial(…args1)(…args2)  =def  f(…args1, …args2)_
 505
 506 #### fn.spread() _(es5-ext/function/#/spread)_
 507
 508 Returns a function that applies underlying function with first list argument
 509
 510 _f.match()(args)  =def  f.apply(null, args)_
 511
 512 #### fn.toStringTokens() _(es5-ext/function/#/to-string-tokens)_
 513
 514 Serializes function into two (arguments and body) string tokens. Result is plain object with `args` and `body` properties.
 515
 516 ### Math extensions
 517
 518 #### acosh(x) _(es5-ext/math/acosh)_
 519
 520 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.acosh).
 521
 522 #### asinh(x) _(es5-ext/math/asinh)_
 523
 524 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.asinh).
 525
 526 #### atanh(x) _(es5-ext/math/atanh)_
 527
 528 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.atanh).
 529
 530 #### cbrt(x) _(es5-ext/math/cbrt)_
 531
 532 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.cbrt).
 533
 534 #### clz32(x) _(es5-ext/math/clz32)_
 535
 536 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.clz32).
 537
 538 #### cosh(x) _(es5-ext/math/cosh)_
 539
 540 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.cosh).
 541
 542 #### expm1(x) _(es5-ext/math/expm1)_
 543
 544 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.expm1).
 545
 546 #### fround(x) _(es5-ext/math/fround)_
 547
 548 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.fround).
 549
 550 #### hypot([…values]) _(es5-ext/math/hypot)_
 551
 552 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.hypot).
 553
 554 #### imul(x, y) _(es5-ext/math/imul)_
 555
 556 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.imul).
 557
 558 #### log1p(x) _(es5-ext/math/log1p)_
 559
 560 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.log1p).
 561
 562 #### log2(x) _(es5-ext/math/log2)_
 563
 564 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.log2).
 565
 566 #### log10(x) _(es5-ext/math/log10)_
 567
 568 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.log10).
 569
 570 #### sign(x) _(es5-ext/math/sign)_
 571
 572 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.sign).
 573
 574 #### sinh(x) _(es5-ext/math/sinh)_
 575
 576 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.sinh).
 577
 578 #### tanh(x) _(es5-ext/math/tanh)_
 579
 580 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.tanh).
 581
 582 #### trunc(x) _(es5-ext/math/trunc)_
 583
 584 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-math.trunc).
 585
 586 ### Number Constructor extensions
 587
 588 #### EPSILON _(es5-ext/number/epsilon)_
 589
 590 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.epsilon).
 591
 592 The difference between 1 and the smallest value greater than 1 that is representable as a Number value, which is approximately 2.2204460492503130808472633361816 x 10-16.
 593
 594 #### isFinite(x) _(es5-ext/number/is-finite)_
 595
 596 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.isfinite).
 597 Whether value is finite. Differs from global isNaN that it doesn't do type coercion.
 598
 599 #### isInteger(x) _(es5-ext/number/is-integer)_
 600
 601 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.isinteger).
 602 Whether value is integer.
 603
 604 #### isNaN(x) _(es5-ext/number/is-nan)_
 605
 606 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.isnan).
 607 Whether value is NaN. Differs from global isNaN that it doesn't do type coercion.
 608
 609 #### isNumber(x) _(es5-ext/number/is-number)_
 610
 611 Whether given value is number
 612
 613 #### isSafeInteger(x) _(es5-ext/number/is-safe-integer)_
 614
 615 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.issafeinteger).
 616
 617 #### MAX_SAFE_INTEGER _(es5-ext/number/max-safe-integer)_
 618
 619 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.maxsafeinteger).
 620 The value of Number.MAX_SAFE_INTEGER is 9007199254740991.
 621
 622 #### MIN_SAFE_INTEGER _(es5-ext/number/min-safe-integer)_
 623
 624 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-number.minsafeinteger).
 625 The value of Number.MIN_SAFE_INTEGER is -9007199254740991 (253-1).
 626
 627 #### toInteger(x) _(es5-ext/number/to-integer)_
 628
 629 Converts value to integer
 630
 631 #### toPosInteger(x) _(es5-ext/number/to-pos-integer)_
 632
 633 Converts value to positive integer. If provided value is less than 0, then 0 is returned
 634
 635 #### toUint32(x) _(es5-ext/number/to-uint32)_
 636
 637 Converts value to unsigned 32 bit integer. This type is used for array lengths.
 638 See: http://www.2ality.com/2012/02/js-integers.html
 639
 640 ### Number Prototype extensions
 641
 642 #### num.pad(length[, precision]) _(es5-ext/number/#/pad)_
 643
 644 Pad given number with zeros. Returns string
 645
 646 ### Object Constructor extensions
 647
 648 #### assign(target, source[, …sourcen]) _(es5-ext/object/assign)_
 649
 650 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-object.assign).
 651 Extend _target_ by enumerable own properties of other objects. If properties are already set on target object, they will be overwritten.
 652
 653 #### clear(obj) _(es5-ext/object/clear)_
 654
 655 Remove all enumerable own properties of the object
 656
 657 #### compact(obj) _(es5-ext/object/compact)_
 658
 659 Returns copy of the object with all enumerable properties that have no falsy values
 660
 661 #### compare(obj1, obj2) _(es5-ext/object/compare)_
 662
 663 Universal cross-type compare function. To be used for e.g. array sort.
 664
 665 #### copy(obj) _(es5-ext/object/copy)_
 666
 667 Returns copy of the object with all enumerable properties.
 668
 669 #### copyDeep(obj) _(es5-ext/object/copy-deep)_
 670
 671 Returns deep copy of the object with all enumerable properties.
 672
 673 #### count(obj) _(es5-ext/object/count)_
 674
 675 Counts number of enumerable own properties on object
 676
 677 #### create(obj[, properties]) _(es5-ext/object/create)_
 678
 679 `Object.create` alternative that provides workaround for [V8 issue](http://code.google.com/p/v8/issues/detail?id=2804).
 680
 681 When `null` is provided as a prototype, it's substituted with specially prepared object that derives from Object.prototype but has all Object.prototype properties shadowed with undefined.
 682
 683 It's quirky solution that allows us to have plain objects with no truthy properties but with turnable prototype.
 684
 685 Use only for objects that you plan to switch prototypes of and be aware of limitations of this workaround.
 686
 687 #### eq(x, y) _(es5-ext/object/eq)_
 688
 689 Whether two values are equal, using [_SameValueZero_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) algorithm.
 690
 691 #### every(obj, cb[, thisArg[, compareFn]]) _(es5-ext/object/every)_
 692
 693 Analogous to Array.prototype.every. Returns true if every key-value pair in this object satisfies the provided testing function.
 694 Optionally _compareFn_ can be provided which assures that keys are tested in given order. If provided _compareFn_ is equal to `true`, then order is alphabetical (by key).
 695
 696 #### filter(obj, cb[, thisArg]) _(es5-ext/object/filter)_
 697
 698 Analogous to Array.prototype.filter. Returns new object with properites for which _cb_ function returned truthy value.
 699
 700 #### firstKey(obj) _(es5-ext/object/first-key)_
 701
 702 Returns first enumerable key of the object, as keys are unordered by specification, it can be any key of an object.
 703
 704 #### flatten(obj) _(es5-ext/object/flatten)_
 705
 706 Returns new object, with flatten properties of input object
 707
 708 _flatten({ a: { b: 1 }, c: { d: 1 } })  =def  { b: 1, d: 1 }_
 709
 710 #### forEach(obj, cb[, thisArg[, compareFn]]) _(es5-ext/object/for-each)_
 711
 712 Analogous to Array.prototype.forEach. Calls a function for each key-value pair found in object
 713 Optionally _compareFn_ can be provided which assures that properties are iterated in given order. If provided _compareFn_ is equal to `true`, then order is alphabetical (by key).
 714
 715 #### getPropertyNames() _(es5-ext/object/get-property-names)_
 716
 717 Get all (not just own) property names of the object
 718
 719 #### is(x, y) _(es5-ext/object/is)_
 720
 721 Whether two values are equal, using [_SameValue_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-samevaluezero) algorithm.
 722
 723 #### isArrayLike(x) _(es5-ext/object/is-array-like)_
 724
 725 Whether object is array-like object
 726
 727 #### isCopy(x, y) _(es5-ext/object/is-copy)_
 728
 729 Two values are considered a copy of same value when all of their own enumerable properties have same values.
 730
 731 #### isCopyDeep(x, y) _(es5-ext/object/is-copy-deep)_
 732
 733 Deep comparision of objects
 734
 735 #### isEmpty(obj) _(es5-ext/object/is-empty)_
 736
 737 True if object doesn't have any own enumerable property
 738
 739 #### isObject(arg) _(es5-ext/object/is-object)_
 740
 741 Whether value is not primitive
 742
 743 #### isPlainObject(arg) _(es5-ext/object/is-plain-object)_
 744
 745 Whether object is plain object, its protototype should be Object.prototype and it cannot be host object.
 746
 747 #### keyOf(obj, searchValue) _(es5-ext/object/key-of)_
 748
 749 Search object for value
 750
 751 #### keys(obj) _(es5-ext/object/keys)_
 752
 753 [_Updated with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-object.keys).
 754 ES6's version of `keys`, doesn't throw on primitive input
 755
 756 #### map(obj, cb[, thisArg]) _(es5-ext/object/map)_
 757
 758 Analogous to Array.prototype.map. Creates a new object with properties which values are results of calling a provided function on every key-value pair in this object.
 759
 760 #### mapKeys(obj, cb[, thisArg]) _(es5-ext/object/map-keys)_
 761
 762 Create new object with same values, but remapped keys
 763
 764 #### mixin(target, source) _(es5-ext/object/mixin)_
 765
 766 Extend _target_ by all own properties of other objects. Properties found in both objects will be overwritten (unless they're not configurable and cannot be overwritten).
 767 _It was for a moment part of ECMAScript 6 draft._
 768
 769 #### mixinPrototypes(target, …source]) _(es5-ext/object/mixin-prototypes)_
 770
 771 Extends _target_, with all source and source's prototype properties.
 772 Useful as an alternative for `setPrototypeOf` in environments in which it cannot be shimmed (no `__proto__` support).
 773
 774 #### normalizeOptions(options) _(es5-ext/object/normalize-options)_
 775
 776 Normalizes options object into flat plain object.
 777
 778 Useful for functions in which we either need to keep options object for future reference or need to modify it for internal use.
 779
 780 - It never returns input `options` object back (always a copy is created)
 781 - `options` can be undefined in such case empty plain object is returned.
 782 - Copies all enumerable properties found down prototype chain.
 783
 784 #### primitiveSet([…names]) _(es5-ext/object/primitive-set)_
 785
 786 Creates `null` prototype based plain object, and sets on it all property names provided in arguments to true.
 787
 788 #### safeTraverse(obj[, …names]) _(es5-ext/object/safe-traverse)_
 789
 790 Safe navigation of object properties. See http://wiki.ecmascript.org/doku.php?id=strawman:existential_operator
 791
 792 #### serialize(value) _(es5-ext/object/serialize)_
 793
 794 Serialize value into string. Differs from [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) that it serializes also dates, functions and regular expresssions.
 795
 796 #### setPrototypeOf(object, proto) _(es5-ext/object/set-prototype-of)_
 797
 798 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-object.setprototypeof).
 799 If native version is not provided, it depends on existence of `__proto__` functionality, if it's missing, `null` instead of function is exposed.
 800
 801 #### some(obj, cb[, thisArg[, compareFn]]) _(es5-ext/object/some)_
 802
 803 Analogous to Array.prototype.some Returns true if any key-value pair satisfies the provided
 804 testing function.
 805 Optionally _compareFn_ can be provided which assures that keys are tested in given order. If provided _compareFn_ is equal to `true`, then order is alphabetical (by key).
 806
 807 #### toArray(obj[, cb[, thisArg[, compareFn]]]) _(es5-ext/object/to-array)_
 808
 809 Creates an array of results of calling a provided function on every key-value pair in this object.
 810 Optionally _compareFn_ can be provided which assures that results are added in given order. If provided _compareFn_ is equal to `true`, then order is alphabetical (by key).
 811
 812 #### unserialize(str) _(es5-ext/object/unserialize)_
 813
 814 Userializes value previously serialized with [serialize](#serializevalue-es5-extobjectserialize)
 815
 816 #### validCallable(x) _(es5-ext/object/valid-callable)_
 817
 818 If given object is not callable throw TypeError in other case return it.
 819
 820 #### validObject(x) _(es5-ext/object/valid-object)_
 821
 822 Throws error if given value is not an object, otherwise it is returned.
 823
 824 #### validValue(x) _(es5-ext/object/valid-value)_
 825
 826 Throws error if given value is `null` or `undefined`, otherwise returns value.
 827
 828 ### RegExp Constructor extensions
 829
 830 #### escape(str) _(es5-ext/reg-exp/escape)_
 831
 832 Escapes string to be used in regular expression
 833
 834 #### isRegExp(x) _(es5-ext/reg-exp/is-reg-exp)_
 835
 836 Whether object is regular expression
 837
 838 #### validRegExp(x) _(es5-ext/reg-exp/valid-reg-exp)_
 839
 840 If object is regular expression it is returned, otherwise TypeError is thrown.
 841
 842 ### RegExp Prototype extensions
 843
 844 #### re.isSticky(x) _(es5-ext/reg-exp/#/is-sticky)_
 845
 846 Whether regular expression has `sticky` flag.
 847
 848 It's to be used as counterpart to [regExp.sticky](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-get-regexp.prototype.sticky) if it's not implemented.
 849
 850 #### re.isUnicode(x) _(es5-ext/reg-exp/#/is-unicode)_
 851
 852 Whether regular expression has `unicode` flag.
 853
 854 It's to be used as counterpart to [regExp.unicode](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-get-regexp.prototype.unicode) if it's not implemented.
 855
 856 #### re.match(string) _(es5-ext/reg-exp/#/match)_
 857
 858 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.match).
 859
 860 #### re.replace(string, replaceValue) _(es5-ext/reg-exp/#/replace)_
 861
 862 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.replace).
 863
 864 #### re.search(string) _(es5-ext/reg-exp/#/search)_
 865
 866 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.search).
 867
 868 #### re.split(string) _(es5-ext/reg-exp/#/search)_
 869
 870 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.split).
 871
 872 #### re.sticky _(es5-ext/reg-exp/#/sticky/implement)_
 873
 874 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.sticky).
 875 It's a getter, so only `implement` and `is-implemented` modules are provided.
 876
 877 #### re.unicode _(es5-ext/reg-exp/#/unicode/implement)_
 878
 879 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-regexp.prototype.unicode).
 880 It's a getter, so only `implement` and `is-implemented` modules are provided.
 881
 882 ### String Constructor extensions
 883
 884 #### formatMethod(fMap) _(es5-ext/string/format-method)_
 885
 886 Creates format method. It's used e.g. to create `Date.prototype.format` method
 887
 888 #### fromCodePoint([…codePoints]) _(es5-ext/string/from-code-point)_
 889
 890 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.fromcodepoint)
 891
 892 #### isString(x) _(es5-ext/string/is-string)_
 893
 894 Whether object is string
 895
 896 #### randomUniq() _(es5-ext/string/random-uniq)_
 897
 898 Returns randomly generated id, with guarantee of local uniqueness (no same id will be returned twice)
 899
 900 #### raw(callSite[, …substitutions]) _(es5-ext/string/raw)_
 901
 902 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.raw)
 903
 904 ### String Prototype extensions
 905
 906 #### str.at(pos) _(es5-ext/string/#/at)_
 907
 908 _Proposed for ECMAScript 6/7 standard, but not (yet) in a draft_
 909
 910 Returns a string at given position in Unicode-safe manner.
 911 Based on [implementation by Mathias Bynens](https://github.com/mathiasbynens/String.prototype.at).
 912
 913 #### str.camelToHyphen() _(es5-ext/string/#/camel-to-hyphen)_
 914
 915 Convert camelCase string to hyphen separated, e.g. one-two-three -> oneTwoThree.
 916 Useful when converting names from js property convention into filename convention.
 917
 918 #### str.capitalize() _(es5-ext/string/#/capitalize)_
 919
 920 Capitalize first character of a string
 921
 922 #### str.caseInsensitiveCompare(str) _(es5-ext/string/#/case-insensitive-compare)_
 923
 924 Case insensitive compare
 925
 926 #### str.codePointAt(pos) _(es5-ext/string/#/code-point-at)_
 927
 928 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.codepointat)
 929
 930 Based on [implementation by Mathias Bynens](https://github.com/mathiasbynens/String.prototype.codePointAt).
 931
 932 #### str.contains(searchString[, position]) _(es5-ext/string/#/contains)_
 933
 934 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.contains)
 935
 936 Whether string contains given string.
 937
 938 #### str.endsWith(searchString[, endPosition]) _(es5-ext/string/#/ends-with)_
 939
 940 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.endswith).
 941 Whether strings ends with given string
 942
 943 #### str.hyphenToCamel() _(es5-ext/string/#/hyphen-to-camel)_
 944
 945 Convert hyphen separated string to camelCase, e.g. one-two-three -> oneTwoThree.
 946 Useful when converting names from filename convention to js property name convention.
 947
 948 #### str.indent(str[, count]) _(es5-ext/string/#/indent)_
 949
 950 Indents each line with provided _str_ (if _count_ given then _str_ is repeated _count_ times).
 951
 952 #### str.last() _(es5-ext/string/#/last)_
 953
 954 Return last character
 955
 956 #### str.normalize([form]) _(es5-ext/string/#/normalize)_
 957
 958 [_Introduced with ECMAScript 6_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize).
 959 Returns the Unicode Normalization Form of a given string.
 960 Based on Matsuza's version. Code used for integrated shim can be found at [github.com/walling/unorm](https://github.com/walling/unorm/blob/master/lib/unorm.js)
 961
 962 #### str.pad(fill[, length]) _(es5-ext/string/#/pad)_
 963
 964 Pad string with _fill_.
 965 If _length_ si given than _fill_ is reapated _length_ times.
 966 If _length_ is negative then pad is applied from right.
 967
 968 #### str.repeat(n) _(es5-ext/string/#/repeat)_
 969
 970 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.repeat).
 971 Repeat given string _n_ times
 972
 973 #### str.plainReplace(search, replace) _(es5-ext/string/#/plain-replace)_
 974
 975 Simple `replace` version. Doesn't support regular expressions. Replaces just first occurrence of search string. Doesn't support insert patterns, therefore it is safe to replace text with text obtained programmatically (there's no need for additional _$_ characters escape in such case).
 976
 977 #### str.plainReplaceAll(search, replace) _(es5-ext/string/#/plain-replace-all)_
 978
 979 Simple `replace` version. Doesn't support regular expressions. Replaces all occurrences of search string. Doesn't support insert patterns, therefore it is safe to replace text with text obtained programmatically (there's no need for additional _$_ characters escape in such case).
 980
 981 #### str.startsWith(searchString[, position]) _(es5-ext/string/#/starts-with)_
 982
 983 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.startswith).
 984 Whether strings starts with given string
 985
 986 #### str[@@iterator] _(es5-ext/string/#/@@iterator)_
 987
 988 [_Introduced with ECMAScript 6_](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype-@@iterator).
 989 Returns iterator object which traverses all string characters (with respect to unicode symbols)
 990
 991 ### Tests [![Build Status](https://travis-ci.org/medikoo/es5-ext.png)](https://travis-ci.org/medikoo/es5-ext)
 992
 993         $ npm test