Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       String::Util -- String processing utility functions

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

	 cpanm String::Util

       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)

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

       Removes all whitespace characters from the given	string.	This includes
       spaces between words.

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

       Formats a string	for literal output in HTML.  An	undefined value	is
       returned	as an empty string.

       htmlesc() is very similar to's escapeHTML.  However, there are a
       few differences.	htmlesc() changes an undefined value to	an empty
       string, whereas escapeHTML() returns undefs as undefs.

       Escapes and quotes a string for use in JavaScript.  Escapes single
       quotes and surrounds the	string in single quotes.  Returns the modified

       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:


       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:


       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:


       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:


       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:


   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.

       Returns the given string	represented as the ascii value of each

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


       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

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

       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

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

       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.

       Miko O'Sullivan <>

       Scott Baker <>

perl v5.32.1			  2020-07-27		       String::Util(3)


Want to link to this manual page? Use this URL:

home | help