View source for Template:Str rep/doc

{{used in system}}
{{cascade-protected template}}
{{Documentation subpage}}
{{lua|Module:String}}
<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->

Returns a modified copy of a given text, with the '''first''' occurrence of a find-string replaced with a replacement-string.

== Usage ==
{{plainlist|1=
*{{tlc|Str rep|''text...''|''find-string''|''replace-string''}}
*<!--NO tlc here--><code><nowiki>{{Str rep| 1=</nowiki>''<nowiki>text...</nowiki>''<nowiki> | 2=</nowiki>''<nowiki>find-string</nowiki>''<nowiki> | 3=</nowiki>''<nowiki>replace-string</nowiki>''<nowiki> }}</nowiki></code>
}}

This is equivalent to {{mlx|String|replace|3=source=''text...''|4=''find-string''|5=''replace-string''|6=1}}.

== Parameters ==

There are three positional (unnamed) parameters, all required:
# the initial text string subject to search and replacement
# the find-string to search for in the text
# the replacement string: param&nbsp;3 replaces param&nbsp;2's first occurrence in param&nbsp;1.

=== Details ===

The value of the text parameter may be anything that resolves to a string, such as:
* Immediate text entered directly into the parameter field: {{tlc|str rep|Dogs chase cats.  Cats chase mice.|...}}
* A parameter passed from a transcluding template: {{tlc|str rep|<nowiki>{{{5|}}}</nowiki>|...}} or {{tlc|str rep|<nowiki>{{{text|}}}</nowiki>|...}}
* A file or template: <code><nowiki>{{str rep|{{Template:Str rep/doc/Dogs and cats}}|...}}</nowiki></code>
* or anything else that resolves to a string.

=== Equal signs and pipes ===

Equal signs in parameter values passed as immediate text either [[Help:Template#Hints and workarounds|need to be escaped]] as <code><nowiki>{{=}}</nowiki></code>, or you can leave them unescaped and use the built-in numeric names ({{para|1}}, {{para|2}}, and {{para|3}}) for the three unnamed positional parameters, as in the section [[#Usage|usage]] at the top. 

Pipe characters in immediate text should be escaped either as <code>&amp;#124;</code> or as {{tl|!}}. See [[Help:Template#Hints and workarounds]]. Pipe characters in embedded items such as params or template invocations don't need to be escaped.

=== White space ===

Pay attention to the use of white space in the parameters; all white space is significant in positional parameters. In particular, [[Help:Template#Parameters|leading and trailing white space]] is not removed, and can affect the results. See contrasting [[#Examples|examples #1 and #2]] below.

If you like the readability of having convenience blanks before and after the parameters so they're not adjacent to the pipe characters, then use the [[Help:Template#Usage hints and workarounds|built-in numeric names]] {{para|1}}, etc. These will not include any leading or trailing blanks in the parameter value; see [[#Examples|example&nbsp;3]].

== Examples ==

# <code><nowiki>{{str rep|Dogs chase cats.|cats|balls}}</nowiki></code> ⟶ {{str rep|Dogs chase cats.|cats|balls}}
# <code><nowiki>{{str rep|Dogs chase cats.|cats |balls }}</nowiki></code> ⟶ {{str rep|Dogs chase cats.|cats |balls }} &nbsp; &nbsp; &mdash;''&nbsp;{{nay|8px}}&nbsp;leading and trailing blanks are significant; see [[#Details|Details]]''
# <code><nowiki>{{str rep|Dogs chase cats.|2=cats |3=balls }}</nowiki></code> ⟶ {{str rep|Dogs chase cats.|2=cats |3=balls }} &nbsp; &nbsp; &mdash;''&nbsp;{{aye|8px}}&nbsp;... but not when named parameters are used''
# <code><nowiki>{{str rep|Dogs chase cats.  Cats chase mice.|chase|love}}</nowiki></code> ⟶ {{str rep|Dogs chase cats.  Cats chase mice.|chase|love}} &nbsp; &nbsp; &mdash;&nbsp;''only first occurrence replaced''
# <code><nowiki>{{str rep|{{Str rep/doc/Dogs and cats}}|chase|love}}</nowiki></code> ⟶ {{str rep|{{Str rep/doc/Dogs and cats}}|chase|love}} &nbsp; &nbsp; &mdash;&nbsp;''text can be entered by a template''

== See also ==
* {{tl|Replace}} - to replace ''all'' occurrences (or a specific number of occurrences)
* {{tl|transliterate}}

{{string-handling templates|IRL}}

<includeonly>{{Sandbox other||
<!-- CATEGORIES AND INTERWIKIS LINKS HERE, THANKS -->
[[Category:String manipulation templates|Replace, {{PAGENAME}}]]

}}</includeonly>