Function.prototype.apply()

  • Revision slug: JavaScript/Reference/Global_Objects/Function/apply
  • Revision title: apply
  • Revision id: 17326
  • Created:
  • Creator: anthonyryan1
  • Is current revision? No
  • Comment 39 words added

Revision Content

Summary

Calls a function with a given this value and arguments provided as an array.

It is worth noting, that while the syntax and effect is almost identical to that of call, the fundamental difference is that call will pass the arguments by value, while apply will pass by reference.

Method of Function
Implemented in: JavaScript 1.3
ECMAScript Edition: ECMA-262 3rd Edition

Syntax

fun.apply(thisArg[, argsArray])

Parameters

thisArg 
Determines the value of this inside fun. If thisArg is null or undefined, this will be the global object. Otherwise, this will be equal to Object(thisArg) (which is thisArg if thisArg is already an object, or a String, Boolean, or Number if thisArg is a primitive value of the corresponding type). Therefore, it is always true that typeof this == "object" when the function executes.
argsArray 
An argument array for the object, specifying the arguments with which fun should be called, or null or undefined if no arguments should be provided to the function.

{{ js_minversion_note("1.8.5", "Starting in JavaScript 1.8.5 (Firefox 4), this method works according to the ECMAScript 5 specification. That is, the arguments can be a generic array-like object instead of an array. See " .. bug(562448) .. " for details on this change.") }}

Description

You can assign a different this object when calling an existing function. this refers to the current object, the calling object. With apply, you can write a method once and then inherit it in another object, without having to rewrite the method for the new object.

apply is very similar to call, except for the type of arguments it supports. You can use an arguments array instead of a named set of parameters. With apply, you can use an array literal, for example, fun.apply(this, [name, value]), or an Array object, for example, fun.apply(this, new Array(name, value)).

You can also use arguments for the argArray parameter. arguments is a local variable of a function. It can be used for all unspecified arguments of the called object. Thus, you do not have to know the arguments of the called object when you use the apply method. You can use arguments to pass all the arguments to the called object. The called object is then responsible for handling the arguments.

Examples

Using apply to chain constructors

You can use apply to chain constructors for an object, similar to Java. In the following example, the constructor for the product object is defined with two parameters, name and value. Another object, prod_dept, initializes its unique variable (dept) and calls the constructor for product in its constructor to initialize the other variables. In this example, the parameter arguments is used for all arguments of the product object's constructor.

function product(name, value)
{
  this.name = name;
  if (value >= 1000)
    this.value = 999;
  else
    this.value = value;
}

function prod_dept(name, value, dept)
{
  this.dept = dept;
  product.apply(this, arguments);
}
prod_dept.prototype = new product();

// since 5 is less than 1000 value is set
var cheese = new prod_dept("feta", 5, "food");

// since 5000 is above 1000, value will be 999
var car = new prod_dept("honda", 5000, "auto");

See Also

call

{{ languages( { "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Function/apply" } ) }}

Revision Source

<h2>Summary</h2>
<p>Calls a function with a given <code>this</code> value and <code>arguments</code> provided as an array.</p>
<p>It is worth noting, that while the syntax and effect is almost identical to that of <a href="/en/JavaScript/Reference/Global_Objects/Function/call" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function/call">call</a>, the fundamental difference is that call will pass the arguments by value, while apply will pass by reference.</p>
<table class="standard-table"> <thead> <tr> <th class="header" colspan="2" scope="row">Method of <a href="/en/JavaScript/Reference/Global_Objects/Function" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></th> </tr> </thead> <tbody> <tr> <th scope="row">Implemented in:</th> <td>JavaScript 1.3</td> </tr> <tr> <th scope="row">ECMAScript Edition:</th> <td>ECMA-262 3rd Edition</td> </tr> </tbody>
</table>
<h2>Syntax</h2>
<p><code><em>fun</em>.apply(<em>thisArg</em>[, <em>argsArray</em>])</code></p>
<h2>Parameters</h2>
<dl> <dt><code>thisArg</code> </dt> <dd>Determines the value of <code>this</code> inside <em><code>fun</code></em>. If <code>thisArg</code> is <code>null</code> or <a href="/en/JavaScript/Reference/Global_Objects/undefined" title="en/Core_JavaScript_1.5_Reference/Global_Properties/undefined">undefined</a>, <code>this</code> will be the global object. Otherwise, <code>this</code> will be equal to <code>Object(thisArg)</code> (which is <code>thisArg</code> if <code>thisArg</code> is already an object, or a <code>String</code>, <code>Boolean</code>, or <code>Number</code> if <code>thisArg</code> is a primitive value of the corresponding type). Therefore, it is always true that <code>typeof this == "object"</code> when the function executes.</dd>
</dl>
<dl> <dt><code>argsArray</code> </dt> <dd>An argument array for the object, specifying the arguments with which <em><code>fun</code></em> should be called, or <code>null</code> or <a href="/en/JavaScript/Reference/Global_Objects/undefined" title="en/Core_JavaScript_1.5_Reference/Global_Properties/undefined">undefined</a> if no arguments should be provided to the function.</dd>
</dl>
<p>{{ js_minversion_note("1.8.5", "Starting in JavaScript 1.8.5 (Firefox 4), this method works according to the ECMAScript 5 specification. That is, the arguments can be a generic array-like object instead of an array. See " .. bug(562448) .. " for details on this change.") }}</p>
<h2>Description</h2>
<p>You can assign a different <code>this</code> object when calling an existing function. <code>this</code> refers to the current object, the calling object. With <code>apply</code>, you can write a method once and then inherit it in another object, without having to rewrite the method for the new object.</p>
<p><code>apply</code> is very similar to <code><a href="/en/JavaScript/Reference/Global_Objects/Function/call" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Function/call">call</a></code>, except for the type of arguments it supports. You can use an arguments array instead of a named set of parameters. With <code>apply</code>, you can use an array literal, for example, <code><em>fun</em>.apply(this, [name, value])</code>, or an <code>Array</code> object, for example, <code><em>fun</em>.apply(this, new Array(name, value))</code>.</p>
<p>You can also use <code><a href="/en/JavaScript/Reference/Functions_and_function_scope/arguments" title="En/Core_JavaScript_1.5_Reference/Functions_and_function_scope/arguments">arguments</a></code> for the <code>argArray</code> parameter. <code>arguments</code> is a local variable of a function. It can be used for all unspecified arguments of the called object. Thus, you do not have to know the arguments of the called object when you use the <code>apply</code> method. You can use <code>arguments</code> to pass all the arguments to the called object. The called object is then responsible for handling the arguments.</p>
<h2>Examples</h2>
<h3>Using <code>apply</code> to chain constructors</h3>
<p>You can use <code>apply</code> to chain constructors for an object, similar to Java. In the following example, the constructor for the <code>product</code> object is defined with two parameters, <code>name</code> and <code>value</code>. Another object, <code>prod_dept</code>, initializes its unique variable (<code>dept</code>) and calls the constructor for <code>product</code> in its constructor to initialize the other variables. In this example, the parameter <code>arguments</code> is used for all arguments of the product object's constructor.</p>
<pre class="brush: js">function product(name, value)
{
  this.name = name;
  if (value &gt;= 1000)
    this.value = 999;
  else
    this.value = value;
}

function prod_dept(name, value, dept)
{
  this.dept = dept;
  product.apply(this, arguments);
}
prod_dept.prototype = new product();

// since 5 is less than 1000 value is set
var cheese = new prod_dept("feta", 5, "food");

// since 5000 is above 1000, value will be 999
var car = new prod_dept("honda", 5000, "auto");
</pre>
<h2>See Also</h2>
<p><a href="/en/JavaScript/Reference/Global_Objects/Function/call" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Function/call">call</a></p>
<p>{{ languages( { "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Function/apply" } ) }}</p>
Revert to this revision