Merge branch 'gawk-5.1-stable' of ssh://git.sv.gnu.org/srv/git/gawk into gawk-5.1-stable

1 files changed, 20 insertions, 1 deletions

diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 1584d3f4..6ace2e85 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -11316,6 +11316,21 @@ When used in numeric conversions, strongly typed regexp variables convert
 to zero. When used in string conversions, they convert to the string
 value of the original regexp text.
 
+There is an additional, interesting corner case. When used as the third
+argument to @code{sub()} or @code{gsub()}, they retain their type.  Thus,
+if you have something like this:
+
+@example
+re = @/don't panic/
+sub(/don't/, "do", re)
+print typeof(re), re
+@end example
+
+@noindent
+then @code{re} retains its type, but now attempts to match the string
+@samp{do panic}.  This provides a (very indirect) way to create regexp-typed
+variables at runtime.
+
 @node Variables
 @subsection Variables
 
@@ -17823,6 +17838,9 @@ numeric values less than one as if they were one.  If no @var{target}
 is supplied, use @code{$0}.  Return the modified string as the result
 of the function. The original target string is @emph{not} changed.
 
+The returned value is @emph{always} a string, even if the original
+@var{target} was a number or a regexp value.
+
 @code{gensub()} is a general substitution function.  Its purpose is
 to provide more features than the standard @code{sub()} and @code{gsub()}
 functions.
@@ -17871,7 +17889,8 @@ substitution is performed.  If @var{how} is zero, @command{gawk} issues
 a warning message.
 
 If @var{regexp} does not match @var{target}, @code{gensub()}'s return value
-is the original unchanged value of @var{target}.
+is the original unchanged value of @var{target}.  Note that, as mentioned
+above, the returned value is a string, even if @var{target} was not.
 
 @item @code{gsub(@var{regexp}, @var{replacement}} [@code{, @var{target}}]@code{)}
 @cindexawkfunc{gsub}