1String::Util(3pm) User Contributed Perl Documentation String::Util(3pm)
2
6 String::Util -- String processing utility functions
7
9 String::Util provides a collection of small, handy functions for
10 processing strings in various ways.
11
13 cpanm String::Util
14
16 No functions are exported by default, they must be specified:
17 use String::Util qw(trim eqq contains)
19 alternately you can use ":all" to export all of the functions
21 use String::Util qw(:all)
23
25 collapse($string)
26 "collapse()" collapses all whitespace in the string down to single
27 spaces. Also removes all leading and trailing whitespace. Undefined
28 input results in undefined output.
29 Note: "crunch()" is an alias to this function. It is considered
31 deprecated. It may be removed in future versions.
32 $var = collapse(" Hello world! "); # "Hello world!"
34 hascontent($scalar), nocontent($scalar)
36 hascontent() returns true if the given argument is defined and contains
37 something besides whitespace.
38 An undefined value returns false. An empty string returns false. A
40 value containing nothing but whitespace (spaces, tabs, carriage
41 returns, newlines, backspace) returns false. A string containing any
42 other characters (including zero) returns true.
43 "nocontent()" returns the negation of "hascontent()".
45 $var = hascontent(""); # False
47 $var = hascontent(" "); # False
48 $var = hascontent("a"); # True
49 $var = nocontent(""); # True
51 $var = nocontent("a"); # False
52 trim($string), ltrim($string), rtrim($string)
54 Returns the string with all leading and trailing whitespace removed.
55 Trim on undef returns "".
56 $var = trim(" my string "); # "my string"
58 ltrim() trims leading whitespace only.
60 rtrim() trims trailing whitespace only.
62 nospace($string)
64 Removes all whitespace characters from the given string. This includes
65 spaces between words.
66 $var = nospace(" Hello World! "); # "HelloWorld!"
68 htmlesc($string)
70 Formats a string for literal output in HTML. An undefined value is
71 returned as an empty string.
72 htmlesc() is very similar to CGI.pm's escapeHTML. However, there are a
74 few differences. htmlesc() changes an undefined value to an empty
75 string, whereas escapeHTML() returns undefs as undefs.
76 jsquote($string)
78 Escapes and quotes a string for use in JavaScript. Escapes single
79 quotes and surrounds the string in single quotes. Returns the modified
80 string.
81 unquote($string)
83 If the given string starts and ends with quotes, removes them.
84 Recognizes single quotes and double quotes. The value must begin and
85 end with same type of quotes or nothing is done to the value. Undef
86 input results in undef output. Some examples and what they return:
87 unquote(q|'Hendrix'|); # Hendrix
89 unquote(q|"Hendrix"|); # Hendrix
90 unquote(q|Hendrix|); # Hendrix
91 unquote(q|"Hendrix'|); # "Hendrix'
92 unquote(q|O'Sullivan|); # O'Sullivan
93 option: braces
95 If the braces option is true, surrounding braces such as [] and {} are
97 also removed. Some examples:
98 unquote(q|[Janis]|, braces=>1); # Janis
100 unquote(q|{Janis}|, braces=>1); # Janis
101 unquote(q|(Janis)|, braces=>1); # Janis
102 repeat($string, $count)
104 Returns the given string repeated the given number of times. The
105 following command outputs "Fred" three times:
106 print repeat('Fred', 3), "\n";
108 Note that repeat() was created a long time based on a misunderstanding
110 of how the perl operator 'x' works. The following command using 'x'
111 would perform exactly the same as the above command.
112 print 'Fred' x 3, "\n";
114 Use whichever you prefer.
116 randword($length, %options)
118 Returns a random string of characters. String will not contain any
119 vowels (to avoid distracting dirty words). First argument is the length
120 of the return string. So this code:
121 foreach my $idx (1..3) {
123 print randword(4), "\n";
124 }
125 would output something like this:
127 kBGV
129 NCWB
130 3tHJ
131 If the string 'dictionary' is sent instead of an integer, then a word
133 is randomly selected from a dictionary file. By default, the
134 dictionary file is assumed to be at /usr/share/dict/words and the shuf
135 command is used to pull out a word. The hash %String::Util::PATHS sets
136 the paths to the dictionary file and the shuf executable. Modify that
137 hash to change the paths. So this code:
138 foreach my $idx (1..3) {
140 print randword('dictionary'), "\n";
141 }
142 would output something like this:
144 mustache
146 fronds
147 browning
148 option: alpha
150 If the alpha option is true, only alphabetic characters are returned,
152 no numerals. For example, this code:
153 foreach my $idx (1..3) {
155 print randword(4, alpha=>1), "\n";
156 }
157 would output something like this:
159 qrML
161 wmWf
162 QGvF
163 option: numerals
165 If the numerals option is true, only numerals are returned, no
167 alphabetic characters. So this code:
168 foreach my $idx (1..3) {
170 print randword(4, numerals=>1), "\n";
171 }
172 would output something like this:
174 3981
176 4734
177 2657
178 option: strip_vowels
180 This option is true by default. If true, vowels are not included in
182 the returned random string. So this code:
183 foreach my $idx (1..3) {
185 print randword(4, strip_vowels=>1), "\n";
186 }
187 would output something like this:
189 Sk3v
191 pV5z
192 XhSX
193 eqq($scalar1, $scalar2)
195 Returns true if the two given values are equal. Also returns true if
196 both are undef. If only one is undef, or if they are both defined but
197 different, returns false. Here are some examples and what they return.
198 $var = eqq('x', 'x'); # True
200 $var = eqq('x', undef); # False
201 $var = eqq(undef, undef); # True
202 Note: equndef() is an alias to this function. It is considered
204 deprecated. It may be removed in future versions.
205 neqq($scalar1, $scalar2)
207 The opposite of neqq, returns true if the two values are *not* the
208 same. Here are some examples and what they return.
209 $var = neqq('x', 'x'); # False
211 $var = neqq('x', undef); # True
212 $var = neqq(undef, undef); # False
213 Note: neundef() is an alias to this function. It is considered
215 deprecated. It may be removed in future versions.
216 ords($string)
218 Returns the given string represented as the ascii value of each
219 character.
220 $var = ords('Hendrix'); # {72}{101}{110}{100}{114}{105}{120}
222 options
224 • convert_spaces=>[true|false]
226 If convert_spaces is true (which is the default) then spaces are
228 converted to their matching ord values. So, for example, this code:
229 $var = ords('a b', convert_spaces=>1); # {97}{32}{98}
231 This code returns the same thing:
233 $var = ords('a b'); # {97}{32}{98}
235 If convert_spaces is false, then spaces are just returned as
237 spaces. So this code:
238 ords('a b', convert_spaces=>0); # {97} {98}
240 • alpha_nums
242 If the alpha_nums option is false, then characters 0-9, a-z, and
244 A-Z are not converted. For example, this code:
245 $var = ords('a=b', alpha_nums=>0); # a{61}b
247 deords($string)
249 Takes the output from ords() and returns the string that original
250 created that output.
251 $var = deords('{72}{101}{110}{100}{114}{105}{120}'); # 'Hendrix'
253 contains($string, $substring)
255 Checks if the string contains substring
256 $var = contains("Hello world", "Hello"); # true
258 $var = contains("Hello world", "llo wor"); # true
259 $var = contains("Hello world", "QQQ"); # false
260 # Also works with grep
262 @arr = grep { contains("cat") } @input;
263 startswith($string, $substring)
265 Checks if the string starts with the characters in substring
266 $var = startwith("Hello world", "Hello"); # true
268 $var = startwith("Hello world", "H"); # true
269 $var = startwith("Hello world", "Q"); # false
270 # Also works with grep
272 @arr = grep { startswith("X") } @input;
273 endswith($string, $substring)
275 Checks if the string ends with the characters in substring
276 $var = endswith("Hello world", "world"); # true
278 $var = endswith("Hello world", "d"); # true
279 $var = endswith("Hello world", "QQQ"); # false
280 # Also works with grep
282 @arr = grep { endswith("z") } @input;
283 crunchlines($string)
285 Compacts contiguous newlines into single newlines. Whitespace between
286 newlines is ignored, so that two newlines separated by whitespace is
287 compacted down to a single newline.
288 $var = crunchlines("x\n\n\nx"); # "x\nx";
290 sanitize($string, $separator = "_")
292 Sanitize all non alpha-numeric characters in a string to underscores.
293 This is useful to take a URL, or filename, or text description and know
294 you can use it safely in a URL or a filename.
295 Note: This will remove any trailing or leading '_' on the string
297 $var = sanitize("http://www.google.com/") # http_www_google_com
299 $var = sanitize("foo_bar()"; # foo_bar
300 $var = sanitize("/path/to/file.txt"); # path_to_file_txt
301 $var = sanitize("Big yellow bird!", "."); # Big.yellow.bird
302 file_get_contents($string, $boolean)
304 Read an entire file from disk into a string. Returns undef if the file
305 cannot be read for any reason. Can also return the file as an array of
306 lines.
307 $str = file_get_contents("/tmp/file.txt"); # Return a string
309 @lines = file_get_contents("/tmp/file.txt", 1); # Return an array
310
312 Copyright (c) 2012-2016 by Miko O'Sullivan. All rights reserved. This
313 program is free software; you can redistribute it and/or modify it
314 under the same terms as Perl itself. This software comes with NO
315 WARRANTY of any kind.
316
318 Miko O'Sullivan <miko@idocs.com>
319 Scott Baker <scott@perturb.org>
321perl v5.34.0 2022-01-21 String::Util(3pm)