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}})

Result

	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}})