{expr1} must be a List, String, Blob or Dictionary. When {expr1} is a List or Dictionary, replace each item in {expr1} with the result of evaluating {expr2}. For a Blob each byte is replaced. For a String, each character, including composing characters, is replaced. If the item type changes you may want to use mapnew() to create a new List or Dictionary. This is required when using Vim9 script.

{expr2} must be a String or Funcref.

If {expr2} is a String, inside {expr2} v:val has the value of the current item. For a Dictionary v:key has the key of the current item and for a List v:key has the index of the current item. For a Blob v:key has the index of the current byte. For a String v:key has the index of the current character. Example:

:call map(mylist, '"> " .. v:val .. " <"')

This puts "> " before and " <" after each item in "mylist".

Note that {expr2} is the result of an expression and is then used as an expression again. Often it is good to use a literal-string to avoid having to double backslashes. You still have to double ' quotes

If {expr2} is a Funcref it is called with two arguments: 1. The key or the index of the current item. 2. the value of the current item. The function must return the new value of the item. Example that changes each value by "key-value":

func KeyValue(key, val)
  return a:key .. '-' .. a:val
endfunc
call map(myDict, function('KeyValue'))

It is shorter when using a lambda:

call map(myDict, {key, val -> key .. '-' .. val})

If you do not use "val" you can leave it out:

call map(myDict, {key -> 'item: ' .. key})

If you do not use "key" you can use a short name:

call map(myDict, {_, val -> 'item: ' .. val})

The operation is done in-place for a List and Dictionary. If you want it to remain unmodified make a copy first:

:let tlist = map(copy(mylist), ' v:val .. "\t"')

Returns {expr1}, the List or Dictionary that was filtered, or a new Blob or String. When an error is encountered while evaluating {expr2} no further items in {expr1} are processed. When {expr2} is a Funcref errors inside a function are ignored, unless it was defined with the "abort" flag.

Can also be used as a method:

mylist->map(expr2)