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         $var = collapse("  Hello     world!    "); # "Hello world!"
31
32   hascontent($scalar), nocontent($scalar)
33       hascontent() returns true if the given argument is defined and contains
34       something besides whitespace.
35
36       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
41       nocontent() returns the negation of hascontent().
42
43         $var = hascontent("");  # False
44         $var = hascontent(" "); # False
45         $var = hascontent("a"); # True
46
47         $var = nocontent("");   # True
48         $var = nocontent("a");  # False
49
50   trim($string), ltrim($string), rtrim($string)
51       Returns the string with all leading and trailing whitespace removed.
52
53         $var = trim(" my string  "); # "my string"
54
55       ltrim() trims leading whitespace only.
56
57       rtrim() trims trailing whitespace only.
58
59   nospace($string)
60       Removes all whitespace characters from the given string. This includes
61       spaces between words.
62
63         $var = nospace("  Hello World!   "); # "HelloWorld!"
64
65   htmlesc($string)
66       Formats a string for literal output in HTML.  An undefined value is
67       returned as an empty string.
68
69       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
73   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
78   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
84         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
90       option: braces
91
92       If the braces option is true, surrounding braces such as [] and {} are
93       also removed. Some examples:
94
95         unquote(q|[Janis]|, braces=>1);  # Janis
96         unquote(q|{Janis}|, braces=>1);  # Janis
97         unquote(q|(Janis)|, braces=>1);  # Janis
98
99   repeat($string, $count)
100       Returns the given string repeated the given number of times. The
101       following command outputs "Fred" three times:
102
103         print repeat('Fred', 3), "\n";
104
105       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
109         print 'Fred' x 3, "\n";
110
111       Use whichever you prefer.
112
113   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
119         $var = eqq('x', 'x');     # True
120         $var = eqq('x', undef);   # False
121         $var = eqq(undef, undef); # True
122
123   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
127         $var = neqq('x', 'x');     # False
128         $var = neqq('x', undef);   # True
129         $var = neqq(undef, undef); # False
130
131   ords($string)
132       Returns the given string represented as the ascii value of each
133       character.
134
135         $var = ords('Hendrix'); # {72}{101}{110}{100}{114}{105}{120}
136
137       options
138
139       •   convert_spaces=>[true|false]
140
141           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
144             $var = ords('a b', convert_spaces=>1); # {97}{32}{98}
145
146           This code returns the same thing:
147
148             $var = ords('a b');                    # {97}{32}{98}
149
150           If convert_spaces is false, then spaces are just returned as
151           spaces. So this code:
152
153             ords('a b', convert_spaces=>0);        # {97} {98}
154
155       •   alpha_nums
156
157           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
160             $var = ords('a=b', alpha_nums=>0); # a{61}b
161
162   deords($string)
163       Takes the output from ords() and returns the string that original
164       created that output.
165
166         $var = deords('{72}{101}{110}{100}{114}{105}{120}'); # 'Hendrix'
167
168   contains($string, $substring)
169       Checks if the string contains substring
170
171         $var = contains("Hello world", "Hello");   # true
172         $var = contains("Hello world", "llo wor"); # true
173         $var = contains("Hello world", "QQQ");     # false
174
175         # Also works with grep
176         @arr = grep { contains("cat") } @input;
177
178   startswith($string, $substring)
179       Checks if the string starts with the characters in substring
180
181         $var = startwith("Hello world", "Hello"); # true
182         $var = startwith("Hello world", "H");     # true
183         $var = startwith("Hello world", "Q");     # false
184
185         # Also works with grep
186         @arr = grep { startswith("X") } @input;
187
188   endswith($string, $substring)
189       Checks if the string ends with the characters in substring
190
191         $var = endswith("Hello world", "world");   # true
192         $var = endswith("Hello world", "d");       # true
193         $var = endswith("Hello world", "QQQ");     # false
194
195         # Also works with grep
196         @arr = grep { endswith("z") } @input;
197
198   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
203         $var = crunchlines("x\n\n\nx"); # "x\nx";
204
205   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
210       Note: This will remove any trailing or leading '_' on the string
211
212         $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
217   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
222         $str   = file_get_contents("/tmp/file.txt");    # Return a string
223         @lines = file_get_contents("/tmp/file.txt", 1); # Return an array
224
225       Note: If you opt to return an array, carriage returns and line feeds
226       are removed from the end of each line.
227
228       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

AUTHORS

238       Miko O'Sullivan <miko@idocs.com>
239
240       Scott Baker <scott@perturb.org>
241
242
243
244perl v5.38.0                      2023-07-21                 String::Util(3pm)
Impressum