In bmewing/mgsub: Safe, Multiple, Simultaneous String Substitution

String Substitutions

Modifying existing strings via substitution is a common practice in programing. To this end, functions like gsub provide a method to accomplish this. Below is an example where "hey" is replaced with "ho" transforming a line from the Ramones into Santa Claus leaving on Christmas Eve.

s = "hey ho, let's go!"
gsub("hey", "ho", s)

Simultaneous Substitutions

gsub only supports one string of matching with one string of replacement. What this means is while you can match on multiple conditions, you can only provide one condition of replacement. Below we construct a regular expression which matches on "hey" or "ho" and replaces any such matches with "yo".

s = "hey ho, let's go!"
gsub("hey|ho", "yo", s)

If you wanted to replace "hey" with "get" and "ho" with "ready" you would need two steps.

s = "hey ho, let's go!"
s_new = gsub("hey", "get", s)
s_new = gsub("ho", "ready", s_new)
s_new

This sequential process however can result in undesired changes. If we want to swap where "hey" and "ho" are, we can see the process breaks down. Because each change happens in order, "hey" becomes "ho" and then every "ho" becomes "hey", undoing the first step.

s = "hey ho, let's go!"
s_new = gsub("hey", "ho", s)
s_new = gsub("ho", "hey", s_new)
s_new

mgsub

This is where the idea of mgsub comes in. mgsub is a safe, simultaneous string substitution function. We pass in a patterns to match as well as replacements and the replacements are applied simultaneously.

library(mgsub)
s = "hey ho, let's go!"
mgsub::mgsub(string = s, pattern = c("hey", "ho"), replacement = c("ho", "hey"))

Regular Expression Support

mgsub fully supports regular expressions as matching criteria as well as backreferences in the replacement. Note how the matching criteria ignores "dopachloride" for replacement but matches both "Dopazamine" and "dopastriamine" (all fake chemicals despite what the replace string claims!).

s = "Dopazamine is not the same as dopachloride or dopastriamine, yet is still fake."
pattern = c("[Dd]opa([^ ]*?mine)", "fake")
replacement = c("Meta\\1", "real")
mgsub::mgsub(s, pattern, replacement)

Furthermore, you can pass through any options from the gsub family. In the example below you can see fixed string matching

s = "All my life I chased $money$ and .power. - not love!"
pattern = c("$money$", ".power.", "love")
replacement = c("balloons", "dolphins", "success")
mgsub::mgsub(s, pattern, replacement, fixed = TRUE)

Safe Substitution

This is actually the most compelling feature of mgsub. Several packages implement a similar type function (also named mgsub) which do not employ safe substitution - qdap, bazar and textclean. Here is a quick overview of what is meant by safety: