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 (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

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), 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 characers (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. 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.

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 returns 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.

   option: braces

   If the braces option is true, surrounding braces such as [] and {} are
   also removed.

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?

repeat($string, $count)

   Returns the given string repeated the given number of times.

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.

   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.

   option: alpha

   If the alpha option is true, only alphabetic characters are returned,
   no numerals.

   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.

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

TERMS AND CONDITIONS

   Copyright (c) 2012 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]

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
     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. Tightened up code for repet.

   Version 1.22

     Fix in documentation for randpost().

     Clarified documentation for hascontent() and nocontent().

   Version 1.23

     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().

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.