yui-object.js revision 458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * The YUI module contains the components required for building the YUI
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * seed file. This includes the script loading mechanism, a simple queue,
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * and the core utilities for the library.
4778ff543a041ac356d6e661cc9b66c3fafa2092Adam Moore * @module yui
2c5ce90c334a2d0f18474e85c93b424b6ec9daaaAdam Moore * @submodule yui-base
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Adds the following Object utilities to the YUI instance
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @class Object
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * Y.Object(o) returns a new object based upon the supplied object.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method ()
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o the supplier object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {Object} the new object.
173310d032abe522e8645dd148cc28591cd128eaAdam Moorevar F = function() {},
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// O = Object.create || function(o) {
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// F.prototype = o;
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// return new F();
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam MooreO = function(o) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore return new F();
16bec62f211cecacdbbc2cb4632f079ef8c7f936Adam Mooreowns = function(o, k) {
c7eb563867fa29409073f3b495a067d9afa00006Adam Moore return o && o.hasOwnProperty && o.hasOwnProperty(k);
c74cf2305e301535acc8a5d42be60e93dcbd97daAdam Moore // return Object.prototype.hasOwnProperty.call(o, k);
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore * Extracts the keys, values, or size from an object
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore * @method _extract
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o the object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param what what to extract (0: keys, 1: values, 2: size).
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean|Array} the extracted info.
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore var count = (what === 2), out = (count) ? 0 : [], i;
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore for (i in o) {
489c0c8e2523f1bcd1acee1173c6d85f6a7edd6aAdam Moore if (owns(o, i)) {
173310d032abe522e8645dd148cc28591cd128eaAdam MooreY.Object = O;
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns an array containing the object's keys
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method keys
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o an object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {string[]} the keys.
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// O.keys = Object.keys || function(o) {
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// return _extract(o);
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam MooreO.keys = function(o) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns an array containing the object's values
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method values
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o an object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {Array} the values.
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// O.values = Object.values || function(o) {
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam Moore// return _extract(o, 1);
458ca79ae0e4fa1eb1a2a3c6f67401a191d025e4Adam MooreO.values = function(o) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns the size of an object
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method size
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o an object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {int} the size.
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns true if the object contains a given key
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method hasKey
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o an object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param k the key to query.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean} true if the object contains the key.
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns true if the object contains a given value
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method hasValue
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o an object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param v the value to query.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean} true if the object contains the value.
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam MooreO.hasValue = function(o, v) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Determines whether or not the property was added
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * to the object instance. Returns false if the property is not present
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * in the object, or was inherited from the prototype.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method owns
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o {any} The object being testing.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param p {string} the property to look for.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean} true if the object has the property on the instance.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Executes a function on each item. The function
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * receives the value, the key, and the object
2e3359c809b56e9d1c663465eaf85d1a4c03bf4cAdam Moore * as parameters (in that order).
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method each
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o the object to iterate.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param f {Function} the function to execute on each item. The function
efa57736d44cf446f1661497a8645bd388b493fbAdam Moore * receives three arguments: the value, the the key, the full object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param c the execution context.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param proto {boolean} include proto.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {YUI} the YUI instance.
ba2701ee03e94104edf19911ee0989f8cee11088Adam Moore var s = c || Y, i;
ba2701ee03e94104edf19911ee0989f8cee11088Adam Moore for (i in o) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore f.call(s, o[i], i, o);
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * Executes a function on each item, but halts if the
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * function returns true. The function
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * receives the value, the key, and the object
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * as paramters (in that order).
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @method some
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o the object to iterate.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param f {Function} the function to execute on each item. The function
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * receives three arguments: the value, the the key, the full object.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param c the execution context.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param proto {boolean} include proto.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean} true if any execution of the function returns true,
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * false otherwise.
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore var s = c || Y, i;
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore for (i in o) {
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore if (f.call(s, o[i], i, o)) {
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore return true;
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore return false;
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * Retrieves the sub value at the provided path,
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * from the value object provided.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @method getValue
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o The object from which to extract the property value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param path {Array} A path array, specifying the object traversal path
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * from which to obtain the sub value.
0dca577a07715960da42d47787eecc25b285182fAdam Moore * @return {Any} The value stored in the path, undefined if not found,
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * undefined if the source is not an object. Returns the source object
0dca577a07715960da42d47787eecc25b285182fAdam Moore * if an empty path is provided.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore p = Y.Array(path),
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore o = o[p[i]];
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * Sets the sub-attribute value at the provided path on the
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * value object. Returns the modified value object, or
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * undefined if the path is invalid.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @method setValue
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param o The object on which to set the sub value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param path {Array} A path array, specifying the object traversal path
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * at which to set the sub value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param val {Any} The new value for the sub-attribute.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {Object} The modified object, with the new sub value set, or
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * undefined, if the path was invalid.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore p = Y.Array(path),
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * Returns true if the object has no properties of its own
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * @method isEmpty
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {boolean} true if the object is empty.
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * @since 3.2.0
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam MooreO.isEmpty = function(o) {
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore for (var i in o) {
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore if (owns(o, i)) {
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore return false;
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore return true;