yui-object.js revision e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002a
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,
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
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 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
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.
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
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
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).
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.
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;
9fb523cf517ad4d6a53ae9f461d672cba63835d2Adam Moore for (i=0; ref !== UNDEFINED && i < leafIdx; i=i+1) {