484 lines
14 KiB
JavaScript
484 lines
14 KiB
JavaScript
|
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
|
||
|
|
//
|
||
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
// you may not use this file except in compliance with the License.
|
||
|
|
// You may obtain a copy of the License at
|
||
|
|
//
|
||
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
//
|
||
|
|
// Unless required by applicable law or agreed to in writing, software
|
||
|
|
// distributed under the License is distributed on an "AS-IS" BASIS,
|
||
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
// See the License for the specific language governing permissions and
|
||
|
|
// limitations under the License.
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @fileoverview Utilities for creating functions. Loosely inspired by the
|
||
|
|
* java classes: http://goo.gl/GM0Hmu and http://goo.gl/6k7nI8.
|
||
|
|
*
|
||
|
|
* @author nicksantos@google.com (Nick Santos)
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
goog.provide('goog.functions');
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that always returns the same value.
|
||
|
|
* @param {T} retValue The value to return.
|
||
|
|
* @return {function():T} The new function.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.constant = function(retValue) {
|
||
|
|
return function() { return retValue; };
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Always returns false.
|
||
|
|
* @type {function(...): boolean}
|
||
|
|
*/
|
||
|
|
goog.functions.FALSE = goog.functions.constant(false);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Always returns true.
|
||
|
|
* @type {function(...): boolean}
|
||
|
|
*/
|
||
|
|
goog.functions.TRUE = goog.functions.constant(true);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Always returns NULL.
|
||
|
|
* @type {function(...): null}
|
||
|
|
*/
|
||
|
|
goog.functions.NULL = goog.functions.constant(null);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A simple function that returns the first argument of whatever is passed
|
||
|
|
* into it.
|
||
|
|
* @param {T=} opt_returnValue The single value that will be returned.
|
||
|
|
* @param {...*} var_args Optional trailing arguments. These are ignored.
|
||
|
|
* @return {T} The first argument passed in, or undefined if nothing was passed.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.identity = function(opt_returnValue, var_args) {
|
||
|
|
return opt_returnValue;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that always throws an error with the given message.
|
||
|
|
* @param {string} message The error message.
|
||
|
|
* @return {!Function} The error-throwing function.
|
||
|
|
*/
|
||
|
|
goog.functions.error = function(message) {
|
||
|
|
return function() { throw Error(message); };
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that throws the given object.
|
||
|
|
* @param {*} err An object to be thrown.
|
||
|
|
* @return {!Function} The error-throwing function.
|
||
|
|
*/
|
||
|
|
goog.functions.fail = function(err) {
|
||
|
|
return function() { throw err; };
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Given a function, create a function that keeps opt_numArgs arguments and
|
||
|
|
* silently discards all additional arguments.
|
||
|
|
* @param {Function} f The original function.
|
||
|
|
* @param {number=} opt_numArgs The number of arguments to keep. Defaults to 0.
|
||
|
|
* @return {!Function} A version of f that only keeps the first opt_numArgs
|
||
|
|
* arguments.
|
||
|
|
*/
|
||
|
|
goog.functions.lock = function(f, opt_numArgs) {
|
||
|
|
opt_numArgs = opt_numArgs || 0;
|
||
|
|
return function() {
|
||
|
|
return f.apply(this, Array.prototype.slice.call(arguments, 0, opt_numArgs));
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that returns its nth argument.
|
||
|
|
* @param {number} n The position of the return argument.
|
||
|
|
* @return {!Function} A new function.
|
||
|
|
*/
|
||
|
|
goog.functions.nth = function(n) {
|
||
|
|
return function() { return arguments[n]; };
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Like goog.partial(), except that arguments are added after arguments to the
|
||
|
|
* returned function.
|
||
|
|
*
|
||
|
|
* Usage:
|
||
|
|
* function f(arg1, arg2, arg3, arg4) { ... }
|
||
|
|
* var g = goog.functions.partialRight(f, arg3, arg4);
|
||
|
|
* g(arg1, arg2);
|
||
|
|
*
|
||
|
|
* @param {!Function} fn A function to partially apply.
|
||
|
|
* @param {...*} var_args Additional arguments that are partially applied to fn
|
||
|
|
* at the end.
|
||
|
|
* @return {!Function} A partially-applied form of the function goog.partial()
|
||
|
|
* was invoked as a method of.
|
||
|
|
*/
|
||
|
|
goog.functions.partialRight = function(fn, var_args) {
|
||
|
|
var rightArgs = Array.prototype.slice.call(arguments, 1);
|
||
|
|
return function() {
|
||
|
|
var newArgs = Array.prototype.slice.call(arguments);
|
||
|
|
newArgs.push.apply(newArgs, rightArgs);
|
||
|
|
return fn.apply(this, newArgs);
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Given a function, create a new function that swallows its return value
|
||
|
|
* and replaces it with a new one.
|
||
|
|
* @param {Function} f A function.
|
||
|
|
* @param {T} retValue A new return value.
|
||
|
|
* @return {function(...?):T} A new function.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.withReturnValue = function(f, retValue) {
|
||
|
|
return goog.functions.sequence(f, goog.functions.constant(retValue));
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that returns whether its argument equals the given value.
|
||
|
|
*
|
||
|
|
* Example:
|
||
|
|
* var key = goog.object.findKey(obj, goog.functions.equalTo('needle'));
|
||
|
|
*
|
||
|
|
* @param {*} value The value to compare to.
|
||
|
|
* @param {boolean=} opt_useLooseComparison Whether to use a loose (==)
|
||
|
|
* comparison rather than a strict (===) one. Defaults to false.
|
||
|
|
* @return {function(*):boolean} The new function.
|
||
|
|
*/
|
||
|
|
goog.functions.equalTo = function(value, opt_useLooseComparison) {
|
||
|
|
return function(other) {
|
||
|
|
return opt_useLooseComparison ? (value == other) : (value === other);
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates the composition of the functions passed in.
|
||
|
|
* For example, (goog.functions.compose(f, g))(a) is equivalent to f(g(a)).
|
||
|
|
* @param {function(...?):T} fn The final function.
|
||
|
|
* @param {...Function} var_args A list of functions.
|
||
|
|
* @return {function(...?):T} The composition of all inputs.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.compose = function(fn, var_args) {
|
||
|
|
var functions = arguments;
|
||
|
|
var length = functions.length;
|
||
|
|
return function() {
|
||
|
|
var result;
|
||
|
|
if (length) {
|
||
|
|
result = functions[length - 1].apply(this, arguments);
|
||
|
|
}
|
||
|
|
|
||
|
|
for (var i = length - 2; i >= 0; i--) {
|
||
|
|
result = functions[i].call(this, result);
|
||
|
|
}
|
||
|
|
return result;
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that calls the functions passed in in sequence, and
|
||
|
|
* returns the value of the last function. For example,
|
||
|
|
* (goog.functions.sequence(f, g))(x) is equivalent to f(x),g(x).
|
||
|
|
* @param {...Function} var_args A list of functions.
|
||
|
|
* @return {!Function} A function that calls all inputs in sequence.
|
||
|
|
*/
|
||
|
|
goog.functions.sequence = function(var_args) {
|
||
|
|
var functions = arguments;
|
||
|
|
var length = functions.length;
|
||
|
|
return function() {
|
||
|
|
var result;
|
||
|
|
for (var i = 0; i < length; i++) {
|
||
|
|
result = functions[i].apply(this, arguments);
|
||
|
|
}
|
||
|
|
return result;
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that returns true if each of its components evaluates
|
||
|
|
* to true. The components are evaluated in order, and the evaluation will be
|
||
|
|
* short-circuited as soon as a function returns false.
|
||
|
|
* For example, (goog.functions.and(f, g))(x) is equivalent to f(x) && g(x).
|
||
|
|
* @param {...Function} var_args A list of functions.
|
||
|
|
* @return {function(...?):boolean} A function that ANDs its component
|
||
|
|
* functions.
|
||
|
|
*/
|
||
|
|
goog.functions.and = function(var_args) {
|
||
|
|
var functions = arguments;
|
||
|
|
var length = functions.length;
|
||
|
|
return function() {
|
||
|
|
for (var i = 0; i < length; i++) {
|
||
|
|
if (!functions[i].apply(this, arguments)) {
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return true;
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that returns true if any of its components evaluates
|
||
|
|
* to true. The components are evaluated in order, and the evaluation will be
|
||
|
|
* short-circuited as soon as a function returns true.
|
||
|
|
* For example, (goog.functions.or(f, g))(x) is equivalent to f(x) || g(x).
|
||
|
|
* @param {...Function} var_args A list of functions.
|
||
|
|
* @return {function(...?):boolean} A function that ORs its component
|
||
|
|
* functions.
|
||
|
|
*/
|
||
|
|
goog.functions.or = function(var_args) {
|
||
|
|
var functions = arguments;
|
||
|
|
var length = functions.length;
|
||
|
|
return function() {
|
||
|
|
for (var i = 0; i < length; i++) {
|
||
|
|
if (functions[i].apply(this, arguments)) {
|
||
|
|
return true;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return false;
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a function that returns the Boolean opposite of a provided function.
|
||
|
|
* For example, (goog.functions.not(f))(x) is equivalent to !f(x).
|
||
|
|
* @param {!Function} f The original function.
|
||
|
|
* @return {function(...?):boolean} A function that delegates to f and returns
|
||
|
|
* opposite.
|
||
|
|
*/
|
||
|
|
goog.functions.not = function(f) {
|
||
|
|
return function() { return !f.apply(this, arguments); };
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Generic factory function to construct an object given the constructor
|
||
|
|
* and the arguments. Intended to be bound to create object factories.
|
||
|
|
*
|
||
|
|
* Example:
|
||
|
|
*
|
||
|
|
* var factory = goog.partial(goog.functions.create, Class);
|
||
|
|
*
|
||
|
|
* @param {function(new:T, ...)} constructor The constructor for the Object.
|
||
|
|
* @param {...*} var_args The arguments to be passed to the constructor.
|
||
|
|
* @return {T} A new instance of the class given in {@code constructor}.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.create = function(constructor, var_args) {
|
||
|
|
/**
|
||
|
|
* @constructor
|
||
|
|
* @final
|
||
|
|
*/
|
||
|
|
var temp = function() {};
|
||
|
|
temp.prototype = constructor.prototype;
|
||
|
|
|
||
|
|
// obj will have constructor's prototype in its chain and
|
||
|
|
// 'obj instanceof constructor' will be true.
|
||
|
|
var obj = new temp();
|
||
|
|
|
||
|
|
// obj is initialized by constructor.
|
||
|
|
// arguments is only array-like so lacks shift(), but can be used with
|
||
|
|
// the Array prototype function.
|
||
|
|
constructor.apply(obj, Array.prototype.slice.call(arguments, 1));
|
||
|
|
return obj;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @define {boolean} Whether the return value cache should be used.
|
||
|
|
* This should only be used to disable caches when testing.
|
||
|
|
*/
|
||
|
|
goog.define('goog.functions.CACHE_RETURN_VALUE', true);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Gives a wrapper function that caches the return value of a parameterless
|
||
|
|
* function when first called.
|
||
|
|
*
|
||
|
|
* When called for the first time, the given function is called and its
|
||
|
|
* return value is cached (thus this is only appropriate for idempotent
|
||
|
|
* functions). Subsequent calls will return the cached return value. This
|
||
|
|
* allows the evaluation of expensive functions to be delayed until first used.
|
||
|
|
*
|
||
|
|
* To cache the return values of functions with parameters, see goog.memoize.
|
||
|
|
*
|
||
|
|
* @param {function():T} fn A function to lazily evaluate.
|
||
|
|
* @return {function():T} A wrapped version the function.
|
||
|
|
* @template T
|
||
|
|
*/
|
||
|
|
goog.functions.cacheReturnValue = function(fn) {
|
||
|
|
var called = false;
|
||
|
|
var value;
|
||
|
|
|
||
|
|
return function() {
|
||
|
|
if (!goog.functions.CACHE_RETURN_VALUE) {
|
||
|
|
return fn();
|
||
|
|
}
|
||
|
|
|
||
|
|
if (!called) {
|
||
|
|
value = fn();
|
||
|
|
called = true;
|
||
|
|
}
|
||
|
|
|
||
|
|
return value;
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Wraps a function to allow it to be called, at most, once. All
|
||
|
|
* additional calls are no-ops.
|
||
|
|
*
|
||
|
|
* This is particularly useful for initialization functions
|
||
|
|
* that should be called, at most, once.
|
||
|
|
*
|
||
|
|
* @param {function():*} f Function to call.
|
||
|
|
* @return {function():undefined} Wrapped function.
|
||
|
|
*/
|
||
|
|
goog.functions.once = function(f) {
|
||
|
|
// Keep a reference to the function that we null out when we're done with
|
||
|
|
// it -- that way, the function can be GC'd when we're done with it.
|
||
|
|
var inner = f;
|
||
|
|
return function() {
|
||
|
|
if (inner) {
|
||
|
|
var tmp = inner;
|
||
|
|
inner = null;
|
||
|
|
tmp();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Wraps a function to allow it to be called, at most, once per interval
|
||
|
|
* (specified in milliseconds). If the wrapper function is called N times within
|
||
|
|
* that interval, only the Nth call will go through.
|
||
|
|
*
|
||
|
|
* This is particularly useful for batching up repeated actions where the
|
||
|
|
* last action should win. This can be used, for example, for refreshing an
|
||
|
|
* autocomplete pop-up every so often rather than updating with every keystroke,
|
||
|
|
* since the final text typed by the user is the one that should produce the
|
||
|
|
* final autocomplete results. For more stateful debouncing with support for
|
||
|
|
* pausing, resuming, and canceling debounced actions, use {@code
|
||
|
|
* goog.async.Debouncer}.
|
||
|
|
*
|
||
|
|
* @param {function(this:SCOPE, ...?)} f Function to call.
|
||
|
|
* @param {number} interval Interval over which to debounce. The function will
|
||
|
|
* only be called after the full interval has elapsed since the last call.
|
||
|
|
* @param {SCOPE=} opt_scope Object in whose scope to call the function.
|
||
|
|
* @return {function(...?): undefined} Wrapped function.
|
||
|
|
* @template SCOPE
|
||
|
|
*/
|
||
|
|
goog.functions.debounce = function(f, interval, opt_scope) {
|
||
|
|
var timeout = 0;
|
||
|
|
return /** @type {function(...?)} */ (function(var_args) {
|
||
|
|
goog.global.clearTimeout(timeout);
|
||
|
|
var args = arguments;
|
||
|
|
timeout = goog.global.setTimeout(function() {
|
||
|
|
f.apply(opt_scope, args);
|
||
|
|
}, interval);
|
||
|
|
});
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Wraps a function to allow it to be called, at most, once per interval
|
||
|
|
* (specified in milliseconds). If the wrapper function is called N times in
|
||
|
|
* that interval, both the 1st and the Nth calls will go through.
|
||
|
|
*
|
||
|
|
* This is particularly useful for limiting repeated user requests where the
|
||
|
|
* the last action should win, but you also don't want to wait until the end of
|
||
|
|
* the interval before sending a request out, as it leads to a perception of
|
||
|
|
* slowness for the user.
|
||
|
|
*
|
||
|
|
* @param {function(this:SCOPE, ...?)} f Function to call.
|
||
|
|
* @param {number} interval Interval over which to throttle. The function can
|
||
|
|
* only be called once per interval.
|
||
|
|
* @param {SCOPE=} opt_scope Object in whose scope to call the function.
|
||
|
|
* @return {function(...?): undefined} Wrapped function.
|
||
|
|
* @template SCOPE
|
||
|
|
*/
|
||
|
|
goog.functions.throttle = function(f, interval, opt_scope) {
|
||
|
|
var timeout = 0;
|
||
|
|
var shouldFire = false;
|
||
|
|
var args = [];
|
||
|
|
|
||
|
|
var handleTimeout = function() {
|
||
|
|
timeout = 0;
|
||
|
|
if (shouldFire) {
|
||
|
|
shouldFire = false;
|
||
|
|
fire();
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
var fire = function() {
|
||
|
|
timeout = goog.global.setTimeout(handleTimeout, interval);
|
||
|
|
f.apply(opt_scope, args);
|
||
|
|
};
|
||
|
|
|
||
|
|
return /** @type {function(...?)} */ (function(var_args) {
|
||
|
|
args = arguments;
|
||
|
|
if (!timeout) {
|
||
|
|
fire();
|
||
|
|
} else {
|
||
|
|
shouldFire = true;
|
||
|
|
}
|
||
|
|
});
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Wraps a function to allow it to be called, at most, once per interval
|
||
|
|
* (specified in milliseconds). If the wrapper function is called N times within
|
||
|
|
* that interval, only the 1st call will go through.
|
||
|
|
*
|
||
|
|
* This is particularly useful for limiting repeated user requests where the
|
||
|
|
* first request is guaranteed to have all the data required to perform the
|
||
|
|
* final action, so there's no need to wait until the end of the interval before
|
||
|
|
* sending the request out.
|
||
|
|
*
|
||
|
|
* @param {function(this:SCOPE, ...?)} f Function to call.
|
||
|
|
* @param {number} interval Interval over which to rate-limit. The function will
|
||
|
|
* only be called once per interval, and ignored for the remainer of the
|
||
|
|
* interval.
|
||
|
|
* @param {SCOPE=} opt_scope Object in whose scope to call the function.
|
||
|
|
* @return {function(...?): undefined} Wrapped function.
|
||
|
|
* @template SCOPE
|
||
|
|
*/
|
||
|
|
goog.functions.rateLimit = function(f, interval, opt_scope) {
|
||
|
|
var timeout = 0;
|
||
|
|
|
||
|
|
var handleTimeout = function() {
|
||
|
|
timeout = 0;
|
||
|
|
};
|
||
|
|
|
||
|
|
return /** @type {function(...?)} */ (function(var_args) {
|
||
|
|
if (!timeout) {
|
||
|
|
timeout = goog.global.setTimeout(handleTimeout, interval);
|
||
|
|
f.apply(opt_scope, arguments);
|
||
|
|
}
|
||
|
|
});
|
||
|
|
};
|