1String::Util(3pm)     User Contributed Perl Documentation    String::Util(3pm)
2
3
4

NAME

6       String::Util -- String processing utility functions
7

DESCRIPTION

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

INSTALLATION

13         cpanm String::Util
14

USAGE

16       No functions are exported by default, they must be specified:
17
18         use String::Util qw(trim eqq contains)
19
20       alternately you can use ":all" to export all of the functions
21
22         use String::Util qw(:all)
23

FUNCTIONS

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
30       Note: "crunch()" is an alias to this function. It is considered
31       deprecated.  It may be removed in future versions.
32
33         $var = collapse("  Hello     world!    "); # "Hello world!"
34
35   hascontent($scalar), nocontent($scalar)
36       hascontent() returns true if the given argument is defined and contains
37       something besides whitespace.
38
39       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
44       "nocontent()" returns the negation of "hascontent()".
45
46         $var = hascontent("");  # False
47         $var = hascontent(" "); # False
48         $var = hascontent("a"); # True
49
50         $var = nocontent("");   # True
51         $var = nocontent("a");  # False
52
53   trim($string), ltrim($string), rtrim($string)
54       Returns the string with all leading and trailing whitespace removed.
55       Trim on undef returns "".
56
57         $var = trim(" my string  "); # "my string"
58
59       ltrim() trims leading whitespace only.
60
61       rtrim() trims trailing whitespace only.
62
63   nospace($string)
64       Removes all whitespace characters from the given string. This includes
65       spaces between words.
66
67         $var = nospace("  Hello World!   "); # "HelloWorld!"
68
69   htmlesc($string)
70       Formats a string for literal output in HTML.  An undefined value is
71       returned as an empty string.
72
73       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
77   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
82   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
88         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
94       option: braces
95
96       If the braces option is true, surrounding braces such as [] and {} are
97       also removed. Some examples:
98
99         unquote(q|[Janis]|, braces=>1);  # Janis
100         unquote(q|{Janis}|, braces=>1);  # Janis
101         unquote(q|(Janis)|, braces=>1);  # Janis
102
103   repeat($string, $count)
104       Returns the given string repeated the given number of times. The
105       following command outputs "Fred" three times:
106
107         print repeat('Fred', 3), "\n";
108
109       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
113         print 'Fred' x 3, "\n";
114
115       Use whichever you prefer.
116
117   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
122         foreach my $idx (1..3) {
123             print randword(4), "\n";
124         }
125
126       would output something like this:
127
128         kBGV
129         NCWB
130         3tHJ
131
132       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
139         foreach my $idx (1..3) {
140             print randword('dictionary'), "\n";
141         }
142
143       would output something like this:
144
145         mustache
146         fronds
147         browning
148
149       option: alpha
150
151       If the alpha option is true, only alphabetic characters are returned,
152       no numerals. For example, this code:
153
154         foreach my $idx (1..3) {
155             print randword(4, alpha=>1), "\n";
156         }
157
158       would output something like this:
159
160         qrML
161         wmWf
162         QGvF
163
164       option: numerals
165
166       If the numerals option is true, only numerals are returned, no
167       alphabetic characters. So this code:
168
169         foreach my $idx (1..3) {
170             print randword(4, numerals=>1), "\n";
171         }
172
173       would output something like this:
174
175         3981
176         4734
177         2657
178
179       option: strip_vowels
180
181       This option is true by default.  If true, vowels are not included in
182       the returned random string. So this code:
183
184         foreach my $idx (1..3) {
185             print randword(4, strip_vowels=>1), "\n";
186         }
187
188       would output something like this:
189
190         Sk3v
191         pV5z
192         XhSX
193
194   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
199         $var = eqq('x', 'x');     # True
200         $var = eqq('x', undef);   # False
201         $var = eqq(undef, undef); # True
202
203       Note: equndef() is an alias to this function. It is considered
204       deprecated.  It may be removed in future versions.
205
206   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
210         $var = neqq('x', 'x');     # False
211         $var = neqq('x', undef);   # True
212         $var = neqq(undef, undef); # False
213
214       Note: neundef() is an alias to this function. It is considered
215       deprecated.  It may be removed in future versions.
216
217   ords($string)
218       Returns the given string represented as the ascii value of each
219       character.
220
221         $var = ords('Hendrix'); # {72}{101}{110}{100}{114}{105}{120}
222
223       options
224
225       •   convert_spaces=>[true|false]
226
227           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
230             $var = ords('a b', convert_spaces=>1); # {97}{32}{98}
231
232           This code returns the same thing:
233
234             $var = ords('a b');                    # {97}{32}{98}
235
236           If convert_spaces is false, then spaces are just returned as
237           spaces. So this code:
238
239             ords('a b', convert_spaces=>0);        # {97} {98}
240
241       •   alpha_nums
242
243           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
246             $var = ords('a=b', alpha_nums=>0); # a{61}b
247
248   deords($string)
249       Takes the output from ords() and returns the string that original
250       created that output.
251
252         $var = deords('{72}{101}{110}{100}{114}{105}{120}'); # 'Hendrix'
253
254   contains($string, $substring)
255       Checks if the string contains substring
256
257         $var = contains("Hello world", "Hello");   # true
258         $var = contains("Hello world", "llo wor"); # true
259         $var = contains("Hello world", "QQQ");     # false
260
261         # Also works with grep
262         @arr = grep { contains("cat") } @input;
263
264   startswith($string, $substring)
265       Checks if the string starts with the characters in substring
266
267         $var = startwith("Hello world", "Hello"); # true
268         $var = startwith("Hello world", "H");     # true
269         $var = startwith("Hello world", "Q");     # false
270
271         # Also works with grep
272         @arr = grep { startswith("X") } @input;
273
274   endswith($string, $substring)
275       Checks if the string ends with the characters in substring
276
277         $var = endswith("Hello world", "world");   # true
278         $var = endswith("Hello world", "d");       # true
279         $var = endswith("Hello world", "QQQ");     # false
280
281         # Also works with grep
282         @arr = grep { endswith("z") } @input;
283
284   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
289         $var = crunchlines("x\n\n\nx"); # "x\nx";
290
291   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
296       Note: This will remove any trailing or leading '_' on the string
297
298         $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
303   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
308         $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

AUTHORS

318       Miko O'Sullivan <miko@idocs.com>
319
320       Scott Baker <scott@perturb.org>
321
322
323
324perl v5.34.0                      2022-01-21                 String::Util(3pm)
Impressum