Template:Str rep/doc

Template:Used in system Template:Cascade-protected template

This is a documentation subpage for Template:Str rep.
It may contain usage information, categories and other content that is not part of the original template page.

Uses Lua:

Module:String

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

Usage

{{Str rep|text...|find-string|replace-string}}
{{Str rep| 1=text... | 2=find-string | 3=replace-string }}

This is equivalent to {{#invoke:String|replace|source=text...|find-string|replace-string|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 3 replaces param 2's first occurrence in param 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: {{str rep|Dogs chase cats. Cats chase mice.|...}}
A parameter passed from a transcluding template: {{str rep|{{{5|}}}|...}} or {{str rep|{{{text|}}}|...}}
A file or template: {{str rep|{{Template:Str rep/doc/Dogs and cats}}|...}}
or anything else that resolves to a string.

Equal signs and pipes

Equal signs in parameter values passed as immediate text either need to be escaped as {{=}}, or you can leave them unescaped and use the built-in numeric names (|1=, |2=, and |3=) for the three unnamed positional parameters, as in the section usage at the top.

Pipe characters in immediate text should be escaped either as | or as {{!}}. See Help:Template. 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, leading and trailing white space is not removed, and can affect the results. See contrasting 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 built-in numeric names |1=, etc. These will not include any leading or trailing blanks in the parameter value; see example 3.

Examples

{{str rep|Dogs chase cats.|cats|balls}} ⟶ Dogs chase balls.
{{str rep|Dogs chase cats.|cats |balls }} ⟶ Dogs chase cats. — 8pxN leading and trailing blanks are significant; see Details
{{str rep|Dogs chase cats.|2=cats |3=balls }} ⟶ Dogs chase balls. — Y ... but not when named parameters are used
{{str rep|Dogs chase cats. Cats chase mice.|chase|love}} ⟶ Dogs love cats. Cats chase mice. — only first occurrence replaced
{{str rep|{{Str rep/doc/Dogs and cats}}|chase|love}} ⟶ Template:Str rep/doc/Dogs and cats — text can be entered by a template