Text::Trim(3pm)

💖 Text::Trim — bestie edition 💖

ok so. you know that one friend who just... cleans up your mess? that's Text::Trim. it's the Perl module that removes leading and/or trailing whitespace from strings. periodt.

it's giving "simple regex wrapper with a flexible context-based interface," and honestly? iconic. 💅

---

✨ VERSION ✨

version 1.04 🎀

---

🌸 SYNOPSIS 🌸

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
    # ...
}

see how it just works? no cap. ✨

---

🦋 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.

tl;dr: it's a regex glow-up in a tiny package. lowkey obsessed. 💖

---

🎀 EXPORTS 🎀

All functions are exported by default. no use gymnastics required, they just show up to the party. 🫶

---

💜 CONTEXT HANDLING 💜

this is the part where it gets smart, and the vibe check is very much passed.

void context

Functions called in void context change their arguments in-place.

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.

so like, if you call it and don't catch the return value, it edits your stuff directly. main character energy fr. but if you do catch the value, your originals are safe. 🙈

list context

Values passed in are changed and returned without affecting the originals.

@result = trim(@strings);    # @strings is unchanged

@result = rtrim;             # @result contains rtrimmed $_

($result) = ltrim(@strings); # like $result = ltrim($strings[0]);

copy-paste behavior, basically. your originals stay untouched. slay. 💅

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.

@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

⚠️ bestie listen. multiple args in scalar context = they get joined using $". if that's not the vibe you want, pass exactly ONE argument. i'm not kidding. that's the whole warning. 🚨

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.

$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 ''

undef stays undef. it said "not my problem, i'm not touching that." 💀 respect honestly.

---

🔥 FUNCTIONS 🔥

trim

Removes leading and trailing whitespace from all arguments, or $_ if none are provided.

the all-rounder. both sides. symmetrical. balanced. 🧚

rtrim

Like trim() but removes only trailing (right) whitespace.

right side only. bye to the trailing stuff. 👋

ltrim

Like trim() but removes only leading (left) whitespace.

left side only. clearing the way before the good part. ✨

---

🌈 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.

Note that this only applies in the case of perl versions after 5.8.0 or so.

so yes, it handles the fancy non-breaking spaces too, as long as the utf8 flag is on. 🦋 just keep in mind that's for perl versions after 5.8.0 or so. iykyk.

---

👑 SEE ALSO 👑

Brent B. Powers' 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 🫶

<https://github.com/rjt-pl/Text-Trim/issues>: Bug reports and feature requests

<https://github.com/rjt-pl/Text-Trim.git>: Source repository

---

🌸 ACKNOWLEDGEMENTS 🌸

Terrence Brannon <metaperl@gmail.com> for bringing my attention to 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>

---

and that's the whole page bestie 💅 this was Text::Trim, version 1.04, and it came to you courtesy of perl v5.36.0, dated 2022-11-20. now go trim something. go off. ✨💖🦋