String

  • Revision slug: JavaScript/Reference/Global_Objects/String
  • Revision title: String
  • Revision id: 54347
  • Created:
  • Creator: satyr
  • Is current revision? No
  • Comment ES5 15.5.5.2; 4 words added

Revision Content

Summary

String is a global object that may be used to construct String instances.

Syntax

String([string])
new String([string])

String literals take the form:

'stringText'
"stringText"

Parameters

string
Any string.
stringText
Any series of characters that has been properly encoded.

Description

String objects may be created by calling the constructor new String(). The String object wraps JavaScript's string primitive data type with the methods described below. The global function String() can also be called without new in front to create a primitive string. String literals in JavaScript are primitive strings.

Because JavaScript automatically converts between string primitives and String objects, you can call any of the methods of the String object on a string primitive. JavaScript automatically converts the string primitive to a temporary String object, calls the method, then discards the temporary String object. For example, you can use the String.length property on a string primitive created from a string literal:

s_obj = new String(s_prim = s_also_prim = "foo");

s_obj.length;       // 3
s_prim.length;      // 3
s_also_prim.length; // 3
'foo'.length;       // 3
"foo".length;       // 3

(A string literal is denoted with single or double quotation marks.)

String objects can be converted to primitive strings with the valueOf method.

String primitives and String objects give different results when evaluated as JavaScript. Primitives are treated as source code; String objects are treated as a character sequence object. For example:

s1 = "2 + 2";               // creates a string primitive
s2 = new String("2 + 2");   // creates a String object
eval(s1);                   // returns the number 4
eval(s2);                   // returns the string "2 + 2"
eval(s2.valueOf());         // returns the number 4

Character access

There are two ways to access an individual character in a string. The first is the charAt method:

return 'cat'.charAt(1); // returns "a"

The other way is to treat the string as an array, where each index corresponds to an individual character:

return 'cat'[1]; // returns "a"
The second way (treating the string as an array) is not part of ECMAScript 3; it's a JavaScript and ECMAScript 5 feature (and not supported in all browsers).

In both cases, attempting to set an individual character won't work. Trying to set a character through charAt results in an error, while trying to set a character via indexing does not throw an error, but the string itself is unchanged.

Comparing strings

C developers have the strcmp() function for comparing strings. In JavaScript, you just use the less-than and greater-than operators:

var a = "a";
var b = "b";
if (a < b) // true
  print(a + " is less than " + b);
else if (a > b)
  print(a + " is greater than " + b);
else
  print(a + " and " + b + " are equal.");

A similar result can be achieved using the localeCompare method inherited by String instances.

Properties

{{ Js_see_prototype("String", "Properties") }}

prototype
Allows the addition of properties to a String object.
{{ jsOverrides("Function", "Properties", ["prototype"]) }}

Methods

{{ Js_see_prototype("String", "Methods") }}

fromCharCode
Returns a string created by using the specified sequence of Unicode values.
{{ jsOverrides("Function", "Methods", ["fromCharCode"]) }}

String instances

Properties

{{ page('en/JavaScript/Reference/Global_Objects/String/prototype', 'Properties') }}

Methods

{{ page('en/JavaScript/Reference/Global_Objects/String/prototype', 'Methods') }}

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

Revision Source

<h2 name="Summary">Summary</h2>
<p><code>String</code> is a global object that may be used to construct <code>String</code> instances.</p>
<h2 name="Syntax">Syntax</h2>
<p><code>String(</code><code><em>[string]</em></code><code>)</code><br>
<code>new String(<em>[string]</em>)</code></p>
<p>String literals take the form:</p>
<p><code><span class="nowiki">'</span><em>stringText</em><span class="nowiki">'</span></code><br>
<code>"<em>stringText</em>"</code></p>
<h2 name="Parameters">Parameters</h2>
<dl> <dt><code>string</code></dt> <dd>Any string.</dd>
</dl>
<dl> <dt><code>stringText</code></dt> <dd>Any series of characters that has been properly encoded.</dd>
</dl>
<h2 name="Description">Description</h2>
<p>String objects may be created by calling the constructor <code>new String()</code>. The <code>String</code> object wraps JavaScript's string primitive data type with the methods described below. The global function <code>String()</code> can also be called without <code>new</code> in front to create a primitive string. String literals in JavaScript are primitive strings.</p>
<p>Because JavaScript automatically converts between string primitives and String objects, you can call any of the methods of the <code>String</code> object on a string primitive. JavaScript automatically converts the string primitive to a temporary <code>String</code> object, calls the method, then discards the temporary <code>String</code> object. For example, you can use the <code>String.length</code> property on a string primitive created from a string literal:</p>
<pre class="brush: js">s_obj = new String(s_prim = s_also_prim = "foo");

s_obj.length;       // 3
s_prim.length;      // 3
s_also_prim.length; // 3
'foo'.length;       // 3
"foo".length;       // 3
</pre>
<p>(A string literal is denoted with single or double quotation marks.)</p>
<p>String objects can be converted to primitive strings with the <a href="/en/JavaScript/Reference/Global_Objects/String/valueOf" title="en/JavaScript/Reference/Global_Objects/String/valueOf"><code>valueOf</code></a> method.</p>
<p>String primitives and String objects give different results when evaluated as JavaScript. Primitives are treated as source code; String objects are treated as a character sequence object. For example:</p>
<pre class="brush: js">s1 = "2 + 2";               // creates a string primitive
s2 = new String("2 + 2");   // creates a String object
eval(s1);                   // returns the number 4
eval(s2);                   // returns the string "2 + 2"
eval(s2.valueOf());         // returns the number 4
</pre>
<h3 name="Character_access">Character access</h3>
<p>There are two ways to access an individual character in a string. The first is the <a href="/en/JavaScript/Reference/Global_Objects/String/charAt" title="en/JavaScript/Reference/Global_Objects/String/charAt"><code>charAt</code></a> method:</p>
<pre class="brush: js">return 'cat'.charAt(1); // returns "a"
</pre>
<p>The other way is to treat the string as an array, where each index corresponds to an individual character:</p>
<pre class="brush: js">return 'cat'[1]; // returns "a"
</pre>
<div class="note">The second way (treating the string as an array) is not part of ECMAScript 3; it's a JavaScript and ECMAScript 5 feature (and not supported in all browsers).</div>
<p>In both cases, attempting to set an individual character won't work. Trying to set a character through <code>charAt</code> results in an error, while trying to set a character via indexing does not throw an error, but the string itself is unchanged.</p><h3 name="Comparing_strings">Comparing strings</h3>
<p>C developers have the <code>strcmp()</code> function for comparing strings. In JavaScript, you just use the <a href="/en/JavaScript/Reference/Operators/Comparison_Operators" title="en/JavaScript/Reference/Operators/Comparison_Operators">less-than and greater-than operators</a>:</p>
<pre class="brush: js">var a = "a";
var b = "b";
if (a &lt; b) // true
  print(a + " is less than " + b);
else if (a &gt; b)
  print(a + " is greater than " + b);
else
  print(a + " and " + b + " are equal.");
</pre>
<p>A similar result can be achieved using the <a href="/en/JavaScript/Reference/Global_Objects/String/localeCompare" title="en/JavaScript/Reference/Global_Objects/String/localeCompare"><code>localeCompare</code></a> method inherited by <code>String</code> instances.</p>
<h2 name="Properties">Properties</h2>
<p>{{ Js_see_prototype("String", "Properties") }}</p>
<dl> <dt><a href="/en/JavaScript/Reference/Global_Objects/String/prototype" title="en/JavaScript/Reference/Global_Objects/String/prototype"><code>prototype</code></a></dt> <dd>Allows the addition of properties to a String object.</dd>
</dl>
<div>{{ jsOverrides("Function", "Properties", ["prototype"]) }}</div>
<h2 name="Methods">Methods</h2>
<p>{{ Js_see_prototype("String", "Methods") }}</p>
<dl> <dt><a href="/en/JavaScript/Reference/Global_Objects/String/fromCharCode" title="en/JavaScript/Reference/Global_Objects/String/fromCharCode"><code>fromCharCode</code></a></dt> <dd>Returns a string created by using the specified sequence of Unicode values.</dd>
</dl>
<div>{{ jsOverrides("Function", "Methods", ["fromCharCode"]) }}</div>
<h2 name="String_instances"><code>String</code> instances</h2>
<h3>Properties</h3>
<p>{{ page('en/JavaScript/Reference/Global_Objects/String/prototype', 'Properties') }}</p>
<h3>Methods</h3>
<p>{{ page('en/JavaScript/Reference/Global_Objects/String/prototype', 'Methods') }}</p>
<p>{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/String", "fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Objets_globaux/String", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/String", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/String" } ) }}</p>
Revert to this revision