# gsub

Definition: | include builtins\regex.e string res = gsub(sequence re, string target, rep)
Description: | Draft - this is a very simple routine that took very little time or effort (or thought) to write, and may change in later releases. Applies the regular expression re (in string or pre-compiled format) to target and returns rep with with all non-overlapping matches substituted with rep. re: a regular expression such as "a(b*)" or the result of applying regex_compile() to such a string. target: a string to be matched against the regular expression. rep: a replacement string, which may contain \0..\9 for the match fragments. Returns: target unaltered if re does not match, otherwise target with each match replaced by rep. If rep contains &, that will be substituted with the match as part of each substitution.
pwa/p2js: | Supported.
Example: |
    ?gsub("[A-Z]","abCDefG","*")        -- "ab**ef*"
    ?gsub("[A-Z]","abCDefGH","(&)")     -- "ab(C)(D)ef(G)(H)"
    ?gsub("[A-Z]+","abCDefGH","(&)")    -- "ab(CD)ef(GH)"
See Also: | gmatch
Technicalia | Prior to 1.0.2 a lone '&' was used and the only available option, equivalent to `\0`. Note that you will need to change eg "&" to either `\0` or "\\0", as "\0" is a length-1 string consisting of a lone null terminator. That version remains available as gsub0() should you need it, as a (hopefully temporary) quick fix, but is likely to be removed in a future release.