Properties | Methods
Top Level

Class String

Object

public class String
extends Object

Player version: Flash Player 5 — (became a native object in Flash Player 6, which improved performance significantly).

The String class is a wrapper for the string primitive data type, and provides methods and properties that let you manipulate primitive string value types. You can convert the value of any object into a string using the String() function.

All the methods of the String class, except for concat(), fromCharCode(), slice(), and substr(), are generic, which means the methods call toString() before performing their operations, and you can use these methods with other non-String objects.

Because all string indexes are zero-based, the index of the last character for any string x is x.length - 1.

You can call any of the methods of the String class using the constructor method new String or using a string literal value. If you specify a string literal, the ActionScript interpreter automatically converts it to a temporary String object, calls the method, and then discards the temporary String object. You can also use the String.length property with a string literal.

Do not confuse a string literal with a String object. In the following example, the first line of code creates the string literal first_string, and the second line of code creates the String object second_string:

var first_string:String = "foo" 
var second_string:String = new String("foo")

Use string literals unless you specifically need to use a String object.



Property Summary
length : Number
An integer specifying the number of characters in the specified String object.

Properties inherited from class Object
__proto__, __resolve, constructor, prototype


Constructor Summary
String(value:String)
Creates a new String object.


Method Summary
charAt(index:Number) : String
Returns the character in the position specified by the parameter index.
charCodeAt(index:Number) : Number
Returns a 16-bit integer from 0 to 65535 that represents the character specified by index.
concat(value:Object) : String
Combines the value of the String object with the parameters and returns the newly formed string; the original value, my_str, is unchanged.
static fromCharCode() : String
Returns a string comprising the characters represented by the Unicode values in the parameters.
indexOf(value:String, [startIndex:Number]) : Number
Searches the string and returns the position of the first occurrence of value found at or after startIndex within the calling string.
lastIndexOf(value:String, [startIndex:Number]) : Number
Searches the string from right to left and returns the index of the last occurrence of value found before startIndex within the calling string.
slice(start:Number, end:Number) : String
Returns a string that includes the start character and all characters up to, but not including, the end character.
split(delimiter:String, [limit:Number]) : Array
Splits a String object into substrings by breaking it wherever the specified delimiter parameter occurs and returns the substrings in an array.
substr(start:Number, length:Number) : String
Returns the characters in a string from the index specified in the start parameter through the number of characters specified in the length parameter.
substring(start:Number, end:Number) : String
Returns a string comprising the characters between the points specified by the start and end parameters.
toLowerCase() : String
Returns a copy of the String object, with all uppercase characters converted to lowercase.
toString() : String
Returns an object's properties as strings regardless of whether the properties are strings.
toUpperCase() : String
Returns a copy of the String object, with all lowercase characters converted to uppercase.
valueOf() : String
Returns the primitive value of a String instance.

Methods inherited from class Object
addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch


Property Detail

length Property

public length : Number

Player version: Flash Player 5

An integer specifying the number of characters in the specified String object.

Because all string indexes are zero-based, the index of the last character for any string x is x.length - 1.

Example
The following example creates a new String object and uses String.length to count the number of characters: 
var my_str:String = "Hello world!";
trace(my_str.length); // output: 12

The following example loops from 0 to my_str.length. The code checks the characters within a string, and if the string contains the @ character, true displays in the Output panel. The code checks the characters within a string, and if the string contains the @ character, true writes to the log file. If it does not contain the @ character, then false displays in the Output panel. If it does not contain the @ character, then false writes to the log file.

function checkAtSymbol(my_str:String):Boolean {
    for (var i = 0; i<my_str.length; i++) {
    if (my_str.charAt(i) == "@") {
        return true;
    }
    }
    return false;
}

trace(checkAtSymbol("dog@house.net")); // output: true
trace(checkAtSymbol("Chris")); // output: false

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:



Constructor Detail

String Constructor

public String(value:String)

Player version: Flash Player 5

Creates a new String object.

Note: Because string literals use less overhead than String objects and are generally easier to use, you should use string literals instead of the constructor for the String class unless you have a good reason to use a String object rather than a string literal.

Parameters
value:String — The initial value of the new String object.


Method Detail

charAt Method

public charAt(index:Number) : String

Player version: Flash Player 5

Returns the character in the position specified by the parameter index. If index is not a number from 0 to string.length - 1, an empty string is returned.

This method is similar to String.charCodeAt() except that the returned value is a character, not a 16-bit integer character code.

Parameters
index:Number — An integer specifying the position of a character in the string. The first character is indicated by 0, and the last character is indicated by my_str.length-1.

Returns
String — The character at the specified index. Or an empty String if the specified index is outside the range of this String's indices.

Example
In the following example, this method is called on the first letter of the string "Chris": 
var my_str:String = "Chris";
var firstChar_str:String = my_str.charAt(0);
trace(firstChar_str); // output: C

See also
String.charCodeAt()

charCodeAt Method

public charCodeAt(index:Number) : Number

Player version: Flash Player 5

Returns a 16-bit integer from 0 to 65535 that represents the character specified by index. If index is not a number from 0 to string.length - 1, NaN is returned.

This method is similar to String.charAt() except that the returned value is a 16-bit integer character code, not a character.

Parameters
index:Number — An integer that specifies the position of a character in the string. The first character is indicated by 0, and the last character is indicated by my_str.length - 1.

Returns
Number — An integer that represents the character specified by index.

Example
In the following example, this method is called on the first letter of the string "Chris": 
var my_str:String = "Chris";
var firstChar_num:Number = my_str.charCodeAt(0);
trace(firstChar_num); // output: 67

See also
String.charAt()

concat Method

public concat(value:Object) : String

Player version: Flash Player 5

Combines the value of the String object with the parameters and returns the newly formed string; the original value, my_str, is unchanged.

Parameters
value:Object — value1[,...valueN] Zero or more values to be concatenated.

Returns
String — A string.

Example
The following example creates two strings and combines them using String.concat(): 
var stringA:String = "Hello";
var stringB:String = "World";
var combinedAB:String = stringA.concat(" ", stringB);
trace(combinedAB); // output: Hello World

fromCharCode Method

public static fromCharCode() : String

Player version: Flash Player 5

Returns a string comprising the characters represented by the Unicode values in the parameters.

Returns
String — A string value of the specified Unicode character codes.

Example
The following example uses fromCharCode() to insert an @ character in the e-mail address: 
var address_str:String = "dog"+String.fromCharCode(64)+"house.net";
trace(address_str); // output: dog@house.net

indexOf Method

public indexOf(value:String, [startIndex:Number]) : Number

Player version: Flash Player 5

Searches the string and returns the position of the first occurrence of value found at or after startIndex within the calling string. This index is zero-based, meaning that the first character in a string is considered to be at index 0--not index 1. If value is not found, the method returns -1.

Parameters
value:String — A string; the substring to search for.
startIndex:Number [optional] — An integer specifying the starting index of the search.

Returns
Number — The position of the first occurrence of the specified substring or -1.

Example
The following examples use indexOf() to return the index of characters and substrings: 
var searchString:String = "Lorem ipsum dolor sit amet.";
var index:Number;

index = searchString.indexOf("L");
trace(index); // output: 0

index = searchString.indexOf("l");
trace(index); // output: 14

index = searchString.indexOf("i");
trace(index); // output: 6

index = searchString.indexOf("ipsum");
trace(index); // output: 6

index = searchString.indexOf("i", 7);
trace(index); // output: 19

index = searchString.indexOf("z");
trace(index); // output: -1

See also
String.lastIndexOf()

lastIndexOf Method

public lastIndexOf(value:String, [startIndex:Number]) : Number

Player version: Flash Player 5

Searches the string from right to left and returns the index of the last occurrence of value found before startIndex within the calling string. This index is zero-based, meaning that the first character in a string is considered to be at index 0--not index 1. If value is not found, the method returns -1.

Parameters
value:String — The string for which to search.
startIndex:Number [optional] — An integer specifying the starting point from which to search for value.

Returns
Number — The position of the last occurrence of the specified substring or -1.

Example
The following example shows how to use lastIndexOf() to return the index of a certain character: 
var searchString:String = "Lorem ipsum dolor sit amet.";
var index:Number;

index = searchString.lastIndexOf("L");
trace(index); // output: 0

index = searchString.lastIndexOf("l");
trace(index); // output: 14

index = searchString.lastIndexOf("i");
trace(index); // output: 19

index = searchString.lastIndexOf("ipsum");
trace(index); // output: 6

index = searchString.lastIndexOf("i", 18);
trace(index); // output: 6

index = searchString.lastIndexOf("z");
trace(index); // output: -1

See also
String.indexOf()

slice Method

public slice(start:Number, end:Number) : String

Player version: Flash Player 5

Returns a string that includes the start character and all characters up to, but not including, the end character. The original String object is not modified. If the end parameter is not specified, the end of the substring is the end of the string. If the character indexed by start is the same as or to the right of the character indexed by end, the method returns an empty string.

Parameters
start:Number — The zero-based index of the starting point for the slice. If start is a negative number, the starting point is determined from the end of the string, where -1 is the last character.
end:Number — An integer that is one greater than the index of the ending point for the slice. The character indexed by the end parameter is not included in the extracted string. If this parameter is omitted, String.length is used. If end is a negative number, the ending point is determined by counting back from the end of the string, where -1 is the last character.

Returns
String — A substring of the specified string.

Example
The following example creates a variable, my_str, assigns it a String value, and then calls the slice() method using a variety of values for both the start and end parameters. Each call to slice() is wrapped in a trace() statement that displays the output in the Output panel. Each call to the slice() method is wrapped in a trace() statement that sends the output to the log file. 
// Index values for the string literal
// positive index:  0   1   2   3   4
// string:          L   o   r   e   m
// negative index: -5  -4  -3  -2  -1

var my_str:String = "Lorem";

// slice the first character
trace("slice(0,1): "+my_str.slice(0, 1)); // output: slice(0,1): L
trace("slice(-5,1): "+my_str.slice(-5, 1)); // output: slice(-5,1): L

// slice the middle three characters
trace("slice(1,4): "+my_str.slice(1, 4)); // slice(1,4): ore
trace("slice(1,-1): "+my_str.slice(1, -1)); // slice(1,-1): ore

// slices that return empty strings because start is not to the left of end
trace("slice(1,1): "+my_str.slice(1, 1)); // slice(1,1):
trace("slice(3,2): "+my_str.slice(3, 2)); // slice(3,2):
trace("slice(-2,2): "+my_str.slice(-2, 2)); // slice(-2,2):

// slices that omit the end parameter use String.length, which equals 5
trace("slice(0): "+my_str.slice(0)); // slice(0): Lorem
trace("slice(3): "+my_str.slice(3)); // slice(3): em

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

See also
String.substr(), String.substring()

split Method

public split(delimiter:String, [limit:Number]) : Array

Player version: Flash Player 5

Splits a String object into substrings by breaking it wherever the specified delimiter parameter occurs and returns the substrings in an array. If you use an empty string ("") as a delimiter, each character in the string is placed as an element in the array.

If the delimiter parameter is undefined, the entire string is placed into the first element of the returned array.

Parameters
delimiter:String — A string; the character or string at which my_str splits.
limit:Number [optional] — The number of items to place into the array.

Returns
Array — An array containing the substrings of my_str.

Example
The following example returns an array with five elements: 
var my_str:String = "P,A,T,S,Y";
var my_array:Array = my_str.split(",");
for (var i = 0; i<my_array.length; i++) {
    trace(my_array[i]);
}
// output:
    P
    A
    T
    S
    Y

The following example returns an array with two elements, "P" and "A":

var my_str:String = "P,A,T,S,Y";
var my_array:Array = my_str.split(",", 2);
trace(my_array); // output: P,A

The following example shows that if you use an empty string ("") for the delimiter parameter, each character in the string is placed as an element in the array:

var my_str:String = new String("Joe");
var my_array:Array = my_str.split("");
for (var i = 0; i<my_array.length; i++) {
    trace(my_array[i]);
}
// output:
    J
    o
    e

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

See also
Array.join()

substr Method

public substr(start:Number, length:Number) : String

Player version: Flash Player 5

Returns the characters in a string from the index specified in the start parameter through the number of characters specified in the length parameter. The substr method does not change the string specified by my_str; it returns a new string.

Parameters
start:Number — An integer that indicates the position of the first character in my_str to be used to create the substring. If start is a negative number, the starting position is determined from the end of the string, where the -1 is the last character.
length:Number — The number of characters in the substring being created. If length is not specified, the substring includes all the characters from the start to the end of the string.

Returns
String — A substring of the specified string.

Example
The following example creates a new string, my_str and uses substr() to return the second word in the string; first, using a positive start parameter, and then using a negative start parameter: 
var my_str:String = new String("Hello world");
var mySubstring:String = new String();
mySubstring = my_str.substr(6,5);
trace(mySubstring); // output: world

mySubstring = my_str.substr(-5,5);
trace(mySubstring); // output: world

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

substring Method

public substring(start:Number, end:Number) : String

Player version: Flash Player 5

Returns a string comprising the characters between the points specified by the start and end parameters. If the end parameter is not specified, the end of the substring is the end of the string. If the value of start equals the value of end, the method returns an empty string. If the value of start is greater than the value of end, the parameters are automatically swapped before the function executes and the original value is unchanged.

Parameters
start:Number — An integer that indicates the position of the first character of my_str used to create the substring. Valid values for start are 0 through String.length - 1. If start is a negative value, 0 is used.
end:Number — An integer that is 1+ the index of the last character in my_str to be extracted. Valid values for end are 1 through String.length. The character indexed by the end parameter is not included in the extracted string. If this parameter is omitted, String.length is used. If this parameter is a negative value, 0 is used.

Returns
String — A substring of the specified string.

Example
The following example shows how to use substring(): 
var my_str:String = "Hello world";
var mySubstring:String = my_str.substring(6,11);
trace(mySubstring); // output: world

The following example shows what happens if a negative start parameter is used:

var my_str:String = "Hello world";
var mySubstring:String = my_str.substring(-5,5);
trace(mySubstring); // output: Hello

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

toLowerCase Method

public toLowerCase() : String

Player version: Flash Player 5

Returns a copy of the String object, with all uppercase characters converted to lowercase. The original value is unchanged.

Returns
String — A string.

Example
The following example creates a string with all uppercase characters and then creates a copy of that string using toLowerCase() to convert all uppercase characters to lowercase characters: 
var upperCase:String = "LOREM IPSUM DOLOR";
var lowerCase:String = upperCase.toLowerCase();
trace("upperCase: " + upperCase); // output: upperCase: LOREM IPSUM DOLOR
trace("lowerCase: " + lowerCase); // output: lowerCase: lorem ipsum dolor

An example is also in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

See also
String.toUpperCase()

toString Method

public toString() : String

Player version: Flash Player 5

Returns an object's properties as strings regardless of whether the properties are strings.

Returns
String — The string.

Example
The following example outputs an uppercase string that lists all of an object's properties, regardless of whether the properties are strings: 
var employee:Object = new Object();
employee.name = "bob";
employee.salary = 60000;
employee.id = 284759021;

var employeeData:String = new String();
for (prop in employee) 
{
    employeeData += employee[prop].toString().toUpperCase() + " ";
}
trace(employeeData);
If the toString() method were not included in this code, and the line in the for loop used employee[prop].toUpperCase(), the output would be "undefined undefined BOB". Including the toString() method produces the desired output: "284759021 60000 BOB".

toUpperCase Method

public toUpperCase() : String

Player version: Flash Player 5

Returns a copy of the String object, with all lowercase characters converted to uppercase. The original value is unchanged.

Returns
String — A string.

Example
The following example creates a string with all lowercase characters and then creates a copy of that string using toUpperCase(): 
var lowerCase:String = "lorem ipsum dolor";
var upperCase:String = lowerCase.toUpperCase();
trace("lowerCase: " + lowerCase); // output: lowerCase: lorem ipsum dolor
trace("upperCase: " + upperCase); // output: upperCase: LOREM IPSUM DOLOR

An example is also found in the Strings.fla file in the ActionScript samples folder. The following list gives typical paths to this folder:

See also
String.toLowerCase()

valueOf Method

public valueOf() : String

Player version: Flash Player 5

Returns the primitive value of a String instance. This method is designed to convert a String object into a primitive string value. Because Flash Player automatically calls valueOf() when necessary, you rarely need to explicitly call this method.

Returns
String — The value of the string.

Example
The following example creates a new instance of the String class and then shows that the valueOf method returns the primitive value, rather than a reference to the new instance. 
var str:String = new String("Hello World");
var value:String = str.valueOf();
trace(str instanceof String); // true
trace(value instanceof String); // false
trace(str === value); // false

Properties | Methods

Copyright © 2005 Macromedia Inc. All rights reserved.
Tue Sep 13 2005, 16:15 PDT