JS_CompareStrings

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_CompareStrings
  • Revision title: JS_CompareStrings
  • Revision id: 147178
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment style, rewriting

Revision Content

{{ Jsapi_ref_header("JS_CompareStrings") }}

Compare two JS strings.

Syntax

intN JS_CompareStrings(JSString *str1, JSString *str2);
Name Type Description
str1 JSString * First string to compare.
str2 JSString * Second string to compare.

Description

JS_CompareStrings compares two JS strings, str1 and str2. If the strings are identical in content and length, JS_CompareStrings returns 0. If str1 is less than str2, the return value is less than 0. If str1 is greater than str2, the return value is greater than 0.

This function imposes a total order on all JavaScript strings, the same order imposed by the JavaScript string comparison operators (<, <=, >, >=), as described in ECMA 262-3 § 11.8.5. As the standard says:

The comparison of strings uses a simple lexicographic ordering on sequences of code point value values. There is no attempt to use the more complex, semantically oriented definitions of character or string equality and collating order defined in the Unicode specification. Therefore strings that are canonically equal according to the Unicode standard could test as unequal.

See Also

{{ LXRSearch("ident", "i", "JS_CompareStrings") }}

JS_ConvertValue, JS_GetStringChars, JS_GetStringLength, JS_ValueToString

Revision Source

<p>{{ Jsapi_ref_header("JS_CompareStrings") }}
</p><p>Compare two JS strings.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval">intN <b>JS_CompareStrings</b>(<a href="en/JSString">JSString</a> *str1, <a href="en/JSString">JSString</a> *str2);
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>str1</code></td>
<td><code><a href="en/JSString">JSString</a> *</code></td>
<td>First string to compare.</td>
</tr>
<tr>
<td><code>str2</code></td>
<td><code><a href="en/JSString">JSString</a> *</code></td>
<td>Second string to compare.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_CompareStrings</code> compares two JS strings, <code>str1</code> and <code>str2</code>. If the strings are identical in content and length, <code>JS_CompareStrings</code> returns <code>0</code>. If <code>str1</code> is less than <code>str2</code>, the return value is less than 0. If <code>str1</code> is greater than <code>str2</code>, the return value is greater than 0.
</p><p>This function imposes a total order on all JavaScript strings, the same order imposed by the JavaScript string comparison operators (<code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>), as described in <a class="external" href="http://bclary.com/2004/11/07/#a-11.8.5">ECMA 262-3 § 11.8.5</a>. As the standard says:
</p>
<blockquote>The comparison of strings uses a simple lexicographic ordering on sequences of code point value values. There is no attempt to use the more complex, semantically oriented definitions of character or string equality and collating order defined in the Unicode specification. Therefore strings that are canonically equal according to the Unicode standard could test as unequal.</blockquote>
<h2 name="See_Also"> See Also </h2>
<p>{{ LXRSearch("ident", "i", "JS_CompareStrings") }}
</p><p><a href="en/JS_ConvertValue">JS_ConvertValue</a>,
<a href="en/JS_GetStringChars">JS_GetStringChars</a>,
<a href="en/JS_GetStringLength">JS_GetStringLength</a>,
<a href="en/JS_ValueToString">JS_ValueToString</a>
</p>
Revert to this revision