The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PTools-0.01
/ PTools::String

NAME

PTools::String - Misc string functions not explicitly provided in Perl

VERSION

This document describes version 0.16, released December, 2005.

SYNOPSIS

use PTools::String;

$strObj = new PTools::String;

$result = $strObj->addCommasToNumber( $bigNumber );

$result = $strObj->centerInBuffer( $string, $bufferLength );

$result = $strObj->justifyRight( $string, $bufferLength );

$result = $strObj->justifyListRight( $arrayRef [,"commaFlag"] [,$bufferLength]);

$result = $strObj->initialCaps( $string );

$result = $strObj->stripExtraWhiteSpace( $string );

$result = $strObj->stripLeftWhiteSpace( $string );

$result = $strObj->stripRightWhiteSpace( $string );

$result = $strObj->zero( $value );

$result = $strObj->plural( $counter, $word, $pluralSuffix, $singularSuffix );

$result = $strObj->prompt( $prompt, $editMatch, $errMsg, $default, @exitStr );

$result = $strObj->untaint( $taintedText, $untaintPattern );

DESCRIPTION

This class provides some miscellaneous string functions not explicitly provided in Perl.

Constructor

new

Instantiate a new object of this class. This is not necessary as all methods in this class work identically as class or object methods.

use PTools::String;

$result = PTools::String->initialCaps( $textString );        # class method

$strObj = new PTools::String;
$result = $strObj->initialCaps( $textString );       # object method

Methods

addCommasToNumber ( BigNumber [, ForceDecimal ] )

Create syntactically correct numbers by inserting commas. This method works with both integers and floating point values, and also adds commas to numbers within character strings.

$result = $strObj->addCommasToNumber( 1234567890 );

$result = $strObj->addCommasToNumber( "Up by 4567.89%" );

To force the result to be returned as a decimal number, even when the BigNumber is an integer, pass any non-null value as the ForceDecimal parameter.

$result = $strObj->addCommasToNumber( 1234567890, "Decimal" );
centerInBuffer ( String, BufferLength )

Center String in a new string of BufferLength.

$result = $strObj->centerInBuffer( "Some text", 40 );
justifyRight ( String, BufferLength )

Right justify String in a new string of BufferLength.

$result = $strObj->justifyRight( "Some text", 40 );
justifyListRight ( ArrayRef [, AddCommasFlag ] [, BufferLength ] )

Right justify a list of strings contained in ArrayRef.

If any non-null value is passed in the AddCommasFlag parameter, commas will be added, when appropriate, to any numbers found in strings within the list. See the addCommasToString method, above, for details on adding commas to numbers.

If no BufferLength is provided, the length of the longest string contained in the ArrayRef is used. When adding commas, the length is calculated after commas, if any, are inserted.

$arrayRef = ["10752734", "2512.05%", "72230 bytes used", "32767")];

$strObj->justifyRight( $arrayRef );

Note that the contents of the $arrayRef is modified in this operation.

initialCaps ( String )

Shift the first letter of each word in String to upper case.

$result = $strObj->initialCaps( "bob m. smith, jr." );
stripExtraWhiteSpace ( String )

Remove leading and trailing white space from String.

$result = $strObj->stripExtraWhiteSpace( "  Some text  " );
stripLeftWhiteSpace ( String )

Remove leading white space from String.

$result = $strObj->stripLeftWhiteSpace( "  Some text  " );
stripRightWhiteSpace ( String )

Remove trailing white space from String.

$result = $strObj->stripRightWhiteSpace( "  Some text  " );
zero ( Value [, DefaultWhenUndef ] )

Since ("0" eq "") in Perl, and we so often need to code around this fact, we can handle this once and for all with the zero method.

Many Perl programmers eventually become familiar with following syntax.

$value = $someStringValue ||"";
$value = $maybeZeroValue  ||"0";

However, the above is often a bit too simplistic. Now we can get return values of "$value" OR "" OR "0" OR "undef".

$value = $self->zeroString( $maybeZeroValue );

And we can also determine a new default for "undef" strings.

$value = $self->zeroString( $maybeUndefValue, "0" );
plural ( Counter, Word, PluralSuffix [, SingularSuffix ] )

Create syntactically correct results, given an arbitrary counter value.

$descrepencies = $strObj->plural( $error, "Descrepenc","ies","y" );
$warnings      = $strObj->plural( $warn,  "Warning","s" );

print "  Found $error $descrepencies\n";
print "  Found $warn $warnings\n";
prompt ( Prompt, [ EditMatch [, ErrMsg ]] [, Default ] [, ExitStrList ] )

Write Prompt text on STDOUT and read a line of input from STDIN. This method handles Ctrl-D and <null> input.

Optionally this method can perform text matching edits on the input.

Prompt

A text string used to prompt the user for input. This is displayed on STDOUT.

EditMatch

A Perl match test used to edit the user's input. If match fails, user is re-prompted for input.

ErrMsg

A text string used as a "hint" displayed if the EditMatch fails.

Default

A text string used as a default value if the user enters nothing.

ExitStrList

A list of zero or more strings that, when entered by the user, will terminate prompts for data entry. Defaults are // and /. The actual ExitString entered by the user is returned as the result to the calling module.

Examples:

$strUtil= "PTools::String";
$uname  = $strUtil->prompt("  User name: ", "^([a-z])\\w{0,7}\$"     );
$empno  = $strUtil->prompt(" Emp Number: ", "^(\\d{1,8}|N\\d{1,7})\$");
$telnet = $strUtil->prompt(" Emp Telnet: ", "^(|\\d{3}-\\d{4})\$"    );
$email  = $strUtil->prompt("     E-Mail: ", ""                       );
$uid    = $strUtil->prompt("     UserID: ", "^\\d{1,5}\$"            );
$gid    = $strUtil->prompt("    GroupID: ", "^\\d{1,5}\$"            );

Notice that "" will pass edit for both 'telnet' and 'email' variables. However, if a value IS entered for 'telnet' it must match the pattern.

isTainted ( String )

Test a string variable for 'taintedness.'

String

A string variable.

Example:

if ( PTools::String->isTainted( $text ) ) { ... }
detaint ( TaintedString [, AllowedChars ] )
untaint ( TaintedString [, AllowedChars ] )

Untaint a text string.

TaintedString

A string containing 'tainted' text.

AllowedChars

An optional string of chars used to 'untaint' the TaintedString string. This string defaults to the '- a-zA-Z0-9_.@' characters. This string can not contain '.*' and, if these characters are found, the default string is used instead.

Any character in the TaintedString not found in the AllowedChars is converted into the underscore ('_') character.

Example:

$text = String->untaint( $text );

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 2002-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.