strings.ReplacePairs

Use the strings.ReplacePairs function to perform multiple replacements on a string in a single operation. This approach is faster than sequentially calling the strings.Replace function.

Replacing strings sequentially requires multiple function calls and variable re-assignments.

{{ $s := "aabbcc" }}
{{ $s = strings.Replace $s "a" "x" }}
{{ $s = strings.Replace $s "b" "y" }}
{{ $s = strings.Replace $s "c" "z" }}
{{ $s }} → xxyyzz

Using strings.ReplacePairs produces the same result with fewer function calls in less time.

{{ "aabbcc" | strings.ReplacePairs "a" "x" "b" "y" "c" "z" }} → xxyyzz

Pairs may also be passed as a single slice:

{{ $pairs := slice
  "a" "x"
  "b" "y"
  "c" "z"
}}
{{ "aabbcc" | strings.ReplacePairs $pairs }} → xxyyzz

Examples

Observe that replacements are not applied recursively because the function scans the string only once.

{{ $pairs := slice
  "a" "b"
  "b" "c"
}}
{{ "a" | strings.ReplacePairs $pairs }} → b

Apply the first match when multiple old strings could match at the same position.

{{ $pairs := slice
  "app" "pear"
  "apple" "orange"
}}
{{ "apple" | strings.ReplacePairs $pairs }} → pearle

Delete specific strings by providing an empty string as the second value in a pair.

{{ $pairs := slice "b" "" }}
{{ "abc" | strings.ReplacePairs $pairs }} → ac

Edge cases

The table below outlines how the function handles various input scenarios.

Performance

While strings.Replace and strings.ReplacePairs can produce the same results, they handle data differently. Choosing the right one can noticeably reduce the time Hugo takes to build your project.

Single pass vs. multiple passes

When using strings.Replace, Hugo must scan the text from start to finish to find a match. If you chain three replacements together, Hugo performs three separate passes over the entire string.

The strings.ReplacePairs function is more efficient because it performs a single pass. Hugo looks through the text once and applies all replacements simultaneously.

Caching

Unlike strings.Replace, which performs a direct substitution, strings.ReplacePairs requires an initialization step to prepare the single-pass replacement logic. To make this efficient, Hugo manages this logic using a cache:

• During the initial call, Hugo initializes and stores the logic for that specific set of pairs.
• During subsequent calls, Hugo retrieves the stored logic, skipping the initialization step and reducing the duration of the call.

Choosing the right function

The efficiency of strings.ReplacePairs increases as the text gets longer or the number of pairs grows. Consider these scenarios when deciding which function to use:

• For a single replacement on a short string like a title, strings.Replace is efficient.
• For multiple replacements or long strings like a long-form article, strings.ReplacePairs is much faster.

For a document with about 8000 characters, which is roughly the length of a long-form article, strings.ReplacePairs outperforms five sequential strings.Replace calls during the initial call. Once cached, it is the faster choice for almost any situation with two or more pairs.