# Yahoo! UI Library

### yui 3.3.0

Yahoo! UI Library > yui > yui-object.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

    /**
     * The YUI module contains the components required for building the YUI
     * seed file.  This includes the script loading mechanism, a simple queue,
     * and the core utilities for the library.
     * @module yui
     * @submodule yui-base
     */

    /**
     * Adds the following Object utilities to the YUI instance
     * @class Object
     */

    /**
     * Y.Object(o) returns a new object based upon the supplied object.
     * @method ()
     * @static
     * @param o the supplier object.
     * @return {Object} the new object.
     */
    var F = function() {},

    // O = Object.create || function(o) {
    //     F.prototype = o;
    //     return new F();
    // },

    O = function(o) {
        F.prototype = o;
        return new F();
    },

    owns = function(o, k) {
        return o && o.hasOwnProperty && o.hasOwnProperty(k);
        // return Object.prototype.hasOwnProperty.call(o, k);
    },

    UNDEF,

    /**
     * Extracts the keys, values, or size from an object
     *
     * @method _extract
     * @param o the object.
     * @param what what to extract (0: keys, 1: values, 2: size).
     * @return {boolean|Array} the extracted info.
     * @static
     * @private
     */
    _extract = function(o, what) {
        var count = (what === 2), out = (count) ? 0 : [], i;

        for (i in o) {
            if (owns(o, i)) {
                if (count) {
                    out++;
                } else {
                    out.push((what) ? o[i] : i);
                }
            }
        }

        return out;
    };

    Y.Object = O;

    /**
     * Returns an array containing the object's keys
     * @method keys
     * @static
     * @param o an object.
     * @return {string[]} the keys.
     */
    // O.keys = Object.keys || function(o) {
    //     return _extract(o);
    // };

    O.keys = function(o) {
        return _extract(o);
    };

    /**
     * Returns an array containing the object's values
     * @method values
     * @static
     * @param o an object.
     * @return {Array} the values.
     */
    // O.values = Object.values || function(o) {
    //     return _extract(o, 1);
    // };

    O.values = function(o) {
        return _extract(o, 1);
    };

    /**
     * Returns the size of an object
     * @method size
     * @static
     * @param o an object.
     * @return {int} the size.
     */
    O.size = Object.size || function(o) {
        return _extract(o, 2);
    };

    /**
     * Returns true if the object contains a given key
     * @method hasKey
     * @static
     * @param o an object.
     * @param k the key to query.
     * @return {boolean} true if the object contains the key.
     */
    O.hasKey = owns;
    /**
     * Returns true if the object contains a given value
     * @method hasValue
     * @static
     * @param o an object.
     * @param v the value to query.
     * @return {boolean} true if the object contains the value.
     */
    O.hasValue = function(o, v) {
        return (Y.Array.indexOf(O.values(o), v) > -1);
    };

    /**
     * Determines whether or not the property was added
     * to the object instance.  Returns false if the property is not present
     * in the object, or was inherited from the prototype.
     *
     * @method owns
     * @static
     * @param o {any} The object being testing.
     * @param p {string} the property to look for.
     * @return {boolean} true if the object has the property on the instance.
     */
    O.owns = owns;

    /**
     * Executes a function on each item. The function
     * receives the value, the key, and the object
     * as parameters (in that order).
     * @method each
     * @static
     * @param o the object to iterate.
     * @param f {Function} the function to execute on each item. The function
     * receives three arguments: the value, the the key, the full object.
     * @param c the execution context.
     * @param proto {boolean} include proto.
     * @return {YUI} the YUI instance.
     */
    O.each = function(o, f, c, proto) {
        var s = c || Y, i;

        for (i in o) {
            if (proto || owns(o, i)) {
                f.call(s, o[i], i, o);
            }
        }
        return Y;
    };

    /**
     * Executes a function on each item, but halts if the
     * function returns true.  The function
     * receives the value, the key, and the object
     * as paramters (in that order).
     * @method some
     * @static
     * @param o the object to iterate.
     * @param f {Function} the function to execute on each item. The function
     * receives three arguments: the value, the the key, the full object.
     * @param c the execution context.
     * @param proto {boolean} include proto.
     * @return {boolean} true if any execution of the function returns true,
     * false otherwise.
     */
    O.some = function(o, f, c, proto) {
        var s = c || Y, i;

        for (i in o) {
            if (proto || owns(o, i)) {
                if (f.call(s, o[i], i, o)) {
                    return true;
                }
            }
        }
        return false;
    };

    /**
     * Retrieves the sub value at the provided path,
     * from the value object provided.
     *
     * @method getValue
     * @static
     * @param o The object from which to extract the property value.
     * @param path {Array} A path array, specifying the object traversal path
     * from which to obtain the sub value.
     * @return {Any} The value stored in the path, undefined if not found,
     * undefined if the source is not an object.  Returns the source object
     * if an empty path is provided.
     */
    O.getValue = function(o, path) {
        if (!Y.Lang.isObject(o)) {
            return UNDEF;
        }

        var i,
            p = Y.Array(path),
            l = p.length;

        for (i = 0; o !== UNDEF && i < l; i++) {
            o = o[p[i]];
        }

        return o;
    };

    /**
     * Sets the sub-attribute value at the provided path on the
     * value object.  Returns the modified value object, or
     * undefined if the path is invalid.
     *
     * @method setValue
     * @static
     * @param o             The object on which to set the sub value.
     * @param path {Array}  A path array, specifying the object traversal path
     *                      at which to set the sub value.
     * @param val {Any}     The new value for the sub-attribute.
     * @return {Object}     The modified object, with the new sub value set, or
     *                      undefined, if the path was invalid.
     */
    O.setValue = function(o, path, val) {
        var i,
            p = Y.Array(path),
            leafIdx = p.length - 1,
            ref = o;

        if (leafIdx >= 0) {
            for (i = 0; ref !== UNDEF && i < leafIdx; i++) {
                ref = ref[p[i]];
            }

            if (ref !== UNDEF) {
                ref[p[i]] = val;
            } else {
                return UNDEF;
            }
        }

        return o;
    };

    /**
     * Returns true if the object has no properties of its own
     * @method isEmpty
     * @static
     * @return {boolean} true if the object is empty.
     * @since 3.2.0
     */
    O.isEmpty = function(o) {
        for (var i in o) {
            if (owns(o, i)) {
                return false;
            }
        }
        return true;
    };

Copyright © 2011 Yahoo! Inc. All rights reserved.