NAME
String::Util -- Handy string processing utilities
SYNOPSIS
use String::Util ':all';
# "crunch" whitespace and remove leading/trailing whitespace
$val = crunch($val);
# does this value have "content", i.e. it's defined
# and has something besides whitespace?
if (hascontent $val) {...}
# format for display in web page
$val = htmlesc($val);
# remove leading/trailing whitespace
$val = trim($val);
# ensure defined value
$val = define($val);
# remove leading/trailing quotes
$val = unquote($val);
# remove all whitespace
$val = nospace($val);
# remove trailing \r and \n, regardless of what
# the OS considers an end-of-line
$val = fullchomp($val);
# or call in void context:
fullchomp $val;
# encrypt string using random seed
$val = randcrypt($val);
# are these two values equal, where two undefs count as "equal"?
if (equndef $a, $b) {...}
# are these two values different, where two undefs count as "equal"?
if (neundef $a, $b) {...}
# get a random string of some specified length
$val = randword(10);
DESCRIPTION
String::Util provides a collection of small, handy utilities for
processing strings.
INSTALLATION
String::Util can be installed with the usual routine:
perl Makefile.PL
make
make test
make install
You can also just copy Util.pm into the String/ directory of one of your
library trees.
FUNCTIONS
crunch(string)
Crunches all whitespace in the string down to single spaces. Also
removes all leading and trailing whitespace. Undefined input results in
undefined output.
hascontent(scalar)
Returns true if the given argument contains something besides
whitespace.
This function tests if the given value is defined and, if it is, if that
defined value contains something besides whitespace.
An undefined value returns false. An empty string returns false. A value
containing nothing but whitespace (spaces, tabs, carriage returns,
newlines, backspace) returns false. A string containing any other
characers (including zero) returns true.
trim(string)
Returns the string with all leading and trailing whitespace removed.
Trim on undef returns undef.
nospace(string)
Removes all whitespace characters from the given string.
htmlesc(string)
Formats a string for literal output in HTML. An undefined value is
returned as an empty string.
htmlesc is very similar to CGI.pm's escapeHTML. If your script already
loads CGI.pm, you may well not need htmlesc. However, there are a few
differences. htmlesc changes an undefined value to an empty string,
whereas escapeHTML returns undefs as undefs and also results in a
warning. Also, escapeHTML will not modify a value in place: you always
have to store the return value, even in you're putting it back in to the
variable the value came from. It's a matter of taste.
unquote(string)
If the given string starts and ends with quotes, removes them.
Recognizes single quotes and double quotes. The value must begin and end
with same type of quotes or nothing is done to the value. Undef input
results in undef output.
define(scalar)
Takes a single value as input. If the value is defined, it is returned
unchanged. If it is not defined, an empty string is returned.
This subroutine is useful for printing when an undef should simply be
represented as an empty string. Granted, Perl already treats undefs as
empty strings in string context, but this sub makes -w happy. And you
ARE using -w, right?
randword(length, %options)
Returns a random string of characters. String will not contain any
vowels (to avoid distracting dirty words). First argument is the length
of the return string.
option: numerals
If the numerals option is true, only numerals are returned, no
alphabetic characters.
option: strip_vowels
This option is true by default. If true, vowels are not included in the
returned random string.
equndef($str1, $str2)
Returns true if the two given strings are equal. Also returns true if
both are undef. If only one is undef, or if they are both defined but
different, returns false.
neundef($str1, $str2)
The opposite of equndef, returns true if the two strings are *not* the
same.
fullchomp(string)
Works like chomp, but is a little more thorough about removing \n's and
\r's even if they aren't part of the OS's standard end-of-line.
Undefs are returned as undefs.
randcrypt(string)
Crypts the given string, seeding the encryption with a random two
character seed.
TERMS AND CONDITIONS
Copyright (c) 2005 by Miko O'Sullivan. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. This software comes with NO WARRANTY of any
kind.
AUTHORS
Miko O'Sullivan miko@idocs.com
VERSION
Version 0.10 December 1, 2005
Initial release
Version 0.11 December 22, 2005
This is a non-backwards compatible version.
urldecode, urlencode were removed entirely. All of the subs that
used used to modify values in place were changed so that they do not
do so anymore, except for fullchomp.
See
ml for why these changes were made.