You can use the SwitchSymbolFormatter utility class when you create custom formatters. You use this class to replace placeholder characters in one string with numbers from a second string.

For example, you specify the following information to the SwitchSymbolFormatter class:

Format string  

The Social Security number is: ###-##-####"

Input string 

"123456789"

The SwitchSymbolFormatter class parses the format string and replaces each placeholder character with a number from the input string in the order in which the numbers are specified in the input string. The default placeholder character is the number sign (#). You can define a different placeholder character by passing it to the constructor when you create a SwitchSymbolFormatter object. For an example, see Using a different placeholder character.

The SwitchSymbolFormatter class creates the following output string from the Format and Input strings:

"The Social Security number is: 123-45-6789"

You pass the format string and input string to the SwitchSymbolFormatter.formatValue() method to create the output string, as the following example shows:

<?xml version="1.0" ?>
<!-- formatters/FormatterSwitchSymbol.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Script>
    <![CDATA[
        
      import mx.formatters.SwitchSymbolFormatter;                

      // Event handler to validate and format input.            
      private function formatVal():void {
          
        var switcher:SwitchSymbolFormatter=new SwitchSymbolFormatter('#');

        formattedSCNumber.text = 
          switcher.formatValue("Formatted Social Securty number: ###-##-#### ", scNum.text);
      }
    ]]>
  </mx:Script>

  <mx:Label text="Enter a 9 digit Social Security number with no separator characters:"/>
  <mx:TextInput id="scNum" text="" maxChars="9" width="50%"/>

  <mx:Button label="Format" click="formatVal();"/>
  <mx:TextInput id="formattedSCNumber" editable="false" width="75%"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can mix alphanumeric characters and placeholder characters in this format string. The format string can contain any characters that are constant for all values of the numeric portion of the string. However, the input string for formatting must be numeric. The number of digits supplied in the source value must match the number of digits defined in the format string.

Using a different placeholder character

By default, the SwitchSymbolFormatter class uses a number sign (#) as the placeholder character to indicate a number substitution within its format string. However, sometimes you might want to include a number sign in your actual format string. Then, you must use a different symbol to indicate a number substitution slot within the format string. You can select any character for this alternative symbol as long as it doesn't appear in the format string.

For example, to use the ampersand character (&) as the placeholder, you create an instance of the SwitchSymbolFormatter class, as the following example shows:

var dataFormatter = new SwitchSymbolFormatter("&");

Handling errors with the SwitchSymbolFormatter class

Unlike other formatters, the SwitchSymbolFormatter class does not write its error messages into an error property. Instead, it is your responsibility to test for error conditions and return an error message if appropriate.

The custom formatter component in the following example formats nine-digit Social Security numbers by using the SwitchSymbolFormatter class:

package myFormatters
{
    // formatters/myFormatter/CustomSSFormatter.as
    import mx.formatters.Formatter
    import mx.formatters.SwitchSymbolFormatter

    public class CustomSSFormatter extends Formatter 
    {
        // Declare the variable to hold the pattern string.
        public var formatString : String = "###-##-####";

        // Constructor
        public function CustomSSFormatter() {
            // Call base class constructor.
            super();
        }

        // Override format().
        override public function format( value:Object ):String {
            // Validate input string value - must be a 9-digit number.
            // You must explicitly check if the value is a number.
            // The formatter does not do that for you. 
            if( !value  || value.toString().length != 9)
                {   error="Invalid String Length";
                    return ""
                }

            // Validate format string.
            // It must contain 9 number placeholders.
            var numCharCnt:int = 0;
            for( var i:int = 0; i<formatString.length; i++ )
                {
                    if( formatString.charAt(i) == "#" )
                    {   numCharCnt++;
                    }
                }

            if( numCharCnt != 9 )
            {
                error="Invalid Format String";
                return ""
            }

            // If the formatString and value are valid, format the number.
            var dataFormatter:SwitchSymbolFormatter = 
                new SwitchSymbolFormatter();
            return dataFormatter.formatValue( formatString, value );
        }
    }
}

The following example uses this custom formatter in an application:

<?xml version="1.0" encoding="UTF-8"?>
<!-- formatters/FormatterSS.mxml -->

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComp="myFormatters.*"> 

    <!-- Declare a formatter and specify formatting properties. -->
    <MyComp:CustomSSFormatter id="SSFormat" 
        formatString="SS: #-#-#-#-#-#-#-#-#"/>

    <!-- Trigger the formatter while populating a string with data. -->
    <mx:TextInput text="Your SS number is {SSFormat.format('123456789')}"/> 

</mx:Application>
The executing SWF file for the previous example is shown below: