.\" 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 .\" ======================================================================== .\" .IX Title "Text::Trim 3pm" .TH Text::Trim 3pm "2022-11-20" "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" Text::Trim \- remove leading and/or trailing whitespace from strings .SH "VERSION" .IX Header "VERSION" version 1.04 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Text::Trim; \& \& $text = "\etimportant data\en"; \& $data = trim $text; \& # now $data contains "important data" and $text is unchanged \& \& # or: \& trim $text; # work in\-place, $text now contains "important data" \& \& @lines = ; \& rtrim @lines; # remove trailing whitespace from all lines \& \& # Alternatively: \& @lines = rtrim ; \& \& # Or even: \& while () { \& trim; # Change $_ in place \& # ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides functions for removing leading and/or trailing whitespace from strings. It is basically a wrapper around some simple regexes with a flexible context-based interface. .SH "EXPORTS" .IX Header "EXPORTS" All functions are exported by default. .SH "CONTEXT HANDLING" .IX Header "CONTEXT HANDLING" .SS "void context" .IX Subsection "void context" Functions called in void context change their arguments in-place .PP .Vb 1 \& trim(@strings); # All strings in @strings are trimmed in\-place \& \& ltrim($text); # remove leading whitespace on $text \& \& rtrim; # remove trailing whitespace on $_ .Ve .PP No changes are made to arguments in non-void contexts. .SS "list context" .IX Subsection "list context" Values passed in are changed and returned without affecting the originals. .PP .Vb 1 \& @result = trim(@strings); # @strings is unchanged \& \& @result = rtrim; # @result contains rtrimmed $_ \& \& ($result) = ltrim(@strings); # like $result = ltrim($strings[0]); .Ve .SS "scalar context" .IX Subsection "scalar context" As list context but multiple arguments are stringified before being returned. Single arguments are unaffected. This means that under these circumstances, the value of \f(CW$"\fR (\f(CW$LIST_SEPARATOR\fR) is used to join the values. If you don't want this, make sure you only use single arguments when calling in scalar context. .PP .Vb 3 \& @strings = ("\ethello\en", "\etthere\en"); \& $trimmed = trim(@strings); \& # $trimmed = "hello there" \& \& local $" = \*(Aq, \*(Aq; \& $trimmed = trim(@strings); \& # Now $trimmed = "hello, there" \& \& $trimmed = rtrim; \& # $trimmed = $_ minus trailing whitespace .Ve .SS "Undefined values" .IX Subsection "Undefined values" If any of the functions are called with undefined values, the behaviour is in general to pass them through unchanged. When stringifying a list (calling in scalar context with multiple arguments) undefined elements are excluded, but if all elements are undefined then the return value is also undefined. .PP .Vb 5 \& $foo = trim(undef); # $foo is undefined \& $foo = trim(undef, undef); # $foo is undefined \& @foo = trim(undef, undef); # @foo contains 2 undefined values \& trim(@foo) # @foo still contains 2 undefined values \& $foo = trim(\*(Aq\*(Aq, undef); # $foo is \*(Aq\*(Aq .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "trim" .IX Subsection "trim" Removes leading and trailing whitespace from all arguments, or \f(CW$_\fR if none are provided. .SS "rtrim" .IX Subsection "rtrim" Like \f(CW\*(C`trim()\*(C'\fR but removes only trailing (right) whitespace. .SS "ltrim" .IX Subsection "ltrim" Like \f(CW\*(C`trim()\*(C'\fR but removes only leading (left) whitespace. .SH "UNICODE" .IX Header "UNICODE" Because this module is implemented using Perl regular expressions, it is capable of recognising and removing unicode whitespace characters (such as non-breaking spaces) from scalars with the utf8 flag on. See Encode for details about the utf8 flag. .PP Note that this only applies in the case of perl versions after 5.8.0 or so. .SH "SEE ALSO" .IX Header "SEE ALSO" Brent B. Powers' String::Strip performs a similar function in \s-1XS.\s0 .SH "AUTHORS" .IX Header "AUTHORS" \&\fBMatt Lawrence\fR \- Original author and maintainer .PP \&\fBRyan Thompson\fR \- Co-maintainer, miscellaneous fixes .SH "SUPPORT" .IX Header "SUPPORT" : Bug reports and feature requests .PP : Source repository .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Terrence Brannon for bringing my attention to String::Strip and suggesting documentation changes. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP