Prototype: string_replace(string, match, replacement)

Return type: string

Description: In a given string, replaces a substring with another string.


  • string: string - Source string - in the range: .*
  • match: string - String to replace - in the range: .*
  • replacement: string - Replacement string - in the range: .*

Reads a string from left to right, replacing the occurences of the second argument with the third argument in order.

All characters in the string to replace in, the substring to match for and the replacement are read literally. This means that ., *, \ and similar characters will be read and replaced as they are. If you are looking for more advanced replace functionality, check out regex_replace().


bundle agent main
      # replace one occurence
      "replace_once" string => string_replace("This is a string", "string", "thing");
      # replace several occurences
      "replace_several" string => string_replace("This is a string", "i", "o");
      # replace nothing
      "replace_none" string => string_replace("This is a string", "boat", "no");
      # replace ambiguous order
      "replace_ambiguous" string => string_replace("aaaaa", "aaa", "b");

      # in order, the above...
      "replace_once = '$(replace_once)'";
      "replace_several = '$(replace_several)'";
      "replace_none = '$(replace_none)'";
      "replace_ambiguous = '$(replace_ambiguous)'";


R: replace_once = 'This is a thing'
R: replace_several = 'Thos os a strong'
R: replace_none = 'This is a string'
R: replace_ambiguous = 'baa'

History: Introduced in 3.12.1 (2018) as a simpler version of regex_replace()

See also: regex_replace()