Function : méthode apply()

Exemple interactif

const numbers = [5, 6, 2, 3, 7];

const max = Math.max.apply(null, numbers);

console.log(max);
// Résultat attendu : 7

const min = Math.min.apply(null, numbers);

console.log(min);
// Résultat attendu : 2

Syntaxe

apply(thisArg)
apply(thisArg, argsArray)

Paramètres

thisArg

La valeur de this fournie pour l'appel à func. Si la fonction n'est pas en mode strict, null et undefined seront remplacées par l'objet global, et les valeurs primitives seront converties en objets.

argsArray Facultatif

Un objet semblable à un tableau, définissant les arguments avec lesquels func doit être appelée, ou null ou undefined si aucun argument ne doit être fourni à la fonction.

Valeur de retour

Le résultat obtenu en appelant la fonction avec la valeur this indiquée et les arguments fournis.

Description

Normalement, lors de l'appel d'une fonction, la valeur de this à l'intérieur de la fonction est l'objet sur lequel la fonction a été appelée. Avec apply(), vous pouvez attribuer une valeur arbitraire à this lors de l'appel d'une fonction existante, sans avoir à rattacher d'abord la fonction à l'objet en tant que propriété. Cela permet d'utiliser les méthodes d'un objet comme fonctions utilitaires génériques.

Vous pouvez également utiliser tout type d'objet semblable à un tableau comme second paramètre. En pratique, cela signifie qu'il doit posséder une propriété length et des propriétés entières (« index ») dans l'intervalle (0..length - 1). Par exemple, vous pouvez utiliser un NodeList, ou un objet personnalisé comme { 'length': 2, '0': 'eat', '1': 'bananas' }. Vous pouvez aussi utiliser arguments, par exemple :

function enveloppe() {
  return autreFonction.apply(null, arguments);
}

Avec les paramètres du reste et la syntaxe de décomposition des paramètres, cela peut être réécrit ainsi :

function enveloppe(...args) {
  return autreFonction(...args);
}

En général, fn.apply(null, args) est équivalent à fn(...args) avec la syntaxe de décomposition des paramètres, sauf que args doit être un objet semblable à un tableau dans le premier cas avec apply(), et un objet itérable dans le second cas avec la syntaxe de décomposition.

Exemples

Utiliser apply() pour ajouter un tableau à un autre

Vous pouvez utiliser Array.prototype.push() pour ajouter un élément à un tableau. Comme push() accepte un nombre variable d'arguments, vous pouvez aussi ajouter plusieurs éléments en une seule fois. Mais si vous passez un tableau à push(), il ajoutera en réalité ce tableau comme un seul élément, au lieu d'ajouter les éléments individuellement, ce qui aboutit à un tableau dans un tableau. À l'inverse, Array.prototype.concat() a le comportement souhaité dans ce cas, mais il ne modifie pas le tableau existant — il crée et retourne un nouveau tableau.

Dans ce cas, vous pouvez utiliser apply pour « étaler » implicitement un tableau en une série d'arguments.

const tableau = ["a", "b"];
const elements = [0, 1, 2];
tableau.push.apply(tableau, elements);
console.info(tableau); // ["a", "b", 0, 1, 2]

Le même effet peut être obtenu avec la syntaxe de décomposition.

const tableau = ["a", "b"];
const elements = [0, 1, 2];
tableau.push(...elements);
console.info(tableau); // ["a", "b", 0, 1, 2]

Utiliser apply() et des fonctions natives

Un usage astucieux de apply() permet d'utiliser des fonctions natives pour certaines tâches qui nécessiteraient autrement de parcourir manuellement une collection (ou d'utiliser la syntaxe de décomposition).

Par exemple, on peut utiliser Math.max() et Math.min() pour obtenir la valeur maximale et minimale d'un tableau.

/* min/max tableau de nombres */
const nombres = [5, 6, 2, 3, 7];

/* usage de Math.min/Math.max et de la méthode apply */
let max = Math.max.apply(null, nombres);
/* Equivalent à Math.max(nombres[0], ...)
  ou Math.max(5, 6, ..) */

let min = Math.min.apply(null, nombres);

/* vs. algorithme trivial avec une boucle */
max = -Infinity;
min = Infinity;

for (const n of nombres) {
  if (n > max) {
    max = n;
  }
  if (n < min) {
    min = n;
  }
}

Attention : en utilisant apply() (ou la syntaxe de décomposition) avec une liste d'arguments arbitrairement longue, vous risquez de dépasser la limite du nombre d'arguments du moteur JavaScript.

Les conséquences d'un appel de fonction avec trop d'arguments (c'est-à-dire plus de plusieurs dizaines de milliers d'arguments) ne sont pas spécifiées et varient selon les moteurs. (Le moteur JavaScriptCore a une limite d'arguments de 65536 ^(angl.)). La plupart des moteurs lèvent une exception ; mais il n'existe aucune spécification normative empêchant d'autres comportements, comme la limitation arbitraire du nombre d'arguments effectivement transmis à la fonction appelée. Pour illustrer ce dernier cas : si un tel moteur avait une limite de quatre arguments (les limites réelles sont bien sûr bien plus élevées), cela reviendrait à ce que les arguments 5, 6, 2, 3 soient passés à apply dans les exemples ci-dessus, plutôt que le tableau complet.

Si votre tableau de valeurs risque d'atteindre plusieurs dizaines de milliers d'éléments, utilisez une stratégie hybride : appliquez votre fonction à des portions du tableau à la fois :

function minimumDuTableau(tableau) {
  let min = Infinity;
  const QUANTUM = 32768;

  for (let i = 0; i < tableau.length; i += QUANTUM) {
    const submin = Math.min.apply(
      null,
      tableau.slice(i, Math.min(i + QUANTUM, tableau.length)),
    );
    min = Math.min(submin, min);
  }

  return min;
}

const min = minimumDuTableau([5, 6, 2, 3, 7]);

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet arguments
• La méthode Function.prototype.bind()
• La méthode Function.prototype.call()
• La méthode Reflect.apply()
• Les fonctions
• La syntaxe de décomposition (...)