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 $var = collapse(" Hello world! "); # "Hello world!"
31 hascontent($scalar), nocontent($scalar)
33 hascontent() returns true if the given argument is defined and contains
34 something besides whitespace.
35 An undefined value returns false. An empty string returns false. A
37 value containing nothing but whitespace (spaces, tabs, carriage
38 returns, newlines, backspace) returns false. A string containing any
39 other characters (including zero) returns true.
40 nocontent() returns the negation of hascontent().
42 $var = hascontent(""); # False
44 $var = hascontent(" "); # False
45 $var = hascontent("a"); # True
46 $var = nocontent(""); # True
48 $var = nocontent("a"); # False
49 trim($string), ltrim($string), rtrim($string)
51 Returns the string with all leading and trailing whitespace removed.
52 $var = trim(" my string "); # "my string"
54 ltrim() trims leading whitespace only.
56 rtrim() trims trailing whitespace only.
58 nospace($string)
60 Removes all whitespace characters from the given string. This includes
61 spaces between words.
62 $var = nospace(" Hello World! "); # "HelloWorld!"
64 htmlesc($string)
66 Formats a string for literal output in HTML. An undefined value is
67 returned as an empty string.
68 htmlesc() is very similar to CGI.pm's escapeHTML. However, there are a
70 few differences. htmlesc() changes an undefined value to an empty
71 string, whereas escapeHTML() returns undefs as undefs.
72 jsquote($string)
74 Escapes and quotes a string for use in JavaScript. Escapes single
75 quotes and surrounds the string in single quotes. Returns the modified
76 string.
77 unquote($string)
79 If the given string starts and ends with quotes, removes them.
80 Recognizes single quotes and double quotes. The value must begin and
81 end with same type of quotes or nothing is done to the value. Undef
82 input results in undef output. Some examples and what they return:
83 unquote(q|'Hendrix'|); # Hendrix
85 unquote(q|"Hendrix"|); # Hendrix
86 unquote(q|Hendrix|); # Hendrix
87 unquote(q|"Hendrix'|); # "Hendrix'
88 unquote(q|O'Sullivan|); # O'Sullivan
89 option: braces
91 If the braces option is true, surrounding braces such as [] and {} are
93 also removed. Some examples:
94 unquote(q|[Janis]|, braces=>1); # Janis
96 unquote(q|{Janis}|, braces=>1); # Janis
97 unquote(q|(Janis)|, braces=>1); # Janis
98 repeat($string, $count)
100 Returns the given string repeated the given number of times. The
101 following command outputs "Fred" three times:
102 print repeat('Fred', 3), "\n";
104 Note that repeat() was created a long time based on a misunderstanding
106 of how the perl operator 'x' works. The following command using "x"
107 would perform exactly the same as the above command.
108 print 'Fred' x 3, "\n";
110 Use whichever you prefer.
112 eqq($scalar1, $scalar2)
114 Returns true if the two given values are equal. Also returns true if
115 both are "undef". If only one is "undef", or if they are both defined
116 but different, returns false. Here are some examples and what they
117 return.
118 $var = eqq('x', 'x'); # True
120 $var = eqq('x', undef); # False
121 $var = eqq(undef, undef); # True
122 neqq($scalar1, $scalar2)
124 The opposite of "neqq", returns true if the two values are *not* the
125 same. Here are some examples and what they return.
126 $var = neqq('x', 'x'); # False
128 $var = neqq('x', undef); # True
129 $var = neqq(undef, undef); # False
130 ords($string)
132 Returns the given string represented as the ascii value of each
133 character.
134 $var = ords('Hendrix'); # {72}{101}{110}{100}{114}{105}{120}
136 options
138 • convert_spaces=>[true|false]
140 If convert_spaces is true (which is the default) then spaces are
142 converted to their matching ord values. So, for example, this code:
143 $var = ords('a b', convert_spaces=>1); # {97}{32}{98}
145 This code returns the same thing:
147 $var = ords('a b'); # {97}{32}{98}
149 If convert_spaces is false, then spaces are just returned as
151 spaces. So this code:
152 ords('a b', convert_spaces=>0); # {97} {98}
154 • alpha_nums
156 If the alpha_nums option is false, then characters 0-9, a-z, and
158 A-Z are not converted. For example, this code:
159 $var = ords('a=b', alpha_nums=>0); # a{61}b
161 deords($string)
163 Takes the output from ords() and returns the string that original
164 created that output.
165 $var = deords('{72}{101}{110}{100}{114}{105}{120}'); # 'Hendrix'
167 contains($string, $substring)
169 Checks if the string contains substring
170 $var = contains("Hello world", "Hello"); # true
172 $var = contains("Hello world", "llo wor"); # true
173 $var = contains("Hello world", "QQQ"); # false
174 # Also works with grep
176 @arr = grep { contains("cat") } @input;
177 startswith($string, $substring)
179 Checks if the string starts with the characters in substring
180 $var = startwith("Hello world", "Hello"); # true
182 $var = startwith("Hello world", "H"); # true
183 $var = startwith("Hello world", "Q"); # false
184 # Also works with grep
186 @arr = grep { startswith("X") } @input;
187 endswith($string, $substring)
189 Checks if the string ends with the characters in substring
190 $var = endswith("Hello world", "world"); # true
192 $var = endswith("Hello world", "d"); # true
193 $var = endswith("Hello world", "QQQ"); # false
194 # Also works with grep
196 @arr = grep { endswith("z") } @input;
197 crunchlines($string)
199 Compacts contiguous newlines into single newlines. Whitespace between
200 newlines is ignored, so that two newlines separated by whitespace is
201 compacted down to a single newline.
202 $var = crunchlines("x\n\n\nx"); # "x\nx";
204 sanitize($string, $separator = "_")
206 Sanitize all non alpha-numeric characters in a string to underscores.
207 This is useful to take a URL, or filename, or text description and know
208 you can use it safely in a URL or a filename.
209 Note: This will remove any trailing or leading '_' on the string
211 $var = sanitize("http://www.google.com/") # http_www_google_com
213 $var = sanitize("foo_bar()"; # foo_bar
214 $var = sanitize("/path/to/file.txt"); # path_to_file_txt
215 $var = sanitize("Big yellow bird!", "."); # Big.yellow.bird
216 file_get_contents($string, $boolean)
218 Read an entire file from disk into a string. Returns undef if the file
219 cannot be read for any reason. Can also return the file as an array of
220 lines.
221 $str = file_get_contents("/tmp/file.txt"); # Return a string
223 @lines = file_get_contents("/tmp/file.txt", 1); # Return an array
224 Note: If you opt to return an array, carriage returns and line feeds
226 are removed from the end of each line.
227 Note: File is read in UTF-8 mode, unless $FGC_MODE is set to an
229 appropriate encoding.
230
232 Copyright (c) 2012-2016 by Miko O'Sullivan. All rights reserved. This
233 program is free software; you can redistribute it and/or modify it
234 under the same terms as Perl itself. This software comes with NO
235 WARRANTY of any kind.
236
238 Miko O'Sullivan <miko@idocs.com>
239 Scott Baker <scott@perturb.org>
241perl v5.36.0 2023-02-02 String::Util(3pm)