1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
# NAME
Text::Trim - remove leading and/or trailing whitespace from strings
# VERSION
version 1.04
# SYNOPSIS
```perl
use Text::Trim;
$text = "\timportant data\n";
$data = trim $text;
# now $data contains "important data" and $text is unchanged
# or:
trim $text; # work in-place, $text now contains "important data"
@lines = <STDIN>;
rtrim @lines; # remove trailing whitespace from all lines
# Alternatively:
@lines = rtrim <STDIN>;
# Or even:
while (<STDIN>) {
trim; # Change $_ in place
# ...
}
```
# 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.
# EXPORTS
All functions are exported by default.
# CONTEXT HANDLING
## void context
Functions called in void context change their arguments in-place
```perl
trim(@strings); # All strings in @strings are trimmed in-place
ltrim($text); # remove leading whitespace on $text
rtrim; # remove trailing whitespace on $_
```
No changes are made to arguments in non-void contexts.
## list context
Values passed in are changed and returned without affecting the originals.
```perl
@result = trim(@strings); # @strings is unchanged
@result = rtrim; # @result contains rtrimmed $_
($result) = ltrim(@strings); # like $result = ltrim($strings[0]);
```
## 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 `$"` (`$LIST_SEPARATOR`) is used to join the values. If you
don't want this, make sure you only use single arguments when calling in
scalar context.
```perl
@strings = ("\thello\n", "\tthere\n");
$trimmed = trim(@strings);
# $trimmed = "hello there"
local $" = ', ';
$trimmed = trim(@strings);
# Now $trimmed = "hello, there"
$trimmed = rtrim;
# $trimmed = $_ minus trailing whitespace
```
## 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.
```perl
$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('', undef); # $foo is ''
```
# FUNCTIONS
## trim
Removes leading and trailing whitespace from all arguments, or `$_` if none
are provided.
## rtrim
Like `trim()` but removes only trailing (right) whitespace.
## ltrim
Like `trim()` but removes only leading (left) whitespace.
# 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](https://metacpan.org/pod/Encode) for details about the
utf8 flag.
Note that this only applies in the case of perl versions after 5.8.0 or so.
# SEE ALSO
Brent B. Powers' [String::Strip](https://metacpan.org/pod/String::Strip) performs a similar function in XS.
# AUTHORS
**Matt Lawrence** <mattlaw@cpan.org> - Original author and maintainer
**Ryan Thompson** <rjt@cpan.org> - Co-maintainer, miscellaneous fixes
# SUPPORT
- [Issue Tracker](https://github.com/rjt-pl/Text-Trim/issues): Bug reports and feature requests
- [GitHub Repository](https://github.com/rjt-pl/Text-Trim.git)
# ACKNOWLEDGEMENTS
Terrence Brannon <metaperl@gmail.com> for bringing my attention to
[String::Strip](https://metacpan.org/pod/String::Strip) and suggesting documentation changes.
# LICENSE
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
[http://dev.perl.org/licenses/artistic.html](http://dev.perl.org/licenses/artistic.html)
|
