yui-object.js revision 91ff24e65531ce8bf171340d9384182f8c168af3
c4e6d94ea429e473a6732b6eb5e0fc980e822881Adam Moore(function() {
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Adds the following Object utilities to the YUI instance
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @class YUI~object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Y.Object(o) returns a new object based upon the supplied object.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @TODO Use native Object.create() when available
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o the supplier object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam 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,
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) {
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns an array containing the object's keys
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @TODO use native Object.keys() if available
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @method Object.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
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @method Object.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
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @method Object.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
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @method Object.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 MooreO.hasKey = function(o, k) {
87b084086b5937585acc7e091b2f1951e94d9145Adam Moore // return (o.hasOwnProperty(k));
87b084086b5937585acc7e091b2f1951e94d9145Adam Moore return (k in o);
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * Returns true if the object contains a given value
d4dbc3afb5bb9cfd13490b358dc37bf951104ca7Adam Moore * @method Object.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.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @deprecated Safari 1.x support has been removed, so this is simply a
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * wrapper for the native implementation. Use the native implementation
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * directly instead.
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @TODO Remove in B1
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Object.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
91ff24e65531ce8bf171340d9384182f8c168af3Adam MooreO.owns = function(o, k) {
91ff24e65531ce8bf171340d9384182f8c168af3Adam Moore return (o.hasOwnProperty(k));
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * Executes a function on each item. The function
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * receives the value, the key, and the object
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * as paramters (in that order).
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @method Object.each
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param o the object to iterate
1b298c6f0ef597aa4ab0b8bcb25430b6c9a87749Adam Moore * @param f {function} the function to execute
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);
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.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @return {Any} The value stored in the path, undefined if not found.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * Returns the source object if an empty path is provided.
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.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore var p=Y.Array(path), leafIdx=p.length-1, i, ref=o;
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore for (i=0; ref !== undefined && i < leafIdx; i=i+1) {