Array : mthode join()

Exemple interactif

const elements = ["Feu", "Air", "Eau"];

console.log(elements.join());
// Rsultat attendu :  Feu,Air,Eau 

console.log(elements.join(""));
// Rsultat attendu :  FeuAirEau 

console.log(elements.join("-"));
// Rsultat attendu :  Feu-Air-Eau 

Syntaxe

join()
join(separator)

Paramtres

separator Facultatif

Une chane de caractres utilise pour sparer chaque paire d'lments adjacents du tableau. Si ce paramtre est omis, les lments du tableau sont spars par une virgule (",").

Valeur de retour

Une chane de caractres contenant tous les lments du tableau fusionns. Si array.length vaut 0, une chane de caractres vide est retourne.

Description

Les conversions en chane de caractres de tous les lments du tableau sont jointes en une seule chane de caractres. Si un lment vaut undefined ou null, il est converti en chane de caractres vide au lieu de la chane de caractres "null" ou "undefined".

La mthode join est utilise en interne par Array.prototype.toString() sans argument. Redfinir join sur une instance de tableau redfinit aussi son comportement toString.

Array.prototype.join convertit rcursivement chaque lment, y compris les tableaux imbriqus, en chanes de caractres. Comme la chane de caractres retourne par Array.prototype.toString (quivalent join()) ne contient pas de sparateurs, les tableaux imbriqus semblent aplatis. Vous ne pouvez contrler que le sparateur du premier niveau, les niveaux plus profonds utilisent toujours la virgule par dfaut.

const matrice = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];

console.log(matrice.join()); // 1,2,3,4,5,6,7,8,9
console.log(matrice.join(";")); // 1,2,3;4,5,6;7,8,9

Si un tableau est cyclique (il contient un lment qui fait rfrence lui-mme), les navigateurs vitent la rcursion infinie en ignorant la rfrence cyclique.

const arr = [];
arr.push(1, [3, arr, 4], 2);
console.log(arr.join(";")); // 1;3,,4;2

Lorsqu'elle est utilise sur un tableau creux, la mthode join() itre sur les emplacements vides comme s'ils avaient la valeur undefined.

La mthode join() est gnrique. Elle attend uniquement que la valeur de this possde une proprit length et des proprits cls entires.

Exemples

Fusionner un tableau de quatre faons diffrentes

L'exemple suivant cre un tableau, a, avec trois lments, puis joint le tableau trois reprises : en utilisant le sparateur par dfaut, une virgule et un espace, puis un plus, puis avec la chane de caractres vide.

const a = new Array("Vent", "Pluie", "Feu");
a.join(); // "Vent,Pluie,Feu"
a.join(", "); // "Vent, Pluie, Feu"
a.join(" + "); // "Vent + Pluie + Feu"
a.join(""); // "VentPluieFeu"

Utiliser join() sur un tableau creux

join() traite les emplacements vides comme des valeurs undefined et produit un sparateur supplmentaire :

console.log([1, , 3].join()); // '1,,3'
console.log([1, undefined, 3].join()); // '1,,3'

Appeler join() sur des objets qui ne sont pas des tableaux

La mthode join() lit la proprit length de this puis accde chaque proprit dont la cl est un entier non ngatif infrieur length.

const objetSimilaireTableau = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 5, // ignor par join(), car length vaut 3
};
console.log(Array.prototype.join.call(objetSimilaireTableau));
// 2,3,4
console.log(Array.prototype.join.call(objetSimilaireTableau, "."));
// 2.3.4

Spcifications

Compatibilit des navigateurs

Voir aussi

• Guide des collections indexes
• L'objet global Array
• La mthode String.prototype.split()
• La mthode Array.prototype.toString()
• La mthode TypedArray.prototype.join()
• Prothse d'mulation de Array.prototype.join dans core-js (angl.)
• Prothse d'mulation es-shims de Array.prototype.join (angl.)