355 lines
11 KiB
JavaScript
355 lines
11 KiB
JavaScript
|
// Copyright 2006 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 Generics method for collection-like classes and objects.
|
||
|
|
*
|
||
|
|
* @author arv@google.com (Erik Arvidsson)
|
||
|
|
*
|
||
|
|
* This file contains functions to work with collections. It supports using
|
||
|
|
* Map, Set, Array and Object and other classes that implement collection-like
|
||
|
|
* methods.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
goog.provide('goog.structs');
|
||
|
|
|
||
|
|
goog.require('goog.array');
|
||
|
|
goog.require('goog.object');
|
||
|
|
|
||
|
|
|
||
|
|
// We treat an object as a dictionary if it has getKeys or it is an object that
|
||
|
|
// isn't arrayLike.
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the number of values in the collection-like object.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
* @return {number} The number of values in the collection-like object.
|
||
|
|
*/
|
||
|
|
goog.structs.getCount = function(col) {
|
||
|
|
if (col.getCount && typeof col.getCount == 'function') {
|
||
|
|
return col.getCount();
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return col.length;
|
||
|
|
}
|
||
|
|
return goog.object.getCount(col);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the values of the collection-like object.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
* @return {!Array<?>} The values in the collection-like object.
|
||
|
|
*/
|
||
|
|
goog.structs.getValues = function(col) {
|
||
|
|
if (col.getValues && typeof col.getValues == 'function') {
|
||
|
|
return col.getValues();
|
||
|
|
}
|
||
|
|
if (goog.isString(col)) {
|
||
|
|
return col.split('');
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col)) {
|
||
|
|
var rv = [];
|
||
|
|
var l = col.length;
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
rv.push(col[i]);
|
||
|
|
}
|
||
|
|
return rv;
|
||
|
|
}
|
||
|
|
return goog.object.getValues(col);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the keys of the collection. Some collections have no notion of
|
||
|
|
* keys/indexes and this function will return undefined in those cases.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
* @return {!Array|undefined} The keys in the collection.
|
||
|
|
*/
|
||
|
|
goog.structs.getKeys = function(col) {
|
||
|
|
if (col.getKeys && typeof col.getKeys == 'function') {
|
||
|
|
return col.getKeys();
|
||
|
|
}
|
||
|
|
// if we have getValues but no getKeys we know this is a key-less collection
|
||
|
|
if (col.getValues && typeof col.getValues == 'function') {
|
||
|
|
return undefined;
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
var rv = [];
|
||
|
|
var l = col.length;
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
rv.push(i);
|
||
|
|
}
|
||
|
|
return rv;
|
||
|
|
}
|
||
|
|
|
||
|
|
return goog.object.getKeys(col);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Whether the collection contains the given value. This is O(n) and uses
|
||
|
|
* equals (==) to test the existence.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
* @param {*} val The value to check for.
|
||
|
|
* @return {boolean} True if the map contains the value.
|
||
|
|
*/
|
||
|
|
goog.structs.contains = function(col, val) {
|
||
|
|
if (col.contains && typeof col.contains == 'function') {
|
||
|
|
return col.contains(val);
|
||
|
|
}
|
||
|
|
if (col.containsValue && typeof col.containsValue == 'function') {
|
||
|
|
return col.containsValue(val);
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.contains(/** @type {!Array<?>} */ (col), val);
|
||
|
|
}
|
||
|
|
return goog.object.containsValue(col, val);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Whether the collection is empty.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
* @return {boolean} True if empty.
|
||
|
|
*/
|
||
|
|
goog.structs.isEmpty = function(col) {
|
||
|
|
if (col.isEmpty && typeof col.isEmpty == 'function') {
|
||
|
|
return col.isEmpty();
|
||
|
|
}
|
||
|
|
|
||
|
|
// We do not use goog.string.isEmptyOrWhitespace because here we treat the
|
||
|
|
// string as
|
||
|
|
// collection and as such even whitespace matters
|
||
|
|
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.isEmpty(/** @type {!Array<?>} */ (col));
|
||
|
|
}
|
||
|
|
return goog.object.isEmpty(col);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Removes all the elements from the collection.
|
||
|
|
* @param {Object} col The collection-like object.
|
||
|
|
*/
|
||
|
|
goog.structs.clear = function(col) {
|
||
|
|
// NOTE(arv): This should not contain strings because strings are immutable
|
||
|
|
if (col.clear && typeof col.clear == 'function') {
|
||
|
|
col.clear();
|
||
|
|
} else if (goog.isArrayLike(col)) {
|
||
|
|
goog.array.clear(/** @type {IArrayLike<?>} */ (col));
|
||
|
|
} else {
|
||
|
|
goog.object.clear(col);
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Calls a function for each value in a collection. The function takes
|
||
|
|
* three arguments; the value, the key and the collection.
|
||
|
|
*
|
||
|
|
* @param {S} col The collection-like object.
|
||
|
|
* @param {function(this:T,?,?,S):?} f The function to call for every value.
|
||
|
|
* This function takes
|
||
|
|
* 3 arguments (the value, the key or undefined if the collection has no
|
||
|
|
* notion of keys, and the collection) and the return value is irrelevant.
|
||
|
|
* @param {T=} opt_obj The object to be used as the value of 'this'
|
||
|
|
* within {@code f}.
|
||
|
|
* @template T,S
|
||
|
|
* @deprecated Use a more specific method, e.g. goog.array.forEach,
|
||
|
|
* goog.object.forEach, or for-of.
|
||
|
|
*/
|
||
|
|
goog.structs.forEach = function(col, f, opt_obj) {
|
||
|
|
if (col.forEach && typeof col.forEach == 'function') {
|
||
|
|
col.forEach(f, opt_obj);
|
||
|
|
} else if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
goog.array.forEach(/** @type {!Array<?>} */ (col), f, opt_obj);
|
||
|
|
} else {
|
||
|
|
var keys = goog.structs.getKeys(col);
|
||
|
|
var values = goog.structs.getValues(col);
|
||
|
|
var l = values.length;
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
f.call(/** @type {?} */ (opt_obj), values[i], keys && keys[i], col);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Calls a function for every value in the collection. When a call returns true,
|
||
|
|
* adds the value to a new collection (Array is returned by default).
|
||
|
|
*
|
||
|
|
* @param {S} col The collection-like object.
|
||
|
|
* @param {function(this:T,?,?,S):boolean} f The function to call for every
|
||
|
|
* value. This function takes
|
||
|
|
* 3 arguments (the value, the key or undefined if the collection has no
|
||
|
|
* notion of keys, and the collection) and should return a Boolean. If the
|
||
|
|
* return value is true the value is added to the result collection. If it
|
||
|
|
* is false the value is not included.
|
||
|
|
* @param {T=} opt_obj The object to be used as the value of 'this'
|
||
|
|
* within {@code f}.
|
||
|
|
* @return {!Object|!Array<?>} A new collection where the passed values are
|
||
|
|
* present. If col is a key-less collection an array is returned. If col
|
||
|
|
* has keys and values a plain old JS object is returned.
|
||
|
|
* @template T,S
|
||
|
|
*/
|
||
|
|
goog.structs.filter = function(col, f, opt_obj) {
|
||
|
|
if (typeof col.filter == 'function') {
|
||
|
|
return col.filter(f, opt_obj);
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.filter(/** @type {!Array<?>} */ (col), f, opt_obj);
|
||
|
|
}
|
||
|
|
|
||
|
|
var rv;
|
||
|
|
var keys = goog.structs.getKeys(col);
|
||
|
|
var values = goog.structs.getValues(col);
|
||
|
|
var l = values.length;
|
||
|
|
if (keys) {
|
||
|
|
rv = {};
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
if (f.call(/** @type {?} */ (opt_obj), values[i], keys[i], col)) {
|
||
|
|
rv[keys[i]] = values[i];
|
||
|
|
}
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
// We should not use goog.array.filter here since we want to make sure that
|
||
|
|
// the index is undefined as well as make sure that col is passed to the
|
||
|
|
// function.
|
||
|
|
rv = [];
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
if (f.call(opt_obj, values[i], undefined, col)) {
|
||
|
|
rv.push(values[i]);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return rv;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Calls a function for every value in the collection and adds the result into a
|
||
|
|
* new collection (defaults to creating a new Array).
|
||
|
|
*
|
||
|
|
* @param {S} col The collection-like object.
|
||
|
|
* @param {function(this:T,?,?,S):V} f The function to call for every value.
|
||
|
|
* This function takes 3 arguments (the value, the key or undefined if the
|
||
|
|
* collection has no notion of keys, and the collection) and should return
|
||
|
|
* something. The result will be used as the value in the new collection.
|
||
|
|
* @param {T=} opt_obj The object to be used as the value of 'this'
|
||
|
|
* within {@code f}.
|
||
|
|
* @return {!Object<V>|!Array<V>} A new collection with the new values. If
|
||
|
|
* col is a key-less collection an array is returned. If col has keys and
|
||
|
|
* values a plain old JS object is returned.
|
||
|
|
* @template T,S,V
|
||
|
|
*/
|
||
|
|
goog.structs.map = function(col, f, opt_obj) {
|
||
|
|
if (typeof col.map == 'function') {
|
||
|
|
return col.map(f, opt_obj);
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.map(/** @type {!Array<?>} */ (col), f, opt_obj);
|
||
|
|
}
|
||
|
|
|
||
|
|
var rv;
|
||
|
|
var keys = goog.structs.getKeys(col);
|
||
|
|
var values = goog.structs.getValues(col);
|
||
|
|
var l = values.length;
|
||
|
|
if (keys) {
|
||
|
|
rv = {};
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
rv[keys[i]] = f.call(/** @type {?} */ (opt_obj), values[i], keys[i], col);
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
// We should not use goog.array.map here since we want to make sure that
|
||
|
|
// the index is undefined as well as make sure that col is passed to the
|
||
|
|
// function.
|
||
|
|
rv = [];
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
rv[i] = f.call(/** @type {?} */ (opt_obj), values[i], undefined, col);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return rv;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Calls f for each value in a collection. If any call returns true this returns
|
||
|
|
* true (without checking the rest). If all returns false this returns false.
|
||
|
|
*
|
||
|
|
* @param {S} col The collection-like object.
|
||
|
|
* @param {function(this:T,?,?,S):boolean} f The function to call for every
|
||
|
|
* value. This function takes 3 arguments (the value, the key or undefined
|
||
|
|
* if the collection has no notion of keys, and the collection) and should
|
||
|
|
* return a boolean.
|
||
|
|
* @param {T=} opt_obj The object to be used as the value of 'this'
|
||
|
|
* within {@code f}.
|
||
|
|
* @return {boolean} True if any value passes the test.
|
||
|
|
* @template T,S
|
||
|
|
*/
|
||
|
|
goog.structs.some = function(col, f, opt_obj) {
|
||
|
|
if (typeof col.some == 'function') {
|
||
|
|
return col.some(f, opt_obj);
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.some(/** @type {!Array<?>} */ (col), f, opt_obj);
|
||
|
|
}
|
||
|
|
var keys = goog.structs.getKeys(col);
|
||
|
|
var values = goog.structs.getValues(col);
|
||
|
|
var l = values.length;
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
if (f.call(/** @type {?} */ (opt_obj), values[i], keys && keys[i], col)) {
|
||
|
|
return true;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return false;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Calls f for each value in a collection. If all calls return true this return
|
||
|
|
* true this returns true. If any returns false this returns false at this point
|
||
|
|
* and does not continue to check the remaining values.
|
||
|
|
*
|
||
|
|
* @param {S} col The collection-like object.
|
||
|
|
* @param {function(this:T,?,?,S):boolean} f The function to call for every
|
||
|
|
* value. This function takes 3 arguments (the value, the key or
|
||
|
|
* undefined if the collection has no notion of keys, and the collection)
|
||
|
|
* and should return a boolean.
|
||
|
|
* @param {T=} opt_obj The object to be used as the value of 'this'
|
||
|
|
* within {@code f}.
|
||
|
|
* @return {boolean} True if all key-value pairs pass the test.
|
||
|
|
* @template T,S
|
||
|
|
*/
|
||
|
|
goog.structs.every = function(col, f, opt_obj) {
|
||
|
|
if (typeof col.every == 'function') {
|
||
|
|
return col.every(f, opt_obj);
|
||
|
|
}
|
||
|
|
if (goog.isArrayLike(col) || goog.isString(col)) {
|
||
|
|
return goog.array.every(/** @type {!Array<?>} */ (col), f, opt_obj);
|
||
|
|
}
|
||
|
|
var keys = goog.structs.getKeys(col);
|
||
|
|
var values = goog.structs.getValues(col);
|
||
|
|
var l = values.length;
|
||
|
|
for (var i = 0; i < l; i++) {
|
||
|
|
if (!f.call(/** @type {?} */ (opt_obj), values[i], keys && keys[i], col)) {
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
return true;
|
||
|
|
};
|