String::Util version 1.01
=========================

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

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

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

  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 &nbsp;.

  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.

  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.

  randcrypt(string)
    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 twonelines 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}

TERMS AND CONDITIONS
    Copyright (c) 2010 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
        http://www.xray.mpe.mpg.de/mailing-lists/modules/2005-12/msg00112.ht
        ml for why these changes were made.

    Version 1.01 November 7, 2010
        Decided it was time to upload five years worth of changes.

