Document that return value of pos(), by default, expresses characters.

When 'use bytes' is in effect, the return value expresses bytes.

Revise documentation and add some tests exemplifying this.

On recommendation of Jason Gibson.

For: RT # 127518

2 files changed, 32 insertions, 2 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 2ac48b9196..176b02cc7d 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -5604,7 +5604,9 @@ X<pos> X<match, position>
 
 Returns the offset of where the last C<m//g> search left off for the
 variable in question (L<C<$_>|perlvar/$_> is used when the variable is not
-specified).  Note that 0 is a valid match offset.
+specified).  This offset is in characters unless the
+(no-longer-recommended) L<C<use bytes>|bytes> pragma is in effect, in
+which case the offset is in bytes.  Note that 0 is a valid match offset.
 L<C<undef>|/undef EXPR> indicates
 that the search position is reset (usually due to match failure, but
 can also be because no match has yet been run on the scalar).
diff --git a/t/op/pos.t b/t/op/pos.t
index 1e3ce33aa1..0bc997e855 100644
--- a/t/op/pos.t
+++ b/t/op/pos.t
@@ -6,7 +6,7 @@ BEGIN {
     require './test.pl';
 }
 
-plan tests => 29;
+plan tests => 33;
 
 $x='banana';
 $x=~/.a/g;
@@ -131,3 +131,31 @@ for my $one(pos $x) {
            'no assertion failure when getting pos clobbers ref with undef';
     }
 }
+
+{
+    # RT # 127518
+    my $x = "\N{U+10000}abc";
+    my %expected = (
+        chars   => { length => 4, pos => 2 },
+        bytes   => { length => 7, pos => 5 },
+    );
+    my %observed;
+    $observed{chars}{length} = length($x);
+    $x =~ m/a/g;
+    $observed{chars}{pos}    = pos($x);
+
+    {
+        use bytes;
+        $observed{bytes}{length} = length($x);
+        $observed{bytes}{pos}    = pos($x);
+    }
+
+    is( $observed{chars}{length}, $expected{chars}{length},
+         "Got expected length in chars");
+    is( $observed{chars}{pos}, $expected{chars}{pos},
+         "Got expected pos in chars");
+    is( $observed{bytes}{length}, $expected{bytes}{length},
+         "Got expected length in bytes");
+    is( $observed{bytes}{pos}, $expected{bytes}{pos},
+         "Got expected pos in bytes");
+}