{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. With a legacy script lambda you don't get an error if it only accepts one argument, but with a Vim9 lambda you get "E1106: One argument too many", the number of arguments must match.

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)