NAME
String::Util -- 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 a web page
$val = htmlesc($val);
# format for display in a web page table cell
$val = cellfill($val);
# remove leading/trailing whitespace
$val = trim($val);
# ensure defined value
$val = define($val);
# repeat string x number of times
$val = repeat($val, $iterations);
# remove leading/trailing quotes
$val = unquote($val);
# remove all whitespace
$val = no_space($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 (eqq $a, $b) {...}
# are these two values different, where two undefs count as "equal"?
if (neqq $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
FUNCTIONS
collapse(string), crunch(string)
collapse() collapses all whitespace in the string down to single
spaces. Also removes all leading and trailing whitespace. Undefined
input results in undefined output.
crunch() is the old name for collapse(). I decided that "crunch" never
sounded right. Spaces don't go "crunch", they go "poof" like a
collapsing ballon. However, crunch() will continue to work as an alias
for collapse().
hascontent(scalar), nocontent(scalar)
hascontent() returns true if the given argument is defined and 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 characters (including zero) returns true.
nocontent() returns the negation of hascontent().
trim(string)
Returns the string with all leading and trailing whitespace removed.
Trim on undef returns undef.
So, for example, the following code changes " my string " to "my
string":
$var = " my string ";
$var = trim($var);
trim accepts two optional arguments, 'left' and 'right', both of which
are true by default. So, to avoid trimming the left side of the string,
set the 'left' argument to false:
$var = trim($var, left=>0);
To avoid trimming the right side, set 'right' to false:
$var = trim($var, right=>0);
ltrim, rtrim
ltrim trims leading whitespace. rtrim trims trailing whitespace. They
are exactly equivalent to
trim($var, left=>0);
and
trim($var, right=>0);
no_space(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. However, there are a
few differences. htmlesc() changes an undefined value to an empty
string, whereas escapeHTML() returns undefs as undefs.
cellfill(string)
Formats a string for literal output in an HTML table cell. Works just
like htmlesc() except that strings with no content (i.e. are undef or
are just whitespace) are returned as .
jsquote($string)
Escapes and quotes a string for use in JavaScript. Escapes single
quotes and surrounds the string in single quotes. Returns the modified
string.
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. Some examples and what they return:
unquote(q|'Hendrix'|); # Hendrix
unquote(q|"Hendrix"|); # Hendrix
unquote(q|Hendrix|); # Hendrix
unquote(q|"Hendrix'|); # "Hendrix'
unquote(q|O'Sullivan|); # O'Sullivan
option: braces
If the braces option is true, surrounding braces such as [] and {} are
also removed. Some examples:
unquote(q|[Janis]|, braces=>1); # Janis
unquote(q|{Janis}|, braces=>1); # Janis
unquote(q|(Janis)|, braces=>1); # Janis
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. Perl already treats undefs as empty
strings in string context, but this subroutine makes the warnings
module <
http://perldoc.perl.org/warnings.html> go away. And you ARE
using warnings, right?
repeat($string, $count)
Returns the given string repeated the given number of times. The
following command outputs "Fred" three times:
print repeat('Fred', 3), "\n";
Note that repeat() was created a long time based on a misunderstanding
of how the perl operator 'x' works. The following command using 'x'
would perform exactly the same as the above command.
print 'Fred' x 3, "\n";
Use whichever you prefer.
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. So this code:
foreach my $idx (1..3) {
print randword(4), "\n";
}
would output something like this:
kBGV
NCWB
3tHJ
If the string 'dictionary' is sent instead of an integer, then a word
is randomly selected from a dictionary file. By default, the dictionary
file is assumed to be at /usr/share/dict/words and the shuf command is
used to pull out a word. The hash %String::Util::PATHS sets the paths
to the dictionary file and the shuf executable. Modify that hash to
change the paths. So this code:
foreach my $idx (1..3) {
print randword('dictionary'), "\n";
}
would output something like this:
mustache
fronds
browning
option: alpha
If the alpha option is true, only alphabetic characters are returned,
no numerals. For example, this code:
foreach my $idx (1..3) {
print randword(4, alpha=>1), "\n";
}
would output something like this:
qrML
wmWf
QGvF
option: numerals
If the numerals option is true, only numerals are returned, no
alphabetic characters. So this code:
foreach my $idx (1..3) {
print randword(4, numerals=>1), "\n";
}
would output something like this:
3981
4734
2657
option: strip_vowels
This option is true by default. If true, vowels are not included in the
returned random string. So this code:
foreach my $idx (1..3) {
print randword(4, strip_vowels=>1), "\n";
}
would output something like this:
Sk3v
pV5z
XhSX
eqq($val1, $val2)
Returns true if the two given values are equal. Also returns true if
both are undef. If only one is undef, or if they are both defined but
different, returns false. Here are some examples and what they return.
eqq('x', 'x'), "\n"; # 1
eqq('x', undef), "\n"; # 0
eqq(undef, undef), "\n"; # 1
neqq($str1, $str2)
The opposite of neqq, returns true if the two values are *not* the
same. Here are some examples and what they return.
print neqq('x', 'x'), "\n"; # 0
print neqq('x', undef), "\n"; # 1
print neqq(undef, undef), "\n"; # 0
equndef(), neundef()
equndef() has been renamed to eqq(). neundef() has been renamed to
neqq(). Those old names have been kept as aliases.
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.
randpost(%opts)
Returns a string that sorta looks like one or more paragraphs.
option: word_count
Sets how many words should be in the post. By default a random number
from 1 to 250 is used.
option: par_odds
Sets the odds of starting a new paragraph after any given word. By
default the value is .05, which means paragraphs will have an average
about twenty words.
option: par
Sets the string to put at the end or the start and end of a paragraph.
Defaults to two newlines for the end of a pargraph.
If this option is a single scalar, that string is added to the end of
each paragraph.
To set both the start and end string, use an array reference. The first
element should be the string to put at the start of a paragraph, the
second should be the string to put at the end of a paragraph.
option: max_length
Sets the maximum length of the returned string, including paragraph
delimiters.
ords($string)
Returns the given string represented as the ascii value of each
character.
For example, this code:
ords('Hendrix')
returns this string:
{72}{101}{110}{100}{114}{105}{120}
options
* convert_spaces=>[true|false]
If convert_spaces is true (which is the default) then spaces are
converted to their matching ord values. So, for example, this code:
ords('a b', convert_spaces=>1)
returns this:
{97}{32}{98}
This code returns the same thing:
ords('a b')
If convert_spaces is false, then spaces are just returned as spaces.
So this code:
ords('a b', convert_spaces=>0);
returns
{97} {98}
* alpha_nums
If the alpha_nums option is false, then characters 0-9, a-z, and A-Z
are not converted. For example, this code:
ords('a=b', alpha_nums=>0)
returns this:
a{61}b
deords($string)
Takes the output from ords() and returns the string that original
created that output.
For example, this command:
deords('{72}{101}{110}{100}{114}{105}{120}')
returns this string: Hendrix
crunchlines($str)
Compacts contiguous newlines into single newlines. Whitespace between
newlines is ignored, so that two newlines separated by whitespace is
compacted down to a single newline.
For example, this code:
crunchlines("x\n\n\nx")
outputs two x's with a single empty line between them:
x
x
spacepad
TERMS AND CONDITIONS
Copyright (c) 2012-2016 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
[email protected]
HISTORY
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
to modify values in place were changed so that they do not do so
anymore, except for fullchomp.
See
http://www.xray.mpe.mpg.de/mailing-lists/modules/2005-12/msg00112.htm
l for why these changes were made.
Version 1.01, November 7, 2010
Decided it was time to upload five years worth of changes.
Version 1.20, July, 2012
Properly listing prerequisites.
Version 1.21, July 18, 2012
Fixed error in POD.
Version 1.22, July 20, 2012
Fix in documentation for randpost().
Clarified documentation for hascontent() and nocontent().
Version 1.23, Sep 1, 2012
Fixed error in META.yml.
Version 1.24, December 31, 2014
Cleaned up POD formatting.
Changed file to using Unixish style newlines. I hadn't realized until
now that it was using Windowish newline. How embarrasing.
Added some features to ords().
Version 1.25, January 4, 2015
Added parentheses to braces option for unquote. Cleaned up and added
to POD. Minor fixes to comments.
Renamed equndef to eqq, and neundef to neqq. However, the old names
have been kept as aliases.
Minor cleanup of formatting.
Version 1.26, Aug 29, 2016
Fixed tests. No significant changes to module.
