String.prototype.substr()

  • Revision slug: JavaScript/Reference/Global_Objects/String/substr
  • Revision title: substr
  • Revision id: 64781
  • Created:
  • Creator: Thorn
  • Is current revision? No
  • Comment 2 words added

Revision Content

 

Summary

Returns the characters in a string beginning at the specified location through the specified number of characters.

Method of String
Implemented in: JavaScript 1.0
ECMA Version: None, although ECMA-262 ed. 3 has a non-normative section suggesting uniform semantics for substr

Syntax

var sub = string.substr(start[, length]);

Parameters

start 
Location at which to begin extracting characters (an integer between 0 and one less than the length of the string).
length 
The number of characters to extract.

Description

start is a character index. The index of the first character is 0, and the index of the last character is 1 less than the length of the string. substr begins extracting characters at start and collects length characters (unless it reaches the end of the string first, in which case it will return fewer).

If start is positive and is greater than or equal to the length of the string, substr returns an empty string.

If start is negative, substr uses it as a character index from the end of the string. If start is negative and abs(start) is larger than the length of the string, substr uses 0 as the start index. Note: the described handling of negative values of the start argument is not supported by Microsoft JScript .

If length is 0 or negative, substr returns an empty string. If length is omitted, substr extracts characters to the end of the string.

Examples

Example: Using substr

Consider the following script:

// assumes a print function is defined
var str = "abcdefghij";
print("(1,2): "    + str.substr(1,2));
print("(-3,2): "   + str.substr(-3,2));
print("(-3): "     + str.substr(-3));
print("(1): "      + str.substr(1));
print("(-20, 2): " + str.substr(-20,2));
print("(20, 2): "  + str.substr(20,2));

This script displays:

(1,2): bc
(-3,2): hi
(-3): hij
(1): bcdefghij
(-20, 2): ab
(20, 2):

See also

slicesubstring

 

{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/String/substr", "fr": "fr/Référence_de_JavaScript_1.5_Core/Objets_globaux/String/substr", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/String/substr", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/String/substr" } ) }}

Revision Source

<p> </p>
<h3 name="Summary">Summary</h3>
<p>Returns the characters in a string beginning at the specified location through the specified number of characters.</p>
<table class="fullwidth-table"> <tbody> <tr> <td class="header" colspan="2">Method of <a href="/en/Core_JavaScript_1.5_Reference/Global_Objects/String" title="en/Core_JavaScript_1.5_Reference/Global_Objects/String">String</a></td> </tr> <tr> <td>Implemented in:</td> <td>JavaScript 1.0</td> </tr> <tr> <td>ECMA Version:</td> <td>None, although ECMA-262 ed. 3 has a non-normative section suggesting uniform semantics for <code>substr</code></td> </tr> </tbody>
</table><h3 name="Syntax">Syntax</h3>
<pre class="eval">var sub = <em>string</em>.substr(<em>start</em>[, <em>length</em>]);
</pre>
<h3 name="Parameters">Parameters</h3>
<dl><dt> <code>start</code> </dt><dd> Location at which to begin extracting characters (an integer between 0 and one less than the length of the string). </dd></dl> <dl><dt> <code>length</code> </dt><dd> The number of characters to extract. </dd></dl>
<h3 name="Description">Description</h3>
<p><code>start</code> is a character index. The index of the first character is 0, and the index of the last character is 1 less than the length of the string. <code>substr</code> begins extracting characters at <code>start</code> and collects <code>length</code> characters (unless it reaches the end of the string first, in which case it will return fewer).</p>
<p>If <code>start</code> is positive and is greater than or equal to the length of the string, <code>substr</code> returns an empty string.</p>
<p>If <code>start</code> is negative, <code>substr</code> uses it as a character index from the end of the string. If <code>start</code> is negative and <code>abs(start)</code> is larger than the length of the string, <code>substr</code> uses 0 as the start index. Note: the described handling of negative values of the <code>start</code> argument is not supported by Microsoft JScript <a class="external" href="http://msdn2.microsoft.com/en-us/library/0esxc5wy.aspx"></a>.</p>
<p>If <code>length</code> is 0 or negative, <code>substr</code> returns an empty string. If <code>length</code> is omitted, <code>substr</code> extracts characters to the end of the string.</p>
<h3 name="Examples">Examples</h3>
<h4 name="Example:_Using_substr">Example: Using <code>substr</code></h4>
<p>Consider the following script:</p>
<pre class="eval">// assumes a print function is defined
var str = "abcdefghij";
print("(1,2): "    + str.substr(1,2));
print("(-3,2): "   + str.substr(-3,2));
print("(-3): "     + str.substr(-3));
print("(1): "      + str.substr(1));
print("(-20, 2): " + str.substr(-20,2));
print("(20, 2): "  + str.substr(20,2));
</pre>
<p>This script displays:</p>
<pre class="eval">(1,2): bc
(-3,2): hi
(-3): hij
(1): bcdefghij
(-20, 2): ab
(20, 2):
</pre><h3 name="See_also">See also</h3>
<p><a class="internal" href="/en/Core_JavaScript_1.5_Reference/Global_Objects/String/slice" style="text-decoration: none; color: rgb(4, 137, 183) !important; cursor: default; " title="En/Core JavaScript 1.5 Reference/Global Objects/String/Slice">slice</a>, <a href="/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring" title="en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring">substring</a></p>
<p> </p>
<p>{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/String/substr", "fr": "fr/Référence_de_JavaScript_1.5_Core/Objets_globaux/String/substr", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/String/substr", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/String/substr" } ) }}</p>
Revert to this revision