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

構文

str.substr(start[, length])

引数

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

戻り値

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

詳細

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

仕様

仕様 ステータス コメント
ECMAScript 3rd Edition (ECMA-262) 標準

JavaScript 1.0 で実装。参考)互換性付録 B に定義されている

ECMAScript 5.1 (ECMA-262)
String.prototype.substr の定義
標準 参考)互換性付録 B に定義されている
ECMAScript 2015 (6th Edition, ECMA-262)
String.prototype.substr の定義
標準 ウェブブラウザのための追加 ECMAScript 機能のための参考)互換性付録 B に定義されている
ECMAScript 2017 Draft (ECMA-262)
String.prototype.substr の定義
ドラフト ウェブブラウザのための追加 ECMAScript 機能のための参考)互換性付録 B に定義されている

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート (有) (有) (有) (有) (有)
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート (有) (有) (有) (有) (有) (有)

関連情報

ドキュメントのタグと貢献者

 最終更新者: TakashiHarano,