1 /* Copyright 2014 Yukkuri Games
2 Licensed under the terms of the GNU GPL v2 or later
3 @license http://www.gnu.org/licenses/gpl-2.0.html
4 @source: http://yukkurigames.com/yuu/
10 /** yf - yuu foundation
12 A collection of tools for functional programming and the kind
13 of sequence (array) manipulations usually associated with
14 functional programming.
16 yf doesn't depend on yuu specifically, but may use standard
17 features not yet widely supported provided by yuu/pre.
20 function isFunction (o
) {
21 /** Check if a value is a function */
22 return Object
.prototype.toString
.call(o
) === '[object Function]';
25 function isString (s
) {
26 /** Check if a value is a string */
27 return Object
.prototype.toString
.call(s
) === "[object String]";
30 function I (x
) { return x
; }
32 function K (x
) { return function () { return x
; }; }
34 /** Get the minimum or maximum of two objects
36 The default JavaScript Math.min and Math.max are unsuitable as
37 generic functions. They don't work on strings. Because they
38 support a variable numbers of arguments they don't work
39 correctly when passed directly to higher-order functions that
40 pass "bonus" arguments such as Array.prototype.reduce.
42 These functions work on any objects comparable with < and >,
43 and only consider two arguments.
45 function min (a
, b
) { return b
< a
? b
: a
; }
46 function max (a
, b
) { return b
> a
? b
: a
; }
47 function clamp(x
, lo
, hi
) { return max(lo
, min(hi
, x
)); }
49 /** Get a property from the this object by name */
50 function getter (key
) { return this[key
]; }
52 /** Set a property value on the this object by name */
53 function setter (key
, value
) { this[key
] = value
; }
56 /** Factor out the special 'this' argument from a function
58 unbind(f)(a, b, c) is equivalent to f.call(a, b, c), and
59 you may store the return value for later use without
60 storing the original function.
63 // return f.call.bind(f) is ~15% slower than this closure on
64 // Chrome 31 and negligibly slower on Firefox 25.
66 return f
.call
.apply(f
, arguments
);
70 /** Unbound versions of useful functions */
71 var slice
= unbind(Array
.prototype.slice
);
73 function contains (seq
, o
) {
74 return Array
.prototype.indexOf
.call(seq
, o
) !== -1;
77 function lacks (seq
, o
) {
78 return !contains(seq
, o
);
81 /** The first element of a sequence */
82 function head (a
) { return a
[0]; }
84 /** All but the first element of a sequence */
85 function tail (a
) { return slice(a
, 1); }
87 /** The last element of a sequence */
88 function last (a
) { return a
[a
.length
- 1]; }
90 /** All but the last element of a sequence */
91 function most (a
) { return slice(a
, 0, -1); }
93 /** The length of a sequence */
94 function len (seq
) { return seq
.length
; }
96 /** Note that yf's argument order is slightly different from
97 JavaScript's normal order (but the same as most other
98 languages with functional elements).
100 This is irrelevant for `fold` and `filter`, but `each` and
101 `map` can take multiple sequences to allow callback functions
102 with arbitrary arity.
104 Because of this difference, there is no final `thisArg` as in
105 e.g. the standard Array's forEach. Instead the `this` of
106 the original call is forwarded. For example,
107 someArray.forEach(callback, thisArg)
109 yf.each.call(thisArg, callback, someArray)
112 function foldl (callback
, seq
, value
) {
113 /** Like Array's reduce, but with no extra arguments
115 This traverses the sequence in indexed order, low-to-high,
116 and calls the provided function with the accumulated value
117 and the sequence item.
120 if (arguments
.length
=== 2)
122 for (; i
< seq
.length
; ++i
)
123 value
= callback
.call(this, value
, seq
[i
]);
127 function foldr (callback
, seq
, value
) {
128 /** Like foldl, but reversed.
130 This traverses the sequence in indexed order, high-to-low,
131 and calls the provided function with the sequence item and
132 the accumulated value.
134 var i
= seq
.length
- 1;
135 if (arguments
.length
=== 2)
138 value
= callback
.call(this, seq
[i
], value
);
142 function call (f
, x
) { return f
.call(this, x
); }
144 function compose () {
145 /** Create a function by composing multiple functions
147 compose(f, g, h)(x, y, z) is equivalent to f(g(h(x, y, z))).
149 var inner
= last(arguments
);
150 var funcs
= most(arguments
);
152 return foldr
.call(this, call
, funcs
, inner
.apply(this, arguments
));
156 // Generating specialized functions for plucking the nth argument
157 // and passing it to a callback is 100-120x faster than the
158 // generic one in V8.
160 // So generate specialized functions for small argc, and only
161 // resort to the generic approach when there's many sequences.
164 /* jshint -W054*/ /* Function constructor is a form of eval */
165 for (var args
= []; args
.length
< 32;
166 args
.push(", seqs[" + args
.length
+ "][i]"))
167 CALLS
[args
.length
] = new Function(
168 "callback", "i", "seqs",
169 "return callback.call(this" + args
.join("") + ");");
171 function lookup (prop
) {
172 /** Return a function that gets a particular property */
174 // Building this as a closure is ~2-5x faster than writing
175 // a function lookup(prop, o) and binding it.
176 return function (s
) { return s
[prop
]; };
179 function callx (callback
, i
, seqs
) {
180 return callback
.apply(this, seqs
.map(lookup(i
)));
183 function calln (argc
) {
184 return CALLS
[argc
] || callx
;
188 /** Provide a variadic-like version of f
190 Arguments passed to the function including and after the
191 final named one are collected and passed as a single
192 sequence (not necessarily Array) value.
194 var length
= f
.length
;
196 case 0: throw new Error("don't use argv for 0-ary functions");
197 case 1: return function () { return f
.call(this, arguments
); };
200 /* The following code can do this without creating a
201 new array, but it causes function calls to randomly
202 not happen in Safari (Mobile and OS X) - presumably
203 due to some JIT bug, because surrounding it in
204 an empty try/catch block also makes it work.
206 arguments[length - 1] = slice(arguments, length - 1);
208 var args
= slice(arguments
, 0, length
- 1);
209 args
.push(slice(arguments
, length
- 1));
210 return f
.apply(this, args
);
215 var each
= argv(function (callback
, seqs
) {
216 /** Call a function on the given sequences' elements
218 If one sequence is longer than the others, `undefined`
219 will be passed for that sequence's argument.
221 For example, each(f, [a, b, c], [x, y]) is equivalent to
226 If you want to pass a thisArg to the callback, use
227 each.call(thisArg, callback, ...).
229 var length
= Math
.max
.apply(Math
, seqs
.map(len
));
230 var fn
= calln(seqs
.length
);
231 for (var i
= 0; i
< length
; ++i
)
232 fn
.call(this, callback
, i
, seqs
);
235 var eachr
= argv(function (callback
, seqs
) {
236 /** Call a function on the given sequences' elements, backwards
238 If one sequence is longer than the others, `undefined` will be
239 passed for that sequence's argument.
241 For example, each(f, [a, b, c], [x, y]) is equivalent to
246 If you want to pass a thisArg to the callback, use
247 eachr.call(thisArg, callback, ...).
249 var length
= Math
.max
.apply(Math
, seqs
.map(len
));
250 var fn
= calln(seqs
.length
);
251 for (var i
= length
- 1; i
>= 0; --i
)
252 fn
.call(this, callback
, i
, seqs
);
255 function pusher (a
) {
256 // Ridiculously faster than a.push.bind(a). :(
257 return function (o
) { a
.push(o
); };
261 /** Build an array by applying a function to sequences
263 Similar to Array.prototype.map, but allows passing multiple
264 sequences to call functions of any arity, as with each.
266 If you want to pass a thisArg to the callback, use
267 map.call(thisArg, callback, ...).
270 arguments
[0] = compose(pusher(a
), arguments
[0]);
271 each
.apply(this, arguments
);
276 /** Build an array by applying a function to sequences backwards
278 As eachr is to each, so mapr is to map.
281 arguments
[0] = compose(pusher(a
), arguments
[0]);
282 eachr
.apply(this, arguments
);
286 function filter (callback
, seq
) {
287 /** Build an array without the elements that fail the predicate
289 Like Array.prototype.filter, but if null is passed for the
290 predicate, any false-y values will be removed.
293 callback
= callback
|| I
;
294 function _ (o
) { if (callback
.call(this, o
)) a
.push(o
); }
295 each
.call(this, _
, seq
);
299 function packed (f
) {
300 /** Pack arguments to a function into an Array
302 packed(f)([a, b, c]) is equivalent to f(a, b, c).
304 return function (args
) { return f
.apply(this, args
); };
308 /** Create a function that dispatches based on argument count
310 Pass a list of functions with varying argument lengths, e.g.
311 var f = argcd(function () { ... },
312 function (a, b) { ... },
313 function (a, b, c) { ... });
315 This can be used for function overloading, clearer
316 defaults for positional parameters, or significantly more
319 The functions can also be accessed directly by their
320 argument count, e.g. f[0], f[2], f[3] above.
322 If no matching argument count is found for a call, a
325 if (arguments
.length
=== 1)
326 throw new Error("don't use argcd for one function");
327 var table
= (function table () {
328 return table
[arguments
.length
].apply(this, arguments
);
330 for (var i
= 0; i
< arguments
.length
; ++i
)
331 table
[arguments
[i
].length
] = arguments
[i
];
336 /** Call the provided callback counting as it goes
338 irange(x) counts from [0, x), by 1.
340 irange(x, y) counts from [x, y), by 1.
342 irange(x, y, s) counts from [x, y), by s.
344 function (callback
, stop
) {
345 return irange
.call(this, callback
, 0, stop
, 1);
347 function (callback
, start
, stop
) {
348 return irange
.call(this, callback
, start
, stop
, 1);
350 function (callback
, start
, stop
, step
) {
351 var length
= Math
.max(Math
.ceil((stop
- start
) / step
), 0);
352 for (var i
= 0; i
< length
; ++i
)
353 callback
.call(this, start
+ step
* i
);
357 function capture1 (ifunc
) {
358 /** Build an array from the values of an iterating function
360 The elements added to the array are the first arguments
361 the iterating function passes.
365 var args
= slice(arguments
);
366 args
.unshift(pusher(a
));
367 ifunc
.apply(this, args
);
372 /** Generate an Array from range of numbers, as irange */
373 var range
= capture1(irange
);
375 function ipairs (callback
, o
) {
376 /** Call the provided callback with each key and value of the object */
377 each
.call(this, function (k
) { callback
.call(this, k
, o
[k
]); },
381 function iprototypeChain (callback
, o
) {
382 /** Traverse an object and its prototype chain */
384 callback
.call(this, o
);
385 } while ((o
= Object
.getPrototypeOf(o
)));
388 function allKeys (o
) {
389 /** Get *ALL* property names. Even unowned non-enumerable ones. */
391 iprototypeChain(compose(packed(props
.push
).bind(props
),
392 Object
.getOwnPropertyNames
),
394 return props
.sort().filter(function (p
, i
, a
) {
395 return p
!== a
[i
- 1];
399 var some
= argv(function (callback
, seqs
) {
400 callback
= callback
|| I
;
401 var length
= Math
.max
.apply(Math
, seqs
.map(len
));
402 var fn
= calln(seqs
.length
);
403 for (var i
= 0; i
< length
; ++i
)
404 if (fn
.call(this, callback
, i
, seqs
))
409 var eachrUntil
= argv(function (callback
, seqs
) { // Reverse of `some`
410 callback
= callback
|| I
;
411 var length
= Math
.max
.apply(Math
, seqs
.map(len
));
412 var fn
= calln(seqs
.length
);
413 for (var i
= length
- 1; i
>= 0; --i
)
414 if (fn
.call(this, callback
, i
, seqs
))
420 /** Build a function equivalent to !f(...) */
421 return function () { return !f
.apply(this, arguments
); };
425 arguments
[0] = not(arguments
[0] || I
);
426 return !some
.apply(this, arguments
);
430 return !some
.apply(this, arguments
);
433 function repeat (o
, n
) {
434 return (new Array(n
)).fill(o
);
437 function arrayify (o
) {
438 /** Equivalent to [].concat(o) but faster */
439 return Array
.isArray(o
) ? o
: [o
];
442 function stash (key
, value
, a
) {
443 each(function (o
) { o
[key
] = value
; }, a
);
446 function without (seq
, o
) {
447 if (arguments
.length
=== 2)
448 return filter(function (a
) { return a
!== o
; }, seq
);
449 var os
= slice(arguments
, 1);
450 return filter(lacks
.bind(null, os
), seq
);
453 function construct (ctr
, args
) {
456 return new (Function
.prototype.bind
.apply(ctr
, args
))();
459 function new_ (ctr
) {
460 return function () { return construct(ctr
, arguments
); };
463 function counter (start
) {
464 var i
= +(start
|| 0);
465 return function () { return i
++; };
468 function volatile (f
) {
469 return { valueOf
: f
};
472 function transform (callback
, seq
) {
473 irange
.call(this, function (i
) {
474 seq
[i
] = callback
.call(this, seq
[i
]);
478 function mapValues (callback
, o
) {
481 r
[k
] = callback
.call(this, o
[k
]);
485 function insertBefore (seq
, o
, before
) {
486 var idx
= seq
.lastIndexOf(before
);
490 seq
.splice(idx
, 0, o
);
494 function seqEqual (a
, b
) {
495 if (a
.length
!== b
.length
)
497 for (var i
= 0; i
< a
.length
; ++i
)
503 function debounce (callback
, wait
) {
510 callback
.apply(this_
, args
);
517 if (id
!== null && this_
!== this)
522 id
= setTimeout(_
, wait
);
526 function pluck (prop
, seq
) {
527 return map(lookup(prop
), seq
);
530 Object
.assign(this, {
537 construct
: construct
,
544 eachrUntil
: eachrUntil
,
552 insertBefore
: insertBefore
,
555 isFunction
: isFunction
,
564 mapValues
: mapValues
,
579 transform
: transform
,
587 }).call(typeof exports
!== "undefined" ? exports
: (this.yf
= {}));