# Yahoo! UI Library

### yui 3.3.0

Yahoo! UI Library > yui > yui-lang.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
     */

    /**
     * Provides the language utilites and extensions used by the library
     * @class Lang
     * @static
     */
    Y.Lang = Y.Lang || {};

    var L = Y.Lang,

    ARRAY = 'array',
    BOOLEAN = 'boolean',
    DATE = 'date',
    ERROR = 'error',
    FUNCTION = 'function',
    NUMBER = 'number',
    NULL = 'null',
    OBJECT = 'object',
    REGEX = 'regexp',
    STRING = 'string',
    STRING_PROTO = String.prototype,
    TOSTRING = Object.prototype.toString,
    UNDEFINED = 'undefined',

    TYPES = {
        'undefined' : UNDEFINED,
        'number' : NUMBER,
        'boolean' : BOOLEAN,
        'string' : STRING,
        '[object Function]' : FUNCTION,
        '[object RegExp]' : REGEX,
        '[object Array]' : ARRAY,
        '[object Date]' : DATE,
        '[object Error]' : ERROR
    },

    TRIMREGEX = /^\s+|\s+$/g,
    EMPTYSTRING = '',
    SUBREGEX = /\{\s*([^\|\}]+?)\s*(?:\|([^\}]*))?\s*\}/g;

    /**
     * Determines whether or not the provided item is an array.
     * Returns false for array-like collections such as the
     * function arguments collection or HTMLElement collection
     * will return false.  Use <code>Y.Array.test</code> if you
     * want to test for an array-like collection.
     * @method isArray
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is an array.
     */
    // L.isArray = Array.isArray || function(o) {
    //     return L.type(o) === ARRAY;
    // };

    L.isArray = function(o) {
        return L.type(o) === ARRAY;
    };

    /**
     * Determines whether or not the provided item is a boolean.
     * @method isBoolean
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is a boolean.
     */
    L.isBoolean = function(o) {
        return typeof o === BOOLEAN;
    };

    /**
     * <p>
     * Determines whether or not the provided item is a function.
     * Note: Internet Explorer thinks certain functions are objects:
     * </p>
     *
     * <pre>
     * var obj = document.createElement("object");
     * Y.Lang.isFunction(obj.getAttribute) // reports false in IE
     * &nbsp;
     * var input = document.createElement("input"); // append to body
     * Y.Lang.isFunction(input.focus) // reports false in IE
     * </pre>
     *
     * <p>
     * You will have to implement additional tests if these functions
     * matter to you.
     * </p>
     *
     * @method isFunction
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is a function.
     */
    L.isFunction = function(o) {
        return L.type(o) === FUNCTION;
    };

    /**
     * Determines whether or not the supplied item is a date instance.
     * @method isDate
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is a date.
     */
    L.isDate = function(o) {
        // return o instanceof Date;
        return L.type(o) === DATE && o.toString() !== 'Invalid Date' && !isNaN(o);
    };

    /**
     * Determines whether or not the provided item is null.
     * @method isNull
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is null.
     */
    L.isNull = function(o) {
        return o === null;
    };

    /**
     * Determines whether or not the provided item is a legal number.
     * @method isNumber
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is a number.
     */
    L.isNumber = function(o) {
        return typeof o === NUMBER && isFinite(o);
    };

    /**
     * Determines whether or not the provided item is of type object
     * or function. Note that arrays are also objects, so
     * <code>Y.Lang.isObject([]) === true</code>.
     * @method isObject
     * @static
     * @param o The object to test.
     * @param failfn {boolean} fail if the input is a function.
     * @return {boolean} true if o is an object.
     */
    L.isObject = function(o, failfn) {
        var t = typeof o;
        return (o && (t === OBJECT ||
            (!failfn && (t === FUNCTION || L.isFunction(o))))) || false;
    };

    /**
     * Determines whether or not the provided item is a string.
     * @method isString
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is a string.
     */
    L.isString = function(o) {
        return typeof o === STRING;
    };

    /**
     * Determines whether or not the provided item is undefined.
     * @method isUndefined
     * @static
     * @param o The object to test.
     * @return {boolean} true if o is undefined.
     */
    L.isUndefined = function(o) {
        return typeof o === UNDEFINED;
    };

    /**
     * Returns a string without any leading or trailing whitespace.  If
     * the input is not a string, the input will be returned untouched.
     * @method trim
     * @static
     * @param s {string} the string to trim.
     * @return {string} the trimmed string.
     */
    L.trim = STRING_PROTO.trim ? function(s) {
        return (s && s.trim) ? s.trim() : s;
    } : function (s) {
        try {
            return s.replace(TRIMREGEX, EMPTYSTRING);
        } catch (e) {
            return s;
        }
    };

    /**
     * Returns a string without any leading whitespace.
     * @method trimLeft
     * @static
     * @param s {string} the string to trim.
     * @return {string} the trimmed string.
     */
    L.trimLeft = STRING_PROTO.trimLeft ? function (s) {
        return s.trimLeft();
    } : function (s) {
        return s.replace(/^\s+/, '');
    };

    /**
     * Returns a string without any trailing whitespace.
     * @method trimRight
     * @static
     * @param s {string} the string to trim.
     * @return {string} the trimmed string.
     */
    L.trimRight = STRING_PROTO.trimRight ? function (s) {
        return s.trimRight();
    } : function (s) {
        return s.replace(/\s+$/, '');
    };

    /**
     * A convenience method for detecting a legitimate non-null value.
     * Returns false for null/undefined/NaN, true for other values,
     * including 0/false/''
     * @method isValue
     * @static
     * @param o The item to test.
     * @return {boolean} true if it is not null/undefined/NaN || false.
     */
    L.isValue = function(o) {
        var t = L.type(o);
        switch (t) {
            case NUMBER:
                return isFinite(o);
            case NULL:
            case UNDEFINED:
                return false;
            default:
                return !!(t);
        }
    };

    /**
     * <p>
     * Returns a string representing the type of the item passed in.
     * </p>
     *
     * <p>
     * Known issues:
     * </p>
     *
     * <ul>
     *   <li>
     *     <code>typeof HTMLElementCollection</code> returns function in Safari, but
     *     <code>Y.type()</code> reports object, which could be a good thing --
     *     but it actually caused the logic in <code>Y.Lang.isObject</code> to fail.
     *   </li>
     * </ul>
     *
     * @method type
     * @param o the item to test.
     * @return {string} the detected type.
     * @static
     */
    L.type = function(o) {
        return TYPES[typeof o] || TYPES[TOSTRING.call(o)] || (o ? OBJECT : NULL);
    };

    /**
     * Lightweight version of <code>Y.substitute</code>. Uses the same template
     * structure as <code>Y.substitute</code>, but doesn't support recursion,
     * auto-object coersion, or formats.
     * @method sub
     * @param {string} s String to be modified.
     * @param {object} o Object containing replacement values.
     * @return {string} the substitute result.
     * @static
     * @since 3.2.0
     */
    L.sub = function(s, o) {
        return ((s.replace) ? s.replace(SUBREGEX, function(match, key) {
            return (!L.isUndefined(o[key])) ? o[key] : match;
        }) : s);
    };

    /**
     * Returns the current time in milliseconds.
     * @method now
     * @return {int} the current date
     * @since 3.3.0
     */
    L.now = Date.now || function () {
      return new Date().getTime();
    };

Copyright © 2011 Yahoo! Inc. All rights reserved.