# String : Object
Return to: JavaScript Core index

Represents the characters of a string.

## Platform Support

IE | Mozilla | Netscape | Opera | Safari
--- | --- | --- | --- | ---
3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

## Constructors

Constructor | Action | IE | Mozilla | Netscape | Opera | Safari
--- | --- | --- | --- | --- | --- | ---
String Constructor(String string) : String Constructs an instance of a String. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

### String(String string) : String

Constructs an instance of a String.

Parameters

String | string | Any string.

Returns

String |

## Properties

Property | Action | IE | Mozilla | Netscape | Opera | Safari
--- | --- | --- | --- | --- | --- | ---
constructor : Object Specifies the function that creates the String prototype. | Show Details | 4.0+ | 1.0+ | 3.0+ | 7.0+ | 1.0+

See Also

  constructor

Availability

  JavaScript 1.1|JScript 2.0|ECMAScript v1

length : Number Number of characters in the string. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

  The following example displays 8 in an Alert dialog box:

      var x = "Netscape";
                              alert("The string length is " + x.length);

Remarks

  This property returns the number of characters in the string. For an empty string, `length` is 0.

Availability

  JavaScript 1.0|JScript 1.0|ECMAScript v1

prototype : Object Reference to the String prototype object. | Show Details | 4.0+ | 1.0+ | 3.0+ | 7.0+ | 1.0+

Availability

  JavaScript 1.1|JScript 2.0|ECMAScript v1

## Functions

Method | Action | IE | Mozilla | Netscape | Opera | Safari
--- | --- | --- | --- | --- | --- | ---
anchor(String name) : String Returns a copy of a string as an HTML anchor. (e.g <a name="name"> | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | name | String to be copied into an HTML anchor.

Returns

String |

  ### Example: Using `anchor`

  The following example code within an HTML `script` element:

      var myString = "Table of Contents";
                              document.writeln(myString.anchor("contents_anchor"));

  will output the following HTML:

      <A NAME="contents_anchor">Table of Contents</A>

Remarks

  Use the `anchor` method with the `document.write` or `document.writeln` methods to programmatically create and display an anchor in a document. Create the anchor with the `anchor` method, and then call `write` or `writeln` to display the anchor in a document. In server-side JavaScript, use the `write` function to display the anchor.

  In the syntax, the text string represents the literal text that you want the user to see. The `nameAttribute` string represents the `NAME` attribute of the A tag.

  Anchors created with the `anchor` method become elements in the `document.anchors` array.

See Also

  link

Availability

  JavaScript 1.0|JScript 1.0|ECMAScript v1

big() : String Returns a copy of a string surrounded by <big></big> HTML tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | no

Returns

String |

  ### Example: Using `big`

  The following example uses `string` methods to change the size of a string:

      var worldString="Hello, world"

                              document.write(worldString.small())
                              document.write("<P>" + worldString.big())
                              document.write("<P>" + worldString.fontsize(7))

  This example produces the same output as the following HTML:

                              <P><SMALL>Hello, world</SMALL>
                              <P><BIG>Hello, world</BIG>
                              <P><FONTSIZE=7>Hello, world</FONTSIZE>

Remarks

  Use the `big` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

See Also

  fontsize|small

Availability

  JavaScript 1.0|JScript 1.0

blink() : String Returns a copy of a string surrounded by <blink></blink> HTML tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `string` methods to change the formatting of a string

  The following example uses `string` methods to change the formatting of a string:

      var worldString="Hello, world"

                              document.write(worldString.blink())
                              document.write("<P>" + worldString.bold())
                              document.write("<P>" + worldString.italics())
                              document.write("<P>" + worldString.strike())

  This example produces the same output as the following HTML:

                              <P><BLINK>Hello, world</BLINK>
                              <P><B>Hello, world</B>
                              <P><I>Hello, world</I>
                              <P><STRIKE>Hello, world</STRIKE>

Remarks

  Use the `blink` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

See Also

  bold|italics|strike

Availability

  JavaScript 1.0|JScript 1.0

bold() : String Returns a copy of a string surrounded by <bold></bold> HTML tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `string` methods to change the formatting of a string

  The following example uses `string` methods to change the formatting of a string:

      var worldString="Hello, world"

                              document.write(worldString.blink())
                              document.write("<P>" + worldString.bold())
                              document.write("<P>" + worldString.italics())
                              document.write("<P>" + worldString.strike())

  This example produces the same output as the following HTML:

                              <P><BLINK>Hello, world</BLINK>
                              <P><B>Hello, world</B>
                              <P><I>Hello, world</I>
                              <P><STRIKE>Hello, world</STRIKE>

Remarks

  Use the `bold` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

See Also

  blink|italics|strike

Availability

  JavaScript 1.0|JScript 1.0

charAt(String index) : String Returns the specified character from a string. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | index | An integer between 0 and 1 less than the length of the string.

Returns

String |

  ### Displaying characters at different locations in a string

  The following example displays characters at different locations in the string "`Brave new world`":

      var anyString="Brave new world"

                              document.writeln("The character at index 0 is " + anyString.charAt(0))
                              document.writeln("The character at index 1 is " + anyString.charAt(1))
                              document.writeln("The character at index 2 is " + anyString.charAt(2))
                              document.writeln("The character at index 3 is " + anyString.charAt(3))
                              document.writeln("The character at index 4 is " + anyString.charAt(4))

  These lines display the following:

      The
                              character at index 0 is B
                              The character at index 1 is r
                              The character at index 2 is a
                              The character at index 3 is v
                              The character at index 4 is e

Remarks

  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 in a string called `stringName` is `stringName.length - 1`. If the `index` you supply is out of range, JavaScript returns an empty string.

See Also

  String.charCodeAt|String.indexOf|String.lastIndexOf

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1

charCodeAt(Object index) : Number Returns the the Unicode value of the character at the specified index. | Show Details | 5.5+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

Object | index | An integer between 0 and 1 less than the length of the string. The default value is 0.

Returns

Number |

  ### Using `charCodeAt`

  The following example returns 65, the Unicode value for A.

      "ABC".charCodeAt(0) // returns 65

Remarks

  Unicode values range from 0 to 65,535. The first 128 Unicode values are a direct match of the ASCII character set.

See Also

  String.charAt|String.fromCharCode

Availability

  JavaScript 1.2|JScript 5.5|ECMAScript v1

concat(String string2...stringN) : String Combines the text of two or more strings and returns a new string. | Show Details | 4.0+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

String | string2...stringN | (one-or-more)Strings to concatenate to this string.

Returns

String |

  ### Using `concat`

  The following example combines strings into a new string.

      s1="Oh "
                              s2="what a beautiful "
                              s3="mornin'."
                              s4=s1.concat(s2,s3) // returns "Oh what a beautiful mornin'."

Remarks
  `concat` combines the text from one or more strings and returns a new string. Changes to the text in one string do not affect the other string.
See Also

  Array.concat

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v3

fixed() : void Returns a copy of a string surrounded by <tt></tt> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

  ### Example: Using `fixed` to change the formatting of a string

  The following example uses the `fixed` method to change the formatting of a string:

      var worldString="Hello, world"
                              document.write(worldString.fixed())

  This example produces the same output as the following HTML:

      <TT>Hello, world</TT>

Remarks
  Use the `fixed` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.
Availability

  JavaScript 1.0|JScript 1.0

fontcolor(String color) : String Returns a copy of a string surrounded by <font color = "color"></font> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | color | A string expressing the color as either a hexadecimal RGB triplet or as a string literal.

Returns

String |

  ### Example: Using `fontcolor`

  The following example uses the `fontcolor` method to change the color of a string:

      var worldString="Hello, world"

                              document.write(worldString.fontcolor("maroon") +  " is maroon in this line")
                              document.write("<P>" + worldString.fontcolor("salmon") + " is salmon in this line")
                              document.write("<P>" + worldString.fontcolor("red") + " is red in this line")
                              document.write("<P>" + worldString.fontcolor("8000") + " is maroon in hexadecimal in this line")
                              document.write("<P>" + worldString.fontcolor("FA8072") + " is salmon in hexadecimal in this line")
                              document.write("<P>" + worldString.fontcolor("FF00") + " is red in hexadecimal in this line")

  The previous example produces the same output as the following HTML:

                              <P><FONT COLOR="maroon">Hello, world</FONT> is maroon in this line
                              <P><FONT COLOR="salmon">Hello, world</FONT> is salmon in this line
                              <P><FONT COLOR="red">Hello, world</FONT> is red in this line
                              <P><FONT COLOR="8000">Hello, world</FONT> is maroon in hexadecimal in this line
                              <P><FONT COLOR="FA8072">Hello, world</FONT> is salmon in hexadecimal in this line
                              <P><FONT COLOR="FF00">Hello, world</FONT> is red in hexadecimal in this line

Remarks

  Use the `fontcolor` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

  If you express color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are red=FA, green=80, and blue=72, so the RGB triplet for salmon is "`FA8072`".

  The `fontcolor` method overrides a value set in the `fgColor` property.

Availability

  JavaScript 1.0|JScript 1.0

fontsize(Number size) : String Returns a copy of a string surrounded by <font size="size"></font> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

Number | size | An integer between 1 and 7, or a string representing a signed integer between 1 and 7, specifiying what the font size should be set to.

Returns

String |

  ### Example: Using `string` methods to change the size of a string

  The following example uses `string` methods to change the size of a string:

      var worldString="Hello, world"

                              document.write(worldString.small())
                              document.write("<P>" + worldString.big())
                              document.write("<P>" + worldString.fontsize(7))

  This example produces the same output as the following HTML:

                              <P><SMALL>Hello, world</SMALL>
                              <P><BIG>Hello, world</BIG>
                              <P><FONT SIZE="7">Hello, world</FONT>

Remarks

  Use the `fontsize` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

  When you specify size as an integer, you set the size of `stringName` to one of the 7 defined sizes. When you specify `size` as a string such as "-2", you adjust the font size of `stringName` relative to the size set in the `BASEFONT` tag.

See Also

  big|small

Availability

  JavaScript 1.0|JScript 1.0

static fromCharCode(String num1, ..., numN) : String Returns a string created by using the specified sequence of Unicode values. | Show Details | 4.0+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

String | num1, ..., numN | (one-or-more)A sequence of numbers that are Unicode values.

Returns

String |

  ### Using `fromCharCode`

  The following example returns the string "ABC".

      String.fromCharCode(65,66,67)

Remarks

  This method returns a string and not a `String` object.

  Because `fromCharCode` is a static method of `String`, you always use it as `String.fromCharCode()`, rather than as a method of a `String` object you created.

See Also

  String.charCodeAt

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v1

indexOf(String searchValue, [String fromIndex]) : Number Returns the index within the calling String object of the first occurrence of the specified value, starting the search at fromIndex, or -1 if the value is not found. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | searchValue | A string representing the value to search for.
String | fromIndex | (optional)The location within the calling string to start the search from. It can be any integer between 0 and the length of the string. The default value is 0.

Returns

Number |

  ### Using `indexOf` and `lastIndexOf`

  The following example uses `indexOf` and `lastIndexOf` to locate values in the string "`Brave new world`".

      var anyString="Brave new world"

                              // Displays 8
                              document.write("<P>The index of the first w from the beginning is " +
                              anyString.indexOf("w"))

                              // Displays 10
                              document.write("<P>The index of the first w from the end is " +
                              anyString.lastIndexOf("w"))

                              // Displays 6
                              document.write("<P>The index of 'new' from the beginning is " +
                              anyString.indexOf("new"))

                              // Displays 6
                              document.write("<P>The index of 'new' from the end is " +
                              anyString.lastIndexOf("new"))

  ### `indexOf` and case-sensitivity

  The following example defines two string variables. The variables contain the same string except that the second string contains uppercase letters. The first `writeln` method displays 19. But because the `indexOf` method is case sensitive, the string "`cheddar`" is not found in `myCapString`, so the second `writeln` method displays -1.

      myString="brie, pepper jack, cheddar"
                              myCapString="Brie, Pepper Jack, Cheddar"

                              document.writeln('myString.indexOf("cheddar") is ' +
                              myString.indexOf("cheddar"))

                              document.writeln('<P>myCapString.indexOf("cheddar") is ' +
                              myCapString.indexOf("cheddar"));

  ### Using `indexOf` to count occurrences of a letter in a string

  The following example sets `count` to the number of occurrences of the letter `x` in the string `str`:

      count = 0;
                              pos = str.indexOf("x");
                              while ( pos != -1 ) {
                              count++;
                              pos = str.indexOf("x", pos+1);
                              }

Remarks

  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 of a string called `stringName` is `stringName.length - 1`.

      "Blue Whale".indexOf("Blue")    // returns 0
                              "Blue Whale".indexOf("Blute")   // returns -1
                              "Blue Whale".indexOf("Whale",0) // returns 5
                              "Blue Whale".indexOf("Whale",5) // returns 5
                              "Blue Whale".indexOf("",9)      // returns 9
                              "Blue Whale".indexOf("",10)     // returns 10
                              "Blue Whale".indexOf("",11)     // returns 10

  The `indexOf` method is case sensitive. For example, the following expression returns -1:

      "Blue Whale".indexOf("blue")

See Also

  charAt|lastIndexOf|split

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1

italics() : String Returns a copy of a string surrounded by <i></i> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `string` methods to change the formatting of a string

  The following example uses `string` methods to change the formatting of a string:

      var worldString="Hello, world"

                              document.write(worldString.blink())
                              document.write("<P>" + worldString.bold())
                              document.write("<P>" + worldString.italics())
                              document.write("<P>" + worldString.strike())

  This example produces the same output as the following HTML:

                              <P><BLINK>Hello, world</BLINK>
                              <P><B>Hello, world</B>
                              <P><I>Hello, world</I>
                              <P><STRIKE>Hello, world</STRIKE>

Remarks

  Use the `italics` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

See Also

  bold|italics|strike

Availability

  JavaScript 1.0|JScript 1.0

lastIndexOf(String searchValue, [String fromIndex]) : Number Returns the index within the calling String object of the last occurrence of the specified value, or -1 if not found. The calling string is searched backward, starting at fromIndex. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | searchValue | A string representing the value to search for.
String | fromIndex | (optional)The location within the calling string to start the search from. It can be any integer between 0 and the length of the string. The default value is the length of the string.

Returns

Number |

  ### Using `indexOf` and `lastIndexOf`

  The following example uses `indexOf` and `lastIndexOf` to locate values in the string "`Brave new world`".

      var anyString="Brave new world"

                              // Displays 8
                              document.write("<P>The index of the first w from the beginning is " +
                              anyString.indexOf("w"))
                              // Displays 10
                              document.write("<P>The index of the first w from the end is " +
                              anyString.lastIndexOf("w"))
                              // Displays 6
                              document.write("<P>The index of 'new' from the beginning is " +
                              anyString.indexOf("new"))
                              // Displays 6
                              document.write("<P>The index of 'new' from the end is " +
                              anyString.lastIndexOf("new"))

Remarks

  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 is `stringName.length - 1`.

      "canal".lastIndexOf("a")   // returns 3
                              "canal".lastIndexOf("a",2) // returns 1
                              "canal".lastIndexOf("a",0) // returns -1
                              "canal".lastIndexOf("x")   // returns -1

  The `lastIndexOf` method is case sensitive. For example, the following expression returns -1:

      "Blue Whale, Killer Whale".lastIndexOf("blue")

See Also

  charAt|indexOf|split

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1

link(String href) : String Returns a copy of a string surrounded by <a href="href"></a> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | href | String specifying the URL for the link.

Returns

String |

  ### Example: Using `link`

  The following example displays the word "Netscape" as a hypertext link that returns the user to the Netscape home page:

      var hotText="Netscape"
                              var URL="http://home.netscape.com"

                              document.write("Click to return to " + hotText.link(URL))

  This example produces the same output as the following HTML:

      Click to return to <A HREF="http://home.netscape.com">Netscape</A>

Remarks

  Use the `link` method to programmatically create a hypertext link, and then call `write` or `writeln` to display the link in a document. In server-side JavaScript, use the `write` function to display the link.

  Links created with the `link` method become elements in the `links` array of the `document` object. See `document.links`.

Availability

  JavaScript 1.0|JScript 1.0

localeCompare(String target) : Number Uses locale-specific ordering to compare two strings. | Show Details | 5.5+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

String | target | A string to be compared locale-wise to the string object.

Returns

Number |

Availability

  JavaScript 1.5|JScript 5.5|ECMAScript v3

match(Object regexp) : Array Used to match a regular expression against a string. | Show Details | 4.0+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

Object | regexp | Name of the regular expression. It can be a variable name or a literal.

Returns

Array |

  ### Using `match`

  In the following example, `match` is used to find "`Chapter`" followed by 1 or more numeric characters followed by a decimal point and numeric character 0 or more times. The regular expression includes the `i` flag so that case will be ignored.

                              str = "For more information, see Chapter 3.4.5.1";
                              re = /(chapter \d+(\.\d)*)/i;
                              found = str.match(re);
                              document.write(found);

  This returns the array containing Chapter 3.4.5.1,Chapter 3.4.5.1,.1

  "`Chapter 3.4.5.1`" is the first match and the first value remembered from `(Chapter \d+(\.\d)*)`.

  "`.1`" is the second value remembered from `(\.\d)`.

  ### Using global and ignore case flags with `match`

  The following example demonstrates the use of the global and ignore case flags with `match`.

                              str = "abcDdcba";
                              newArray = str.match(/d/gi);
                              document.write(newArray);

  The returned array contains D, d.

Remarks

  If the regular expression does not include the `g` flag, returns the same result that `RegExp.exec` would return on the regular expression and string. If the regular expression includes the `g` flag, returns an array of all the matches of the regular expression in the string.

  ### Note

  If you execute a match simply to find true or false, use `String.search` or the regular expression `test` method.

See Also

  RegExp|RegExp.exec|RegExp.test|String.replace|String.search

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v3

replace(String regexp, String newSubStr, String function) : Array Finds a match between a regular expression and a string, and replaces the matched substring with a new substring. | Show Details | 3.0+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

String | regexp | The name of the regular expression. It can be a variable name or a literal.
String | newSubStr | The string to put in place of the string found with regexp.
String | function | A function to be invoked after the match has been performed.

Returns

Array |

  ### Using `global` and `ignore` with `replace`

  In the following example, the regular expression includes the global and ignore case flags which permits `replace` to replace each occurrence of 'apples' in the string with 'oranges'.

                              re = /apples/gi;
                              str = "Apples are round, and apples are juicy.";
                              newstr=str.replace(re, "oranges");
                              document.write(newstr)

  This prints "oranges are round, and oranges are juicy."

  ### Defining the regular expression in `replace`

  In the following example, the regular expression is defined in `replace` and includes the ignore case flag.

                              str = "Twas the night before Xmas...";
                              newstr=str.replace(/xmas/i, "Christmas");
                              document.write(newstr)

  This prints "Twas the night before Christmas..."

  ### Switching words in a string

  The following script switches the words in the string. For the replacement text, the script uses the `$1` and `$2` replacement patterns.

                              re = /(\w+)\s(\w+)/;
                              str = "John Smith";
                              newstr = str.replace(re, "$2, $1");
                              document.write(newstr)

  This prints "Smith, John".

  ### Replacing a Fahrenheit degree with its Celcius equivalent

  The following example replaces a Fahrenheit degree with its equivalent Celsius degree. The Fahrenheit degree should be a number ending with F. The function returns the Celsius number ending with C. For example, if the input number is 212F, the function returns 100C. If the number is 0F, the function returns -17.77777777777778C.

  The regular expression `test` checks for any number that ends with F. The number of Fahrenheit degree is accessible to your function through the parameter `$1`. The function sets the Celsius number based on the Fahrenheit degree passed in a string to the `f2c` function. `f2c` then returns the Celsius number. This function approximates Perl's s///e flag.

      function f2c(x) {
                              var s = String(x)
                              var test = /(\d+(?:\.\d*)?)F\b/g
                              return s.replace
                              (test,
                              function (str,p1,offset,s) {
                              return ((p1-32) * 5/9) + "C";
                              }
                              )
                              }

Remarks

  This method does not change the `String` object it is called on. It simply returns a new string.

  If you want to execute a global search and replace, include the `g` flag in the regular expression.

  ### Specifying a string as a parameter

  The replacement string can include the following special replacement patterns:

  Pattern | Inserts
  `$$` | Inserts a "$".
  `$&` | Inserts the matched substring.
  `$`` | Inserts the portion of the string that precedes the matched substring.
  `$Â´` | Inserts the portion of the string that follows the matched substring.
  `$n` or `$nn` | Where `n` or `nn` are decimal digits, inserts the nth parenthesized submatch string.

  ### Specifying a function as a parameter

  When you specify a function as the second parameter, the function is invoked after the match has been performed. (The use of a function in this manner is often called a lambda expression.)

  In your function, you can dynamically generate the string that replaces the matched substring. The result of the function call is used as the replacement value.

  The nested function can use the matched substrings to determine the new string (`newSubStr`) that replaces the found substring. You get the matched substrings through the parameters of your function. The first parameter of your function holds the complete matched substring. The following n parameters can be used for parenthetical matches, remembered submatch strings, where n is the number of submatch strings in the regular expression. Finally, the last two parameters are the offset within the string where the match occurred and the string itself. For example, the following `replace` method returns XX.zzzz - XX , zzzz.

      "XXzzzz".replace(/(X*)(z*)/,
                              function (str, p1, p2, offset, s) {
                              return str + " - " + p1 + " , " + p2;
                              }
                              )

See Also

  RegExp|RegExp.exec|RegExp.test|String.match|String.search

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v3

search(String regexp) : Number Executes the search for a match between a regular expression and this String object. | Show Details | 4.0+ | 1.0+ | 4.0+ | 7.0+ | 1.0+

Parameters

String | regexp | Name of the regular expression. It can be a variable name or a literal.

Returns

Number |

  ### Using `search`

  The following example prints a message which depends on the success of the test.

      function testinput(re, str){
                              if (str.search(re) != -1)
                              midstring = " contains ";
                              else
                              midstring = " does not contain ";
                              document.write (str + midstring + re.source);
                              }

Remarks

  If successful, search returns the index of the regular expression inside the string. Otherwise, it returns -1.

  When you want to know whether a pattern is found in a string use `search` (similar to the regular expression `test` method); for more information (but slower execution) use `match` (similar to the regular expression `exec` method).

See Also

  RegExp|RegExp.exec|RegExp.test|String.match|String.replace

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v3

slice(String beginSlice, String endSlice) : String Extracts a section of a string and returns a new string. | Show Details | 4.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

String | beginSlice | The zero-based index at which to begin extraction.
String | endSlice | The zero-based index at which to end extraction. If omitted, slice extracts to the end of the string.

Returns

String |

  ### Using `slice` to create a new string

  The following example uses `slice` to create a new string.

                              str1="The morning is upon us. "
                              str2=str1.slice(3,-5)
                              document.write(str2)

  This writes:

      morning is upon

Remarks

  `slice` extracts the text from one string and returns a new string. Changes to the text in one string do not affect the other string.

  `slice` extracts up to but not including `endSlice`. `string.slice(1,4)` extracts the second character through the fourth character (characters indexed 1, 2, and 3).

  As a negative index, endSlice indicates an offset from the end of the string. string.slice(2,-1) extracts the third character through the second to last character in the string.

See Also

  Array.slice|String.substring

Availability

  JavaScript 1.2|JScript 3.0|ECMAScript v3

small() : String Returns a copy of a string surrounded by <small></small> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `string` methods to change the size of a string

      var worldString="Hello, world"

                              document.write(worldString.small())
                              document.write("<P>" + worldString.big())
                              document.write("<P>" + worldString.fontsize(7))

  This example produces the same output as the following HTML:

                              <P><SMALL>Hello, world</SMALL>
                              <P><BIG>Hello, world</BIG>
                              <P><FONTSIZE=7>Hello, world</FONTSIZE>

Remarks
  Use the `small` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.
See Also

  big|fontsize

Availability

  JavaScript 1.0|JScript 1.0

split(String separator, [String limit]) : Array Splits a String object into an array of strings by separating the string into substrings. | Show Details | 4.0+ | 1.0+ | 3.0+ | 7.0+ | no

Parameters

String | separator | Specifies the character to use for separating the string. The separator is treated as a string or a regular expression. If separator is omitted, the array returned contains one element consisting of the entire string.
String | limit | (optional)Integer specifying a limit on the number of splits to be found.

Returns

Array |

  ### Using `split`

  The following example defines a function that splits a string into an array of strings using the specified separator. After splitting the string, the function displays messages indicating the original string (before the split), the separator used, the number of elements in the array, and the individual array elements.

      function splitString (stringToSplit,separator) {
                              arrayOfStrings = stringToSplit.split(separator)
                              document.write ('<P>The original string is: "' + stringToSplit + '"')
                              document.write ('<BR>The separator is: "' + separator + '"')
                              document.write ("<BR>The array has " + arrayOfStrings.length + " elements: ")

                              for (var i=0; i < arrayOfStrings.length; i++) {
                              document.write (arrayOfStrings[i] + " / ")
                              }
                              }

                              var tempestString="Oh brave new world that has such people in it."
                              var monthString="Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"

                              var space=" "
                              var comma=","

                              splitString(tempestString,space)
                              splitString(tempestString)
                              splitString(monthString,comma)

  This example produces the following output:

      The original string is: "Oh brave
                              new world that has such people in it."
                              The separator is: " "
                              The array has 10 elements: Oh / brave / new / world / that / has / such / people / in / it. /

                              The original string is: "Oh brave new world that has such people in it."
                              The separator is: "undefined"
                              The array has 1 elements: Oh brave new world that has such people in it. /

                              The original string is: "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
                              The separator is: ","
                              The array has 12 elements: Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec /

  ### The difference between `split` in JavaScript 1.2 and other versions

  Consider the following script:

                              str="She sells seashells \nby the\n seashore"
                              document.write(str + "<BR>")
                              a=str.split(" ")
                              document.write(a)

  Using `LANGUAGE="JavaScript1.2"`, this script produces:

      "She", "sells", "seashells", "by", "the", "seashore"

  Without `LANGUAGE="JavaScript1.2"`, this script splits only on single space characters, producing:

      "She", "sells", "seashells", "\nby", "the\n", "seashore"

  ### Removing spaces from a string

  In the following example, `split` looks for 1 or more spaces followed by a semicolon followed by 1 or more spaces and, when found, removes the spaces from the string. `nameList` is the array returned as a result of `split`.

                              names = "Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand ";
                              document.write (names + "<BR>" + "<BR>");
                              re = /\s+;\s+/;
                              nameList = names.split (re);
                              document.write(nameList);

  This prints two lines; the first line prints the original string, and the second line prints the resulting array.

      Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand
                              Harry Trump,Fred Barney,Helen Rigby,Bill Abel,Chris Hand

  ### Returning a limited number of splits

  In the following example, `split` looks for 0 or more spaces in a string and returns the first 3 splits that it finds.

                              myVar = " Hello World. How are you doing? ";
                              splits = myVar.split(" ", 3);
                              document.write(splits)

  This script displays the following:

      ["Hello", "World.", "How"

Remarks

  The `split` method returns the new array.

  When found, `separator` is removed from the string and the substrings are returned in an array. If `separator` is omitted, the array contains one element consisting of the entire string.

  In JavaScript 1.2 or later, `split` has the following additions:

  - It can take a regular expression argument, as well as a fixed string, by which to split the object string. If `separator` is a regular expression, any included parenthesis cause submatches to be included in the returned array.
  - It can take a limit count so that the resulting array does not include trailing elements.
  - If you specify `LANGUAGE="JavaScript1.2"` in the `script` tag, `string.split(" ")` splits on any run of 1 or more white space characters including spaces, tabs, line feeds, and carriage returns.
See Also

  charAt|indexOf|lastIndexOf

Availability

  JavaScript 1.1|JScript 3.0|ECMAScript v1|enhanced in ECMAScript v3

strike() : String Returns a copy of a string surrounded by tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `string` methods to change the formatting of a string

  The following example uses `string` methods to change the formatting of a string:

      var worldString="Hello, world"

                              document.write(worldString.blink())
                              document.write("<P>" + worldString.bold())
                              document.write("<P>" + worldString.italics())
                              document.write("<P>" + worldString.strike())

  This example produces the same output as the following HTML:

                              <P><BLINK>Hello, world</BLINK>
                              <P><B>Hello, world</B>
                              <P><I>Hello, world</I>
                              <P><STRIKE>Hello, world</STRIKE>

Remarks

  Use the `strike` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to display the string.

See Also

  blink|bold|italics

Availability

  JavaScript 1.0|JScript 1.0

sub() : String Returns a copy of a string surrounded by <sub></sub> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `sub` and `sup` methods to format a string

  The following example uses the `sub` and `sup` methods to format a string:

      var superText="superscript"
                              var subText="subscript"

                              document.write("<P>This is what a " + superText.sup() + " looks like.")
                              document.write("<P>This is what a " + subText.sub() + " looks like.")

  This example produces the same output as the following HTML:

                              <P>This is what a <SUP>superscript</SUP> looks like.
                              <P>This is what a <SUB>subscript</SUB> looks like.

Remarks

  Use the `sub` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to generate the HTML.

See Also

  sup

Availability

  JavaScript 1.0|JScript 1.0

substr(Number start, Number length) : String Returns the characters in a string beginning at the specified location through the specified number of characters. | Show Details | 4.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

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

Returns

String |

  ### Using `substr`

  Consider the following script:

      str = "abcdefghij";
                              document.writeln("(1,2): ", str.substr(1,2));
                              document.writeln("(-2,2): ", str.substr(-2,2));
                              document.writeln("(1): ", str.substr(1));
                              document.writeln("(-20, 2): ", str.substr(1,20));
                              document.writeln("(20, 2): ", str.substr(20,2));

  This script displays:

      (1,2): bc
                              (-2,2): ij
                              (1): bcdefghij
                              (-20, 2): bcdefghij
                              (20, 2):

Remarks

  `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` number of characters.

  If `start` is positive and is the length of the string or longer, `substr` returns no characters.

  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 is the start index.

  If `length` is 0 or negative, `substr` returns no characters. If `length` is omitted, `start` extracts characters to the end of the string.

See Also

  substring|String.slice

Availability

  JavaScript 1.2|JScript 3.0|deprecated

substring(Number indexA, [Number indexB]) : String Returns a subset of a String object. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Parameters

Number | indexA | An integer between 0 and one less than the length of the string.
Number | indexB | (optional)An integer between 0 and the length of the string.

Returns

String |

  ### Using `substring`

  The following example uses `substring` to display characters from the string "`Mozilla`":

      var anyString = "Mozilla";

                              // Displays "Moz"
                              document.write(anyString.substring(0,3));
                              document.write(anyString.substring(3,0));
                              // Displays "lla"
                              document.write(anyString.substring(4,7));
                              document.write(anyString.substring(7,4));
                              // Displays "Mozill"
                              document.write(anyString.substring(0,6));
                              // Displays "Mozilla"
                              document.write(anyString.substring(0,7));
                              document.write(anyString.substring(0,10));

  ### Replacing a substring within a string

  The following example replaces a substring within a string. It will replace both individual characters and substrings. The function call at the end of the example changes the string "`Brave New World`" into "`Brave New Web`".

      function replaceString(oldS, newS, fullS) {
                              // Replaces oldS with newS in the string fullS
                              for (var i = 0; i < fullS.length; i++) {
                              if (fullS.substring(i, i + oldS.length) == oldS) {
                              fullS = fullS.substring(0, i) + newS + fullS.substring(i + oldS.length, fullS.length);
                              }
                              }
                              return fullS;
                              }

                              replaceString("World", "Web", "Brave New World");

  ### JavaScript 1.2 "Out of Memory" error

  In JavaScript 1.2, using `LANGUAGE="JavaScript1.2"`, the following script produces a runtime error (out of memory).

                              var str = "Mozilla";
                              document.write(str.substring(0,3));
                              document.write(str.substring(3,0));

  Without `LANGUAGE="JavaScript1.2"`, the above script prints the following:

      Moz Moz

  In the second write, the index numbers are swapped.

Remarks

  `substring` extracts characters from `indexA` up to but not including `indexB`. In particular:

  - If `indexA` is less than 0, `indexA` is treated as if it were 0.
  - If `indexB` is greater than `stringName.length`, `indexB` is treated as if it were `stringName.length`.
  - If `indexA` equals `indexB`, `substring` returns an empty string.
  - If `indexB` is omitted, `substring` extracts characters to the end of the string.

  ### In JavaScript 1.2

  Using `LANGUAGE="JavaScript1.2"` in the `script` tag,

  - If `indexA` is greater than `indexB`, JavaScript produces a runtime error (out of memory).

  Without `LANGUAGE="JavaScript1.2"` in the `script` tag,

  - If `indexA` is greater than `indexB`, JavaScript returns `substring(indexB, indexA)`.
See Also

  String.charAt|String.indexOf|String.lastIndexOf|String.slice|String.substr

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1

sup() : String Returns a copy of a string surrounded by <sup></sup> tags. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `sub` and `sup` methods to format a string

  The following example uses the `sub` and `sup` methods to format a string:

      var superText="superscript"
                              var subText="subscript"

                              document.write("<P>This is what a " + superText.sup() + " looks like.")
                              document.write("<P>This is what a " + subText.sub() + " looks like.")

  This example produces the same output as the following HTML:

                              <P>This is what a <SUP>superscript</SUP> looks like.
                              <P>This is what a <SUB>subscript</SUB> looks like.

Remarks

  Use the `sup` method with the `write` or `writeln` methods to format and display a string in a document. In server-side JavaScript, use the `write` function to generate the HTML.

See Also

  sub

Availability

  JavaScript 1.0|JScript 1.0

toLocaleLowerCase() : String Returns a copy of a string in lowercase letters in a locale-specific format. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | no

Returns

String |

See Also

  String.toLocaleUpperCase|String.toLowerCase|String.toUpperCase

Availability

  JavaScript 1.5|JScript 5.5, ECMAScript v3

toLocaleUpperCase() : String Returns a copy of a string in uppercase letters in a locale-specific format. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | no

Returns

String |

See Also

  String.toLocaleLowerCase|String.toLowerCase|String.toUpperCase

Availability

  JavaScript 1.5|JScript 5.5, ECMAScript v3

toLowerCase() : String Returns the string value converted to lowercase. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Using `toLowerCase`

  The following example displays the lowercase string "`alphabet`":

      var upperText="ALPHABET"
                              document.write(upperText.toLowerCase())

Remarks

  The `toLowerCase` method returns the value of the string converted to lowercase. `toLowerCase` does not affect the value of the string itself.

See Also

  toUpperCase

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1

toString() : String Returns a string representing the specified object. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Using `toString`

  The following example displays the string value of a String object:

      x = new String("Hello world");
                              alert(x.toString())      // Displays "Hello world"

Throws
    TypeError is thrown if the specified object is not a String.
See Also

  String.valueOf

Availability

  JavaScript 1.0|JScript 1.0, ECMAScript v1 Overrides Object.toString

toUpperCase() : String Returns the string value converted to all uppercase. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

String |

  ### Example: Using `toUpperCase`

  The following example displays the string "`ALPHABET`":

      var lowerText="alphabet"
                              document.write(lowerText.toUpperCase())

Remarks

  The `toUpperCase` method returns the value of the string converted to uppercase. `toUpperCase` does not affect the value of the string itself.

See Also

  toLowerCase

Availability

  JavaScript 1.0|JScript 1.0|ECMAScript v1

valueOf() : Object Returns the primitive value of a String object. | Show Details | 3.0+ | 1.0+ | 2.0+ | 7.0+ | 1.0+

Returns

Object |

  ### Example: Using `valueOf`

      x = new String("Hello world");
                              alert(x.valueOf())          // Displays "Hello world"

Remarks

  The `valueOf` method of `String` returns the primitive value of a String object as a string data type. This value is equivalent to String.toString.

  This method is usually called internally by JavaScript and not explicitly in code.

See Also

  toString|Object.valueOf

Availability

  JavaScript 1.0|JScript 1.0|ECMAScript v1

## Availability

JavaScript 1.0|JScript 1.0|ECMAScript v1

text_javascript aptana_docs