NAME
PAB3::Utils - Utility functions for the PAB3 environment or as standalone
SYNOPSIS
use PAB3::Utils qw(:default);
# all functions should be thread safe and does NOT affect
# to CORE::localtime or POSIX locale and time functions
# create an object of PAB3::Utils
$utils = PAB3::Utils->new();
$locale = set_locale( @locale );
set_user_locale( $hash_ref );
$bool = set_timezone( $timezone );
@ta = PAB3::Utils::localtime();
@ta = PAB3::Utils::gmtime();
# almost POSIX compatible
$string = strftime( $format );
$string = strftime( $format, $timestamp );
$string = strftime( $format, $timestamp, $gmt );
# almost POSIX compatible
$string = strfmon( $format, $number );
$string = number_format( $number );
$string = number_format( $number, $right_prec );
$string = number_format( $number, $right_prec, $dec_point );
$string = number_format( $number, $right_prec, $dec_point, $thou_sep );
$string = number_format(
$number, $right_prec, $dec_point, $thou_sep, $neg_sign
);
$string = number_format(
$number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign
);
$string = number_format(
$number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign,
$left_prec
);
$string = number_format(
$number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign,
$left_prec, $fillchar
);
$newstr = str_trim( $string );
$string = round( $number );
$string = round( $number, $precision );DESCRIPTION
PAB3::Utils implements thread safe locale and time support and some other useful functions.
This module should be threadsafe, BUT:
Under ModPerl or PerlEx environments several scripts may take access to the same instance of the Perl interpreter. All module functions are interpreter global! If you plan using several locale and time settings in your scripts which may take access to the same interpreter you should use new() to create independend objects.
EXAMPLES
Standard Use
use PAB3::Utils;
&PAB3::Utils::set_timezone( 'Europe/Berlin' );
&PAB3::Utils::set_locale( 'de_DE.UTF-8' );
print &PAB3::Utils::strftime( '%c', time ), "\n";Exporting goodies
use PAB3::Utils qw(:default); # localtime and gmtime are not exported
set_timezone( 'Europe/Berlin' );
set_locale( 'de_DE.UTF-8' );
print strftime( '%c', time ), "\n";OO design
use PAB3::Utils;
$utils = PAB3::Utils->new();
$utils->set_timezone( 'America/New_York' );
$utils->set_locale( 'en_US' );
print $utils->strftime( '%c' ), "\n";METHODS
- new ()
-
Creates a new class of PAB3::Utils and returns it.
- setlocale ( @locals )
- set_locale ( @locals )
-
Set locale information. setlocale is a synonym for set_locale.
Parameters
@locals
One or more locale strings. Each parameter is tried to be set as new locale until success.
For example:
$localestr = set_locale( 'en', 'en_EN', 'en_US' ); print "New locale is $localestr\n";Return Values
Returns the new locale set, or FALSE if no locale could be found.
- set_user_locale ( $hash_ref )
-
Set userdefined locale information.
Parameters
$hash_ref
A hashref with locale information. Following fields are used in short or long version:
'dp' or 'decimal_point' => decimal point character 'ts' or 'thousands_sep' => thousands separator 'grp' or 'grouping' => numeric grouping, (i.e. [3, 2]) 'cs' or 'currency_symbol' => local currency symbol (i.e. $) 'ics' or 'int_curr_symbol' => international currency symbol (i.e. USD) 'csa' or 'curr_symb_align' => currency symbol alignment: 'l' = left side, 'r' = right side 'css' or 'curr_symb_space' => space between currency symbol and value: true or false 'fd' or 'frac_digits' => local fractional digits 'ifd' or 'int_frac_digits' => international fractional digits 'ns' or 'negative_sign' => sign for negative values 'ps' or 'positive_sign' => sign for positive values 'aml' or 'am_lower' => A.M. string in lower case (i.e. am) 'pml' or 'pm_lower' => P.M. string in lower case (i.e. pm) 'amu' or 'am_upper' => A.M. string in upper case (i.e. AM) 'pmu' or 'pm_upper' => P.M. string in upper case (i.e. PM) 'apf' or 'ampm_format' => am/pm format string (i.e. %I:%M:%S %p) 'df' or 'date_format' => date format (i.e. %m/%d/%Y) 'tf' or 'time_format' => time format (i.e. %H:%M:%S) 'dtf' or 'datetime_format' => datetime format (i.e. %a %d %b %Y %r %Z) 'sdn' or 'short_day_names' => array with short day names 'ldn' or 'long_day_names' => array with long day names 'smn' or 'short_month_names' => array with short month names 'lmn' or 'long_month_names' => array with long month namesReturn Values
Returns nothing.
Example
my %locale = ( 'dp' => '.', 'ts' => ',', 'grp' => [3, 3], 'cs' => '$', 'ics' => 'USD', 'csa' => 'l', 'css' => 0, 'fd' => 2, 'ifd' => 2, 'ns' => '-', 'ps' => '+', 'aml' => 'am', 'pml' => 'pm', 'amu' => 'AM', 'pmu' => 'PM', 'apf' => '%I:%M:%S %p', 'df' => '%m/%d/%Y', 'tf' => '%H:%M:%S', 'dtf' => '%a %d %b %Y %r %Z', 'sdn' => ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], 'ldn' => ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'], 'smn' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], 'lmn' => ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'], ); set_user_locale( \%locale ); print strftime( '%c' ), "\n"; - set_timezone ( $zone )
-
Sets the timezone used by all date and time functions from here.
Parameters
$zone
The timezone identifier, like 'UTC' or 'Europe/Lisabon'. A list of identifiers can be found here: http://php.net/manual/timezones.php.
- localtime ()
- localtime ( $timestamp )
-
Converts a time as returned by the time function to a 9-element list with the time analyzed for the local time zone. Typically used as follows:
# 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); - gmtime ()
- gmtime ( $timestamp )
-
Converts a time as returned by the time function to an 9-element list with the time localized for the standard Greenwich time zone. Typically used as follows:
# 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time); - strftime ( $format )
- strftime ( $format, $timestamp )
- strftime ( $format, $timestamp, $gmt )
-
Format a local time/date according to locale or gmt settings
Parameters
$format
The following conversion specifiers are recognized in the format string:
%A is replaced by the locale's full weekday name. %a is replaced by the locale's abbreviated weekday name. %B is replaced by the locale's full month name. %b or %h is replaced by the locale's abbreviated month name. %C is replaced by the century (a year divided by 100 and truncated to an integer) as a decimal number [00,99]. %c or %+ is replaced by the locale's appropriate date and time representa- tion. %D is replaced by the date in the format ``%m/%d/%y''. %d is replaced by the day of the month as a decimal number [01,31]. %e is replaced by the day of month as a decimal number [1,31]; single digits are preceded by a blank. %F is replaced by the date in the format ``%Y-%m-%d'' (the ISO 8601 date format). %G is replaced by the ISO 8601 year with century as a decimal number. %g is replaced by the ISO 8601 year without century as a decimal num- ber (00-99). This is the year that includes the greater part of the week. (Monday as the first day of a week). See also the `%V' conversion specification. %H is replaced by the hour (24-hour clock) as a decimal number [00,23]. %I is replaced by the hour (12-hour clock) as a decimal number [01,12]. %j is replaced by the day of the year as a decimal number [001,366]. %k is replaced by the hour (24-hour clock) as a decimal number [0,23]; single digits are preceded by a blank. %l is replaced by the hour (12-hour clock) as a decimal number [1,12]; single digits are preceded by a blank. %M is replaced by the minute as a decimal number [00,59]. %m is replaced by the month as a decimal number [01,12]. %n is replaced by a newline. %o or %O is replaced by the offset from UTC in seconds. %p is replaced by the locale's equivalent of either ``AM'' or ``PM''. %P is replaced by the locale's equivalent of either ``AM'' or ``PM'' represented in lower case format. %R is replaced by the time in the format ``%H:%M''. %r is replaced by the locale's representation of 12-hour clock time using AM/PM notation. %S is replaced by the second as a decimal number [00,61]. The range of seconds is (00-61) instead of (00-59) to allow for the periodic occurrence of leap seconds and double leap seconds. %s is replaced by the number of seconds since the Epoch, UTC (see mktime(3)). %T is replaced by the time in the format ``%H:%M:%S''. %t is replaced by a tab. %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. %u is replaced by the weekday (Monday as the first day of the week) as a decimal number [1,7]. %V is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. According to ISO 8601 the week containing January 1 is week 1 if it has four or more days in the new year, otherwise it is week 53 of the previous year, and the next week is week 1. The year is given by the `%G' conversion specification. %v is replaced by the date in the format ``%e-%b-%Y''. %W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. %w is replaced by the weekday (Sunday as the first day of the week) as a decimal number [0,6]. %X is replaced by the locale's appropriate time representation. %x is replaced by the locale's appropriate date representation. %Y is replaced by the year with century as a decimal number. %y is replaced by the year without century as a decimal number [00,99]. %Z is replaced by the time zone name. %z is replaced by the offset from ITC in the ISO 8601 format ``[-]hhmm''. %% is replaced by `%'.$timestamp
The optional timestamp parameter is an integer Unix timestamp that defaults to the current time if a timestamp is not given. In other words, it defaults to the value of time().
$gmt
Optional gmt parameter indicates to use timestamp localized for the standard Greenwich time zone.
- strfmon ( $format, $value )
-
The strfmon() function converts a numeric value to monetary strings according to the specifications in the $format parameter. The function converts the double-precision floating-point value parameter under the control of the $format parameter and returns the result.
Parameters
$format
Contains characters and conversion specifications.
The application shall ensure that a conversion specification consists of the following sequence:
- A '%' character - Optional flags - Optional field width - Optional left precision - Optional right precision - A required conversion specifier character that determines the conversion to be performedFlags
One or more of the following optional flags can be specified to control the conversion:
=f An '=' followed by a single character f which is used as the numeric fill character. In order to work with precision or width counts, the fill character shall be a single byte character; if not, the behavior is undefined. The default numeric fill character is the <space>. This flag does not affect field width filling which always uses the <space>. This flag is ignored unless a left precision (see below) is specified. ^ Do not format the currency amount with grouping characters. The default is to insert the grouping characters if defined for the current locale. + or ( Specify the style of representing positive and negative currency amounts. Only one of '+' or '(' may be specified. If '+' is specified, the locale's equivalent of '+' and '-' are used (for example, in the U.S., the empty string if positive and '-' if negative). If '(' is specified, negative amounts are enclosed within parentheses. If neither flag is specified, the '+' style is used. ! Suppress the currency symbol from the output conversion. - Specify the alignment. If this flag is present the result of the conversion is left-justified (padded to the right) rather than right-justified. This flag shall be ignored unless a field width (see below) is specified.Field Width
w A decimal digit string w specifying a minimum field width in bytes in which the result of the conversion is right-justified (or left-justified if the flag '-' is specified). The default is 0.Left Precision
#n A '#' followed by a decimal digit string n specifying a maximum number of digits expected to be formatted to the left of the radix character. This option can be used to keep the formatted output from multiple calls to the strfmon() function aligned in the same columns. It can also be used to fill unused positions with a special character as in "$***123.45". This option causes an amount to be formatted as if it has the number of digits specified by n. If more than n digit positions are required, this conversion specification is ignored. Digit positions in excess of those actually required are filled with the numeric fill character (see the =f flag above). If grouping has not been suppressed with the '^' flag, and it is defined for the current locale, grouping separators are inserted before the fill characters (if any) are added. Grouping separators are not applied to fill characters even if the fill character is a digit. To ensure alignment, any characters appearing before or after the number in the formatted output such as currency or sign symbols are padded as necessary with <space>s to make their positive and negative formats an equal length.Right Precision
.p A period followed by a decimal digit string p specifying the number of digits after the radix character. If the value of the right precision p is 0, no radix character appears. If a right precision is not included, a default specified by the current locale is used. The amount being formatted is rounded to the specified number of digits prior to formatting.Conversion Specifier Characters
The conversion specifier characters and their meanings are:
i The double argument is formatted according to the locale's international currency format (for example, in the U.S.: USD 1,234.56). n The double argument is formatted according to the locale's national currency format (for example, in the U.S.: $1,234.56). % Convert to a '%' ; no argument is converted. The entire conversion specification shall be %%.$value
Specifies the double data to be converted according to the format parameter.
Return Values
Returns the converted double-precision floating-point value parameter under the control of the $format parameter.
Examples
strfmon( '%n', 123.45 );Given a locale for the U.S. and the values 123.45, -123.45, and 3456.781, the following output might be produced. Square brackets ( "[]" ) are used in this example to delimit the output.
%n [$123.45] Default formatting [-$123.45] [$3,456.78] %11n [ $123.45] Right align within an 11-character field [ -$123.45] [ $3,456.78] %#5n [ $ 123.45] Aligned columns for values up to 99999 [-$ 123.45] [ $ 3,456.78] %=*#5n [ $***123.45] Specify a fill character [-$***123.45] [ $*3,456.78] %=0#5n [ $000123.45] Fill characters do not use grouping [-$000123.45] even if the fill character is a digit [ $03,456.78] %^#5n [ $ 123.45] Disable the grouping separator [-$ 123.45] [ $ 3456.78] %^#5.0n [ $ 123] Round off to whole units [-$ 123] [ $ 3457] %^#5.4n [ $ 123.4500] Increase the precision [-$ 123.4500] [ $ 3456.7810] %(#5n [ $ 123.45 ] Use an alternative pos/neg style [($ 123.45)] [ $ 3,456.78 ] %!(#5n [ 123.45 ] Disable the currency symbol [( 123.45)] [ 3,456.78 ] %-14#5.4n [ $ 123.4500 ] Left-justify the output [-$ 123.4500 ] [ $ 3,456.7810 ] %14#5.4n [ $ 123.4500] Corresponding right-justified output [ -$ 123.4500] [ $ 3,456.7810] - number_format ( $number )
- number_format ( $number, $decimals )
- number_format ( $number, $right_prec, $dec_point )
- number_format ( $number, $right_prec, $dec_point, $thou_sep )
- number_format ( $number, $right_prec, $dec_point, $thou_sep, $neg_sign )
- number_format ( $number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign )
- number_format ( $number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign, $left_prec )
- number_format ( $number, $right_prec, $dec_point, $thou_sep, $neg_sign, $pos_sign, $left_prec, $fillchar )
-
Format a number with grouped thousands and other formatings.
Parameters
$number
The number to be formated
$right_prec
Specifying the number of digits after the radix character. Default is 0.
$dec_point
Decimal point character. The default value is used from current locale.
$thou_sep
Thousands separator (1 character). The default value is used from current locale.
$neg_sign
Sign for negative values. The default value is used from current locale.
$pos_sign
Sign for positive values. The default value is used from current locale.
$left_prec
Specifying a maximum number of digits expected to be formatted to the left of the radix character. Default is 0.
$fillchar
A single character which is used as the fill character. The default fill character is the <space>.
Return Values
Returns a formatted version of $number
Examples
$number = 1234.56; # english notation (default locale) number_format( 1234.56 ); # 1,235 # french notation number_format( $number, 2, ',', ' ' ); # 1 234,56 # financial notation number_format( $number, 2, '.', ',', '-', '+', 7, '0' ); # +00001,234.56 - round ( $val )
- round ( $val, $precision )
-
Returns the rounded value of val to specified precision (number of digits after the decimal point). Default precision is 0.
- trim ( $str )
- str_trim ( $str )
-
This function returns a string with whitespace stripped from the beginning and end of str. trim() will strip these characters:
" " (ASCII 32 (0x20)), an ordinary space. "\t" (ASCII 9 (0x09)), a tab. "\n" (ASCII 10 (0x0A)), a new line (line feed). "\r" (ASCII 13 (0x0D)), a carriage return. "\0" (ASCII 0 (0x00)), the NUL-byte. "\x0B" (ASCII 11 (0x0B)), a vertical tab.
AUTHORS
Christian Mueller <christian_at_hbr1.com>
COPYRIGHT
The PAB3::Utils module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.