String.prototype.substr()

非推奨の substr() メソッドは、文字列内における文字を、指定した位置から指定した数だけ返します。

構文

str.substr(start[, length])

引数

start

文字を取り出す位置（ 0 から文字列の長さ以下までの整数）。負の数が与えられた場合、strLength + start のように扱われる。strLength は文字列の長さ（たとえば、start が -3 の場合、strLength - 3 のように扱われる）。

length

省略可能。取り出す文字の数。

戻り値

与えられた文字列の抽出されたセクションを含む新しい文字列。length が 0 や負の数の場合、空文字列が買えるされる。

詳細

start は文字のインデックスです。一番最初の文字のインデックスは、 0 で、最後の文字のインデックスは、文字列の長さから 1 を引いた数です。substr は、start から文字の取り出しを開始し、length 個の文字を集めます（start から文字列の最後までの長さが指定した length より短かった場合は、length より少ない数の文字を返すでしょう）。

start が正の数かつ文字列の長さ以上である場合、substr は空の文字列を返します。

start が負の数である場合、substr はそれを文字列の最後から数えた文字のインデックスとして使用します。start が負の数かつ start の絶対値が文字列の長さより大きい場合、substr は開始インデックスとして 0 を使用します。注: start の引数に負の数の値を指定することは、Microsoft JScript ではサポートされません。
【訳注: JScript では start に負の数を指定した場合、正の数として扱われます】

length が 0 あるいは負の数の場合、substr は空の文字列を返します。length が省略された場合、start から文字列の最後までの文字を取り出します。

例

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): '

ポリフィル

Microsoft の JScript は start インデックスとして負の数をサポートしません。この機能を使用したい場合、このバグを回避するために、次の互換コードを使用できます:

// 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);
}

仕様

ブラウザ実装状況

関連情報

• String.prototype.slice()
• String.prototype.substring()