lib/goog/functions/functions.js

1// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS-IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/**
16 * @fileoverview Utilities for creating functions. Loosely inspired by the
17 * java classes: http://goo.gl/GM0Hmu and http://goo.gl/6k7nI8.
18 *
19 * @author nicksantos@google.com (Nick Santos)
20 */
21
22
23goog.provide('goog.functions');
24
25
26/**
27 * Creates a function that always returns the same value.
28 * @param {T} retValue The value to return.
29 * @return {function():T} The new function.
30 * @template T
31 */
32goog.functions.constant = function(retValue) {
33 return function() {
34 return retValue;
35 };
36};
37
38
39/**
40 * Always returns false.
41 * @type {function(...): boolean}
42 */
43goog.functions.FALSE = goog.functions.constant(false);
44
45
46/**
47 * Always returns true.
48 * @type {function(...): boolean}
49 */
50goog.functions.TRUE = goog.functions.constant(true);
51
52
53/**
54 * Always returns NULL.
55 * @type {function(...): null}
56 */
57goog.functions.NULL = goog.functions.constant(null);
58
59
60/**
61 * A simple function that returns the first argument of whatever is passed
62 * into it.
63 * @param {T=} opt_returnValue The single value that will be returned.
64 * @param {...*} var_args Optional trailing arguments. These are ignored.
65 * @return {T} The first argument passed in, or undefined if nothing was passed.
66 * @template T
67 */
68goog.functions.identity = function(opt_returnValue, var_args) {
69 return opt_returnValue;
70};
71
72
73/**
74 * Creates a function that always throws an error with the given message.
75 * @param {string} message The error message.
76 * @return {!Function} The error-throwing function.
77 */
78goog.functions.error = function(message) {
79 return function() {
80 throw Error(message);
81 };
82};
83
84
85/**
86 * Creates a function that throws the given object.
87 * @param {*} err An object to be thrown.
88 * @return {!Function} The error-throwing function.
89 */
90goog.functions.fail = function(err) {
91 return function() {
92 throw err;
93 }
94};
95
96
97/**
98 * Given a function, create a function that keeps opt_numArgs arguments and
99 * silently discards all additional arguments.
100 * @param {Function} f The original function.
101 * @param {number=} opt_numArgs The number of arguments to keep. Defaults to 0.
102 * @return {!Function} A version of f that only keeps the first opt_numArgs
103 * arguments.
104 */
105goog.functions.lock = function(f, opt_numArgs) {
106 opt_numArgs = opt_numArgs || 0;
107 return function() {
108 return f.apply(this, Array.prototype.slice.call(arguments, 0, opt_numArgs));
109 };
110};
111
112
113/**
114 * Creates a function that returns its nth argument.
115 * @param {number} n The position of the return argument.
116 * @return {!Function} A new function.
117 */
118goog.functions.nth = function(n) {
119 return function() {
120 return arguments[n];
121 };
122};
123
124
125/**
126 * Given a function, create a new function that swallows its return value
127 * and replaces it with a new one.
128 * @param {Function} f A function.
129 * @param {T} retValue A new return value.
130 * @return {function(...[?]):T} A new function.
131 * @template T
132 */
133goog.functions.withReturnValue = function(f, retValue) {
134 return goog.functions.sequence(f, goog.functions.constant(retValue));
135};
136
137
138/**
139 * Creates the composition of the functions passed in.
140 * For example, (goog.functions.compose(f, g))(a) is equivalent to f(g(a)).
141 * @param {function(...[?]):T} fn The final function.
142 * @param {...Function} var_args A list of functions.
143 * @return {function(...[?]):T} The composition of all inputs.
144 * @template T
145 */
146goog.functions.compose = function(fn, var_args) {
147 var functions = arguments;
148 var length = functions.length;
149 return function() {
150 var result;
151 if (length) {
152 result = functions[length - 1].apply(this, arguments);
153 }
154
155 for (var i = length - 2; i >= 0; i--) {
156 result = functions[i].call(this, result);
157 }
158 return result;
159 };
160};
161
162
163/**
164 * Creates a function that calls the functions passed in in sequence, and
165 * returns the value of the last function. For example,
166 * (goog.functions.sequence(f, g))(x) is equivalent to f(x),g(x).
167 * @param {...Function} var_args A list of functions.
168 * @return {!Function} A function that calls all inputs in sequence.
169 */
170goog.functions.sequence = function(var_args) {
171 var functions = arguments;
172 var length = functions.length;
173 return function() {
174 var result;
175 for (var i = 0; i < length; i++) {
176 result = functions[i].apply(this, arguments);
177 }
178 return result;
179 };
180};
181
182
183/**
184 * Creates a function that returns true if each of its components evaluates
185 * to true. The components are evaluated in order, and the evaluation will be
186 * short-circuited as soon as a function returns false.
187 * For example, (goog.functions.and(f, g))(x) is equivalent to f(x) && g(x).
188 * @param {...Function} var_args A list of functions.
189 * @return {function(...[?]):boolean} A function that ANDs its component
190 * functions.
191 */
192goog.functions.and = function(var_args) {
193 var functions = arguments;
194 var length = functions.length;
195 return function() {
196 for (var i = 0; i < length; i++) {
197 if (!functions[i].apply(this, arguments)) {
198 return false;
199 }
200 }
201 return true;
202 };
203};
204
205
206/**
207 * Creates a function that returns true if any of its components evaluates
208 * to true. The components are evaluated in order, and the evaluation will be
209 * short-circuited as soon as a function returns true.
210 * For example, (goog.functions.or(f, g))(x) is equivalent to f(x) || g(x).
211 * @param {...Function} var_args A list of functions.
212 * @return {function(...[?]):boolean} A function that ORs its component
213 * functions.
214 */
215goog.functions.or = function(var_args) {
216 var functions = arguments;
217 var length = functions.length;
218 return function() {
219 for (var i = 0; i < length; i++) {
220 if (functions[i].apply(this, arguments)) {
221 return true;
222 }
223 }
224 return false;
225 };
226};
227
228
229/**
230 * Creates a function that returns the Boolean opposite of a provided function.
231 * For example, (goog.functions.not(f))(x) is equivalent to !f(x).
232 * @param {!Function} f The original function.
233 * @return {function(...[?]):boolean} A function that delegates to f and returns
234 * opposite.
235 */
236goog.functions.not = function(f) {
237 return function() {
238 return !f.apply(this, arguments);
239 };
240};
241
242
243/**
244 * Generic factory function to construct an object given the constructor
245 * and the arguments. Intended to be bound to create object factories.
246 *
247 * Callers should cast the result to the appropriate type for proper type
248 * checking by the compiler.
249 * @param {!Function} constructor The constructor for the Object.
250 * @param {...*} var_args The arguments to be passed to the constructor.
251 * @return {!Object} A new instance of the class given in {@code constructor}.
252 */
253goog.functions.create = function(constructor, var_args) {
254 /**
255 * @constructor
256 * @final
257 */
258 var temp = function() {};
259 temp.prototype = constructor.prototype;
260
261 // obj will have constructor's prototype in its chain and
262 // 'obj instanceof constructor' will be true.
263 var obj = new temp();
264
265 // obj is initialized by constructor.
266 // arguments is only array-like so lacks shift(), but can be used with
267 // the Array prototype function.
268 constructor.apply(obj, Array.prototype.slice.call(arguments, 1));
269 return obj;
270};
271
272
273/**
274 * @define {boolean} Whether the return value cache should be used.
275 * This should only be used to disable caches when testing.
276 */
277goog.define('goog.functions.CACHE_RETURN_VALUE', true);
278
279
280/**
281 * Gives a wrapper function that caches the return value of a parameterless
282 * function when first called.
283 *
284 * When called for the first time, the given function is called and its
285 * return value is cached (thus this is only appropriate for idempotent
286 * functions). Subsequent calls will return the cached return value. This
287 * allows the evaluation of expensive functions to be delayed until first used.
288 *
289 * To cache the return values of functions with parameters, see goog.memoize.
290 *
291 * @param {!function():T} fn A function to lazily evaluate.
292 * @return {!function():T} A wrapped version the function.
293 * @template T
294 */
295goog.functions.cacheReturnValue = function(fn) {
296 var called = false;
297 var value;
298
299 return function() {
300 if (!goog.functions.CACHE_RETURN_VALUE) {
301 return fn();
302 }
303
304 if (!called) {
305 value = fn();
306 called = true;
307 }
308
309 return value;
310 }
311};