NAME

Pitonyak::StringUtil - General string utilities.

String module created by Andrew Pitonyak for his personal use to format strings for pretty output.

SYNOPSIS

The subroutines in this module are intended to be used as methods, not as calls on an object. Therefore, you should call all methods directly.

Many of the subroutines modify the arguments. For example, when you trim space from a string, the argument is modified.

Methods are not available unless they are specifically imported. So, to use the smart_printer_default routine, you must first import it. For example,

DESCRIPTION

array_width

Return the length of the longest string in an array.

Arguments are not modified.

array_width([arg1], [arg2], ... [argn])

Each argument or array element should be a scalar or a reference to an array. The primary usage is to print a group of strings in a fixed width field. For example:

use Pitonyak::StringUtil qw(array_width right_fmt); my @strings = ('one', 'two', 'three', 'four'); foreach (right_fmt(array_width(@strings), @strings)) {   print "$_\n"; }

produces:

one   two three  four

center_fmt

Modify the arguments to be strings centered in the specified width. A string that is longer than the specified width is truncated.

In array context, return the entire array.

In scalar context, return only the first string.

center_fmt($width_to_use, @strings_to_format)

Modify the arguments to be strings centered in the specified width.

• Modify the arguments to be strings centered in C<< $width_to_use >>.
• The strings are left and right padded to use the entire width.
• The strings are truncated to fit into the space if they are too long.

use Pitonyak::StringUtil qw(center_fmt); my $long_str = 'I am really long'; my @strings = ('one', 'two', 'three', 'four'); foreach (center_fmt(8, @strings, $long_str)) {   print "$_\n"; }

produces:

one   two  three   four I am rea

compact_space

Modify each argument to change runs of white space to a single space.

compact_space(@list_of_strings)

Modify each argument to change runs of white space to a single space.

• Arguments are modified.
• Continuous spaces are changed to a singel space.
• Leading and trailing spaces are removed.



use Pitonyak::StringUtil qw(compact_space); my $test_str = ' one two '; compact_space($test_str); print "($test_str)\n";

delimited_values

delimited_values($delimiter, @values)

For each string in @values, split it based on the delimiter. White space is trimmed from the front and rear. An array of values is returned.

delimited_values(',', '1, 2, 3, 4');

substr_no_space

substr_no_space($line, $start, $len)

Extract text from $line starting at at the zero based location $start, with length $len.

Leading and trailing spaces are removed.

Bounds are checked to avoid errors.

hash_key_width

hash_key_width($hash_reference)

Determine the maximum width of the keys in a hash reference. Usually used to right justify hash keys. For example:

use Pitonyak::StringUtil qw(hash_key_width right_fmt); my %map = ('one'=>1, 'two'=> 2, 'three'=>3, 'four'=>4); my $width = hash_key_width(%map); while ( my ($key, $value) = each(%map) ) {   print right_fmt($width, $key)." => $value\n"; }

produces

three => 3   one => 1   two => 2  four => 4

The function is defined as sub hash_key_width(\%), so Perl automatically uses a hash reference for the call; in the example above, %map is used rather than \%map.

hash_val_width

hash_val_width($hash_reference)

Determine the maximum width of the values in a hash. The usage is the same as hash_key_width.

left_fmt

Modify the arguments by appending space to force them to be the specified length.

left_fmt($width_to_use, @strings_to_format)

Modify the arguments by appending space to force them to be the specified length.

• Arguments are modified.
• Append spaces so that each argument is the requested width.
• Do not truncate arguments even if they are too long.

use Pitonyak::StringUtil qw(hash_key_width left_fmt); my %map = ('one'=>1, 'two'=> 2, 'three'=>3, 'four'=>4); my $width = hash_key_width(%map); while ( my ($key, $value) = each(%map) ) {   print left_fmt($width, $key)." => $value\n"; }

produces

three => 3 one   => 1 two   => 2 four  => 4

num_int_digits

num_int_digits($integer_number)

Return the number of digits in this integer. This method fails if the number is not an integer. For example, consider the following example:

produces

Make special note of the results for numbers with decimals, and especially for numbers that are very large in magnitude (as in much larger than an integer).

num_with_leading_zeros

Format numbers to contain leading zeros.

num_with_leading_zeros(($width_to_use, @numbers_to_format)

Return N-digit strings representing the number with leading zeros.

• Arguments are NOT modified.
• Negative signs are not returned unless the width is negative.
• Prepend the number with leading zeros to force the string to the specified length.
• Numbers are printed as integers, and realy large numbers are a problem (see example).

use Pitonyak::StringUtil qw(num_with_leading_zeros); my @numbers = (7, '00554', '+32', '-677', '123.456', 3.1415, 1.9e23); foreach my $num (@numbers) {   print num_with_leading_zeros(-5, $num)." <= $num\n"; }

produces

00007 <= 7 00554 <= 00554 00032 <= +32 -0677 <= -677 00123 <= 123.456 00003 <= 3.1415 -0001 <= 1.9e+023

trans_blank

trans_blank($value)

Return $value if it is defined, and an empty string if it is not. The trans_blank method is roughly equivalent to:

return defined($value) ? $value : '';

The primary purpose is to avoid warnings such as "Use of uninitialized value in concatenation (.) or string at...".

use Pitonyak::StringUtil qw(trans_blank); my $x; my $y = '7'; print "($x)\n";                  #Casues a warning message. print '('.trans_blank($x).")\n"; #No warning message. print '('.trans_blank($y).")\n"; #No warning message.

trans_blank($value, $default)

Returns $value if it is defined with length greater than zero and $default if it is not. In other words, a string of length zero is treated the same as an undefined value. A typical value for $default is the empty string, which means trans_blank is rarely called with two arguments.

Return $value if it is defined, and $default if it is not. The trans_blank method is roughly equivalent to:

return defined($value) ? $value : $default;

The primary purpose is to avoid warnings such as "Use of uninitialized value in concatenation (.) or string at...".

use Pitonyak::StringUtil qw(trans_blank); my $x; my $y = '7'; print '('.trans_blank($x, '<empty>').")\n"; # Print (<empty>) print '('.trans_blank($y, '<empty>').")\n"; # Print (7)

trim_fmt

trim_fmt($width_to_use, @strings_to_format)

Trim all strings so that their length is not greater than $width_to_use. Strings that are too long are truncated. The string arguments are modified.

use Pitonyak::StringUtil qw(trim_fmt); my @strings = ('123456789', '123'); trim_fmt(5, @strings); print '('.join('), (', @strings).")\n";

produces

(12345), (123)

trim_space

trim_space(@strings_to_format)

Remove leading and trailing white space. The parameters are modified.

right_fmt

Modify the arguments by prepending space to force them to be the specified length.

right_fmt($width_to_use, @strings_to_format)

Modify the arguments by prepending space to force them to be the specified length.

• Arguments are modified.
• Prepend spaces so that each argument is the requested width.
• Do not truncate arguments even if they are too long.

use Pitonyak::StringUtil qw(hash_key_width right_fmt); my %map = ('one'=>1, 'two'=> 2, 'three'=>3, 'four'=>4); my $width = hash_key_width(%map); while ( my ($key, $value) = each(%map) ) {   print right_fmt($width, $key)." => $value\n"; }

produces

three => 3   one => 1   two => 2  four => 4

smart_printer

smart_printer($left, $left_grow, $separator, @Things_to_print)

Print the argument in a pleasing way depending on the type. The arguments are not modified. The first three arguments direct how items are printed.

1. Left margin when an item is printed.
2. How to grow the left indent for recursive printing.
3. Separator used for items.

An item is printed based on its type.

• Left margin when an item is printed.
• How to grow the left indent for recursive printing.
• Separator used for items.
• A scalars is printed directly.
• A Hash is printed as { key => value ... }. Each key value pair is separated by the item separator (usually a new line).
• An Array is printed as ( value ... ). Each value is separated by the item separator (usually a new line).
• Keys and values can also be references.

See smart_printer_default to see a typical example.

smart_printer_default

smart_printer_default(Things to print)

Simple wrapper to call smart_printer.

• Items are printed with no initial left indent.
• Recursive indents using two extra spaces.
• A new line is the item separator.

use Pitonyak::StringUtil qw(smart_printer_default); my %hash2 = ('a' => 'A', 'b' => 'B'); my @strings = ('123456789', '123', \%hash2); my %hash1 = ('one' => 1, 'two' => 2, 'ary' => \@strings); print smart_printer_default(\%hash1); }

produces

{   one => 1   two => 2   ary =>     (       123456789       123       {         a => A         b => B       }     ) }

COPYRIGHT

Copyright 1998-2008, Andrew Pitonyak (andrew@pitonyak.org)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Modification History

March 13, 1998

Version 1.00 First release

September 10, 2002

Version 1.01 Changed internal documentation to POD

January 24, 2007

Version 1.02 Updated POD and package name for use in CEFM project. Fixed a bug where each negative number caused the width to become smaller for the next iteration if multiple numbers were passed at the same time.

September 16, 2008

Version 1.03 Updated POD for minor corrections.