#if COPYRIGHT
//------------------------------------------------------------------------------
// <copyright file="Function.js" company="Microsoft">
//     Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>
//------------------------------------------------------------------------------
#endif
 
Function.__typeName = 'Function';
Function.__class = true;

Function.createCallback = function(method, context) {
    /// <summary>
    ///     Creates a callback function that retains the parameter initially used during its creation.
    ///     The callback is used without parameter but this will call the actual method with the parameter.
    ///     This is especially useful when setting up a handler for a DOM event that must retain a parameter
    ///     despite the DOM event handler needing to be a function with the event object as the only parameter.
    ///     In this case, the function will be called with the event as the first parameter and the context
    ///     as the second.
    ///     If the callback is called with an arbitrary list of parameters, the context is appended.
    /// </summary>
    /// <param name="method" type="Function">The function for which the callback is created.</param>
    /// <param name="context" mayBeNull="true">The parameter for the function.</param>
    /// <returns type="Function">The callback function.</returns>

    // The method still makes sense for null context, but not if the context is omitted altogether
    // (omitted context makes the callback equivalent to the method itself, with one more level of indirection).

    return function() {
        var l = arguments.length;
        if (l > 0) {
            // arguments is not a real array, need to build a real one from it so we can add
            var args = [];
            for (var i = 0; i < l; i++) {
                args[i] = arguments[i];
            }
            args[l] = context;
            return method.apply(this, args);
        }
        return method.call(this, context);
    }
}

Function.createDelegate = function(instance, method) {
    /// <summary>
    ///     Creates a delegate function that retains the context from its creation
    ///     (i.e. what 'this' means from within its scope).
    ///     This is especially useful when setting up an event handler to point to an object method
    ///     that needs to use the 'this' pointer from within its scope.
    /// </summary>
    /// <param name="instance" mayBeNull="true">
    ///     The object instance that will be the context for the function (i.e. what 'this' means from within its scope).
    /// </param>
    /// <param name="method" type="Function">The function from which the delegate is created.</param>
    /// <returns type="Function">The delegate function.</returns>

    // The method still makes some sense with a null instance, in the same way that createCallback still
    // makes sense with a null context.

    return function() {
        return method.apply(instance, arguments);
    }
}

Function.emptyFunction = Function.emptyMethod = function() {
    /// <summary>A function that does nothing.</summary>
    /// <validationOptions enabled="false"/>
}

Function.validateParameters = function(parameters, expectedParameters, validateParameterCount) {
    /// <summary locid="M:J#Function.validateParameters">
    ///     Validates the parameters to a method are as expected.
    /// </summary>
    /// <param name="parameters"/>
    /// <param name="expectedParameters"/>
    /// <param name="validateParameterCount" type="Boolean" optional="true">True if extra parameters are prohibited, false if they should be ignored. The default is true.</param>
    /// <returns type="Error" mayBeNull="true"/>
    /// <example>
    ///     function foo(anyParam, stringParam, anyArrayParam, stringArrayParam,
    ///                  interfaceParam, optionalStringParam) {
    ///         #if DEBUG
    ///         var e = Function.validateParameters(arguments, [
    ///             { name: "anyParam" },
    ///             { name: "mayBeNullParam", mayBeNull: true },
    ///             { name: "stringParam", type: String },
    ///             { name: "floatParam", type: Number },
    ///             { name: "intParam", type: Number, integer: true },
    ///             { name: "domParam", domElement: true },
    ///             { name: "anyArrayParam", type: Array },
    ///             { name: "mayBeNullArrayParam", type: Array, elementMayBeNull: true },
    ///             { name: "stringArrayParam", type: Array, elementType: String },
    ///             { name: "intArrayParam", type: Array, elementType: Number, elementInteger: true },
    ///             { name: "domElementArrayParam", type: Array, elementDomElement: true },
    ///             { name: "interfaceParam", type: Sys.IFoo }
    ///             { name: "optionalStringParam", type: String, optional: true }
    ///             { name: "stringParamArray", type: String, parameterArray: true }
    ///             { name: "mayBeNullParamArray", parameterArray: true, mayBeNull: true }
    ///         ]);
    ///         if (e) throw e;
    ///         #endif
    ///     }
    /// </example>    
    // type info omitted from parameters so that the parameter-parameters are not enumerated and each entry validated
    return Function._validateParams(parameters, expectedParameters, validateParameterCount);
}

Function._validateParams = function(params, expectedParams, validateParameterCount) {
    // *DO NOT* triple-slash comment those. The double-slashes here are on purpose.
    // We don't need to document private functions and those will induce infinite loops
    // if the preprocessor generates validation code for these.
    // <summary>
    //     Validates the parameters to a method.
    // </summary>
    // <example>
    //     function foo(anyParam, stringParam, anyArrayParam, stringArrayParam,
    //                  interfaceParam, optionalStringParam) {
    //         #if DEBUG
    //         var e = Function._validateParams(arguments, [
    //             { name: "anyParam" },
    //             { name: "mayBeNullParam", mayBeNull: true },
    //             { name: "stringParam", type: String },
    //             { name: "floatParam", type: Number },
    //             { name: "intParam", type: Number, integer: true },
    //             { name: "domParam", domElement: true },
    //             { name: "anyArrayParam", type: Array },
    //             { name: "mayBeNullArrayParam", type: Array, elementMayBeNull: true },
    //             { name: "stringArrayParam", type: Array, elementType: String },
    //             { name: "intArrayParam", type: Array, elementType: Number, elementInteger: true },
    //             { name: "domElementArrayParam", type: Array, elementDomElement: true },
    //             { name: "interfaceParam", type: Sys.IFoo }
    //             { name: "optionalStringParam", type: String, optional: true }
    //             { name: "stringParamArray", type: String, parameterArray: true }
    //             { name: "mayBeNullParamArray", parameterArray: true, mayBeNull: true }
    //         ]);
    //         if (e) throw e;
    //         #endif
    //     }
    // </example>
    // <param name="params" type="Array">Array of parameter values passed to the method.</param>
    // <param name="expectedParams" type="Array" optional="true">Array of JSON objects describing the expected parameters.</param>
    var e, expectedLength = expectedParams.length;
    validateParameterCount = validateParameterCount || (typeof(validateParameterCount) === "undefined");
    e = Function._validateParameterCount(params, expectedParams, validateParameterCount);
    if (e) {
        e.popStackFrame();
        return e;
    }
    for (var i = 0, l = params.length; i < l; i++) {
        // If there are more params than expectedParams, then the last expectedParam
        // must be a paramArray.  Use the last expectedParam to validate the remaining
        // params.
        var expectedParam = expectedParams[Math.min(i, expectedLength - 1)],
            paramName = expectedParam.name;
        if (expectedParam.parameterArray) {
            // Append index of parameter in parameterArray
            paramName += "[" + (i - expectedLength + 1) + "]";
        }
        else if (!validateParameterCount && (i >= expectedLength)) {
            // there were more params than expected params.
            // count validation is disabled, and the last expected param
            // is not a parameter array. Just ignore the rest of the parameters.
            break;
        }
        e = Function._validateParameter(params[i], expectedParam, paramName);
        if (e) {
            e.popStackFrame();
            return e;
        }
    }
    return null;
}

Function._validateParameterCount = function(params, expectedParams, validateParameterCount) {
    var i, error,
        expectedLen = expectedParams.length,
        actualLen = params.length;
    if (actualLen < expectedLen) {
        // this might be ok if some parameters are optional or if theres a parameter array
        var minParams = expectedLen;
        for (i = 0; i < expectedLen; i++) {
            var param = expectedParams[i];
            if (param.optional || param.parameterArray) {
                minParams--;
            }
        }        
        if (actualLen < minParams) {
            error = true;
        }
    }
    else if (validateParameterCount && (actualLen > expectedLen)) {
        // this might be ok if a parameter is a parameterArray
        error = true;      
        for (i = 0; i < expectedLen; i++) {
            if (expectedParams[i].parameterArray) {
                error = false; // infinite parameters is ok
                break;
            }
        }  
    }

    if (error) {
        var e = Error.parameterCount();
        e.popStackFrame();
        return e;
    }

    return null;
}

Function._validateParameter = function(param, expectedParam, paramName) {
    var e,
        expectedType = expectedParam.type,
        expectedInteger = !!expectedParam.integer,
        expectedDomElement = !!expectedParam.domElement,
        mayBeNull = !!expectedParam.mayBeNull;

    e = Function._validateParameterType(param, expectedType, expectedInteger, expectedDomElement, mayBeNull, paramName);
    if (e) {
        e.popStackFrame();
        return e;
    }

    // If parameter is an array, and not undefined or null, validate the type of its elements
    var expectedElementType = expectedParam.elementType,
        elementMayBeNull = !!expectedParam.elementMayBeNull;
    if (expectedType === Array && typeof(param) !== "undefined" && param !== null &&
        (expectedElementType || !elementMayBeNull)) {
        var expectedElementInteger = !!expectedParam.elementInteger,
            expectedElementDomElement = !!expectedParam.elementDomElement;
        for (var i=0; i < param.length; i++) {
            var elem = param[i];
            e = Function._validateParameterType(elem, expectedElementType,
                expectedElementInteger, expectedElementDomElement, elementMayBeNull,
                paramName + "[" + i + "]");
            if (e) {
                e.popStackFrame();
                return e;
            }
        }
    }

    return null;
}

Function._validateParameterType = function(param, expectedType, expectedInteger, expectedDomElement, mayBeNull, paramName) {
    var e, i;

    if (typeof(param) === "undefined") {
        if (mayBeNull) {
            return null;
        }
        else {
            e = Error.argumentUndefined(paramName);
            e.popStackFrame();
            return e;
        }
    }

    if (param === null) {
        if (mayBeNull) {
            return null;
        }
        else {
            e = Error.argumentNull(paramName);
            e.popStackFrame();
            return e;
        }
    }

    if (expectedType && expectedType.__enum) {
        if (typeof(param) !== 'number') {
            e = Error.argumentType(paramName, Object.getType(param), expectedType);
            e.popStackFrame();
            return e;
        }
        if ((param % 1) === 0) {
            var values = expectedType.prototype;
            if (!expectedType.__flags || (param === 0)) {
                for (i in values) {
                    if (values[i] === param) return null;
                }
            }
            else {
                var v = param;
                for (i in values) {
                    var vali = values[i];
                    if (vali === 0) continue;
                    if ((vali & param) === vali) {
                        v -= vali;
                    }
                    if (v === 0) return null;
                }
            }
        }
        e = Error.argumentOutOfRange(paramName, param, String.format(Sys.Res.enumInvalidValue, param, expectedType.getName()));
        e.popStackFrame();
        return e;
    }

    // Text nodes are not considered DOM elements here.
    if (expectedDomElement && (!Sys._isDomElement(param) || (param.nodeType === 3))) {
        e = Error.argument(paramName, Sys.Res.argumentDomElement);
        e.popStackFrame();
        return e;
    }

    // If there is no expected type, any type is allowed.
    if (expectedType && !Sys._isInstanceOfType(expectedType, param)) {
        e = Error.argumentType(paramName, Object.getType(param), expectedType);
        e.popStackFrame();
        return e;
    }

    if (expectedType === Number && expectedInteger) {
        // Modulo operator is 5x faster than Math.round().
        // Modulo returns Number.NaN for Number.NaN, Number.POSITIVE_INFINITY, and Number.NEGATIVE_INFINITY.
        if ((param % 1) !== 0) {
            e = Error.argumentOutOfRange(paramName, param, Sys.Res.argumentInteger);
            e.popStackFrame();
            return e;
        }
    }

    return null;
}