docs/source/String.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='String'>/**
  19 </span> * @class String
  20  *
  21  * `String` is a global object that may be used to construct String instances.
  22  *
  23  * String objects may be created by calling the constructor `new String()`. The `String` object wraps
  24  * JavaScript's string primitive data type with the methods described below. The global function
  25  * `String()` can also be called without new in front to create a primitive string. String literals in
  26  * JavaScript are primitive strings.
  27  *
  28  * Because JavaScript automatically converts between string primitives and String objects, you can call
  29  * any of the methods of the `String` object on a string primitive. JavaScript automatically converts the
  30  * string primitive to a temporary `String` object, calls the method, then discards the temporary String
  31  * object. For example, you can use the `String.length` property on a string primitive created from a
  32  * string literal:
  33  *
  34  *     s_obj = new String(s_prim = s_also_prim = &quot;foo&quot;);
  35  *
  36  *     s_obj.length;       // 3
  37  *     s_prim.length;      // 3
  38  *     s_also_prim.length; // 3
  39  *     'foo'.length;       // 3
  40  *     &quot;foo&quot;.length;       // 3
  41  *
  42  * (A string literal is denoted with single or double quotation marks.)
  43  *
  44  * String objects can be converted to primitive strings with the `valueOf` method.
  45  *
  46  * String primitives and String objects give different results when evaluated as JavaScript. Primitives
  47  * are treated as source code; String objects are treated as a character sequence object. For example:
  48  *
  49  *     s1 = &quot;2 + 2&quot;;               // creates a string primitive
  50  *     s2 = new String(&quot;2 + 2&quot;);   // creates a String object
  51  *     eval(s1);                   // returns the number 4
  52  *     eval(s2);                   // returns the string &quot;2 + 2&quot;
  53  *     eval(s2.valueOf());         // returns the number 4
  54  *
  55  * # Character access
  56  *
  57  * There are two ways to access an individual character in a string. The first is the `charAt` method:
  58  *
  59  *     return 'cat'.charAt(1); // returns &quot;a&quot;
  60  *
  61  * The other way is to treat the string as an array, where each index corresponds to an individual
  62  * character:
  63  *
  64  *     return 'cat'[1]; // returns &quot;a&quot;
  65  *
  66  * The second way (treating the string as an array) is not part of ECMAScript 3. It is a JavaScript and
  67  * ECMAScript 5 feature.
  68  *
  69  * In both cases, attempting to set an individual character won't work. Trying to set a character
  70  * through `charAt` results in an error, while trying to set a character via indexing does not throw an
  71  * error, but the string itself is unchanged.
  72  *
  73  * # Comparing strings
  74  *
  75  * C developers have the `strcmp()` function for comparing strings. In JavaScript, you just use the less-
  76  * than and greater-than operators:
  77  *
  78  *     var a = &quot;a&quot;;
  79  *     var b = &quot;b&quot;;
  80  *     if (a &lt; b) // true
  81  *         print(a + &quot; is less than &quot; + b);
  82  *     else if (a &gt; b)
  83  *         print(a + &quot; is greater than &quot; + b);
  84  *     else
  85  *         print(a + &quot; and &quot; + b + &quot; are equal.&quot;);
  86  *
  87  * A similar result can be achieved using the `localeCompare` method inherited by `String` instances.
  88  *
  89  * &lt;div class=&quot;notice&quot;&gt;
  90  * Documentation for this class comes from &lt;a href=&quot;https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String&quot;&gt;MDN&lt;/a&gt;
  91  * and is available under &lt;a href=&quot;http://creativecommons.org/licenses/by-sa/2.0/&quot;&gt;Creative Commons: Attribution-Sharealike license&lt;/a&gt;.
  92  * &lt;/div&gt;
  93  */
  94
  95 <span id='String-method-constructor'>/**
  96 </span> * @method constructor
  97  * Creates new String object.
  98  * @param {Object} value The value to wrap into String object.
  99  */
 100
 101 //Methods
 102
 103 <span id='String-method-fromCharCode'>/**
 104 </span> * @method fromCharCode
 105  * Returns a string created by using the specified sequence of Unicode values.
 106  *
 107  * This method returns a string and not a `String` object.
 108  *
 109  * Because `fromCharCode` is a static method of `String`, you always use it as `String.fromCharCode()`,
 110  * rather than as a method of a `String` object you created.
 111  *
 112  * Although most common Unicode values can be represented in a fixed width system/with one number (as
 113  * expected early on during JavaScript standardization) and `fromCharCode()` can be used to return a
 114  * single character for the most common values (i.e., UCS-2 values which are the subset of UTF-16 with
 115  * the most common characters), in order to deal with ALL legal Unicode values, `fromCharCode()` alone
 116  * is inadequate. Since the higher code point characters use two (lower value) &quot;surrogate&quot; numbers to
 117  * form a single character, `fromCharCode()` can be used to return such a pair and thus adequately
 118  * represent these higher valued characters.
 119  *
 120  * Be aware, therefore, that the following utility function to grab the accurate character even for
 121  * higher value code points, may be returning a value which is rendered as a single character, but
 122  * which has a string count of two (though usually the count will be one).
 123  *
 124  *     // String.fromCharCode() alone cannot get the character at such a high code point
 125  *     // The following, on the other hand, can return a 4-byte character as well as the
 126  *     //   usual 2-byte ones (i.e., it can return a single character which actually has
 127  *     //   a string length of 2 instead of 1!)
 128  *     alert(fixedFromCharCode(0x2F804)); // or 194564 in decimal
 129  *
 130  *     function fixedFromCharCode (codePt) {
 131  *         if (codePt &gt; 0xFFFF) {
 132  *             codePt -= 0x10000;
 133  *             return String.fromCharCode(0xD800 + (codePt &gt;&gt; 10), 0xDC00 +
 134  *             (codePt &amp; 0x3FF));
 135  *         }
 136  *         else {
 137  *             return String.fromCharCode(codePt);
 138  *         }
 139  *     }
 140  *
 141  * The following example returns the string &quot;ABC&quot;.
 142  *
 143  *     String.fromCharCode(65,66,67)
 144  *
 145  * @param {Number} num1, ..., numN A sequence of numbers that are Unicode values.
 146  * @return {String} String containing characters from encoding.
 147  */
 148
 149 //Properties
 150
 151 <span id='String-property-length'>/**
 152 </span> * @property {Number} length
 153  * Reflects the length of the string.
 154  *
 155  * This property returns the number of code units in the string. UTF-16, the string format used by JavaScript, uses a single 16-bit
 156  * code unit to represent the most common characters, but needs to use two code units for less commonly-used characters, so it's
 157  * possible for the value returned by `length` to not match the actual number of characters in the string.
 158  *
 159  * For an empty string, `length` is 0.
 160  *
 161  *     var x = &quot;Netscape&quot;;
 162  *     var empty = &quot;&quot;;
 163  *
 164  *     console.log(&quot;Netspace is &quot; + x.length + &quot; code units long&quot;);
 165  *     console.log(&quot;The empty string is has a length of &quot; + empty.length); // should be 0
 166  */
 167
 168 //Methods
 169
 170 <span id='String-method-charAt'>/**
 171 </span> * @method charAt
 172  * Returns the character at the specified index.
 173  *
 174  * Characters in a string are indexed from left to right. The index of the first character is 0, and
 175  * the index of the last character in a string called `stringName` is `stringName.length - 1`. If the
 176  * index you supply is out of range, JavaScript returns an empty string.
 177  *
 178  * The following example displays characters at different locations in the string &quot;Brave new world&quot;:
 179  *
 180  *     var anyString=&quot;Brave new world&quot;;
 181  *
 182  *     document.writeln(&quot;The character at index 0 is '&quot; + anyString.charAt(0) + &quot;'&quot;);
 183  *     document.writeln(&quot;The character at index 1 is '&quot; + anyString.charAt(1) + &quot;'&quot;);
 184  *     document.writeln(&quot;The character at index 2 is '&quot; + anyString.charAt(2) + &quot;'&quot;);
 185  *     document.writeln(&quot;The character at index 3 is '&quot; + anyString.charAt(3) + &quot;'&quot;);
 186  *     document.writeln(&quot;The character at index 4 is '&quot; + anyString.charAt(4) + &quot;'&quot;);
 187  *     document.writeln(&quot;The character at index 999 is '&quot; + anyString.charAt(999) + &quot;'&quot;);
 188  *
 189  * These lines display the following:
 190  *
 191  *     The character at index 0 is 'B'
 192  *     The character at index 1 is 'r'
 193  *     The character at index 2 is 'a'
 194  *     The character at index 3 is 'v'
 195  *     The character at index 4 is 'e'
 196  *     The character at index 999 is ''
 197  *
 198  * The following provides a means of ensuring that going through a string loop always provides a whole
 199  * character, even if the string contains characters that are not in the Basic Multi-lingual Plane.
 200  *
 201  *     var str = 'A\uD87E\uDC04Z'; // We could also use a non-BMP character directly
 202  *     for (var i=0, chr; i &lt; str.length; i++) {
 203  *         if ((chr = getWholeChar(str, i)) === false) {continue;} // Adapt this line at the top of
 204  * each loop, passing in the whole string and the current iteration and returning a variable to
 205  * represent the individual character
 206  *         alert(chr);
 207  *     }
 208  *
 209  *     function getWholeChar (str, i) {
 210  *         var code = str.charCodeAt(i);
 211  *
 212  *         if (isNaN(code)) {
 213  *         return ''; // Position not found
 214  *         }
 215  *         if (code &lt; 0xD800 || code &gt; 0xDFFF) {
 216  *             return str.charAt(i);
 217  *         }
 218  *         if (0xD800 &lt;= code &amp;&amp; code &lt;= 0xDBFF) { // High surrogate (could change last hex to 0xDB7F
 219  * to treat high private surrogates as single characters)
 220  *         if (str.length &lt;= (i+1))  {
 221  *             throw 'High surrogate without following low surrogate';
 222  *         }
 223  *         var next = str.charCodeAt(i+1);
 224  *         if (0xDC00 &gt; next || next &gt; 0xDFFF) {
 225  *             throw 'High surrogate without following low surrogate';
 226  *         }
 227  *         return str.charAt(i)+str.charAt(i+1);
 228  *     }
 229  *     // Low surrogate (0xDC00 &lt;= code &amp;&amp; code &lt;= 0xDFFF)
 230  *     if (i === 0) {
 231  *         throw 'Low surrogate without preceding high surrogate';
 232  *     }
 233  *     var prev = str.charCodeAt(i-1);
 234  *     if (0xD800 &gt; prev || prev &gt; 0xDBFF) { // (could change last hex to 0xDB7F to treat high private
 235  * surrogates as single characters)
 236  *       throw 'Low surrogate without preceding high surrogate';
 237  *     }
 238  *     return false; // We can pass over low surrogates now as the second component in a pair which we
 239  * have already processed
 240  * }
 241  *
 242  * While the second example may be more frequently useful for those wishing to support non-BMP
 243  * characters (since the above does not require the caller to know where any non-BMP character might
 244  * appear), in the event that one _does_ wish, in choosing a character by index, to treat the surrogate
 245  * pairs within a string as the single characters they represent, one can use the following:
 246  *
 247  *     function fixedCharAt (str, idx) {
 248  *         var ret = '';
 249  *         str += '';
 250  *         var end = str.length;
 251  *
 252  *         var surrogatePairs = /[\uD800-\uDBFF][\uDC00-\uDFFF]/g;
 253  *         while ((surrogatePairs.exec(str)) != null) {
 254  *             var li = surrogatePairs.lastIndex;
 255  *             if (li - 2 &lt; idx) {
 256  *                 idx++;
 257  *             }
 258  *             else {
 259  *             break;
 260  *         }
 261  *     }
 262  *
 263  *     if (idx &gt;= end || idx &lt; 0) {
 264  *         return '';
 265  *     }
 266  *
 267  *     ret += str.charAt(idx);
 268  *
 269  *     if (/[\uD800-\uDBFF]/.test(ret) &amp;&amp; /[\uDC00-\uDFFF]/.test(str.charAt(idx+1))) {
 270  *         ret += str.charAt(idx+1); // Go one further, since one of the &quot;characters&quot; is part of a
 271  * surrogate pair
 272  *     }
 273  *     return ret;
 274  *     }
 275  *
 276  * @param {Number} index An integer between 0 and 1 less than the length of the string.
 277  * @return {String} Individual character from string.
 278  */
 279
 280 <span id='String-method-charCodeAt'>/**
 281 </span> * @method charCodeAt
 282  * Returns a number indicating the Unicode value of the character at the given index.
 283  *
 284  * Unicode code points range from 0 to 1,114,111. The first 128 Unicode code points are a direct match
 285  * of the ASCII character encoding.
 286  *
 287  * Note that `charCodeAt` will always return a value that is less than 65,536. This is because the
 288  * higher code points are represented by a pair of (lower valued) &quot;surrogate&quot; pseudo-characters which
 289  * are used to comprise the real character. Because of this, in order to examine or reproduce the full
 290  * character for individual characters of value 65,536 and above, for such characters, it is necessary
 291  * to retrieve not only `charCodeAt(i)`, but also `charCodeAt(i+1)` (as if examining/reproducing a
 292  * string with two letters). See example 2 and 3 below.
 293  *
 294  * `charCodeAt` returns `NaN` if the given index is not greater than 0 or is greater than the length of
 295  * the string.
 296  *
 297  * Backward Compatibility with JavaScript 1.2
 298  *
 299  * The `charCodeAt` method returns a number indicating the ISO-Latin-1 codeset value of the character
 300  * at the given index. The ISO-Latin-1 codeset ranges from 0 to 255. The first 0 to 127 are a direct
 301  * match of the ASCII character set.
 302  *
 303  * Example 1: Using `charCodeAt`
 304  *
 305  * The following example returns 65, the Unicode value for A.
 306  *
 307  *    &quot;ABC&quot;.charCodeAt(0) // returns 65
 308  *
 309  * Example 2: Fixing `charCodeAt` to handle non-Basic-Multilingual-Plane characters if their presence
 310  * earlier in the string is unknown
 311  *
 312  * This version might be used in for loops and the like when it is unknown whether non-BMP characters
 313  * exist before the specified index position.
 314  *
 315  *     function fixedCharCodeAt (str, idx) {
 316  *         // ex. fixedCharCodeAt ('\uD800\uDC00', 0); // 65536
 317  *         // ex. fixedCharCodeAt ('\uD800\uDC00', 1); // 65536
 318  *         idx = idx || 0;
 319  *         var code = str.charCodeAt(idx);
 320  *         var hi, low;
 321  *         if (0xD800 &lt;= code &amp;&amp; code &lt;= 0xDBFF) { // High surrogate (could change last hex to 0xDB7F to treat high private surrogates as single characters)
 322  *             hi = code;
 323  *             low = str.charCodeAt(idx+1);
 324  *             if (isNaN(low)) {
 325  *                 throw 'High surrogate not followed by low surrogate in fixedCharCodeAt()';
 326  *             }
 327  *             return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;
 328  *         }
 329  *         if (0xDC00 &lt;= code &amp;&amp; code &lt;= 0xDFFF) { // Low surrogate
 330  *         // We return false to allow loops to skip this iteration since should have already handled
 331  * high surrogate above in the previous iteration
 332  *             return false;
 333  *         }
 334  *         return code;
 335  *     }
 336  *
 337  * Example 3: Fixing `charCodeAt` to handle non-Basic-Multilingual-Plane characters if their presence
 338  * earlier in the string is known
 339  *
 340  *     function knownCharCodeAt (str, idx) {
 341  *         str += '';
 342  *         var code,
 343  *         end = str.length;
 344  *
 345  *         var surrogatePairs = /[\uD800-\uDBFF][\uDC00-\uDFFF]/g;
 346  *         while ((surrogatePairs.exec(str)) != null) {
 347  *             var li = surrogatePairs.lastIndex;
 348  *             if (li - 2 &lt; idx) {
 349  *                 idx++;
 350  *             }
 351  *             else {
 352  *                 break;
 353  *             }
 354  *         }
 355  *
 356  *         if (idx &gt;= end || idx &lt; 0) {
 357  *             return NaN;
 358  *         }
 359  *
 360  *         code = str.charCodeAt(idx);
 361  *
 362  *         var hi, low;
 363  *         if (0xD800 &lt;= code &amp;&amp; code &lt;= 0xDBFF) {
 364  *             hi = code;
 365  *             low = str.charCodeAt(idx+1); // Go one further, since one of the &quot;characters&quot; is part of
 366  * a surrogate pair
 367  *             return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;
 368  *         }
 369  *         return code;
 370  *     }
 371  *
 372  * @param {Number} index An integer greater than 0 and less than the length of the string; if it is
 373  * not a number, it defaults to 0.
 374  * @return {Number} Value between 0 and 65535.
 375  */
 376
 377 <span id='String-method-concat'>/**
 378 </span> * @method concat
 379  * Combines the text of two strings and returns a new string.
 380  *
 381  * `concat` combines the text from one or more strings and returns a new string. Changes to the text in
 382  * one string do not affect the other string.
 383  *
 384  * The following example combines strings into a new string.
 385  *
 386  *     var hello = &quot;Hello, &quot;;
 387  *     console.log(hello.concat(&quot;Kevin&quot;, &quot; have a nice day.&quot;)); // Hello, Kevin have a nice day.
 388  *
 389  * @param {String} string2...stringN
 390  * @return {String} Result of both strings.
 391  */
 392
 393 <span id='String-method-indexOf'>/**
 394 </span> * @method indexOf
 395  * Returns the index within the calling `String` object of the first occurrence of the specified value,
 396  * or -1 if not found.
 397  *
 398  * Characters in a string are indexed from left to right. The index of the first character is 0, and the index of the last character
 399  * of a string called `stringName` is `stringName.length - 1`.
 400  *
 401  *     &quot;Blue Whale&quot;.indexOf(&quot;Blue&quot;)    // returns 0
 402  *     &quot;Blue Whale&quot;.indexOf(&quot;Blute&quot;)   // returns -1
 403  *     &quot;Blue Whale&quot;.indexOf(&quot;Whale&quot;,0) // returns 5
 404  *     &quot;Blue Whale&quot;.indexOf(&quot;Whale&quot;,5) // returns 5
 405  *     &quot;Blue Whale&quot;.indexOf(&quot;&quot;,9)      // returns 9
 406  *     &quot;Blue Whale&quot;.indexOf(&quot;&quot;,10)     // returns 10
 407  *     &quot;Blue Whale&quot;.indexOf(&quot;&quot;,11)     // returns 10
 408  *
 409  * The `indexOf` method is case sensitive. For example, the following expression returns -1:
 410  *
 411  *     &quot;Blue Whale&quot;.indexOf(&quot;blue&quot;)
 412  *
 413  * Note that '0' doesn't evaluate to true and '-1' doesn't evaluate to false. Therefore, when checking if a specific string exists
 414  * within another string the correct way to check would be:
 415  *
 416  *     &quot;Blue Whale&quot;.indexOf(&quot;Blue&quot;) != -1 // true
 417  *     &quot;Blue Whale&quot;.indexOf(&quot;Bloe&quot;) != -1 // false
 418  *
 419  * The following example uses indexOf and lastIndexOf to locate values in the string &quot;Brave new world&quot;.
 420  *
 421  *     var anyString=&quot;Brave new world&quot;
 422  *
 423  *     document.write(&quot;&lt;P&gt;The index of the first w from the beginning is &quot; + anyString.indexOf(&quot;w&quot;))          // Displays 8
 424  *     document.write(&quot;&lt;P&gt;The index of the first w from the end is &quot; + anyString.lastIndexOf(&quot;w&quot;))      // Displays 10
 425  *     document.write(&quot;&lt;P&gt;The index of 'new' from the beginning is &quot; + anyString.indexOf(&quot;new&quot;))        // Displays 6
 426  *     document.write(&quot;&lt;P&gt;The index of 'new' from the end is &quot; + anyString.lastIndexOf(&quot;new&quot;))    // Displays 6
 427  *
 428  * The following example defines two string variables. The variables contain the same string except that the second string contains
 429  * uppercase letters. The first `writeln` method displays 19. But because the `indexOf` method is case sensitive, the string
 430  * &quot;cheddar&quot; is not found in `myCapString`, so the second `writeln` method displays -1.
 431  *
 432  *     myString=&quot;brie, pepper jack, cheddar&quot;
 433  *     myCapString=&quot;Brie, Pepper Jack, Cheddar&quot;
 434  *     document.writeln('myString.indexOf(&quot;cheddar&quot;) is ' + myString.indexOf(&quot;cheddar&quot;))
 435  *     document.writeln('&lt;P&gt;myCapString.indexOf(&quot;cheddar&quot;) is ' + myCapString.indexOf(&quot;cheddar&quot;))
 436  *
 437  * The following example sets count to the number of occurrences of the letter x in the string str:
 438  *
 439  *     count = 0;
 440  *     pos = str.indexOf(&quot;x&quot;);
 441  *     while ( pos != -1 ) {
 442  *         count++;
 443  *         pos = str.indexOf(&quot;x&quot;,pos+1);
 444  *     }
 445  *
 446  * @param {String} searchValue A string representing the value to search for.
 447  * @param {Number} fromIndex The location within the calling string to start the search from. It can be any integer between 0 and
 448  * the length of the string. The default value is 0.
 449  * @return {Number} Position of specified value or -1 if not found.
 450  */
 451
 452 <span id='String-method-lastIndexOf'>/**
 453 </span> * @method lastIndexOf
 454  * Returns the index within the calling String object of the last occurrence of
 455  * the specified value, or -1 if not found. The calling string is searched
 456  * backward, starting at fromIndex.
 457  *
 458  * Characters in a string are indexed from left to right. The index of the first character is 0, and the index of the last character
 459  * is `stringName.length - 1`.
 460  *
 461  *     &quot;canal&quot;.lastIndexOf(&quot;a&quot;)   // returns 3
 462  *     &quot;canal&quot;.lastIndexOf(&quot;a&quot;,2) // returns 1
 463  *     &quot;canal&quot;.lastIndexOf(&quot;a&quot;,0) // returns -1
 464  *     &quot;canal&quot;.lastIndexOf(&quot;x&quot;)   // returns -1
 465  *
 466  * The `lastIndexOf` method is case sensitive. For example, the following expression returns -1:
 467  *
 468  *     &quot;Blue Whale, Killer Whale&quot;.lastIndexOf(&quot;blue&quot;)
 469  *
 470  * The following example uses `indexOf` and `lastIndexOf` to locate values in the string &quot;`Brave new world`&quot;.
 471  *
 472  *     var anyString=&quot;Brave new world&quot;
 473  *
 474  *     // Displays 8
 475  *     document.write(&quot;&lt;P&gt;The index of the first w from the beginning is &quot; +
 476  *     anyString.indexOf(&quot;w&quot;))
 477  *     // Displays 10
 478  *     document.write(&quot;&lt;P&gt;The index of the first w from the end is &quot; +
 479  *     anyString.lastIndexOf(&quot;w&quot;))
 480  *     // Displays 6
 481  *     document.write(&quot;&lt;P&gt;The index of 'new' from the beginning is &quot; +
 482  *     anyString.indexOf(&quot;new&quot;))
 483  *     // Displays 6
 484  *     document.write(&quot;&lt;P&gt;The index of 'new' from the end is &quot; +
 485  *     anyString.lastIndexOf(&quot;new&quot;))
 486  *
 487  * @param {String} searchValue A string representing the value to search for.
 488  * @param {Number} fromIndex The location within the calling string to start the search from, indexed from left to right. It can
 489  * be any integer between 0 and the length of the string. The default value is the length of the string.
 490  * @return {Number}
 491  */
 492
 493 <span id='String-method-localeCompare'>/**
 494 </span> * @method localeCompare
 495  * Returns a number indicating whether a reference string comes before or after or is the same as the
 496  * given string in sort order.
 497  *
 498  * Returns a number indicating whether a reference string comes before or after or is the same as the
 499  * given string in sort order. Returns -1 if the string occurs earlier in a sort than `compareString`,
 500  * returns 1 if the string occurs afterwards in such a sort, and returns 0 if they occur at the same
 501  * level.
 502  *
 503  * The following example demonstrates the different potential results for a string occurring before,
 504  * after, or at the same level as another:
 505  *
 506  *     alert('a'.localeCompare('b')); // -1
 507  *     alert('b'.localeCompare('a')); // 1
 508  *     alert('b'.localeCompare('b')); // 0
 509  *
 510  * @param {String} compareString The string against which the referring string is comparing.
 511  * @return {Number} Returns -1 if the string occurs earlier in a sort than
 512  * compareString, returns 1 if the string occurs afterwards in such a sort, and
 513  * returns 0 if they occur at the same level.
 514  */
 515
 516 <span id='String-method-match'>/**
 517 </span> * @method match
 518  * Used to match a regular expression against a string.
 519  *
 520  * If the regular expression does not include the `g` flag, returns the same result as `regexp.exec(string)`.
 521  *
 522  * If the regular expression includes the `g` flag, the method returns an Array containing all matches. If there were no matches,
 523  * the method returns `null`.
 524  *
 525  * The returned {@link Array} has an extra `input` property, which contains the regexp that generated it as a result. In addition,
 526  * it has an `index` property, which represents the zero-based index of the match in the string.
 527  *
 528  * In the following example, `match` is used to find &quot;Chapter&quot; followed by 1 or more numeric characters followed by a decimal point
 529  * and numeric character 0 or more times. The regular expression includes the `i` flag so that case will be ignored.
 530  *
 531  *     str = &quot;For more information, see Chapter 3.4.5.1&quot;;
 532  *     re = /(chapter \d+(\.\d)*)/i;
 533  *     found = str.match(re);
 534  *     document.write(found);
 535  *
 536  * This returns the array containing Chapter 3.4.5.1,Chapter 3.4.5.1,.1
 537  *
 538  * &quot;`Chapter 3.4.5.1`&quot; is the first match and the first value remembered from `(Chapter \d+(\.\d)*)`.
 539  *
 540  * &quot;`.1`&quot; is the second value remembered from `(\.\d)`.
 541  *
 542  * The following example demonstrates the use of the global and ignore case flags with `match`. All letters A through E and a
 543  * through e are returned, each its own element in the array
 544  *
 545  *     var str = &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz&quot;;
 546  *     var regexp = /[A-E]/gi;
 547  *     var matches_array = str.match(regexp);
 548  *     document.write(matches_array);
 549  *
 550  * `matches_array` now equals `['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']`.
 551  *
 552  * @param {RegExp} regexp A {@link RegExp} object. If a non-RegExp object `obj` is passed, it is
 553  * implicitly converted to a RegExp by using `new RegExp(obj)`.
 554  * @return {Array} Contains results of the match (if any).
 555  */
 556
 557 <span id='String-method-replace'>/**
 558 </span> * @method replace
 559  * Used to find a match between a regular expression and a string, and to replace the matched substring
 560  * with a new substring.
 561  *
 562  * This method does not change the `String` object it is called on. It simply returns a new string.
 563  *
 564  * To perform a global search and replace, either include the `g` flag in the regular expression or if
 565  * the first parameter is a string, include `g` in the flags parameter.
 566  *
 567  * The replacement string can include the following special replacement patterns:
 568  *
 569  * | Pattern       | Inserts
 570  * |:--------------|:--------------------------------------------------------------------------------------
 571  * | `$$`          | Inserts a `$`.
 572  * | `$&amp;`          | Inserts the matched substring.
 573  * | `$``          | Inserts the portion of the string that precedes the matched substring.
 574  * | `$'`          | Inserts the portion of the string that follows the matched substring.
 575  * | `$n` or `$nn` | Where `n` or `nn` are decimal digits, inserts the _n_th parenthesized submatch string, provided the first
 576  * |               | argument was a `RegExp` object.
 577  *
 578  * You can specify a function as the second parameter. In this case, the function will be invoked after the match has been
 579  * performed. The function's result (return value) will be used as the replacement string. (Note: the above-mentioned special
 580  * replacement patterns do not apply in this case.) Note that the function will be invoked multiple times for each full match to be
 581  * replaced if the regular expression in the first parameter is global.
 582  *
 583  * The arguments to the function are as follows:
 584  *
 585  * | Possible Name | Supplied Value
 586  * |:--------------|:--------------------------------------------------------------------------------------
 587  * | `str`         | The matched substring. (Corresponds to `$&amp;` above.)
 588  * | `p1, p2, ...` | The _n_th parenthesized submatch string, provided the first argument to replace was a `RegExp` object.
 589  * |               | (Correspond to $1, $2, etc. above.)
 590  * | `offset`      | The offset of the matched substring within the total string being examined. (For example, if the total string
 591  * |               | was &quot;`abcd`&quot;, and the matched substring was &quot;`bc`&quot;, then this argument will be 1.)
 592  * | `s`           | The total string being examined.
 593  *
 594  * (The exact number of arguments will depend on whether the first argument was a `RegExp` object and, if so, how many parenthesized
 595  * submatches it specifies.)
 596  *
 597  * The following example will set `newString` to &quot;`XXzzzz - XX , zzzz`&quot;:
 598  *
 599  *     function replacer(str, p1, p2, offset, s)
 600  *     {
 601  *         return str + &quot; - &quot; + p1 + &quot; , &quot; + p2;
 602  *     }
 603  *     var newString = &quot;XXzzzz&quot;.replace(/(X*)(z*)/, replacer);
 604  *
 605  * In the following example, the regular expression includes the global and ignore case flags which permits replace to replace each
 606  * occurrence of 'apples' in the string with 'oranges'.
 607  *
 608  *     var re = /apples/gi;
 609  *     var str = &quot;Apples are round, and apples are juicy.&quot;;
 610  *     var newstr = str.replace(re, &quot;oranges&quot;);
 611  *     print(newstr);
 612  *
 613  * In this version, a string is used as the first parameter and the global and ignore case flags are specified in the flags
 614  * parameter.
 615  *
 616  *     var str = &quot;Apples are round, and apples are juicy.&quot;;
 617  *     var newstr = str.replace(&quot;apples&quot;, &quot;oranges&quot;, &quot;gi&quot;);
 618  *     print(newstr);
 619  *
 620  * Both of these examples print &quot;oranges are round, and oranges are juicy.&quot;
 621  *
 622  * In the following example, the regular expression is defined in replace and includes the ignore case flag.
 623  *
 624  *     var str = &quot;Twas the night before Xmas...&quot;;
 625  *     var newstr = str.replace(/xmas/i, &quot;Christmas&quot;);
 626  *     print(newstr);
 627  *
 628  * This prints &quot;Twas the night before Christmas...&quot;
 629  *
 630  * The following script switches the words in the string. For the replacement text, the script uses the $1 and $2 replacement
 631  * patterns.
 632  *
 633  *     var re = /(\w+)\s(\w+)/;
 634  *     var str = &quot;John Smith&quot;;
 635  *     var newstr = str.replace(re, &quot;$2, $1&quot;);
 636  *     print(newstr);
 637  *
 638  * This prints &quot;Smith, John&quot;.
 639  *
 640  * In this example, all occurrences of capital letters in the string are converted to lower case, and a hyphen is inserted just
 641  * before the match location. The important thing here is that additional operations are needed on the matched item before it is
 642  * given back as a replacement.
 643  *
 644  * The replacement function accepts the matched snippet as its parameter, and uses it to transform the case and concatenate the
 645  * hyphen before returning.
 646  *
 647  *     function styleHyphenFormat(propertyName)
 648  *     {
 649  *         function upperToHyphenLower(match)
 650  *         {
 651  *             return '-' + match.toLowerCase();
 652  *         }
 653  *         return propertyName.replace(/[A-Z]/, upperToHyphenLower);
 654  *     }
 655  *
 656  * Given `styleHyphenFormat('borderTop')`, this returns 'border-top'.
 657  *
 658  * Because we want to further transform the _result_ of the match before the final substitution is made, we must use a function.
 659  * This forces the evaluation of the match prior to the `toLowerCase()` method. If we had tried to do this using the match without a
 660  *  function, the `toLowerCase()` would have no effect.
 661  *
 662  *     var newString = propertyName.replace(/[A-Z]/, '-' + '$&amp;'.toLowerCase());  // won't work
 663  *
 664  * This is because `'$&amp;'.toLowerCase()` would be evaluated first as a string literal (resulting in the same `'$&amp;'`) before using the
 665  * characters as a pattern.
 666  *
 667  * The following example replaces a Fahrenheit degree with its equivalent Celsius degree. The Fahrenheit degree should be a number
 668  * ending with F. The function returns the Celsius number ending with C. For example, if the input number is 212F, the function
 669  *  returns 100C. If the number is 0F, the function returns -17.77777777777778C.
 670  *
 671  * The regular expression `test` checks for any number that ends with F. The number of Fahrenheit degree is accessible to the
 672  * function through its second parameter, `p1`. The function sets the Celsius number based on the Fahrenheit degree passed in a
 673  * string to the `f2c` function. `f2c` then returns the Celsius number. This function approximates Perl's `s///e` flag.
 674  *
 675  *     function f2c(x)
 676  *     {
 677  *         function convert(str, p1, offset, s)
 678  *         {
 679  *             return ((p1-32) * 5/9) + &quot;C&quot;;
 680  *         }
 681  *         var s = String(x);
 682  *         var test = /(\d+(?:\.\d*)?)F\b/g;
 683  *         return s.replace(test, convert);
 684  *     }
 685  *
 686  * @param {RegExp} regexp A RegExp object. The match is replaced by the return value of parameter #2.
 687  * @param {String} substr A String that is to be replaced by `newSubStr`.
 688  * @param {String} newSubStr The String that replaces the substring received from parameter #1. A
 689  * number of special replacement patterns are supported; see the &quot;Specifying a string as a parameter&quot;
 690  * section below.
 691  * @param {Function} function A function to be invoked to create the new substring (to put in place
 692  * of the substring received from parameter #1). The arguments supplied to this function are described
 693  * in the &quot;Specifying a function as a parameter&quot; section below.
 694  * @return {String} String of matched replaced items.
 695  */
 696
 697 <span id='String-method-search'>/**
 698 </span> * @method search
 699  * Executes the search for a match between a regular expression and a specified string.
 700  *
 701  * If successful, search returns the index of the regular expression inside the string. Otherwise, it
 702  * returns -1.
 703  *
 704  * When you want to know whether a pattern is found in a string use search (similar to the regular
 705  * expression `test` method); for more information (but slower execution) use `match` (similar to the
 706  * regular expression `exec` method).
 707  *
 708  * The following example prints a message which depends on the success of the test.
 709  *
 710  *     function testinput(re, str){
 711  *         if (str.search(re) != -1)
 712  *             midstring = &quot; contains &quot;;
 713  *         else
 714  *             midstring = &quot; does not contain &quot;;
 715  *         document.write (str + midstring + re);
 716  *     }
 717  *
 718  * @param {RegExp} regexp A regular expression object. If a non-RegExp object obj is passed, it is
 719  * implicitly converted to a RegExp by using `new RegExp(obj)`.
 720  * @return {Number} If successful, search returns the index of the regular
 721  * expression inside the string. Otherwise, it returns -1.
 722  */
 723
 724 <span id='String-method-slice'>/**
 725 </span> * @method slice
 726  * Extracts a section of a string and returns a new string.
 727  *
 728  * `slice` extracts the text from one string and returns a new string. Changes to the text in one
 729  * string do not affect the other string.
 730  *
 731  * `slice` extracts up to but not including `endSlice`. `string.slice(1,4)` extracts the second
 732  * character through the fourth character (characters indexed 1, 2, and 3).
 733  *
 734  * As a negative index, `endSlice` indicates an offset from the end of the string. `string.slice(2,-1)`
 735  * extracts the third character through the second to last character in the string.
 736  *
 737  * The following example uses slice to create a new string.
 738  *
 739  *     // assumes a print function is defined
 740  *     var str1 = &quot;The morning is upon us.&quot;;
 741  *     var str2 = str1.slice(4, -2);
 742  *     print(str2);
 743  *
 744  * This writes:
 745  *
 746  *     morning is upon u
 747  *
 748  * @param {Number} beginSlice The zero-based index at which to begin extraction.
 749  * @param {Number} endSlice The zero-based index at which to end extraction. If omitted, `slice`
 750  * extracts to the end of the string.
 751  * @return {String} All characters from specified start up to (but excluding)
 752  * end.
 753  */
 754
 755 <span id='String-method-split'>/**
 756 </span> * @method split
 757  * Splits a `String` object into an array of strings by separating the string into substrings.
 758  *
 759  * The `split` method returns the new array.
 760  *
 761  * When found, `separator` is removed from the string and the substrings are returned in an array. If
 762  * `separator` is omitted, the array contains one element consisting of the entire string.
 763  *
 764  * If `separator` is a regular expression that contains capturing parentheses, then each time separator
 765  * is matched the results (including any undefined results) of the capturing parentheses are spliced
 766  * into the output array. However, not all browsers support this capability.
 767  *
 768  * Note: When the string is empty, `split` returns an array containing one empty string, rather than an
 769  * empty array.
 770  *
 771  * The following example defines a function that splits a string into an array of strings using the
 772  * specified separator. After splitting the string, the function displays messages indicating the
 773  * original string (before the split), the separator used, the number of elements in the array, and the
 774  * individual array elements.
 775  *
 776  *     function splitString(stringToSplit,separator)
 777  *     {
 778  *         var arrayOfStrings = stringToSplit.split(separator);
 779  *         print('The original string is: &quot;' + stringToSplit + '&quot;');
 780  *         print('The separator is: &quot;' + separator + '&quot;');
 781  *         print(&quot;The array has &quot; + arrayOfStrings.length + &quot; elements: &quot;);
 782  *
 783  *         for (var i=0; i &lt; arrayOfStrings.length; i++)
 784  *             print(arrayOfStrings[i] + &quot; / &quot;);
 785  *     }
 786  *
 787  *     var tempestString = &quot;Oh brave new world that has such people in it.&quot;;
 788  *     var monthString = &quot;Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec&quot;;
 789  *
 790  *     var space = &quot; &quot;;
 791  *     var comma = &quot;,&quot;;
 792  *
 793  *     splitString(tempestString, space);
 794  *     splitString(tempestString);
 795  *     splitString(monthString, comma);
 796  *
 797  * This example produces the following output:
 798  *
 799  *     The original string is: &quot;Oh brave new world that has such people in it.&quot;
 800  *     The separator is: &quot; &quot;
 801  *     The array has 10 elements: Oh / brave / new / world / that / has / such / people / in / it. /
 802  *
 803  *     The original string is: &quot;Oh brave new world that has such people in it.&quot;
 804  *     The separator is: &quot;undefined&quot;
 805  *     The array has 1 elements: Oh brave new world that has such people in it. /
 806  *
 807  * The original string is: &quot;Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec&quot;
 808  * The separator is: &quot;,&quot;
 809  * The array has 12 elements: Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec /
 810  *
 811  * In the following example, `split` looks for 0 or more spaces followed by a semicolon followed by 0
 812  * or more spaces and, when found, removes the spaces from the string. nameList is the array returned
 813  * as a result of split.
 814  *
 815  *     var names = &quot;Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand &quot;;
 816  *     print(names);
 817  *     var re = /\s*;\s*\/;
 818  *     var nameList = names.split(re);
 819  *     print(nameList);
 820  *
 821  * This prints two lines; the first line prints the original string, and the second line prints the
 822  * resulting array.
 823  *
 824  *     Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand
 825  *     Harry Trump,Fred Barney,Helen Rigby,Bill Abel,Chris Hand
 826  *
 827  * In the following example, split looks for 0 or more spaces in a string and returns the first 3
 828  * splits that it finds.
 829  *
 830  *     var myString = &quot;Hello World. How are you doing?&quot;;
 831  *     var splits = myString.split(&quot; &quot;, 3);
 832  *     print(splits);
 833  *
 834  * This script displays the following:
 835  *
 836  *     Hello,World.,How
 837  *
 838  * If `separator` contains capturing parentheses, matched results are returned in the array.
 839  *
 840  *     var myString = &quot;Hello 1 word. Sentence number 2.&quot;;
 841  *     var splits = myString.split(/(\d)/);
 842  *     print(splits);
 843  *
 844  * This script displays the following:
 845  *
 846  *     Hello ,1, word. Sentence number ,2, .
 847  *
 848  * @param {String} seperator Specifies the character to use for separating the string. The separator is treated as a string or a
 849  * regular expression. If separator is omitted, the array returned contains one element consisting of the entire string.
 850  * @param {Number} limit Integer specifying a limit on the number of splits to be found.  The split method still splits on every
 851  * match of separator, but it truncates the returned array to at most limit elements.
 852  * @return {Array} Substrings are returned in an array.
 853  */
 854
 855 <span id='String-method-substr'>/**
 856 </span> * @method substr
 857  * Returns the characters in a string beginning at the specified location through the specified number
 858  * of characters.
 859  *
 860  * `start` is a character index. The index of the first character is 0, and the index of the last
 861  * character is 1 less than the length of the string. `substr` begins extracting characters at start
 862  * and collects length characters (unless it reaches the end of the string first, in which case it will
 863  * return fewer).
 864  *
 865  * If `start` is positive and is greater than or equal to the length of the string, `substr` returns an
 866  * empty string.
 867  *
 868  * If `start` is negative, `substr` uses it as a character index from the end of the string. If start
 869  * is negative and abs(start) is larger than the length of the string, `substr` uses 0 as the start
 870  * index. Note: the described handling of negative values of the start argument is not supported by
 871  * Microsoft JScript.
 872  *
 873  * If length is 0 or negative, `substr` returns an empty string. If length is omitted, `substr`
 874  * extracts characters to the end of the string.
 875  *
 876  * Consider the following script:
 877  *
 878  *     // assumes a print function is defined
 879  *     var str = &quot;abcdefghij&quot;;
 880  *     print(&quot;(1,2): &quot;    + str.substr(1,2));
 881  *     print(&quot;(-3,2): &quot;   + str.substr(-3,2));
 882  *     print(&quot;(-3): &quot;     + str.substr(-3));
 883  *     print(&quot;(1): &quot;      + str.substr(1));
 884  *     print(&quot;(-20, 2): &quot; + str.substr(-20,2));
 885  *     print(&quot;(20, 2): &quot;  + str.substr(20,2));
 886  *
 887  * This script displays:
 888  *
 889  *     (1,2): bc
 890  *     (-3,2): hi
 891  *     (-3): hij
 892  *     (1): bcdefghij
 893  *     (-20, 2): ab
 894  *     (20, 2):
 895  *
 896  * @param {Number} start Location at which to begin extracting characters.
 897  * @param {Number} length The number of characters to extract.
 898  * @return {String} Modified string.
 899  */
 900
 901 <span id='String-method-substring'>/**
 902 </span> * @method substring
 903  * Returns the characters in a string between two indexes into the string.
 904  *
 905  * substring extracts characters from indexA up to but not including indexB. In particular:
 906  * *   If `indexA` equals `indexB`, `substring` returns an empty string.
 907  * *   If `indexB` is omitted, substring extracts characters to the end of the string.
 908  * *   If either argument is less than 0 or is `NaN`, it is treated as if it were 0.
 909  * *   If either argument is greater than `stringName.length`, it is treated as if it were
 910  * `stringName.length`.
 911  *
 912  * If `indexA` is larger than `indexB`, then the effect of substring is as if the two arguments were
 913  * swapped; for example, `str.substring(1, 0) == str.substring(0, 1)`.
 914  *
 915  * The following example uses substring to display characters from the string &quot;Sencha&quot;:
 916  *
 917  *     // assumes a print function is defined
 918  *     var anyString = &quot;Sencha&quot;;
 919  *
 920  *     // Displays &quot;Sen&quot;
 921  *     print(anyString.substring(0,3));
 922  *     print(anyString.substring(3,0));
 923  *
 924  *     // Displays &quot;cha&quot;
 925  *     print(anyString.substring(3,6));
 926  *     print(anyString.substring(6,3));
 927  *
 928  *     // Displays &quot;Sencha&quot;
 929  *     print(anyString.substring(0,6));
 930  *     print(anyString.substring(0,10));
 931  *
 932  * The following example replaces a substring within a string. It will replace both individual
 933  * characters and `substrings`. The function call at the end of the example changes the string &quot;Brave
 934  * New World&quot; into &quot;Brave New Web&quot;.
 935  *
 936  *     function replaceString(oldS, newS, fullS) {
 937  *         // Replaces oldS with newS in the string fullS
 938  *         for (var i = 0; i &lt; fullS.length; i++) {
 939  *             if (fullS.substring(i, i + oldS.length) == oldS) {
 940  *                 fullS = fullS.substring(0, i) + newS + fullS.substring(i + oldS.length,
 941  * fullS.length);
 942  *             }
 943  *         }
 944  *         return fullS;
 945  *     }
 946  *
 947  *     replaceString(&quot;World&quot;, &quot;Web&quot;, &quot;Brave New World&quot;);
 948  *
 949  * @param {Number} indexA An integer between 0 and one less than the length of the string.
 950  * @param {Number} indexB (optional) An integer between 0 and the length of the string.
 951  * @return {String} Returns the characters in a string between two indexes into the string.
 952  */
 953
 954 <span id='String-method-toLocaleLowerCase'>/**
 955 </span> * @method toLocaleLowerCase
 956  * The characters within a string are converted to lower case while respecting the current locale. For
 957  * most languages, this will return the same as `toLowerCase`.
 958  *
 959  * The `toLocaleLowerCase` method returns the value of the string converted to lower case according to
 960  * any locale-specific case mappings. `toLocaleLowerCase` does not affect the value of the string
 961  * itself. In most cases, this will produce the same result as `toLowerCase()`, but for some locales,
 962  * such as Turkish, whose case mappings do not follow the default case mappings in Unicode, there may
 963  * be a different result.
 964  *
 965  * The following example displays the string &quot;sencha&quot;:
 966  *
 967  *     var upperText=&quot;sencha&quot;;
 968  *     document.write(upperText.toLocaleLowerCase());
 969  *
 970  * @return {String} Returns value of the string in lowercase.
 971  */
 972
 973 <span id='String-method-toLocaleUpperCase'>/**
 974 </span> * @method toLocaleUpperCase
 975  * The characters within a string are converted to upper case while respecting the current locale. For
 976  * most languages, this will return the same as `toUpperCase`.
 977  *
 978  * The `toLocaleUpperCase` method returns the value of the string converted to upper case according to
 979  * any locale-specific case mappings. `toLocaleUpperCase` does not affect the value of the string
 980  * itself. In most cases, this will produce the same result as `toUpperCase()`, but for some locales,
 981  * such as Turkish, whose case mappings do not follow the default case mappings in Unicode, there may
 982  * be a different result.
 983  *
 984  * The following example displays the string &quot;SENCHA&quot;:
 985  *
 986  *     var lowerText=&quot;sencha&quot;;
 987  *     document.write(lowerText.toLocaleUpperCase());
 988  *
 989  * @return {String} Returns value of the string in uppercase.
 990  */
 991
 992 <span id='String-method-toLowerCase'>/**
 993 </span> * @method toLowerCase
 994  * Returns the calling string value converted to lower case.
 995  *
 996  * The `toLowerCase` method returns the value of the string converted to lowercase. `toLowerCase` does
 997  * not affect the value of the string itself.
 998  *
 999  * The following example displays the lowercase string &quot;sencha&quot;:
1000  *
1001  *     var upperText=&quot;SENCHA&quot;;
1002  *     document.write(upperText.toLowerCase());
1003  *
1004  * @return {String} Returns value of the string in lowercase.
1005  */
1006
1007 <span id='String-method-toString'>/**
1008 </span> * @method toString
1009  * Returns a string representing the specified object. Overrides the `Object.toString` method.
1010  *
1011  * The `String` object overrides the `toString` method of the `Object` object; it does not inherit
1012  * `Object.toString`. For `String` objects, the `toString` method returns a string representation of
1013  * the object.
1014  *
1015  * The following example displays the string value of a String object:
1016  *
1017  *     x = new String(&quot;Hello world&quot;);
1018  *     alert(x.toString())      // Displays &quot;Hello world&quot;
1019  *
1020  * @return {String} A string representation of the object.
1021  */
1022
1023 <span id='String-method-toUpperCase'>/**
1024 </span> * @method toUpperCase
1025  * Returns the calling string value converted to uppercase.
1026  *
1027  * The `toUpperCase` method returns the value of the string converted to uppercase. `toUpperCase` does
1028  * not affect the value of the string itself.
1029  *
1030  * The following example displays the string &quot;SENCHA&quot;:
1031
1032  *     var lowerText=&quot;sencha&quot;;
1033  *     document.write(lowerText.toUpperCase());
1034  *
1035  * @return {String} Returns value of the string in uppercase.
1036  */
1037
1038 <span id='String-method-valueOf'>/**
1039 </span> * @method valueOf
1040  * Returns the primitive value of the specified object. Overrides the `Object.valueOf` method.
1041  *
1042  * The `valueOf` method of String returns the primitive value of a `String` object as a string data
1043  * type. This value is equivalent to `String.toString`.
1044  *
1045  * This method is usually called internally by JavaScript and not explicitly in code.
1046  *
1047  *     x = new String(&quot;Hello world&quot;);
1048  *     alert(x.valueOf())          // Displays &quot;Hello world&quot;
1049  *
1050  * @return {String} Returns value of string.
1051  */</pre>
1052 </body>
1053 </html>