| Current File : //lib/node_modules/bower/lib/node_modules/mout/doc/function.md |
# function #
Function*(al)* utilities.
## awaitDelay(fn, delay):Function
Returns a function that ensures that `fn` is only called *after* `delay`
milliseconds have elapsed. When the returned function is called before the
delay has elapsed, it will wait until the delay has elapsed and then call `fn`.
When the returned function is called after the delay has elapsed, it will call
`fn` after the next "tick" (it will always be called asynchronously). The
context and arguments that the returned function is called in are applied to
`fn`.
In the below example `onLoaded` will not be executed before a 1000 millisecond
delay. Even if `loadImages` loads and calls `callback` earlier. However, say
the images take 1500 milliseconds to load, it will trigger `onLoaded`
immediately.
```js
var callback = awaitDelay(onLoaded, 1000);
loadImages(callback);
function onLoaded(){
console.log('loaded');
}
```
You can also cancel de delayed call by simply using the native `clearTimeout`
method (like a regular `setTimeout` call).
```js
var timeoutId = callback();
// onLoaded won't be called since it was canceled before the 1000ms delay
clearTimeout(timeoutId);
```
### Arguments:
1. `fn` (Function) : Target Function
2. `delay` (Number) : Delay of execution in milliseconds
See: [`debounce()`](#debounce)
## bind(fn, context, [...args]):Function
Return a function that will execute in the given context, optionally adding any additional supplied parameters to the beginning of the arguments collection.
### Arguments
1. `fn` (Function) : Target Function
2. `context` (Object) : Execution context (object used as `this`)
3. `[...args]` (*) : Arguments (0...n arguments)
See: [`partial()`](#partial), [object/bindAll](./object.html#bindAll)
## compose(...fn):Function
Returns the composition of a list of functions, where each function consumes
the return value of the function that follows. In math terms, composing the
functions `f()`, `g()`, and `h()` produces `f(g(h()))`.
```js
function add2(x) { return x + 2 }
function multi2(x) { return x * 2 }
map([1, 2, 3], compose(add2, multi2)); // [4, 6, 8]
//same as
map([1, 2, 3], function(x){
return add2( multi2(x) );
});
```
## constant(value):Function
Returns a new function that will always return `value` when called.
```js
var f = constant('foo');
f(); // 'foo'
// Provided arguments are ignored; value is always returned
f(1); // 'foo'
f = constant({ foo: 'bar' });
f(); // { foo: 'bar' }
```
## debounce(fn, delay[, isAsap]):Function
Creates a function that will delay the execution of `fn` until after `delay`
milliseconds have elapsed since the last time it was invoked.
Subsequent calls to the debounced function will return the result of the last
`fn` call.
```js
// sometimes less is more
var lazyRedraw = debounce(redraw, 300);
foo.on.resize.add(lazyRedraw);
```
In this visualization, `|` is a debounced-function call and `X` is the actual
callback execution:
Default
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X X
Debounced with `isAsap == true`:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X X
You also have the option to cancel the debounced call if it didn't happen yet:
```js
lazyRedraw();
// lazyRedraw won't be called since `cancel` was called before the `delay`
lazyRedraw.cancel();
```
See: [`throttle()`](#throttle)
## func(name):Function
Returns a function that calls a method with given `name` on supplied object.
Useful for iteration methods like `array/map` and `array/forEach`.
See: [`prop()`](#prop)
```js
// will call the method `getName()` for each `user`
var names = map(users, func('getName'));
```
## identity(val):*
Returns the first argument provided to it.
```js
identity(3); // 3
identity(1,2,3); // 1
identity('foo'); // "foo"
```
## partial(fn, [...args]):Function
Return a partially applied function supplying default arguments.
This method is similar to [`bind`](#bind), except it does not alter the this
binding.
### Arguments
1. `fn` (Function) : Target Function
2. `[...args]` (*) : Arguments (0...n arguments)
See: [`bind()`](#bind)
```js
function add(a, b){ return a + b }
var add10 = partial(add, 10);
console.log( add10(2) ); // 12
```
## prop(name):Function
Returns a function that gets a property with given `name` from supplied object.
Useful for using in conjunction with `array/map` and/or for creating getters.
See: [`array/pluck()`](array.html#pluck)
```js
var users = [{name:"John", age:21}, {name:"Jane", age:25}];
// ["John", "Jane"]
var names = map(users, prop('name'));
```
## series(...fn):Function
Returns a function that will execute all the supplied functions in order and
passing the same parameters to all of them. Useful for combining multiple
`array/forEach` into a single one and/or for debugging.
```js
// call `console.log()` and `doStuff()` for each item item in the array
forEach(arr, series(console.log, doStuff));
```
## throttle(fn, interval):Function
Creates a function that, when executed, will only call the `fn` function at
most once per every `interval` milliseconds.
If the throttled function is invoked more than once during the wait timeout,
`fn` will also be called on the trailing edge of the timeout.
Subsequent calls to the throttled function will return the result of the last
`fn` call.
```js
// sometimes less is more
var lazyRedraw = throttle(redraw, 300);
foo.on.resize.add(lazyRedraw);
```
In this visualization, `|` is a throttled-function call and `X` is the actual
`fn` execution:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X X X X X X X X X X X X
You also have the option to cancel the throttled call if it didn't happen yet:
```js
lazyRedraw();
setTimeout(function(){
lazyRedraw();
// lazyRedraw will be called only once since `cancel` was called before
// the `interval` for 2nd call completed
lazyRedraw.cancel();
}, 250);
```
See: [`debounce()`](#debounce)
## timeout(fn, millis, context, [...args]):Number
Functions as a wrapper for `setTimeout`. Calls a the function `fn` after a given delay `millis` in milliseconds.
The function is called within the specified context. The return value can be used to clear the timeout using `clearTimeout`.
```js
var id = timeout(doStuff, 300, this);
clearTimeout(id);
```
## times(n, callback, [context]):void
Iterates over a callback `n` times.
### Arguments
1. `n` (Number) : Number of iterations
2. `callback` (Function) : Closure executed for every iteration
3. `context` (Object) : Execution context (object used as `this`)
```js
var output = '';
times(5, function(i) {
output += i.toString();
});
// output: 01234
```
## wrap(fn, wrapper):Function
Wraps the first `fn` inside of the `wrapper` function, passing it as the first argument. This allows the `wrapper` to execute code before and after the `fn` runs, adjust the arguments, and execute it conditionally.
```js
var hello = function(name) { return "hello: " + name; };
hello = wrap(hello, function(func) {
return "before, " + func("moe") + ", after";
});
hello();
// output: 'before, hello: moe, after'
```
See: [`partial()`](#partial)
-------------------------------------------------------------------------------
For more usage examples check specs inside `/tests` folder. Unit tests are the
best documentation you can get...