Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

String.prototype.substr()

La méthode substr() renvoie les caractères d'une chaîne de caractères commençant à un endroit donné et sur une longueur donnée. Autrement dit, cette méthode renvoie la sous-chaîne de la chaîne courante à partir d'un indice

Syntaxe

str.substr(début[, longueur])

Paramètres

début
L'indice à partir duquel extraire les caractères. Si la valeur fournie est négative, elle sera traitée comme strLength + début avec strLength la longueur de la chaîne (par exemple, si début vaut -3, il sera traité comme strLength - 3.)
longueur
Paramètre optionnel. Le nombre de caractères à extraire.

Valeur de retour

Une nouvelle chaîne de caractères obtenue en extrayant une section donnée de la chaîne appelante. Si le paramètre longueur est négatif ou nul, c'est une chaîne vide qui sera renvoyée.

Description

début est l'indice de la chaîne à partir duquel effectuer l'extraction. L'indice du premier caractère est 0, l'indice du dernier caractère de la chaîne est la longueur de la chaîne moins un. substr() effectue l'extraction à partir de début et extrait longueur caractères (sauf si la fin de la chaîne est atteinte avant).

Si début est positif et supérieur ou égal à la longueur de la chaîne, substr() renvoie la chaîne vide.

Si début est négatif, substr() compte à partir de la fin de la chaîne. Si début est négatif et que abs(début) est supérieur à la longueur de la chaîne, substr() utilise 0 comme indice de début.

Si longueur vaut 0 ou est négatif, substr() renvoie une chaîne vide. Si le paramètre longueur n'est pas utilisé, substr() extrait les caractères jusqu'à la fin de la chaîne.

Exemples

Utiliser substr()

var str = 'abcdefghij';

console.log('(1, 2): ' + str.substr(1, 2));     // '(1, 2): bc'
console.log('(-3, 2): ' + str.substr(-3, 2));   // '(-3, 2): hi'
console.log('(-3): ' + str.substr(-3));         // '(-3): hij'
console.log('(1): ' + str.substr(1));           // '(1): bcdefghij'
console.log('(-20, 2): ' + str.substr(-20, 2)); // '(-20, 2): ab'
console.log('(20, 2): ' + str.substr(20, 2));   // '(20, 2): '

Prothèse d'émulation (polyfill)

Les valeurs négatives pour le premier argument (début) peuvent ne pas être gérées dans certains environnement (JScript Microsoft par exemple). Pour pouvoir bénéficier de cette fonctionnalité, on peut utiliser le fragment de code suivante :

// on n'applique le correctif que si nécessaire
if ('ab'.substr(-1) != 'b') {
  /**
   *  Obtenir la sous-chaîne d'une chaîne
   *  @param  {integer}  début     où commencer l'extraction
   *  @param  {integer}  longueur  combien de caractères pour la sous-chaîne
   *  @return {string}
   */
  String.prototype.substr = function(substr) {
    return function(début, longueur) {
      // Si on a un début négatif, on transforme la valeur
      // pour calculer l'indice positif à partir duquel
      // commencer l'extraction
      if (début < 0) {
        début = this.length + début;
      }

      // la valeur est désormais positive, on appelle
      // la fonction originale
      return substr.call(this, start, length);
    }
  }(String.prototype.substr);
}

Spécifications

Spécification État Commentaires
ECMAScript 3rd Edition (ECMA-262) Standard Définie dans l'annexe B (informative) sur la compatibilité. Implémentée avec JavaScript 1.0.
ECMAScript 5.1 (ECMA-262)
La définition de 'String.prototype.substr' dans cette spécification.
Standard Définie dans l'annexe B (informative) sur la compatibilité.
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'String.prototype.substr' dans cette spécification.
Standard Définie dans l'annexe B (normative) pour les fonctionnalités ECMAScript additionnelles des navigateurs web.
ECMAScript 2017 Draft (ECMA-262)
La définition de 'String.prototype.substr' dans cette spécification.
Projet Defined in the (normative) Annex B for Additional ECMAScript Features for Web Browsers

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support simple (Oui) (Oui) (Oui) (Oui) (Oui)
Fonctionnalité Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support simple (Oui) (Oui) (Oui) (Oui) (Oui) (Oui)

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, teoli, Jeremie, Julien.stuby
 Dernière mise à jour par : SphinxKnight,