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.