NAME

String::FormatX - Perl extension for formatting strings and numbers

Purpose

Formats a string based on pre-defined String::FormatX templates or user-supplied template patterns.

Requires

You will need all of the modules below to be installed for the String::FormatX library to work.

Exporter

Number::Format

Carp

Synopsis

        # As a function library...

        use String::FormatX qw(FormatX);

        my $FormattedSSN = FormatX('123456789','999-99-9999');
        print $FormattedSSN; # prints 123-45-6789

        my $GreenMoney = FormatX('123456789','~PRICE');
        print $GreenMoney; # prints $ 1,234,567.89


        # As an object...

        use String::FormatX;
        my $StrObj = new String::FormatX;

        my $FormattedSSN = $StrObj->FormatX('123456789','999-99-9999');
        print $FormattedSSN; # prints 123-45-6789

Author

Lance P. Cleveland Charleston Software Associates (www.CharlestonSW.com) (c) 2005-2006 - Charleston Software Associates, Inc.

Public Methods

new()

 Create a new String::FormatX object.

 Properties
 ERRMSG - contains last error message generated during String::FormatX processing
 

new()

 Create a new FormatX object.

FormatX()

 Return a string formatted as instructed.

 Parameters
 STR            => Input string to be formatted
 FORMAT  =>     Format template

The FORMAT Parameter

 FORMAT can be set to a predefined string as in FORMAT=>'~PRICE' or to a
 user-defined output string as in FORMAT=>'999-99-9999'.

 Predefined Strings
 ~PRICE - return a price starting with "$ ", comma separated, and 2 decimal precision

 User Defined Strings
 9 - only a numeric allowed in this position
 X - alphanumeric and '_' allowed in this position 
 All other characters are taken as literal replacements within the text.

 Processing
 When a '9' or 'X' appears in the format string the input string is processed
 scanning for the next numeric or alphanumeric throwing away all interim
 characters during the search.  In other words, if we are looking for digit format
 such as '999.99' and we get 'blah12blah345' you end up with '123.45' because
 we threw away the blah blah.