From: Nicholas Clark <nick@ccl4.org>
Date: Sat, 27 Nov 2004 14:43:37 +0000 (+0000)
Subject: Clarify the return values of pos, particularly 0 and undef, as
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b17c04f34c21c46addcb48d31ee352efe59be622;p=p5sagit%2Fp5-mst-13.2.git

Clarify the return values of pos, particularly 0 and undef, as
suggested by Stas Bekman

p4raw-id: //depot/perl@23550
---

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index c67560f..5fde4b8 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3828,9 +3828,14 @@ array in subroutines, just like C<shift>.
 =item pos
 
 Returns the offset of where the last C<m//g> search left off for the variable
-in question (C<$_> is used when the variable is not specified).  May be
-modified to change that offset.  Such modification will also influence
-the C<\G> zero-width assertion in regular expressions.  See L<perlre> and
+in question (C<$_> is used when the variable is not specified).  Note that
+0 is a valid match offset, while C<undef> indicates that the search position
+is reset (usually due to match failure, but can also be because no match has
+yet been performed on the scalar). C<pos> directly accesses the location used
+by the regexp engine to store the offset, so assigning to C<pos> will change
+that offset, and so will also influence the C<\G> zero-width assertion in
+regular expressions. Because a failed C<m//gc> match doesn't reset the offset,
+the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST