Class YAHOO.lang
                        
                        
                    
                    
                    
                
  
                    
                        Provides the language utilites and extensions used by the library
                    
                    
                    
                        
                            Properties
                            
                                    
                                    _IEEnumFix
                                        - private static object
                                    
                                    
                                        
                                            IE will not enumerate native functions in a derived object even if the
function was overridden.  This is a workaround for specific functions
we care about on the Object prototype.
                                        
                                     
     
                                        
                                    
                                     
                             
                         
                     
                    
                        
                            Methods
                            
                                    
                                    
                                    
                                        
                                        
                                         static 
                                        
                                        void
                                            augment
                                           (
                                                
                                                        
                                                         r
                                                    
                                                
                                                        , 
                                                         s
                                                    
                                                
                                                        , 
                                                         arguments
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Same as YAHOO.lang.augmentObject, except it only applies prototype
properties.  This is an alias for augmentProto.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        r
                                                        <Function>
                                                        the object to receive the augmentation
- 
                                                        s
                                                        <Function>
                                                        the object that supplies the properties to augment
- 
                                                        arguments
                                                        <String*|boolean>
                                                        zero or more properties methods to
augment the receiver with.  If none specified, everything
in the supplier will be used unless it would
overwrite an existing property in the receiver.  if true
is specified as the third parameter, all properties will
be applied and will overwrite an existing property in
the receiver
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                         static 
                                        
                                        void
                                            augmentObject
                                           (
                                                
                                                        
                                                         r
                                                    
                                                
                                                        , 
                                                         s
                                                    
                                                
                                                        , 
                                                         arguments
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Applies all properties in the supplier to the receiver if the
receiver does not have these properties yet.  Optionally, one or
more methods/properties can be specified (as additional
parameters).  This option will overwrite the property if receiver
has it already.  If true is passed as the third parameter, all
properties will be applied and _will_ overwrite properties in
the receiver.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        r
                                                        <Function>
                                                        the object to receive the augmentation
- 
                                                        s
                                                        <Function>
                                                        the object that supplies the properties to augment
- 
                                                        arguments
                                                        <String*|boolean>
                                                        zero or more properties methods
to augment the receiver with.  If none specified, everything
in the supplier will be used unless it would
overwrite an existing property in the receiver. If true
is specified as the third parameter, all properties will
be applied and will overwrite an existing property in
the receiver
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                         static 
                                        
                                        void
                                            augmentProto
                                           (
                                                
                                                        
                                                         r
                                                    
                                                
                                                        , 
                                                         s
                                                    
                                                
                                                        , 
                                                         arguments
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Same as YAHOO.lang.augmentObject, except it only applies prototype properties
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        r
                                                        <Function>
                                                        the object to receive the augmentation
- 
                                                        s
                                                        <Function>
                                                        the object that supplies the properties to augment
- 
                                                        arguments
                                                        <String*|boolean>
                                                        zero or more properties methods
to augment the receiver with.  If none specified, everything
in the supplier will be used unless it would overwrite an existing
property in the receiver.  if true is specified as the third
parameter, all properties will be applied and will overwrite an
existing property in the receiver
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        String
                                            dump
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                                        , 
                                                         d
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Returns a simple string representation of the object or array.
Other types of objects will be returned unprocessed.  Arrays
are expected to be indexed.  Use object notation for
associative arrays.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <Object>
                                                        The object to dump
- 
                                                        d
                                                        <int>
                                                        How deep to recurse child objects, default 3
                                                    - Returns:
                                                    
                                                            String
                                                    
- the dump result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                         static 
                                        
                                        String
                                            escapeHTML
                                           (
                                                
                                                        
                                                         html
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            
Returns a copy of the specified string with special HTML characters
escaped. The following characters will be converted to their
corresponding character entities:
& < > " ' / `
This implementation is based on the
OWASP
HTML escaping recommendations. In addition to the characters
in the OWASP recommendation, we also escape the `
character, since IE interprets it as an attribute delimiter when used in
innerHTML.
                                         
                                        
                                                
                                                    - Parameters:
- 
                                                        html
                                                        <String>
                                                        String to escape.
                                                    - Returns:
                                                    
                                                            String
                                                    
- Escaped string.
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                         static 
                                        
                                        void
                                            extend
                                           (
                                                
                                                        
                                                         subc
                                                    
                                                
                                                        , 
                                                         superc
                                                    
                                                
                                                        , 
                                                         overrides
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Utility to set up the prototype, constructor and superclass properties to
support an inheritance strategy that can chain constructors and methods.
Static members will not be inherited.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        subc
                                                        <Function>
                                                        the object to modify
- 
                                                        superc
                                                        <Function>
                                                        the object to inherit
- 
                                                        overrides
                                                        <Object>
                                                        additional properties/methods to add to the
subclass prototype.  These will override the
matching items obtained from the superclass
if present.
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            hasOwnProperty
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                                        , 
                                                         prop
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            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.
This abstraction is provided to enable hasOwnProperty for Safari 1.3.x.
There is a discrepancy between YAHOO.lang.hasOwnProperty and
Object.prototype.hasOwnProperty when the property is a primitive added to
both the instance AND prototype with the same value:
var A = function() {};
A.prototype.foo = 'foo';
var a = new A();
a.foo = 'foo';
alert(a.hasOwnProperty('foo')); // true
alert(YAHOO.lang.hasOwnProperty(a, 'foo')); // false when using fallback
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
- 
                                                        prop
                                                        <string>
                                                        the name of the property to test
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isArray
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines wheather or not the provided object is an array.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isBoolean
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is a boolean
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isFunction
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is a function.
Note: Internet Explorer thinks certain functions are objects:
var obj = document.createElement("object");
YAHOO.lang.isFunction(obj.getAttribute) // reports false in IE
var input = document.createElement("input"); // append to body
YAHOO.lang.isFunction(input.focus) // reports false in IE
You will have to implement additional tests if these functions
matter to you.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isNull
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is null
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isNumber
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is a legal number
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isObject
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is of type object
or function
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isString
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is a string
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isUndefined
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Determines whether or not the provided object is undefined
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        The object being testing
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- the result
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        boolean
                                            isValue
                                           (
                                                
                                                        
                                                         o
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            A convenience method for detecting a legitimate non-null value.
Returns false for null/undefined/NaN, true for other values,
including 0/false/''
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        o
                                                        <any>
                                                        the item to test
                                                    - Returns:
                                                    
                                                            boolean
                                                    
- true if it is not null/undefined/NaN || false
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        
                                            later
                                           (
                                                
                                                        
                                                         when
                                                    
                                                
                                                        , 
                                                         o
                                                    
                                                
                                                        , 
                                                         fn
                                                    
                                                
                                                        , 
                                                         data
                                                    
                                                
                                                        , 
                                                         periodic
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Executes the supplied function in the context of the supplied
object 'when' milliseconds later.  Executes the function a
single time unless periodic is set to true.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        when
                                                        <int>
                                                        the number of milliseconds to wait until the fn
is executed
- 
                                                        o
                                                        <object>
                                                        the context object
- 
                                                        fn
                                                        <Function|String>
                                                        the function to execute or the name of
the method in the 'o' object to execute
- 
                                                        data
                                                        <object>
                                                        [Array] data that is provided to the function.  This accepts
either a single item or an array.  If an array is provided, the
function is executed with one parameter for each array item.  If
you need to pass a single array parameter, it needs to be wrapped in
an array [myarray]
- 
                                                        periodic
                                                        <boolean>
                                                        if true, executes continuously at supplied
interval until canceled
                                                    - Returns:
                                                    
                                                    
- a timer object. Call the cancel() method on this object to
stop the timer.
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        
                                            merge
                                           (
                                                
                                                        
                                                         arguments
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Returns a new object containing all of the properties of
all the supplied objects.  The properties from later objects
will overwrite those in earlier objects.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        arguments
                                                        <Object*>
                                                        the objects to merge
                                                    - Returns:
                                                    
                                                    
- the new merged object
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        String
                                            substitute
                                           (
                                                
                                                        
                                                         s
                                                    
                                                
                                                        , 
                                                         o
                                                    
                                                
                                                        , 
                                                         f
                                                    
                                                
                                                        , 
                                                         recurse
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Does variable substitution on a string. It scans through the string
looking for expressions enclosed in { } braces. If an expression
is found, it is used a key on the object.  If there is a space in
the key, the first word is used for the key and the rest is provided
to an optional function to be used to programatically determine the
value (the extra information might be used for this decision). If
the value for the key in the object, or what is returned from the
function has a string value, number value, or object value, it is
substituted for the bracket expression and it repeats.  If this
value is an object, it uses the Object's toString() if this has
been overridden, otherwise it does a shallow dump of the key/value
pairs.
By specifying the recurse option, the string is rescanned after
every replacement, allowing for nested template substitutions.
The side effect of this option is that curly braces in the
replacement content must be encoded.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        s
                                                        <String>
                                                        The string that will be modified.
- 
                                                        o
                                                        <Object>
                                                        An object containing the replacement values
- 
                                                        f
                                                        <Function>
                                                        An optional function that can be used to
process each match.  It receives the key,
value, and any extra metadata included with
the key inside of the braces.
- 
                                                        recurse
                                                        <boolean>
                                                        default true - if not false, the replaced
string will be rescanned so that nested substitutions are possible.
                                                    - Returns:
                                                    
                                                            String
                                                    
- the substituted string
 
                                     
                                    
                                     
                                    
                                    
                                    
                                        
                                        
                                        
                                        
                                        string
                                            trim
                                           (
                                                
                                                        
                                                         s
                                                    
                                                
                                            )
                                        
                                        
                                        
                                            Returns a string without any leading or trailing whitespace.  If
the input is not a string, the input will be returned untouched.
                                        
                                        
                                                
                                                    - Parameters:
- 
                                                        s
                                                        <string>
                                                        the string to trim
                                                    - Returns:
                                                    
                                                            string
                                                    
- the trimmed string