.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "String::Util 3pm" .TH String::Util 3pm "2023-02-05" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" String::Util \-\- String processing utility functions .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBString::Util\fR provides a collection of small, handy functions for processing strings in various ways. .SH "INSTALLATION" .IX Header "INSTALLATION" .Vb 1 \& cpanm String::Util .Ve .SH "USAGE" .IX Header "USAGE" No functions are exported by default, they must be specified: .PP .Vb 1 \& use String::Util qw(trim eqq contains) .Ve .PP alternately you can use \f(CW\*(C`:all\*(C'\fR to export \fBall\fR of the functions .PP .Vb 1 \& use String::Util qw(:all) .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "collapse($string)" .IX Subsection "collapse($string)" \&\f(CW\*(C`collapse()\*(C'\fR collapses all whitespace in the string down to single spaces. Also removes all leading and trailing whitespace. Undefined input results in undefined output. .PP .Vb 1 \& $var = collapse(" Hello world! "); # "Hello world!" .Ve .SS "hascontent($scalar), nocontent($scalar)" .IX Subsection "hascontent($scalar), nocontent($scalar)" \&\f(CW\*(C`hascontent()\*(C'\fR returns true if the given argument is defined and contains something besides whitespace. .PP 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. .PP \&\f(CW\*(C`nocontent()\*(C'\fR returns the negation of \f(CW\*(C`hascontent()\*(C'\fR. .PP .Vb 3 \& $var = hascontent(""); # False \& $var = hascontent(" "); # False \& $var = hascontent("a"); # True \& \& $var = nocontent(""); # True \& $var = nocontent("a"); # False .Ve .SS "trim($string), ltrim($string), rtrim($string)" .IX Subsection "trim($string), ltrim($string), rtrim($string)" Returns the string with all leading and trailing whitespace removed. .PP .Vb 1 \& $var = trim(" my string "); # "my string" .Ve .PP \&\f(CW\*(C`ltrim()\*(C'\fR trims \fBleading\fR whitespace only. .PP \&\f(CW\*(C`rtrim()\*(C'\fR trims \fBtrailing\fR whitespace only. .SS "nospace($string)" .IX Subsection "nospace($string)" Removes \fBall\fR whitespace characters from the given string. This includes spaces between words. .PP .Vb 1 \& $var = nospace(" Hello World! "); # "HelloWorld!" .Ve .SS "htmlesc($string)" .IX Subsection "htmlesc($string)" Formats a string for literal output in \s-1HTML.\s0 An undefined value is returned as an empty string. .PP \&\fBhtmlesc()\fR is very similar to \s-1CGI\s0.pm's escapeHTML. However, there are a few differences. \fBhtmlesc()\fR changes an undefined value to an empty string, whereas \&\fBescapeHTML()\fR returns undefs as undefs. .SS "jsquote($string)" .IX Subsection "jsquote($string)" Escapes and quotes a string for use in JavaScript. Escapes single quotes and surrounds the string in single quotes. Returns the modified string. .SS "unquote($string)" .IX Subsection "unquote($string)" 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: .PP .Vb 5 \& unquote(q|\*(AqHendrix\*(Aq|); # Hendrix \& unquote(q|"Hendrix"|); # Hendrix \& unquote(q|Hendrix|); # Hendrix \& unquote(q|"Hendrix\*(Aq|); # "Hendrix\*(Aq \& unquote(q|O\*(AqSullivan|); # O\*(AqSullivan .Ve .PP \&\fBoption:\fR braces .PP If the braces option is true, surrounding braces such as [] and {} are also removed. Some examples: .PP .Vb 3 \& unquote(q|[Janis]|, braces=>1); # Janis \& unquote(q|{Janis}|, braces=>1); # Janis \& unquote(q|(Janis)|, braces=>1); # Janis .Ve .ie n .SS "repeat($string, $count)" .el .SS "repeat($string, \f(CW$count\fP)" .IX Subsection "repeat($string, $count)" Returns the given string repeated the given number of times. The following command outputs \*(L"Fred\*(R" three times: .PP .Vb 1 \& print repeat(\*(AqFred\*(Aq, 3), "\en"; .Ve .PP Note that \f(CW\*(C`repeat()\*(C'\fR was created a long time based on a misunderstanding of how the perl operator 'x' works. The following command using \f(CW\*(C`x\*(C'\fR would perform exactly the same as the above command. .PP .Vb 1 \& print \*(AqFred\*(Aq x 3, "\en"; .Ve .PP Use whichever you prefer. .ie n .SS "eqq($scalar1, $scalar2)" .el .SS "eqq($scalar1, \f(CW$scalar2\fP)" .IX Subsection "eqq($scalar1, $scalar2)" Returns true if the two given values are equal. Also returns true if both are \f(CW\*(C`undef\*(C'\fR. If only one is \f(CW\*(C`undef\*(C'\fR, or if they are both defined but different, returns false. Here are some examples and what they return. .PP .Vb 3 \& $var = eqq(\*(Aqx\*(Aq, \*(Aqx\*(Aq); # True \& $var = eqq(\*(Aqx\*(Aq, undef); # False \& $var = eqq(undef, undef); # True .Ve .ie n .SS "neqq($scalar1, $scalar2)" .el .SS "neqq($scalar1, \f(CW$scalar2\fP)" .IX Subsection "neqq($scalar1, $scalar2)" The opposite of \f(CW\*(C`neqq\*(C'\fR, returns true if the two values are *not* the same. Here are some examples and what they return. .PP .Vb 3 \& $var = neqq(\*(Aqx\*(Aq, \*(Aqx\*(Aq); # False \& $var = neqq(\*(Aqx\*(Aq, undef); # True \& $var = neqq(undef, undef); # False .Ve .SS "ords($string)" .IX Subsection "ords($string)" Returns the given string represented as the ascii value of each character. .PP .Vb 1 \& $var = ords(\*(AqHendrix\*(Aq); # {72}{101}{110}{100}{114}{105}{120} .Ve .PP \&\fBoptions\fR .IP "\(bu" 4 convert_spaces=>[true|false] .Sp If convert_spaces is true (which is the default) then spaces are converted to their matching ord values. So, for example, this code: .Sp .Vb 1 \& $var = ords(\*(Aqa b\*(Aq, convert_spaces=>1); # {97}{32}{98} .Ve .Sp This code returns the same thing: .Sp .Vb 1 \& $var = ords(\*(Aqa b\*(Aq); # {97}{32}{98} .Ve .Sp If convert_spaces is false, then spaces are just returned as spaces. So this code: .Sp .Vb 1 \& ords(\*(Aqa b\*(Aq, convert_spaces=>0); # {97} {98} .Ve .IP "\(bu" 4 alpha_nums .Sp If the alpha_nums option is false, then characters 0\-9, a\-z, and A\-Z are not converted. For example, this code: .Sp .Vb 1 \& $var = ords(\*(Aqa=b\*(Aq, alpha_nums=>0); # a{61}b .Ve .SS "deords($string)" .IX Subsection "deords($string)" Takes the output from \f(CW\*(C`ords()\*(C'\fR and returns the string that original created that output. .PP .Vb 1 \& $var = deords(\*(Aq{72}{101}{110}{100}{114}{105}{120}\*(Aq); # \*(AqHendrix\*(Aq .Ve .ie n .SS "contains($string, $substring)" .el .SS "contains($string, \f(CW$substring\fP)" .IX Subsection "contains($string, $substring)" Checks if the string contains substring .PP .Vb 3 \& $var = contains("Hello world", "Hello"); # true \& $var = contains("Hello world", "llo wor"); # true \& $var = contains("Hello world", "QQQ"); # false \& \& # Also works with grep \& @arr = grep { contains("cat") } @input; .Ve .ie n .SS "startswith($string, $substring)" .el .SS "startswith($string, \f(CW$substring\fP)" .IX Subsection "startswith($string, $substring)" Checks if the string starts with the characters in substring .PP .Vb 3 \& $var = startwith("Hello world", "Hello"); # true \& $var = startwith("Hello world", "H"); # true \& $var = startwith("Hello world", "Q"); # false \& \& # Also works with grep \& @arr = grep { startswith("X") } @input; .Ve .ie n .SS "endswith($string, $substring)" .el .SS "endswith($string, \f(CW$substring\fP)" .IX Subsection "endswith($string, $substring)" Checks if the string ends with the characters in substring .PP .Vb 3 \& $var = endswith("Hello world", "world"); # true \& $var = endswith("Hello world", "d"); # true \& $var = endswith("Hello world", "QQQ"); # false \& \& # Also works with grep \& @arr = grep { endswith("z") } @input; .Ve .SS "crunchlines($string)" .IX Subsection "crunchlines($string)" 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. .PP .Vb 1 \& $var = crunchlines("x\en\en\enx"); # "x\enx"; .Ve .ie n .SS "sanitize($string, $separator = ""_"")" .el .SS "sanitize($string, \f(CW$separator\fP = ``_'')" .IX Subsection "sanitize($string, $separator = _)" Sanitize all non alpha-numeric characters in a string to underscores. This is useful to take a \s-1URL,\s0 or filename, or text description and know you can use it safely in a \s-1URL\s0 or a filename. .PP \&\fBNote:\fR This will remove any trailing or leading '_' on the string .PP .Vb 4 \& $var = sanitize("http://www.google.com/") # http_www_google_com \& $var = sanitize("foo_bar()"; # foo_bar \& $var = sanitize("/path/to/file.txt"); # path_to_file_txt \& $var = sanitize("Big yellow bird!", "."); # Big.yellow.bird .Ve .ie n .SS "file_get_contents($string, $boolean)" .el .SS "file_get_contents($string, \f(CW$boolean\fP)" .IX Subsection "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 lines. .PP .Vb 2 \& $str = file_get_contents("/tmp/file.txt"); # Return a string \& @lines = file_get_contents("/tmp/file.txt", 1); # Return an array .Ve .PP \&\fBNote:\fR If you opt to return an array, carriage returns and line feeds are removed from the end of each line. .PP \&\fBNote:\fR File is read in \fB\s-1UTF\-8\s0\fR mode, unless \f(CW$FGC_MODE\fR is set to an appropriate encoding. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" 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 \fB\s-1NO WARRANTY\s0\fR of any kind. .SH "AUTHORS" .IX Header "AUTHORS" Miko O'Sullivan .PP Scott Baker