Editing Module:String/doc (section)

== replace (gsub) ==

This function allows one to replace a target string or pattern within another string. To Lua programmers: this function works internally by calling <code>[[mw:Extension:Scribunto/Lua_reference_manual#mw.ustring.gsub|mw.ustring.gsub]]</code>.

Usage:

: <code><nowiki>{{#invoke:</nowiki>String|replace|''source_str''|''pattern_string''|''replace_string''|''replacement_count''|''plain_flag''}}</code>

OR

: <code><nowiki>{{#invoke:</nowiki>String|replace|source= ''source_string'' |pattern= ''pattern_string'' |replace= ''replace_string'' |count= ''replacement_count'' |plain= ''plain_flag'' }}</code>

Parameters:

; source
: The string to search
; pattern
: The string or pattern to find within source
; replace
: The replacement text
; count
: The number of occurrences to replace; defaults to all
; plain
: Boolean flag indicating that pattern should be understood as plain text and not as a [[mw:Extension:Scribunto/Lua reference manual#Ustring patterns|Scribunto ustring pattern]] (a unicode-friendly [[w:Lua (programming language)|Lua]]-style [[w:regular expression|regular expression]]); defaults to true

Examples:

* <code><nowiki>"{{#invoke:String|replace| abc123def456 |123|XYZ}}"</nowiki></code> → "{{#invoke:String|replace| abc123def456 |123|XYZ}}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}"
* <code><nowiki>"{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}"</nowiki></code> → "{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}"
* <code><nowiki>{{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }}</nowiki></code> → {{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }}