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.