str replace for strings

Signature

> str replace {flags} (find) (replace) ...rest

Flags

• --all, -a: replace all occurrences of the pattern
• --no-expand, -n: do not expand capture groups (like $name) in the replacement string
• --regex, -r: match the pattern as a regular expression in the input, instead of a substring
• --multiline, -m: multi-line regex mode (implies --regex): ^ and $ match begin/end of line; equivalent to (?m)

Parameters

• find: The pattern to find.
• replace: The replacement string, or a closure that generates it.
• ...rest: For a data structure input, operate on strings at the given cell paths.

Input/output types:

Examples

Find and replace the first occurrence of a substring

> 'c:\some\cool\path' | str replace 'c:\some\cool' '~'
~\path

Find and replace all occurrences of a substring

> 'abc abc abc' | str replace --all 'b' 'z'
azc azc azc

Find and replace contents with capture group using regular expression

> 'my_library.rb' | str replace -r '(.+).rb' '$1.nu'
my_library.nu

Find and replace contents with capture group using regular expression, with escapes

> 'hello=world' | str replace -r '\$?(?<varname>.*)=(?<value>.*)' '$$$varname = $value'
$hello = world

Find and replace all occurrences of found string using regular expression

> 'abc abc abc' | str replace --all --regex 'b' 'z'
azc azc azc

Find and replace all occurrences of found string in table using regular expression

> [[ColA ColB ColC]; [abc abc ads]] | str replace --all --regex 'b' 'z' ColA ColC
╭───┬──────┬──────┬──────╮
│ # │ ColA │ ColB │ ColC │
├───┼──────┼──────┼──────┤
│ 0 │ azc  │ abc  │ ads  │
╰───┴──────┴──────┴──────╯

Find and replace all occurrences of found string in record using regular expression

> { KeyA: abc, KeyB: abc, KeyC: ads } | str replace --all --regex 'b' 'z' KeyA KeyC
╭──────┬─────╮
│ KeyA │ azc │
│ KeyB │ abc │
│ KeyC │ ads │
╰──────┴─────╯

Find and replace contents without using the replace parameter as a regular expression

> 'dogs_$1_cats' | str replace -r '\$1' '$2' -n
dogs_$2_cats

Use captures to manipulate the input text using regular expression

> "abc-def" | str replace -r "(.+)-(.+)" "${2}_${1}"
def_abc

Find and replace with fancy-regex using regular expression

> 'a successful b' | str replace -r '\b([sS])uc(?:cs|s?)e(ed(?:ed|ing|s?)|ss(?:es|ful(?:ly)?|i(?:ons?|ve(?:ly)?)|ors?)?)\b' '${1}ucce$2'
a successful b

Find and replace with fancy-regex using regular expression

> 'GHIKK-9+*' | str replace -r '[*[:xdigit:]+]' 'z'
GHIKK-z+*

Find and replace on individual lines using multiline regular expression

> "non-matching line\n123. one line\n124. another line\n" | str replace --all --multiline '^[0-9]+\. ' ''
non-matching line
one line
another line

Find and replace backslash escape sequences using a closure

> 'string: \"abc\" backslash: \\ newline:\nend' | str replace -a -r '\\(.)' {|char| if $char == "n" { "\n" } else { $char } }
string: "abc" backslash: \ newline:
end

Notes

The pattern to find can be a substring (default) or a regular expression (with --regex).

The replacement can be a a string, possibly containing references to numbered ($1 etc) or named capture groups ($name), or it can be closure that is invoked for each match. In the latter case, the closure is invoked with the entire match as its input and any capture groups as its argument. It must return a string that will be used as a replacement for the match.