Excerpts from Yukihiro Matsumoto's message of Fri Mar 13 12:47:48 +0200 2009:
> Hi,
> 
> In message "Re: [ruby-core:22719] Re: [Bug #1251] gsub problem"
>     on Sat, 7 Mar 2009 21:00:34 +0900, Wolfgang Ndasi-Donner <ed.odanow / wonado.de> writes:
> 
> |I think this behaviour should be documented somewhere, because it can 
> |really confuse persons, which do not use complex RegExes during their 
> |daily work.
> 
> Agreed.  Any opinion for concrete description?  Anyone?

RubySpec has this to say (please add any clarifications and
missing behaviour--I am sure there are some 1.9.1 cases at
least):

ruby 1.8.7 (2008-08-11 patchlevel 72) [i686-darwin9]

String#sub with pattern, replacement
- returns a copy of self with all occurrences of pattern replaced with replacement
- ignores a block if supplied
- supports \G which matches at the beginning of the string
- supports /i for ignoring case
- doesn't interpret regexp metacharacters if pattern is a string
- replaces \1 sequences with the regexp's corresponding capture
- treats \1 sequences without corresponding captures as empty strings
- replaces \& and \0 with the complete match
- replaces \` with everything before the current match
- replaces \' with everything after the current match
- replaces \\\+ with \\+
- replaces \+ with the last paren that actually matched
- treats \+ as an empty string if there was no captures
- maps \\ in replacement to \
- leaves unknown \x escapes in replacement untouched
- leaves \ at the end of replacement untouched
- taints the result if the original string or replacement is tainted
- tries to convert pattern to a string using to_str
- raises a TypeError when pattern can't be converted to a string
- tries to convert replacement to a string using to_str
- raises a TypeError when replacement can't be converted to a string
- returns subclass instances when called on a subclass
- sets $~ to MatchData of match and nil when there's none
- replaces \\1 with \1
- replaces \\1 with \1
- replaces \\\1 with \

String#sub with pattern and block
- returns a copy of self with the first occurrences of pattern replaced with the block's return value
- sets $~ for access from the block
- restores $~ after leaving the block
- sets $~ to MatchData of last match and nil when there's none for access from outside
- doesn't raise a RuntimeError if the string is modified while substituting
- doesn't interpolate special sequences like \1 for the block's return value
- converts the block's return value to a string using to_s
- taints the result if the original string or replacement is tainted

String#sub! with pattern, replacement
- modifies self in place and returns self
- taints self if replacement is tainted
- returns nil if no modifications were made
- raises a TypeError when self is frozen

String#sub! with pattern and block
- modifies self in place and returns self
- taints self if block's result is tainted
- returns nil if no modifications were made
- raises a RuntimeError if the string is modified while substituting
- raises a RuntimeError when self is frozen

String#gsub with pattern and replacement
- doesn't freak out when replacing ^
- returns a copy of self with all occurrences of pattern replaced with replacement
- ignores a block if supplied
- supports \G which matches at the beginning of the remaining (non-matched) string
- supports /i for ignoring case
- doesn't interpret regexp metacharacters if pattern is a string
- replaces \1 sequences with the regexp's corresponding capture
- treats \1 sequences without corresponding captures as empty strings
- replaces \& and \0 with the complete match
- replaces \` with everything before the current match
- replaces \' with everything after the current match
- replaces \+ with the last paren that actually matched
- treats \+ as an empty string if there was no captures
- maps \\ in replacement to \
- leaves unknown \x escapes in replacement untouched
- leaves \ at the end of replacement untouched
- taints the result if the original string or replacement is tainted
- tries to convert pattern to a string using to_str
- raises a TypeError when pattern can't be converted to a string
- tries to convert replacement to a string using to_str
- raises a TypeError when replacement can't be converted to a string
- returns subclass instances when called on a subclass
- sets $~ to MatchData of last match and nil when there's none

String#gsub with pattern and block
- returns a copy of self with all occurrences of pattern replaced with the block's return value
- sets $~ for access from the block
- restores $~ after leaving the block
- sets $~ to MatchData of last match and nil when there's none for access from outside
- raises a RuntimeError if the string is modified while substituting
- doesn't interpolate special sequences like \1 for the block's return value
- converts the block's return value to a string using to_s
- taints the result if the original string or replacement is tainted

String#gsub! with pattern and replacement
- modifies self in place and returns self
- taints self if replacement is tainted
- returns nil if no modifications were made
- raises a TypeError when self is frozen

String#gsub! with pattern and block
- modifies self in place and returns self
- taints self if block's result is tainted
- returns nil if no modifications were made
- raises a RuntimeError when self is frozen


Finished in 0.030081 seconds

2 files, 82 examples, 251 expectations, 0 failures, 0 errors


--
Magic is insufficiently advanced technology.