yui-object.js revision 8c3fae1cf2a8dfa82c53922a6f99ab7b991b959c
4778ff543a041ac356d6e661cc9b66c3fafa2092Adam Moore * The YUI module contains the components required for building the YUI seed file.
2c5ce90c334a2d0f18474e85c93b424b6ec9daaaAdam Moore * This includes the script loading mechanism, a simple queue, and the core utilities for the library.
4778ff543a041ac356d6e661cc9b66c3fafa2092Adam Moore * @module yui
2c5ce90c334a2d0f18474e85c93b424b6ec9daaaAdam Moore * @submodule yui-base
c4e6d94ea429e473a6732b6eb5e0fc980e822881Adam Moore(function() {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Adds the following Object utilities to the YUI instance
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @class Object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Y.Object(o) returns a new object based upon the supplied object.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @TODO Use native Object.create() when available
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method ()
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o the supplier object
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @return {Object} the new object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam MooreY.Object = function(o) {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore var F = function() {};
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore return new F();
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moorevar O = Y.Object,
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
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore * @param o the object
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore * @param what what to extract (0: keys, 1: values, 2: size)
91ff24e65531ce8bf171340d9384182f8c168af3Adam 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)) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns an array containing the object's keys
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @TODO use native Object.keys() if available
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method keys
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param o an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @return {string[]} the keys
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam MooreO.keys = function(o) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns an array containing the object's values
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @TODO use native Object.values() if available
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method values
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param o an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @return {Array} the values
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam MooreO.values = function(o) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns the size of an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @TODO use native Object.size() if available
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method size
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param o an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @return {int} the size
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam MooreO.size = function(o) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns true if the object contains a given key
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method hasKey
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param o an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param k the key to query
87b084086b5937585acc7e091b2f1951e94d9145Adam 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
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param o an object
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @param v the value to query
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam 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
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o {any} The object being testing
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param p {string} the property to look for
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam 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
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o the object to iterate
efa57736d44cf446f1661497a8645bd388b493fbAdam 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.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param c the execution context
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param proto {boolean} include proto
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam 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
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @param o the object to iterate
23209f57fce338501bc1dc828a991d103732b92fAdam 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.
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @param c the execution context
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @param proto {boolean} include proto
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @return {boolean} true if any execution of the function returns true, 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
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam 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,
0dca577a07715960da42d47787eecc25b285182fAdam Moore * undefined if the source is not an object. Returns the source object
0dca577a07715960da42d47787eecc25b285182fAdam Moore * if an empty path is provided.
b9f576e4a859f38cf945d867cf23fdbb84347564Adam Moore p = Y.Array(path),
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore o = o[p[i]];
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * Sets the sub-attribute value at the provided path on the
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam 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.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @return {Object} The modified object, with the new sub value set, or
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * undefined, if the path was invalid.
b9f576e4a859f38cf945d867cf23fdbb84347564Adam Moore p = Y.Array(path),
b9f576e4a859f38cf945d867cf23fdbb84347564Adam Moore for (i=0; ref !== UNDEFINED && i < leafIdx; i++) {
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * Returns true if the object has no properties of its own
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * @method isEmpty
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam 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;