List.ReplaceMatchingItems

List

Replaces occurrences of specified values in a list with replacement values, given as a list of {old, new} pairs.

Syntax

List.ReplaceMatchingItems(list as list, replacements as list, optional equationCriteria as any) as list

Parameters

Name	Type	Required	Description
`list`	`list`	Yes	The source list in which replacements are made.
`replacements`	`list`	Yes	A list of two-element lists, each of the form {oldValue, newValue}, specifying what to replace and with what.
`equationCriteria`	`any`	No	An optional equation criteria to control how equality is determined when matching values.

Return Value

list — A new list with all specified values replaced.

Remarks

List.ReplaceMatchingItems performs multiple value replacements in a single pass through the list. The replacements parameter is a list of {old, new} pairs — for each item in the source list, if it matches an old value, it is replaced with the corresponding new value.

Multiple replacement pairs can be specified.
If an item matches more than one replacement pair, the first matching pair is applied.
Items that don't match any replacement pair are left unchanged.
All occurrences of each matching value are replaced.
Comparison is case-sensitive for text by default.

Examples

Example 1: Replace two values

List.ReplaceMatchingItems({1, 2, 3, 4, 5}, {{2, 20}, {4, 40}})

Output

	Result
1	{1, 20, 3, 40, 5}

Example 2: Recode categorical values

let
    Status = {"Active", "Inactive", "Pending", "Active", "Inactive"},
    Recoded = List.ReplaceMatchingItems(Status, {{"Active", "A"}, {"Inactive", "I"}, {"Pending", "P"}})
in
    Recoded

Applied Steps

The final output — the status list with all full labels replaced by abbreviated single-letter codes.

	Result
1	{A, I, P, A, I}

Example 3: Replace null values with a default

List.ReplaceMatchingItems({10, null, 30, null, 50}, {{null, 0}})