FreeBSD Manual Pages

home | help
String::Util(3)	      User Contributed Perl Documentation      String::Util(3)

NAME
       String::Util -- String processing utility functions

DESCRIPTION
       String::Util provides a collection of small, handy functions for
       processing strings in various ways.

INSTALLATION
	 cpanm String::Util

USAGE
       No functions are	exported by default, they must be specified:

	 use String::Util qw(trim eqq contains)

       alternately you can use ":all" to export	all of the functions

	 use String::Util qw(:all)

FUNCTIONS
   collapse($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.

       Note: "crunch()"	is an alias to this function. It is considered
       deprecated.  It may be removed in future	versions.

	 $var =	collapse("  Hello     world!	"); # "Hello world!"

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

	 $var =	hascontent("");	 # False
	 $var =	hascontent(" "); # False
	 $var =	hascontent("a"); # True

	 $var =	nocontent("");	 # True
	 $var =	nocontent("a");	 # False

   trim($string), ltrim($string), rtrim($string)
       Returns the string with all leading and trailing	whitespace removed.
       Trim on undef returns "".

	 $var =	trim(" my string  "); #	"my string"

       ltrim() trims leading whitespace	only.

       rtrim() trims trailing whitespace only.

   nospace($string)
       Removes all whitespace characters from the given	string.	This includes
       spaces between words.

	 $var =	nospace("  Hello World!	  "); #	"HelloWorld!"

   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.

   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

   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($scalar1, $scalar2)
       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.

	 $var =	eqq('x', 'x'), "\n";	  # True
	 $var =	eqq('x', undef), "\n";	  # False
	 $var =	eqq(undef, undef), "\n";  # True

       Note: equndef() is an alias to this function. It	is considered
       deprecated.  It may be removed in future	versions.

   neqq($scalar1, $scalar2)
       The opposite of neqq, returns true if the two values are	*not* the
       same.  Here are some examples and what they return.

	 $var =	neqq('x', 'x'),	"\n";	   # False
	 $var =	neqq('x', undef), "\n";	   # True
	 $var =	neqq(undef, undef), "\n";  # False

       Note: neundef() is an alias to this function. It	is considered
       deprecated.  It may be removed in future	versions.

   ords($string)
       Returns the given string	represented as the ascii value of each
       character.

	 $var =	ords('Hendrix'); # {72}{101}{110}{100}{114}{105}{120}

       options

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

	     $var = ords('a b',	convert_spaces=>1); # {97}{32}{98}

	   This	code returns the same thing:

	     $var = ords('a b');		    # {97}{32}{98}

	   If convert_spaces is	false, then spaces are just returned as
	   spaces. So this code:

	     ords('a b', convert_spaces=>0);	    # {97} {98}

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

	     $var = ords('a=b',	alpha_nums=>0);	# a{61}b

   deords($string)
       Takes the output	from ords() and	returns	the string that	original
       created that output.

	 $var =	deords('{72}{101}{110}{100}{114}{105}{120}'); #	'Hendrix'

   contains($string, $substring)
       Checks if the string contains substring

	 $var =	contains("Hello	world",	"Hello");   # true
	 $var =	contains("Hello	world",	"llo wor"); # true
	 $var =	contains("Hello	world",	"QQQ");	    # false

   startswith($string, $substring)
       Checks if the string starts with	the characters in substring

	 $var =	startwidth("Hello world", "Hello"); # true
	 $var =	startwidth("Hello world", "H");	    # true
	 $var =	startwidth("Hello world", "Q");	    # false

   sanitize($string)
       Sanitize	all non	alpha-numeric characters in a string to	underscores.
       This is useful to take a	URL, or	filename, or text description and know
       you can use it safely in	a URL or a filename.

       Note: This will remove any trailing or leading '_' on the string

	 $var =	sanitize("http://www.google.com/") # http_www_google_com
	 $var =	sanitize("foo_bar()";		   # foo_bar
	 $var =	sanitize("/path/to/file.txt");	   # path_to_file_txt

   endswith($string, $substring)
       Checks if the string ends with the characters in	substring

	 $var =	endswidth("Hello world", "world");   # true
	 $var =	endswidth("Hello world", "d");	     # true
	 $var =	endswidth("Hello world", "QQQ");     # false

   crunchlines($string)
       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.

	 $var =	crunchlines("x\n\n\nx"); # "x\nx";

   file_get_contents($string, $boolean)
       Read an entire file from	disk into a string. Returns undef if the file
       cannot be read for any reason. Can also return the file as an array of
       lines.

	 $str	= file_get_contents("/tmp/file.txt");	 # Return a string
	 @lines	= file_get_contents("/tmp/file.txt", 1); # Return an array

COPYRIGHT AND LICENSE
       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 <miko@idocs.com>

       Scott Baker <scott@perturb.org>

perl v5.32.1			  2020-07-27		       String::Util(3)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=String::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>
home | help
Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages
