Defines a pattern to be highlighted in the current window (a "match"). It will be highlighted with {group}. Returns an identification number (ID), which can be used to delete the match using matchdelete(). The ID is bound to the window. Matching is case sensitive and magic, unless case sensitivity or magicness are explicitly overridden in {pattern}. The 'magic', 'smartcase' and 'ignorecase' options are not used. The "Conceal" value is special, it causes the match to be concealed.

The optional {priority} argument assigns a priority to the match. A match with a high priority will have its highlighting overrule that of a match with a lower priority. A priority is specified as an integer (negative numbers are no exception). If the {priority} argument is not specified, the default priority is 10. The priority of 'hlsearch' is zero, hence all matches with a priority greater than zero will overrule it. Syntax highlighting (see 'syntax') is a separate mechanism, and regardless of the chosen priority a match will always overrule syntax highlighting.

The optional {id} argument allows the request for a specific match ID. If a specified ID is already taken, an error message will appear and the match will not be added. An ID is specified as a positive integer (zero excluded). IDs 1, 2 and 3 are reserved for :match, :2match and :3match, respectively. 3 is reserved for use by the matchparen plugin. If the {id} argument is not specified or -1, matchadd() automatically chooses a free ID, which is at least 1000.

The optional {dict} argument allows for further custom values. Currently this is used to specify a match specific conceal character that will be shown for hl-Conceal highlighted matches. The dict can have the following members:

    conceal     Special character to show instead of the
                match (only for `hl-Conceal` highlighted
                matches, see `:syn-cchar`)
    window      Instead of the current window use the
                window with this number or window ID.

The number of matches is not limited, as it is the case with the :match commands.

Returns -1 on error.

Example:

:highlight MyGroup ctermbg=green guibg=green
:let m = matchadd("MyGroup", "TODO")

Deletion of the pattern:

:call matchdelete(m)

A list of matches defined by matchadd() and :match are available from getmatches(). All matches can be deleted in one operation by clearmatches().

Can also be used as a method:

GetGroup()->matchadd('TODO')