String.prototype.substr()

O método substr() retorna uma parte da string, começando no índice especificado e estendendo-se por um determinado número de caracteres posteriormente.

Sintaxe

str.substr(start[, length])

Parâmetros

start
Local para começar a extrair os caracteres.
length
Opcional. O número de caracteres a serem extraídos.

Valor de retorno

Uma nova string contendo a seção extraída da string fornecida.

Descrição

O substr() extrai caracteres de comprimento de uma str, contando a partir do índice inicial.

  • Se o start for um número positivo, o índice começa a contar no início da string. Seu valor é limitado ao tamanho da string (str.length).
  • Se o start for um número negativo, o índice começa a contar a partir do final da string. Seu valor é limitado ao tamanho da string (-str.length).

Nota: No Microsoft JScript, valores negativos no argumento start não são considerados como referência ao final da string.

  • Se length for omitido, substr() extrairá caracteres até o final da string.
  • Se length for undefined, substr() extrai os caracteres até o final da string.
  • Se length for um número negativo, ele será tratado como 0.
  • Para start e length, NaN é tratado como 0.

Exemplos

Usando substr()

var aString = 'Mozilla';

console.log(aString.substr(0, 1));   // 'M'
console.log(aString.substr(1, 0));   // ''
console.log(aString.substr(-1, 1));  // 'a'
console.log(aString.substr(1, -1));  // ''
console.log(aString.substr(-3));     // 'lla'
console.log(aString.substr(1));      // 'ozilla'
console.log(aString.substr(-20, 2)); // 'Mo'
console.log(aString.substr(20, 2));  // ''

Polyfill

JScript da Microsoft não suporta valores negativos para o índice de start. Se você deseja usar esse recurso, você pode usar o seguinte código de compatibilidade para evitar esse erro:

// only run when the substr() function is broken
if ('ab'.substr(-1) != 'b') {
  /**
   *  Get the substring of a string
   *  @param  {integer}  start   where to start the substring
   *  @param  {integer}  length  how many characters to return
   *  @return {string}
   */
  String.prototype.substr = function(substr) {
    return function(start, length) {
      // call the original method
      return substr.call(this,
      	// did we get a negative start, calculate how much it is from the beginning of the string
        // adjust the start parameter for negative value
        start < 0 ? this.length + start : start,
        length)
    }
  }(String.prototype.substr);
}

Especificações

Specification Status Comment
ECMAScript 3rd Edition (ECMA-262) Padrão Defined in the (informative) Compatibility Annex B. Implemented in JavaScript 1.0.
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.substr' in that specification.
Padrão Defined in the (informative) Compatibility Annex B
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.substr' in that specification.
Padrão Defined in the (normative) Annex B for Additional ECMAScript Features for Web Browsers
ECMAScript (ECMA-262)
The definition of 'String.prototype.substr' in that specification.
Padrão em tempo real Defined in the (normative) Annex B for Additional ECMAScript Features for Web Browsers

BCD tables only load in the browser

Veja também