String::Util

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";
 }