StringNN 2 IE 3 ECMA 1  

  

A String object represents any sequence of zero or more characters that are to be treated strictly as text (that is, no math operations are to be applied). A large library of methods is divided into two categories. One category surrounds a string with a pair of HTML tags for a variety of HTML character formatting. These methods are used primarily to assist statements that use document.write( ) to dynamically create content, but their functionality is now superceded by style sheets. The second, vital method category is the more traditional set of string parsing and manipulation methods that facilitate finding and copying characters and substrings, case changes, and conversion from string lists to JavaScript arrays.

 

By and large, you don't have to worry about explicitly creating a string beyond a simple assignment of a quoted string value:

var myString = "howdy";
 

Occasionally, however, it is helpful to create a string object using the constructor of the static String object. Preparing string values for passage to Java applets often requires this type of string generation:

var myString = new String("howdy");
 

Other than the constructor, prototype property, and fromCharCode( ) method, all properties and methods are for use with instances of the String object, rather than the static String object.

 
Properties
 
constructorlengthprototype
 
Methods
 
anchor( )big( )blink( )bold( )
charAt( )charCodeAt( )concat( )fixed( )
fontcolor( )fontsize( )fromCharCode( )indexOf( )
italics( )lastIndexOf( )link( )localeCompare( )
match( )replace( )search( )slice( )
small( )split( )strike( )sub( )
substr( )substring( )sup( )toLocaleLowerCase( )
toLocaleUpperCase( )toLowerCase( )toString( )toUpperCase( )
valueOf( )
 
Creating a String Object
 
var myValue = "someString";
var myValue = new String("someString");
constructorNN 4 IE 4 ECMA 1  

Read/Write  

This is a reference to the function that created the instance of a String objectthe native String( ) constructor function in browsers.

 
Example
 
if (myVar.constructor == String) {
    // process native string
}
 
Value

Function object reference.

lengthNN 2 IE 3 ECMA 1  

Read-only  

Provides a count of the number of characters in the string. String values dynamically change their lengths if new values are assigned to them or if other strings are concatenated.

 
Example
 
for (var i = 0; i < myString.length; i++) {
    ...
}
 
Value

Integer.

prototypeNN 3 IE 4 ECMA 1  

Read/Write  

This is a property of the static String object. Use the prototype property to assign new properties and methods to future instances of a String value created in the current document. See the Array.prototype property description for examples.

 
Example
 
String.prototype.author = "DG";
 
Value

Any data, including function references.

anchor( )NN 2 IE 3 ECMA n/a  

anchor("anchorName")

  

Returns a copy of the string embedded within an anchor (<a>) tag set. The value passed as a parameter is assigned to the name attribute of the tag.

 
Parameters
 
  • A string to use as the value of the name attribute.
 
Returned Value

A string within an a element.

big( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <big> tag set.

 
Parameters

None.

 
Returned Value

A string within a big element.

blink( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <blink> tag set.

 
Parameters

None.

 
Returned Value

A string within a blink element.

bold( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <b> tag set.

 
Parameters

None.

 
Returned Value

A string within a b element.

charAt( )NN 2 IE 3 ECMA 1  

charAt(positionIndex)

  

Returns a single character string of the character located at the zero-based index position passed as a parameter. Use this method instead of substring( ) when only one character from a known position is needed from a string.

 
Parameters
 
index

A zero-based integer.

 
Returned Value

A one-character string. In newer browser versions, an empty string is returned if the parameter value points to a character beyond the length of the string.

charCodeAt( )NN 4 IE 4 ECMA 1  

charCodeAt(positionIndex)

  

Returns a number of the decimal Unicode value for the character located at the zero-based index position passed as a parameter. For common alphanumeric characters, the Unicode values are the same as ASCII values.

 
Parameters
 
index

A zero-based integer.

 
Returned Value

A positive integer. Returns NaN if the parameter value points to a character beyond the length of the string.

concat( )NN 4 IE 4 ECMA n/a  

concat(string2)

  

Returns a string that appends the parameter string to the current string object. The results of this method are the same as concatenating strings with the add (+) or add-by-value (+=) operators. Neither the method nor operators insert spaces between the two string components.

 
Parameters
 
  • Any string.
 
Returned Value

String.

fixed( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <tt> tag set.

 
Parameters

None.

 
Returned Value

A string within a tt element.

fontcolor( )NN 2 IE 3 ECMA n/a  

fontColor(color)

  

Returns a copy of the string embedded within a font (<font>) tag set. The value passed as a parameter is assigned to the color attribute of the tag.

 
Parameters
 
  • A string to use as the value of the color attribute.
 
Returned Value

A string within a font element.

fontsize( )NN 2 IE 3 ECMA n/a  

fontSize(size)

  

Returns a copy of the string embedded within a font (<font>) tag set. The value passed as a parameter is assigned to the size attribute of the tag.

 
Parameters
 
  • An integer to use as the value of the size attribute.
 
Returned Value

A string within a font element.

fromCharCode( )NN 4 IE 4 ECMA 1  

fromCharCode(num1, [, num2,[...numN]])

  

This is a static method that returns a string of one or more characters with Unicode values that are passed as a comma-delimited list of parameters. For example, the expression:

String.fromCharCode(120, 121, 122)
 

returns "xyz".

 
Parameters
 
  • One or more integer values in an unquoted, comma-delimited list.
 
Returned Value

A string.

indexOf( )NN 2 IE 3 ECMA 1  

indexOf(searchString[, startPositionIndex])

  

Returns a zero-based integer of the position within the current string where the searchString parameter starts. Normally, the search starts with the first (index of zero) character, but you may have the search begin later in the string by specifying the optional second parameter, which is the index value of where the search should start. If there is no match, the returned value is -1. This is a backward-compatible quick way to find out if one string contains another: if the returned value is -1 then you know the searchString is not in the larger string. If the returned value is another number (the precise value doesn't matter), the searchString is in the larger string. For browsers that support regular expressions, the String object's search( ) method performs a similar function.

 
Parameters
 
  • A string to look for in the current string object.
  • A zero-based integer indicating the position within the current string object to begin the search of the first parameter.
 
Returned Value

Integer.

italics( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within an <i> tag set.

 
Parameters

None.

 
Returned Value

A string within an i element.

lastIndexOf( )NN 2 IE 3 ECMA 1  

lastIndexOf(searchString[, startPositionIndex])

  

Returns a zero-based integer of the position within the current string object where the searchString parameter starts. This method works like the indexOf( ) method but begins all searches from the end of the string or some index position. Even though searching starts from the end of the string, the startPositionIndex parameter is based on the start of the string, as is the returned value. If there is no match, the returned value is -1.

 
Parameters
 
  • A string to look for in the current string object.
  • A zero-based integer indicating the position within the current string object to begin the search of the first parameter. Even though the search starts from the end of the string, this parameter value is relative to the front of the string.
 
Returned Value

Integer.

link( )NN 2 IE 3 ECMA n/a  

link(URL)

  

Returns a copy of the string embedded within an anchor (<a>) tag set. The value passed as a parameter is assigned to the href attribute of the tag.

 
Parameters
 
  • A string to use as the value of the href attribute.
 
Returned Value

A string within an a element.

localeCompare( )NN 6 IE 5.5(Win) ECMA 3  

localeCompare(string2)

  

Returns a number indicating whether the current string sorts before, the same as, or after the parameter string, based on browser- and system-dependent string localization. If the current string sorts before the parameter string, the return value is a negative number; if they are the same, the return value is 0, if the current string sorts after the parameter string, the return value is a positive number.

 

Use this method with caution if the strings contain characters outside the Latin character set because each browser can determine what localization equalities are in place. They also calculate the return values differently.

 
Parameters
 
  • Any string.
 
Returned Value

Integer

match( )NN 4 IE 4 ECMA 3  

match(regexpression)

  

Returns an array of strings within the current string that match the regular expression passed as a parameter. For example, if you pass a regular expression that specifies any five-digit number, the returned value of the match( ) method would be an array of all five-digit numbers (as strings) in the main string. Properties of the RegExp static object are influenced by this method's operation.

 
Parameters
 
  • A regular expression object. See the regular expression object for the syntax to create a regular expression object.
 
Returned Value

An array of strings.

replace( )NN 4 IE 4 ECMA 3  

replace(regexpression, replaceString)

  

Returns the new string that results when matches of the regexpression parameter are replaced by the replaceString parameter. The original string is unharmed in the process, so you need to capture the returned value in a variable to preserve the changes.

 
Parameters
 
  • A regular expression object. If you want the replace( ) method to act globally on the string, set the global switch (g) on the regular expression. See the regular expression object for the syntax to create a regular expression object.
  • A string that is to take the place of all matches of regexpression in the current string.
 
Returned Value

A string.

search( )NN 4 IE 4 ECMA 3  

search(regexpression)

  

Returns the zero-based indexed value of the first character in the current string that matches the pattern of the regexpression parameter. This method is similar to the indexOf( ) method, but the search is performed with a regular expression rather than a straight string.

 
Parameters
 
  • A regular expression object. See the regular expression object for the syntax to create a regular expression object.
 
Returned Value

Integer.

slice( )NN 4 IE 4 ECMA 3  

slice(startPositionIndex, endPositionIndex])

  

Returns a substring of the current string. The substring is copied from the main string starting at the zero-based index count value of the character in the main string. If no second parameter is provided, the substring extends to the end of the main string. The optional second parameter can be another zero-based index value of where the substring should end. This value may also be a negative value, which counts from the end of the string toward the front.

 
Parameters
 
  • A zero-based integer indicating the position within the current string object to start copying characters.
  • A zero-based integer indicating the position within the current string object to end copying characters. Negative values count inward from the end of the string.
 
Returned Value

String.

small( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <small> tag set.

 
Parameters

None.

 
Returned Value

A string within a small element.

split( )NN 3 IE 4 ECMA 1  

split(delimiter [, limitInteger])

  

Returns a new array object whose elements are segments of the current string. The current string is divided into array entries at each instance of the delimiter string specified as the first parameter of the method. The delimiter does not become part of the array. You do not have to declare the array prior to stuffing the results of the split( ) method. For example, if a string consists of a comma-delimited list of names, you can convert the list into an array as follows:

var listArray = stringList.split(",");
 

You may also use a regular expression as the parameter to divide the string by a pattern rather than a fixed character.

 
Parameters
 
  • A string or regular expression that defines where the main string is divided into elements of the resulting array.
  • An optional integer that restricts the number of items converted into array elements.
 
Returned Value

Array.

strike( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <strike> tag set.

 
Parameters

None.

 
Returned Value

A string within a strike element.

sub( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <sub> tag set.

 
Parameters

None.

 
Returned Value

A string within a sub element.

substr( )NN 4 IE 4 ECMA n/a  

substr(startPositionIndex [, length])

  

Returns a copy of an extract from the current string. The extract begins at the zero-based index position of the current string as specified by the first parameter of the method. If no other parameter is provided, the extract continues to the end of the main string. The second parameter can specify an integer of the number of characters to be extracted from the main string. In contrast, the substring( ) method's parameters point to the start and end position index values of the main string.

 
Parameters
 
  • A zero-based integer indicating the position within the current string object to start copying characters
  • An optional integer of the number of characters to extract, starting with the character indicated by the startPositionIndex parameter
 
Returned Value

A string.

substring( )NN 2 IE 3 ECMA 1  

substring(startPositionIndex, endPositionIndex)

  

Returns a copy of an extract from the current string. The extract begins at the zero-based index position of the current string as specified by the first parameter of the method and ends just before the character whose index is specified by the second parameter. For example, "Frobnitz".substring(0,4) returns the substring from positions 0 through 3: Frob. In contrast, the substr( ) method's parameters point to the start position of the main string and the number of characters (length) to extract.

 
Parameters
 
  • A zero-based integer indicating the position within the current string object to start copying characters.
  • A zero-based integer indicating the position within the current string object to end copying characters. In other words, the copy is made from startPositionIndex up to, but not including, the character at position endPositionIndex.
 
Returned Value

A string.

sup( )NN 2 IE 3 ECMA n/a  

  

Returns a copy of the string embedded within a <sup> tag set.

 
Parameters

None.

 
Returned Value

A string within a sup element.

toLocaleLowerCase( ), toLocaleUpperCase( )NN 6 IE 5.5 ECMA 3  

  

Return a copy of the current string in all lowercase or uppercase letters. Works the same as the regular version, except for some non-Latin alphabets with character mappings that may require special internal handling.

 
Parameters

None.

 
Returned Value

String.

toLowerCase( ), toUpperCase( )NN 2 IE 3 ECMA 1  

  

Return a copy of the current string in all lowercase or uppercase letters. If you want to replace the current string with a case-adjusted version, assign the result of the method to the same string:

myString = myString.toUpperCase( );
 

It is common to use either one of these methods to create a case-insensitive comparison of two strings. This is especially convenient if one of the strings being compared is entered by a user, who may submit a variety of case situations:

if (document.forms[0].entry.value.toLowerCase( ) == compareValue) {
    ...
}
 
Parameters

None.

 
Returned Value

String.

toString( ), valueOf( )NN 4 IE 4 ECMA 1  

  

Return a string value of the object.

 
Parameters

None.

 
Returned Value

String value.