From 80a3f1f4ba8d4a8085b65e1c404a2fb7f6e2375c Mon Sep 17 00:00:00 2001
From: Dan Book <grinnz@grinnz.com>
Date: Tue, 22 Apr 2025 05:18:37 -0400
Subject: [PATCH] better suggestions for builtin::trim equivalence (Resolves
 #23212)

---
 lib/builtin.pm                 | 13 +++++++------
 t/porting/known_pod_issues.dat |  3 ++-
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/lib/builtin.pm b/lib/builtin.pm
index d56bfb6f08f0..ddc176f25678 100644
--- a/lib/builtin.pm
+++ b/lib/builtin.pm
@@ -1,4 +1,4 @@
-package builtin 0.018;
+package builtin 0.019;
 
 use v5.40;
 
@@ -43,6 +43,10 @@ can be requested for convenience.
 Individual named functions can be imported by listing them as import
 parameters on the C<use> statement for this pragma.
 
+The L<builtin::compat> module from CPAN provides versions of many of these
+functions that can be used on Perl versions where C<builtin> or specific
+functions are not yet available.
+
 B<Warning>:  At present, many of the functions in the C<builtin> namespace are
 experimental.  Calling them will trigger warnings of the
 C<experimental::builtin> category.
@@ -414,15 +418,12 @@ A complete list is in L<perlrecharclass/Whitespace>.
 
 C<trim> is equivalent to:
 
-    $str =~ s/\A\s+|\s+\z//urg;
+    my $trimmed = $str =~ s/\A\s+//ur =~ s/\s+\z//ur;
 
 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
 experimental and it is included in the 5.40 and higher builtin version
 bundles.
 
-For Perl versions where this function is not available look at the
-L<String::Util> module for a comparable implementation.
-
 =head2 is_tainted
 
     $bool = is_tainted($var);
@@ -487,4 +488,4 @@ Available starting with Perl 5.40.
 
 =head1 SEE ALSO
 
-L<perlop>, L<perlfunc>, L<Scalar::Util>
+L<perlop>, L<perlfunc>, L<Scalar::Util>, L<builtin::compat>
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 14ca2e583c37..f49d39daf463 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -76,6 +76,7 @@ bind(2)
 blib
 BSD::Resource
 builtin
+builtin::compat
 ByteLoader
 bytes
 bzip2(1)
@@ -119,8 +120,8 @@ connect(2)
 constant
 CORE
 Coro
-CPAN
 cpan
+CPAN
 cpan2dist(1)
 CPAN::API::HOWTO
 CPAN::Changes::Spec