Object | +-String public class String extends Object 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. Availability: ActionScript 1.0; Flash Player 5 - (became a native object in Flash Player 6, which improved performance significantly). Property summary
Properties inherited from class Object
Constructor summary
Method summary
Methods inherited from class Object
charAt (String.charAt method)public charAt(index:Number) : String 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. Availability: ActionScript 1.0; Flash Player 5 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 indeces. 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 charCodeAt (String.charCodeAt method) charCodeAt (String.charCodeAt method)public charCodeAt(index:Number) : Number 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. Availability: ActionScript 1.0; Flash Player 5 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 charAt (String.charAt method) concat (String.concat method)public 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. Availability: ActionScript 1.0; Flash Player 5 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 (String.fromCharCode method)public static fromCharCode() : String Returns a string comprising the characters represented by the Unicode values in the parameters. Availability: ActionScript 1.0; Flash Player 5 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 (String.indexOf method)public 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. 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. Availability: ActionScript 1.0; Flash Player 5 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 lastIndexOf (String.lastIndexOf method) lastIndexOf (String.lastIndexOf method)public 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. 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. Availability: ActionScript 1.0; Flash Player 5 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 indexOf (String.indexOf method) length (String.length property)public length : Number 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. Availability: ActionScript 1.0; Flash Player 5 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. If it does not contain the @ character, then false displays in the Output panel. 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:
slice (String.slice method)public 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. 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. Availability: ActionScript 1.0; Flash Player 5 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. // 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 substr (String.substr method), substring (String.substring method) split (String.split method)public 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. 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. Availability: ActionScript 1.0; Flash Player 5 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 join (Array.join method) String constructorpublic String(value:String) 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. Availability: ActionScript 1.0; Flash Player 5 Parameters value:String - The initial value of the new String object. substr (String.substr method)public 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. The substr method does not change the string specified by my_str; it returns a new string. Availability: ActionScript 1.0; Flash Player 5 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 (String.substring method)public substring(start:Number, end:Number) : String 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. Availability: ActionScript 1.0; Flash Player 5 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 (String.toLowerCase method)public toLowerCase() : String Returns a copy of the String object, with all uppercase characters converted to lowercase. The original value is unchanged. Availability: ActionScript 1.0; Flash Player 5 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 toUpperCase (String.toUpperCase method) toString (String.toString method)public toString() : String Returns an object's properties as strings regardless of whether the properties are strings. Availability: ActionScript 1.0; Flash Player 5 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 (String.toUpperCase method)public toUpperCase() : String Returns a copy of the String object, with all lowercase characters converted to uppercase. The original value is unchanged. Availability: ActionScript 1.0; Flash Player 5 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 toLowerCase (String.toLowerCase method) valueOf (String.valueOf method)public valueOf() : String 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. Availability: ActionScript 1.0; Flash Player 5 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 |