flash.globalization

# StringTools - AS3

Package | flash.globalization
Class | public final class StringTools
Inheritance | StringTools Object

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The StringTools class provides locale-sensitive case conversion methods.

In some situations the conversion between uppercase and lowercase letters is not a simple mapping from one character to another and instead requires language- or context-specific processing. For example:

- In Turkish and Azeri, the uppercase of the dotted lowercase i is an uppercase dotted İ (U+0130). Similarly the lowercase of a dotless uppercase I, is a lowercase dotless ı (U+0131).
- The lowercase sharp S, ß (U+00DF), used in German is converted to uppercase double SS.
- In Greek there are two representations of the lowercase sigma, σ (U+03C3) and ς (U+03C2), which both convert to the single uppercase sigma Σ (U+03A3).

The `toLowerCase()` and `toUpperCase()` methods of this class provide this special case conversion logic.

Due to the use of the user's settings, the use of case conversion rules provided by the operating system, and the use of a fallback locale when a requested locale is not supported, different users can see different case conversion results even when using the same locale ID.

View the examples

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | actualLocaleIDName : String [read-only] The name of the actual locale ID used by this StringTools object. | StringTools
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | lastOperationStatus : String [read-only] The status of the most recent operation that this StringTools object performed. | StringTools
|  | requestedLocaleIDName : String [read-only] The name of the requested locale ID that was passed to the constructor of this StringTools object. | StringTools

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | StringTools(requestedLocaleIDName:String) Constructs a new StringTools object that provides case conversion and other utilities according to the conventions of a given locale. | StringTools
|  | getAvailableLocaleIDNames():Vector.<String> [static] Lists all of the locale ID names supported by this class. | StringTools
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toLowerCase(s:String):String Converts a string to lowercase according to language conventions. | StringTools
|  | toString():String Returns the string representation of the specified object. | Object
|  | toUpperCase(s:String):String Converts a string to uppercase according to language conventions. | StringTools
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### actualLocaleIDName

property

`actualLocaleIDName:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The name of the actual locale ID used by this StringTools object.

There are three possibilities for the value of the name, depending on operating system and the value of the `requestedLocaleIDName` parameter passed to the `StringTools()` constructor.

1. If the requested locale was not `LocaleID.DEFAULT` and the operating system provides support for the requested locale, then the name returned is the same as the `requestedLocaleIDName` property.
2. If `LocaleID.DEFAULT` was used as the value for the `requestedLocaleIDName` parameter to the constructor, then the name of the current locale specified by the user's operating system is used. The `LocaleID.DEFAULT` value preserves user's customized setting in the OS. Passing an explicit value as the `requestedLocaleIDName` parameter does not necessarily give the same result as using the `LocaleID.DEFAULT` even if the two locale ID names are the same. The user could have customized the locale settings on the machine, and by requesting an explicit locale ID name rather than using `LocaleID.DEFAULT` your application would not retrieve those customized settings.
3. If the system does not support the `requestedLocaleIDName` specified in the constructor then a fallback locale ID name is provided.

Implementation
`public function get actualLocaleIDName():String`

Related API Elements

LocaleID
requestedLocaleIDName
StringTools

### lastOperationStatus

property

`lastOperationStatus:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The status of the most recent operation that this StringTools object performed. The `lastOperationStatus` property is set whenever the constructor or a method of this class is called or another property is set. For the possible values see the description for each method.

Implementation
`public function get lastOperationStatus():String`

Related API Elements

LastOperationStatus

### requestedLocaleIDName

property

`requestedLocaleIDName:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The name of the requested locale ID that was passed to the constructor of this StringTools object.

If the `LocaleID.DEFAULT` value was used then the name returned is "i-default". The actual locale used can differ from the requested locale when a fallback locale is applied. The name of the actual locale can be retrieved using the `actualLocaleIDName` property.

Implementation
`public function get requestedLocaleIDName():String`

Related API Elements

LocaleID
actualLocaleIDName
StringTools()
Constructor Detail

### StringTools

()
Constructor

`public function StringTools(requestedLocaleIDName:String)`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

Constructs a new StringTools object that provides case conversion and other utilities according to the conventions of a given locale.

This constructor determines if the current operating system supports the requested locale ID name. If it is not supported then a fallback locale is used instead. If a fallback locale is used then the `lastOperationStatus` property indicates the type of fallback, and the `actualLocaleIDName` property contains the name of the fallback locale ID.

When this constructor completes successfully the `lastOperationStatus` property is set to:

- `LastOperationStatus.NO_ERROR`

When the requested locale ID name is not available then the `lastOperationStatus` is set to one of the following:

- `LastOperationStatus.USING_FALLBACK_WARNING`
- `LastOperationStatus.USING_DEFAULT_WARNING`

Otherwise the `lastOperationStatus` property is set to one of the constants defined in the LastOperationStatus class.

Parameters

| `requestedLocaleIDName:String` — The preferred locale ID name to use when determining date or time formats.

Throws

| `ArgumentError` — when the `requestedLocaleIDName` parameter is `null`

Related API Elements

LocaleID
lastOperationStatus
requestedLocaleIDName
actualLocaleIDName
Method Detail

### getAvailableLocaleIDNames

()
method

`public static function getAvailableLocaleIDNames():Vector.<String>`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

Lists all of the locale ID names supported by this class.

If this class is not supported on the current operating system, this method returns a null value.

When this method is called and it completes successfully, the `lastOperationStatus` property is set to:

- `LastOperationStatus.NO_ERROR`

Otherwise the `lastOperationStatus` property is set to one of the constants defined in the `LastOperationStatus` class.

Returns

| `Vector.<String>` — A vector of strings containing all of the locale ID names supported by this class.

### toLowerCase

()
method

`public function toLowerCase(s:String):String`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

Converts a string to lowercase according to language conventions. Depending on the locale, the output string length can differ from the input string length.

When this method is called and it completes successfully, the `lastOperationStatus` property is set to:

- `LastOperationStatus.NO_ERROR`

Otherwise the `lastOperationStatus` property is set to one of the constants defined in the `LastOperationStatus` class.

Parameters

| `s:String` — A string to convert to lowercase.

Returns

| `String` — The converted lowercase string.

Throws

| `ArgumentError` — when the `s` parameter is null.

Related API Elements

lastOperationStatus
LastOperationStatus

### toUpperCase

()
method

`public function toUpperCase(s:String):String`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

Converts a string to uppercase according to language conventions. Depending on the locale, the output string length can differ from the input string length.

When this method is called and it completes successfully, the `lastOperationStatus` property is set to:

- `LastOperationStatus.NO_ERROR`

Otherwise the `lastOperationStatus` property is set to one of the constants defined in the `LastOperationStatus` class.

Parameters

| `s:String` — A string to convert to uppercase.

Returns

| `String` — The converted uppercase string.

Throws

| `ArgumentError` — when the `s` parameter is null.

Related API Elements

lastOperationStatus
LastOperationStatus
Examples How to use this example
StringToolsExample.as
This example shows how different strings are converted to lower case and upper case in a lingustically correct manner.

This example takes the following steps:

1. Creates a StringTools object.
2. Defines three strings with characters unique to the Turkish, Greek, and German languages.
3. Converts each string to upper case and lower case and displays the results. This example demonstrates interesting locale-specific behavior for characters like the Turkish "Ä±" and "Ä°", the German "ÃŸ" and the Greek "Î£Ï‚Ïƒ".

Copy

    package {
        import flash.display.Sprite;
        import flash.globalization.LocaleID;
        import flash.globalization.StringTools;
        import flash.text.TextField;
        import flash.text.TextFieldAutoSize;

        public class StringToolsExample extends Sprite
        {
            public function StringToolsExample()
            {
                var localeName:String= LocaleID.DEFAULT;
                var strTool:StringTools = new StringTools(localeName);

                trace('\n\n' + "LocaleID requested: " + nf.requestedLocaleIDName
                + "; actual: " + nf.actualLocaleIDName);
                trace( "Last Operation Status:" + nf.lastOperationStatus );

                var turkishStr:String = "iI Ä±Ä°";
                var greekStr:String = "Î£Ï‚ÏƒÎ²Î°Î�Î£";
                var germanStr:String= "ÃŸ";

                var tfTurInp:TextField = createTextField(10, 10);
                tfTurInp.text="Turkish Input: \t " + turkishStr;

                var tfdash:TextField = createTextField(10, 20);
                tfdash.text="-------------------";

                var tf1:TextField = createTextField(10, 30);
                tf1.text="\t Upper case: \t " + strTool.toUpperCase(turkishStr);

                var tf2:TextField = createTextField(10, 40);
                tf2.text="\t Lower case: \t " + strTool.toLowerCase(turkishStr);

                var tfgreekInp:TextField = createTextField(10, 60);
                tfgreekInp.text="Greek Input: \t " + greekStr;

                var tfdash1:TextField = createTextField(10, 70);
                tfdash1.text="-------------------";

                var tf3:TextField = createTextField(10, 80);
                tf3.text="\t Upper case: \t " + strTool.toUpperCase(greekStr);

                var tf4:TextField = createTextField(10, 90);
                tf4.text="\t Lower case: \t " + strTool.toLowerCase(greekStr);

                var tfgermanInp:TextField = createTextField(10, 110);
                tfgermanInp.text="German Input: \t " + germanStr;

                var tfdash2:TextField = createTextField(10, 120);
                tfdash2.text="-------------------";

                var tf5:TextField = createTextField(10, 130);
                tf5.text="\t Upper case: \t " + strTool.toUpperCase(germanStr);

                var tf6:TextField = createTextField(10, 140);
                tf6.text="\t Lower case: \t " + strTool.toLowerCase(germanStr);
            }

            private function createTextField(x:Number, y:Number):TextField
            {
                var result:TextField = new TextField();
                result.x = x;
                result.y = y;
                result.autoSize=TextFieldAutoSize.LEFT;
                addChild(result);
                return result;
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00