/usr/share/doc/vim-doc/html/eval.html

<HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: eval</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: eval</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>

<HR>
<PRE>

*<A NAME="eval.txt"></A><B>eval.txt</B>*	For Vim version 7.4.  Last change: 2016 Mar 29


		  VIM REFERENCE MANUAL	  by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>



Expression evaluation			*<A NAME="expression"></A><B>expression</B>* *<A NAME="expr"></A><B>expr</B>* *<A NAME="E15"></A><B>E15</B>* *<A NAME="eval"></A><B>eval</B>*

Using expressions is introduced in chapter 41 of the user manual |<A HREF="usr_41.html">usr_41.txt</A>|.

Note: Expression evaluation can be disabled at compile time.  If this has been
done, the features in this document are not available.	See |<A HREF="various.html#+eval">+eval</A>| and
|<A HREF="#no-eval-feature">no-eval-feature</A>|.

1.  Variables			|<A HREF="#variables">variables</A>|
    1.1 Variable types
    1.2 Function references		|<A HREF="#Funcref">Funcref</A>|
    1.3 Lists				|<A HREF="#Lists">Lists</A>|
    1.4 Dictionaries			|<A HREF="#Dictionaries">Dictionaries</A>|
    1.5 More about variables		|<A HREF="#more-variables">more-variables</A>|
2.  Expression syntax		|<A HREF="#expression-syntax">expression-syntax</A>|
3.  Internal variable		|<A HREF="#internal-variables">internal-variables</A>|
4.  Builtin Functions		|<A HREF="#functions">functions</A>|
5.  Defining functions		|<A HREF="#user-functions">user-functions</A>|
6.  Curly braces names		|<A HREF="#curly-braces-names">curly-braces-names</A>|
7.  Commands			|<A HREF="#expression-commands">expression-commands</A>|
8.  Exception handling		|<A HREF="#exception-handling">exception-handling</A>|
9.  Examples			|<A HREF="#eval-examples">eval-examples</A>|
10. No <A HREF="various.html#+eval">+eval</A> feature		|<A HREF="#no-eval-feature">no-eval-feature</A>|
11. The sandbox			|<A HREF="#eval-sandbox">eval-sandbox</A>|
12. Textlock			|<A HREF="#textlock">textlock</A>|

{Vi does not have any of these commands}

==============================================================================

1. Variables						*<A NAME="variables"></A><B>variables</B>*

<B><FONT COLOR="PURPLE">1.1 Variable types </FONT></B>

							*<A NAME="E712"></A><B>E712</B>*
There are nine types of <A HREF="#variables">variables</A>:


<A HREF="#Number">Number</A>		A 32 or 64 bit signed number.  |<A HREF="#expr-number">expr-number</A>| *<A NAME="Number"></A><B>Number</B>*
		Examples:  -123  0x10  0177


<A HREF="#Float">Float</A>		A floating point number. |<A HREF="#floating-point-format">floating-point-format</A>| *<A NAME="Float"></A><B>Float</B>*
		{only when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		Examples: 123.456  1.15e-6  -1.1e3

<A HREF="#String">String</A>		A NUL terminated <A HREF="#string">string</A> of 8-bit unsigned characters (bytes).
		|<A HREF="#expr-string">expr-string</A>| Examples: &quot;ab\txx\&quot;--&quot;  'x-z''a,c'

List		An ordered sequence of items |<A HREF="#List">List</A>|.
		Example: [1, 2, ['a', 'b']]

<A HREF="#Dictionary">Dictionary</A>	An associative, unordered array: Each entry has a key and a
		value. |<A HREF="#Dictionary">Dictionary</A>|
		Example: {'blue': &quot;#0000ff&quot;, 'red': &quot;#ff0000&quot;}

Funcref		A reference to a function |<A HREF="#Funcref">Funcref</A>|.
		Example: function(&quot;strlen&quot;)


<A HREF="#Special">Special</A>		|<A HREF="#v:false">v:false</A>|, |<A HREF="#v:true">v:true</A>|, |<A HREF="#v:none">v:none</A>| and |<A HREF="#v:null">v:null</A>|.  *<A NAME="Special"></A><B>Special</B>*


<A HREF="#Job">Job</A>		Used for a job, see |<A HREF="#job_start()">job_start()</A>|. *<A NAME="Job"></A><B>Job</B>*


<A HREF="#Channel">Channel</A>		Used for a <A HREF="channel.html#channel">channel</A>, see |<A HREF="#ch_open()">ch_open()</A>|. *<A NAME="Channel"></A><B>Channel</B>*

The <A HREF="#Number">Number</A> and <A HREF="#String">String</A> types are converted automatically, depending on how they
are used.

Conversion from a <A HREF="#Number">Number</A> to a <A HREF="#String">String</A> is by making the ASCII representation of
the <A HREF="#Number">Number</A>.  Examples:
<B><FONT COLOR="PURPLE">	Number 123	--&gt;	String "123" </FONT></B>
<B><FONT COLOR="PURPLE">	Number 0	--&gt;	String "0" </FONT></B>
<B><FONT COLOR="PURPLE">	Number -1	--&gt;	String "-1" </FONT></B>

							*<A NAME="octal"></A><B>octal</B>*
Conversion from a <A HREF="#String">String</A> to a <A HREF="#Number">Number</A> is done by converting the first digits to
a number.  Hexadecimal &quot;0xf9&quot;, Octal &quot;017&quot;, and Binary &quot;0b10&quot; numbers are
recognized.  If the <A HREF="#String">String</A> doesn't start with digits, the result is zero.
Examples:
<B><FONT COLOR="PURPLE">	String "456"	--&gt;	Number 456 </FONT></B>
<B><FONT COLOR="PURPLE">	String "6bar"	--&gt;	Number 6 </FONT></B>
<B><FONT COLOR="PURPLE">	String "foo"	--&gt;	Number 0 </FONT></B>
<B><FONT COLOR="PURPLE">	String "0xf1"	--&gt;	Number 241 </FONT></B>
<B><FONT COLOR="PURPLE">	String "0100"	--&gt;	Number 64 </FONT></B>
<B><FONT COLOR="PURPLE">	String "0b101"	--&gt;	Number 5 </FONT></B>
<B><FONT COLOR="PURPLE">	String "-8"	--&gt;	Number -8 </FONT></B>
<B><FONT COLOR="PURPLE">	String "+8"	--&gt;	Number 0 </FONT></B>

To force conversion from <A HREF="#String">String</A> to <A HREF="#Number">Number</A>, add zero to <A HREF="motion.html#it">it</A>:
<B>	:echo "0100" + 0</B>
<B><FONT COLOR="PURPLE"> 	64 </FONT></B>

To avoid a leading zero to cause <A HREF="#octal">octal</A> conversion, or for using a different
base, use |<A HREF="#str2nr()">str2nr()</A>|.

For <A HREF="options.html#boolean">boolean</A> operators Numbers are used.  Zero is FALSE, non-zero is TRUE.

Note that in the command
<B>	:if "foo"</B>
&quot;foo&quot; is converted to 0, which means FALSE.  To test for a non-empty <A HREF="#string">string</A>,
use <A HREF="#empty()">empty()</A>:
<B>	:if !empty("foo")</B>
 

		*<A NAME="E745"></A><B>E745</B>* *<A NAME="E728"></A><B>E728</B>* *<A NAME="E703"></A><B>E703</B>* *<A NAME="E729"></A><B>E729</B>* *<A NAME="E730"></A><B>E730</B>* *<A NAME="E731"></A><B>E731</B>* *<A NAME="E908"></A><B>E908</B>* *<A NAME="E910"></A><B>E910</B>* *<A NAME="E913"></A><B>E913</B>*
<A HREF="#List">List</A>, <A HREF="#Dictionary">Dictionary</A>, <A HREF="#Funcref">Funcref</A> and <A HREF="#Job">Job</A> types are not automatically converted.


							*<A NAME="E805"></A><B>E805</B>* *<A NAME="E806"></A><B>E806</B>* *<A NAME="E808"></A><B>E808</B>*
When mixing <A HREF="#Number">Number</A> and <A HREF="#Float">Float</A> the <A HREF="#Number">Number</A> is converted to <A HREF="#Float">Float</A>.	Otherwise
there is no automatic conversion of <A HREF="#Float">Float</A>.  You can use <A HREF="#str2float()">str2float()</A> for <A HREF="#String">String</A>
to <A HREF="#Float">Float</A>, <A HREF="#printf()">printf()</A> for <A HREF="#Float">Float</A> to <A HREF="#String">String</A> and <A HREF="#float2nr()">float2nr()</A> for <A HREF="#Float">Float</A> to <A HREF="#Number">Number</A>.


			*<A NAME="E891"></A><B>E891</B>* *<A NAME="E892"></A><B>E892</B>* *<A NAME="E893"></A><B>E893</B>* *<A NAME="E894"></A><B>E894</B>* *<A NAME="E907"></A><B>E907</B>* *<A NAME="E911"></A><B>E911</B>* *<A NAME="E914"></A><B>E914</B>*
When expecting a <A HREF="#Float">Float</A> a <A HREF="#Number">Number</A> can also be used, but nothing else.


						*<A NAME="no-type-checking"></A><B>no-type-checking</B>*
You will not get an error if you try to change the type of a variable.


<B><FONT COLOR="PURPLE">1.2 Function references </FONT></B>

					*<A NAME="Funcref"></A><B>Funcref</B>* *<A NAME="E695"></A><B>E695</B>* *<A NAME="E718"></A><B>E718</B>*
A <A HREF="#Funcref">Funcref</A> variable is obtained with the |<A HREF="#function()">function()</A>| function.	It can be used
in an <A HREF="#expression">expression</A> in the place of a function name, before the parenthesis
around the arguments, to invoke the function <A HREF="motion.html#it">it</A> refers to.  Example:

<B>	:let Fn = function("MyFunc")</B>
<B>	:echo Fn()</B>

 							*<A NAME="E704"></A><B>E704</B>* *<A NAME="E705"></A><B>E705</B>* *<A NAME="E707"></A><B>E707</B>*
A <A HREF="#Funcref">Funcref</A> variable must start with a capital, &quot;s:&quot;, &quot;<A HREF="#w:">w:</A>&quot;, &quot;<A HREF="#t:">t:</A>&quot; or &quot;<A HREF="#b:">b:</A>&quot;.  You
can use &quot;<A HREF="#g:">g:</A>&quot; but the following name must still start with a capital.  You
cannot have both a <A HREF="#Funcref">Funcref</A> variable and a function with the same name.

A special <A HREF="change.html#case">case</A> is defining a function and directly assigning its <A HREF="#Funcref">Funcref</A> to a
<A HREF="#Dictionary">Dictionary</A> entry.  Example:
<B>	:function dict.init() dict</B>
<B>	:   let self.val = 0</B>
<B>	:endfunction</B>

The key of the <A HREF="#Dictionary">Dictionary</A> can start with a lower <A HREF="change.html#case">case</A> <A HREF="print.html#letter">letter</A>.  The actual
function name is not used here.  Also see |<A HREF="#numbered-function">numbered-function</A>|.

A <A HREF="#Funcref">Funcref</A> can also be used with the |<A HREF="#:call">:call</A>| command:
<B>	:call Fn()</B>
<B>	:call dict.init()</B>

The name of the referenced function can be obtained with |<A HREF="#string()">string()</A>|.
<B>	:let func = string(Fn)</B>

You can use |<A HREF="#call()">call()</A>| to invoke a <A HREF="#Funcref">Funcref</A> and use a <A HREF="#list">list</A> variable for the
arguments:
<B>	:let r = call(Fn, mylist)</B>


<B><FONT COLOR="PURPLE">1.3 Lists </FONT></B>

						*<A NAME="list"></A><B>list</B>* *<A NAME="List"></A><B>List</B>* *<A NAME="Lists"></A><B>Lists</B>* *<A NAME="E686"></A><B>E686</B>*
A <A HREF="#List">List</A> is an ordered sequence of items.  An item can be of any type.  Items
can be accessed by their index number.	Items can be added and removed at any
position in the sequence.


<B><FONT COLOR="PURPLE">List creation </FONT></B>

							*<A NAME="E696"></A><B>E696</B>* *<A NAME="E697"></A><B>E697</B>*
A <A HREF="#List">List</A> is created with a comma separated <A HREF="#list">list</A> of items in square brackets.
Examples:
<B>	:let mylist = [1, two, 3, "four"]</B>
<B>	:let emptylist = []</B>

An item can be any <A HREF="#expression">expression</A>.	Using a <A HREF="#List">List</A> for an item creates a
<A HREF="#List">List</A> of <A HREF="#Lists">Lists</A>:
<B>	:let nestlist = [[11, 12], [21, 22], [31, 32]]</B>

An extra comma after the last item is ignored.


<B><FONT COLOR="PURPLE">List index </FONT></B>

							*<A NAME="list-index"></A><B>list-index</B>* *<A NAME="E684"></A><B>E684</B>*
An item in the <A HREF="#List">List</A> can be accessed by putting the index in square brackets
after the <A HREF="#List">List</A>.  Indexes are zero-based, thus the first item has index zero.
<B>	:let item = mylist[0]		" get the first item: 1</B>
<B>	:let item = mylist[2]		" get the third item: 3</B>

When the resulting item is a <A HREF="#list">list</A> this can be repeated:
<B>	:let item = nestlist[0][1]	" get the first list, second item: 12</B>
 
A negative index is counted from the end.  Index -1 refers to the last item in
the <A HREF="#List">List</A>, -2 to the last but one item, etc.
<B>	:let last = mylist[-1]		" get the last item: "four"</B>

To avoid an error for an invalid index use the |<A HREF="#get()">get()</A>| function.  When an item
is not available <A HREF="motion.html#it">it</A> returns zero or the default value you specify:
<B>	:echo get(mylist, idx)</B>
<B>	:echo get(mylist, idx, "NONE")</B>


<B><FONT COLOR="PURPLE">List concatenation </FONT></B>

Two lists can be concatenated with the &quot;<A HREF="motion.html#+">+</A>&quot; <A HREF="motion.html#operator">operator</A>:
<B>	:let longlist = mylist + [5, 6]</B>
<B>	:let mylist += [7, 8]</B>

To prepend or append an item turn the item into a <A HREF="#list">list</A> by putting <A HREF="motion.html#[]">[]</A> around
<A HREF="motion.html#it">it</A>.  To change a list in-place see |<A HREF="#list-modification">list-modification</A>| below.


<B><FONT COLOR="PURPLE">Sublist </FONT></B>

A part of the <A HREF="#List">List</A> can be obtained by specifying the first and last index,
separated by a colon in square brackets:
<B>	:let shortlist = mylist[2:-1]	" get List [3, "four"]</B>

Omitting the first index is similar to zero.  Omitting the last index is
similar to -1.
<B>	:let endlist = mylist[2:]	" from item 2 to the end: [3, "four"]</B>
<B>	:let shortlist = mylist[2:2]	" List with one item: [3]</B>
<B>	:let otherlist = mylist[:]	" make a copy of the List</B>

If the first index is beyond the last item of the <A HREF="#List">List</A> or the second item is
before the first item, the result is an empty <A HREF="#list">list</A>.  There is no error
message.

If the second index is equal to or greater than the length of the <A HREF="#list">list</A> the
length minus one is used:
<B>	:let mylist = [0, 1, 2, 3]</B>
<B>	:echo mylist[2:8]		" result: [2, 3]</B>

NOTE: mylist[s:e] means using the variable &quot;s:e&quot; <A HREF="motion.html#as">as</A> index.  Watch out for
using a single <A HREF="print.html#letter">letter</A> variable before the &quot;<A HREF="cmdline.html#:">:</A>&quot;.	<A HREF="insert.html#Insert">Insert</A> a space when needed:
mylist[s : e].


<B><FONT COLOR="PURPLE">List identity </FONT></B>

							*<A NAME="list-identity"></A><B>list-identity</B>*
When variable &quot;aa&quot; is a <A HREF="#list">list</A> and you assign <A HREF="motion.html#it">it</A> to another variable &quot;bb&quot;, both
<A HREF="#variables">variables</A> refer to the same <A HREF="#list">list</A>.  Thus <A HREF="change.html#changing">changing</A> the <A HREF="#list">list</A> &quot;aa&quot; will also
change &quot;bb&quot;:
<B>	:let aa = [1, 2, 3]</B>
<B>	:let bb = aa</B>
<B>	:call add(aa, 4)</B>
<B>	:echo bb</B>
 	[1, 2, 3, 4]

Making a copy of a <A HREF="#list">list</A> is done with the |<A HREF="#copy()">copy()</A>| function.  Using [:] also
works, <A HREF="motion.html#as">as</A> explained above.  This creates a shallow copy of the <A HREF="#list">list</A>: Changing
a <A HREF="#list">list</A> item in the <A HREF="#list">list</A> will also change the item in the copied <A HREF="#list">list</A>:
<B>	:let aa = [[1, 'a'], 2, 3]</B>
<B>	:let bb = copy(aa)</B>
<B>	:call add(aa, 4)</B>
<B>	:let aa[0][1] = 'aaa'</B>
<B>	:echo aa</B>
 	[[1, aaa], 2, 3, 4]
<B>	:echo bb</B>
 	[[1, aaa], 2, 3]

To make a completely independent <A HREF="#list">list</A> use |<A HREF="#deepcopy()">deepcopy()</A>|.  This also makes a
copy of the values in the <A HREF="#list">list</A>, recursively.  Up to a hundred levels deep.

The <A HREF="motion.html#operator">operator</A> &quot;is&quot; can be used to check if two <A HREF="#variables">variables</A> refer to the same
<A HREF="#List">List</A>.  &quot;isnot&quot; does the opposite.  In contrast &quot;<A HREF="change.html#==">==</A>&quot; compares if two lists have
the same value.
<B>	:let alist = [1, 2, 3]</B>
<B>	:let blist = [1, 2, 3]</B>
<B>	:echo alist is blist</B>
 	0
<B>	:echo alist == blist</B>
 	1

Note about comparing lists: Two lists are considered equal if they have the
same length and all items compare equal, <A HREF="motion.html#as">as</A> with using &quot;<A HREF="change.html#==">==</A>&quot;.  There is one
exception: When comparing a number with a <A HREF="#string">string</A> they are considered
different.  There is no automatic type conversion, <A HREF="motion.html#as">as</A> with using &quot;<A HREF="change.html#==">==</A>&quot; on
<A HREF="#variables">variables</A>.  Example:
<B>	echo 4 == "4"</B>
 	1
<B>	echo [4] == ["4"]</B>
 	0

Thus comparing <A HREF="#Lists">Lists</A> is more strict than comparing numbers and strings.  You
can compare simple values this way too by putting them in a <A HREF="#list">list</A>:

<B>	:let a = 5</B>
<B>	:let b = "5"</B>
<B>	:echo a == b</B>
 	1
<B>	:echo [a] == [b]</B>
 	0


<B><FONT COLOR="PURPLE">List unpack </FONT></B>

To unpack the items in a <A HREF="#list">list</A> to individual <A HREF="#variables">variables</A>, put the <A HREF="#variables">variables</A> in
square brackets, like <A HREF="#list">list</A> items:
<B>	:let [var1, var2] = mylist</B>

When the number of <A HREF="#variables">variables</A> does not match the number of items in the <A HREF="#list">list</A>
this produces an error.  To handle any extra items from the <A HREF="#list">list</A> append &quot;<A HREF="motion.html#;">;</A>&quot;
and a variable name:
<B>	:let [var1, var2; rest] = mylist</B>

This works like:
<B>	:let var1 = mylist[0]</B>
<B>	:let var2 = mylist[1]</B>
<B>	:let rest = mylist[2:]</B>

Except that there is no error if there are only two items.  &quot;rest&quot; will be an
empty <A HREF="#list">list</A> then.


<B><FONT COLOR="PURPLE">List modification </FONT></B>

							*<A NAME="list-modification"></A><B>list-modification</B>*
To change a specific item of a <A HREF="#list">list</A> use |<A HREF="#:let">:let</A>| this way:
<B>	:let list[4] = "four"</B>
<B>	:let listlist[0][3] = item</B>

To change part of a <A HREF="#list">list</A> you can specify the first and last item to be
modified.  The value must at least have the number of items in the range:
<B>	:let list[3:5] = [3, 4, 5]</B>

Adding and removing items from a <A HREF="#list">list</A> is done with <A HREF="#functions">functions</A>.  Here are a few
examples:
<B>	:call insert(list, 'a')		" prepend item 'a'</B>
<B>	:call insert(list, 'a', 3)	" insert item 'a' before list[3]</B>
<B>	:call add(list, "new")		" append String item</B>
<B>	:call add(list, [1, 2])		" append a List as one new item</B>
<B>	:call extend(list, [1, 2])	" extend the list with two more items</B>
<B>	:let i = remove(list, 3)	" remove item 3</B>
<B>	:unlet list[3]			" idem</B>
<B>	:let l = remove(list, 3, -1)	" remove items 3 to last item</B>
<B>	:unlet list[3 : ]		" idem</B>
<B>	:call filter(list, 'v:val !~ "x"')  " remove items with an 'x'</B>

Changing the order of items in a <A HREF="#list">list</A>:
<B>	:call sort(list)		" sort a list alphabetically</B>
<B>	:call reverse(list)		" reverse the order of items</B>
<B>	:call uniq(sort(list))		" sort and remove duplicates</B>


<B><FONT COLOR="PURPLE">For loop </FONT></B>

The |<A HREF="#:for">:for</A>| loop executes commands for each item in a <A HREF="#list">list</A>.  A variable is set
to each item in the <A HREF="#list">list</A> in sequence.  Example:
<B>	:for item in mylist</B>
<B>	:   call Doit(item)</B>
<B>	:endfor</B>

This works like:
<B>	:let index = 0</B>
<B>	:while index &lt; len(mylist)</B>
<B>	:   let item = mylist[index]</B>
<B>	:   :call Doit(item)</B>
<B>	:   let index = index + 1</B>
<B>	:endwhile</B>

If all you want to <A HREF="diff.html#do">do</A> is modify each item in the <A HREF="#list">list</A> then the |<A HREF="#map()">map()</A>|
function will be a simpler method than a for loop.

Just like the |<A HREF="#:let">:let</A>| command, |<A HREF="#:for">:for</A>| also accepts a <A HREF="#list">list</A> of <A HREF="#variables">variables</A>.	This
requires the argument to be a <A HREF="#list">list</A> of lists.
<B>	:for [lnum, col] in [[1, 3], [2, 8], [3, 0]]</B>
<B>	:   call Doit(lnum, col)</B>
<B>	:endfor</B>

This works like a |<A HREF="#:let">:let</A>| command is done for each <A HREF="#list">list</A> item.  Again, the types
must remain the same to avoid an error.

It is also possible to put remaining items in a <A HREF="#List">List</A> variable:
<B>	:for [i, j; rest] in listlist</B>
<B>	:   call Doit(i, j)</B>
<B>	:   if !empty(rest)</B>
<B>	:      echo "remainder: " . string(rest)</B>
<B>	:   endif</B>
<B>	:endfor</B>


<B><FONT COLOR="PURPLE">List functions </FONT></B>

						*<A NAME="E714"></A><B>E714</B>*
Functions that are useful with a <A HREF="#List">List</A>:
<B>	:let r = call(funcname, list)	" call a function with an argument list</B>
<B>	:if empty(list)			" check if list is empty</B>
<B>	:let l = len(list)		" number of items in list</B>
<B>	:let big = max(list)		" maximum value in list</B>
<B>	:let small = min(list)		" minimum value in list</B>
<B>	:let xs = count(list, 'x')	" count nr of times 'x' appears in list</B>
<B>	:let i = index(list, 'x')	" index of first 'x' in list</B>
<B>	:let lines = getline(1, 10)	" get ten text lines from buffer</B>
<B>	:call append('$', lines)	" append text lines in buffer</B>
<B>	:let list = split("a b c")	" create list from items in a string</B>
<B>	:let string = join(list, ', ')	" create string from list items</B>
<B>	:let s = string(list)		" String representation of list</B>
<B>	:call map(list, '"&gt;&gt; " . v:val')  " prepend "&gt;&gt; " to each item</B>

Don't forget that a combination of features can make things simple.  For
example, to add up all the numbers in a <A HREF="#list">list</A>:
<B>	:exe 'let sum = ' . join(nrlist, '+')</B>


<B><FONT COLOR="PURPLE">1.4 Dictionaries </FONT></B>

					*<A NAME="dict"></A><B>dict</B>* *<A NAME="Dictionaries"></A><B>Dictionaries</B>* *<A NAME="Dictionary"></A><B>Dictionary</B>*
A <A HREF="#Dictionary">Dictionary</A> is an associative array: Each entry has a key and a value.  The
entry can be located with the key.  The entries are stored without a specific
ordering.


<B><FONT COLOR="PURPLE">Dictionary creation </FONT></B>

						*<A NAME="E720"></A><B>E720</B>* *<A NAME="E721"></A><B>E721</B>* *<A NAME="E722"></A><B>E722</B>* *<A NAME="E723"></A><B>E723</B>*
A <A HREF="#Dictionary">Dictionary</A> is created with a comma separated <A HREF="#list">list</A> of entries in curly
braces.  Each entry has a key and a value, separated by a colon.  Each key can
only appear once.  Examples:
<B>	:let mydict = {1: 'one', 2: 'two', 3: 'three'}</B>
<B>	:let emptydict = {}</B>

 							*<A NAME="E713"></A><B>E713</B>* *<A NAME="E716"></A><B>E716</B>* *<A NAME="E717"></A><B>E717</B>*
A key is always a <A HREF="#String">String</A>.  You can use a <A HREF="#Number">Number</A>, <A HREF="motion.html#it">it</A> will be converted to a
<A HREF="#String">String</A> automatically.  Thus the <A HREF="#String">String</A> '4' and the number 4 will find the same
entry.	Note that the <A HREF="#String">String</A> '04' and the <A HREF="#Number">Number</A> 04 are different, since the
<A HREF="#Number">Number</A> will be converted to the <A HREF="#String">String</A> '4'.

A value can be any <A HREF="#expression">expression</A>.	Using a <A HREF="#Dictionary">Dictionary</A> for a value creates a
nested <A HREF="#Dictionary">Dictionary</A>:
<B>	:let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}</B>

An extra comma after the last entry is ignored.


<B><FONT COLOR="PURPLE">Accessing entries </FONT></B>

The normal way to access an entry is by putting the key in square brackets:
<B>	:let val = mydict["one"]</B>
<B>	:let mydict["four"] = 4</B>

You can add new entries to an existing <A HREF="#Dictionary">Dictionary</A> this way, unlike <A HREF="#Lists">Lists</A>.

For keys that consist entirely of letters, digits and underscore the following
form can be used YXXYexpr-entry|:
<B>	:let val = mydict.one</B>
<B>	:let mydict.four = 4</B>

Since an entry can be any type, also a <A HREF="#List">List</A> and a <A HREF="#Dictionary">Dictionary</A>, the indexing and
key lookup can be repeated:
<B>	:echo dict.key[idx].key</B>


<B><FONT COLOR="PURPLE">Dictionary to List conversion </FONT></B>

You may want to loop over the entries in a dictionary.	For this you need to
turn the <A HREF="#Dictionary">Dictionary</A> into a <A HREF="#List">List</A> and pass <A HREF="motion.html#it">it</A> to |<A HREF="#:for">:for</A>|.

Most often you want to loop over the keys, using the |<A HREF="#keys()">keys()</A>| function:
<B>	:for key in keys(mydict)</B>
<B>	:   echo key . ': ' . mydict[key]</B>
<B>	:endfor</B>

The <A HREF="#List">List</A> of keys is unsorted.  You may want to sort them first:
<B>	:for key in sort(keys(mydict))</B>

To loop over the values use the |<A HREF="#values()">values()</A>| function: 
<B>	:for v in values(mydict)</B>
<B>	:   echo "value: " . v</B>
<B>	:endfor</B>

If you want both the key and the value use the |<A HREF="#items()">items()</A>| function.  It returns
a <A HREF="#List">List</A> in which each item is a	<A HREF="#List">List</A> with two items, the key and the value:
<B>	:for [key, value] in items(mydict)</B>
<B>	:   echo key . ': ' . value</B>
<B>	:endfor</B>


<B><FONT COLOR="PURPLE">Dictionary identity </FONT></B>

							*<A NAME="dict-identity"></A><B>dict-identity</B>*
Just like <A HREF="#Lists">Lists</A> you need to use |<A HREF="#copy()">copy()</A>| and |<A HREF="#deepcopy()">deepcopy()</A>| to make a copy of a
<A HREF="#Dictionary">Dictionary</A>.  Otherwise, assignment results in referring to the same
<A HREF="#Dictionary">Dictionary</A>:
<B>	:let onedict = {'a': 1, 'b': 2}</B>
<B>	:let adict = onedict</B>
<B>	:let adict['a'] = 11</B>
<B>	:echo onedict['a']</B>
<B>	11</B>

Two <A HREF="#Dictionaries">Dictionaries</A> compare equal if all the key-value pairs compare equal.  For
more info see |<A HREF="#list-identity">list-identity</A>|.


<B><FONT COLOR="PURPLE">Dictionary modification </FONT></B>

							*<A NAME="dict-modification"></A><B>dict-modification</B>*
To change an already existing entry of a <A HREF="#Dictionary">Dictionary</A>, or to add a new entry,
use |<A HREF="#:let">:let</A>| this way:
<B>	:let dict[4] = "four"</B>
<B>	:let dict['one'] = item</B>

Removing an entry from a <A HREF="#Dictionary">Dictionary</A> is done with |<A HREF="#remove()">remove()</A>| or |<A HREF="#:unlet">:unlet</A>|.
Three ways to remove the entry with key &quot;aaa&quot; from <A HREF="#dict">dict</A>:
<B>	:let i = remove(dict, 'aaa')</B>
<B>	:unlet dict.aaa</B>
<B>	:unlet dict['aaa']</B>

Merging a <A HREF="#Dictionary">Dictionary</A> with another is done with YXXYextend()|:
<B>	:call extend(adict, bdict)</B>
This extends adict with all entries from bdict.  Duplicate keys cause entries
in adict to be overwritten.  An optional third argument can change this.
Note that the order of entries in a <A HREF="#Dictionary">Dictionary</A> is irrelevant, thus don't
expect &quot;<A HREF="#:echo">:echo</A> adict&quot; to show the items from bdict after the older entries in
adict.

Weeding out entries from a <A HREF="#Dictionary">Dictionary</A> can be done with YXXYfilter()|:
<B>	:call filter(dict, 'v:val =~ "x"')</B>
This removes all entries from &quot;<A HREF="#dict">dict</A>&quot; with a value not matching '<A HREF="change.html#x">x</A>'.


<B><FONT COLOR="PURPLE">Dictionary function </FONT></B>

				*<A NAME="Dictionary-function"></A><B>Dictionary-function</B>* *<A NAME="self"></A><B>self</B>* *<A NAME="E725"></A><B>E725</B>* *<A NAME="E862"></A><B>E862</B>*
When a function is defined with the &quot;<A HREF="#dict">dict</A>&quot; attribute <A HREF="motion.html#it">it</A> can be used in a
special way with a dictionary.	Example:
<B>	:function Mylen() dict</B>
<B>	:   return len(self.data)</B>
<B>	:endfunction</B>
<B>	:let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}</B>
<B>	:echo mydict.len()</B>

This is like a method in object oriented programming.  The entry in the
<A HREF="#Dictionary">Dictionary</A> is a |<A HREF="#Funcref">Funcref</A>|.  The local variable &quot;<A HREF="#self">self</A>&quot; refers to the dictionary
the function was invoked from.

It is also possible to add a function without the &quot;<A HREF="#dict">dict</A>&quot; attribute <A HREF="motion.html#as">as</A> a
<A HREF="#Funcref">Funcref</A> to a <A HREF="#Dictionary">Dictionary</A>, but the &quot;<A HREF="#self">self</A>&quot; variable is not available then.


				*<A NAME="numbered-function"></A><B>numbered-function</B>* *<A NAME="anonymous-function"></A><B>anonymous-function</B>*
To avoid the extra name for the function <A HREF="motion.html#it">it</A> can be defined and directly
assigned to a <A HREF="#Dictionary">Dictionary</A> in this way:
<B>	:let mydict = {'data': [0, 1, 2, 3]}</B>
<B>	:function mydict.len()</B>
<B>	:   return len(self.data)</B>
<B>	:endfunction</B>
<B>	:echo mydict.len()</B>

The function will then get a number and the value of dict.len is a |<A HREF="#Funcref">Funcref</A>|
that references this function.	The function can only be used through a
|<A HREF="#Funcref">Funcref</A>|.  It will automatically be deleted when there is no |<A HREF="#Funcref">Funcref</A>|
remaining that refers to <A HREF="motion.html#it">it</A>.

It is not necessary to use the &quot;<A HREF="#dict">dict</A>&quot; attribute for a numbered function.

If you get an error for a numbered function, you can find out what <A HREF="motion.html#it">it</A> is with
a trick.  Assuming the function is <A HREF="usr_42.html#42">42</A>, the command is:
<B>	:function {42}</B>


<B><FONT COLOR="PURPLE">Functions for Dictionaries </FONT></B>

							*<A NAME="E715"></A><B>E715</B>*
Functions that can be used with a <A HREF="#Dictionary">Dictionary</A>:
<B>	:if has_key(dict, 'foo')	" TRUE if dict has entry with key "foo"</B>
<B>	:if empty(dict)			" TRUE if dict is empty</B>
<B>	:let l = len(dict)		" number of items in dict</B>
<B>	:let big = max(dict)		" maximum value in dict</B>
<B>	:let small = min(dict)		" minimum value in dict</B>
<B>	:let xs = count(dict, 'x')	" count nr of times 'x' appears in dict</B>
<B>	:let s = string(dict)		" String representation of dict</B>
<B>	:call map(dict, '"&gt;&gt; " . v:val')  " prepend "&gt;&gt; " to each item</B>


<B><FONT COLOR="PURPLE">1.5 More about variables </FONT></B>

							*<A NAME="more-variables"></A><B>more-variables</B>*
If you need to know the type of a variable or <A HREF="#expression">expression</A>, use the |<A HREF="#type()">type()</A>|
function.

When the '<A HREF="change.html#!">!</A>' flag is included in the <A HREF="options.html#'viminfo'">'viminfo'</A> option, global <A HREF="#variables">variables</A> that
start with an <A HREF="change.html#uppercase">uppercase</A> <A HREF="print.html#letter">letter</A>, and don't contain a <A HREF="change.html#lowercase">lowercase</A> <A HREF="print.html#letter">letter</A>, are
stored in the viminfo file |<A HREF="starting.html#viminfo-file">viminfo-file</A>|.

When the <A HREF="options.html#'sessionoptions'">'sessionoptions'</A> option contains &quot;global&quot;, global <A HREF="#variables">variables</A> that
start with an <A HREF="change.html#uppercase">uppercase</A> <A HREF="print.html#letter">letter</A> and contain at least one <A HREF="change.html#lowercase">lowercase</A> <A HREF="print.html#letter">letter</A> are
stored in the session file |<A HREF="starting.html#session-file">session-file</A>|.

<B><FONT COLOR="PURPLE">variable name		can be stored where </FONT></B>
my_var_6		not
My_Var_6		session file
MY_VAR_6		<A HREF="starting.html#viminfo">viminfo</A> file


It's possible to form a variable name with curly braces, see
|<A HREF="#curly-braces-names">curly-braces-names</A>|.

==============================================================================

2. Expression <A HREF="syntax.html#syntax">syntax</A>					*<A NAME="expression-syntax"></A><B>expression-syntax</B>*

Expression <A HREF="syntax.html#syntax">syntax</A> summary, from least to most significant:

|<A HREF="#expr1">expr1</A>| <A HREF="#expr2">expr2</A> ? expr1 : expr1	if-then-else

|<A HREF="#expr2">expr2</A>|	<A HREF="#expr3">expr3</A> &#124;&#124; <A HREF="#expr3">expr3</A> ..	logical OR

|<A HREF="#expr3">expr3</A>|	<A HREF="#expr4">expr4</A> &amp;&amp; <A HREF="#expr4">expr4</A> ..	logical AND

|<A HREF="#expr4">expr4</A>|	<A HREF="#expr5">expr5</A> <A HREF="change.html#==">==</A> <A HREF="#expr5">expr5</A>		equal
	<A HREF="#expr5">expr5</A> != <A HREF="#expr5">expr5</A>		not equal
	<A HREF="#expr5">expr5</A> <A HREF="change.html#&gt;">&gt;</A>	 <A HREF="#expr5">expr5</A>		greater than
	<A HREF="#expr5">expr5</A> &gt;= <A HREF="#expr5">expr5</A>		greater than or equal
	<A HREF="#expr5">expr5</A> <A HREF="change.html#&lt;">&lt;</A>	 <A HREF="#expr5">expr5</A>		smaller than
	<A HREF="#expr5">expr5</A> &lt;= <A HREF="#expr5">expr5</A>		smaller than or equal
	<A HREF="#expr5">expr5</A> =~ <A HREF="#expr5">expr5</A>		<A HREF="pattern.html#regexp">regexp</A> matches
	<A HREF="#expr5">expr5</A> !~ <A HREF="#expr5">expr5</A>		<A HREF="pattern.html#regexp">regexp</A> doesn't match

	<A HREF="#expr5">expr5</A> <A HREF="change.html#==">==</A>? <A HREF="#expr5">expr5</A>		equal, ignoring <A HREF="change.html#case">case</A>
	<A HREF="#expr5">expr5</A> ==# <A HREF="#expr5">expr5</A>		equal, match <A HREF="change.html#case">case</A>
	etc.			As above, append ? for ignoring <A HREF="change.html#case">case</A>, # for
				matching <A HREF="change.html#case">case</A>

	<A HREF="#expr5">expr5</A> is <A HREF="#expr5">expr5</A>		same |<A HREF="#List">List</A>| instance
	<A HREF="#expr5">expr5</A> isnot <A HREF="#expr5">expr5</A>	different |<A HREF="#List">List</A>| instance

|<A HREF="#expr5">expr5</A>|	<A HREF="#expr6">expr6</A> +	 <A HREF="#expr6">expr6</A> ..	number addition or <A HREF="#list">list</A> concatenation
	<A HREF="#expr6">expr6</A> -	 <A HREF="#expr6">expr6</A> ..	number subtraction
	<A HREF="#expr6">expr6</A> .	 <A HREF="#expr6">expr6</A> ..	<A HREF="#string">string</A> concatenation

|<A HREF="#expr6">expr6</A>|	<A HREF="#expr7">expr7</A> &#42;	 <A HREF="#expr7">expr7</A> ..	number multiplication
	<A HREF="#expr7">expr7</A> /	 <A HREF="#expr7">expr7</A> ..	number division
	<A HREF="#expr7">expr7</A> <A HREF="motion.html#&#37;">&#37;</A>	 <A HREF="#expr7">expr7</A> ..	number modulo

|<A HREF="#expr7">expr7</A>|	! expr7			logical NOT
	- <A HREF="#expr7">expr7</A>			unary minus
	+ <A HREF="#expr7">expr7</A>			unary plus

|<A HREF="#expr8">expr8</A>|	expr8[expr1]		byte of a <A HREF="#String">String</A> or item of a |<A HREF="#List">List</A>|
	expr8[expr1 : expr1]	substring of a <A HREF="#String">String</A> or <A HREF="#sublist">sublist</A> of a |<A HREF="#List">List</A>|
	expr8.name		entry in a |<A HREF="#Dictionary">Dictionary</A>|
	expr8(expr1, <A HREF="#...">...</A>)	function call with |<A HREF="#Funcref">Funcref</A>| variable

|<A HREF="#expr9">expr9</A>| number			number constant
	&quot;<A HREF="#string">string</A>&quot;		<A HREF="#string">string</A> constant, <A HREF="intro.html#backslash">backslash</A> is special
	'<A HREF="#string">string</A>'		<A HREF="#string">string</A> constant, '' is doubled
	[expr1, ...]		|<A HREF="#List">List</A>|
	{expr1: <A HREF="#expr1">expr1</A>, ...}	|<A HREF="#Dictionary">Dictionary</A>|
	&amp;option			option value
	(expr1)			nested <A HREF="#expression">expression</A>
	variable		internal variable
	va{ria}ble		internal variable with curly braces
	$VAR			environment variable
	<A HREF="#@r">@r</A>			contents of <A HREF="sponsor.html#register">register</A> '<A HREF="change.html#r">r</A>'
	function(expr1, <A HREF="#...">...</A>)	function call
	func{ti}on(expr1, <A HREF="#...">...</A>)	function call with curly braces


&quot;..&quot; indicates that the operations in this level can be concatenated.
Example:
<B>	&amp;nu || &amp;list &amp;&amp; &amp;shell == "csh"</B>

All expressions within one level are parsed from left to right.



<A HREF="#expr1">expr1</A>							*<A NAME="expr1"></A><B>expr1</B>* *<A NAME="E109"></A><B>E109</B>*

<A HREF="#expr2">expr2</A> ? <A HREF="#expr1">expr1</A> : <A HREF="#expr1">expr1</A>

The <A HREF="#expression">expression</A> before the '<A HREF="pattern.html#?">?</A>' is evaluated to a number.  If <A HREF="motion.html#it">it</A> evaluates to
non-zero, the result is the value of the <A HREF="#expression">expression</A> between the '<A HREF="pattern.html#?">?</A>' and '<A HREF="cmdline.html#:">:</A>',
otherwise the result is the value of the <A HREF="#expression">expression</A> after the '<A HREF="cmdline.html#:">:</A>'.
Example:
<B>	:echo lnum == 1 ? "top" : lnum</B>

Since the first <A HREF="#expression">expression</A> is an &quot;<A HREF="#expr2">expr2</A>&quot;, <A HREF="motion.html#it">it</A> cannot contain another ?:.  The
other two expressions can, thus allow for recursive use of ?:.
Example:
<B>	:echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum</B>

To keep this readable, using |<A HREF="repeat.html#line-continuation">line-continuation</A>| is suggested:
<B>	:echo lnum == 1</B>
<B>	:\	? "top"</B>
<B>	:\	: lnum == 1000</B>
<B>	:\		? "last"</B>
<B>	:\		: lnum</B>

You should always put a space before the '<A HREF="cmdline.html#:">:</A>', otherwise <A HREF="motion.html#it">it</A> can be mistaken for
use in a variable such <A HREF="motion.html#as">as</A> &quot;<A HREF="#a:1">a:1</A>&quot;.



<A HREF="#expr2">expr2</A> and <A HREF="#expr3">expr3</A>						*<A NAME="expr2"></A><B>expr2</B>* *<A NAME="expr3"></A><B>expr3</B>*


					*<A NAME="expr-barbar"></A><B>expr-barbar</B>* *<A NAME="expr-&amp;&amp;"></A><B>expr-&amp;&amp;</B>*
The &quot;&#124;&#124;&quot; and &quot;&amp;&amp;&quot; operators take one argument on each side.  The arguments
are (converted to) Numbers.  The result is:

<B><FONT COLOR="PURPLE">	 input				 output </FONT></B>
<B><FONT COLOR="PURPLE">n1		n2		n1 || n2	n1 &amp;&amp; n2 </FONT></B>
zero		zero		zero		zero
zero		non-zero	non-zero	zero
non-zero	zero		non-zero	zero
non-zero	non-zero	non-zero	non-zero

The operators can be concatenated, for example:

<B>	&amp;nu || &amp;list &amp;&amp; &amp;shell == "csh"</B>

Note that &quot;&amp;&amp;&quot; takes precedence over &quot;&#124;&#124;&quot;, so this has the meaning of:

<B>	&amp;nu || (&amp;list &amp;&amp; &amp;shell == "csh")</B>

Once the result is known, the <A HREF="#expression">expression</A> &quot;short-circuits&quot;, that is, further
arguments are not evaluated.  This is like what happens in C.  For example:

<B>	let a = 1</B>
<B>	echo a || b</B>

This is valid even if there is no variable called &quot;<A HREF="motion.html#b">b</A>&quot; because &quot;<A HREF="insert.html#a">a</A>&quot; is non-zero,
so the result must be non-zero.  Similarly below:

<B>	echo exists("b") &amp;&amp; b == "yes"</B>

This is valid whether &quot;<A HREF="motion.html#b">b</A>&quot; has been defined or not.  The second clause will
only be evaluated if &quot;<A HREF="motion.html#b">b</A>&quot; has been defined.



<A HREF="#expr4">expr4</A>							*<A NAME="expr4"></A><B>expr4</B>*

<A HREF="#expr5">expr5</A> {cmp} <A HREF="#expr5">expr5</A>

Compare two <A HREF="#expr5">expr5</A> expressions, resulting in a 0 if <A HREF="motion.html#it">it</A> evaluates to false, or 1
if <A HREF="motion.html#it">it</A> evaluates to true.


			*<A NAME="expr-=="></A><B>expr-==</B>*  *<A NAME="expr-!="></A><B>expr-!=</B>*  *<A NAME="expr-&gt;"></A><B>expr-&gt;</B>*	 *<A NAME="expr-&gt;="></A><B>expr-&gt;=</B>*

			*<A NAME="expr-&lt;"></A><B>expr-&lt;</B>*   *<A NAME="expr-&lt;="></A><B>expr-&lt;=</B>*  *<A NAME="expr-=~"></A><B>expr-=~</B>*  *<A NAME="expr-!~"></A><B>expr-!~</B>*

			*<A NAME="expr-==#"></A><B>expr-==#</B>* *<A NAME="expr-!=#"></A><B>expr-!=#</B>* *<A NAME="expr-&gt;#"></A><B>expr-&gt;#</B>*  *<A NAME="expr-&gt;=#"></A><B>expr-&gt;=#</B>*

			*<A NAME="expr-&lt;#"></A><B>expr-&lt;#</B>*  *<A NAME="expr-&lt;=#"></A><B>expr-&lt;=#</B>* *<A NAME="expr-=~#"></A><B>expr-=~#</B>* *<A NAME="expr-!~#"></A><B>expr-!~#</B>*

			*<A NAME="expr-==?"></A><B>expr-==?</B>* *<A NAME="expr-!=?"></A><B>expr-!=?</B>* *<A NAME="expr-&gt;?"></A><B>expr-&gt;?</B>*  *<A NAME="expr-&gt;=?"></A><B>expr-&gt;=?</B>*

			*<A NAME="expr-&lt;?"></A><B>expr-&lt;?</B>*  *<A NAME="expr-&lt;=?"></A><B>expr-&lt;=?</B>* *<A NAME="expr-=~?"></A><B>expr-=~?</B>* *<A NAME="expr-!~?"></A><B>expr-!~?</B>*

			*<A NAME="expr-is"></A><B>expr-is</B>* *<A NAME="expr-isnot"></A><B>expr-isnot</B>* *<A NAME="expr-is#"></A><B>expr-is#</B>* *<A NAME="expr-isnot#"></A><B>expr-isnot#</B>*

			*<A NAME="expr-is?"></A><B>expr-is?</B>* *<A NAME="expr-isnot?"></A><B>expr-isnot?</B>*
<B><FONT COLOR="PURPLE">		use 'ignorecase'    match case	   ignore case </FONT></B>
equal			<A HREF="change.html#==">==</A>		==#		<A HREF="change.html#==">==</A>?
not equal		!=		!=#		!=?
greater than		<A HREF="change.html#&gt;">&gt;</A>		&gt;#		<A HREF="change.html#&gt;">&gt;</A>?
greater than or equal	&gt;=		&gt;=#		&gt;=?
smaller than		<A HREF="change.html#&lt;">&lt;</A>		&lt;#		<A HREF="change.html#&lt;">&lt;</A>?
smaller than or equal	&lt;=		&lt;=#		&lt;=?
<A HREF="pattern.html#regexp">regexp</A> matches		=~		=~#		=~?
<A HREF="pattern.html#regexp">regexp</A> doesn't match	!~		!~#		!~?
same instance		is		is#		is?
different instance	isnot		isnot#		isnot?

Examples:
&quot;abc&quot; ==# &quot;Abc&quot;	  evaluates to 0
&quot;abc&quot; <A HREF="change.html#==">==</A>? &quot;Abc&quot;	  evaluates to 1
&quot;abc&quot; <A HREF="change.html#==">==</A> &quot;Abc&quot;	  evaluates to 1 if <A HREF="options.html#'ignorecase'">'ignorecase'</A> is set, 0 otherwise


							*<A NAME="E691"></A><B>E691</B>* *<A NAME="E692"></A><B>E692</B>*
A |<A HREF="#List">List</A>| can only be compared with a |<A HREF="#List">List</A>| and only &quot;equal&quot;, &quot;not equal&quot; and
&quot;is&quot; can be used.  This compares the values of the <A HREF="#list">list</A>, recursively.
Ignoring <A HREF="change.html#case">case</A> means <A HREF="change.html#case">case</A> is ignored when comparing item values.


							*<A NAME="E735"></A><B>E735</B>* *<A NAME="E736"></A><B>E736</B>*
A |<A HREF="#Dictionary">Dictionary</A>| can only be compared with a |<A HREF="#Dictionary">Dictionary</A>| and only &quot;equal&quot;, &quot;not
equal&quot; and &quot;is&quot; can be used.  This compares the key/values of the |<A HREF="#Dictionary">Dictionary</A>|
recursively.  Ignoring <A HREF="change.html#case">case</A> means <A HREF="change.html#case">case</A> is ignored when comparing item values.


							*<A NAME="E693"></A><B>E693</B>* *<A NAME="E694"></A><B>E694</B>*
A |<A HREF="#Funcref">Funcref</A>| can only be compared with a |<A HREF="#Funcref">Funcref</A>| and only &quot;equal&quot; and &quot;not
equal&quot; can be used.  Case is never ignored.  Whether arguments or a <A HREF="#Dictionary">Dictionary</A>
are bound (with a partial) is ignored.  This is so that when a function is
made a member of a <A HREF="#Dictionary">Dictionary</A> <A HREF="motion.html#it">it</A> is still considered to be the same function.
To compare partials to see if they bind the same argument and <A HREF="#Dictionary">Dictionary</A>
values use <A HREF="#string()">string()</A>:
<B>	echo string(Partial1) == string(Partial2)</B>

When using &quot;is&quot; or &quot;isnot&quot; with a |<A HREF="#List">List</A>| or a |<A HREF="#Dictionary">Dictionary</A>| this checks if the
expressions are referring to the same |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| instance.  A copy
of a |<A HREF="#List">List</A>| is different from the original |<A HREF="#List">List</A>|.  When using &quot;is&quot; without
a |<A HREF="#List">List</A>| or a |<A HREF="#Dictionary">Dictionary</A>| <A HREF="motion.html#it">it</A> is equivalent to using &quot;equal&quot;, using &quot;isnot&quot;
equivalent to using &quot;not equal&quot;.  Except that a different type means the
values are different:
<B>	echo 4 == '4'</B>
<B>	1</B>
<B>	echo 4 is '4'</B>
<B>	0</B>
<B>	echo 0 is []</B>
<B>	0</B>
&quot;is#&quot;/&quot;isnot#&quot; and &quot;is?&quot;/&quot;isnot?&quot; can be used to match and ignore <A HREF="change.html#case">case</A>.

When comparing a <A HREF="#String">String</A> with a <A HREF="#Number">Number</A>, the <A HREF="#String">String</A> is converted to a <A HREF="#Number">Number</A>,
and the comparison is done on Numbers.	This means that:
<B>	echo 0 == 'x'</B>
<B>	1</B>
because '<A HREF="change.html#x">x</A>' converted to a <A HREF="#Number">Number</A> is zero.  However:
<B>	echo [0] == ['x']</B>
<B>	0</B>
Inside a <A HREF="#List">List</A> or <A HREF="#Dictionary">Dictionary</A> this conversion is not used.

When comparing two Strings, this is done with strcmp() or stricmp().  This
results in the mathematical difference (comparing byte values), not
necessarily the alphabetical difference in the local language.

When using the operators with a trailing '<A HREF="pattern.html##">#</A>', or the short version and
<A HREF="options.html#'ignorecase'">'ignorecase'</A> is off, the comparing is done with strcmp(): <A HREF="change.html#case">case</A> matters.

When using the operators with a trailing '<A HREF="pattern.html#?">?</A>', or the short version and
<A HREF="options.html#'ignorecase'">'ignorecase'</A> is set, the comparing is done with stricmp(): <A HREF="change.html#case">case</A> is ignored.

<A HREF="options.html#'smartcase'">'smartcase'</A> is not used.

The &quot;=~&quot; and &quot;!~&quot; operators match the lefthand argument with the righthand
argument, which is used <A HREF="motion.html#as">as</A> a pattern.  See |<A HREF="pattern.html#pattern">pattern</A>| for what a pattern is.
This matching is always done like <A HREF="options.html#'magic'">'magic'</A> was set and <A HREF="options.html#'cpoptions'">'cpoptions'</A> is empty, no
matter what the actual value of <A HREF="options.html#'magic'">'magic'</A> or <A HREF="options.html#'cpoptions'">'cpoptions'</A> is.  This makes scripts
portable.  To avoid backslashes in the <A HREF="pattern.html#regexp">regexp</A> <A HREF="pattern.html#pattern">pattern</A> to be doubled, use a
single-quote string, see |<A HREF="#literal-string">literal-string</A>|.
Since a <A HREF="#string">string</A> is considered to be a single line, a multi-line <A HREF="pattern.html#pattern">pattern</A>
(containing \n, backslash-n) will not match.  However, a literal NL character
can be matched like an ordinary character.  Examples:
	&quot;foo\nbar&quot; =~ &quot;\n&quot;	evaluates to 1
	&quot;foo\nbar&quot; =~ &quot;\\n&quot;	evaluates to 0



<A HREF="#expr5">expr5</A> and <A HREF="#expr6">expr6</A>						*<A NAME="expr5"></A><B>expr5</B>* *<A NAME="expr6"></A><B>expr6</B>*

<A HREF="#expr6">expr6</A> +	 <A HREF="#expr6">expr6</A> ..	<A HREF="#Number">Number</A> addition or |<A HREF="#List">List</A>| concatenation	*<A NAME="expr-+"></A><B>expr-+</B>*

<A HREF="#expr6">expr6</A> -	 <A HREF="#expr6">expr6</A> ..	<A HREF="#Number">Number</A> subtraction			*<A NAME="expr--"></A><B>expr--</B>*

<A HREF="#expr6">expr6</A> .	 <A HREF="#expr6">expr6</A> ..	<A HREF="#String">String</A> concatenation			*<A NAME="expr-."></A><B>expr-.</B>*

For |<A HREF="#Lists">Lists</A>| only &quot;<A HREF="motion.html#+">+</A>&quot; is possible and then both <A HREF="#expr6">expr6</A> must be a <A HREF="#list">list</A>.  The
result is a new <A HREF="#list">list</A> with the two lists Concatenated.


<A HREF="#expr7">expr7</A> &#42;	 <A HREF="#expr7">expr7</A> ..	<A HREF="#Number">Number</A> multiplication			*<A NAME="expr-star"></A><B>expr-star</B>*

<A HREF="#expr7">expr7</A> /	 <A HREF="#expr7">expr7</A> ..	<A HREF="#Number">Number</A> division				*<A NAME="expr-/"></A><B>expr-/</B>*

<A HREF="#expr7">expr7</A> <A HREF="motion.html#&#37;">&#37;</A>	 <A HREF="#expr7">expr7</A> ..	<A HREF="#Number">Number</A> modulo				*<A NAME="expr-&#37;"></A><B>expr-&#37;</B>*

For all, except &quot;<A HREF="repeat.html#.">.</A>&quot;, Strings are converted to Numbers.
For bitwise operators see |<A HREF="#and()">and()</A>|, |<A HREF="#or()">or()</A>| and |<A HREF="#xor()">xor()</A>|.

Note the difference between &quot;<A HREF="motion.html#+">+</A>&quot; and &quot;<A HREF="repeat.html#.">.</A>&quot;:
	&quot;123&quot; + &quot;456&quot; = 579
	&quot;123&quot; . &quot;456&quot; = &quot;123456&quot;

Since '<A HREF="repeat.html#.">.</A>' has the same precedence <A HREF="motion.html#as">as</A> '<A HREF="motion.html#+">+</A>' and '<A HREF="motion.html#-">-</A>', you need to read:
<B>	1 . 90 + 90.0</B>
As:
<B>	(1 . 90) + 90.0</B>
That works, since the <A HREF="#String">String</A> &quot;190&quot; is automatically converted to the <A HREF="#Number">Number</A>
190, which can be added to the <A HREF="#Float">Float</A> 90.0.  However:
<B>	1 . 90 * 90.0</B>
Should be read <A HREF="motion.html#as">as</A>:
<B>	1 . (90 * 90.0)</B>
Since '<A HREF="repeat.html#.">.</A>' has lower precedence than '*'.  This does NOT work, since this
attempts to concatenate a <A HREF="#Float">Float</A> and a <A HREF="#String">String</A>.

When dividing a <A HREF="#Number">Number</A> by zero the result depends on the value:
	  0 / 0  = -0x80000000	(like NaN for <A HREF="#Float">Float</A>)
	 &gt;0 / 0  =  0x7fffffff	(like positive infinity)
	 &lt;0 / 0  = -0x7fffffff	(like negative infinity)
	(before Vim 7.2 <A HREF="motion.html#it">it</A> was always 0x7fffffff)

When the righthand side of '<A HREF="motion.html#&#37;">&#37;</A>' is zero, the result is 0.

None of these work for |<A HREF="#Funcref">Funcref</A>|<A HREF="change.html#s">s</A>.


. and <A HREF="motion.html#&#37;">&#37;</A> <A HREF="diff.html#do">do</A> not work for <A HREF="#Float">Float</A>. *<A NAME="E804"></A><B>E804</B>*



<A HREF="#expr7">expr7</A>							*<A NAME="expr7"></A><B>expr7</B>*

! <A HREF="#expr7">expr7</A>			logical NOT		*<A NAME="expr-!"></A><B>expr-!</B>*

- <A HREF="#expr7">expr7</A>			unary minus		*<A NAME="expr-unary--"></A><B>expr-unary--</B>*

+ <A HREF="#expr7">expr7</A>			unary plus		*<A NAME="expr-unary-+"></A><B>expr-unary-+</B>*

For '<A HREF="change.html#!">!</A>' non-zero becomes zero, zero becomes one.
For '<A HREF="motion.html#-">-</A>' the sign of the number is changed.
For '<A HREF="motion.html#+">+</A>' the number is unchanged.

A <A HREF="#String">String</A> will be converted to a <A HREF="#Number">Number</A> first.

These three can be repeated and mixed.	Examples:
	!-1	    <A HREF="change.html#==">==</A> 0
	!!8	    <A HREF="change.html#==">==</A> 1
	--9	    <A HREF="change.html#==">==</A> 9



<A HREF="#expr8">expr8</A>							*<A NAME="expr8"></A><B>expr8</B>*

expr8[expr1]		item of <A HREF="#String">String</A> or |<A HREF="#List">List</A>|	*<A NAME="expr-[]"></A><B>expr-[]</B>* *<A NAME="E111"></A><B>E111</B>*

							*<A NAME="E909"></A><B>E909</B>*
If <A HREF="#expr8">expr8</A> is a <A HREF="#Number">Number</A> or <A HREF="#String">String</A> this results in a <A HREF="#String">String</A> that contains the
expr1'th single byte from <A HREF="#expr8">expr8</A>.  <A HREF="#expr8">expr8</A> is used <A HREF="motion.html#as">as</A> a <A HREF="#String">String</A>, <A HREF="#expr1">expr1</A> <A HREF="motion.html#as">as</A> a
<A HREF="#Number">Number</A>.  This doesn't recognize <A HREF="mbyte.html#multi-byte">multi-byte</A> encodings, see |<A HREF="#byteidx()">byteidx()</A>| for
an alternative.

Index zero gives the first byte.  This is like <A HREF="motion.html#it">it</A> works in C.  Careful:
text column numbers start with one!  Example, to get the byte under the
cursor:
<B>	:let c = getline(".")[col(".") - 1]</B>

If the length of the <A HREF="#String">String</A> is <A HREF="various.html#less">less</A> than the index, the result is an empty
<A HREF="#String">String</A>.  A negative index always results in an empty <A HREF="#string">string</A> (reason: backward
compatibility).  Use [-1:] to get the last byte.

If <A HREF="#expr8">expr8</A> is a |<A HREF="#List">List</A>| then <A HREF="motion.html#it">it</A> results the item at index <A HREF="#expr1">expr1</A>.  See |<A HREF="#list-index">list-index</A>|
for possible index values.  If the index is out of range this results in an
error.	Example:
<B>	:let item = mylist[-1]		" get last item</B>

Generally, if a |<A HREF="#List">List</A>| index is equal to or higher than the length of the
|<A HREF="#List">List</A>|, or more negative than the length of the |<A HREF="#List">List</A>|, this results in an
error.



expr8[expr1a : expr1b]	substring or <A HREF="#sublist">sublist</A>		*<A NAME="expr-[:]"></A><B>expr-[:]</B>*

If <A HREF="#expr8">expr8</A> is a <A HREF="#Number">Number</A> or <A HREF="#String">String</A> this results in the substring with the bytes
from expr1a to and including expr1b.  <A HREF="#expr8">expr8</A> is used <A HREF="motion.html#as">as</A> a <A HREF="#String">String</A>, expr1a and
expr1b are used <A HREF="motion.html#as">as</A> a <A HREF="#Number">Number</A>.  This doesn't recognize <A HREF="mbyte.html#multi-byte">multi-byte</A> encodings, see
|<A HREF="#byteidx()">byteidx()</A>| for computing the indexes.

If expr1a is omitted zero is used.  If expr1b is omitted the length of the
<A HREF="#string">string</A> minus one is used.

A negative number can be used to measure from the end of the <A HREF="#string">string</A>.  -1 is
the last character, -2 the last but one, etc.

If an index goes out of range for the <A HREF="#string">string</A> characters are omitted.  If
expr1b is smaller than expr1a the result is an empty <A HREF="#string">string</A>.

Examples:
<B>	:let c = name[-1:]		" last byte of a string</B>
<B>	:let c = name[-2:-2]		" last but one byte of a string</B>
<B>	:let s = line(".")[4:]		" from the fifth byte to the end</B>
<B>	:let s = s[:-3]			" remove last two bytes</B>
 

							*<A NAME="sublist"></A><B>sublist</B>* *<A NAME="slice"></A><B>slice</B>*
If <A HREF="#expr8">expr8</A> is a |<A HREF="#List">List</A>| this results in a new |<A HREF="#List">List</A>| with the items indicated by
the indexes expr1a and expr1b.	This works like with a <A HREF="#String">String</A>, <A HREF="motion.html#as">as</A> explained
just above, except that indexes out of range cause an error.  Examples:
<B>	:let l = mylist[:3]		" first four items</B>
<B>	:let l = mylist[4:4]		" List with one item</B>
<B>	:let l = mylist[:]		" shallow copy of a List</B>

Using expr8[expr1] or expr8[expr1a : expr1b] on a |<A HREF="#Funcref">Funcref</A>| results in an
error.

Watch out for confusion between a namespace and a variable followed by a colon
for a <A HREF="#sublist">sublist</A>:
<B>	mylist[n:]     " uses variable n</B>
<B>	mylist[s:]     " uses namespace s:, error!</B>



expr8.name		entry in a |<A HREF="#Dictionary">Dictionary</A>|		*<A NAME="expr-entry"></A><B>expr-entry</B>*

If <A HREF="#expr8">expr8</A> is a |<A HREF="#Dictionary">Dictionary</A>| and <A HREF="motion.html#it">it</A> is followed by a dot, then the following
name will be used <A HREF="motion.html#as">as</A> a key in the |<A HREF="#Dictionary">Dictionary</A>|.  This is just like:
expr8[name].

The name must consist of alphanumeric characters, just like a variable name,
but <A HREF="motion.html#it">it</A> may start with a number.  Curly braces cannot be used.

There must not be white space before or after the dot.

Examples:
<B>	:let dict = {"one": 1, 2: "two"}</B>
<B>	:echo dict.one</B>
<B>	:echo dict .2</B>

Note that the dot is also used for <A HREF="#String">String</A> concatenation.  To avoid confusion
always put spaces around the dot for <A HREF="#String">String</A> concatenation.


expr8(expr1, <A HREF="#...">...</A>)	|<A HREF="#Funcref">Funcref</A>| function call

When <A HREF="#expr8">expr8</A> is a |<A HREF="#Funcref">Funcref</A>| type variable, invoke the function <A HREF="motion.html#it">it</A> refers to.




							*<A NAME="expr9"></A><B>expr9</B>*
number

number			number constant			*<A NAME="expr-number"></A><B>expr-number</B>* 

						*<A NAME="hex-number"></A><B>hex-number</B>* *<A NAME="octal-number"></A><B>octal-number</B>*

Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).


						*<A NAME="floating-point-format"></A><B>floating-point-format</B>*
Floating point numbers can be written in two forms:

	[-+]{N}.{M}
	[-+]{N}.{M}[eE][-+]{exp}

{N} and {M} are numbers.  Both {N} and {M} must be present and can only
contain digits.
[-+] means there is an optional plus or minus sign.
{exp} is the exponent, power of 10.
Only a decimal point is accepted, not a comma.	No matter what the current
<A HREF="mbyte.html#locale">locale</A> is.
{only when compiled with the |<A HREF="various.html#+float">+float</A>| feature}

Examples:
	123.456
	+0.0001
	55.0
	-0.123
	1.234e03
	1.0E-6
	-3.1416e+88

These are INVALID:
	3.		empty {M}
	1e40		missing .{M}


							*<A NAME="float-pi"></A><B>float-pi</B>* *<A NAME="float-e"></A><B>float-e</B>*
A few useful values to copy&amp;paste:
<B>	:let pi = 3.14159265359</B>
<B>	:let e  = 2.71828182846</B>

Rationale:
Before floating point was introduced, the text &quot;123.456&quot; was interpreted <A HREF="motion.html#as">as</A>
the two numbers &quot;123&quot; and &quot;456&quot;, both converted to a <A HREF="#string">string</A> and concatenated,
resulting in the <A HREF="#string">string</A> &quot;123456&quot;.  Since this was considered pointless, and we
could not find <A HREF="motion.html#it">it</A> intentionally being used in Vim scripts, this backwards
incompatibility was accepted in favor of being able to use the normal <A HREF="intro.html#notation">notation</A>
for floating point numbers.


						*<A NAME="floating-point-precision"></A><B>floating-point-precision</B>*
The precision and range of floating points numbers depends on what &quot;double&quot;
means in the library Vim was compiled with.  There is no way to change this at
runtime.

The default for displaying a |<A HREF="#Float">Float</A>| is to use 6 decimal places, like using
printf(&quot;&#37;g&quot;, <A HREF="motion.html#f">f</A>f).  You can select something else when using the |<A HREF="#printf()">printf()</A>|
function.  Example:
<B>	:echo printf('%.15e', atan(1))</B>
 	7.853981633974483e-01




<A HREF="#string">string</A>					*<A NAME="string"></A><B>string</B>* *<A NAME="String"></A><B>String</B>* *<A NAME="expr-string"></A><B>expr-string</B>* *<A NAME="E114"></A><B>E114</B>*

&quot;<A HREF="#string">string</A>&quot;		<A HREF="#string">string</A> constant		*<A NAME="expr-quote"></A><B>expr-quote</B>*

Note that double <A HREF="quotes.html#quotes">quotes</A> are used.

A <A HREF="#string">string</A> constant accepts these special characters:
\...	three-digit <A HREF="#octal">octal</A> number (e.g., &quot;\316&quot;)
\..	two-digit <A HREF="#octal">octal</A> number (must be followed by non-digit)
\.	one-digit <A HREF="#octal">octal</A> number (must be followed by non-digit)
\x..	byte specified with two hex numbers (e.g., &quot;\x1f&quot;)
\x.	byte specified with one hex number (must be followed by non-hex char)
\X..	same <A HREF="motion.html#as">as</A> \x..
\X.	same <A HREF="motion.html#as">as</A> \x.
\u....	character specified with up to 4 hex numbers, stored according to the
	current value of <A HREF="options.html#'encoding'">'encoding'</A> (e.g., &quot;\u02a4&quot;)
\U....	same <A HREF="motion.html#as">as</A> \u but allows up to 8 hex numbers.
\b	backspace <A HREF="motion.html#&lt;BS&gt;">&lt;BS&gt;</A>
\e	<A HREF="intro.html#escape">escape</A> <A HREF="intro.html#&lt;Esc&gt;">&lt;Esc&gt;</A>
\f	<A HREF="intro.html#formfeed">formfeed</A> &lt;FF&gt;
\n	newline <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A>
\r	return <A HREF="motion.html#&lt;CR&gt;">&lt;CR&gt;</A>
\t	<A HREF="intro.html#tab">tab</A> <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A>
\\	<A HREF="intro.html#backslash">backslash</A>
\&quot;	double <A HREF="change.html#quote">quote</A>
\&lt;xxx&gt;	<A HREF="#Special">Special</A> key named &quot;xxx&quot;.  e.g. &quot;\&lt;C-W&gt;&quot; for <A HREF="index.html#CTRL-W">CTRL-W</A>.  This is for use
	in mappings, the 0x80 byte is escaped.  Don't use &lt;Char-xxxx&gt; to get a
	<A HREF="mbyte.html#utf-8">utf-8</A> character, use \uxxxx <A HREF="motion.html#as">as</A> mentioned above.

Note that &quot;\xff&quot; is stored <A HREF="motion.html#as">as</A> the byte 255, which may be invalid in some
encodings.  Use &quot;\u00ff&quot; to store character 255 according to the current value
of <A HREF="options.html#'encoding'">'encoding'</A>.

Note that &quot;\000&quot; and &quot;\x00&quot; force the end of the <A HREF="#string">string</A>.



<A HREF="#literal-string">literal-string</A>						*<A NAME="literal-string"></A><B>literal-string</B>* *<A NAME="E115"></A><B>E115</B>*

'<A HREF="#string">string</A>'		<A HREF="#string">string</A> constant			*<A NAME="expr-'"></A><B>expr-'</B>*

Note that single <A HREF="quotes.html#quotes">quotes</A> are used.

This <A HREF="#string">string</A> is taken <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> is.	No backslashes are removed or have a special
meaning.  The only exception is that two <A HREF="quotes.html#quotes">quotes</A> stand for one <A HREF="change.html#quote.">quote.</A>

Single quoted strings are useful for patterns, so that backslashes <A HREF="diff.html#do">do</A> not need
to be doubled.	These two commands are equivalent:
<B>	if a =~ "\\s*"</B>
<B>	if a =~ '\s*'</B>



option						*<A NAME="expr-option"></A><B>expr-option</B>* *<A NAME="E112"></A><B>E112</B>* *<A NAME="E113"></A><B>E113</B>*
&amp;option			option value, local value if possible
&amp;g:option		global option value
&amp;l:option		local option value

Examples:
<B>	echo "tabstop is " . &amp;tabstop</B>
<B>	if &amp;insertmode</B>

Any option name can be used here.  See |<A HREF="options.html#options">options</A>|.  When using the local value
and there is no buffer-local or window-local value, the global value is used
anyway.



<A HREF="sponsor.html#register">register</A>						*<A NAME="expr-register"></A><B>expr-register</B>* *<A NAME="@r"></A><B>@r</B>*
<A HREF="#@r">@r</A>			contents of <A HREF="sponsor.html#register">register</A> '<A HREF="change.html#r">r</A>'

The result is the contents of the named <A HREF="sponsor.html#register">register</A>, <A HREF="motion.html#as">as</A> a single <A HREF="#string">string</A>.
Newlines are inserted where required.  To get the contents of the unnamed
register use @&quot; or <A HREF="repeat.html#@@">@@</A>.	See |<A HREF="change.html#registers">registers</A>| for an explanation of the available
<A HREF="change.html#registers">registers</A>.

When using the '<A HREF="change.html#=">=</A>' <A HREF="sponsor.html#register">register</A> you get the <A HREF="#expression">expression</A> itself, not what <A HREF="motion.html#it">it</A>
evaluates to.  Use |<A HREF="#eval()">eval()</A>| to evaluate <A HREF="motion.html#it">it</A>.



nesting							*<A NAME="expr-nesting"></A><B>expr-nesting</B>* *<A NAME="E110"></A><B>E110</B>*
(expr1)			nested <A HREF="#expression">expression</A>



environment variable					*<A NAME="expr-env"></A><B>expr-env</B>*
$VAR			environment variable

The <A HREF="#String">String</A> value of any environment variable.  When <A HREF="motion.html#it">it</A> is not defined, the
result is an empty <A HREF="#string">string</A>.

						*<A NAME="expr-env-expand"></A><B>expr-env-expand</B>*
Note that there is a difference between using $VAR directly and using
expand(&quot;$VAR&quot;).  Using <A HREF="motion.html#it">it</A> directly will only expand environment <A HREF="#variables">variables</A> that
are known inside the current Vim session.  Using <A HREF="#expand()">expand()</A> will first try using
the environment <A HREF="#variables">variables</A> known inside the current Vim session.  If that
fails, a shell will be used to expand the variable.  This can be slow, but <A HREF="motion.html#it">it</A>
does expand all <A HREF="#variables">variables</A> that the shell knows about.  Example:
<B>	:echo $shell</B>
<B>	:echo expand("$shell")</B>
The first one probably doesn't echo anything, the second echoes the $shell
variable (if your shell supports <A HREF="motion.html#it">it</A>).



internal variable					*<A NAME="expr-variable"></A><B>expr-variable</B>*
variable		internal variable
See below |<A HREF="#internal-variables">internal-variables</A>|.



function call		*<A NAME="expr-function"></A><B>expr-function</B>* *<A NAME="E116"></A><B>E116</B>* *<A NAME="E118"></A><B>E118</B>* *<A NAME="E119"></A><B>E119</B>* *<A NAME="E120"></A><B>E120</B>*
function(expr1, <A HREF="#...">...</A>)	function call
See below |<A HREF="#functions">functions</A>|.


==============================================================================

3. Internal variable				*<A NAME="internal-variables"></A><B>internal-variables</B>* *<A NAME="E461"></A><B>E461</B>*

An internal variable name can be made up of letters, digits and '<A HREF="motion.html#_">_</A>'.  But <A HREF="motion.html#it">it</A>
cannot start with a digit.  It's also possible to use curly braces, see
|<A HREF="#curly-braces-names">curly-braces-names</A>|.

An internal variable is created with the &quot;:let&quot; command |<A HREF="#:let">:let</A>|.
An internal variable is explicitly destroyed with the &quot;<A HREF="#:unlet">:unlet</A>&quot; command
|<A HREF="#:unlet">:unlet</A>|.
Using a name that is not an internal variable or refers to a variable that has
been destroyed results in an error.

There are several name spaces for <A HREF="#variables">variables</A>.  Which one is to be used is
specified by what is prepended:

		(nothing) In a function: local to a function; otherwise: global
|<A HREF="#buffer-variable">buffer-variable</A>|    <A HREF="#b:">b:</A>	  Local to the current buffer.
|<A HREF="#window-variable">window-variable</A>|    <A HREF="#w:">w:</A>	  Local to the current window.
|<A HREF="#tabpage-variable">tabpage-variable</A>|   <A HREF="#t:">t:</A>	  Local to the current tab page.
|<A HREF="#global-variable">global-variable</A>|    <A HREF="#g:">g:</A>	  Global.
|<A HREF="#local-variable">local-variable</A>|     <A HREF="#l:">l:</A>	  Local to a function.
|<A HREF="#script-variable">script-variable</A>|    s:	  Local to a |<A HREF="repeat.html#:source">:source</A>|'ed Vim script.
|<A HREF="#function-argument">function-argument</A>|  a:	  Function argument (only inside a function).
|<A HREF="#vim-variable">vim-variable</A>|       <A HREF="#v:">v:</A>	  Global, predefined by Vim.

The scope name by itself can be used <A HREF="motion.html#as">as</A> a |<A HREF="#Dictionary">Dictionary</A>|.  For example, to
delete all <A HREF="map.html#script-local">script-local</A> <A HREF="#variables">variables</A>:
<B>	:for k in keys(s:)</B>
<B>	:    unlet s:[k]</B>
<B>	:endfor</B>
 

						*<A NAME="buffer-variable"></A><B>buffer-variable</B>* *<A NAME="b:var"></A><B>b:var</B>* *<A NAME="b:"></A><B>b:</B>*
A variable name that is preceded with &quot;<A HREF="#b:">b:</A>&quot; is local to the current buffer.
Thus you can have several &quot;b:foo&quot; <A HREF="#variables">variables</A>, one for each buffer.
This kind of variable is deleted when the buffer is wiped out or deleted with
|<A HREF="windows.html#:bdelete">:bdelete</A>|.

One local buffer variable is predefined:

					*<A NAME="b:changedtick"></A><B>b:changedtick</B>* *<A NAME="changetick"></A><B>changetick</B>*
<A HREF="#b:changedtick">b:changedtick</A>	The total number of changes to the current buffer.  It is
		incremented for each change.  An <A HREF="undo.html#undo">undo</A> command is also a change
		in this <A HREF="change.html#case">case</A>.  This can be used to perform an action only when
		the buffer has changed.  Example:
<B>		    :if my_changedtick != b:changedtick</B>
<B>		    :	let my_changedtick = b:changedtick</B>
<B>		    :	call My_Update()</B>
<B>		    :endif</B>
 

						*<A NAME="window-variable"></A><B>window-variable</B>* *<A NAME="w:var"></A><B>w:var</B>* *<A NAME="w:"></A><B>w:</B>*
A variable name that is preceded with &quot;<A HREF="#w:">w:</A>&quot; is local to the current <A HREF="windows.html#window">window</A>.  It
is deleted when the <A HREF="windows.html#window">window</A> is closed.


						*<A NAME="tabpage-variable"></A><B>tabpage-variable</B>* *<A NAME="t:var"></A><B>t:var</B>* *<A NAME="t:"></A><B>t:</B>*
A variable name that is preceded with &quot;<A HREF="#t:">t:</A>&quot; is local to the current <A HREF="intro.html#tab">tab</A> page,
It is deleted when the <A HREF="intro.html#tab">tab</A> page is closed. {not available when compiled
without the |<A HREF="various.html#+windows">+windows</A>| feature}


						*<A NAME="global-variable"></A><B>global-variable</B>* *<A NAME="g:var"></A><B>g:var</B>* *<A NAME="g:"></A><B>g:</B>*
Inside <A HREF="#functions">functions</A> global <A HREF="#variables">variables</A> are accessed with &quot;<A HREF="#g:">g:</A>&quot;.  Omitting this will
access a variable local to a function.	But &quot;<A HREF="#g:">g:</A>&quot; can also be used in any other
place if you like.


						*<A NAME="local-variable"></A><B>local-variable</B>* *<A NAME="l:var"></A><B>l:var</B>* *<A NAME="l:"></A><B>l:</B>*
Inside <A HREF="#functions">functions</A> local <A HREF="#variables">variables</A> are accessed without prepending anything.
But you can also prepend &quot;<A HREF="#l:">l:</A>&quot; if you like.  However, without prepending &quot;<A HREF="#l:">l:</A>&quot;
you may run into reserved variable names.  For example &quot;<A HREF="intro.html#count">count</A>&quot;.  By itself <A HREF="motion.html#it">it</A>
refers to &quot;<A HREF="#v:count">v:count</A>&quot;.  Using &quot;l:count&quot; you can have a local variable with the
same name.


						*<A NAME="script-variable"></A><B>script-variable</B>* *<A NAME="s:var"></A><B>s:var</B>*
In a Vim <A HREF="usr_41.html#script">script</A> <A HREF="#variables">variables</A> starting with &quot;s:&quot; can be used.  They cannot be
accessed from outside of the scripts, thus are local to the <A HREF="usr_41.html#script">script</A>.

They can be used in:
- commands executed while the <A HREF="usr_41.html#script">script</A> is sourced
- <A HREF="#functions">functions</A> defined in the <A HREF="usr_41.html#script">script</A>
- autocommands defined in the <A HREF="usr_41.html#script">script</A>
- <A HREF="#functions">functions</A> and autocommands defined in <A HREF="#functions">functions</A> and autocommands which were
  defined in the <A HREF="usr_41.html#script">script</A> (recursively)
- user defined commands defined in the <A HREF="usr_41.html#script">script</A>
Thus not in:
- other scripts sourced from this one
- mappings
- <A HREF="gui.html#menus">menus</A>
- etc.

Script <A HREF="#variables">variables</A> can be used to avoid conflicts with global variable names.
Take this example:

<B>	let s:counter = 0</B>
<B>	function MyCounter()</B>
<B>	  let s:counter = s:counter + 1</B>
<B>	  echo s:counter</B>
<B>	endfunction</B>
<B>	command Tick call MyCounter()</B>

You can now invoke &quot;Tick&quot; from any <A HREF="usr_41.html#script">script</A>, and the &quot;s:counter&quot; variable in
that <A HREF="usr_41.html#script">script</A> will not be changed, only the &quot;s:counter&quot; in the <A HREF="usr_41.html#script">script</A> where
&quot;Tick&quot; was defined is used.

Another example that does the same:

<B>	let s:counter = 0</B>
<B>	command Tick let s:counter = s:counter + 1 | echo s:counter</B>

When calling a function and invoking a user-defined command, the context for
<A HREF="usr_41.html#script">script</A> <A HREF="#variables">variables</A> is set to the <A HREF="usr_41.html#script">script</A> where the function or command was
defined.

The <A HREF="usr_41.html#script">script</A> <A HREF="#variables">variables</A> are also available when a function is defined inside a
function that is defined in a <A HREF="usr_41.html#script">script</A>.  Example:

<B>	let s:counter = 0</B>
<B>	function StartCounting(incr)</B>
<B>	  if a:incr</B>
<B>	    function MyCounter()</B>
<B>	      let s:counter = s:counter + 1</B>
<B>	    endfunction</B>
<B>	  else</B>
<B>	    function MyCounter()</B>
<B>	      let s:counter = s:counter - 1</B>
<B>	    endfunction</B>
<B>	  endif</B>
<B>	endfunction</B>

This defines the MyCounter() function either for counting up or counting down
when calling StartCounting().  It doesn't matter from where StartCounting() is
called, the s:counter variable will be accessible in MyCounter().

When the same <A HREF="usr_41.html#script">script</A> is sourced again <A HREF="motion.html#it">it</A> will use the same <A HREF="usr_41.html#script">script</A> <A HREF="#variables">variables</A>.
They will remain valid <A HREF="motion.html#as">as</A> long <A HREF="motion.html#as">as</A> Vim is running.  This can be used to
maintain a counter:

<B>	if !exists("s:counter")</B>
<B>	  let s:counter = 1</B>
<B>	  echo "script executed for the first time"</B>
<B>	else</B>
<B>	  let s:counter = s:counter + 1</B>
<B>	  echo "script executed " . s:counter . " times now"</B>
<B>	endif</B>

Note that this means that <A HREF="filetype.html#filetype">filetype</A> plugins don't get a different set of <A HREF="usr_41.html#script">script</A>
<A HREF="#variables">variables</A> for each buffer.  Use local buffer <A HREF="#variables">variables</A> instead |<A HREF="#b:var">b:var</A>|.



Predefined Vim <A HREF="#variables">variables</A>:			*<A NAME="vim-variable"></A><B>vim-variable</B>* *<A NAME="v:var"></A><B>v:var</B>* *<A NAME="v:"></A><B>v:</B>*


					*<A NAME="v:beval_col"></A><B>v:beval_col</B>* *<A NAME="beval_col-variable"></A><B>beval_col-variable</B>*
<A HREF="#v:beval_col">v:beval_col</A>	The number of the column, over which the mouse pointer is.
		This is the byte index in the |<A HREF="#v:beval_lnum">v:beval_lnum</A>| line.
		Only valid while evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> option.


					*<A NAME="v:beval_bufnr"></A><B>v:beval_bufnr</B>* *<A NAME="beval_bufnr-variable"></A><B>beval_bufnr-variable</B>*
<A HREF="#v:beval_bufnr">v:beval_bufnr</A>	The number of the buffer, over which the mouse pointer is. Only
		valid while evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> option.


					*<A NAME="v:beval_lnum"></A><B>v:beval_lnum</B>* *<A NAME="beval_lnum-variable"></A><B>beval_lnum-variable</B>*
<A HREF="#v:beval_lnum">v:beval_lnum</A>	The number of the line, over which the mouse pointer is. Only
		valid while evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> option.


					*<A NAME="v:beval_text"></A><B>v:beval_text</B>* *<A NAME="beval_text-variable"></A><B>beval_text-variable</B>*
<A HREF="#v:beval_text">v:beval_text</A>	The text under or after the mouse pointer.  Usually a <A HREF="motion.html#word">word</A> <A HREF="motion.html#as">as</A>
		<A HREF="motion.html#it">it</A> is useful for debugging a C program.  <A HREF="options.html#'iskeyword'">'iskeyword'</A> applies,
		but a dot and &quot;-&gt;&quot; before the position is included.  When on a
		'<A HREF="index.html#]">]</A>' the text before <A HREF="motion.html#it">it</A> is used, including the matching '<A HREF="index.html#[">[</A>' and
		<A HREF="motion.html#word">word</A> before <A HREF="motion.html#it">it</A>.  When on a <A HREF="visual.html#Visual">Visual</A> area within one line the
		highlighted text is used.
		Only valid while evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> option.


					*<A NAME="v:beval_winnr"></A><B>v:beval_winnr</B>* *<A NAME="beval_winnr-variable"></A><B>beval_winnr-variable</B>*
<A HREF="#v:beval_winnr">v:beval_winnr</A>	The number of the <A HREF="windows.html#window">window</A>, over which the mouse pointer is. Only
		valid while evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> option.  The first
		<A HREF="windows.html#window">window</A> has number zero (unlike most other places where a
		<A HREF="windows.html#window">window</A> gets a number).


					*<A NAME="v:char"></A><B>v:char</B>* *<A NAME="char-variable"></A><B>char-variable</B>*
<A HREF="#v:char">v:char</A>		Argument for evaluating <A HREF="options.html#'formatexpr'">'formatexpr'</A> and used for the typed
		character when using &lt;expr&gt; in an abbreviation |<A HREF="map.html#:map-&lt;expr&gt;">:map-&lt;expr&gt;</A>|.
		It is also used by the |<A HREF="autocmd.html#InsertCharPre">InsertCharPre</A>| and |<A HREF="autocmd.html#InsertEnter">InsertEnter</A>| events.


			*<A NAME="v:charconvert_from"></A><B>v:charconvert_from</B>* *<A NAME="charconvert_from-variable"></A><B>charconvert_from-variable</B>*
<A HREF="#v:charconvert_from">v:charconvert_from</A>
		The name of the character encoding of a file to be converted.
		Only valid while evaluating the <A HREF="options.html#'charconvert'">'charconvert'</A> option.


			*<A NAME="v:charconvert_to"></A><B>v:charconvert_to</B>* *<A NAME="charconvert_to-variable"></A><B>charconvert_to-variable</B>*
<A HREF="#v:charconvert_to">v:charconvert_to</A>
		The name of the character encoding of a file after conversion.
		Only valid while evaluating the <A HREF="options.html#'charconvert'">'charconvert'</A> option.


					*<A NAME="v:cmdarg"></A><B>v:cmdarg</B>* *<A NAME="cmdarg-variable"></A><B>cmdarg-variable</B>*
<A HREF="#v:cmdarg">v:cmdarg</A>	This variable is used for two purposes:
		1. The extra arguments given to a file read/write command.
		   Currently these are &quot;++enc=&quot; and &quot;++ff=&quot;.  This variable is
		   set before an <A HREF="autocmd.html#autocommand">autocommand</A> event for a file read/write
		   command is triggered.  There is a leading space to make <A HREF="motion.html#it">it</A>
		   possible to append this variable directly after the
		   read/write command.	Note: The &quot;<A HREF="editing.html#+cmd">+cmd</A>&quot; argument isn't
		   included here, because <A HREF="motion.html#it">it</A> will be executed anyway.
		2. When <A HREF="print.html#printing">printing</A> a PostScript file with &quot;<A HREF="print.html#:hardcopy">:hardcopy</A>&quot; this is
		   the argument for the &quot;<A HREF="print.html#:hardcopy">:hardcopy</A>&quot; command.  This can be used
		   in <A HREF="options.html#'printexpr'">'printexpr'</A>.


					*<A NAME="v:cmdbang"></A><B>v:cmdbang</B>* *<A NAME="cmdbang-variable"></A><B>cmdbang-variable</B>*
<A HREF="#v:cmdbang">v:cmdbang</A>	Set like <A HREF="#v:cmdarg">v:cmdarg</A> for a file read/write command.  When a &quot;<A HREF="change.html#!">!</A>&quot;
		was used the value is 1, otherwise <A HREF="motion.html#it">it</A> is 0.  Note that this
		can only be used in autocommands.  For user commands |<A HREF="map.html#&lt;bang&gt;">&lt;bang&gt;</A>|
		can be used.


				*<A NAME="v:completed_item"></A><B>v:completed_item</B>* *<A NAME="completed_item-variable"></A><B>completed_item-variable</B>*
<A HREF="#v:completed_item">v:completed_item</A>
		|<A HREF="#Dictionary">Dictionary</A>| containing the |<A HREF="insert.html#complete-items">complete-items</A>| for the most
		recently completed <A HREF="motion.html#word">word</A> after |<A HREF="autocmd.html#CompleteDone">CompleteDone</A>|.  The
		|<A HREF="#Dictionary">Dictionary</A>| is empty if the completion failed.


					*<A NAME="v:count"></A><B>v:count</B>* *<A NAME="count-variable"></A><B>count-variable</B>*
<A HREF="#v:count">v:count</A>		The <A HREF="intro.html#count">count</A> given for the last <A HREF="intro.html#Normal">Normal</A> mode command.  Can be used
		to get the <A HREF="intro.html#count">count</A> before a <A HREF="map.html#mapping">mapping</A>.  Read-only.	Example:
<B>	:map _x :&lt;C-U&gt;echo "the count is " . v:count&lt;CR&gt;</B>
 		Note: The &lt;C-U&gt; is required to remove the line range that you
		get when typing '<A HREF="cmdline.html#:">:</A>' after a <A HREF="intro.html#count">count</A>.
		When there are two counts, <A HREF="motion.html#as">as</A> in &quot;3d2w&quot;, they are multiplied,
		just like what happens in the command, &quot;d6w&quot; for the example.
		Also used for evaluating the <A HREF="options.html#'formatexpr'">'formatexpr'</A> option.
		&quot;<A HREF="intro.html#count">count</A>&quot; also works, for backwards compatibility.


					*<A NAME="v:count1"></A><B>v:count1</B>* *<A NAME="count1-variable"></A><B>count1-variable</B>*
<A HREF="#v:count1">v:count1</A>	Just like &quot;<A HREF="#v:count">v:count</A>&quot;, but defaults to one when no <A HREF="intro.html#count">count</A> is
		used.


						*<A NAME="v:ctype"></A><B>v:ctype</B>* *<A NAME="ctype-variable"></A><B>ctype-variable</B>*
<A HREF="#v:ctype">v:ctype</A>		The current <A HREF="mbyte.html#locale">locale</A> setting for characters of the runtime
		environment.  This allows Vim scripts to be aware of the
		current <A HREF="mbyte.html#locale">locale</A> encoding.  Technical: it's the value of
		LC_CTYPE.  When not using a <A HREF="mbyte.html#locale">locale</A> the value is &quot;<A HREF="change.html#C">C</A>&quot;.
		This variable can not be set directly, use the |<A HREF="mlang.html#:language">:language</A>|
		command.
		See |<A HREF="mlang.html#multi-lang">multi-lang</A>|.


					*<A NAME="v:dying"></A><B>v:dying</B>* *<A NAME="dying-variable"></A><B>dying-variable</B>*
<A HREF="#v:dying">v:dying</A>		Normally zero.	When a deadly signal is caught it's set to
		one.  When multiple signals are caught the number increases.
		Can be used in an <A HREF="autocmd.html#autocommand">autocommand</A> to check if Vim didn't
		terminate normally. {only works on Unix}
		Example:
<B>	:au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif</B>
 		Note: if another deadly signal is caught when <A HREF="#v:dying">v:dying</A> is one,
		<A HREF="autocmd.html#VimLeave">VimLeave</A> autocommands will not be executed.


					*<A NAME="v:errmsg"></A><B>v:errmsg</B>* *<A NAME="errmsg-variable"></A><B>errmsg-variable</B>*
<A HREF="#v:errmsg">v:errmsg</A>	Last given error message.  It's allowed to set this variable.
		Example:
<B>	:let v:errmsg = ""</B>
<B>	:silent! next</B>
<B>	:if v:errmsg != ""</B>
<B>	:  ... handle error</B>
 		&quot;errmsg&quot; also works, for backwards compatibility.


					*<A NAME="v:errors"></A><B>v:errors</B>* *<A NAME="errors-variable"></A><B>errors-variable</B>*
<A HREF="#v:errors">v:errors</A>	Errors found by assert <A HREF="#functions">functions</A>, such as |<A HREF="#assert_true()">assert_true()</A>|.
		This is a <A HREF="#list">list</A> of strings.
		The assert <A HREF="#functions">functions</A> append an item when an assert fails.
		To remove old results make <A HREF="motion.html#it">it</A> empty:
<B>	:let v:errors = []</B>
 		If <A HREF="#v:errors">v:errors</A> is set to anything but a <A HREF="#list">list</A> <A HREF="motion.html#it">it</A> is made an empty
		<A HREF="#list">list</A> by the assert function.


					*<A NAME="v:exception"></A><B>v:exception</B>* *<A NAME="exception-variable"></A><B>exception-variable</B>*
<A HREF="#v:exception">v:exception</A>	The value of the exception most recently caught and not
		finished.  See also |<A HREF="#v:throwpoint">v:throwpoint</A>| and |<A HREF="#throw-variables">throw-variables</A>|.
		Example:
<B>	:try</B>
<B>	:  throw "oops"</B>
<B>	:catch /.*/</B>
<B>	:  echo "caught" v:exception</B>
<B>	:endtry</B>
 		Output: &quot;caught oops&quot;.


					*<A NAME="v:false"></A><B>v:false</B>* *<A NAME="false-variable"></A><B>false-variable</B>*
<A HREF="#v:false">v:false</A>		A <A HREF="#Number">Number</A> with value zero. Used to put &quot;false&quot; in JSON.  See
		|<A HREF="#json_encode()">json_encode()</A>|.
		When used <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A> this evaluates to &quot;false&quot;.
<B>			echo v:false</B>
<B><FONT COLOR="PURPLE"> 			false </FONT></B>


					*<A NAME="v:fcs_reason"></A><B>v:fcs_reason</B>* *<A NAME="fcs_reason-variable"></A><B>fcs_reason-variable</B>*
<A HREF="#v:fcs_reason">v:fcs_reason</A>	The reason why the |<A HREF="autocmd.html#FileChangedShell">FileChangedShell</A>| event was triggered.
		Can be used in an <A HREF="autocmd.html#autocommand">autocommand</A> to decide what to <A HREF="diff.html#do">do</A> and/or what
		to set <A HREF="#v:fcs_choice">v:fcs_choice</A> to.  Possible values:
			deleted		file no longer exists
			conflict	file contents, mode or <A HREF="editing.html#timestamp">timestamp</A> was
					changed and buffer is modified
			changed		file contents has changed
			mode		mode of file changed
			time		only file <A HREF="editing.html#timestamp">timestamp</A> changed


					*<A NAME="v:fcs_choice"></A><B>v:fcs_choice</B>* *<A NAME="fcs_choice-variable"></A><B>fcs_choice-variable</B>*
<A HREF="#v:fcs_choice">v:fcs_choice</A>	What should happen after a |<A HREF="autocmd.html#FileChangedShell">FileChangedShell</A>| event was
		triggered.  Can be used in an <A HREF="autocmd.html#autocommand">autocommand</A> to tell Vim what to
		<A HREF="diff.html#do">do</A> with the affected buffer:
			<A HREF="editing.html#reload">reload</A>		Reload the buffer (does not work if
					the file was deleted).
			ask		Ask the user what to <A HREF="diff.html#do">do</A>, <A HREF="motion.html#as">as</A> if there
					was no <A HREF="autocmd.html#autocommand">autocommand</A>.  Except that when
					only the <A HREF="editing.html#timestamp">timestamp</A> changed nothing
					will happen.
			&lt;empty&gt;		Nothing, the <A HREF="autocmd.html#autocommand">autocommand</A> should <A HREF="diff.html#do">do</A>
					everything that needs to be done.
		The default is empty.  If another (invalid) value is used then
		Vim behaves like <A HREF="motion.html#it">it</A> is empty, there is no warning message.


					*<A NAME="v:fname_in"></A><B>v:fname_in</B>* *<A NAME="fname_in-variable"></A><B>fname_in-variable</B>*
<A HREF="#v:fname_in">v:fname_in</A>	The name of the input file.  Valid while evaluating:
<B><FONT COLOR="PURPLE">			option		used for </FONT></B>
			<A HREF="options.html#'charconvert'">'charconvert'</A>	file to be converted
			<A HREF="options.html#'diffexpr'">'diffexpr'</A>	original file
			<A HREF="options.html#'patchexpr'">'patchexpr'</A>	original file
			<A HREF="options.html#'printexpr'">'printexpr'</A>	file to be printed
		And set to the swap file name for |<A HREF="autocmd.html#SwapExists">SwapExists</A>|.


					*<A NAME="v:fname_out"></A><B>v:fname_out</B>* *<A NAME="fname_out-variable"></A><B>fname_out-variable</B>*
<A HREF="#v:fname_out">v:fname_out</A>	The name of the output file.  Only valid while
		evaluating:
<B><FONT COLOR="PURPLE">			option		used for </FONT></B>
			<A HREF="options.html#'charconvert'">'charconvert'</A>	resulting converted file (*)
			<A HREF="options.html#'diffexpr'">'diffexpr'</A>	output of <A HREF="diff.html#diff">diff</A>
			<A HREF="options.html#'patchexpr'">'patchexpr'</A>	resulting patched file
		(*) When doing conversion for a write command (e.g., &quot;<A HREF="editing.html#:w">:w</A>
		file&quot;) <A HREF="motion.html#it">it</A> will be equal to <A HREF="#v:fname_in">v:fname_in</A>.	When doing conversion
		for a read command (e.g., &quot;<A HREF="editing.html#:e">:e</A> file&quot;) <A HREF="motion.html#it">it</A> will be a temporary
		file and different from <A HREF="#v:fname_in">v:fname_in</A>.


					*<A NAME="v:fname_new"></A><B>v:fname_new</B>* *<A NAME="fname_new-variable"></A><B>fname_new-variable</B>*
<A HREF="#v:fname_new">v:fname_new</A>	The name of the new version of the file.  Only valid while
		evaluating <A HREF="options.html#'diffexpr'">'diffexpr'</A>.


					*<A NAME="v:fname_diff"></A><B>v:fname_diff</B>* *<A NAME="fname_diff-variable"></A><B>fname_diff-variable</B>*
<A HREF="#v:fname_diff">v:fname_diff</A>	The name of the <A HREF="diff.html#diff">diff</A> (patch) file.  Only valid while
		evaluating <A HREF="options.html#'patchexpr'">'patchexpr'</A>.


					*<A NAME="v:folddashes"></A><B>v:folddashes</B>* *<A NAME="folddashes-variable"></A><B>folddashes-variable</B>*
<A HREF="#v:folddashes">v:folddashes</A>	Used for <A HREF="options.html#'foldtext'">'foldtext'</A>: dashes representing foldlevel of a closed
		fold.
		Read-only in the |<A HREF="#sandbox">sandbox</A>|. |<A HREF="fold.html#fold-foldtext">fold-foldtext</A>|


					*<A NAME="v:foldlevel"></A><B>v:foldlevel</B>* *<A NAME="foldlevel-variable"></A><B>foldlevel-variable</B>*
<A HREF="#v:foldlevel">v:foldlevel</A>	Used for <A HREF="options.html#'foldtext'">'foldtext'</A>: foldlevel of closed fold.
		Read-only in the |<A HREF="#sandbox">sandbox</A>|. |<A HREF="fold.html#fold-foldtext">fold-foldtext</A>|


					*<A NAME="v:foldend"></A><B>v:foldend</B>* *<A NAME="foldend-variable"></A><B>foldend-variable</B>*
<A HREF="#v:foldend">v:foldend</A>	Used for <A HREF="options.html#'foldtext'">'foldtext'</A>: last line of closed fold.
		Read-only in the |<A HREF="#sandbox">sandbox</A>|. |<A HREF="fold.html#fold-foldtext">fold-foldtext</A>|


					*<A NAME="v:foldstart"></A><B>v:foldstart</B>* *<A NAME="foldstart-variable"></A><B>foldstart-variable</B>*
<A HREF="#v:foldstart">v:foldstart</A>	Used for <A HREF="options.html#'foldtext'">'foldtext'</A>: first line of closed fold.
		Read-only in the |<A HREF="#sandbox">sandbox</A>|. |<A HREF="fold.html#fold-foldtext">fold-foldtext</A>|


					*<A NAME="v:hlsearch"></A><B>v:hlsearch</B>* *<A NAME="hlsearch-variable"></A><B>hlsearch-variable</B>*
<A HREF="#v:hlsearch">v:hlsearch</A>	Variable that indicates whether search highlighting is on. 
		Setting <A HREF="motion.html#it">it</A> makes sense only if <A HREF="options.html#'hlsearch'">'hlsearch'</A> is enabled which
		requires |<A HREF="various.html#+extra_search">+extra_search</A>|. Setting this variable to zero acts
		like the |<A HREF="pattern.html#:nohlsearch">:nohlsearch</A>| command, setting <A HREF="motion.html#it">it</A> to one acts like
<B>			let &amp;hlsearch = &amp;hlsearch</B>
 		Note that the value is restored when returning from a
		function. |<A HREF="#function-search-undo">function-search-undo</A>|.


					*<A NAME="v:insertmode"></A><B>v:insertmode</B>* *<A NAME="insertmode-variable"></A><B>insertmode-variable</B>*
<A HREF="#v:insertmode">v:insertmode</A>	Used for the |<A HREF="autocmd.html#InsertEnter">InsertEnter</A>| and |<A HREF="autocmd.html#InsertChange">InsertChange</A>| <A HREF="autocmd.html#autocommand">autocommand</A>
		events.  Values:
			<A HREF="insert.html#i">i</A>	<A HREF="insert.html#Insert">Insert</A> mode
			<A HREF="change.html#r">r</A>	<A HREF="insert.html#Replace">Replace</A> mode
			<A HREF="visual.html#v">v</A>	Virtual <A HREF="insert.html#Replace">Replace</A> mode


						*<A NAME="v:key"></A><B>v:key</B>* *<A NAME="key-variable"></A><B>key-variable</B>*
<A HREF="#v:key">v:key</A>		Key of the current item of a |<A HREF="#Dictionary">Dictionary</A>|.  Only valid while
		evaluating the <A HREF="#expression">expression</A> used with |<A HREF="#map()">map()</A>| and |<A HREF="#filter()">filter()</A>|.
		Read-only.


						*<A NAME="v:lang"></A><B>v:lang</B>* *<A NAME="lang-variable"></A><B>lang-variable</B>*
<A HREF="#v:lang">v:lang</A>		The current <A HREF="mbyte.html#locale">locale</A> setting for <A HREF="message.html#messages">messages</A> of the runtime
		environment.  This allows Vim scripts to be aware of the
		current language.  Technical: it's the value of LC_MESSAGES.
		The value is system dependent.
		This variable can not be set directly, use the |<A HREF="mlang.html#:language">:language</A>|
		command.
		It can be different from |<A HREF="#v:ctype">v:ctype</A>| when <A HREF="message.html#messages">messages</A> are desired
		in a different language than what is used for character
		encoding.  See |<A HREF="mlang.html#multi-lang">multi-lang</A>|.


						*<A NAME="v:lc_time"></A><B>v:lc_time</B>* *<A NAME="lc_time-variable"></A><B>lc_time-variable</B>*
<A HREF="#v:lc_time">v:lc_time</A>	The current <A HREF="mbyte.html#locale">locale</A> setting for time <A HREF="message.html#messages">messages</A> of the runtime
		environment.  This allows Vim scripts to be aware of the
		current language.  Technical: it's the value of LC_TIME.
		This variable can not be set directly, use the |<A HREF="mlang.html#:language">:language</A>|
		command.  See |<A HREF="mlang.html#multi-lang">multi-lang</A>|.


						*<A NAME="v:lnum"></A><B>v:lnum</B>* *<A NAME="lnum-variable"></A><B>lnum-variable</B>*
<A HREF="#v:lnum">v:lnum</A>		Line number for the <A HREF="options.html#'foldexpr'">'foldexpr'</A> |<A HREF="fold.html#fold-expr">fold-expr</A>|, <A HREF="options.html#'formatexpr'">'formatexpr'</A> and
		<A HREF="options.html#'indentexpr'">'indentexpr'</A> expressions, <A HREF="intro.html#tab">tab</A> page number for <A HREF="options.html#'guitablabel'">'guitablabel'</A>
		and <A HREF="options.html#'guitabtooltip'">'guitabtooltip'</A>.  Only valid while one of these
		expressions is being evaluated.  Read-only when in the
		|<A HREF="#sandbox">sandbox</A>|.


					*<A NAME="v:mouse_win"></A><B>v:mouse_win</B>* *<A NAME="mouse_win-variable"></A><B>mouse_win-variable</B>*
<A HREF="#v:mouse_win">v:mouse_win</A>	Window number for a mouse click obtained with |<A HREF="#getchar()">getchar()</A>|.
		First <A HREF="windows.html#window">window</A> has number 1, like with |<A HREF="#winnr()">winnr()</A>|.  The value is
		zero when there was no mouse button click.


					*<A NAME="v:mouse_lnum"></A><B>v:mouse_lnum</B>* *<A NAME="mouse_lnum-variable"></A><B>mouse_lnum-variable</B>*
<A HREF="#v:mouse_lnum">v:mouse_lnum</A>	Line number for a mouse click obtained with |<A HREF="#getchar()">getchar()</A>|.
		This is the text line number, not the screen line number.  The
		value is zero when there was no mouse button click.


					*<A NAME="v:mouse_col"></A><B>v:mouse_col</B>* *<A NAME="mouse_col-variable"></A><B>mouse_col-variable</B>*
<A HREF="#v:mouse_col">v:mouse_col</A>	Column number for a mouse click obtained with |<A HREF="#getchar()">getchar()</A>|.
		This is the screen column number, like with |<A HREF="#virtcol()">virtcol()</A>|.  The
		value is zero when there was no mouse button click.


					*<A NAME="v:none"></A><B>v:none</B>* *<A NAME="none-variable"></A><B>none-variable</B>*
<A HREF="#v:none">v:none</A>		An empty <A HREF="#String">String</A>. Used to put an empty item in JSON.  See
		|<A HREF="#json_encode()">json_encode()</A>|.
		When used <A HREF="motion.html#as">as</A> a number this evaluates to zero.
		When used <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A> this evaluates to &quot;none&quot;.
<B>			echo v:none</B>
<B><FONT COLOR="PURPLE"> 			none </FONT></B>


					*<A NAME="v:null"></A><B>v:null</B>* *<A NAME="null-variable"></A><B>null-variable</B>*
<A HREF="#v:null">v:null</A>		An empty <A HREF="#String">String</A>. Used to put &quot;null&quot; in JSON.  See
		|<A HREF="#json_encode()">json_encode()</A>|.
		When used <A HREF="motion.html#as">as</A> a number this evaluates to zero.
		When used <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A> this evaluates to &quot;null&quot;.
<B>			echo v:null</B>
<B><FONT COLOR="PURPLE"> 			null </FONT></B>


					*<A NAME="v:oldfiles"></A><B>v:oldfiles</B>* *<A NAME="oldfiles-variable"></A><B>oldfiles-variable</B>*
<A HREF="#v:oldfiles">v:oldfiles</A>	<A HREF="#List">List</A> of file names that is loaded from the |<A HREF="starting.html#viminfo">viminfo</A>| file on
		<A HREF="starting.html#startup">startup</A>.  These are the files that Vim remembers marks for.
		The length of the <A HREF="#List">List</A> is limited by the '' argument of the
		<A HREF="options.html#'viminfo'">'viminfo'</A> option (default is 100).
		When the |<A HREF="starting.html#viminfo">viminfo</A>| file is not used the <A HREF="#List">List</A> is empty.
		Also see |<A HREF="starting.html#:oldfiles">:oldfiles</A>| and |<A HREF="cmdline.html#c_#&lt;">c_#&lt;</A>|.
		The <A HREF="#List">List</A> can be modified, but this has no effect on what is
		stored in the |<A HREF="starting.html#viminfo">viminfo</A>| file later.  If you use values other
		than <A HREF="#String">String</A> this will cause trouble.
		{only when compiled with the |<A HREF="various.html#+viminfo">+viminfo</A>| feature}


						    *<A NAME="v:option_new"></A><B>v:option_new</B>*
<A HREF="#v:option_new">v:option_new</A>    New value of the option. Valid while executing an |<A HREF="autocmd.html#OptionSet">OptionSet</A>|
		<A HREF="autocmd.html#autocommand">autocommand</A>.

						    *<A NAME="v:option_old"></A><B>v:option_old</B>*
<A HREF="#v:option_old">v:option_old</A>    Old value of the option. Valid while executing an |<A HREF="autocmd.html#OptionSet">OptionSet</A>|
		<A HREF="autocmd.html#autocommand">autocommand</A>.

						    *<A NAME="v:option_type"></A><B>v:option_type</B>*
<A HREF="#v:option_type">v:option_type</A>   Scope of the set command. Valid while executing an
		|<A HREF="autocmd.html#OptionSet">OptionSet</A>| <A HREF="autocmd.html#autocommand">autocommand</A>. Can be either &quot;global&quot; or &quot;local&quot;

					*<A NAME="v:operator"></A><B>v:operator</B>* *<A NAME="operator-variable"></A><B>operator-variable</B>*
<A HREF="#v:operator">v:operator</A>	The last <A HREF="motion.html#operator">operator</A> given in <A HREF="intro.html#Normal">Normal</A> mode.  This is a single
		character except for commands starting with &lt;g&gt; or &lt;z&gt;,
		in which <A HREF="change.html#case">case</A> <A HREF="motion.html#it">it</A> is two characters.  Best used alongside
		|<A HREF="#v:prevcount">v:prevcount</A>| and |<A HREF="#v:register">v:register</A>|.  Useful if you want to cancel
		<A HREF="intro.html#Operator-pending">Operator-pending</A> mode and then use the <A HREF="motion.html#operator">operator</A>, e.g.:
<B>			:omap O &lt;Esc&gt;:call MyMotion(v:operator)&lt;CR&gt;</B>
 		The value remains set until another <A HREF="motion.html#operator">operator</A> is entered, thus
		don't expect <A HREF="motion.html#it">it</A> to be empty.
		<A HREF="#v:operator">v:operator</A> is not set for |<A HREF="change.html#:delete">:delete</A>|, |<A HREF="change.html#:yank">:yank</A>| or other <A HREF="intro.html#Ex">Ex</A>
		commands.
		Read-only.


					*<A NAME="v:prevcount"></A><B>v:prevcount</B>* *<A NAME="prevcount-variable"></A><B>prevcount-variable</B>*
<A HREF="#v:prevcount">v:prevcount</A>	The <A HREF="intro.html#count">count</A> given for the last but one <A HREF="intro.html#Normal">Normal</A> mode command.
		This is the <A HREF="#v:count">v:count</A> value of the previous command.  Useful if
		you want to cancel <A HREF="visual.html#Visual">Visual</A> or <A HREF="intro.html#Operator-pending">Operator-pending</A> mode and then
		use the <A HREF="intro.html#count">count</A>, e.g.:
<B>			:vmap % &lt;Esc&gt;:call MyFilter(v:prevcount)&lt;CR&gt;</B>
 		Read-only.


					*<A NAME="v:profiling"></A><B>v:profiling</B>* *<A NAME="profiling-variable"></A><B>profiling-variable</B>*
<A HREF="#v:profiling">v:profiling</A>	Normally zero.	Set to one after using &quot;<A HREF="repeat.html#:profile">:profile</A> start&quot;.
		See |<A HREF="repeat.html#profiling">profiling</A>|.


					*<A NAME="v:progname"></A><B>v:progname</B>* *<A NAME="progname-variable"></A><B>progname-variable</B>*
<A HREF="#v:progname">v:progname</A>	Contains the name (with path removed) with which Vim was
		invoked.  Allows you to <A HREF="diff.html#do">do</A> special initialisations for |<A HREF="starting.html#view">view</A>|,
		|<A HREF="starting.html#evim">evim</A>| etc., or any other name you might symlink to Vim.
		Read-only.


					*<A NAME="v:progpath"></A><B>v:progpath</B>* *<A NAME="progpath-variable"></A><B>progpath-variable</B>*
<A HREF="#v:progpath">v:progpath</A>	Contains the command with which Vim was invoked, including the
		path.  Useful if you want to message a Vim server using a
		|<A HREF="remote.html#--remote-expr">--remote-expr</A>|.
		To get the full path use:
<B>			echo exepath(v:progpath)</B>
 		NOTE: This does not work when the command is a relative path
		and the current directory has changed.
		Read-only.


					*<A NAME="v:register"></A><B>v:register</B>* *<A NAME="register-variable"></A><B>register-variable</B>*
<A HREF="#v:register">v:register</A>	The name of the <A HREF="sponsor.html#register">register</A> in effect for the current normal mode
		command (regardless of whether that command actually used a
		<A HREF="sponsor.html#register">register</A>).  Or for the currently executing normal mode <A HREF="map.html#mapping">mapping</A>
		(use this in custom commands that take a <A HREF="sponsor.html#register">register</A>).
		If none is supplied <A HREF="motion.html#it">it</A> is the default <A HREF="sponsor.html#register">register</A> &#39;&#34;'', unless
		<A HREF="options.html#'clipboard'">'clipboard'</A> contains &quot;unnamed&quot; or &quot;unnamedplus&quot;, then <A HREF="motion.html#it">it</A> is
		'*' or '<A HREF="motion.html#+">+</A>'.
		Also see |<A HREF="#getreg()">getreg()</A>| and |<A HREF="#setreg()">setreg()</A>|


					*<A NAME="v:scrollstart"></A><B>v:scrollstart</B>* *<A NAME="scrollstart-variable"></A><B>scrollstart-variable</B>*
<A HREF="#v:scrollstart">v:scrollstart</A>	<A HREF="#String">String</A> describing the <A HREF="usr_41.html#script">script</A> or function that caused the
		screen to scroll up.  It's only set when <A HREF="motion.html#it">it</A> is empty, thus the
		first reason is remembered.  It is set to &quot;Unknown&quot; for a
		typed command.
		This can be used to find out why your <A HREF="usr_41.html#script">script</A> causes the
		<A HREF="message.html#hit-enter">hit-enter</A> prompt.


					*<A NAME="v:servername"></A><B>v:servername</B>* *<A NAME="servername-variable"></A><B>servername-variable</B>*
<A HREF="#v:servername">v:servername</A>	The resulting registered |<A HREF="remote.html#x11-clientserver">x11-clientserver</A>| name if any.
		Read-only.

		

<A HREF="#v:searchforward">v:searchforward</A>			*<A NAME="v:searchforward"></A><B>v:searchforward</B>* *<A NAME="searchforward-variable"></A><B>searchforward-variable</B>*
		Search direction:  1 after a forward search, 0 after a
		backward search.  It is reset to forward when directly setting
		the last search <A HREF="pattern.html#pattern">pattern</A>, see |<A HREF="change.html#quote/">quote/</A>|.
		Note that the value is restored when returning from a
		function. |<A HREF="#function-search-undo">function-search-undo</A>|.
		Read-write.


					*<A NAME="v:shell_error"></A><B>v:shell_error</B>* *<A NAME="shell_error-variable"></A><B>shell_error-variable</B>*
<A HREF="#v:shell_error">v:shell_error</A>	Result of the last shell command.  When non-zero, the last
		shell command had an error.  When zero, there was no problem.
		This only works when the shell returns the error code to Vim.
		The value -1 is often used when the command could not be
		executed.  Read-only.
		Example:
<B>	:!mv foo bar</B>
<B>	:if v:shell_error</B>
<B>	:  echo 'could not rename "foo" to "bar"!'</B>
<B>	:endif</B>
 		&quot;shell_error&quot; also works, for backwards compatibility.


					*<A NAME="v:statusmsg"></A><B>v:statusmsg</B>* *<A NAME="statusmsg-variable"></A><B>statusmsg-variable</B>*
<A HREF="#v:statusmsg">v:statusmsg</A>	Last given status message.  It's allowed to set this variable.


					*<A NAME="v:swapname"></A><B>v:swapname</B>* *<A NAME="swapname-variable"></A><B>swapname-variable</B>*
<A HREF="#v:swapname">v:swapname</A>	Only valid when executing |<A HREF="autocmd.html#SwapExists">SwapExists</A>| autocommands: Name of
		the swap file found.  Read-only.


					*<A NAME="v:swapchoice"></A><B>v:swapchoice</B>* *<A NAME="swapchoice-variable"></A><B>swapchoice-variable</B>*
<A HREF="#v:swapchoice">v:swapchoice</A>	|<A HREF="autocmd.html#SwapExists">SwapExists</A>| autocommands can set this to the selected choice
		for handling an existing swap file:
			'<A HREF="insert.html#o">o</A>'	Open read-only
			'<A HREF="motion.html#e">e</A>'	Edit anyway
			'<A HREF="change.html#r">r</A>'	Recover
			'<A HREF="change.html#d">d</A>'	Delete swapfile
			'<A HREF="repeat.html#q">q</A>'	Quit
			'<A HREF="insert.html#a">a</A>'	Abort
		The value should be a single-character <A HREF="#string">string</A>.	An empty value
		results in the user being asked, <A HREF="motion.html#as">as</A> would happen when there is
		no <A HREF="autocmd.html#SwapExists">SwapExists</A> <A HREF="autocmd.html#autocommand">autocommand</A>.  The default is empty.


					*<A NAME="v:swapcommand"></A><B>v:swapcommand</B>* *<A NAME="swapcommand-variable"></A><B>swapcommand-variable</B>*
<A HREF="#v:swapcommand">v:swapcommand</A>	<A HREF="intro.html#Normal">Normal</A> mode command to be executed after a file has been
		opened.  Can be used for a |<A HREF="autocmd.html#SwapExists">SwapExists</A>| <A HREF="autocmd.html#autocommand">autocommand</A> to have
		another Vim open the file and jump to the right place.	For
		example, when jumping to a <A HREF="tagsrch.html#tag">tag</A> the value is &quot;<A HREF="tagsrch.html#:tag">:tag</A> tagname\r&quot;.
		For &quot;<A HREF="editing.html#:edit">:edit</A> <A HREF="editing.html#+cmd">+cmd</A> file&quot; the value is &quot;:cmd\r&quot;.


				*<A NAME="v:termresponse"></A><B>v:termresponse</B>* *<A NAME="termresponse-variable"></A><B>termresponse-variable</B>*
<A HREF="#v:termresponse">v:termresponse</A>	The <A HREF="intro.html#escape">escape</A> sequence returned by the terminal for the |<A HREF="term.html#t_RV">t_RV</A>|
		<A HREF="term.html#termcap">termcap</A> entry.	It is set when Vim receives an <A HREF="intro.html#escape">escape</A> sequence
		that starts with ESC [ or CSI and ends in a '<A HREF="change.html#c">c</A>', with only
		digits, '<A HREF="motion.html#;">;</A>' and '<A HREF="repeat.html#.">.</A>' in between.
		When this option is set, the <A HREF="autocmd.html#TermResponse">TermResponse</A> <A HREF="autocmd.html#autocommand">autocommand</A> event is
		fired, so that you can react to the response from the
		terminal.
		The response from a new xterm is: &quot;&lt;Esc&gt;[ Pp ; Pv ; Pc c&quot;.  Pp
		is the terminal type: 0 for vt100 and 1 for vt220.  Pv is the
		patch level (since this was introduced in patch 95, it's
		always 95 or bigger).  Pc is always zero.
		{only when compiled with |<A HREF="various.html#+termresponse">+termresponse</A>| feature}


				*<A NAME="v:this_session"></A><B>v:this_session</B>* *<A NAME="this_session-variable"></A><B>this_session-variable</B>*
<A HREF="#v:this_session">v:this_session</A>	Full filename of the last loaded or saved session file.  See
		|<A HREF="starting.html#:mksession">:mksession</A>|.  It is allowed to set this variable.  When no
		session file has been saved, this variable is empty.
		&quot;this_session&quot; also works, for backwards compatibility.


					*<A NAME="v:throwpoint"></A><B>v:throwpoint</B>* *<A NAME="throwpoint-variable"></A><B>throwpoint-variable</B>*
<A HREF="#v:throwpoint">v:throwpoint</A>	The point where the exception most recently caught and not
		finished was thrown.  Not set when commands are typed.	See
		also |<A HREF="#v:exception">v:exception</A>| and |<A HREF="#throw-variables">throw-variables</A>|.
		Example:
<B>	:try</B>
<B>	:  throw "oops"</B>
<B>	:catch /.*/</B>
<B>	:  echo "Exception from" v:throwpoint</B>
<B>	:endtry</B>
 		Output: &quot;Exception from test.vim, line 2&quot;


						*<A NAME="v:true"></A><B>v:true</B>* *<A NAME="true-variable"></A><B>true-variable</B>*
<A HREF="#v:true">v:true</A>		A <A HREF="#Number">Number</A> with value one. Used to put &quot;true&quot; in JSON.  See
		|<A HREF="#json_encode()">json_encode()</A>|.
		When used <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A> this evaluates to &quot;true&quot;.
<B>			echo v:true</B>
<B><FONT COLOR="PURPLE"> 			true </FONT></B>

						*<A NAME="v:val"></A><B>v:val</B>* *<A NAME="val-variable"></A><B>val-variable</B>*
<A HREF="#v:val">v:val</A>		Value of the current item of a |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>|.	Only
		valid while evaluating the <A HREF="#expression">expression</A> used with |<A HREF="#map()">map()</A>| and
		|<A HREF="#filter()">filter()</A>|.  Read-only.


					*<A NAME="v:version"></A><B>v:version</B>* *<A NAME="version-variable"></A><B>version-variable</B>*
<A HREF="#v:version">v:version</A>	Version number of Vim: Major version number times 100 plus
		minor version number.  Version 5.0 is 500.  Version 5.1 (5.01)
		is 501.  Read-only.  &quot;version&quot; also works, for backwards
		compatibility.
		Use |<A HREF="#has()">has()</A>| to check if a certain patch was included, e.g.:
<B>			if has("patch-7.4.123")</B>
 		Note that patch numbers are specific to the version, thus both
		version 5.0 and 5.1 may have a patch 123, but these are
		completely different.


				*<A NAME="v:vim_did_enter"></A><B>v:vim_did_enter</B>* *<A NAME="vim_did_enter-variable"></A><B>vim_did_enter-variable</B>*
<A HREF="#v:vim_did_enter">v:vim_did_enter</A>	Zero until most of <A HREF="starting.html#startup">startup</A> is done.  It is set to one just
		before |<A HREF="autocmd.html#VimEnter">VimEnter</A>| autocommands are triggered.


					*<A NAME="v:warningmsg"></A><B>v:warningmsg</B>* *<A NAME="warningmsg-variable"></A><B>warningmsg-variable</B>*
<A HREF="#v:warningmsg">v:warningmsg</A>	Last given warning message.  It's allowed to set this variable.


					*<A NAME="v:windowid"></A><B>v:windowid</B>* *<A NAME="windowid-variable"></A><B>windowid-variable</B>*
<A HREF="#v:windowid">v:windowid</A>	When any <A HREF="options.html#X11">X11</A> based <A HREF="gui.html#GUI">GUI</A> is running or when running in a
		terminal and Vim connects to the X server (|<A HREF="starting.html#-X">-X</A>|) this will be
		set to the <A HREF="windows.html#window">window</A> ID.
		When an <A HREF="os_win32.html#MS-Windows">MS-Windows</A> <A HREF="gui.html#GUI">GUI</A> is running this will be set to the
		<A HREF="windows.html#window">window</A> handle.
		Otherwise the value is zero.
		Note: for <A HREF="windows.html#windows">windows</A> inside Vim use |<A HREF="#winnr()">winnr()</A>|.

==============================================================================

4. Builtin Functions					*<A NAME="functions"></A><B>functions</B>*

See |<A HREF="usr_41.html#function-list">function-list</A>| for a list grouped by what the function is used for.

(Use <A HREF="tagsrch.html#CTRL-]">CTRL-]</A> on the function name to jump to the full explanation.)

<B><FONT COLOR="PURPLE">USAGE				RESULT	DESCRIPTION	</FONT></B>

abs( {expr})			<A HREF="#Float">Float</A> or <A HREF="#Number">Number</A>  absolute value of {expr}
acos( {expr})			<A HREF="#Float">Float</A>	arc cosine of {expr}
add( {list}, {item})		List	append {item} to |<A HREF="#List">List</A>| {list}
alloc_fail( {id}, {countdown}, {repeat})
				none	make memory allocation fail
and( {expr}, {expr})		<A HREF="#Number">Number</A>  bitwise AND
append( {lnum}, {string})	<A HREF="#Number">Number</A>	append {string} below line {lnum}
append( {lnum}, {list})		<A HREF="#Number">Number</A>	append lines {list} below line {lnum}
<A HREF="#argc()">argc()</A>				<A HREF="#Number">Number</A>	number of files in the argument <A HREF="#list">list</A>
<A HREF="#argidx()">argidx()</A>			<A HREF="#Number">Number</A>	current index in the argument <A HREF="#list">list</A>
arglistid( [{winnr} [, {tabnr}]])
				<A HREF="#Number">Number</A>	argument <A HREF="#list">list</A> id
argv( {nr})			<A HREF="#String">String</A>	{nr} entry of the argument <A HREF="#list">list</A>
<A HREF="#argv()">argv()</A>				<A HREF="#List">List</A>	the argument <A HREF="#list">list</A>
assert_equal( {exp}, {act} [, {msg}]) none  assert {exp} equals {act}
assert_exception( {error} [, {msg}])  none  assert {error} is in <A HREF="#v:exception">v:exception</A>
assert_fails( {cmd} [, {error}])      none  assert {cmd} fails
assert_false( {actual} [, {msg}])     none  assert {actual} is false
assert_match( <A HREF="autocmd.html#{pat}">{pat}</A>, {text} [, {msg}]) none  assert <A HREF="autocmd.html#{pat}">{pat}</A> matches {text}
assert_true( {actual} [, {msg}])      none  assert {actual} is true
asin( {expr})			<A HREF="#Float">Float</A>	arc sine of {expr}
atan( {expr})			<A HREF="#Float">Float</A>	arc tangent of {expr}
atan2( {expr}, {expr})		<A HREF="#Float">Float</A>   arc tangent of {expr1} / {expr2}
browse( {save}, {title}, {initdir}, {default})
				<A HREF="#String">String</A>	put up a file requester
browsedir( {title}, {initdir})	<A HREF="#String">String</A>	put up a directory requester
bufexists( {expr})		<A HREF="#Number">Number</A>	TRUE if buffer {expr} exists
buflisted( {expr})		<A HREF="#Number">Number</A>	TRUE if buffer {expr} is listed
bufloaded( {expr})		<A HREF="#Number">Number</A>	TRUE if buffer {expr} is loaded
bufname( {expr})		<A HREF="#String">String</A>	Name of the buffer {expr}
bufnr( {expr} [, {create}])	<A HREF="#Number">Number</A>	<A HREF="#Number">Number</A> of the buffer {expr}
bufwinnr( {expr})		<A HREF="#Number">Number</A>	<A HREF="windows.html#window">window</A> number of buffer {expr}
byte2line( {byte})		<A HREF="#Number">Number</A>	line number at byte <A HREF="intro.html#count">count</A> {byte}
byteidx( {expr}, {nr})		<A HREF="#Number">Number</A>	byte index of {nr}'th char in {expr}
byteidxcomp( {expr}, {nr})	<A HREF="#Number">Number</A>	byte index of {nr}'th char in {expr}
call( {func}, <A HREF="editing.html#{arglist}">{arglist}</A> [, {dict}])
				any	call {func} with arguments <A HREF="editing.html#{arglist}">{arglist}</A>
ceil( {expr})			<A HREF="#Float">Float</A>	round {expr} up
ch_close( {handle})		none	close {handle}
ch_evalexpr( {handle}, {expr} [, {options}])
				any	evaluate {expr} on JSON {handle}
ch_evalraw( {handle}, {string} [, {options}])
				any	evaluate {string} on raw {handle}
ch_getbufnr( {handle}, {what})	<A HREF="#Number">Number</A>	get buffer number for {handle}/{what}
ch_getjob( {channel})		<A HREF="#Job">Job</A>	get the <A HREF="#Job">Job</A> of {channel}
ch_info( {handle})		<A HREF="#String">String</A>	info about <A HREF="channel.html#channel">channel</A>  {handle}
ch_log( {msg} [, {handle}])	none	write {msg} in the <A HREF="channel.html#channel">channel</A> log file
ch_logfile( {fname} [, {mode}])	none	start logging <A HREF="channel.html#channel">channel</A> activity
ch_open( <A HREF="cmdline.html#{address}">{address}</A> [, {options}]) <A HREF="#Channel">Channel</A> open a <A HREF="channel.html#channel">channel</A> to <A HREF="cmdline.html#{address}">{address}</A>
ch_read( {handle} [, {options}])  <A HREF="#String">String</A>  read from  {handle}
ch_readraw( {handle} [, {options}])  <A HREF="#String">String</A>  read raw from  {handle}
ch_sendexpr( {handle}, {expr} [, {options}])
				any	send {expr} over JSON {handle}
ch_sendraw( {handle}, {string} [, {options}])
				any	send {string} over raw {handle}
ch_setoptions( {handle}, {options})  none  set <A HREF="options.html#options">options</A> for {handle}
ch_status( {handle})		<A HREF="#String">String</A>	status of <A HREF="channel.html#channel">channel</A>  {handle}
<A HREF="#changenr()">changenr()</A>			<A HREF="#Number">Number</A>	current change number
char2nr( {expr}[, {utf8}])	<A HREF="#Number">Number</A>	ASCII/UTF8 value of first char in {expr}
cindent( {lnum})		<A HREF="#Number">Number</A>	C indent for line {lnum}
<A HREF="#clearmatches()">clearmatches()</A>			none	clear all matches
col( {expr})			<A HREF="#Number">Number</A>	column nr of cursor or <A HREF="motion.html#mark">mark</A>
complete( {startcol}, {matches}) none	set <A HREF="insert.html#Insert">Insert</A> mode completion
complete_add( {expr})		<A HREF="#Number">Number</A>	add completion match
<A HREF="#complete_check()">complete_check()</A>		<A HREF="#Number">Number</A>	check for key typed during completion
confirm( {msg} [, {choices} [, {default} [, {type}]]])
				<A HREF="#Number">Number</A>	number of choice picked by user
copy( {expr})			any	make a shallow copy of {expr}
cos( {expr})			<A HREF="#Float">Float</A>	cosine of {expr}
cosh( {expr})			<A HREF="#Float">Float</A>	hyperbolic cosine of {expr}
count( {list}, {expr} [, {ic} [, {start}]])
				<A HREF="#Number">Number</A>	 <A HREF="intro.html#count">count</A> how many {expr} are in {list}
cscope_connection( [{num} , {dbpath} [, {prepend}]])
				<A HREF="#Number">Number</A>	checks existence of <A HREF="if_cscop.html#cscope">cscope</A> connection
cursor( {lnum}, {col} [, {off}])
				<A HREF="#Number">Number</A>	move cursor to {lnum}, {col}, {off}
cursor( {list})			<A HREF="#Number">Number</A>	move cursor to position in {list}
deepcopy( {expr} [, {noref}])	any	make a full copy of {expr}
delete( {fname} [, {flags}])	<A HREF="#Number">Number</A>	delete the file or directory {fname}
<A HREF="#did_filetype()">did_filetype()</A>			<A HREF="#Number">Number</A>	TRUE if <A HREF="autocmd.html#FileType">FileType</A> <A HREF="autocmd.html#autocommand">autocommand</A> event used
diff_filler( {lnum})		<A HREF="#Number">Number</A>	<A HREF="diff.html#diff">diff</A> filler lines about {lnum}
diff_hlID( {lnum}, {col})	<A HREF="#Number">Number</A>	<A HREF="diff.html#diff">diff</A> highlighting at {lnum}/{col}
disable_char_avail_for_testing( {expr})  none  test without typeahead
empty( {expr})			<A HREF="#Number">Number</A>	TRUE if {expr} is empty
escape( {string}, {chars})	<A HREF="#String">String</A>	<A HREF="intro.html#escape">escape</A> {chars} in {string} with '\'
eval( {string})			any	evaluate {string} into its value
<A HREF="#eventhandler()">eventhandler()</A>			<A HREF="#Number">Number</A>	TRUE if inside an event handler
executable( {expr})		<A HREF="#Number">Number</A>	1 if executable {expr} exists
exepath( {expr})		<A HREF="#String">String</A>  full path of the command {expr}
exists( {expr})			<A HREF="#Number">Number</A>	TRUE if {expr} exists
extend( {expr1}, {expr2} [, {expr3}])
				List/Dict insert items of {expr2} into {expr1}
exp( {expr})			<A HREF="#Float">Float</A>	exponential of {expr}
expand( {expr} [, {nosuf} [, {list}]])
				any	expand special keywords in {expr}
feedkeys( {string} [, {mode}])	<A HREF="#Number">Number</A>	add key sequence to typeahead buffer
filereadable( <A HREF="editing.html#{file}">{file}</A>)		<A HREF="#Number">Number</A>	TRUE if <A HREF="editing.html#{file}">{file}</A> is a readable file
filewritable( <A HREF="editing.html#{file}">{file}</A>)		<A HREF="#Number">Number</A>	TRUE if <A HREF="editing.html#{file}">{file}</A> is a writable file
filter( {expr}, {string})	List/Dict  remove items from {expr} where
					{string} is 0
finddir( {name}[, {path}[, {count}]])
				<A HREF="#String">String</A>	find directory {name} in {path}
findfile( {name}[, {path}[, {count}]])
				<A HREF="#String">String</A>	find file {name} in {path}
float2nr( {expr})		<A HREF="#Number">Number</A>	convert <A HREF="#Float">Float</A> {expr} to a <A HREF="#Number">Number</A>
floor( {expr})			<A HREF="#Float">Float</A>	round {expr} down
fmod( {expr1}, {expr2})		<A HREF="#Float">Float</A>	remainder of {expr1} / {expr2}
fnameescape( {fname})		<A HREF="#String">String</A>	<A HREF="intro.html#escape">escape</A> special characters in {fname}
fnamemodify( {fname}, {mods})	<A HREF="#String">String</A>	modify file name
foldclosed( {lnum})		<A HREF="#Number">Number</A>	first line of fold at {lnum} if closed
foldclosedend( {lnum})		<A HREF="#Number">Number</A>	last line of fold at {lnum} if closed
foldlevel( {lnum})		<A HREF="#Number">Number</A>	fold level at {lnum}
<A HREF="#foldtext()">foldtext()</A>			<A HREF="#String">String</A>	line displayed for closed fold
foldtextresult( {lnum})		<A HREF="#String">String</A>	text for closed fold at {lnum}
<A HREF="#foreground()">foreground()</A>			<A HREF="#Number">Number</A>	bring the Vim <A HREF="windows.html#window">window</A> to the foreground
function({name} [, {arglist}] [, {dict}])
				<A HREF="#Funcref">Funcref</A> reference to function {name}
garbagecollect( [{atexit}])	none	free memory, breaking cyclic references
get( {list}, {idx} [, {def}])	any	get item {idx} from {list} or {def}
get( {dict}, {key} [, {def}])	any	get item {key} from {dict} or {def}
getbufline( {expr}, {lnum} [, {end}])
				<A HREF="#List">List</A>	lines {lnum} to {end} of buffer {expr}
getbufvar( {expr}, {varname} [, {def}])
				any	variable {varname} in buffer {expr}
getchar( [expr])		<A HREF="#Number">Number</A>	get one character from the user
<A HREF="#getcharmod()">getcharmod()</A>			<A HREF="#Number">Number</A>	modifiers for the last typed character
<A HREF="#getcharsearch()">getcharsearch()</A>			Dict	last character search
<A HREF="#getcmdline()">getcmdline()</A>			<A HREF="#String">String</A>	return the current command-line
<A HREF="#getcmdpos()">getcmdpos()</A>			<A HREF="#Number">Number</A>	return cursor position in command-line
<A HREF="#getcmdtype()">getcmdtype()</A>			<A HREF="#String">String</A>	return current command-line type
<A HREF="#getcmdwintype()">getcmdwintype()</A>			<A HREF="#String">String</A>	return current command-line <A HREF="windows.html#window">window</A> type
<A HREF="#getcurpos()">getcurpos()</A>			<A HREF="#List">List</A>	position of the cursor
getcwd( [{winnr} [, {tabnr}]])	<A HREF="#String">String</A>	get the current working directory
getfontname( [{name}])		<A HREF="#String">String</A>	name of font being used
getfperm( {fname})		<A HREF="#String">String</A>	file permissions of file {fname}
getfsize( {fname})		<A HREF="#Number">Number</A>	size in bytes of file {fname}
getftime( {fname})		<A HREF="#Number">Number</A>	last modification time of file
getftype( {fname})		<A HREF="#String">String</A>	description of type of file {fname}
getline( {lnum})		<A HREF="#String">String</A>	line {lnum} of current buffer
getline( {lnum}, {end})		<A HREF="#List">List</A>	lines {lnum} to {end} of current buffer
getloclist( {nr})		<A HREF="#List">List</A>	<A HREF="#list">list</A> of location <A HREF="#list">list</A> items
<A HREF="#getmatches()">getmatches()</A>			<A HREF="#List">List</A>	<A HREF="#list">list</A> of current matches
<A HREF="#getpid()">getpid()</A>			<A HREF="#Number">Number</A>	process ID of Vim
getpos( {expr})			<A HREF="#List">List</A>	position of cursor, <A HREF="motion.html#mark">mark</A>, etc.
<A HREF="#getqflist()">getqflist()</A>			<A HREF="#List">List</A>	<A HREF="#list">list</A> of <A HREF="quickfix.html#quickfix">quickfix</A> items
getreg( [{regname} [, 1 [, {list}]]])
				<A HREF="#String">String</A> or <A HREF="#List">List</A>   contents of <A HREF="sponsor.html#register">register</A>
getregtype( [{regname}])	<A HREF="#String">String</A>	type of <A HREF="sponsor.html#register">register</A>
gettabvar( {nr}, {varname} [, {def}])
				any	variable {varname} in <A HREF="intro.html#tab">tab</A> {nr} or {def}
gettabwinvar( {tabnr}, {winnr}, {name} [, {def}])
				any	{name} in {winnr} in <A HREF="intro.html#tab">tab</A> page {tabnr}
<A HREF="#getwinposx()">getwinposx()</A>			<A HREF="#Number">Number</A>	X coord in pixels of <A HREF="gui.html#GUI">GUI</A> Vim <A HREF="windows.html#window">window</A>
<A HREF="#getwinposy()">getwinposy()</A>			<A HREF="#Number">Number</A>	<A HREF="change.html#Y">Y</A> coord in pixels of <A HREF="gui.html#GUI">GUI</A> Vim <A HREF="windows.html#window">window</A>
getwinvar( {nr}, {varname} [, {def}])
				any	variable {varname} in <A HREF="windows.html#window">window</A> {nr}
glob( {expr} [, {nosuf} [, {list} [, {alllinks}]]])
				any	expand file <A HREF="editing.html#wildcards">wildcards</A> in {expr}
glob2regpat( {expr})		<A HREF="#String">String</A>  convert a glob pat into a search pat
globpath( {path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
				<A HREF="#String">String</A>	<A HREF="diff.html#do">do</A> glob({expr}) for all dirs in {path}
has( {feature})			<A HREF="#Number">Number</A>	TRUE if feature {feature} supported
has_key( {dict}, {key})		<A HREF="#Number">Number</A>	TRUE if {dict} has entry {key}
haslocaldir( [{winnr} [, {tabnr}]])
				<A HREF="#Number">Number</A>	TRUE if the <A HREF="windows.html#window">window</A> executed |<A HREF="editing.html#:lcd">:lcd</A>|
hasmapto( {what} [, {mode} [, {abbr}]])
				<A HREF="#Number">Number</A>	TRUE if <A HREF="map.html#mapping">mapping</A> to {what} exists
histadd( {history}, {item})	<A HREF="#String">String</A>	add an item to a <A HREF="cmdline.html#history">history</A>
histdel( {history} [, {item}])	<A HREF="#String">String</A>	remove an item from a <A HREF="cmdline.html#history">history</A>
histget( {history} [, {index}])	<A HREF="#String">String</A>	get the item {index} from a <A HREF="cmdline.html#history">history</A>
histnr( {history})		<A HREF="#Number">Number</A>	highest index of a <A HREF="cmdline.html#history">history</A>
hlexists( {name})		<A HREF="#Number">Number</A>	TRUE if highlight group {name} exists
hlID( {name})			<A HREF="#Number">Number</A>	<A HREF="syntax.html#syntax">syntax</A> ID of highlight group {name}
<A HREF="#hostname()">hostname()</A>			<A HREF="#String">String</A>	name of the machine Vim is running on
iconv( {expr}, {from}, {to})	<A HREF="#String">String</A>	convert encoding of {expr}
indent( {lnum})			<A HREF="#Number">Number</A>	indent of line {lnum}
index( {list}, {expr} [, {start} [, {ic}]])
				<A HREF="#Number">Number</A>	index in {list} where {expr} appears
input( {prompt} [, {text} [, {completion}]])
				<A HREF="#String">String</A>	get input from the user
inputdialog( {p} [, {t} [, {c}]]) <A HREF="#String">String</A>  like <A HREF="#input()">input()</A> but in a <A HREF="gui.html#GUI">GUI</A> <A HREF="gui_w32.html#dialog">dialog</A>
inputlist( {textlist})		<A HREF="#Number">Number</A>	let the user pick from a choice <A HREF="#list">list</A>
<A HREF="#inputrestore()">inputrestore()</A>			<A HREF="#Number">Number</A>	restore typeahead
<A HREF="#inputsave()">inputsave()</A>			<A HREF="#Number">Number</A>	save and clear typeahead
inputsecret( {prompt} [, {text}]) <A HREF="#String">String</A>  like <A HREF="#input()">input()</A> but hiding the text
insert( {list}, {item} [, {idx}]) <A HREF="#List">List</A>	insert {item} in {list} [before {idx}]
invert( {expr})			<A HREF="#Number">Number</A>  bitwise invert
isdirectory( {directory})	<A HREF="#Number">Number</A>	TRUE if {directory} is a directory
islocked( {expr})		<A HREF="#Number">Number</A>	TRUE if {expr} is locked
isnan( {expr})			<A HREF="#Number">Number</A>  TRUE if {expr} is NaN
items( {dict})			<A HREF="#List">List</A>	key-value pairs in {dict}
job_getchannel( {job})		<A HREF="#Channel">Channel</A>	get the <A HREF="channel.html#channel">channel</A> handle for {job}
job_info( {job})		Dict	get information about {job}
job_setoptions( {job}, {options}) none	set <A HREF="options.html#options">options</A> for {job}
job_start( {command} [, {options}]) <A HREF="#Job">Job</A>	 start a <A HREF="channel.html#job">job</A>
job_status( {job})		<A HREF="#String">String</A>	get the status of {job}
job_stop( {job} [, {how}])	<A HREF="#Number">Number</A>	stop {job}
join( {list} [, {sep}])		<A HREF="#String">String</A>	join {list} items into one <A HREF="#String">String</A>
js_decode( {string})		any	decode JS style JSON
js_encode( {expr})		<A HREF="#String">String</A>	encode JS style JSON
json_decode( {string})		any	decode JSON
json_encode( {expr})		<A HREF="#String">String</A>	encode JSON
keys( {dict})			<A HREF="#List">List</A>	keys in {dict}
len( {expr})			<A HREF="#Number">Number</A>	the length of {expr}
libcall( {lib}, {func}, {arg})	<A HREF="#String">String</A>	call {func} in library {lib} with {arg}
libcallnr( {lib}, {func}, {arg})  <A HREF="#Number">Number</A>  idem, but return a <A HREF="#Number">Number</A>
line( {expr})			<A HREF="#Number">Number</A>	line nr of cursor, last line or <A HREF="motion.html#mark">mark</A>
line2byte( {lnum})		<A HREF="#Number">Number</A>	byte <A HREF="intro.html#count">count</A> of line {lnum}
lispindent( {lnum})		<A HREF="#Number">Number</A>	Lisp indent for line {lnum}
<A HREF="#localtime()">localtime()</A>			<A HREF="#Number">Number</A>	current time
log( {expr})			<A HREF="#Float">Float</A>	natural logarithm (base <A HREF="motion.html#e">e</A>) of {expr}
log10( {expr})			<A HREF="#Float">Float</A>	logarithm of <A HREF="#Float">Float</A> {expr} to base 10
luaeval( {expr}[, {expr}])	any	evaluate |<A HREF="if_lua.html#Lua">Lua</A>| <A HREF="#expression">expression</A>
map( {expr}, {string})		List/Dict  change each item in {expr} to {expr}
maparg( {name}[, {mode} [, {abbr} [, {dict}]]])
				<A HREF="#String">String</A> or Dict
					rhs of <A HREF="map.html#mapping">mapping</A> {name} in mode {mode}
mapcheck( {name}[, {mode} [, {abbr}]])
				<A HREF="#String">String</A>	check for mappings matching {name}
match( {expr}, {pat}[, {start}[, {count}]])
				<A HREF="#Number">Number</A>	position where <A HREF="autocmd.html#{pat}">{pat}</A> matches in {expr}
matchadd( {group}, {pattern}[, {priority}[, {id} [, {dict}]]])
				<A HREF="#Number">Number</A>	highlight {pattern} with {group}
matchaddpos( {group}, {pos}[, {priority}[, {id}[, {dict}]]])
				<A HREF="#Number">Number</A>	highlight positions with {group}
matcharg( {nr})			<A HREF="#List">List</A>	arguments of |<A HREF="pattern.html#:match">:match</A>|
matchdelete( {id})		<A HREF="#Number">Number</A>	delete match identified by {id}
matchend( {expr}, {pat}[, {start}[, {count}]])
				<A HREF="#Number">Number</A>	position where <A HREF="autocmd.html#{pat}">{pat}</A> ends in {expr}
matchlist( {expr}, {pat}[, {start}[, {count}]])
				<A HREF="#List">List</A>	match and submatches of <A HREF="autocmd.html#{pat}">{pat}</A> in {expr}
matchstr( {expr}, {pat}[, {start}[, {count}]])
				<A HREF="#String">String</A>	{count}'th match of <A HREF="autocmd.html#{pat}">{pat}</A> in {expr}
matchstrpos( {expr}, {pat}[, {start}[, {count}]])
				<A HREF="#List">List</A>	{count}'th match of <A HREF="autocmd.html#{pat}">{pat}</A> in {expr}
max( {list})			<A HREF="#Number">Number</A>	maximum value of items in {list}
min( {list})			<A HREF="#Number">Number</A>	minimum value of items in {list}
mkdir( {name} [, {path} [, {prot}]])
				<A HREF="#Number">Number</A>	create directory {name}
mode( [expr])			<A HREF="#String">String</A>	current editing mode
mzeval( {expr})			any	evaluate |<A HREF="if_mzsch.html#MzScheme">MzScheme</A>| <A HREF="#expression">expression</A>
nextnonblank( {lnum})		<A HREF="#Number">Number</A>	line nr of non-blank line &gt;= {lnum}
nr2char( {expr}[, {utf8}])	<A HREF="#String">String</A>	single char with ASCII/UTF8 value {expr}
or( {expr}, {expr})		<A HREF="#Number">Number</A>  bitwise OR
pathshorten( {expr})		<A HREF="#String">String</A>	shorten directory names in a path
perleval( {expr})		any	evaluate |<A HREF="if_perl.html#Perl">Perl</A>| <A HREF="#expression">expression</A>
pow( {x}, {y})			<A HREF="#Float">Float</A>	{x} to the power of {y}
prevnonblank( {lnum})		<A HREF="#Number">Number</A>	line nr of non-blank line &lt;= {lnum}
printf( {fmt}, {expr1}...)	<A HREF="#String">String</A>	format text
<A HREF="#pumvisible()">pumvisible()</A>			<A HREF="#Number">Number</A>	whether popup menu is visible
pyeval( {expr})			any	evaluate |<A HREF="if_pyth.html#Python">Python</A>| <A HREF="#expression">expression</A>
py3eval( {expr})		any	evaluate |<A HREF="if_pyth.html#python3">python3</A>| <A HREF="#expression">expression</A>
range( {expr} [, {max} [, {stride}]])
				<A HREF="#List">List</A>	items from {expr} to {max}
readfile( {fname} [, {binary} [, {max}]])
				<A HREF="#List">List</A>	get <A HREF="#list">list</A> of lines from file {fname}
reltime( [{start} [, {end}]])	<A HREF="#List">List</A>	get time value
reltimestr( {time})		<A HREF="#String">String</A>	turn time value into a <A HREF="#String">String</A>
remote_expr( {server}, {string} [, {idvar}])
				<A HREF="#String">String</A>	send <A HREF="#expression">expression</A>
remote_foreground( {server})	<A HREF="#Number">Number</A>	bring Vim server to the foreground
remote_peek( {serverid} [, {retvar}])
				<A HREF="#Number">Number</A>	check for reply <A HREF="#string">string</A>
remote_read( {serverid})	<A HREF="#String">String</A>	read reply <A HREF="#string">string</A>
remote_send( {server}, {string} [, {idvar}])
				<A HREF="#String">String</A>	send key sequence
remove( {list}, {idx} [, {end}])  any	remove items {idx}-{end} from {list}
remove( {dict}, {key})		any	remove entry {key} from {dict}
rename( {from}, {to})		<A HREF="#Number">Number</A>	rename (move) file from {from} to {to}
repeat( {expr}, {count})	<A HREF="#String">String</A>	repeat {expr} {count} times
resolve( {filename})		<A HREF="#String">String</A>	get filename a shortcut points to
reverse( {list})		<A HREF="#List">List</A>	reverse {list} in-place
round( {expr})			<A HREF="#Float">Float</A>	round off {expr}
screenattr( {row}, {col})	<A HREF="#Number">Number</A>	attribute at screen position
screenchar( {row}, {col})	<A HREF="#Number">Number</A>	character at screen position
<A HREF="#screencol()">screencol()</A>			<A HREF="#Number">Number</A>	current cursor column
<A HREF="#screenrow()">screenrow()</A>			<A HREF="#Number">Number</A>	current cursor row
search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
				<A HREF="#Number">Number</A>	search for {pattern}
searchdecl( {name} [, {global} [, {thisblock}]])
				<A HREF="#Number">Number</A>	search for variable declaration
searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
				<A HREF="#Number">Number</A>	search for other end of start/end pair
searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
				<A HREF="#List">List</A>	search for other end of start/end pair
searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
				<A HREF="#List">List</A>	search for {pattern}
server2client( {clientid}, {string})
				<A HREF="#Number">Number</A>	send reply <A HREF="#string">string</A>
<A HREF="#serverlist()">serverlist()</A>			<A HREF="#String">String</A>	get a <A HREF="#list">list</A> of available servers
setbufvar( {expr}, {varname}, {val})	set {varname} in buffer {expr} to {val}
setcharsearch( {dict})		Dict	set character search from {dict}
setcmdpos( {pos})		<A HREF="#Number">Number</A>	set cursor position in command-line
setfperm( {fname}, {mode})	<A HREF="#Number">Number</A>	set {fname} file permissions to {mode}
setline( {lnum}, {line})	<A HREF="#Number">Number</A>	set line {lnum} to {line}
setloclist( {nr}, {list}[, {action}])
				<A HREF="#Number">Number</A>	modify location <A HREF="#list">list</A> using {list}
setmatches( {list})		<A HREF="#Number">Number</A>	restore a <A HREF="#list">list</A> of matches
setpos( {expr}, {list})		<A HREF="#Number">Number</A>	set the {expr} position to {list}
setqflist( {list}[, {action}])	<A HREF="#Number">Number</A>	modify <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A> using {list}
setreg( {n}, {v}[, {opt}])	<A HREF="#Number">Number</A>	set <A HREF="sponsor.html#register">register</A> to value and type
settabvar( {nr}, {varname}, {val})	set {varname} in <A HREF="intro.html#tab">tab</A> page {nr} to {val}
settabwinvar( {tabnr}, {winnr}, {varname}, {val})    set {varname} in <A HREF="windows.html#window">window</A>
					{winnr} in <A HREF="intro.html#tab">tab</A> page {tabnr} to {val}
setwinvar( {nr}, {varname}, {val})	set {varname} in <A HREF="windows.html#window">window</A> {nr} to {val}
sha256( {string})		<A HREF="#String">String</A>	SHA256 checksum of {string}
shellescape( {string} [, {special}])
				<A HREF="#String">String</A>	<A HREF="intro.html#escape">escape</A> {string} for use <A HREF="motion.html#as">as</A> shell
					command argument
<A HREF="#shiftwidth()">shiftwidth()</A>			<A HREF="#Number">Number</A>	effective value of <A HREF="options.html#'shiftwidth'">'shiftwidth'</A>
simplify( {filename})		<A HREF="#String">String</A>	simplify filename <A HREF="motion.html#as">as</A> much <A HREF="motion.html#as">as</A> possible
sin( {expr})			<A HREF="#Float">Float</A>	sine of {expr}
sinh( {expr})			<A HREF="#Float">Float</A>	hyperbolic sine of {expr}
sort( {list} [, {func} [, {dict}]])
				<A HREF="#List">List</A>	sort {list}, using {func} to compare
soundfold( {word})		<A HREF="#String">String</A>	sound-fold {word}
<A HREF="#spellbadword()">spellbadword()</A>			<A HREF="#String">String</A>	badly spelled <A HREF="motion.html#word">word</A> at cursor
spellsuggest( {word} [, {max} [, {capital}]])
				<A HREF="#List">List</A>	spelling suggestions
split( {expr} [, <A HREF="autocmd.html#{pat}">{pat}</A> [, {keepempty}]])
				List	make |<A HREF="#List">List</A>| from <A HREF="autocmd.html#{pat}">{pat}</A> separated {expr}
sqrt( {expr})			<A HREF="#Float">Float</A>	square root of {expr}
str2float( {expr})		<A HREF="#Float">Float</A>	convert <A HREF="#String">String</A> to <A HREF="#Float">Float</A>
str2nr( {expr} [, {base}])	<A HREF="#Number">Number</A>	convert <A HREF="#String">String</A> to <A HREF="#Number">Number</A>
strchars( {expr} [, {skipcc}])	<A HREF="#Number">Number</A>	character length of the <A HREF="#String">String</A> {expr}
strdisplaywidth( {expr} [, {col}]) <A HREF="#Number">Number</A> display length of the <A HREF="#String">String</A> {expr}
strftime( {format}[, {time}])	<A HREF="#String">String</A>	time in specified format
stridx( {haystack}, {needle}[, {start}])
				<A HREF="#Number">Number</A>	index of {needle} in {haystack}
string( {expr})			<A HREF="#String">String</A>	<A HREF="#String">String</A> representation of {expr} value
strlen( {expr})			<A HREF="#Number">Number</A>	length of the <A HREF="#String">String</A> {expr}
strpart( {src}, {start}[, {len}])
				<A HREF="#String">String</A>	{len} characters of {src} at {start}
strridx( {haystack}, {needle} [, {start}])
				<A HREF="#Number">Number</A>	last index of {needle} in {haystack}
strtrans( {expr})		<A HREF="#String">String</A>	translate <A HREF="#string">string</A> to make <A HREF="motion.html#it">it</A> printable
strwidth( {expr})		<A HREF="#Number">Number</A>	display cell length of the <A HREF="#String">String</A> {expr}
submatch( {nr}[, {list}])	<A HREF="#String">String</A> or <A HREF="#List">List</A>
					specific match in &quot;<A HREF="change.html#:s">:s</A>&quot; or <A HREF="#substitute()">substitute()</A>
substitute( {expr}, <A HREF="autocmd.html#{pat}">{pat}</A>, {sub}, {flags})
				<A HREF="#String">String</A>	all <A HREF="autocmd.html#{pat}">{pat}</A> in {expr} replaced with {sub}
synID( {lnum}, {col}, {trans})	<A HREF="#Number">Number</A>	<A HREF="syntax.html#syntax">syntax</A> ID at {lnum} and {col}
synIDattr( {synID}, {what} [, {mode}])
				<A HREF="#String">String</A>	attribute {what} of <A HREF="syntax.html#syntax">syntax</A> ID {synID}
synIDtrans( {synID})		<A HREF="#Number">Number</A>	translated <A HREF="syntax.html#syntax">syntax</A> ID of {synID}
synconcealed( {lnum}, {col})	<A HREF="#List">List</A>    info about concealing
synstack( {lnum}, {col})	<A HREF="#List">List</A>	stack of <A HREF="syntax.html#syntax">syntax</A> IDs at {lnum} and {col}
system( {expr} [, {input}])	<A HREF="#String">String</A>	output of shell command/filter {expr}
systemlist( {expr} [, {input}])	<A HREF="#List">List</A>	output of shell command/filter {expr}
tabpagebuflist( [{arg}])	<A HREF="#List">List</A>	<A HREF="#list">list</A> of buffer numbers in <A HREF="intro.html#tab">tab</A> page
tabpagenr( [{arg}])		<A HREF="#Number">Number</A>	number of current or last <A HREF="intro.html#tab">tab</A> page
tabpagewinnr( {tabarg}[, {arg}])
				<A HREF="#Number">Number</A>	number of current <A HREF="windows.html#window">window</A> in <A HREF="intro.html#tab">tab</A> page
taglist( {expr})		<A HREF="#List">List</A>	<A HREF="#list">list</A> of <A HREF="tagsrch.html#tags">tags</A> matching {expr}
<A HREF="#tagfiles()">tagfiles()</A>			<A HREF="#List">List</A>	<A HREF="tagsrch.html#tags">tags</A> files used
tan( {expr})			<A HREF="#Float">Float</A>	tangent of {expr}
tanh( {expr})			<A HREF="#Float">Float</A>	hyperbolic tangent of {expr}
<A HREF="#tempname()">tempname()</A>			<A HREF="#String">String</A>	name for a temporary file
timer_start( {time}, {callback} [, {options}])
				<A HREF="#Number">Number</A>	create a timer
timer_stop( {timer})		none	stop a timer
tolower( {expr})		<A HREF="#String">String</A>	the <A HREF="#String">String</A> {expr} switched to <A HREF="change.html#lowercase">lowercase</A>
toupper( {expr})		<A HREF="#String">String</A>	the <A HREF="#String">String</A> {expr} switched to <A HREF="change.html#uppercase">uppercase</A>
tr( {src}, {fromstr}, {tostr})	<A HREF="#String">String</A>	translate chars of {src} in {fromstr}
					to chars in {tostr}
trunc( {expr})			<A HREF="#Float">Float</A>	truncate <A HREF="#Float">Float</A> {expr}
type( {name})			<A HREF="#Number">Number</A>	type of variable {name}
undofile( {name})		<A HREF="#String">String</A>	<A HREF="undo.html#undo">undo</A> file name for {name}
<A HREF="#undotree()">undotree()</A>			<A HREF="#List">List</A>	<A HREF="undo.html#undo">undo</A> file tree
uniq( {list} [, {func} [, {dict}]])
				<A HREF="#List">List</A>	remove adjacent duplicates from a <A HREF="#list">list</A>
values( {dict})			<A HREF="#List">List</A>	values in {dict}
virtcol( {expr})		<A HREF="#Number">Number</A>	screen column of cursor or <A HREF="motion.html#mark">mark</A>
visualmode( [expr])		<A HREF="#String">String</A>	last visual mode used
<A HREF="#wildmenumode()">wildmenumode()</A>			<A HREF="#Number">Number</A>	whether <A HREF="options.html#'wildmenu'">'wildmenu'</A> mode is active
win_findbuf( {bufnr}) 		<A HREF="#List">List</A>	find <A HREF="windows.html#windows">windows</A> containing {bufnr}
win_getid( [{win} [, {tab}]]) 	<A HREF="#Number">Number</A>	get <A HREF="windows.html#window">window</A> ID for {win} in {tab}
win_gotoid( {expr})		<A HREF="#Number">Number</A>	go to <A HREF="windows.html#window">window</A> with ID {expr}
win_id2tabwin( {expr})		<A HREF="#List">List</A>	get <A HREF="intro.html#tab">tab</A> and <A HREF="windows.html#window">window</A> nr from <A HREF="windows.html#window">window</A> ID
win_id2win( {expr})		<A HREF="#Number">Number</A>	get <A HREF="windows.html#window">window</A> nr from <A HREF="windows.html#window">window</A> ID
winbufnr( {nr})			<A HREF="#Number">Number</A>	buffer number of <A HREF="windows.html#window">window</A> {nr}
<A HREF="#wincol()">wincol()</A>			<A HREF="#Number">Number</A>	<A HREF="windows.html#window">window</A> column of the cursor
winheight( {nr})		<A HREF="#Number">Number</A>	height of <A HREF="windows.html#window">window</A> {nr}
<A HREF="#winline()">winline()</A>			<A HREF="#Number">Number</A>	<A HREF="windows.html#window">window</A> line of the cursor
winnr( [{expr}])		<A HREF="#Number">Number</A>	number of current <A HREF="windows.html#window">window</A>
<A HREF="#winrestcmd()">winrestcmd()</A>			<A HREF="#String">String</A>	returns command to restore <A HREF="windows.html#window">window</A> sizes
winrestview( {dict})		none	restore <A HREF="starting.html#view">view</A> of current <A HREF="windows.html#window">window</A>
<A HREF="#winsaveview()">winsaveview()</A>			Dict	save <A HREF="starting.html#view">view</A> of current <A HREF="windows.html#window">window</A>
winwidth( {nr})			<A HREF="#Number">Number</A>	width of <A HREF="windows.html#window">window</A> {nr}
<A HREF="#wordcount()">wordcount()</A>			Dict	get byte/char/word statistics
writefile( {list}, {fname} [, {flags}])
				<A HREF="#Number">Number</A>	write <A HREF="#list">list</A> of lines to file {fname}
xor( {expr}, {expr})		<A HREF="#Number">Number</A>  bitwise XOR


abs({expr})							*<A NAME="abs()"></A><B>abs()</B>*
		Return the absolute value of {expr}.  When {expr} evaluates to
		a |<A HREF="#Float">Float</A>| <A HREF="#abs()">abs()</A> returns a |<A HREF="#Float">Float</A>|.  When {expr} can be
		converted to a |<A HREF="#Number">Number</A>| <A HREF="#abs()">abs()</A> returns a |<A HREF="#Number">Number</A>|.  Otherwise
		<A HREF="#abs()">abs()</A> gives an error message and returns -1.
		Examples:
<B>			echo abs(1.456)</B>
 			1.456 
<B>			echo abs(-5.456)</B>
 			5.456 
<B>			echo abs(-4)</B>
 			4
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



acos({expr})							*<A NAME="acos()"></A><B>acos()</B>*
		Return the arc cosine of {expr} measured in radians, <A HREF="motion.html#as">as</A> a
		|<A HREF="#Float">Float</A>| in the range of [0, pi].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>| in the range
		[-1, 1].
		Examples:
<B>			:echo acos(0)</B>
 			1.570796
<B>			:echo acos(-0.5)</B>
 			2.094395
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



add({list}, {expr})					*<A NAME="add()"></A><B>add()</B>*
		Append the item {expr} to |<A HREF="#List">List</A>| {list}.  Returns the
		resulting |<A HREF="#List">List</A>|.  Examples:
<B>			:let alist = add([1, 2, 3], item)</B>
<B>			:call add(mylist, "woodstock")</B>
 		Note that when {expr} is a |<A HREF="#List">List</A>| <A HREF="motion.html#it">it</A> is appended <A HREF="motion.html#as">as</A> a single
		item.  Use |<A HREF="#extend()">extend()</A>| to concatenate |<A HREF="#Lists">Lists</A>|.
		Use |<A HREF="#insert()">insert()</A>| to add an item at another position.



alloc_fail({id}, {countdown}, {repeat})			*<A NAME="alloc_fail()"></A><B>alloc_fail()</B>*
		This is for testing: If the memory allocation with {id} is
		called, then decrement {countdown}, and when <A HREF="motion.html#it">it</A> reaches zero
		let memory allocation fail {repeat} times.  When {repeat} is
		smaller than one <A HREF="motion.html#it">it</A> fails one time.



and({expr}, {expr})					*<A NAME="and()"></A><B>and()</B>*
		Bitwise AND on the two arguments.  The arguments are converted
		to a number.  A <A HREF="#List">List</A>, Dict or <A HREF="#Float">Float</A> argument causes an error.
		Example:
<B>			:let flag = and(bits, 0x80)</B>



append({lnum}, {expr})					*<A NAME="append()"></A><B>append()</B>*
		When {expr} is a |<A HREF="#List">List</A>|: Append each item of the |<A HREF="#List">List</A>| <A HREF="motion.html#as">as</A> a
		text line below line {lnum} in the current buffer.
		Otherwise append {expr} <A HREF="motion.html#as">as</A> one text line below line {lnum} in
		the current buffer.
		{lnum} can be zero to insert a line before the first one.
		Returns 1 for failure ({lnum} out of range or out of memory),
		0 for success.	Example:
<B>			:let failed = append(line('$'), "# THE END")</B>
<B>			:let failed = append(0, ["Chapter 1", "the beginning"])</B>
 

							*<A NAME="argc()"></A><B>argc()</B>*
<A HREF="#argc()">argc()</A>		The result is the number of files in the argument <A HREF="#list">list</A> of the
		current <A HREF="windows.html#window">window</A>.  See |<A HREF="editing.html#arglist">arglist</A>|.


							*<A NAME="argidx()"></A><B>argidx()</B>*
<A HREF="#argidx()">argidx()</A>	The result is the current index in the argument <A HREF="#list">list</A>.  0 is
		the first file.  <A HREF="#argc()">argc()</A> - 1 is the last one.  See |<A HREF="editing.html#arglist">arglist</A>|.


							*<A NAME="arglistid()"></A><B>arglistid()</B>*
arglistid([{winnr} [, {tabnr}]])
		Return the argument <A HREF="#list">list</A> ID.  This is a number which
		identifies the argument <A HREF="#list">list</A> being used.  Zero is used for the
		global argument list.  See |<A HREF="editing.html#arglist">arglist</A>|.
		Return -1 if the arguments are invalid.

		Without arguments use the current <A HREF="windows.html#window">window</A>.
		With {winnr} only use this <A HREF="windows.html#window">window</A> in the current <A HREF="intro.html#tab">tab</A> page.
		With {winnr} and {tabnr} use the <A HREF="windows.html#window">window</A> in the specified <A HREF="intro.html#tab">tab</A>
		page.


							*<A NAME="argv()"></A><B>argv()</B>*
argv([{nr}])	The result is the {nr}th file in the argument <A HREF="#list">list</A> of the
		current <A HREF="windows.html#window">window</A>.  See |<A HREF="editing.html#arglist">arglist</A>|.  &quot;argv(0)&quot; is the first one.
		Example:
<B>	:let i = 0</B>
<B>	:while i &lt; argc()</B>
<B>	:  let f = escape(fnameescape(argv(i)), '.')</B>
<B>	:  exe 'amenu Arg.' . f . ' :e ' . f . '&lt;CR&gt;'</B>
<B>	:  let i = i + 1</B>
<B>	:endwhile</B>
 		Without the {nr} argument a |<A HREF="#List">List</A>| with the whole |<A HREF="editing.html#arglist">arglist</A>| is
		returned.


							*<A NAME="assert_equal()"></A><B>assert_equal()</B>*
assert_equal({expected}, {actual} [, {msg}])
		When {expected} and {actual} are not equal an error message is
		added to |<A HREF="#v:errors">v:errors</A>|.
		There is no automatic conversion, the <A HREF="#String">String</A> &quot;4&quot; is different
		from the <A HREF="#Number">Number</A> 4.  And the number 4 is different from the
		<A HREF="#Float">Float</A> 4.0.  The value of <A HREF="options.html#'ignorecase'">'ignorecase'</A> is not used here, <A HREF="change.html#case">case</A>
		always matters.
		When {msg} is omitted an error in the form &quot;Expected
		{expected} but got {actual}&quot; is produced.
		Example:
<B>	assert_equal('foo', 'bar')</B>
 		Will result in a <A HREF="#string">string</A> to be added to YXXYv:errors|:
<B><FONT COLOR="PURPLE">	test.vim line 12: Expected 'foo' but got 'bar' </FONT></B>


assert_exception({error} [, {msg}])			*<A NAME="assert_exception()"></A><B>assert_exception()</B>*
		When <A HREF="#v:exception">v:exception</A> does not contain the <A HREF="#string">string</A> {error} an error
		message is added to |<A HREF="#v:errors">v:errors</A>|.
		This can be used to assert that a command throws an exception.
		Using the error number, followed by a colon, avoids problems
		with translations:
<B>			try</B>
<B>			  commandthatfails</B>
<B>			  call assert_false(1, 'command should have failed')</B>
<B>			catch</B>
<B>			  call assert_exception('E492:')</B>
<B>			endtry</B>


assert_fails({cmd} [, {error}])					*<A NAME="assert_fails()"></A><B>assert_fails()</B>*
		Run {cmd} and add an error message to |<A HREF="#v:errors">v:errors</A>| if <A HREF="motion.html#it">it</A> does
		NOT produce an error.
		When {error} is given <A HREF="motion.html#it">it</A> must match |<A HREF="#v:errmsg">v:errmsg</A>|.


assert_false({actual} [, {msg}])				*<A NAME="assert_false()"></A><B>assert_false()</B>*
		When {actual} is not false an error message is added to
		|<A HREF="#v:errors">v:errors</A>|, like with |<A HREF="#assert_equal()">assert_equal()</A>|.
		A value is false when <A HREF="motion.html#it">it</A> is zero. When {actual} is not a
		number the assert fails.
		When {msg} is omitted an error in the form &quot;Expected False but
		got {actual}&quot; is produced.


								*<A NAME="assert_match()"></A><B>assert_match()</B>*
assert_match({pattern}, {actual} [, {msg}])
		When {pattern} does not match {actual} an error message is
		added to |<A HREF="#v:errors">v:errors</A>|.

		{pattern} is used <A HREF="motion.html#as">as</A> with |=~|: The matching is always done
		like <A HREF="options.html#'magic'">'magic'</A> was set and <A HREF="options.html#'cpoptions'">'cpoptions'</A> is empty, no matter what
		the actual value of <A HREF="options.html#'magic'">'magic'</A> or <A HREF="options.html#'cpoptions'">'cpoptions'</A> is.

		{actual} is used <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A>, automatic conversion applies.
		Use &quot;<A HREF="motion.html#^">^</A>&quot; and &quot;<A HREF="motion.html#$">$</A>&quot; to match with the start and end of the text.
		Use both to match the whole text.

		When {msg} is omitted an error in the form &quot;<A HREF="pattern.html#Pattern">Pattern</A> {pattern}
		does not match {actual}&quot; is produced.
		Example:
<B>	assert_match('^f.*o$', 'foobar')</B>
 		Will result in a <A HREF="#string">string</A> to be added to YXXYv:errors|:
<B><FONT COLOR="PURPLE">	test.vim line 12: Pattern '^f.*o$' does not match 'foobar' </FONT></B>


assert_true({actual} [, {msg}])					*<A NAME="assert_true()"></A><B>assert_true()</B>*
		When {actual} is not true an error message is added to
		|<A HREF="#v:errors">v:errors</A>|, like with |<A HREF="#assert_equal()">assert_equal()</A>|.
		A value is true when <A HREF="motion.html#it">it</A> is a non-zero number.  When {actual}
		is not a number the assert fails.
		When {msg} is omitted an error in the form &quot;Expected True but
		got {actual}&quot; is produced.


asin({expr})						*<A NAME="asin()"></A><B>asin()</B>*
		Return the arc sine of {expr} measured in radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|
		in the range of [-pi/2, pi/2].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>| in the range
		[-1, 1].
		Examples:
<B>			:echo asin(0.8)</B>
 			0.927295
<B>			:echo asin(-0.5)</B>
 			-0.523599
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



atan({expr})						*<A NAME="atan()"></A><B>atan()</B>*
		Return the principal value of the arc tangent of {expr}, in
		the range [-pi/2, +pi/2] radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo atan(100)</B>
 			1.560797
<B>			:echo atan(-4.01)</B>
 			-1.326405
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



atan2({expr1}, {expr2})					*<A NAME="atan2()"></A><B>atan2()</B>*
		Return the arc tangent of {expr1} / {expr2}, measured in
		radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| in the range [-pi, pi].
		{expr1} and {expr2} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo atan2(-1, 1)</B>
 			-0.785398
<B>			:echo atan2(1, -1)</B>
 			2.356194
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



							*<A NAME="browse()"></A><B>browse()</B>*
browse({save}, {title}, {initdir}, {default})
		Put up a file requester.  This only works when &quot;has(&quot;browse&quot;)&quot;
		returns non-zero (only in some <A HREF="gui.html#GUI">GUI</A> versions).
		The input fields are:
		    {save}	when non-zero, select file to write
		    {title}	title for the requester
		    {initdir}	directory to start browsing in
		    {default}	default file name
		When the &quot;Cancel&quot; button is hit, something went wrong, or
		browsing is not possible, an empty <A HREF="#string">string</A> is returned.


							*<A NAME="browsedir()"></A><B>browsedir()</B>*
browsedir({title}, {initdir})
		Put up a directory requester.  This only works when
		&quot;has(&quot;browse&quot;)&quot; returns non-zero (only in some <A HREF="gui.html#GUI">GUI</A> versions).
		On systems where a directory browser is not supported a file
		browser is used.  In that <A HREF="change.html#case">case</A>: select a file in the directory
		to be used.
		The input fields are:
		    {title}	title for the requester
		    {initdir}	directory to start browsing in
		When the &quot;Cancel&quot; button is hit, something went wrong, or
		browsing is not possible, an empty <A HREF="#string">string</A> is returned.


bufexists({expr})					*<A NAME="bufexists()"></A><B>bufexists()</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero if a buffer called
		{expr} exists.
		If the {expr} argument is a number, buffer numbers are used.
		If the {expr} argument is a <A HREF="#string">string</A> <A HREF="motion.html#it">it</A> must match a buffer name
		exactly.  The name can be:
		- Relative to the current directory.
		- A full path.
		- The name of a buffer with <A HREF="options.html#'buftype'">'buftype'</A> set to &quot;nofile&quot;.
		- A URL name.
		Unlisted <A HREF="windows.html#buffers">buffers</A> will be found.
		Note that help files are listed by their short name in the
		output of |<A HREF="windows.html#:buffers">:buffers</A>|, but <A HREF="#bufexists()">bufexists()</A> requires using their
		long name to be able to find them.
		<A HREF="#bufexists()">bufexists()</A> may report a buffer exists, but to use the name
		with a |<A HREF="windows.html#:buffer">:buffer</A>| command you may need to use |<A HREF="#expand()">expand()</A>|.  Esp
		for <A HREF="os_win32.html#MS-Windows">MS-Windows</A> 8.3 names in the form &quot;c:\DOCUME~1&quot;
		Use &quot;bufexists(0)&quot; to test for the existence of an alternate
		file name.

							*<A NAME="buffer_exists()"></A><B>buffer_exists()</B>*
		Obsolete name: <A HREF="#buffer_exists()">buffer_exists()</A>.


buflisted({expr})					*<A NAME="buflisted()"></A><B>buflisted()</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero if a buffer called
		{expr} exists and is listed (has the <A HREF="options.html#'buflisted'">'buflisted'</A> option set).
		The {expr} argument is used like with |<A HREF="#bufexists()">bufexists()</A>|.


bufloaded({expr})					*<A NAME="bufloaded()"></A><B>bufloaded()</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero if a buffer called
		{expr} exists and is loaded (shown in a <A HREF="windows.html#window">window</A> or hidden).
		The {expr} argument is used like with |<A HREF="#bufexists()">bufexists()</A>|.


bufname({expr})						*<A NAME="bufname()"></A><B>bufname()</B>*
		The result is the name of a buffer, <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> is displayed by the
		&quot;<A HREF="windows.html#:ls">:ls</A>&quot; command.
		If {expr} is a <A HREF="#Number">Number</A>, that buffer number's name is given.
		<A HREF="#Number">Number</A> zero is the alternate buffer for the current <A HREF="windows.html#window">window</A>.
		If {expr} is a <A HREF="#String">String</A>, <A HREF="motion.html#it">it</A> is used <A HREF="motion.html#as">as</A> a |<A HREF="autocmd.html#file-pattern">file-pattern</A>| to match
		with the buffer names.	This is always done like <A HREF="options.html#'magic'">'magic'</A> is
		set and <A HREF="options.html#'cpoptions'">'cpoptions'</A> is empty.  When there is more than one
		match an empty <A HREF="#string">string</A> is returned.
		&quot;&quot; or &quot;<A HREF="motion.html#&#37;">&#37;</A>&quot; can be used for the current buffer, &quot;<A HREF="pattern.html##">#</A>&quot; for the
		alternate buffer.
		A full match is preferred, otherwise a match at the start, end
		or middle of the buffer name is accepted.  If you only want a
		full match then put &quot;<A HREF="motion.html#^">^</A>&quot; at the start and &quot;<A HREF="motion.html#$">$</A>&quot; at the end of the
		<A HREF="pattern.html#pattern">pattern</A>.
		Listed <A HREF="windows.html#buffers">buffers</A> are found first.  If there is a single match
		with a listed buffer, that one is returned.  Next unlisted
		<A HREF="windows.html#buffers">buffers</A> are searched for.
		If the {expr} is a <A HREF="#String">String</A>, but you want to use <A HREF="motion.html#it">it</A> <A HREF="motion.html#as">as</A> a buffer
		number, force <A HREF="motion.html#it">it</A> to be a <A HREF="#Number">Number</A> by adding zero to <A HREF="motion.html#it">it</A>:
<B>			:echo bufname("3" + 0)</B>
 		If the buffer doesn't exist, or doesn't have a name, an empty
		<A HREF="#string">string</A> is returned.
<B>	bufname("#")		alternate buffer name</B>
<B>	bufname(3)		name of buffer 3</B>
<B>	bufname("%")		name of current buffer</B>
<B>	bufname("file2")	name of buffer where "file2" matches.</B>

 							*<A NAME="buffer_name()"></A><B>buffer_name()</B>*
		Obsolete name: <A HREF="#buffer_name()">buffer_name()</A>.


							*<A NAME="bufnr()"></A><B>bufnr()</B>*
bufnr({expr} [, {create}])
		The result is the number of a buffer, <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> is displayed by
		the &quot;<A HREF="windows.html#:ls">:ls</A>&quot; command.  For the use of {expr}, see |<A HREF="#bufname()">bufname()</A>|
		above.
		If the buffer doesn't exist, -1 is returned.  Or, if the
		{create} argument is present and not zero, a new, unlisted,
		buffer is created and its number is returned.
		bufnr(&quot;$&quot;) is the last buffer:
<B>	:let last_buffer = bufnr("$")</B>
 		The result is a <A HREF="#Number">Number</A>, which is the highest buffer number
		of existing <A HREF="windows.html#buffers">buffers</A>.  Note that not all <A HREF="windows.html#buffers">buffers</A> with a smaller
		number necessarily exist, because &quot;<A HREF="windows.html#:bwipeout">:bwipeout</A>&quot; may have removed
		them.  Use <A HREF="#bufexists()">bufexists()</A> to test for the existence of a buffer.

							*<A NAME="buffer_number()"></A><B>buffer_number()</B>*
		Obsolete name: <A HREF="#buffer_number()">buffer_number()</A>.

							*<A NAME="last_buffer_nr()"></A><B>last_buffer_nr()</B>*
		Obsolete name for bufnr(&quot;$&quot;): <A HREF="#last_buffer_nr()">last_buffer_nr()</A>.


bufwinnr({expr})					*<A NAME="bufwinnr()"></A><B>bufwinnr()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the number of the first
		<A HREF="windows.html#window">window</A> associated with buffer {expr}.  For the use of {expr},
		see |<A HREF="#bufname()">bufname()</A>| above.	If buffer {expr} doesn't exist or
		there is no such <A HREF="windows.html#window">window</A>, -1 is returned.  Example:

<B>	echo "A window containing buffer 1 is " . (bufwinnr(1))</B>

 		The number can be used with |<A HREF="windows.html#CTRL-W_w">CTRL-W_w</A>| and &quot;<A HREF="windows.html#:wincmd">:wincmd</A> w&quot;
		|<A HREF="windows.html#:wincmd">:wincmd</A>|.
		Only deals with the current <A HREF="intro.html#tab">tab</A> page.


byte2line({byte})					*<A NAME="byte2line()"></A><B>byte2line()</B>*
		Return the line number that contains the character at byte
		<A HREF="intro.html#count">count</A> {byte} in the current buffer.  This includes the
		end-of-line character, depending on the <A HREF="options.html#'fileformat'">'fileformat'</A> option
		for the current buffer.  The first character has byte <A HREF="intro.html#count">count</A>
		one.
		Also see |<A HREF="#line2byte()">line2byte()</A>|, |<A HREF="motion.html#go">go</A>| and |<A HREF="motion.html#:goto">:goto</A>|.
		{not available when compiled without the |<A HREF="various.html#+byte_offset">+byte_offset</A>|
		feature}


byteidx({expr}, {nr})					*<A NAME="byteidx()"></A><B>byteidx()</B>*
		Return byte index of the {nr}'th character in the <A HREF="#string">string</A>
		{expr}.  Use zero for the first character, <A HREF="motion.html#it">it</A> returns zero.
		This function is only useful when there are <A HREF="mbyte.html#multibyte">multibyte</A>
		characters, otherwise the returned value is equal to {nr}.
		Composing characters are not counted separately, their byte
		length is added to the preceding base character.  See
		|<A HREF="#byteidxcomp()">byteidxcomp()</A>| below for counting composing characters
		separately.
		Example :
<B>			echo matchstr(str, ".", byteidx(str, 3))</B>
 		will display the fourth character.  Another way to <A HREF="diff.html#do">do</A> the
		same:
<B>			let s = strpart(str, byteidx(str, 3))</B>
<B>			echo strpart(s, 0, byteidx(s, 1))</B>
 		If there are <A HREF="various.html#less">less</A> than {nr} characters -1 is returned.
		If there are exactly {nr} characters the length of the <A HREF="#string">string</A>
		in bytes is returned.


byteidxcomp({expr}, {nr})					*<A NAME="byteidxcomp()"></A><B>byteidxcomp()</B>*
		Like <A HREF="#byteidx()">byteidx()</A>, except that a composing character is counted
		<A HREF="motion.html#as">as</A> a separate character.  Example:
<B>			let s = 'e' . nr2char(0x301)</B>
<B>			echo byteidx(s, 1)</B>
<B>			echo byteidxcomp(s, 1)</B>
<B>			echo byteidxcomp(s, 2)</B>
 		The first and third echo result in 3 ('e' plus composing
		character is 3 bytes), the second echo results in 1 ('e' is
		one byte).
		Only works different from <A HREF="#byteidx()">byteidx()</A> when <A HREF="options.html#'encoding'">'encoding'</A> is set to
		a <A HREF="mbyte.html#Unicode">Unicode</A> encoding.


call({func}, <A HREF="editing.html#{arglist}">{arglist}</A> [, {dict}])			*<A NAME="call()"></A><B>call()</B>* *<A NAME="E699"></A><B>E699</B>*
		Call function {func} with the items in |<A HREF="#List">List</A>| <A HREF="editing.html#{arglist}">{arglist}</A> <A HREF="motion.html#as">as</A>
		arguments.
		{func} can either be a |<A HREF="#Funcref">Funcref</A>| or the name of a function.
		<A HREF="#a:firstline">a:firstline</A> and <A HREF="#a:lastline">a:lastline</A> are set to the cursor line.
		Returns the return value of the called function.
		{dict} is for <A HREF="#functions">functions</A> with the &quot;<A HREF="#dict">dict</A>&quot; attribute.  It will be
		used to set the local variable &quot;<A HREF="#self">self</A>&quot;. |<A HREF="#Dictionary-function">Dictionary-function</A>|


ceil({expr})							*<A NAME="ceil()"></A><B>ceil()</B>*
		Return the smallest integral value greater than or equal to
		{expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| (round up).
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			echo ceil(1.456)</B>
 			2.0 
<B>			echo ceil(-5.456)</B>
 			-5.0 
<B>			echo ceil(4.0)</B>
 			4.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}


<A HREF="#changenr()">changenr()</A>						*<A NAME="changenr()"></A><B>changenr()</B>*
		Return the number of the most recent change.  This is the same
		number <A HREF="motion.html#as">as</A> what is displayed with |<A HREF="undo.html#:undolist">:undolist</A>| and can be used
		with the |<A HREF="undo.html#:undo">:undo</A>| command.
		When a change was made <A HREF="motion.html#it">it</A> is the number of that change.  After
		<A HREF="undo.html#redo">redo</A> <A HREF="motion.html#it">it</A> is the number of the redone change.  After <A HREF="undo.html#undo">undo</A> <A HREF="motion.html#it">it</A> is
		one <A HREF="various.html#less">less</A> than the number of the undone change.


char2nr({expr}[, {utf8}])					*<A NAME="char2nr()"></A><B>char2nr()</B>*
		Return number value of the first char in {expr}.  Examples:
<B>			char2nr(" ")		returns 32</B>
<B>			char2nr("ABC")		returns 65</B>
 		When {utf8} is omitted or zero, the current <A HREF="options.html#'encoding'">'encoding'</A> is used.
		Example for &quot;<A HREF="mbyte.html#utf-8">utf-8</A>&quot;:
<B>			char2nr("&aacute;")		returns 225</B>
<B>			char2nr("&aacute;"[0])		returns 195</B>
 		With {utf8} set to 1, always treat <A HREF="motion.html#as">as</A> <A HREF="mbyte.html#utf-8">utf-8</A> characters.
		A combining character is a separate character.
		|<A HREF="#nr2char()">nr2char()</A>| does the opposite.


cindent({lnum})						*<A NAME="cindent()"></A><B>cindent()</B>*
		Get the amount of indent for line {lnum} according the C
		indenting rules, <A HREF="motion.html#as">as</A> with <A HREF="options.html#'cindent'">'cindent'</A>.
		The indent is counted in spaces, the value of <A HREF="options.html#'tabstop'">'tabstop'</A> is
		relevant.  {lnum} is used just like in |<A HREF="#getline()">getline()</A>|.
		When {lnum} is invalid or Vim was not compiled the |<A HREF="various.html#+cindent">+cindent</A>|
		feature, -1 is returned.
		See |<A HREF="indent.html#C-indenting">C-indenting</A>|.


<A HREF="#clearmatches()">clearmatches()</A>						*<A NAME="clearmatches()"></A><B>clearmatches()</B>*
		Clears all matches previously defined by |<A HREF="#matchadd()">matchadd()</A>| and the
		|<A HREF="pattern.html#:match">:match</A>| commands.


							*<A NAME="col()"></A><B>col()</B>*
col({expr})	The result is a <A HREF="#Number">Number</A>, which is the byte index of the column
		position given with {expr}.  The accepted positions are:
		    .	    the cursor position
		    $	    the end of the cursor line (the result is the
			    number of bytes in the cursor line plus one)
		    'x	    position of <A HREF="motion.html#mark">mark</A> <A HREF="change.html#x">x</A> (if the <A HREF="motion.html#mark">mark</A> is not set, 0 is
			    returned)
		    <A HREF="visual.html#v">v</A>       In <A HREF="visual.html#Visual">Visual</A> mode: the start of the <A HREF="visual.html#Visual">Visual</A> area (the
			    cursor is the end).  When not in <A HREF="visual.html#Visual">Visual</A> mode
			    returns the cursor position.  Differs from |<A HREF="motion.html#'&lt;">'&lt;</A>| in
			    that it's updated right away.
		Additionally {expr} can be [lnum, col]: a |<A HREF="#List">List</A>| with the line
		and column number. Most useful when the column is &quot;<A HREF="motion.html#$">$</A>&quot;, to get
		the last column of a specific line.  When &quot;lnum&quot; or &quot;col&quot; is
		out of range then <A HREF="#col()">col()</A> returns zero.
		To get the line number use |<A HREF="#line()">line()</A>|.  To get both use
		|<A HREF="#getpos()">getpos()</A>|.
		For the screen column position use |<A HREF="#virtcol()">virtcol()</A>|.
		Note that only marks in the current file can be used.
		Examples:
<B>			col(".")		column of cursor</B>
<B>			col("$")		length of cursor line plus one</B>
<B>			col("'t")		column of mark t</B>
<B>			col("'" . markname)	column of mark markname</B>
 		The first column is 1.	0 is returned for an error.
		For an <A HREF="change.html#uppercase">uppercase</A> <A HREF="motion.html#mark">mark</A> the column may actually be in another
		buffer.
		For the cursor position, when <A HREF="options.html#'virtualedit'">'virtualedit'</A> is active, the
		column is one higher if the cursor is after the end of the
		line.  This can be used to obtain the column in <A HREF="insert.html#Insert">Insert</A> mode:
<B>			:imap &lt;F2&gt; &lt;C-O&gt;:let save_ve = &amp;ve&lt;CR&gt;</B>
<B>				\&lt;C-O&gt;:set ve=all&lt;CR&gt;</B>
<B>				\&lt;C-O&gt;:echo col(".") . "\n" &lt;Bar&gt;</B>
<B>				\let &amp;ve = save_ve&lt;CR&gt;</B>
 


complete({startcol}, {matches})			*<A NAME="complete()"></A><B>complete()</B>* *<A NAME="E785"></A><B>E785</B>*
		Set the matches for <A HREF="insert.html#Insert">Insert</A> mode completion.
		Can only be used in <A HREF="insert.html#Insert">Insert</A> mode.  You need to use a <A HREF="map.html#mapping">mapping</A>
		with CTRL-R = |<A HREF="insert.html#i_CTRL-R">i_CTRL-R</A>|.  It does not work after <A HREF="motion.html#CTRL-O">CTRL-O</A> or
		with an <A HREF="#expression">expression</A> <A HREF="map.html#mapping">mapping</A>.
		{startcol} is the byte offset in the line where the completed
		text start.  The text up to the cursor is the original text
		that will be replaced by the matches.  Use col('.') for an
		empty <A HREF="#string">string</A>.  &quot;col('.') - 1&quot; will replace one character by a
		match.
		{matches} must be a |<A HREF="#List">List</A>|.  Each |<A HREF="#List">List</A>| item is one match.
		See |<A HREF="insert.html#complete-items">complete-items</A>| for the kind of items that are possible.
		Note that the after calling this function you need to avoid
		<A HREF="insert.html#inserting">inserting</A> anything that would cause completion to stop.
		The match can be selected with <A HREF="motion.html#CTRL-N">CTRL-N</A> and <A HREF="motion.html#CTRL-P">CTRL-P</A> <A HREF="motion.html#as">as</A> usual with
		<A HREF="insert.html#Insert">Insert</A> mode completion.  The popup menu will appear if
		specified, see |<A HREF="insert.html#ins-completion-menu">ins-completion-menu</A>|.
		Example:
<B>	inoremap &lt;F5&gt; &lt;C-R&gt;=ListMonths()&lt;CR&gt;</B>

<B>	func! ListMonths()</B>
<B>	  call complete(col('.'), ['January', 'February', 'March',</B>
<B>		\ 'April', 'May', 'June', 'July', 'August', 'September',</B>
<B>		\ 'October', 'November', 'December'])</B>
<B>	  return ''</B>
<B>	endfunc</B>
 		This isn't very useful, but <A HREF="motion.html#it">it</A> shows how <A HREF="motion.html#it">it</A> works.  Note that
		an empty <A HREF="#string">string</A> is returned to avoid a zero being inserted.


complete_add({expr})				*<A NAME="complete_add()"></A><B>complete_add()</B>*
		Add {expr} to the <A HREF="#list">list</A> of matches.  Only to be used by the
		function specified with the <A HREF="options.html#'completefunc'">'completefunc'</A> option.
		Returns 0 for failure (empty <A HREF="#string">string</A> or out of memory),
		1 when the match was added, 2 when the match was already in
		the <A HREF="#list">list</A>.
		See |<A HREF="insert.html#complete-functions">complete-functions</A>| for an explanation of {expr}.	It is
		the same <A HREF="motion.html#as">as</A> one item in the <A HREF="#list">list</A> that <A HREF="options.html#'omnifunc'">'omnifunc'</A> would return.


<A HREF="#complete_check()">complete_check()</A>				*<A NAME="complete_check()"></A><B>complete_check()</B>*
		Check for a key typed while looking for completion matches.
		This is to be used when looking for matches takes some time.
		Returns non-zero when searching for matches is to be aborted,
		zero otherwise.
		Only to be used by the function specified with the
		<A HREF="options.html#'completefunc'">'completefunc'</A> option.


						*<A NAME="confirm()"></A><B>confirm()</B>*
confirm({msg} [, {choices} [, {default} [, {type}]]])
		Confirm() offers the user a <A HREF="gui_w32.html#dialog">dialog</A>, from which a choice can be
		made.  It returns the number of the choice.  For the first
		choice this is 1.
		Note: <A HREF="#confirm()">confirm()</A> is only supported when compiled with <A HREF="gui_w32.html#dialog">dialog</A>
		support, see |<A HREF="various.html#+dialog_con">+dialog_con</A>| and |<A HREF="various.html#+dialog_gui">+dialog_gui</A>|.

		{msg} is displayed in a |<A HREF="gui_w32.html#dialog">dialog</A>| with {choices} <A HREF="motion.html#as">as</A> the
		alternatives.  When {choices} is missing or empty, &quot;&amp;OK&quot; is
		used (and translated).
		{msg} is a <A HREF="#String">String</A>, use '\n' to include a newline.  Only on
		some systems the <A HREF="#string">string</A> is wrapped when <A HREF="motion.html#it">it</A> doesn't fit.

		{choices} is a <A HREF="#String">String</A>, with the individual choices separated
		by '\n', e.g.
<B>			confirm("Save changes?", "&amp;Yes\n&amp;No\n&amp;Cancel")</B>
 		The <A HREF="print.html#letter">letter</A> after the '<A HREF="change.html#&amp;">&amp;</A>' is the shortcut key for that choice.
		Thus you can type '<A HREF="change.html#c">c</A>' to select &quot;Cancel&quot;.  The shortcut does
		not need to be the first <A HREF="print.html#letter">letter</A>:
<B>			confirm("file has been modified", "&amp;Save\nSave &amp;All")</B>
 		For the console, the first <A HREF="print.html#letter">letter</A> of each choice is used <A HREF="motion.html#as">as</A>
		the default shortcut key.

		The optional {default} argument is the number of the choice
		that is made if the user hits <A HREF="motion.html#&lt;CR&gt;">&lt;CR&gt;</A>.  Use 1 to make the first
		choice the default one.  Use 0 to not set a default.  If
		{default} is omitted, 1 is used.

		The optional {type} argument gives the type of <A HREF="gui_w32.html#dialog">dialog</A>.  This
		is only used for the icon of the <A HREF="gui_x11.html#GTK">GTK</A>, <A HREF="os_mac.html#Mac">Mac</A>, <A HREF="gui_x11.html#Motif">Motif</A> and <A HREF="os_win32.html#Win32">Win32</A>
		<A HREF="gui.html#GUI">GUI</A>.  It can be one of these values: &quot;Error&quot;, &quot;Question&quot;,
		&quot;Info&quot;, &quot;Warning&quot; or &quot;Generic&quot;.  Only the first character is
		relevant.  When {type} is omitted, &quot;Generic&quot; is used.

		If the user aborts the <A HREF="gui_w32.html#dialog">dialog</A> by pressing <A HREF="intro.html#&lt;Esc&gt;">&lt;Esc&gt;</A>, <A HREF="pattern.html#CTRL-C">CTRL-C</A>,
		or another valid interrupt key, <A HREF="#confirm()">confirm()</A> returns 0.

		An example:
<B>   :let choice = confirm("What do you want?", "&amp;Apples\n&amp;Oranges\n&amp;Bananas", 2)</B>
<B>   :if choice == 0</B>
<B>   :	echo "make up your mind!"</B>
<B>   :elseif choice == 3</B>
<B>   :	echo "tasteful"</B>
<B>   :else</B>
<B>   :	echo "I prefer bananas myself."</B>
<B>   :endif</B>
 		In a <A HREF="gui.html#GUI">GUI</A> <A HREF="gui_w32.html#dialog">dialog</A>, buttons are used.  The layout of the buttons
		depends on the '<A HREF="visual.html#v">v</A>' flag in <A HREF="options.html#'guioptions'">'guioptions'</A>.  If <A HREF="motion.html#it">it</A> is included,
		the buttons are always put vertically.	Otherwise,  <A HREF="#confirm()">confirm()</A>
		tries to put the buttons in one horizontal line.  If they
		don't fit, a vertical layout is used anyway.  For some systems
		the horizontal layout is always used.


ch_close({handle})						*<A NAME="ch_close()"></A><B>ch_close()</B>*
		Close {handle}.  See |<A HREF="channel.html#channel-close">channel-close</A>|.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_evalexpr({handle}, {expr} [, {options}])			*<A NAME="ch_evalexpr()"></A><B>ch_evalexpr()</B>*
		Send {expr} over {handle}.  The {expr} is encoded
		according to the type of <A HREF="channel.html#channel">channel</A>.  The function cannot be used
		with a raw channel.  See |<A HREF="channel.html#channel-use">channel-use</A>|.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.

								*<A NAME="E917"></A><B>E917</B>*
		{options} must be a <A HREF="#Dictionary">Dictionary</A>.  It must not have a &quot;callback&quot;
		entry.  It can have a &quot;timeout&quot; entry to specify the timeout
		for this specific request.

		<A HREF="#ch_evalexpr()">ch_evalexpr()</A> waits for a response and returns the decoded
		<A HREF="#expression">expression</A>.  When there is an error or timeout <A HREF="motion.html#it">it</A> returns an
		empty <A HREF="#string">string</A>.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_evalraw({handle}, {string} [, {options}])		*<A NAME="ch_evalraw()"></A><B>ch_evalraw()</B>*
		Send {string} over {handle}.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.

		Works like |<A HREF="#ch_evalexpr()">ch_evalexpr()</A>|, but does not encode the request or
		decode the response.  The caller is responsible for the
		correct contents.  Also does not add a newline for a <A HREF="channel.html#channel">channel</A>
		in NL mode, the caller must <A HREF="diff.html#do">do</A> that.  The NL in the response
		is removed.
		See |<A HREF="channel.html#channel-use">channel-use</A>|.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_getbufnr({handle}, {what})				 *<A NAME="ch_getbufnr()"></A><B>ch_getbufnr()</B>*
		Get the buffer number that {handle} is using for {what}.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.
		{what} can be &quot;err&quot; for stderr, &quot;out&quot; for stdout or empty for
		socket output.
		Returns -1 when there is no buffer.
		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_getjob({channel})						*<A NAME="ch_getjob()"></A><B>ch_getjob()</B>*
		Get the <A HREF="#Job">Job</A> associated with {channel}.
		If there is no job calling |<A HREF="#job_status()">job_status()</A>| on the returned <A HREF="#Job">Job</A>
		will result in &quot;fail&quot;.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| and
		|<A HREF="various.html#+job">+job</A>| features}


ch_info({handle})						*<A NAME="ch_info()"></A><B>ch_info()</B>*
		Returns a <A HREF="#Dictionary">Dictionary</A> with information about {handle}.  The
		items are:
		   &quot;id&quot;		  number of the <A HREF="channel.html#channel">channel</A>
		   &quot;status&quot;	  &quot;open&quot; (any part is open) or &quot;closed&quot;
		When opened with <A HREF="#ch_open()">ch_open()</A>:
		   &quot;hostname&quot;	  the hostname of the address
		   &quot;port&quot;	  the port of the address
		   &quot;sock_status&quot;  &quot;open&quot; or &quot;closed&quot;
		   &quot;sock_mode&quot;	  &quot;NL&quot;, &quot;RAW&quot;, &quot;JSON&quot; or &quot;JS&quot;
		   &quot;sock_io&quot;	  &quot;socket&quot;
		   &quot;sock_timeout&quot; timeout in msec
		When opened with <A HREF="#job_start()">job_start()</A>:
		   &quot;out_status&quot;	  &quot;open&quot; or &quot;closed&quot;
		   &quot;<A HREF="channel.html#out_mode">out_mode</A>&quot;	  &quot;NL&quot;, &quot;RAW&quot;, &quot;JSON&quot; or &quot;JS&quot;
		   &quot;out_io&quot;	  &quot;null&quot;, &quot;pipe&quot;, &quot;file&quot; or &quot;buffer&quot;
		   &quot;<A HREF="channel.html#out_timeout">out_timeout</A>&quot;  timeout in msec
		   &quot;err_status&quot;	  &quot;open&quot; or &quot;closed&quot;
		   &quot;<A HREF="channel.html#err_mode">err_mode</A>&quot;	  &quot;NL&quot;, &quot;RAW&quot;, &quot;JSON&quot; or &quot;JS&quot;
		   &quot;err_io&quot;	  &quot;out&quot;, &quot;null&quot;, &quot;pipe&quot;, &quot;file&quot; or &quot;buffer&quot;
		   &quot;<A HREF="channel.html#err_timeout">err_timeout</A>&quot;  timeout in msec
		   &quot;in_status&quot;	  &quot;open&quot; or &quot;closed&quot;
		   &quot;<A HREF="channel.html#in_mode">in_mode</A>&quot;	  &quot;NL&quot;, &quot;RAW&quot;, &quot;JSON&quot; or &quot;JS&quot;
		   &quot;in_io&quot;	  &quot;null&quot;, &quot;pipe&quot;, &quot;file&quot; or &quot;buffer&quot;
		   &quot;in_timeout&quot;	  timeout in msec


ch_log({msg} [, {handle}])					*<A NAME="ch_log()"></A><B>ch_log()</B>*
		Write {msg} in the <A HREF="channel.html#channel">channel</A> log file, if <A HREF="motion.html#it">it</A> was opened with
		|<A HREF="#ch_logfile()">ch_logfile()</A>|.
		When {handle} is passed the <A HREF="channel.html#channel">channel</A> number is used for the
		message.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.  The
		<A HREF="#Channel">Channel</A> must open.


ch_logfile({fname} [, {mode}])					*<A NAME="ch_logfile()"></A><B>ch_logfile()</B>*
		Start logging <A HREF="channel.html#channel">channel</A> activity to {fname}.
		When {fname} is an empty <A HREF="#string">string</A>: stop logging.

		When {mode} is omitted or &quot;<A HREF="insert.html#a">a</A>&quot; append to the file.
		When {mode} is &quot;<A HREF="motion.html#w">w</A>&quot; start with an empty file.

		The file is flushed after every message, on <A HREF="os_unix.html#Unix">Unix</A> you can use
		&quot;tail -f&quot; to see what is going on in real time.



ch_open({address} [, {options}])				*<A NAME="ch_open()"></A><B>ch_open()</B>*
		Open a channel to <A HREF="cmdline.html#{address}">{address}</A>.  See |<A HREF="channel.html#channel">channel</A>|.
		Returns a <A HREF="#Channel">Channel</A>.  Use |<A HREF="#ch_status()">ch_status()</A>| to check for failure.

		<A HREF="cmdline.html#{address}">{address}</A> has the form &quot;hostname:port&quot;, e.g.,
		&quot;localhost:8765&quot;.

		If {options} is given <A HREF="motion.html#it">it</A> must be a |<A HREF="#Dictionary">Dictionary</A>|.
		See |<A HREF="channel.html#channel-open-options">channel-open-options</A>|.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_read({handle} [, {options}])					*<A NAME="ch_read()"></A><B>ch_read()</B>*
		Read from {handle} and return the received message.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.
		See |<A HREF="channel.html#channel-more">channel-more</A>|.
		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_readraw({handle} [, {options}])			*<A NAME="ch_readraw()"></A><B>ch_readraw()</B>*
		Like <A HREF="#ch_read()">ch_read()</A> but for a JS and JSON <A HREF="channel.html#channel">channel</A> does not decode
		the message.  See |<A HREF="channel.html#channel-more">channel-more</A>|.
		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_sendexpr({handle}, {expr} [, {options}])			*<A NAME="ch_sendexpr()"></A><B>ch_sendexpr()</B>*
		Send {expr} over {handle}.  The {expr} is encoded
		according to the type of <A HREF="channel.html#channel">channel</A>.  The function cannot be used
		with a raw <A HREF="channel.html#channel">channel</A>.

		See |<A HREF="channel.html#channel-use">channel-use</A>|.				*<A NAME="E912"></A><B>E912</B>*
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_sendraw({handle}, {string} [, {options}])		*<A NAME="ch_sendraw()"></A><B>ch_sendraw()</B>*
		Send {string} over {handle}.
		Works like |<A HREF="#ch_sendexpr()">ch_sendexpr()</A>|, but does not encode the request or
		decode the response.  The caller is responsible for the
		correct contents.  Also does not add a newline for a <A HREF="channel.html#channel">channel</A>
		in NL mode, the caller must <A HREF="diff.html#do">do</A> that.  The NL in the response
		is removed.
		See |<A HREF="channel.html#channel-use">channel-use</A>|.

		{only available when compiled with the |<A HREF="various.html#+channel">+channel</A>| feature}


ch_setoptions({handle}, {options})			*<A NAME="ch_setoptions()"></A><B>ch_setoptions()</B>*
		Set <A HREF="options.html#options">options</A> on {handle}:
			&quot;callback&quot;	the <A HREF="channel.html#channel">channel</A> callback
			&quot;timeout&quot;	default read timeout in msec
			&quot;mode&quot;		mode for the whole <A HREF="channel.html#channel">channel</A>
		See |<A HREF="#ch_open()">ch_open()</A>| for more explanation.
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.

		Note that <A HREF="change.html#changing">changing</A> the mode may cause queued <A HREF="message.html#messages">messages</A> to be
		lost.

		These <A HREF="options.html#options">options</A> cannot be changed:
			&quot;<A HREF="channel.html#waittime">waittime</A>&quot;	only applies to &quot;ch_open()YXXY


ch_status({handle})						*<A NAME="ch_status()"></A><B>ch_status()</B>*
		Return the status of {handle}:
			&quot;fail&quot;		failed to open the <A HREF="channel.html#channel">channel</A>
			&quot;open&quot;		<A HREF="channel.html#channel">channel</A> can be used
			&quot;closed&quot;	<A HREF="channel.html#channel">channel</A> can not be used
		{handle} can be <A HREF="#Channel">Channel</A> or a <A HREF="#Job">Job</A> that has a <A HREF="#Channel">Channel</A>.


							*<A NAME="copy()"></A><B>copy()</B>*
copy({expr})	Make a copy of {expr}.	For Numbers and Strings this isn't
		different from using {expr} directly.
		When {expr} is a |<A HREF="#List">List</A>| a shallow copy is created.  This means
		that the original |<A HREF="#List">List</A>| can be changed without <A HREF="change.html#changing">changing</A> the
		copy, and vice versa.  But the items are identical, thus
		<A HREF="change.html#changing">changing</A> an item changes the contents of both |<A HREF="#Lists">Lists</A>|.
		A |<A HREF="#Dictionary">Dictionary</A>| is copied in a similar way <A HREF="motion.html#as">as</A> a |<A HREF="#List">List</A>|.
		Also see |<A HREF="#deepcopy()">deepcopy()</A>|.


cos({expr})						*<A NAME="cos()"></A><B>cos()</B>*
		Return the cosine of {expr}, measured in radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo cos(100)</B>
 			0.862319
<B>			:echo cos(-4.01)</B>
 			-0.646043
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



cosh({expr})						*<A NAME="cosh()"></A><B>cosh()</B>*
		Return the hyperbolic cosine of {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| in the range
		[1, inf].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo cosh(0.5)</B>
 			1.127626
<B>			:echo cosh(-0.5)</B>
 			-1.127626
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}

		

count({comp}, {expr} [, {ic} [, {start}]])			*<A NAME="count()"></A><B>count()</B>*
		Return the number of times an item with value {expr} appears
		in |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| {comp}.
		If {start} is given then start with the item with this index.
		{start} can only be used with a |<A HREF="#List">List</A>|.
		When {ic} is given and it's non-zero then <A HREF="change.html#case">case</A> is ignored.



							*<A NAME="cscope_connection()"></A><B>cscope_connection()</B>*
cscope_connection([{num} , {dbpath} [, {prepend}]])
		Checks for the existence of a |<A HREF="if_cscop.html#cscope">cscope</A>| connection.  If no
		parameters are specified, then the function returns:
			0, if <A HREF="if_cscop.html#cscope">cscope</A> was not available (not compiled in), or
			   if there are no <A HREF="if_cscop.html#cscope">cscope</A> connections;
			1, if there is at least one <A HREF="if_cscop.html#cscope">cscope</A> connection.

		If parameters are specified, then the value of {num}
		determines how existence of a <A HREF="if_cscop.html#cscope">cscope</A> connection is checked:

		{num}	Description of existence check
		-----	------------------------------
		0	Same <A HREF="motion.html#as">as</A> no parameters (e.g., &quot;cscope_connection()&quot;).
		1	Ignore {prepend}, and use partial <A HREF="#string">string</A> matches for
			{dbpath}.
		2	Ignore {prepend}, and use exact <A HREF="#string">string</A> matches for
			{dbpath}.
		3	Use {prepend}, use partial <A HREF="#string">string</A> matches for both
			{dbpath} and {prepend}.
		4	Use {prepend}, use exact <A HREF="#string">string</A> matches for both
			{dbpath} and {prepend}.

		Note: All <A HREF="#string">string</A> comparisons are <A HREF="change.html#case">case</A> sensitive!

		Examples.  Suppose we had the following (from &quot;<A HREF="if_cscop.html#:cs">:cs</A> show&quot;):

<B>  # pid    database name			prepend path</B>
<B>  0 27664  cscope.out				/usr/local</B>
 
<B><FONT COLOR="PURPLE">		Invocation					Return Val </FONT></B>
		----------					----------
<B>		cscope_connection()					1</B>
<B>		cscope_connection(1, "out")				1</B>
<B>		cscope_connection(2, "out")				0</B>
<B>		cscope_connection(3, "out")				0</B>
<B>		cscope_connection(3, "out", "local")			1</B>
<B>		cscope_connection(4, "out")				0</B>
<B>		cscope_connection(4, "out", "local")			0</B>
<B>		cscope_connection(4, "cscope.out", "/usr/local")	1</B>
 

cursor({lnum}, {col} [, {off}])				*<A NAME="cursor()"></A><B>cursor()</B>*
cursor({list})
		Positions the cursor at the column (byte <A HREF="intro.html#count">count</A>) {col} in the
		line {lnum}.  The first column is one.

		When there is one argument {list} this is used <A HREF="motion.html#as">as</A> a |<A HREF="#List">List</A>|
		with two, three or four item:
			[{lnum}, {col}, {off}]
			[{lnum}, {col}, {off}, {curswant}]
		This is like the return value of |<A HREF="#getpos()">getpos()</A>| or |<A HREF="#getcurpos()">getcurpos()</A>|,
		but without the first item.

		Does not change the <A HREF="motion.html#jumplist">jumplist</A>.
		If {lnum} is greater than the number of lines in the buffer,
		the cursor will be positioned at the last line in the buffer.
		If {lnum} is zero, the cursor will stay in the current line.
		If {col} is greater than the number of bytes in the line,
		the cursor will be positioned at the last character in the
		line.
		If {col} is zero, the cursor will stay in the current column.
		If {curswant} is given <A HREF="motion.html#it">it</A> is used to set the preferred column
		for vertical <A HREF="intro.html#movement">movement</A>.  Otherwise {col} is used.

		When <A HREF="options.html#'virtualedit'">'virtualedit'</A> is used {off} specifies the offset in
		screen columns from the start of the character.  E.g., a
		position within a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> or after the last character.
		Returns 0 when the position could be set, -1 otherwise.



deepcopy({expr}[, {noref}])				*<A NAME="deepcopy()"></A><B>deepcopy()</B>* *<A NAME="E698"></A><B>E698</B>*
		Make a copy of {expr}.	For Numbers and Strings this isn't
		different from using {expr} directly.
		When {expr} is a |<A HREF="#List">List</A>| a full copy is created.  This means
		that the original |<A HREF="#List">List</A>| can be changed without <A HREF="change.html#changing">changing</A> the
		copy, and vice versa.  When an item is a |<A HREF="#List">List</A>| or
		|<A HREF="#Dictionary">Dictionary</A>|, a copy for <A HREF="motion.html#it">it</A> is made, recursively.  Thus
		<A HREF="change.html#changing">changing</A> an item in the copy does not change the contents of
		the original |<A HREF="#List">List</A>|.
		A |<A HREF="#Dictionary">Dictionary</A>| is copied in a similar way <A HREF="motion.html#as">as</A> a |<A HREF="#List">List</A>|.
		When {noref} is omitted or zero a contained |<A HREF="#List">List</A>| or
		|<A HREF="#Dictionary">Dictionary</A>| is only copied once.  All references point to
		this single copy.  With {noref} set to 1 every occurrence of a
		|<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| results in a new copy.  This also means
		that a cyclic reference causes <A HREF="#deepcopy()">deepcopy()</A> to fail.

								*<A NAME="E724"></A><B>E724</B>*
		Nesting is possible up to 100 levels.  When there is an item
		that refers back to a higher level making a deep copy with
		{noref} set to 1 will fail.
		Also see |<A HREF="#copy()">copy()</A>|.


delete({fname} [, {flags}])					*<A NAME="delete()"></A><B>delete()</B>*
		Without {flags} or with {flags} empty: Deletes the file by the
		name {fname}.  This also works when {fname} is a symbolic link.

		When {flags} is &quot;<A HREF="change.html#d">d</A>&quot;: Deletes the directory by the name
		{fname}.  This fails when directory {fname} is not empty.
		
		When {flags} is &quot;rf&quot;: Deletes the directory by the name
		{fname} and everything in <A HREF="motion.html#it">it</A>, recursively.  BE CAREFUL!
		A symbolic link itself is deleted, not what <A HREF="motion.html#it">it</A> points to.
		
		The result is a <A HREF="#Number">Number</A>, which is 0 if the delete operation was
		successful and -1 when the deletion failed or partly failed.

		Use |<A HREF="#remove()">remove()</A>| to delete an item from a |<A HREF="#List">List</A>|.
		To delete a line from the buffer use |<A HREF="change.html#:delete">:delete</A>|.  Use |<A HREF="#:exe">:exe</A>|
		when the line number is in a variable.


							*<A NAME="did_filetype()"></A><B>did_filetype()</B>*
<A HREF="#did_filetype()">did_filetype()</A>	Returns non-zero when autocommands are being executed and the
		<A HREF="autocmd.html#FileType">FileType</A> event has been triggered at least once.  Can be used
		to avoid triggering the <A HREF="autocmd.html#FileType">FileType</A> event again in the scripts
		that detect the file type. |<A HREF="autocmd.html#FileType">FileType</A>|
		When editing another file, the counter is reset, thus this
		really checks if the <A HREF="autocmd.html#FileType">FileType</A> event has been triggered for the
		current buffer.  This allows an <A HREF="autocmd.html#autocommand">autocommand</A> that starts
		editing another buffer to set <A HREF="options.html#'filetype'">'filetype'</A> and load a <A HREF="syntax.html#syntax">syntax</A>
		file.


diff_filler({lnum})					*<A NAME="diff_filler()"></A><B>diff_filler()</B>*
		Returns the number of filler lines above line {lnum}.
		These are the lines that were inserted at this point in
		another diff'ed <A HREF="windows.html#window">window</A>.  These filler lines are shown in the
		display but don't exist in the buffer.
		{lnum} is used like with |<A HREF="#getline()">getline()</A>|.  Thus &quot;<A HREF="repeat.html#.">.</A>&quot; is the current
		line, &quot;'m&quot; <A HREF="motion.html#mark">mark</A> <A HREF="motion.html#m">m</A>, etc.
		Returns 0 if the current <A HREF="windows.html#window">window</A> is not in <A HREF="diff.html#diff">diff</A> mode.


diff_hlID({lnum}, {col})				*<A NAME="diff_hlID()"></A><B>diff_hlID()</B>*
		Returns the highlight ID for <A HREF="diff.html#diff">diff</A> mode at line {lnum} column
		{col} (byte index).  When the current line does not have a
		<A HREF="diff.html#diff">diff</A> change zero is returned.
		{lnum} is used like with |<A HREF="#getline()">getline()</A>|.  Thus &quot;<A HREF="repeat.html#.">.</A>&quot; is the current
		line, &quot;'m&quot; <A HREF="motion.html#mark">mark</A> <A HREF="motion.html#m">m</A>, etc.
		{col} is 1 for the leftmost column, {lnum} is 1 for the first
		line.
		The highlight ID can be used with |<A HREF="#synIDattr()">synIDattr()</A>| to obtain
		<A HREF="syntax.html#syntax">syntax</A> information about the highlighting.


					*<A NAME="disable_char_avail_for_testing()"></A><B>disable_char_avail_for_testing()</B>*
disable_char_avail_for_testing({expr})
		When {expr} is 1 the internal char_avail() function will
		return FALSE.  When {expr} is 0 the char_avail() function will
		function normally.
		Only use this for a test where typeahead causes the test not
		to work.  E.g., to trigger the <A HREF="autocmd.html#CursorMovedI">CursorMovedI</A> <A HREF="autocmd.html#autocommand">autocommand</A> event.


empty({expr})						*<A NAME="empty()"></A><B>empty()</B>*
		Return the <A HREF="#Number">Number</A> 1 if {expr} is empty, zero otherwise.
		- A |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| is empty when <A HREF="motion.html#it">it</A> does not have any
		  items.
		- A <A HREF="#Number">Number</A> and <A HREF="#Float">Float</A> is empty when its value is zero.
		- |<A HREF="#v:false">v:false</A>|, |<A HREF="#v:none">v:none</A>| and |<A HREF="#v:null">v:null</A>| are empty, |<A HREF="#v:true">v:true</A>| is not.
		- A <A HREF="#Job">Job</A> is empty when <A HREF="motion.html#it">it</A> failed to start.
		- A <A HREF="#Channel">Channel</A> is empty when <A HREF="motion.html#it">it</A> is closed.

		For a long |<A HREF="#List">List</A>| this is much faster than comparing the
		length with zero.


escape({string}, {chars})				*<A NAME="escape()"></A><B>escape()</B>*
		Escape the characters in {chars} that occur in {string} with a
		<A HREF="intro.html#backslash">backslash</A>.  Example:
<B>			:echo escape('c:\program files\vim', ' \')</B>
 		results in:
<B>			c:\\program\ files\\vim</B>
 		Also see |<A HREF="#shellescape()">shellescape()</A>|.


							*<A NAME="eval()"></A><B>eval()</B>*
eval({string})	Evaluate {string} and return the result.  Especially useful to
		turn the result of |<A HREF="#string()">string()</A>| back into the original value.
		This works for Numbers, Floats, Strings and composites of
		them.  Also works for |<A HREF="#Funcref">Funcref</A>|<A HREF="change.html#s">s</A> that refer to existing
		<A HREF="#functions">functions</A>.


<A HREF="#eventhandler()">eventhandler()</A>						*<A NAME="eventhandler()"></A><B>eventhandler()</B>*
		Returns 1 when inside an event handler.  That is that Vim got
		interrupted while waiting for the user to type a character,
		e.g., when dropping a file on Vim.  This means interactive
		commands cannot be used.  Otherwise zero is returned.


executable({expr})					*<A NAME="executable()"></A><B>executable()</B>*
		This function checks if an executable with the name {expr}
		exists.  {expr} must be the name of the program without any
		arguments.
		<A HREF="#executable()">executable()</A> uses the value of $PATH and/or the normal

		searchpath for programs.		*<A NAME="PATHEXT"></A><B>PATHEXT</B>*
		On <A HREF="os_msdos.html#MS-DOS">MS-DOS</A> and <A HREF="os_win32.html#MS-Windows">MS-Windows</A> the &quot;.exe&quot;, &quot;.bat&quot;, etc. can
		optionally be included.  Then the extensions in $PATHEXT are
		tried.	Thus if &quot;foo.exe&quot; does not exist, &quot;foo.exe.bat&quot; can be
		found.	If $PATHEXT is not set then &quot;.exe;.com;.bat;.cmd&quot; is
		used.  A dot by itself can be used in $PATHEXT to try using
		the name without an extension.	When <A HREF="options.html#'shell'">'shell'</A> looks like a
		<A HREF="os_unix.html#Unix">Unix</A> shell, then the name is also tried without adding an
		extension.
		On <A HREF="os_msdos.html#MS-DOS">MS-DOS</A> and <A HREF="os_win32.html#MS-Windows">MS-Windows</A> <A HREF="motion.html#it">it</A> only checks if the file exists and
		is not a directory, not if it's really executable.
		On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> an executable in the same directory <A HREF="motion.html#as">as</A> Vim is
		always found.  Since this directory is added to $PATH <A HREF="motion.html#it">it</A>
		should also work to execute <A HREF="motion.html#it">it</A> |<A HREF="os_win32.html#win32-PATH">win32-PATH</A>|.
		The result is a <A HREF="#Number">Number</A>:
			1	exists
			0	does not exist
			-1	not implemented on this system


exepath({expr})						*<A NAME="exepath()"></A><B>exepath()</B>*
		If {expr} is an executable and is either an absolute path, a
		relative path or found in $PATH, return the full path.
		Note that the current directory is used when {expr} starts
		with &quot;./&quot;, which may be a problem for Vim:
<B>			echo exepath(v:progpath)</B>
 		If {expr} cannot be found in $PATH or is not executable then
		an empty <A HREF="#string">string</A> is returned.


							*<A NAME="exists()"></A><B>exists()</B>*
exists({expr})	The result is a <A HREF="#Number">Number</A>, which is non-zero if {expr} is
		defined, zero otherwise.  The {expr} argument is a <A HREF="#string">string</A>,
		which contains one of these:
			&amp;option-name	Vim option (only checks if <A HREF="motion.html#it">it</A> exists,
					not if <A HREF="motion.html#it">it</A> really works)
			+option-name	Vim option that works.
			$ENVNAME	environment variable (could also be
					done by comparing with an empty
					<A HREF="#string">string</A>)
			*funcname	built-in function (see |<A HREF="#functions">functions</A>|)
					or user defined function (see
					|<A HREF="#user-functions">user-functions</A>|). Also works for a
					variable that is a <A HREF="#Funcref">Funcref</A>.
			varname		internal variable (see
					|<A HREF="#internal-variables">internal-variables</A>|).	Also works
					for |<A HREF="#curly-braces-names">curly-braces-names</A>|, |<A HREF="#Dictionary">Dictionary</A>|
					entries, |<A HREF="#List">List</A>| items, etc.  Beware
					that evaluating an index may cause an
					error message for an invalid
					<A HREF="#expression">expression</A>.  E.g.:
<B>					   :let l = [1, 2, 3]</B>
<B>					   :echo exists("l[5]")</B>
 					   0
<B>					   :echo exists("l[xx]")</B>
 					   <A HREF="#E121">E121</A>: Undefined variable: xx
					   0
			:cmdname	<A HREF="intro.html#Ex">Ex</A> command: built-in command, user
					command or command modifier |<A HREF="map.html#:command">:command</A>|.
					Returns:
					1  for match with start of a command
					2  full match with a command
					3  matches several user commands
					To check for a supported command
					always check the return value to be 2.
			:2match		The |<A HREF="pattern.html#:2match">:2match</A>| command.
			:3match		The |<A HREF="pattern.html#:3match">:3match</A>| command.
			#event		<A HREF="autocmd.html#autocommand">autocommand</A> defined for this event
			#event#pattern	<A HREF="autocmd.html#autocommand">autocommand</A> defined for this event and
					<A HREF="pattern.html#pattern">pattern</A> (the <A HREF="pattern.html#pattern">pattern</A> is taken
					literally and compared to the
					<A HREF="autocmd.html#autocommand">autocommand</A> patterns character by
					character)
			#group		<A HREF="autocmd.html#autocommand">autocommand</A> group exists
			#group#event	<A HREF="autocmd.html#autocommand">autocommand</A> defined for this group and
					event.
			#group#event#pattern
					<A HREF="autocmd.html#autocommand">autocommand</A> defined for this group,
					event and <A HREF="pattern.html#pattern">pattern</A>.
			##event		<A HREF="autocmd.html#autocommand">autocommand</A> for this event is
					supported.
		For checking for a supported feature use |<A HREF="#has()">has()</A>|.

		Examples:
<B>			exists("&amp;shortname")</B>
<B>			exists("$HOSTNAME")</B>
<B>			exists("*strftime")</B>
<B>			exists("*s:MyFunc")</B>
<B>			exists("bufcount")</B>
<B>			exists(":Make")</B>
<B>			exists("#CursorHold")</B>
<B>			exists("#BufReadPre#*.gz")</B>
<B>			exists("#filetypeindent")</B>
<B>			exists("#filetypeindent#FileType")</B>
<B>			exists("#filetypeindent#FileType#*")</B>
<B>			exists("##ColorScheme")</B>
 		There must be no space between the symbol (&amp;/$/*/#) and the
		name.
		There must be no extra characters after the name, although in
		a few cases this is ignored.  That may become more strict in
		the future, thus don't <A HREF="intro.html#count">count</A> on <A HREF="motion.html#it">it</A>!
		Working example:
<B>			exists(":make")</B>
 		NOT working example:
<B>			exists(":make install")</B>

 		Note that the argument must be a <A HREF="#string">string</A>, not the name of the
		variable itself.  For example:
<B>			exists(bufcount)</B>
 		This doesn't check for existence of the &quot;bufcount&quot; variable,
		but gets the value of &quot;bufcount&quot;, and checks if that exists.


exp({expr})						*<A NAME="exp()"></A><B>exp()</B>*
		Return the exponential of {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| in the range
		[0, inf].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo exp(2)</B>
 			7.389056
<B>			:echo exp(-1)</B>
 			0.367879
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



expand({expr} [, {nosuf} [, {list}]])				*<A NAME="expand()"></A><B>expand()</B>*
		Expand <A HREF="editing.html#wildcards">wildcards</A> and the following special keywords in {expr}.
		<A HREF="options.html#'wildignorecase'">'wildignorecase'</A> applies.

		If {list} is given and <A HREF="motion.html#it">it</A> is non-zero, a <A HREF="#List">List</A> will be returned.
		Otherwise the result is a <A HREF="#String">String</A> and when there are several
		matches, they are separated by <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> characters.  [Note: in
		version 5.0 a space was used, which caused problems when a
		file name contains a space]

		If the expansion fails, the result is an empty <A HREF="#string">string</A>.	A name
		for a non-existing file is not included, unless {expr} does
		not start with '<A HREF="motion.html#&#37;">&#37;</A>', '<A HREF="pattern.html##">#</A>' or '<A HREF="change.html#&lt;">&lt;</A>', see below.

		When {expr} starts with '<A HREF="motion.html#&#37;">&#37;</A>', '<A HREF="pattern.html##">#</A>' or '<A HREF="change.html#&lt;">&lt;</A>', the expansion is done
		like for the |<A HREF="cmdline.html#cmdline-special">cmdline-special</A>| <A HREF="#variables">variables</A> with their associated
		modifiers.  Here is a short overview:

			<A HREF="motion.html#&#37;">&#37;</A>		current file name
			#		alternate file name
			#n		alternate file name <A HREF="pattern.html#n">n</A>
			<A HREF="cmdline.html#&lt;cfile&gt;">&lt;cfile&gt;</A>		file name under the cursor
			<A HREF="cmdline.html#&lt;afile&gt;">&lt;afile&gt;</A>		autocmd file name
			<A HREF="cmdline.html#&lt;abuf&gt;">&lt;abuf&gt;</A>		autocmd buffer number (as a String!)
			<A HREF="cmdline.html#&lt;amatch&gt;">&lt;amatch&gt;</A>	autocmd matched name
			<A HREF="cmdline.html#&lt;sfile&gt;">&lt;sfile&gt;</A>		sourced <A HREF="usr_41.html#script">script</A> file or function name
			<A HREF="cmdline.html#&lt;slnum&gt;">&lt;slnum&gt;</A>		sourced <A HREF="usr_41.html#script">script</A> file line number
			&lt;cword&gt;		<A HREF="motion.html#word">word</A> under the cursor
			&lt;cWORD&gt;		<A HREF="motion.html#WORD">WORD</A> under the cursor
			&lt;client&gt;	the {clientid} of the last received
					message |<A HREF="#server2client()">server2client()</A>|
		Modifiers:
			<A HREF="various.html#:p">:p</A>		expand to full path
			<A HREF="helphelp.html#:h">:h</A>		head (last path component removed)
			<A HREF="change.html#:t">:t</A>		tail (last path component only)
			<A HREF="insert.html#:r">:r</A>		root (one extension removed)
			<A HREF="editing.html#:e">:e</A>		extension only

		Example:
<B>			:let &amp;tags = expand("%:p:h") . "/tags"</B>
 		Note that when expanding a <A HREF="#string">string</A> that starts with '<A HREF="motion.html#&#37;">&#37;</A>', '<A HREF="pattern.html##">#</A>' or
		'<A HREF="change.html#&lt;">&lt;</A>', any following text is ignored.  This does NOT work:
<B>			:let doesntwork = expand("%:h.bak")</B>
 		Use this:
<B>			:let doeswork = expand("%:h") . ".bak"</B>
 		Also note that expanding &quot;<A HREF="cmdline.html#&lt;cfile&gt;">&lt;cfile&gt;</A>&quot; and others only returns the
		referenced file name without further expansion.  If &quot;<A HREF="cmdline.html#&lt;cfile&gt;">&lt;cfile&gt;</A>&quot;
		is &quot;~/.cshrc&quot;, you need to <A HREF="diff.html#do">do</A> another <A HREF="#expand()">expand()</A> to have the
		&quot;~/&quot; expanded into the path of the home directory:
<B>			:echo expand(expand("&lt;cfile&gt;"))</B>
 
		There cannot be white space between the <A HREF="#variables">variables</A> and the
		following modifier.  The |<A HREF="#fnamemodify()">fnamemodify()</A>| function can be used
		to modify normal file names.

		When using '<A HREF="motion.html#&#37;">&#37;</A>' or '<A HREF="pattern.html##">#</A>', and the current or alternate file name
		is not defined, an empty <A HREF="#string">string</A> is used.  Using &quot;<A HREF="cmdline.html#&#37;:p">&#37;:p</A>&quot; in a
		buffer with no name, results in the current directory, with a
		'<A HREF="pattern.html#/">/</A>' added.

		When {expr} does not start with '<A HREF="motion.html#&#37;">&#37;</A>', '<A HREF="pattern.html##">#</A>' or '<A HREF="change.html#&lt;">&lt;</A>', <A HREF="motion.html#it">it</A> is
		expanded like a file name is expanded on the command line.
		<A HREF="options.html#'suffixes'">'suffixes'</A> and <A HREF="options.html#'wildignore'">'wildignore'</A> are used, unless the optional
		{nosuf} argument is given and <A HREF="motion.html#it">it</A> is non-zero.
		Names for non-existing files are included.  The &quot;**&quot; item can
		be used to search in a directory tree.  For example, to find
		all &quot;README&quot; files in the current directory and below:
<B>			:echo expand("**/README")</B>
 
		Expand() can also be used to expand <A HREF="#variables">variables</A> and environment
		<A HREF="#variables">variables</A> that are only known in a shell.  But this can be
		slow, because a shell may be used to <A HREF="diff.html#do">do</A> the expansion.  See
		|<A HREF="#expr-env-expand">expr-env-expand</A>|.
		The expanded variable is still handled like a <A HREF="#list">list</A> of file
		names.	When an environment variable cannot be expanded, <A HREF="motion.html#it">it</A> is
		left unchanged.  Thus &quot;<A HREF="#:echo">:echo</A> expand('$FOOBAR')&quot; results in
		&quot;$FOOBAR&quot;.

		See |<A HREF="#glob()">glob()</A>| for finding existing files.  See |<A HREF="#system()">system()</A>| for
		getting the raw output of an external command.


extend({expr1}, {expr2} [, {expr3}])			*<A NAME="extend()"></A><B>extend()</B>*
		{expr1} and {expr2} must be both |<A HREF="#Lists">Lists</A>| or both
		|<A HREF="#Dictionaries">Dictionaries</A>|.

		If they are |Lists|: Append {expr2} to {expr1}.
		If {expr3} is given insert the items of {expr2} before item
		{expr3} in {expr1}.  When {expr3} is zero insert before the
		first item.  When {expr3} is equal to len({expr1}) then
		{expr2} is appended.
		Examples:
<B>			:echo sort(extend(mylist, [7, 5]))</B>
<B>			:call extend(mylist, [2, 3], 1)</B>
 		When {expr1} is the same <A HREF="#List">List</A> <A HREF="motion.html#as">as</A> {expr2} then the number of
		items copied is equal to the original length of the <A HREF="#List">List</A>.
		E.g., when {expr3} is 1 you get N new copies of the first item
		(where N is the original length of the <A HREF="#List">List</A>).
		Use |<A HREF="#add()">add()</A>| to concatenate one item to a <A HREF="#list">list</A>.	To concatenate
		two lists into a new <A HREF="#list">list</A> use the + <A HREF="motion.html#operator">operator</A>:
<B>			:let newlist = [1, 2, 3] + [4, 5]</B>
 
		If they are YXXYDictionaries|:
		Add all entries from {expr2} to {expr1}.
		If a key exists in both {expr1} and {expr2} then {expr3} is
		used to decide what to <A HREF="diff.html#do">do</A>:
		{expr3} = &quot;keep&quot;: keep the value of {expr1}
		{expr3} = &quot;force&quot;: use the value of {expr2}

		{expr3} = &quot;error&quot;: give an error message		*<A NAME="E737"></A><B>E737</B>*
		When {expr3} is omitted then &quot;force&quot; is assumed.

		{expr1} is changed when {expr2} is not empty.  If necessary
		make a copy of {expr1} first.
		{expr2} remains unchanged.
		When {expr1} is locked and {expr2} is not empty the operation
		fails.
		Returns {expr1}.



feedkeys({string} [, {mode}])				*<A NAME="feedkeys()"></A><B>feedkeys()</B>*
		Characters in {string} are queued for processing <A HREF="motion.html#as">as</A> if they
		come from a <A HREF="map.html#mapping">mapping</A> or were typed by the user.
		By default the <A HREF="#string">string</A> is added to the end of the typeahead
		buffer, thus if a <A HREF="map.html#mapping">mapping</A> is still being executed the
		characters come after them.  Use the '<A HREF="insert.html#i">i</A>' flag to insert before
		other characters, they will be executed next, before any
		characters from a <A HREF="map.html#mapping">mapping</A>.
		The function does not wait for processing of keys contained in
		{string}.
		To include special keys into {string}, use double-quotes
		and &quot;\...&quot; <A HREF="intro.html#notation">notation</A> |<A HREF="#expr-quote">expr-quote</A>|. For example,
		feedkeys(&quot;\&lt;CR&gt;&quot;) simulates pressing of the <A HREF="intro.html#&lt;Enter&gt;">&lt;Enter&gt;</A> key. But
		feedkeys('\&lt;CR&gt;') pushes 5 characters.
		If {mode} is absent, keys are remapped.
		{mode} is a <A HREF="#String">String</A>, which can contain these character flags:
		'<A HREF="motion.html#m">m</A>'	Remap keys. This is default.
		'<A HREF="pattern.html#n">n</A>'	Do not remap keys.
		'<A HREF="motion.html#t">t</A>'	Handle keys <A HREF="motion.html#as">as</A> if typed; otherwise they are handled <A HREF="motion.html#as">as</A>
			if coming from a <A HREF="map.html#mapping">mapping</A>.  This matters for <A HREF="undo.html#undo">undo</A>,
			opening <A HREF="fold.html#folds">folds</A>, etc.
		'<A HREF="insert.html#i">i</A>'	<A HREF="insert.html#Insert">Insert</A> the <A HREF="#string">string</A> instead of appending (see above).
		'<A HREF="change.html#x">x</A>'	Execute commands until typeahead is empty.  This is
			similar to using &quot;:normal!&quot;.  You can call <A HREF="#feedkeys()">feedkeys()</A>
			several times without '<A HREF="change.html#x">x</A>' and then one time with '<A HREF="change.html#x">x</A>'
			(possibly with an empty {string}) to execute all the
			typeahead.
		Return value is always 0.


filereadable({file})					*<A NAME="filereadable()"></A><B>filereadable()</B>*
		The result is a <A HREF="#Number">Number</A>, which is TRUE when a file with the
		name <A HREF="editing.html#{file}">{file}</A> exists, and can be read.  If <A HREF="editing.html#{file}">{file}</A> doesn't exist,
		or is a directory, the result is FALSE.  <A HREF="editing.html#{file}">{file}</A> is any
		<A HREF="#expression">expression</A>, which is used <A HREF="motion.html#as">as</A> a <A HREF="#String">String</A>.
		If you don't care about the file being readable you can use
		|<A HREF="#glob()">glob()</A>|.

							*<A NAME="file_readable()"></A><B>file_readable()</B>*
		Obsolete name: <A HREF="#file_readable()">file_readable()</A>.



filewritable({file})					*<A NAME="filewritable()"></A><B>filewritable()</B>*
		The result is a <A HREF="#Number">Number</A>, which is 1 when a file with the
		name <A HREF="editing.html#{file}">{file}</A> exists, and can be written.  If <A HREF="editing.html#{file}">{file}</A> doesn't
		exist, or is not writable, the result is 0.  If <A HREF="editing.html#{file}">{file}</A> is a
		directory, and we can write to <A HREF="motion.html#it">it</A>, the result is 2.



filter({expr}, {string})					*<A NAME="filter()"></A><B>filter()</B>*
		{expr} must be a |<A HREF="#List">List</A>| or a |<A HREF="#Dictionary">Dictionary</A>|.
		For each item in {expr} evaluate {string} and when the result
		is zero remove the item from the |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>|.
		Inside {string} |<A HREF="#v:val">v:val</A>| has the value of the current item.
		For a |<A HREF="#Dictionary">Dictionary</A>| |<A HREF="#v:key">v:key</A>| has the key of the current item.
		Examples:
<B>			:call filter(mylist, 'v:val !~ "OLD"')</B>
 		Removes the items where &quot;OLD&quot; appears.
<B>			:call filter(mydict, 'v:key &gt;= 8')</B>
 		Removes the items with a key below 8.
<B>			:call filter(var, 0)</B>
 		Removes all the items, thus clears the |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>|.

		Note that {string} is the result of <A HREF="#expression">expression</A> and is then
		used <A HREF="motion.html#as">as</A> an <A HREF="#expression">expression</A> again.  Often <A HREF="motion.html#it">it</A> is good to use a
		|<A HREF="#literal-string">literal-string</A>| to avoid having to double backslashes.

		The operation is done in-place.  If you want a |<A HREF="#List">List</A>| or
		|<A HREF="#Dictionary">Dictionary</A>| to remain unmodified make a copy first:
<B>			:let l = filter(copy(mylist), 'v:val =~ "KEEP"')</B>

 		Returns {expr}, the |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| that was filtered.
		When an error is encountered while evaluating {string} no
		further items in {expr} are processed.



finddir({name}[, {path}[, {count}]])				*<A NAME="finddir()"></A><B>finddir()</B>*
		Find directory {name} in {path}.  Supports both downwards and
		upwards recursive directory searches.  See |<A HREF="editing.html#file-searching">file-searching</A>|
		for the <A HREF="syntax.html#syntax">syntax</A> of {path}.
		Returns the path of the first found match.  When the found
		directory is below the current directory a relative path is
		returned.  Otherwise a full path is returned.
		If {path} is omitted or empty then <A HREF="options.html#'path'">'path'</A> is used.
		If the optional {count} is given, find {count}'s occurrence of
		{name} in {path} instead of the first one.
		When {count} is negative return all the matches in a |<A HREF="#List">List</A>|.
		This is quite similar to the ex-command |<A HREF="editing.html#:find">:find</A>|.
		{only available when compiled with the |<A HREF="various.html#+file_in_path">+file_in_path</A>|
		feature}


findfile({name}[, {path}[, {count}]])				*<A NAME="findfile()"></A><B>findfile()</B>*
		Just like |<A HREF="#finddir()">finddir()</A>|, but find a file instead of a directory.
		Uses <A HREF="options.html#'suffixesadd'">'suffixesadd'</A>.
		Example:
<B>			:echo findfile("tags.vim", ".;")</B>
 		Searches from the directory of the current file upwards until
		<A HREF="motion.html#it">it</A> finds the file &quot;tags.vim&quot;.


float2nr({expr})					*<A NAME="float2nr()"></A><B>float2nr()</B>*
		Convert {expr} to a <A HREF="#Number">Number</A> by omitting the part after the
		decimal point.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a <A HREF="#Number">Number</A>.
		When the value of {expr} is out of range for a |<A HREF="#Number">Number</A>| the
		result is truncated to 0x7fffffff or -0x7fffffff.  NaN results
		in -0x80000000.
		Examples:
<B>			echo float2nr(3.95)</B>
 			3 
<B>			echo float2nr(-23.45)</B>
 			-23 
<B>			echo float2nr(1.0e100)</B>
 			2147483647 
<B>			echo float2nr(-1.0e150)</B>
 			-2147483647 
<B>			echo float2nr(1.0e-100)</B>
 			0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



floor({expr})							*<A NAME="floor()"></A><B>floor()</B>*
		Return the largest integral value <A HREF="various.html#less">less</A> than or equal to
		{expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| (round down).
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			echo floor(1.856)</B>
 			1.0 
<B>			echo floor(-5.456)</B>
 			-6.0 
<B>			echo floor(4.0)</B>
 			4.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		


fmod({expr1}, {expr2})					*<A NAME="fmod()"></A><B>fmod()</B>*
		Return the remainder of {expr1} / {expr2}, even if the
		division is not representable.  Returns {expr1} - <A HREF="insert.html#i">i</A> &#42; {expr2}
		for some integer <A HREF="insert.html#i">i</A> such that if {expr2} is non-zero, the
		result has the same sign <A HREF="motion.html#as">as</A> {expr1} and magnitude <A HREF="various.html#less">less</A> than
		the magnitude of {expr2}.  If {expr2} is zero, the value
		returned is zero.  The value returned is a |<A HREF="#Float">Float</A>|.
		{expr1} and {expr2} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo fmod(12.33, 1.22)</B>
 			0.13
<B>			:echo fmod(-12.33, 1.22)</B>
 			-0.13
		{only available when compiled with |<A HREF="various.html#+float">+float</A>| feature}



fnameescape({string})					*<A NAME="fnameescape()"></A><B>fnameescape()</B>*
		Escape {string} for use <A HREF="motion.html#as">as</A> file name command argument.	All
		characters that have a special meaning, such <A HREF="motion.html#as">as</A> '<A HREF="motion.html#&#37;">&#37;</A>' and '&#124;'
		are escaped with a <A HREF="intro.html#backslash">backslash</A>.
		For most systems the characters escaped are
		&quot; \t\n*?[{`$\\&#37;#'\&quot;|!&lt;&quot;.  For systems where a <A HREF="intro.html#backslash">backslash</A>
		appears in a filename, <A HREF="motion.html#it">it</A> depends on the value of <A HREF="options.html#'isfname'">'isfname'</A>.
		A leading '<A HREF="motion.html#+">+</A>' and '<A HREF="change.html#&gt;">&gt;</A>' is also escaped (special after |<A HREF="editing.html#:edit">:edit</A>|
		and |<A HREF="editing.html#:write">:write</A>|).  And a &quot;<A HREF="motion.html#-">-</A>&quot; by itself (special after |<A HREF="editing.html#:cd">:cd</A>|).
		Example:
<B>			:let fname = '+some str%nge|name'</B>
<B>			:exe "edit " . fnameescape(fname)</B>
 		results in executing:
<B>			edit \+some\ str\%nge\|name</B>


fnamemodify({fname}, {mods})				*<A NAME="fnamemodify()"></A><B>fnamemodify()</B>*
		Modify file name {fname} according to {mods}.  {mods} is a
		<A HREF="#string">string</A> of characters like <A HREF="motion.html#it">it</A> is used for file names on the
		command line.  See |<A HREF="cmdline.html#filename-modifiers">filename-modifiers</A>|.
		Example:
<B>			:echo fnamemodify("main.c", ":p:h")</B>
 		results in:
<B>			/home/mool/vim/vim/src</B>
 		Note: Environment <A HREF="#variables">variables</A> don't work in {fname}, use
		|<A HREF="#expand()">expand()</A>| first then.


foldclosed({lnum})					*<A NAME="foldclosed()"></A><B>foldclosed()</B>*
		The result is a <A HREF="#Number">Number</A>.  If the line {lnum} is in a closed
		fold, the result is the number of the first line in that fold.
		If the line {lnum} is not in a closed fold, -1 is returned.


foldclosedend({lnum})					*<A NAME="foldclosedend()"></A><B>foldclosedend()</B>*
		The result is a <A HREF="#Number">Number</A>.  If the line {lnum} is in a closed
		fold, the result is the number of the last line in that fold.
		If the line {lnum} is not in a closed fold, -1 is returned.


foldlevel({lnum})					*<A NAME="foldlevel()"></A><B>foldlevel()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the foldlevel of line {lnum}
		in the current buffer.	For nested <A HREF="fold.html#folds">folds</A> the deepest level is
		returned.  If there is no fold at line {lnum}, zero is
		returned.  It doesn't matter if the <A HREF="fold.html#folds">folds</A> are open or closed.
		When used while updating <A HREF="fold.html#folds">folds</A> (from <A HREF="options.html#'foldexpr'">'foldexpr'</A>) -1 is
		returned for lines where <A HREF="fold.html#folds">folds</A> are still to be updated and the
		foldlevel is unknown.  As a special <A HREF="change.html#case">case</A> the level of the
		previous line is usually available.


							*<A NAME="foldtext()"></A><B>foldtext()</B>*
<A HREF="#foldtext()">foldtext()</A>	Returns a <A HREF="#String">String</A>, to be displayed for a closed fold.  This is
		the default function used for the <A HREF="options.html#'foldtext'">'foldtext'</A> option and should
		only be called from evaluating <A HREF="options.html#'foldtext'">'foldtext'</A>.  It uses the
		|<A HREF="#v:foldstart">v:foldstart</A>|, |<A HREF="#v:foldend">v:foldend</A>| and |<A HREF="#v:folddashes">v:folddashes</A>| <A HREF="#variables">variables</A>.
		The returned <A HREF="#string">string</A> looks like this:
<B>			+-- 45 lines: abcdef</B>
 		The number of dashes depends on the foldlevel.	The &quot;45&quot; is
		the number of lines in the fold.  &quot;abcdef&quot; is the text in the
		first non-blank line of the fold.  Leading white space, &quot;<A HREF="version7.html#//">//</A>&quot;
		or &quot;/*&quot; and the text from the <A HREF="options.html#'foldmarker'">'foldmarker'</A> and <A HREF="options.html#'commentstring'">'commentstring'</A>
		<A HREF="options.html#options">options</A> is removed.
		{not available when compiled without the |<A HREF="various.html#+folding">+folding</A>| feature}


foldtextresult({lnum})					*<A NAME="foldtextresult()"></A><B>foldtextresult()</B>*
		Returns the text that is displayed for the closed fold at line
		{lnum}.  Evaluates <A HREF="options.html#'foldtext'">'foldtext'</A> in the appropriate context.
		When there is no closed fold at {lnum} an empty <A HREF="#string">string</A> is
		returned.
		{lnum} is used like with |<A HREF="#getline()">getline()</A>|.  Thus &quot;<A HREF="repeat.html#.">.</A>&quot; is the current
		line, &quot;'m&quot; <A HREF="motion.html#mark">mark</A> <A HREF="motion.html#m">m</A>, etc.
		Useful when exporting folded text, e.g., to HTML.
		{not available when compiled without the |<A HREF="various.html#+folding">+folding</A>| feature}


							*<A NAME="foreground()"></A><B>foreground()</B>*
<A HREF="#foreground()">foreground()</A>	Move the Vim <A HREF="windows.html#window">window</A> to the foreground.	Useful when sent from
		a client to a Vim server. |<A HREF="#remote_send()">remote_send()</A>|
		On <A HREF="os_win32.html#Win32">Win32</A> systems this might not work, the OS does not always
		allow a <A HREF="windows.html#window">window</A> to bring itself to the foreground.  Use
		|<A HREF="#remote_foreground()">remote_foreground()</A>| instead.
		{only in the <A HREF="os_win32.html#Win32">Win32</A>, <A HREF="gui_x11.html#Athena">Athena</A>, <A HREF="gui_x11.html#Motif">Motif</A> and <A HREF="gui_x11.html#GTK">GTK</A> <A HREF="gui.html#GUI">GUI</A> versions and the
		<A HREF="os_win32.html#Win32">Win32</A> console version}



					*<A NAME="function()"></A><B>function()</B>* *<A NAME="E700"></A><B>E700</B>* *<A NAME="E922"></A><B>E922</B>* *<A NAME="E923"></A><B>E923</B>*
function({name} [, {arglist}] [, {dict}])
		Return a |<A HREF="#Funcref">Funcref</A>| variable that refers to function {name}.
		{name} can be the name of a user defined function or an
		internal function.

		{name} can also be a <A HREF="#Funcref">Funcref</A>, also a partial.  When <A HREF="motion.html#it">it</A> is a
		partial the <A HREF="#dict">dict</A> stored in <A HREF="motion.html#it">it</A> will be used and the {dict}
		argument is not allowed. E.g.:
<B>			let FuncWithArg = function(dict.Func, [arg])</B>
<B>			let Broken = function(dict.Func, [arg], dict)</B>
 
		When <A HREF="editing.html#{arglist}">{arglist}</A> or {dict} is present this creates a partial.
		That mans the argument <A HREF="#list">list</A> and/or the dictionary is stored in
		the <A HREF="#Funcref">Funcref</A> and will be used when the <A HREF="#Funcref">Funcref</A> is called.
		
		The arguments are passed to the function in front of other
		arguments.  Example:
<B>			func Callback(arg1, arg2, name)</B>
<B>			...</B>
<B>			let Func = function('Callback', ['one', 'two'])</B>
<B>			...</B>
<B>			call Func('name')</B>
 		Invokes the function <A HREF="motion.html#as">as</A> with:
<B>			call Callback('one', 'two', 'name')</B>

 		The <A HREF="#function()">function()</A> call can be nested to add more arguments to the
		<A HREF="#Funcref">Funcref</A>.  The extra arguments are appended to the <A HREF="#list">list</A> of
		arguments.  Example:
<B>			func Callback(arg1, arg2, name)</B>
<B>			...</B>
<B>			let Func = function('Callback', ['one'])</B>
<B>			let Func2 = function(Func, ['two'])</B>
<B>			...</B>
<B>			call Func2('name')</B>
 		Invokes the function <A HREF="motion.html#as">as</A> with:
<B>			call Callback('one', 'two', 'name')</B>

 		The <A HREF="#Dictionary">Dictionary</A> is only useful when calling a &quot;<A HREF="#dict">dict</A>&quot; function.
		In that <A HREF="change.html#case">case</A> the {dict} is passed in <A HREF="motion.html#as">as</A> &quot;<A HREF="#self">self</A>&quot;. Example:
<B>			function Callback() dict</B>
<B>			   echo "called for " . self.name</B>
<B>			endfunction</B>
<B>			...</B>
<B>			let context = {"name": "example"}</B>
<B>			let Func = function('Callback', context)</B>
<B>			...</B>
<B>			call Func()	" will echo: called for example</B>
 		The use of <A HREF="#function()">function()</A> is not needed when there are no extra
		arguments, these two are equivalent:
<B>			let Func = function('Callback', context)</B>
<B>			let Func = context.Callback</B>

 		The argument <A HREF="#list">list</A> and the <A HREF="#Dictionary">Dictionary</A> can be combined:
<B>			function Callback(arg1, count) dict</B>
<B>			...</B>
<B>			let context = {"name": "example"}</B>
<B>			let Func = function('Callback', ['one'], context)</B>
<B>			...</B>
<B>			call Func(500)</B>
 		Invokes the function <A HREF="motion.html#as">as</A> with:
<B>			call context.Callback('one', 500)</B>



garbagecollect([{atexit}])				*<A NAME="garbagecollect()"></A><B>garbagecollect()</B>*
		Cleanup unused |<A HREF="#Lists">Lists</A>| and |<A HREF="#Dictionaries">Dictionaries</A>| that have circular
		references.  There is hardly ever a need to invoke this
		function, <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> is automatically done when Vim runs out of
		memory or is waiting for the user to press a key after
		<A HREF="options.html#'updatetime'">'updatetime'</A>.  Items without circular references are always
		freed when they become unused.
		This is useful if you have deleted a very big |<A HREF="#List">List</A>| and/or
		|<A HREF="#Dictionary">Dictionary</A>| with circular references in a <A HREF="usr_41.html#script">script</A> that runs
		for a long time.
		When the optional {atexit} argument is one, garbage
		collection will also be done when <A HREF="starting.html#exiting">exiting</A> Vim, if <A HREF="motion.html#it">it</A> wasn't
		done before.  This is useful when checking for memory leaks.


get({list}, {idx} [, {default}])			*<A NAME="get()"></A><B>get()</B>*
		Get item {idx} from |<A HREF="#List">List</A>| {list}.  When this item is not
		available return {default}.  Return zero when {default} is
		omitted.
get({dict}, {key} [, {default}])
		Get item with key {key} from |<A HREF="#Dictionary">Dictionary</A>| {dict}.  When this
		item is not available return {default}.  Return zero when
		{default} is omitted.


							*<A NAME="getbufline()"></A><B>getbufline()</B>*
getbufline({expr}, {lnum} [, {end}])
		Return a |<A HREF="#List">List</A>| with the lines starting from {lnum} to {end}
		(inclusive) in the buffer {expr}.  If {end} is omitted, a
		|<A HREF="#List">List</A>| with only the line {lnum} is returned.

		For the use of {expr}, see |<A HREF="#bufname()">bufname()</A>| above.

		For {lnum} and {end} &quot;<A HREF="motion.html#$">$</A>&quot; can be used for the last line of the
		buffer.  Otherwise a number must be used.

		When {lnum} is smaller than 1 or bigger than the number of
		lines in the buffer, an empty |<A HREF="#List">List</A>| is returned.

		When {end} is greater than the number of lines in the buffer,
		<A HREF="motion.html#it">it</A> is treated <A HREF="motion.html#as">as</A> {end} is set to the number of lines in the
		buffer.  When {end} is before {lnum} an empty |<A HREF="#List">List</A>| is
		returned.

		This function works only for loaded <A HREF="windows.html#buffers">buffers</A>.  For unloaded and
		non-existing <A HREF="windows.html#buffers">buffers</A>, an empty |<A HREF="#List">List</A>| is returned.

		Example:
<B>			:let lines = getbufline(bufnr("myfile"), 1, "$")</B>


getbufvar({expr}, {varname} [, {def}])				*<A NAME="getbufvar()"></A><B>getbufvar()</B>*
		The result is the value of option or local buffer variable
		{varname} in buffer {expr}.  Note that the name without &quot;<A HREF="#b:">b:</A>&quot;
		must be used.
		When {varname} is empty returns a dictionary with all the
		buffer-local <A HREF="#variables">variables</A>.
		This also works for a global or buffer-local option, but <A HREF="motion.html#it">it</A>
		doesn't work for a global variable, window-local variable or
		window-local option.
		For the use of {expr}, see |<A HREF="#bufname()">bufname()</A>| above.
		When the buffer or variable doesn't exist {def} or an empty
		<A HREF="#string">string</A> is returned, there is no error message.
		Examples:
<B>			:let bufmodified = getbufvar(1, "&amp;mod")</B>
<B>			:echo "todo myvar = " . getbufvar("todo", "myvar")</B>
 

getchar([expr])						*<A NAME="getchar()"></A><B>getchar()</B>*
		Get a single character from the user or input stream.
		If [expr] is omitted, wait until a character is available.
		If [expr] is 0, only get a character when one is available.
			Return zero otherwise.
		If [expr] is 1, only check if a character is available, <A HREF="motion.html#it">it</A> is
			not consumed.  Return zero if no character available.

		Without [expr] and when [expr] is 0 a whole character or
		special key is returned.  If <A HREF="motion.html#it">it</A> is an 8-bit character, the
		result is a number.  Use <A HREF="#nr2char()">nr2char()</A> to convert <A HREF="motion.html#it">it</A> to a <A HREF="#String">String</A>.
		Otherwise a <A HREF="#String">String</A> is returned with the encoded character.
		For a special key it's a sequence of bytes starting with 0x80
		(decimal: 128).  This is the same value <A HREF="motion.html#as">as</A> the <A HREF="#string">string</A>
		&quot;\&lt;Key&gt;&quot;, e.g., &quot;\&lt;Left&gt;&quot;.  The returned value is also a
		<A HREF="#String">String</A> when a modifier (shift, <A HREF="intro.html#control">control</A>, <A HREF="intro.html#alt">alt</A>) was used that is
		not included in the character.

		When [expr] is 0 and Esc is typed, there will be a short delay
		while Vim waits to see if this is the start of an <A HREF="intro.html#escape">escape</A>
		sequence.

		When [expr] is 1 only the first byte is returned.  For a
		one-byte character <A HREF="motion.html#it">it</A> is the character itself <A HREF="motion.html#as">as</A> a number.
		Use <A HREF="#nr2char()">nr2char()</A> to convert <A HREF="motion.html#it">it</A> to a <A HREF="#String">String</A>.

		Use <A HREF="#getcharmod()">getcharmod()</A> to obtain any additional modifiers.

		When the user clicks a mouse button, the mouse event will be
		returned.  The position can then be found in |<A HREF="#v:mouse_col">v:mouse_col</A>|,
		|<A HREF="#v:mouse_lnum">v:mouse_lnum</A>| and |<A HREF="#v:mouse_win">v:mouse_win</A>|.  This example positions the
		mouse <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> would normally happen:
<B>			let c = getchar()</B>
<B>			if c == "\&lt;LeftMouse&gt;" &amp;&amp; v:mouse_win &gt; 0</B>
<B>			  exe v:mouse_win . "wincmd w"</B>
<B>			  exe v:mouse_lnum</B>
<B>			  exe "normal " . v:mouse_col . "|"</B>
<B>			endif</B>
 
		There is no prompt, you will somehow have to make clear to the
		user that a character has to be typed.
		There is no <A HREF="map.html#mapping">mapping</A> for the character.
		Key codes are replaced, thus when the user presses the <A HREF="change.html#&lt;Del&gt;">&lt;Del&gt;</A>
		key you get the code for the <A HREF="change.html#&lt;Del&gt;">&lt;Del&gt;</A> key, not the raw character
		sequence.  Examples:
<B>			getchar() == "\&lt;Del&gt;"</B>
<B>			getchar() == "\&lt;S-Left&gt;"</B>
 		This example redefines &quot;<A HREF="motion.html#f">f</A>&quot; to ignore <A HREF="change.html#case">case</A>:
<B>			:nmap f :call FindChar()&lt;CR&gt;</B>
<B>			:function FindChar()</B>
<B>			:  let c = nr2char(getchar())</B>
<B>			:  while col('.') &lt; col('$') - 1</B>
<B>			:    normal l</B>
<B>			:    if getline('.')[col('.') - 1] ==? c</B>
<B>			:      break</B>
<B>			:    endif</B>
<B>			:  endwhile</B>
<B>			:endfunction</B>
 
		You may also receive synthetic characters, such <A HREF="motion.html#as">as</A>
		|<A HREF="autocmd.html#&lt;CursorHold&gt;">&lt;CursorHold&gt;</A>|. Often you will want to ignore this and get
		another character:
<B>			:function GetKey()</B>
<B>			:  let c = getchar()</B>
<B>			:  while c == "\&lt;CursorHold&gt;"</B>
<B>			:    let c = getchar()</B>
<B>			:  endwhile</B>
<B>			:  return c</B>
<B>			:endfunction</B>


<A HREF="#getcharmod()">getcharmod()</A>						*<A NAME="getcharmod()"></A><B>getcharmod()</B>*
		The result is a <A HREF="#Number">Number</A> which is the state of the modifiers for
		the last obtained character with <A HREF="#getchar()">getchar()</A> or in another way.
		These values are added together:
			2	<A HREF="intro.html#shift">shift</A>
			4	<A HREF="intro.html#control">control</A>
			8	<A HREF="intro.html#alt">alt</A> (meta)
			16	<A HREF="intro.html#meta">meta</A> (when it's different from ALT)
			32	mouse double click
			64	mouse triple click
			96	mouse quadruple click (== 32 + 64)
			128	command (Macintosh only)
		Only the modifiers that have not been included in the
		character itself are obtained.	Thus Shift-a results in &quot;<A HREF="insert.html#A">A</A>&quot;
		without a modifier.


<A HREF="#getcharsearch()">getcharsearch()</A>						*<A NAME="getcharsearch()"></A><B>getcharsearch()</B>*
		Return the current character search information <A HREF="motion.html#as">as</A> a {dict}
		with the following entries:

		    char	character previously used for a character
				search (|<A HREF="motion.html#t">t</A>|, |<A HREF="motion.html#f">f</A>|, |<A HREF="motion.html#T">T</A>|, or |<A HREF="motion.html#F">F</A>|); empty <A HREF="#string">string</A>
				if no character search has been performed
		    forward	direction of character search; 1 for forward,
				0 for backward
		    until	type of character search; 1 for a |<A HREF="motion.html#t">t</A>| or |<A HREF="motion.html#T">T</A>|
				character search, 0 for an |<A HREF="motion.html#f">f</A>| or |<A HREF="motion.html#F">F</A>|
				character search

		This can be useful to always have |<A HREF="motion.html#;">;</A>| and |<A HREF="motion.html#,">,</A>| search
		forward/backward regardless of the direction of the previous
		character search:
<B>			:nnoremap &lt;expr&gt; ; getcharsearch().forward ? ';' : ','</B>
<B>			:nnoremap &lt;expr&gt; , getcharsearch().forward ? ',' : ';'</B>
 		Also see |<A HREF="#setcharsearch()">setcharsearch()</A>|.


<A HREF="#getcmdline()">getcmdline()</A>						*<A NAME="getcmdline()"></A><B>getcmdline()</B>*
		Return the current command-line.  Only works when the command
		line is being edited, thus requires use of |<A HREF="cmdline.html#c_CTRL-\_e">c_CTRL-\_e</A>| or
		|<A HREF="cmdline.html#c_CTRL-R_=">c_CTRL-R_=</A>|.
		Example:
<B>			:cmap &lt;F7&gt; &lt;C-\&gt;eescape(getcmdline(), ' \')&lt;CR&gt;</B>
 		Also see |<A HREF="#getcmdtype()">getcmdtype()</A>|, |<A HREF="#getcmdpos()">getcmdpos()</A>| and |<A HREF="#setcmdpos()">setcmdpos()</A>|.


<A HREF="#getcmdpos()">getcmdpos()</A>						*<A NAME="getcmdpos()"></A><B>getcmdpos()</B>*
		Return the position of the cursor in the command line <A HREF="motion.html#as">as</A> a
		byte <A HREF="intro.html#count">count</A>.  The first column is 1.
		Only works when editing the command line, thus requires use of
		|<A HREF="cmdline.html#c_CTRL-\_e">c_CTRL-\_e</A>| or |<A HREF="cmdline.html#c_CTRL-R_=">c_CTRL-R_=</A>| or an <A HREF="#expression">expression</A> <A HREF="map.html#mapping">mapping</A>.
		Returns 0 otherwise.
		Also see |<A HREF="#getcmdtype()">getcmdtype()</A>|, |<A HREF="#setcmdpos()">setcmdpos()</A>| and |<A HREF="#getcmdline()">getcmdline()</A>|.


<A HREF="#getcmdtype()">getcmdtype()</A>						*<A NAME="getcmdtype()"></A><B>getcmdtype()</B>*
		Return the current command-line type. Possible return values
		are:
		    :	normal <A HREF="intro.html#Ex">Ex</A> command
		    <A HREF="change.html#&gt;">&gt;</A>	debug mode command |<A HREF="repeat.html#debug-mode">debug-mode</A>|
		    /	forward search command
		    ?	backward search command
		    @	|<A HREF="#input()">input()</A>| command
		    -	|<A HREF="insert.html#:insert">:insert</A>| or |<A HREF="insert.html#:append">:append</A>| command
		    =	|<A HREF="insert.html#i_CTRL-R_=">i_CTRL-R_=</A>|
		Only works when editing the command line, thus requires use of
		|<A HREF="cmdline.html#c_CTRL-\_e">c_CTRL-\_e</A>| or |<A HREF="cmdline.html#c_CTRL-R_=">c_CTRL-R_=</A>| or an <A HREF="#expression">expression</A> <A HREF="map.html#mapping">mapping</A>.
		Returns an empty <A HREF="#string">string</A> otherwise.
		Also see |<A HREF="#getcmdpos()">getcmdpos()</A>|, |<A HREF="#setcmdpos()">setcmdpos()</A>| and |<A HREF="#getcmdline()">getcmdline()</A>|.


<A HREF="#getcmdwintype()">getcmdwintype()</A>						*<A NAME="getcmdwintype()"></A><B>getcmdwintype()</B>*
		Return the current |<A HREF="cmdline.html#command-line-window">command-line-window</A>| type. Possible return
		values are the same <A HREF="motion.html#as">as</A> |<A HREF="#getcmdtype()">getcmdtype()</A>|. Returns an empty <A HREF="#string">string</A>
		when not in the command-line <A HREF="windows.html#window">window</A>.


							*<A NAME="getcurpos()"></A><B>getcurpos()</B>*
<A HREF="#getcurpos()">getcurpos()</A>	Get the position of the cursor.  This is like getpos('.'), but
		includes an extra item in the <A HREF="#list">list</A>:
<B><FONT COLOR="PURPLE">		    [bufnum, lnum, col, off, curswant] </FONT></B>
		The &quot;curswant&quot; number is the preferred column when moving the
		cursor vertically.
		This can be used to save and restore the cursor position:
<B>			let save_cursor = getcurpos()</B>
<B>			MoveTheCursorAround</B>
<B>			call setpos('.', save_cursor)</B>
 

							*<A NAME="getcwd()"></A><B>getcwd()</B>*
getcwd([{winnr} [, {tabnr}]])
		The result is a <A HREF="#String">String</A>, which is the name of the current
		working directory.
		Without arguments, for the current <A HREF="windows.html#window">window</A>.

		With {winnr} return the local current directory of this <A HREF="windows.html#window">window</A>
		in the current <A HREF="intro.html#tab">tab</A> page.
		With {winnr} and {tabnr} return the local current directory of
		the <A HREF="windows.html#window">window</A> in the specified <A HREF="intro.html#tab">tab</A> page.
		Return an empty <A HREF="#string">string</A> if the arguments are invalid.


getfsize({fname})					*<A NAME="getfsize()"></A><B>getfsize()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the size in bytes of the
		given file {fname}.
		If {fname} is a directory, 0 is returned.
		If the file {fname} can't be found, -1 is returned.
		If the size of {fname} is too big to fit in a <A HREF="#Number">Number</A> then -2
		is returned.


getfontname([{name}])					*<A NAME="getfontname()"></A><B>getfontname()</B>*
		Without an argument returns the name of the normal font being
		used.  Like what is used for the <A HREF="intro.html#Normal">Normal</A> highlight group
		|<A HREF="syntax.html#hl-Normal">hl-Normal</A>|.
		With an argument a check is done whether {name} is a valid
		font name.  If not then an empty <A HREF="#string">string</A> is returned.
		Otherwise the actual font name is returned, or {name} if the
		<A HREF="gui.html#GUI">GUI</A> does not support obtaining the real name.
		Only works when the <A HREF="gui.html#GUI">GUI</A> is running, thus not in your <A HREF="starting.html#vimrc">vimrc</A> or
		<A HREF="gui.html#gvimrc">gvimrc</A> file.  Use the |<A HREF="autocmd.html#GUIEnter">GUIEnter</A>| <A HREF="autocmd.html#autocommand">autocommand</A> to use this
		function just after the <A HREF="gui.html#GUI">GUI</A> has started.
		Note that the <A HREF="gui_x11.html#GTK">GTK</A> 2 <A HREF="gui.html#GUI">GUI</A> accepts any font name, thus checking
		for a valid name does not work.


getfperm({fname})					*<A NAME="getfperm()"></A><B>getfperm()</B>*
		The result is a <A HREF="#String">String</A>, which is the read, write, and execute
		permissions of the given file {fname}.
		If {fname} does not exist or its directory cannot be read, an
		empty <A HREF="#string">string</A> is returned.
		The result is of the form &quot;rwxrwxrwx&quot;, where each group of
		&quot;rwx&quot; flags represent, in turn, the permissions of the owner
		of the file, the group the file belongs to, and other users.
		If a user does not have a given permission the flag for this
		is replaced with the <A HREF="#string">string</A> &quot;<A HREF="motion.html#-">-</A>&quot;.  Examples:
<B>			:echo getfperm("/etc/passwd")</B>
<B>			:echo getfperm(expand("~/.vimrc"))</B>
 		This will hopefully (from a security point of <A HREF="starting.html#view">view</A>) display
		the <A HREF="#string">string</A> &quot;rw-r--r--&quot; or even &quot;rw-------&quot;.

		For setting permissins use |<A HREF="#setfperm()">setfperm()</A>|.


getftime({fname})					*<A NAME="getftime()"></A><B>getftime()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the last modification time of
		the given file {fname}.  The value is measured <A HREF="motion.html#as">as</A> seconds
		since 1st Jan 1970, and may be passed to <A HREF="#strftime()">strftime()</A>.  See also
		|<A HREF="#localtime()">localtime()</A>| and |<A HREF="#strftime()">strftime()</A>|.
		If the file {fname} can't be found -1 is returned.


getftype({fname})					*<A NAME="getftype()"></A><B>getftype()</B>*
		The result is a <A HREF="#String">String</A>, which is a description of the kind of
		file of the given file {fname}.
		If {fname} does not exist an empty <A HREF="#string">string</A> is returned.
		Here is a table over different kinds of files and their
		results:
			<A HREF="intro.html#Normal">Normal</A> file		&quot;file&quot;
			Directory		&quot;dir&quot;
			Symbolic link		&quot;link&quot;
			Block device		&quot;bdev&quot;
			Character device	&quot;cdev&quot;
			Socket			&quot;socket&quot;
			FIFO			&quot;fifo&quot;
			All other		&quot;other&quot;
		Example:
<B>			getftype("/home")</B>
 		Note that a type such <A HREF="motion.html#as">as</A> &quot;link&quot; will only be returned on
		systems that support <A HREF="motion.html#it">it</A>.  On some systems only &quot;dir&quot; and
		&quot;file&quot; are returned.  On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> a symbolic link to a
		directory returns &quot;dir&quot; instead of &quot;link&quot;.


							*<A NAME="getline()"></A><B>getline()</B>*
getline({lnum} [, {end}])
		Without {end} the result is a <A HREF="#String">String</A>, which is line {lnum}
		from the current buffer.  Example:
<B>			getline(1)</B>
 		When {lnum} is a <A HREF="#String">String</A> that doesn't start with a
		digit, <A HREF="#line()">line()</A> is called to translate the <A HREF="#String">String</A> into a <A HREF="#Number">Number</A>.
		To get the line under the cursor:
<B>			getline(".")</B>
 		When {lnum} is smaller than 1 or bigger than the number of
		lines in the buffer, an empty <A HREF="#string">string</A> is returned.

		When {end} is given the result is a |<A HREF="#List">List</A>| where each item is
		a line from the current buffer in the range {lnum} to {end},
		including line {end}.
		{end} is used in the same way <A HREF="motion.html#as">as</A> {lnum}.
		Non-existing lines are silently omitted.
		When {end} is before {lnum} an empty |<A HREF="#List">List</A>| is returned.
		Example:
<B>			:let start = line('.')</B>
<B>			:let end = search("^$") - 1</B>
<B>			:let lines = getline(start, end)</B>

 		To get lines from another buffer see |<A HREF="#getbufline()">getbufline()</A>|


getloclist({nr})					*<A NAME="getloclist()"></A><B>getloclist()</B>*
		Returns a <A HREF="#list">list</A> with all the entries in the location <A HREF="#list">list</A> for
		<A HREF="windows.html#window">window</A> {nr}. When {nr} is zero the current <A HREF="windows.html#window">window</A> is used.
		For a location <A HREF="#list">list</A> <A HREF="windows.html#window">window</A>, the displayed location <A HREF="#list">list</A> is
		returned.  For an invalid <A HREF="windows.html#window">window</A> number {nr}, an empty <A HREF="#list">list</A> is
		returned. Otherwise, same <A HREF="motion.html#as">as</A> |<A HREF="#getqflist()">getqflist()</A>|.


<A HREF="#getmatches()">getmatches()</A>						*<A NAME="getmatches()"></A><B>getmatches()</B>*
		Returns a |<A HREF="#List">List</A>| with all matches previously defined by
		|<A HREF="#matchadd()">matchadd()</A>| and the |<A HREF="pattern.html#:match">:match</A>| commands.  |<A HREF="#getmatches()">getmatches()</A>| is
		useful in combination with |<A HREF="#setmatches()">setmatches()</A>|, <A HREF="motion.html#as">as</A> |<A HREF="#setmatches()">setmatches()</A>|
		can restore a <A HREF="#list">list</A> of matches saved by |<A HREF="#getmatches()">getmatches()</A>|.
		Example:
<B>			:echo getmatches()</B>
 			[{'group': 'MyGroup1', '<A HREF="pattern.html#pattern">pattern</A>': 'TODO',
			'priority': 10, 'id': 1}, {'group': 'MyGroup2',
			'<A HREF="pattern.html#pattern">pattern</A>': 'FIXME', 'priority': 10, 'id': 2}]
<B>			:let m = getmatches()</B>
<B>			:call clearmatches()</B>
<B>			:echo getmatches()</B>
 			<A HREF="motion.html#[]">[]</A>
<B>			:call setmatches(m)</B>
<B>			:echo getmatches()</B>
 			[{'group': 'MyGroup1', '<A HREF="pattern.html#pattern">pattern</A>': 'TODO',
			'priority': 10, 'id': 1}, {'group': 'MyGroup2',
			'<A HREF="pattern.html#pattern">pattern</A>': 'FIXME', 'priority': 10, 'id': 2}]
<B>			:unlet m</B>
 

							*<A NAME="getpid()"></A><B>getpid()</B>*
<A HREF="#getpid()">getpid()</A>	Return a <A HREF="#Number">Number</A> which is the process ID of the Vim process.
		On <A HREF="os_unix.html#Unix">Unix</A> and <A HREF="os_win32.html#MS-Windows">MS-Windows</A> this is a unique number, until Vim
		exits.	On <A HREF="os_msdos.html#MS-DOS">MS-DOS</A> it's always zero.


							*<A NAME="getpos()"></A><B>getpos()</B>*
getpos({expr})	Get the position for {expr}.  For possible values of {expr}
		see |<A HREF="#line()">line()</A>|.  For getting the cursor position see
		|<A HREF="#getcurpos()">getcurpos()</A>|.
		The result is a |<A HREF="#List">List</A>| with four numbers:
		    [bufnum, lnum, col, off]
		&quot;bufnum&quot; is zero, unless a <A HREF="motion.html#mark">mark</A> like <A HREF="motion.html#'0">'0</A> or <A HREF="motion.html#'A">'A</A> is used, then <A HREF="motion.html#it">it</A>
		is the buffer number of the <A HREF="motion.html#mark">mark</A>.
		&quot;lnum&quot; and &quot;col&quot; are the position in the buffer.  The first
		column is 1.
		The &quot;off&quot; number is zero, unless <A HREF="options.html#'virtualedit'">'virtualedit'</A> is used.  Then
		<A HREF="motion.html#it">it</A> is the offset in screen columns from the start of the
		character.  E.g., a position within a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> or after the last
		character.
		Note that for <A HREF="motion.html#'&lt;">'&lt;</A> and <A HREF="motion.html#'&gt;">'&gt;</A> <A HREF="visual.html#Visual">Visual</A> mode matters: when <A HREF="motion.html#it">it</A> is &quot;<A HREF="visual.html#V">V</A>&quot;
		(visual line mode) the column of <A HREF="motion.html#'&lt;">'&lt;</A> is zero and the column of
		<A HREF="motion.html#'&gt;">'&gt;</A> is a large number.
		This can be used to save and restore the position of a <A HREF="motion.html#mark">mark</A>:
<B>			let save_a_mark = getpos("'a")</B>
<B>			...</B>
<B>			call setpos("'a", save_a_mark)</B>
 		Also see |<A HREF="#getcurpos()">getcurpos()</A>| and |<A HREF="#setpos()">setpos()</A>|.



<A HREF="#getqflist()">getqflist()</A>						*<A NAME="getqflist()"></A><B>getqflist()</B>*
		Returns a <A HREF="#list">list</A> with all the current <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="message.html#errors">errors</A>.  Each
		<A HREF="#list">list</A> item is a dictionary with these entries:
			bufnr	number of buffer that has the file name, use
				<A HREF="#bufname()">bufname()</A> to get the name
			lnum	line number in the buffer (first line is 1)
			col	column number (first column is 1)
			vcol	non-zero: &quot;col&quot; is visual column
				zero: &quot;col&quot; is byte index
			nr	error number
			<A HREF="pattern.html#pattern">pattern</A>	search <A HREF="pattern.html#pattern">pattern</A> used to locate the error
			text	description of the error
			type	type of the error, '<A HREF="motion.html#E">E</A>', '1', etc.
			valid	non-zero: recognized error message

		When there is no error <A HREF="#list">list</A> or it's empty an empty <A HREF="#list">list</A> is
		returned. <A HREF="quickfix.html#Quickfix">Quickfix</A> <A HREF="#list">list</A> entries with non-existing buffer
		number are returned with &quot;bufnr&quot; set to zero.

		Useful application: Find <A HREF="pattern.html#pattern">pattern</A> matches in multiple files and
		<A HREF="diff.html#do">do</A> something with them:
<B>			:vimgrep /theword/jg *.c</B>
<B>			:for d in getqflist()</B>
<B>			:   echo bufname(d.bufnr) ':' d.lnum '=' d.text</B>
<B>			:endfor</B>



getreg([{regname} [, 1 [, {list}]]])			*<A NAME="getreg()"></A><B>getreg()</B>*
		The result is a <A HREF="#String">String</A>, which is the contents of <A HREF="sponsor.html#register">register</A>
		{regname}.  Example:
<B>			:let cliptext = getreg('*')</B>
 		getreg('=') returns the last evaluated value of the <A HREF="#expression">expression</A>
		<A HREF="sponsor.html#register">register</A>.  (For use in maps.)
		getreg('=', 1) returns the <A HREF="#expression">expression</A> itself, so that <A HREF="motion.html#it">it</A> can
		be restored with |<A HREF="#setreg()">setreg()</A>|.  For other <A HREF="change.html#registers">registers</A> the extra
		argument is ignored, thus you can always give <A HREF="motion.html#it">it</A>.
		If {list} is present and non-zero result type is changed to 
		|<A HREF="#List">List</A>|. Each <A HREF="#list">list</A> item is one text line. Use <A HREF="motion.html#it">it</A> if you care
		about zero bytes possibly present inside <A HREF="sponsor.html#register">register</A>: without
		third argument both NLs and zero bytes are represented <A HREF="motion.html#as">as</A> NLs
		(see |<A HREF="pattern.html#NL-used-for-Nul">NL-used-for-Nul</A>|).
		If {regname} is not specified, |<A HREF="#v:register">v:register</A>| is used.



getregtype([{regname}])					*<A NAME="getregtype()"></A><B>getregtype()</B>*
		The result is a <A HREF="#String">String</A>, which is type of <A HREF="sponsor.html#register">register</A> {regname}.
		The value will be one of:
		    &quot;<A HREF="visual.html#v">v</A>&quot;			for |<A HREF="motion.html#characterwise">characterwise</A>| text
		    &quot;<A HREF="visual.html#V">V</A>&quot;			for |<A HREF="motion.html#linewise">linewise</A>| text
		    &quot;&lt;CTRL-V&gt;{width}&quot;	for |<A HREF="visual.html#blockwise-visual">blockwise-visual</A>| text
		    &quot;&quot;			for an empty or unknown <A HREF="sponsor.html#register">register</A>
		&lt;CTRL-V&gt; is one character with value 0x16.
		If {regname} is not specified, |<A HREF="#v:register">v:register</A>| is used.


gettabvar({tabnr}, {varname} [, {def}])				*<A NAME="gettabvar()"></A><B>gettabvar()</B>*
		Get the value of a tab-local variable {varname} in <A HREF="intro.html#tab">tab</A> page
		{tabnr}. |<A HREF="#t:var">t:var</A>|
		Tabs are numbered starting with one.
		When {varname} is empty a dictionary with all tab-local
		<A HREF="#variables">variables</A> is returned.
		Note that the name without &quot;<A HREF="#t:">t:</A>&quot; must be used.
		When the <A HREF="intro.html#tab">tab</A> or variable doesn't exist {def} or an empty
		<A HREF="#string">string</A> is returned, there is no error message.


gettabwinvar({tabnr}, {winnr}, {varname} [, {def}])		*<A NAME="gettabwinvar()"></A><B>gettabwinvar()</B>*
		Get the value of window-local variable {varname} in <A HREF="windows.html#window">window</A>
		{winnr} in <A HREF="intro.html#tab">tab</A> page {tabnr}.
		When {varname} starts with &quot;<A HREF="change.html#&amp;">&amp;</A>&quot; get the value of a window-local
		option.
		When {varname} is empty a dictionary with all window-local
		<A HREF="#variables">variables</A> is returned.
		Note that {varname} must be the name without &quot;<A HREF="#w:">w:</A>&quot;.
		Tabs are numbered starting with one.  For the current <A HREF="tabpage.html#tabpage">tabpage</A>
		use |<A HREF="#getwinvar()">getwinvar()</A>|.
		When {winnr} is zero the current <A HREF="windows.html#window">window</A> is used.
		This also works for a global option, buffer-local option and
		window-local option, but <A HREF="motion.html#it">it</A> doesn't work for a global variable
		or buffer-local variable.
		When the <A HREF="intro.html#tab">tab</A>, <A HREF="windows.html#window">window</A> or variable doesn't exist {def} or an
		empty <A HREF="#string">string</A> is returned, there is no error message.
		Examples:
<B>			:let list_is_on = gettabwinvar(1, 2, '&amp;list')</B>
<B>			:echo "myvar = " . gettabwinvar(3, 1, 'myvar')</B>
 

							*<A NAME="getwinposx()"></A><B>getwinposx()</B>*
<A HREF="#getwinposx()">getwinposx()</A>	The result is a <A HREF="#Number">Number</A>, which is the X coordinate in pixels of
		the left hand side of the <A HREF="gui.html#GUI">GUI</A> Vim <A HREF="windows.html#window">window</A>.  The result will be
		-1 if the information is not available.


							*<A NAME="getwinposy()"></A><B>getwinposy()</B>*
<A HREF="#getwinposy()">getwinposy()</A>	The result is a <A HREF="#Number">Number</A>, which is the <A HREF="change.html#Y">Y</A> coordinate in pixels of
		the top of the <A HREF="gui.html#GUI">GUI</A> Vim <A HREF="windows.html#window">window</A>.	The result will be -1 if the
		information is not available.


getwinvar({winnr}, {varname} [, {def}])				*<A NAME="getwinvar()"></A><B>getwinvar()</B>*
		Like |<A HREF="#gettabwinvar()">gettabwinvar()</A>| for the current <A HREF="tabpage.html#tabpage">tabpage</A>.
		Examples:
<B>			:let list_is_on = getwinvar(2, '&amp;list')</B>
<B>			:echo "myvar = " . getwinvar(1, 'myvar')</B>
 

glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])		*<A NAME="glob()"></A><B>glob()</B>*
		Expand the file wildcards in {expr}.  See |<A HREF="editing.html#wildcards">wildcards</A>| for the
		use of special characters.

		Unless the optional {nosuf} argument is given and is non-zero,
		the <A HREF="options.html#'suffixes'">'suffixes'</A> and <A HREF="options.html#'wildignore'">'wildignore'</A> <A HREF="options.html#options">options</A> apply: Names matching
		one of the patterns in <A HREF="options.html#'wildignore'">'wildignore'</A> will be skipped and
		<A HREF="options.html#'suffixes'">'suffixes'</A> affect the ordering of matches.
		<A HREF="options.html#'wildignorecase'">'wildignorecase'</A> always applies.

		When {list} is present and <A HREF="motion.html#it">it</A> is non-zero the result is a <A HREF="#List">List</A>
		with all matching files. The advantage of using a <A HREF="#List">List</A> is,
		you also get filenames containing newlines correctly.
		Otherwise the result is a <A HREF="#String">String</A> and when there are several
		matches, they are separated by <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> characters.

		If the expansion fails, the result is an empty <A HREF="#String">String</A> or <A HREF="#List">List</A>.

		A name for a non-existing file is not included.  A symbolic
		link is only included if <A HREF="motion.html#it">it</A> points to an existing file.
		However, when the {alllinks} argument is present and <A HREF="motion.html#it">it</A> is
		non-zero then all symbolic links are included.

		For most systems backticks can be used to get files names from
		any external command.  Example:
<B>			:let tagfiles = glob("`find . -name tags -print`")</B>
<B>			:let &amp;tags = substitute(tagfiles, "\n", ",", "g")</B>
 		The result of the program inside the backticks should be one
		item per line.	Spaces inside an item are allowed.

		See |<A HREF="#expand()">expand()</A>| for expanding special Vim <A HREF="#variables">variables</A>.  See
		|<A HREF="#system()">system()</A>| for getting the raw output of an external command.


glob2regpat({expr})					 *<A NAME="glob2regpat()"></A><B>glob2regpat()</B>*
		Convert a file <A HREF="pattern.html#pattern">pattern</A>, <A HREF="motion.html#as">as</A> used by <A HREF="#glob()">glob()</A>, into a search
		<A HREF="pattern.html#pattern">pattern</A>.  The result can be used to match with a <A HREF="#string">string</A> that
		is a file name.  E.g.
<B>			if filename =~ glob2regpat('Make*.mak')</B>
 		This is equivalent to:
<B>			if filename =~ '^Make.*\.mak$'</B>
 		When {expr} is an empty <A HREF="#string">string</A> the result is &quot;^$&quot;, match an
		empty <A HREF="#string">string</A>.


								*<A NAME="globpath()"></A><B>globpath()</B>*
globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
		Perform <A HREF="#glob()">glob()</A> on all directories in {path} and concatenate
		the results.  Example:
<B>			:echo globpath(&amp;rtp, "syntax/c.vim")</B>
 
		{path} is a comma-separated <A HREF="#list">list</A> of directory names.  Each
		directory name is prepended to {expr} and expanded like with
		|<A HREF="#glob()">glob()</A>|.  A path separator is inserted when needed.
		To add a comma inside a directory name <A HREF="intro.html#escape">escape</A> <A HREF="motion.html#it">it</A> with a
		<A HREF="intro.html#backslash">backslash</A>.  Note that on <A HREF="os_win32.html#MS-Windows">MS-Windows</A> a directory may have a
		trailing <A HREF="intro.html#backslash">backslash</A>, remove <A HREF="motion.html#it">it</A> if you put a comma after <A HREF="motion.html#it">it</A>.
		If the expansion fails for one of the directories, there is no
		error message.

		Unless the optional {nosuf} argument is given and is non-zero,
		the <A HREF="options.html#'suffixes'">'suffixes'</A> and <A HREF="options.html#'wildignore'">'wildignore'</A> <A HREF="options.html#options">options</A> apply: Names matching
		one of the patterns in <A HREF="options.html#'wildignore'">'wildignore'</A> will be skipped and
		<A HREF="options.html#'suffixes'">'suffixes'</A> affect the ordering of matches.

		When {list} is present and <A HREF="motion.html#it">it</A> is non-zero the result is a <A HREF="#List">List</A>
		with all matching files. The advantage of using a <A HREF="#List">List</A> is, you
		also get filenames containing newlines correctly. Otherwise
		the result is a <A HREF="#String">String</A> and when there are several matches,
		they are separated by <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> characters.  Example:
<B>			:echo globpath(&amp;rtp, "syntax/c.vim", 0, 1)</B>
 
		{alllinks} is used <A HREF="motion.html#as">as</A> with |<A HREF="#glob()">glob()</A>|.

		The &quot;**&quot; item can be used to search in a directory tree.
		For example, to find all &quot;README.txt&quot; files in the directories
		in <A HREF="options.html#'runtimepath'">'runtimepath'</A> and below:
<B>			:echo globpath(&amp;rtp, "**/README.txt")</B>
 		Upwards search and limiting the depth of &quot;**&quot; is not
		supported, thus using <A HREF="options.html#'path'">'path'</A> will not always work properly.


							*<A NAME="has()"></A><B>has()</B>*
has({feature})	The result is a <A HREF="#Number">Number</A>, which is 1 if the feature {feature} is
		supported, zero otherwise.  The {feature} argument is a
		<A HREF="#string">string</A>.  See |<A HREF="#feature-list">feature-list</A>| below.
		Also see |<A HREF="#exists()">exists()</A>|.



has_key({dict}, {key})					*<A NAME="has_key()"></A><B>has_key()</B>*
		The result is a <A HREF="#Number">Number</A>, which is 1 if |<A HREF="#Dictionary">Dictionary</A>| {dict} has
		an entry with key {key}.  Zero otherwise.


haslocaldir([{winnr} [, {tabnr}]])			*<A NAME="haslocaldir()"></A><B>haslocaldir()</B>*
		The result is a <A HREF="#Number">Number</A>, which is 1 when the <A HREF="windows.html#window">window</A> has set a
		local path via |<A HREF="editing.html#:lcd">:lcd</A>|, and 0 otherwise.

		Without arguments use the current <A HREF="windows.html#window">window</A>.
		With {winnr} use this <A HREF="windows.html#window">window</A> in the current <A HREF="intro.html#tab">tab</A> page.
		With {winnr} and {tabnr} use the <A HREF="windows.html#window">window</A> in the specified <A HREF="intro.html#tab">tab</A>
		page.
		Return 0 if the arguments are invalid.


hasmapto({what} [, {mode} [, {abbr}]])			*<A NAME="hasmapto()"></A><B>hasmapto()</B>*
		The result is a <A HREF="#Number">Number</A>, which is 1 if there is a <A HREF="map.html#mapping">mapping</A> that
		contains {what} in somewhere in the rhs (what <A HREF="motion.html#it">it</A> is mapped to)
		and this <A HREF="map.html#mapping">mapping</A> exists in one of the modes indicated by
		{mode}.
		When {abbr} is there and <A HREF="motion.html#it">it</A> is non-zero use <A HREF="map.html#abbreviations">abbreviations</A>
		instead of mappings.  Don't forget to specify <A HREF="insert.html#Insert">Insert</A> and/or
		<A HREF="cmdline.html#Command-line">Command-line</A> mode.
		Both the global mappings and the mappings local to the current
		buffer are checked for a match.
		If no matching <A HREF="map.html#mapping">mapping</A> is found 0 is returned.
		The following characters are recognized in {mode}:
			<A HREF="pattern.html#n">n</A>	<A HREF="intro.html#Normal">Normal</A> mode
			<A HREF="visual.html#v">v</A>	<A HREF="visual.html#Visual">Visual</A> mode
			<A HREF="insert.html#o">o</A>	<A HREF="intro.html#Operator-pending">Operator-pending</A> mode
			<A HREF="insert.html#i">i</A>	<A HREF="insert.html#Insert">Insert</A> mode
			<A HREF="motion.html#l">l</A>	Language-Argument (&quot;r&quot;, &quot;<A HREF="motion.html#f">f</A>&quot;, &quot;<A HREF="motion.html#t">t</A>&quot;, etc.)
			<A HREF="change.html#c">c</A>	<A HREF="cmdline.html#Command-line">Command-line</A> mode
		When {mode} is omitted, &quot;nvo&quot; is used.

		This function is useful to check if a <A HREF="map.html#mapping">mapping</A> already exists
		to a function in a Vim <A HREF="usr_41.html#script">script</A>.	Example:
<B>			:if !hasmapto('\ABCdoit')</B>
<B>			:   map &lt;Leader&gt;d \ABCdoit</B>
<B>			:endif</B>
 		This installs the <A HREF="map.html#mapping">mapping</A> to &quot;\ABCdoit&quot; only if there isn't
		already a <A HREF="map.html#mapping">mapping</A> to &quot;\ABCdoit&quot;.


histadd({history}, {item})				*<A NAME="histadd()"></A><B>histadd()</B>*
		Add the <A HREF="#String">String</A> {item} to the <A HREF="cmdline.html#history">history</A> {history} which can be

		one of:					*<A NAME="hist-names"></A><B>hist-names</B>*
			&quot;cmd&quot;	 or &quot;<A HREF="cmdline.html#:">:</A>&quot;	  command line <A HREF="cmdline.html#history">history</A>
			&quot;search&quot; or &quot;<A HREF="pattern.html#/">/</A>&quot;   search <A HREF="pattern.html#pattern">pattern</A> <A HREF="cmdline.html#history">history</A>
			&quot;<A HREF="#expr">expr</A>&quot;	 or &quot;<A HREF="change.html#=">=</A>&quot;   typed <A HREF="#expression">expression</A> <A HREF="cmdline.html#history">history</A>
			&quot;input&quot;  or &quot;<A HREF="repeat.html#@">@</A>&quot;	  input line <A HREF="cmdline.html#history">history</A>
			&quot;debug&quot;  or &quot;<A HREF="change.html#&gt;">&gt;</A>&quot;   debug command <A HREF="cmdline.html#history">history</A>
		The {history} <A HREF="#string">string</A> does not need to be the whole name, one
		character is sufficient.
		If {item} does already exist in the <A HREF="cmdline.html#history">history</A>, <A HREF="motion.html#it">it</A> will be
		shifted to become the newest entry.
		The result is a <A HREF="#Number">Number</A>: 1 if the operation was successful,
		otherwise 0 is returned.

		Example:
<B>			:call histadd("input", strftime("%Y %b %d"))</B>
<B>			:let date=input("Enter date: ")</B>
 		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.


histdel({history} [, {item}])				*<A NAME="histdel()"></A><B>histdel()</B>*
		Clear {history}, i.e. delete all its entries.  See |<A HREF="#hist-names">hist-names</A>|
		for the possible values of {history}.

		If the parameter {item} evaluates to a <A HREF="#String">String</A>, <A HREF="motion.html#it">it</A> is used <A HREF="motion.html#as">as</A> a
		regular <A HREF="#expression">expression</A>.  All entries matching that <A HREF="#expression">expression</A> will
		be removed from the <A HREF="cmdline.html#history">history</A> (if there are any).
		Upper/lowercase must match, unless &quot;\c&quot; is used |<A HREF="pattern.html#/\c">/\c</A>|.
		If {item} evaluates to a <A HREF="#Number">Number</A>, <A HREF="motion.html#it">it</A> will be interpreted <A HREF="motion.html#as">as</A>
		an index, see |<A HREF="cmdline.html#:history-indexing">:history-indexing</A>|.  The respective entry will
		be removed if <A HREF="motion.html#it">it</A> exists.

		The result is a <A HREF="#Number">Number</A>: 1 for a successful operation,
		otherwise 0 is returned.

		Examples:
		Clear <A HREF="#expression">expression</A> <A HREF="sponsor.html#register">register</A> <A HREF="cmdline.html#history">history</A>:
<B>			:call histdel("expr")</B>
 
		Remove all entries starting with &quot;*&quot; from the search <A HREF="cmdline.html#history">history</A>:
<B>			:call histdel("/", '^\*')</B>
 
		The following three are equivalent:
<B>			:call histdel("search", histnr("search"))</B>
<B>			:call histdel("search", -1)</B>
<B>			:call histdel("search", '^'.histget("search", -1).'$')</B>
 
		To delete the last search <A HREF="pattern.html#pattern">pattern</A> and use the last-but-one for
		the &quot;<A HREF="pattern.html#n">n</A>&quot; command and <A HREF="options.html#'hlsearch'">'hlsearch'</A>:
<B>			:call histdel("search", -1)</B>
<B>			:let @/ = histget("search", -1)</B>


histget({history} [, {index}])				*<A NAME="histget()"></A><B>histget()</B>*
		The result is a <A HREF="#String">String</A>, the entry with <A HREF="#Number">Number</A> {index} from
		{history}.  See |<A HREF="#hist-names">hist-names</A>| for the possible values of
		{history}, and |<A HREF="cmdline.html#:history-indexing">:history-indexing</A>| for {index}.  If there is
		no such entry, an empty <A HREF="#String">String</A> is returned.  When {index} is
		omitted, the most recent item from the <A HREF="cmdline.html#history">history</A> is used.

		Examples:
		Redo the second last search from <A HREF="cmdline.html#history">history</A>.
<B>			:execute '/' . histget("search", -2)</B>

 		Define an <A HREF="intro.html#Ex">Ex</A> command &quot;:H {num}&quot; that supports re-execution of
		the {num}th entry from the output of |<A HREF="cmdline.html#:history">:history</A>|.
<B>			:command -nargs=1 H execute histget("cmd", 0+&lt;args&gt;)</B>
 

histnr({history})					*<A NAME="histnr()"></A><B>histnr()</B>*
		The result is the <A HREF="#Number">Number</A> of the current entry in {history}.
		See |<A HREF="#hist-names">hist-names</A>| for the possible values of {history}.
		If an error occurred, -1 is returned.

		Example:
<B>			:let inp_index = histnr("expr")</B>
 

hlexists({name})					*<A NAME="hlexists()"></A><B>hlexists()</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero if a highlight group
		called {name} exists.  This is when the group has been
		defined in some way.  Not necessarily when highlighting has
		been defined for <A HREF="motion.html#it">it</A>, <A HREF="motion.html#it">it</A> may also have been used for a <A HREF="syntax.html#syntax">syntax</A>
		item.

							*<A NAME="highlight_exists()"></A><B>highlight_exists()</B>*
		Obsolete name: <A HREF="#highlight_exists()">highlight_exists()</A>.


							*<A NAME="hlID()"></A><B>hlID()</B>*
hlID({name})	The result is a <A HREF="#Number">Number</A>, which is the ID of the highlight group
		with name {name}.  When the highlight group doesn't exist,
		zero is returned.
		This can be used to retrieve information about the highlight
		group.	For example, to get the background color of the
		&quot;Comment&quot; group:
<B>	:echo synIDattr(synIDtrans(hlID("Comment")), "bg")</B>

 							*<A NAME="highlightID()"></A><B>highlightID()</B>*
		Obsolete name: <A HREF="#highlightID()">highlightID()</A>.


<A HREF="#hostname()">hostname()</A>						*<A NAME="hostname()"></A><B>hostname()</B>*
		The result is a <A HREF="#String">String</A>, which is the name of the machine on
		which Vim is currently running.  Machine names greater than
		256 characters long are truncated.


iconv({expr}, {from}, {to})				*<A NAME="iconv()"></A><B>iconv()</B>*
		The result is a <A HREF="#String">String</A>, which is the text {expr} converted
		from encoding {from} to encoding {to}.
		When the conversion completely fails an empty <A HREF="#string">string</A> is
		returned.  When some characters could not be converted they
		are replaced with &quot;<A HREF="pattern.html#?">?</A>&quot;.
		The encoding names are whatever the <A HREF="#iconv()">iconv()</A> library function
		can accept, see &quot;:!man 3 iconv&quot;.
		Most conversions require Vim to be compiled with the |<A HREF="various.html#+iconv">+iconv</A>|
		feature.  Otherwise only <A HREF="mbyte.html#UTF-8">UTF-8</A> to latin1 conversion and back
		can be done.
		This can be used to display <A HREF="message.html#messages">messages</A> with special characters,
		no matter what <A HREF="options.html#'encoding'">'encoding'</A> is set to.  Write the message in
		<A HREF="mbyte.html#UTF-8">UTF-8</A> and use:
<B>			echo iconv(utf8_str, "utf-8", &amp;enc)</B>
 		Note that Vim uses <A HREF="mbyte.html#UTF-8">UTF-8</A> for all <A HREF="mbyte.html#Unicode">Unicode</A> encodings, conversion
		from/to UCS-2 is automatically changed to use <A HREF="mbyte.html#UTF-8">UTF-8</A>.  You
		cannot use UCS-2 in a <A HREF="#string">string</A> anyway, because of the NUL bytes.
		{only available when compiled with the |<A HREF="various.html#+multi_byte">+multi_byte</A>| feature}


							*<A NAME="indent()"></A><B>indent()</B>*
indent({lnum})	The result is a <A HREF="#Number">Number</A>, which is indent of line {lnum} in the
		current buffer.  The indent is counted in spaces, the value
		of <A HREF="options.html#'tabstop'">'tabstop'</A> is relevant.  {lnum} is used just like in
		|<A HREF="#getline()">getline()</A>|.
		When {lnum} is invalid -1 is returned.



index({list}, {expr} [, {start} [, {ic}]])			*<A NAME="index()"></A><B>index()</B>*
		Return the lowest index in |<A HREF="#List">List</A>| {list} where the item has a
		value equal to {expr}.  There is no automatic conversion, so
		the <A HREF="#String">String</A> &quot;4&quot; is different from the <A HREF="#Number">Number</A> 4.  And the number
		4 is different from the <A HREF="#Float">Float</A> 4.0.  The value of <A HREF="options.html#'ignorecase'">'ignorecase'</A>
		is not used here, <A HREF="change.html#case">case</A> always matters.
		If {start} is given then start looking at the item with index
		{start} (may be negative for an item relative to the end).
		When {ic} is given and <A HREF="motion.html#it">it</A> is non-zero, ignore <A HREF="change.html#case">case</A>.  Otherwise
		<A HREF="change.html#case">case</A> must match.
		-1 is returned when {expr} is not found in {list}.
		Example:
<B>			:let idx = index(words, "the")</B>
<B>			:if index(numbers, 123) &gt;= 0</B>



input({prompt} [, {text} [, {completion}]])		*<A NAME="input()"></A><B>input()</B>*
		The result is a <A HREF="#String">String</A>, which is whatever the user typed on
		the command-line.  The {prompt} argument is either a prompt
		<A HREF="#string">string</A>, or a blank <A HREF="#string">string</A> (for no prompt).  A '\n' can be used
		in the prompt to start a new line.
		The highlighting set with |<A HREF="#:echohl">:echohl</A>| is used for the prompt.
		The input is entered just like a command-line, with the same
		editing commands and mappings.	There is a separate <A HREF="cmdline.html#history">history</A>
		for lines typed for <A HREF="#input()">input()</A>.
		Example:
<B>			:if input("Coffee or beer? ") == "beer"</B>
<B>			:  echo "Cheers!"</B>
<B>			:endif</B>
 
		If the optional {text} argument is present and not empty, this
		is used for the default reply, <A HREF="motion.html#as">as</A> if the user typed this.
		Example:
<B>			:let color = input("Color? ", "white")</B>

 		The optional {completion} argument specifies the type of
		completion supported for the input.  Without <A HREF="motion.html#it">it</A> completion is
		not performed.	The supported completion types are the same <A HREF="motion.html#as">as</A>
		that can be supplied to a user-defined command using the
		&quot;-complete=&quot; argument.	Refer to |<A HREF="map.html#:command-completion">:command-completion</A>| for
		more information.  Example:
<B>			let fname = input("File: ", "", "file")</B>
 
		NOTE: This function must not be used in a <A HREF="starting.html#startup">startup</A> file, for
		the versions that only run in <A HREF="gui.html#GUI">GUI</A> mode (e.g., the <A HREF="os_win32.html#Win32">Win32</A> <A HREF="gui.html#GUI">GUI</A>).
		Note: When <A HREF="#input()">input()</A> is called from within a <A HREF="map.html#mapping">mapping</A> <A HREF="motion.html#it">it</A> will
		consume remaining characters from that <A HREF="map.html#mapping">mapping</A>, because a
		<A HREF="map.html#mapping">mapping</A> is handled like the characters were typed.
		Use |<A HREF="#inputsave()">inputsave()</A>| before <A HREF="#input()">input()</A> and |<A HREF="#inputrestore()">inputrestore()</A>|
		after <A HREF="#input()">input()</A> to avoid that.  Another solution is to avoid
		that further characters follow in the <A HREF="map.html#mapping">mapping</A>, e.g., by using
		|<A HREF="#:execute">:execute</A>| or |<A HREF="various.html#:normal">:normal</A>|.

		Example with a <A HREF="map.html#mapping">mapping</A>:
<B>			:nmap \x :call GetFoo()&lt;CR&gt;:exe "/" . Foo&lt;CR&gt;</B>
<B>			:function GetFoo()</B>
<B>			:  call inputsave()</B>
<B>			:  let g:Foo = input("enter search pattern: ")</B>
<B>			:  call inputrestore()</B>
<B>			:endfunction</B>


inputdialog({prompt} [, {text} [, {cancelreturn}]])		*<A NAME="inputdialog()"></A><B>inputdialog()</B>*
		Like |<A HREF="#input()">input()</A>|, but when the <A HREF="gui.html#GUI">GUI</A> is running and text dialogs
		are supported, a <A HREF="gui_w32.html#dialog">dialog</A> <A HREF="windows.html#window">window</A> pops up to input the text.
		Example:
<B>		   :let n = inputdialog("value for shiftwidth", shiftwidth())</B>
<B>		   :if n != ""</B>
<B>		   :  let &amp;sw = n</B>
<B>		   :endif</B>
 		When the <A HREF="gui_w32.html#dialog">dialog</A> is cancelled {cancelreturn} is returned.  When
		omitted an empty <A HREF="#string">string</A> is returned.
		Hitting <A HREF="intro.html#&lt;Enter&gt;">&lt;Enter&gt;</A> works like pressing the OK button.  Hitting
		<A HREF="intro.html#&lt;Esc&gt;">&lt;Esc&gt;</A> works like pressing the Cancel button.
		NOTE: <A HREF="cmdline.html#Command-line">Command-line</A> completion is not supported.


inputlist({textlist})					*<A NAME="inputlist()"></A><B>inputlist()</B>*
		{textlist} must be a |<A HREF="#List">List</A>| of strings.  This |<A HREF="#List">List</A>| is
		displayed, one <A HREF="#string">string</A> per line.  The user will be prompted to
		enter a number, which is returned.
		The user can also select an item by clicking on <A HREF="motion.html#it">it</A> with the
		mouse.	For the first <A HREF="#string">string</A> 0 is returned.  When clicking
		above the first item a negative number is returned.  When
		clicking on the prompt one more than the length of {textlist}
		is returned.
		Make sure {textlist} has <A HREF="various.html#less">less</A> than <A HREF="options.html#'lines'">'lines'</A> entries, otherwise
		<A HREF="motion.html#it">it</A> won't work.	It's a good idea to put the entry number at
		the start of the <A HREF="#string">string</A>.  And put a prompt in the first item.
		Example:
<B>			let color = inputlist(['Select color:', '1. red',</B>
<B>				\ '2. green', '3. blue'])</B>


<A HREF="#inputrestore()">inputrestore()</A>						*<A NAME="inputrestore()"></A><B>inputrestore()</B>*
		Restore typeahead that was saved with a previous |<A HREF="#inputsave()">inputsave()</A>|.
		Should be called the same number of times <A HREF="#inputsave()">inputsave()</A> is
		called.  Calling <A HREF="motion.html#it">it</A> more often is harmless though.
		Returns 1 when there is nothing to restore, 0 otherwise.


<A HREF="#inputsave()">inputsave()</A>						*<A NAME="inputsave()"></A><B>inputsave()</B>*
		Preserve typeahead (also from mappings) and clear <A HREF="motion.html#it">it</A>, so that
		a following prompt gets input from the user.  Should be
		followed by a matching <A HREF="#inputrestore()">inputrestore()</A> after the prompt.  Can
		be used several times, in which <A HREF="change.html#case">case</A> there must be just <A HREF="motion.html#as">as</A>
		many <A HREF="#inputrestore()">inputrestore()</A> calls.
		Returns 1 when out of memory, 0 otherwise.


inputsecret({prompt} [, {text}])			*<A NAME="inputsecret()"></A><B>inputsecret()</B>*
		This function acts much like the |<A HREF="#input()">input()</A>| function with but
		two exceptions:
		<A HREF="motion.html#a)">a)</A> the user's response will be displayed <A HREF="motion.html#as">as</A> a sequence of
		asterisks (&quot;*&quot;) thereby keeping the entry secret, and
		<A HREF="motion.html#b">b</A>) the user's response will not be recorded on the input
		|<A HREF="cmdline.html#history">history</A>| stack.
		The result is a <A HREF="#String">String</A>, which is whatever the user actually
		typed on the command-line in response to the issued prompt.
		NOTE: <A HREF="cmdline.html#Command-line">Command-line</A> completion is not supported.


insert({list}, {item} [, {idx}])			*<A NAME="insert()"></A><B>insert()</B>*
		<A HREF="insert.html#Insert">Insert</A> {item} at the start of |<A HREF="#List">List</A>| {list}.
		If {idx} is specified insert {item} before the item with index
		{idx}.	If {idx} is zero <A HREF="motion.html#it">it</A> goes before the first item, just
		like omitting {idx}.  A negative {idx} is also possible, see
		|<A HREF="#list-index">list-index</A>|.  -1 inserts just before the last item.
		Returns the resulting |<A HREF="#List">List</A>|.  Examples:
<B>			:let mylist = insert([2, 3, 5], 1)</B>
<B>			:call insert(mylist, 4, -1)</B>
<B>			:call insert(mylist, 6, len(mylist))</B>
 		The last example can be done simpler with |<A HREF="#add()">add()</A>|.
		Note that when {item} is a |<A HREF="#List">List</A>| <A HREF="motion.html#it">it</A> is inserted <A HREF="motion.html#as">as</A> a single
		item.  Use |<A HREF="#extend()">extend()</A>| to concatenate |<A HREF="#Lists">Lists</A>|.


invert({expr})						*<A NAME="invert()"></A><B>invert()</B>*
		Bitwise invert.  The argument is converted to a number.  A
		<A HREF="#List">List</A>, Dict or <A HREF="#Float">Float</A> argument causes an error.  Example:
<B>			:let bits = invert(bits)</B>


isdirectory({directory})				*<A NAME="isdirectory()"></A><B>isdirectory()</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero when a directory
		with the name {directory} exists.  If {directory} doesn't
		exist, or isn't a directory, the result is FALSE.  {directory}
		is any <A HREF="#expression">expression</A>, which is used <A HREF="motion.html#as">as</A> a <A HREF="#String">String</A>.


islocked({expr})					*<A NAME="islocked()"></A><B>islocked()</B>* *<A NAME="E786"></A><B>E786</B>*
		The result is a <A HREF="#Number">Number</A>, which is non-zero when {expr} is the
		name of a locked variable.
		{expr} must be the name of a variable, |<A HREF="#List">List</A>| item or
		|<A HREF="#Dictionary">Dictionary</A>| entry, not the variable itself!  Example:
<B>			:let alist = [0, ['a', 'b'], 2, 3]</B>
<B>			:lockvar 1 alist</B>
<B>			:echo islocked('alist')		" 1</B>
<B>			:echo islocked('alist[1]')	" 0</B>

 		When {expr} is a variable that does not exist you get an error
		message.  Use |<A HREF="#exists()">exists()</A>| to check for existence.


isnan({expr})						*<A NAME="isnan()"></A><B>isnan()</B>*
		Return non-zero if {expr} is a float with value NaN.
<B>			echo isnan(0.0 / 0.0)</B>
<B><FONT COLOR="PURPLE"> 			1 </FONT></B>

		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}


items({dict})						*<A NAME="items()"></A><B>items()</B>*
		Return a |<A HREF="#List">List</A>| with all the key-value pairs of {dict}.  Each
		|<A HREF="#List">List</A>| item is a <A HREF="#list">list</A> with two items: the key of a {dict}
		entry and the value of this entry.  The |<A HREF="#List">List</A>| is in arbitrary
		order.


job_getchannel({job})					 *<A NAME="job_getchannel()"></A><B>job_getchannel()</B>*
		Get the <A HREF="channel.html#channel">channel</A> handle that {job} is using.
		To check if the <A HREF="channel.html#job">job</A> has no <A HREF="channel.html#channel">channel</A>:
<B>			if string(job_getchannel()) == 'channel fail'</B>
 
		{only available when compiled with the |<A HREF="various.html#+job">+job</A>| feature}


job_info({job})						*<A NAME="job_info()"></A><B>job_info()</B>*
		Returns a <A HREF="#Dictionary">Dictionary</A> with information about {job}:
		   &quot;status&quot;	what |<A HREF="#job_status()">job_status()</A>| returns
		   &quot;channel&quot;	what |<A HREF="#job_getchannel()">job_getchannel()</A>| returns
		   &quot;exitval&quot;	only valid when &quot;status&quot; is &quot;dead&quot;
		   &quot;exit_cb&quot;	function to be called on exit
		   &quot;stoponexit&quot;	|<A HREF="channel.html#job-stoponexit">job-stoponexit</A>|


job_setoptions({job}, {options})			*<A NAME="job_setoptions()"></A><B>job_setoptions()</B>*
		Change <A HREF="options.html#options">options</A> for {job}.  Supported are:
		   &quot;stoponexit&quot;	|<A HREF="channel.html#job-stoponexit">job-stoponexit</A>|
		   &quot;exit_cb&quot;	|<A HREF="channel.html#job-exit_cb">job-exit_cb</A>|


job_start({command} [, {options}])			*<A NAME="job_start()"></A><B>job_start()</B>*
		Start a <A HREF="channel.html#job">job</A> and return a <A HREF="#Job">Job</A> object.  Unlike |<A HREF="#system()">system()</A>| and
		|<A HREF="various.html#:!cmd">:!cmd</A>| this does not wait for the <A HREF="channel.html#job">job</A> to finish.

		{command} can be a <A HREF="#String">String</A>.  This works best on <A HREF="os_win32.html#MS-Windows">MS-Windows</A>.  On
		<A HREF="os_unix.html#Unix">Unix</A> <A HREF="motion.html#it">it</A> is split up in white-separated parts to be passed to
		execvp().  Arguments in double <A HREF="quotes.html#quotes">quotes</A> can contain white space.

		{command} can be a <A HREF="#List">List</A>, where the first item is the executable
		and further items are the arguments.  All items are converted
		to <A HREF="#String">String</A>.  This works best on <A HREF="os_unix.html#Unix">Unix</A>.

		On <A HREF="os_win32.html#MS-Windows">MS-Windows</A>, <A HREF="#job_start()">job_start()</A> makes a <A HREF="gui.html#GUI">GUI</A> application hidden. If
		want to show <A HREF="motion.html#it">it</A>, Use |<A HREF="os_win32.html#:!start">:!start</A>| instead.

		The command is executed directly, not through a shell, the
		<A HREF="options.html#'shell'">'shell'</A> option is not used.  To use the shell:
<B>	let job = job_start(["/bin/sh", "-c", "echo hello"])</B>
 		Or:
<B>	let job = job_start('/bin/sh -c "echo hello"')</B>
 		Note that this will start two processes, the shell and the
		command <A HREF="motion.html#it">it</A> executes.  If you don't want this use the &quot;exec&quot;
		shell command.

		On <A HREF="os_unix.html#Unix">Unix</A> $PATH is used to search for the executable only when
		the command does not contain a slash.

		The <A HREF="channel.html#job">job</A> will use the same terminal <A HREF="motion.html#as">as</A> Vim.  If <A HREF="motion.html#it">it</A> reads from
		stdin the <A HREF="channel.html#job">job</A> and Vim will be fighting over input, that
		doesn't work.  Redirect stdin and stdout to avoid problems:
<B>	let job = job_start(['sh', '-c', "myserver &lt;/dev/null &gt;/dev/null"])</B>
 
		The returned <A HREF="#Job">Job</A> object can be used to get the status with
		|<A HREF="#job_status()">job_status()</A>| and stop the job with |<A HREF="#job_stop()">job_stop()</A>|.

		{options} must be a <A HREF="#Dictionary">Dictionary</A>.  It can contain many optional
		items, see |<A HREF="channel.html#job-options">job-options</A>|.

		{only available when compiled with the |<A HREF="various.html#+job">+job</A>| feature}


job_status({job})					*<A NAME="job_status()"></A><B>job_status()</B>* *<A NAME="E916"></A><B>E916</B>*
		Returns a <A HREF="#String">String</A> with the status of {job}:
			&quot;run&quot;	<A HREF="channel.html#job">job</A> is running
			&quot;fail&quot;	<A HREF="channel.html#job">job</A> failed to start
			&quot;dead&quot;	<A HREF="channel.html#job">job</A> died or was stopped after running
		
		If an exit callback was set with the &quot;exit-cb&quot; option and the
		<A HREF="channel.html#job">job</A> is now detected to be &quot;dead&quot; the callback will be invoked.

		For more information see |<A HREF="#job_info()">job_info()</A>|.

		{only available when compiled with the |<A HREF="various.html#+job">+job</A>| feature}


job_stop({job} [, {how}])					*<A NAME="job_stop()"></A><B>job_stop()</B>*
		Stop the {job}.  This can also be used to signal the <A HREF="channel.html#job">job</A>.

		When {how} is omitted or is &quot;term&quot; the <A HREF="channel.html#job">job</A> will be terminated.
		For <A HREF="os_unix.html#Unix">Unix</A> SIGTERM is sent.  On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> the <A HREF="channel.html#job">job</A> will be
		terminated forcedly (there is no &quot;gentle&quot; way).
		This goes to the process group, thus children may also be
		affected.

		Effect for <A HREF="os_unix.html#Unix">Unix</A>:
			&quot;term&quot;	 SIGTERM (default)
			&quot;hup&quot;	 SIGHUP
			&quot;quit&quot;	 SIGQUIT
			&quot;int&quot;	 SIGINT
			&quot;kill&quot;	 SIGKILL (strongest way to stop)
			number	 signal with that number

		Effect for <A HREF="os_win32.html#MS-Windows">MS-Windows</A>:
			&quot;term&quot;	 terminate process forcedly (default)
			&quot;hup&quot;	 CTRL_BREAK
			&quot;quit&quot;	 CTRL_BREAK
			&quot;int&quot;	 CTRL_C
			&quot;kill&quot;	 terminate process forcedly
			Others	 CTRL_BREAK

		On <A HREF="os_unix.html#Unix">Unix</A> the signal is sent to the process group.  This means
		that when the <A HREF="channel.html#job">job</A> is &quot;sh <A HREF="starting.html#-c">-c</A> command&quot; <A HREF="motion.html#it">it</A> affects both the shell
		and the command.

		The result is a <A HREF="#Number">Number</A>: 1 if the operation could be executed,
		0 if &quot;how&quot; is not supported on the system.
		Note that even when the operation was executed, whether the
		<A HREF="channel.html#job">job</A> was actually stopped needs to be checked with
		<A HREF="#job_status()">job_status()</A>.
		The status of the <A HREF="channel.html#job">job</A> isn't checked, the operation will even
		be done when Vim thinks the <A HREF="channel.html#job">job</A> isn't running.

		{only available when compiled with the |<A HREF="various.html#+job">+job</A>| feature}


join({list} [, {sep}])					*<A NAME="join()"></A><B>join()</B>*
		Join the items in {list} together into one <A HREF="#String">String</A>.
		When {sep} is specified <A HREF="motion.html#it">it</A> is put in between the items.  If
		{sep} is omitted a single space is used.
		Note that {sep} is not added at the end.  You might want to
		add <A HREF="motion.html#it">it</A> there too:
<B>			let lines = join(mylist, "\n") . "\n"</B>
 		<A HREF="#String">String</A> items are used as-is.  |<A HREF="#Lists">Lists</A>| and |<A HREF="#Dictionaries">Dictionaries</A>| are
		converted into a string like with |<A HREF="#string()">string()</A>|.
		The opposite function is |<A HREF="#split()">split()</A>|.


js_decode({string})					*<A NAME="js_decode()"></A><B>js_decode()</B>*
		This is similar to |<A HREF="#json_decode()">json_decode()</A>| with these differences:
		- Object key names <A HREF="diff.html#do">do</A> not have to be in <A HREF="quotes.html#quotes">quotes</A>.
		- Empty items in an array (between two commas) are allowed and
		  result in <A HREF="#v:none">v:none</A> items.


js_encode({expr})					*<A NAME="js_encode()"></A><B>js_encode()</B>*
		This is similar to |<A HREF="#json_encode()">json_encode()</A>| with these differences:
		- Object key names are not in <A HREF="quotes.html#quotes">quotes</A>.
		- <A HREF="#v:none">v:none</A> items in an array result in an empty item between
		  commas.
		For example, the Vim object:
<B><FONT COLOR="PURPLE">			[1,v:none,{"one":1},v:none] </FONT></B>
		Will be encoded <A HREF="motion.html#as">as</A>:
<B><FONT COLOR="PURPLE">			[1,,{one:1},,] </FONT></B>
		While <A HREF="#json_encode()">json_encode()</A> would produce:
<B><FONT COLOR="PURPLE">			[1,null,{"one":1},null] </FONT></B>
		This encoding is valid for JavaScript. It is more efficient
		than JSON, especially when using an array with optional items.



json_decode({string})					*<A NAME="json_decode()"></A><B>json_decode()</B>*
		This parses a JSON formatted <A HREF="#string">string</A> and returns the equivalent
		in Vim values.  See |<A HREF="#json_encode()">json_encode()</A>| for the relation between
		JSON and Vim values.
		The decoding is permissive:
		- A trailing comma in an array and object is ignored.
		- More floating point numbers are recognized, e.g. &quot;1.&quot; for
		  &quot;1.0&quot;.
		The result must be a valid Vim type:
		- An empty object member name is not allowed.
		- Duplicate object member names are not allowed.


json_encode({expr})					*<A NAME="json_encode()"></A><B>json_encode()</B>*
		Encode {expr} <A HREF="motion.html#as">as</A> JSON and return this <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A>.
		The encoding is specified in:
		https://tools.ietf.org/html/rfc7159.html
		Vim values are converted <A HREF="motion.html#as">as</A> follows:
		   <A HREF="#Number">Number</A>		decimal number
		   <A HREF="#Float">Float</A>		floating point number
		   <A HREF="#Float">Float</A> nan		&quot;NaN&quot;
		   <A HREF="#Float">Float</A> inf		&quot;Infinity&quot;
		   <A HREF="#String">String</A>		in double <A HREF="quotes.html#quotes">quotes</A> (possibly null)
		   <A HREF="#Funcref">Funcref</A>		not possible, error
		   <A HREF="#List">List</A>			<A HREF="motion.html#as">as</A> an array (possibly null); when
		   			used recursively: <A HREF="motion.html#[]">[]</A>
		   Dict			<A HREF="motion.html#as">as</A> an object (possibly null); when
		   			used recursively: <A HREF="intro.html#{}">{}</A>
		   <A HREF="#v:false">v:false</A>		&quot;false&quot;
		   <A HREF="#v:true">v:true</A>		&quot;true&quot;
		   <A HREF="#v:none">v:none</A>		&quot;null&quot;
		   <A HREF="#v:null">v:null</A>		&quot;null&quot;
		Note that NaN and Infinity are passed on <A HREF="motion.html#as">as</A> values.  This is
		missing in the JSON standard, but several implementations <A HREF="diff.html#do">do</A>
		allow <A HREF="motion.html#it">it</A>.  If not then you will get an error.


keys({dict})						*<A NAME="keys()"></A><B>keys()</B>*
		Return a |<A HREF="#List">List</A>| with all the keys of {dict}.  The |<A HREF="#List">List</A>| is in
		arbitrary order.


							*<A NAME="len()"></A><B>len()</B>* *<A NAME="E701"></A><B>E701</B>*
len({expr})	The result is a <A HREF="#Number">Number</A>, which is the length of the argument.
		When {expr} is a <A HREF="#String">String</A> or a <A HREF="#Number">Number</A> the length in bytes is
		used, <A HREF="motion.html#as">as</A> with |<A HREF="#strlen()">strlen()</A>|.
		When {expr} is a |<A HREF="#List">List</A>| the number of items in the |<A HREF="#List">List</A>| is
		returned.
		When {expr} is a |<A HREF="#Dictionary">Dictionary</A>| the number of entries in the
		|<A HREF="#Dictionary">Dictionary</A>| is returned.
		Otherwise an error is given.


						*<A NAME="libcall()"></A><B>libcall()</B>* *<A NAME="E364"></A><B>E364</B>* *<A NAME="E368"></A><B>E368</B>*
libcall({libname}, {funcname}, {argument})
		Call function {funcname} in the run-time library {libname}
		with single argument {argument}.
		This is useful to call <A HREF="#functions">functions</A> in a library that you
		especially made to be used with Vim.  Since only one argument
		is possible, calling standard library <A HREF="#functions">functions</A> is rather
		limited.
		The result is the <A HREF="#String">String</A> returned by the function.  If the
		function returns NULL, this will appear <A HREF="motion.html#as">as</A> an empty <A HREF="#string">string</A> &quot;&quot;
		to Vim.
		If the function returns a number, use <A HREF="#libcallnr()">libcallnr()</A>!
		If {argument} is a number, <A HREF="motion.html#it">it</A> is passed to the function <A HREF="motion.html#as">as</A> an
		int; if {argument} is a <A HREF="#string">string</A>, <A HREF="motion.html#it">it</A> is passed <A HREF="motion.html#as">as</A> a
		null-terminated <A HREF="#string">string</A>.
		This function will fail in |<A HREF="starting.html#restricted-mode">restricted-mode</A>|.

		<A HREF="#libcall()">libcall()</A> allows you to write your own 'plug-in' extensions to
		Vim without having to recompile the program.  It is NOT a
		means to call system <A HREF="#functions">functions</A>!  If you try to <A HREF="diff.html#do">do</A> so Vim will
		very probably crash.

		For <A HREF="os_win32.html#Win32">Win32</A>, the <A HREF="#functions">functions</A> you write must be placed in a DLL
		and use the normal C calling convention (NOT Pascal which is
		used in Windows System DLLs).  The function must take exactly
		one parameter, either a character pointer or a long integer,
		and must return a character pointer or NULL.  The character
		pointer returned must point to memory that will remain valid
		after the function has returned (e.g. in static data in the
		DLL).  If <A HREF="motion.html#it">it</A> points to allocated memory, that memory will
		leak away.  Using a static buffer in the function should work,
		it's then freed when the DLL is unloaded.

		WARNING: If the function returns a non-valid pointer, Vim may
		crash!	This also happens if the function returns a number,
		because Vim thinks it's a pointer.
		For <A HREF="os_win32.html#Win32">Win32</A> systems, {libname} should be the filename of the DLL
		without the &quot;.DLL&quot; suffix.  A full path is only required if
		the DLL is not in the usual places.
		For <A HREF="os_unix.html#Unix">Unix</A>: When compiling your own plugins, remember that the
		object code must be compiled <A HREF="motion.html#as">as</A> position-independent ('PIC').
		{only in <A HREF="os_win32.html#Win32">Win32</A> and some <A HREF="os_unix.html#Unix">Unix</A> versions, when the |<A HREF="various.html#+libcall">+libcall</A>|
		feature is present}
		Examples:
<B>			:echo libcall("libc.so", "getenv", "HOME")</B>
 

							*<A NAME="libcallnr()"></A><B>libcallnr()</B>*
libcallnr({libname}, {funcname}, {argument})
		Just like |<A HREF="#libcall()">libcall()</A>|, but used for a function that returns an
		int instead of a <A HREF="#string">string</A>.
		{only in <A HREF="os_win32.html#Win32">Win32</A> on some <A HREF="os_unix.html#Unix">Unix</A> versions, when the |<A HREF="various.html#+libcall">+libcall</A>|
		feature is present}
		Examples:
<B>			:echo libcallnr("/usr/lib/libc.so", "getpid", "")</B>
<B>			:call libcallnr("libc.so", "printf", "Hello World!\n")</B>
<B>			:call libcallnr("libc.so", "sleep", 10)</B>
 

							*<A NAME="line()"></A><B>line()</B>*
line({expr})	The result is a <A HREF="#Number">Number</A>, which is the line number of the file
		position given with {expr}.  The accepted positions are:
		    .	    the cursor position
		    $	    the last line in the current buffer
		    'x	    position of <A HREF="motion.html#mark">mark</A> <A HREF="change.html#x">x</A> (if the <A HREF="motion.html#mark">mark</A> is not set, 0 is
			    returned)
		    w0	    first line visible in current <A HREF="windows.html#window">window</A>
		    w$	    last line visible in current <A HREF="windows.html#window">window</A>
		    <A HREF="visual.html#v">v</A>	    In <A HREF="visual.html#Visual">Visual</A> mode: the start of the <A HREF="visual.html#Visual">Visual</A> area (the
			    cursor is the end).  When not in <A HREF="visual.html#Visual">Visual</A> mode
			    returns the cursor position.  Differs from |<A HREF="motion.html#'&lt;">'&lt;</A>| in
			    that it's updated right away.
		Note that a <A HREF="motion.html#mark">mark</A> in another file can be used.  The line number
		then applies to another buffer.
		To get the column number use |<A HREF="#col()">col()</A>|.  To get both use
		|<A HREF="#getpos()">getpos()</A>|.
		Examples:
<B>			line(".")		line number of the cursor</B>
<B>			line("'t")		line number of mark t</B>
<B>			line("'" . marker)	line number of mark marker</B>

 							*<A NAME="last-position-jump"></A><B>last-position-jump</B>*
		This <A HREF="autocmd.html#autocommand">autocommand</A> jumps to the last known position in a file
		just after opening <A HREF="motion.html#it">it</A>, if the &#39;&#34;' <A HREF="motion.html#mark">mark</A> is set:
<B>	:au BufReadPost * if line("'\"") &gt; 1 &amp;&amp; line("'\"") &lt;= line("$") | exe "normal! g`\"" | endif</B>


line2byte({lnum})					*<A NAME="line2byte()"></A><B>line2byte()</B>*
		Return the byte <A HREF="intro.html#count">count</A> from the start of the buffer for line
		{lnum}.  This includes the end-of-line character, depending on
		the <A HREF="options.html#'fileformat'">'fileformat'</A> option for the current buffer.  The first
		line returns 1. <A HREF="options.html#'encoding'">'encoding'</A> matters, <A HREF="options.html#'fileencoding'">'fileencoding'</A> is ignored.
		This can also be used to get the byte <A HREF="intro.html#count">count</A> for the line just
		below the last line:
<B>			line2byte(line("$") + 1)</B>
 		This is the buffer size plus one.  If <A HREF="options.html#'fileencoding'">'fileencoding'</A> is empty
		<A HREF="motion.html#it">it</A> is the file size plus one.
		When {lnum} is invalid, or the |<A HREF="various.html#+byte_offset">+byte_offset</A>| feature has been
		disabled at compile time, -1 is returned.
		Also see |<A HREF="#byte2line()">byte2line()</A>|, |<A HREF="motion.html#go">go</A>| and |<A HREF="motion.html#:goto">:goto</A>|.


lispindent({lnum})					*<A NAME="lispindent()"></A><B>lispindent()</B>*
		Get the amount of indent for line {lnum} according the lisp
		indenting rules, <A HREF="motion.html#as">as</A> with <A HREF="options.html#'lisp'">'lisp'</A>.
		The indent is counted in spaces, the value of <A HREF="options.html#'tabstop'">'tabstop'</A> is
		relevant.  {lnum} is used just like in |<A HREF="#getline()">getline()</A>|.
		When {lnum} is invalid or Vim was not compiled the
		|<A HREF="various.html#+lispindent">+lispindent</A>| feature, -1 is returned.


<A HREF="#localtime()">localtime()</A>						*<A NAME="localtime()"></A><B>localtime()</B>*
		Return the current time, measured <A HREF="motion.html#as">as</A> seconds since 1st Jan
		1970.  See also |<A HREF="#strftime()">strftime()</A>| and |<A HREF="#getftime()">getftime()</A>|.



log({expr})						*<A NAME="log()"></A><B>log()</B>*
		Return the natural logarithm (base <A HREF="motion.html#e">e</A>) of {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>| in the range
		(0, inf].
		Examples:
<B>			:echo log(10)</B>
 			2.302585
<B>			:echo log(exp(5))</B>
 			5.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



log10({expr})						*<A NAME="log10()"></A><B>log10()</B>*
		Return the logarithm of Float {expr} to base 10 <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo log10(1000)</B>
 			3.0
<B>			:echo log10(0.01)</B>
 			-2.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		

luaeval({expr}[, {expr}])					*<A NAME="luaeval()"></A><B>luaeval()</B>*
		Evaluate <A HREF="if_lua.html#Lua">Lua</A> <A HREF="#expression">expression</A> {expr} and return its result converted 
		to Vim data structures. Second {expr} may hold additional 
		argument accessible <A HREF="motion.html#as">as</A> _A inside first {expr}.
		Strings are returned <A HREF="motion.html#as">as</A> they are.
		Boolean <A HREF="index.html#objects">objects</A> are converted to numbers.
		Numbers are converted to |<A HREF="#Float">Float</A>| values if vim was compiled 
		with |<A HREF="various.html#+float">+float</A>| and to numbers otherwise.
		<A HREF="#Dictionaries">Dictionaries</A> and lists obtained by vim.eval() are returned 
		as-is.
		Other <A HREF="index.html#objects">objects</A> are returned <A HREF="motion.html#as">as</A> zero without any <A HREF="message.html#errors">errors</A>.
		See |<A HREF="if_lua.html#lua-luaeval">lua-luaeval</A>| for more details.
		{only available when compiled with the |<A HREF="various.html#+lua">+lua</A>| feature}


map({expr}, {string})					*<A NAME="map()"></A><B>map()</B>*
		{expr} must be a |<A HREF="#List">List</A>| or a |<A HREF="#Dictionary">Dictionary</A>|.
		<A HREF="insert.html#Replace">Replace</A> each item in {expr} with the result of evaluating
		{string}.
		Inside {string} |<A HREF="#v:val">v:val</A>| has the value of the current item.
		For a |<A HREF="#Dictionary">Dictionary</A>| |<A HREF="#v:key">v:key</A>| has the key of the current item
		and for a |<A HREF="#List">List</A>| |<A HREF="#v:key">v:key</A>| has the index of the current item.
		Example:
<B>			:call map(mylist, '"&gt; " . v:val . " &lt;"')</B>
 		This puts &quot;<A HREF="change.html#&gt;">&gt;</A> &quot; before and &quot; &lt;&quot; after each item in &quot;mylist&quot;.

		Note that {string} is the result of an <A HREF="#expression">expression</A> and is then
		used <A HREF="motion.html#as">as</A> an <A HREF="#expression">expression</A> again.  Often <A HREF="motion.html#it">it</A> is good to use a
		|<A HREF="#literal-string">literal-string</A>| to avoid having to double backslashes.  You
		still have to double '' <A HREF="quotes.html#quotes">quotes</A>

		The operation is done in-place.  If you want a |<A HREF="#List">List</A>| or
		|<A HREF="#Dictionary">Dictionary</A>| to remain unmodified make a copy first:
<B>			:let tlist = map(copy(mylist), ' v:val . "\t"')</B>

 		Returns {expr}, the |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| that was filtered.
		When an error is encountered while evaluating {string} no
		further items in {expr} are processed.



maparg({name}[, {mode} [, {abbr} [, {dict}]]])			*<A NAME="maparg()"></A><B>maparg()</B>*
		When {dict} is omitted or zero: Return the rhs of <A HREF="map.html#mapping">mapping</A>
		{name} in mode {mode}.  The returned <A HREF="#String">String</A> has special
		characters translated like in the output of the &quot;<A HREF="map.html#:map">:map</A>&quot; command
		listing.
		
		When there is no <A HREF="map.html#mapping">mapping</A> for {name}, an empty <A HREF="#String">String</A> is
		returned.

		The {name} can have special key names, like in the &quot;<A HREF="map.html#:map">:map</A>&quot;
		command.

		{mode} can be one of these strings:
			&quot;<A HREF="pattern.html#n">n</A>&quot;	<A HREF="intro.html#Normal">Normal</A>
			&quot;<A HREF="visual.html#v">v</A>&quot;	<A HREF="visual.html#Visual">Visual</A> (including <A HREF="visual.html#Select">Select</A>)
			&quot;<A HREF="insert.html#o">o</A>&quot;	<A HREF="intro.html#Operator-pending">Operator-pending</A>
			&quot;<A HREF="insert.html#i">i</A>&quot;	<A HREF="insert.html#Insert">Insert</A>
			&quot;<A HREF="change.html#c">c</A>&quot;	Cmd-line
			&quot;<A HREF="change.html#s">s</A>&quot;	<A HREF="visual.html#Select">Select</A>
			&quot;<A HREF="change.html#x">x</A>&quot;	<A HREF="visual.html#Visual">Visual</A>
			&quot;l&quot;	langmap |<A HREF="map.html#language-mapping">language-mapping</A>|
			&quot;&quot;	<A HREF="intro.html#Normal">Normal</A>, <A HREF="visual.html#Visual">Visual</A> and <A HREF="intro.html#Operator-pending">Operator-pending</A>
		When {mode} is omitted, the modes for &quot;&quot; are used.

		When {abbr} is there and <A HREF="motion.html#it">it</A> is non-zero use <A HREF="map.html#abbreviations">abbreviations</A>
		instead of mappings.

		When {dict} is there and <A HREF="motion.html#it">it</A> is non-zero return a dictionary
		containing all the information of the <A HREF="map.html#mapping">mapping</A> with the
		following items:
		  &quot;lhs&quot;	     The <A HREF="map.html#{lhs}">{lhs}</A> of the <A HREF="map.html#mapping">mapping</A>.
		  &quot;rhs&quot;	     The <A HREF="map.html#{rhs}">{rhs}</A> of the <A HREF="map.html#mapping">mapping</A> <A HREF="motion.html#as">as</A> typed.
		  &quot;silent&quot;   1 for a |<A HREF="map.html#:map-silent">:map-silent</A>| <A HREF="map.html#mapping">mapping</A>, else 0.
		  &quot;noremap&quot;  1 if the <A HREF="map.html#{rhs}">{rhs}</A> of the <A HREF="map.html#mapping">mapping</A> is not remappable.
		  &quot;expr&quot;     1 for an <A HREF="#expression">expression</A> <A HREF="map.html#mapping">mapping</A> (|<A HREF="map.html#:map-&lt;expr&gt;">:map-&lt;expr&gt;</A>|).
		  &quot;buffer&quot;   1 for a buffer local <A HREF="map.html#mapping">mapping</A> (|<A HREF="map.html#:map-local">:map-local</A>|).
		  &quot;mode&quot;     Modes for which the <A HREF="map.html#mapping">mapping</A> is defined. In
			     addition to the modes mentioned above, these
			     characters will be used:
			     &quot; &quot;     <A HREF="intro.html#Normal">Normal</A>, <A HREF="visual.html#Visual">Visual</A> and <A HREF="intro.html#Operator-pending">Operator-pending</A>
			     &quot;<A HREF="change.html#!">!</A>&quot;     <A HREF="insert.html#Insert">Insert</A> and Commandline mode
				     (|<A HREF="map.html#mapmode-ic">mapmode-ic</A>|)
		  &quot;sid&quot;	     The <A HREF="usr_41.html#script">script</A> local ID, used for &lt;sid&gt; mappings
			     (|<A HREF="map.html#&lt;SID&gt;">&lt;SID&gt;</A>|).
		  &quot;nowait&quot;   Do not wait for other, longer mappings.
			     (|<A HREF="map.html#:map-&lt;nowait&gt;">:map-&lt;nowait&gt;</A>|).

		The mappings local to the current buffer are checked first,
		then the global mappings.
		This function can be used to map a key even when it's already
		mapped, and have <A HREF="motion.html#it">it</A> <A HREF="diff.html#do">do</A> the original <A HREF="map.html#mapping">mapping</A> too.  Sketch:
<B>			exe 'nnoremap &lt;Tab&gt; ==' . maparg('&lt;Tab&gt;', 'n')</B>



mapcheck({name}[, {mode} [, {abbr}]])			*<A NAME="mapcheck()"></A><B>mapcheck()</B>*
		Check if there is a <A HREF="map.html#mapping">mapping</A> that matches with {name} in mode
		{mode}.  See |<A HREF="#maparg()">maparg()</A>| for {mode} and special names in
		{name}.
		When {abbr} is there and <A HREF="motion.html#it">it</A> is non-zero use <A HREF="map.html#abbreviations">abbreviations</A>
		instead of mappings.
		A match happens with a <A HREF="map.html#mapping">mapping</A> that starts with {name} and
		with a <A HREF="map.html#mapping">mapping</A> which is equal to the start of {name}.

<B><FONT COLOR="PURPLE">			matches mapping "a"	"ab"	"abc" </FONT></B>
		   mapcheck(&quot;a&quot;)	yes	yes	 yes
		   mapcheck(&quot;abc&quot;)	yes	yes	 yes
		   mapcheck(&quot;ax&quot;)	yes	no	 no
		   mapcheck(&quot;b&quot;)	no	no	 no

		The difference with <A HREF="#maparg()">maparg()</A> is that <A HREF="#mapcheck()">mapcheck()</A> finds a
		<A HREF="map.html#mapping">mapping</A> that matches with {name}, while <A HREF="#maparg()">maparg()</A> only finds a
		<A HREF="map.html#mapping">mapping</A> for {name} exactly.
		When there is no <A HREF="map.html#mapping">mapping</A> that starts with {name}, an empty
		<A HREF="#String">String</A> is returned.  If there is one, the rhs of that <A HREF="map.html#mapping">mapping</A>
		is returned.  If there are several mappings that start with
		{name}, the rhs of one of them is returned.
		The mappings local to the current buffer are checked first,
		then the global mappings.
		This function can be used to check if a <A HREF="map.html#mapping">mapping</A> can be added
		without being ambiguous.  Example:
<B>	:if mapcheck("_vv") == ""</B>
<B>	:   map _vv :set guifont=7x13&lt;CR&gt;</B>
<B>	:endif</B>
 		This avoids adding the &quot;_vv&quot; <A HREF="map.html#mapping">mapping</A> when there already is a
		<A HREF="map.html#mapping">mapping</A> for &quot;_v&quot; or for &quot;_vvv&quot;.


match({expr}, {pat}[, {start}[, {count}]])			*<A NAME="match()"></A><B>match()</B>*
		When {expr} is a |<A HREF="#List">List</A>| then this returns the index of the
		first item where <A HREF="autocmd.html#{pat}">{pat}</A> matches.  Each item is used <A HREF="motion.html#as">as</A> a
		<A HREF="#String">String</A>, |<A HREF="#Lists">Lists</A>| and |<A HREF="#Dictionaries">Dictionaries</A>| are used <A HREF="motion.html#as">as</A> echoed.
		Otherwise, {expr} is used <A HREF="motion.html#as">as</A> a <A HREF="#String">String</A>.	The result is a
		<A HREF="#Number">Number</A>, which gives the index (byte offset) in {expr} where
		<A HREF="autocmd.html#{pat}">{pat}</A> matches.
		A match at the first character or |<A HREF="#List">List</A>| item returns zero.
		If there is no match -1 is returned.
		For getting submatches see |<A HREF="#matchlist()">matchlist()</A>|.
		Example:
<B>			:echo match("testing", "ing")	" results in 4</B>
<B>			:echo match([1, 'x'], '\a')	" results in 1</B>
 		See |<A HREF="#string-match">string-match</A>| for how <A HREF="autocmd.html#{pat}">{pat}</A> is used.

								*<A NAME="strpbrk()"></A><B>strpbrk()</B>*
		Vim doesn't have a <A HREF="#strpbrk()">strpbrk()</A> function.	But you can <A HREF="diff.html#do">do</A>:
<B>			:let sepidx = match(line, '[.,;: \t]')</B>

 								*<A NAME="strcasestr()"></A><B>strcasestr()</B>*
		Vim doesn't have a <A HREF="#strcasestr()">strcasestr()</A> function.  But you can add
		&quot;\c&quot; to the <A HREF="pattern.html#pattern">pattern</A> to ignore <A HREF="change.html#case">case</A>:
<B>			:let idx = match(haystack, '\cneedle')</B>
 
		If {start} is given, the search starts from byte index
		{start} in a <A HREF="#String">String</A> or item {start} in a |<A HREF="#List">List</A>|.
		The result, however, is still the index counted from the
		first character/item.  Example:
<B>			:echo match("testing", "ing", 2)</B>
 		result is again &quot;4&quot;.
<B>			:echo match("testing", "ing", 4)</B>
 		result is again &quot;4&quot;.
<B>			:echo match("testing", "t", 2)</B>
 		result is &quot;3&quot;.
		For a <A HREF="#String">String</A>, if {start} <A HREF="change.html#&gt;">&gt;</A> 0 then <A HREF="motion.html#it">it</A> is like the <A HREF="#string">string</A> starts
		{start} bytes later, thus &quot;<A HREF="motion.html#^">^</A>&quot; will match at {start}.  Except
		when {count} is given, then it's like matches before the
		{start} byte are ignored (this is a bit complicated to keep <A HREF="motion.html#it">it</A>
		backwards compatible).
		For a <A HREF="#String">String</A>, if {start} <A HREF="change.html#&lt;">&lt;</A> 0, <A HREF="motion.html#it">it</A> will be set to 0.  For a <A HREF="#list">list</A>
		the index is counted from the end.
		If {start} is out of range ({start} <A HREF="change.html#&gt;">&gt;</A> strlen({expr}) for a
		<A HREF="#String">String</A> or {start} <A HREF="change.html#&gt;">&gt;</A> len({expr}) for a |<A HREF="#List">List</A>|) -1 is returned.

		When {count} is given use the {count}'th match.  When a match
		is found in a <A HREF="#String">String</A> the search for the next one starts one
		character further.  Thus this example results in 1:
<B>			echo match("testing", "..", 0, 2)</B>
 		In a |<A HREF="#List">List</A>| the search continues in the next item.
		Note that when {count} is added the way {start} works changes,
		see above.

		See |<A HREF="pattern.html#pattern">pattern</A>| for the patterns that are accepted.
		The <A HREF="options.html#'ignorecase'">'ignorecase'</A> option is used to set the ignore-caseness of
		the <A HREF="pattern.html#pattern">pattern</A>.  <A HREF="options.html#'smartcase'">'smartcase'</A> is NOT used.	The matching is always
		done like <A HREF="options.html#'magic'">'magic'</A> is set and <A HREF="options.html#'cpoptions'">'cpoptions'</A> is empty.


					*<A NAME="matchadd()"></A><B>matchadd()</B>* *<A NAME="E798"></A><B>E798</B>* *<A NAME="E799"></A><B>E799</B>* *<A NAME="E801"></A><B>E801</B>*
matchadd({group}, {pattern}[, {priority}[, {id}[, {dict}]]])
		Defines a <A HREF="pattern.html#pattern">pattern</A> to be highlighted in the current <A HREF="windows.html#window">window</A> (a
		&quot;match&quot;).  It will be highlighted with {group}.  Returns an
		identification number (ID), which can be used to delete the
		match using |<A HREF="#matchdelete()">matchdelete()</A>|.
		Matching is <A HREF="change.html#case">case</A> sensitive and magic, unless <A HREF="change.html#case">case</A> sensitivity
		or magicness are explicitly overridden in {pattern}.  The
		<A HREF="options.html#'magic'">'magic'</A>, <A HREF="options.html#'smartcase'">'smartcase'</A> and <A HREF="options.html#'ignorecase'">'ignorecase'</A> <A HREF="options.html#options">options</A> are not used.
		The &quot;Conceal&quot; value is special, <A HREF="motion.html#it">it</A> 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 <A HREF="motion.html#as">as</A> an integer (negative numbers are no
		exception).  If the {priority} argument is not specified, the
		default priority is 10.  The priority of <A HREF="options.html#'hlsearch'">'hlsearch'</A> is zero,
		hence all matches with a priority greater than zero will
		overrule <A HREF="motion.html#it">it</A>.  <A HREF="autocmd.html#Syntax">Syntax</A> highlighting (see <A HREF="options.html#'syntax'">'syntax'</A>) is a separate
		mechanism, and regardless of the chosen priority a match will
		always overrule <A HREF="syntax.html#syntax">syntax</A> 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 <A HREF="motion.html#as">as</A> a positive integer (zero excluded).  IDs 1, 2
		and 3 are reserved for |<A HREF="pattern.html#:match">:match</A>|, |<A HREF="pattern.html#:2match">:2match</A>| and |<A HREF="pattern.html#:3match">:3match</A>|,
		respectively.  If the {id} argument is not specified or -1,
		|<A HREF="#matchadd()">matchadd()</A>| automatically chooses a free ID.

		The optional {dict} argument allows for further custom
		values. Currently this is used to specify a match specific
		<A HREF="syntax.html#conceal">conceal</A> character that will be shown for |<A HREF="syntax.html#hl-Conceal">hl-Conceal</A>|
		highlighted matches. The <A HREF="#dict">dict</A> can have the following members:

			<A HREF="syntax.html#conceal">conceal</A>	    <A HREF="#Special">Special</A> character to show instead of the
				    match (only for |<A HREF="syntax.html#hl-Conceal">hl-Conceal</A>| highlighted
				    matches, see |<A HREF="syntax.html#:syn-cchar">:syn-cchar</A>|)

		The number of matches is not limited, <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> is the <A HREF="change.html#case">case</A> with
		the |<A HREF="pattern.html#:match">:match</A>| commands.

		Example:
<B>			:highlight MyGroup ctermbg=green guibg=green</B>
<B>			:let m = matchadd("MyGroup", "TODO")</B>
 		Deletion of the <A HREF="pattern.html#pattern">pattern</A>:
<B>			:call matchdelete(m)</B>

 		A <A HREF="#list">list</A> of matches defined by |<A HREF="#matchadd()">matchadd()</A>| and |<A HREF="pattern.html#:match">:match</A>| are
		available from |<A HREF="#getmatches()">getmatches()</A>|.	All matches can be deleted in
		one operation by |<A HREF="#clearmatches()">clearmatches()</A>|.


matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]])		*<A NAME="matchaddpos()"></A><B>matchaddpos()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#matchadd()">matchadd()</A>|, but requires a <A HREF="#list">list</A> of positions {pos}
		instead of a <A HREF="pattern.html#pattern">pattern</A>. This command is faster than |<A HREF="#matchadd()">matchadd()</A>|
		because <A HREF="motion.html#it">it</A> does not require to handle regular expressions and
		sets buffer line boundaries to redraw screen. It is supposed
		to be used when fast match additions and deletions are
		required, for example to highlight matching parentheses.

		The <A HREF="#list">list</A> {pos} can contain one of these items:
		- A number.  This whole line will be highlighted.  The first
		  line has number 1.
		- A <A HREF="#list">list</A> with one number, e.g., [23]. The whole line with this
		  number will be highlighted.
		- A <A HREF="#list">list</A> with two numbers, e.g., [23, 11]. The first number is
		  the line number, the second one is the column number (first
		  column is 1, the value must correspond to the byte index <A HREF="motion.html#as">as</A>
		  |<A HREF="#col()">col()</A>| would return).  The character at this position will
		  be highlighted.
		- A <A HREF="#list">list</A> with three numbers, e.g., [23, 11, 3]. As above, but
		  the third number gives the length of the highlight in bytes.
		
		The maximum number of positions is 8.

		Example:
<B>			:highlight MyGroup ctermbg=green guibg=green</B>
<B>			:let m = matchaddpos("MyGroup", [[23, 24], 34])</B>
 		Deletion of the <A HREF="pattern.html#pattern">pattern</A>:
<B>			:call matchdelete(m)</B>

 		Matches added by |<A HREF="#matchaddpos()">matchaddpos()</A>| are returned by
		|<A HREF="#getmatches()">getmatches()</A>| with an entry &quot;pos1&quot;, &quot;pos2&quot;, etc., with the
		value a <A HREF="#list">list</A> like the {pos} item.
		These matches cannot be set via |<A HREF="#setmatches()">setmatches()</A>|, however they
		can still be deleted by |<A HREF="#clearmatches()">clearmatches()</A>|.


matcharg({nr})							*<A NAME="matcharg()"></A><B>matcharg()</B>*
		Selects the {nr} match item, <A HREF="motion.html#as">as</A> set with a |<A HREF="pattern.html#:match">:match</A>|,
		|<A HREF="pattern.html#:2match">:2match</A>| or |<A HREF="pattern.html#:3match">:3match</A>| command.
		Return a |<A HREF="#List">List</A>| with two elements:
			The name of the highlight group used
			The <A HREF="pattern.html#pattern">pattern</A> used.
		When {nr} is not 1, 2 or 3 returns an empty |<A HREF="#List">List</A>|.
		When there is no match item set returns ['', ''].
		This is useful to save and restore a |<A HREF="pattern.html#:match">:match</A>|.
		Highlighting matches using the |<A HREF="pattern.html#:match">:match</A>| commands are limited
		to three matches. |<A HREF="#matchadd()">matchadd()</A>| does not have this limitation.


matchdelete({id})			       *<A NAME="matchdelete()"></A><B>matchdelete()</B>* *<A NAME="E802"></A><B>E802</B>* *<A NAME="E803"></A><B>E803</B>*
		Deletes a match with ID {id} previously defined by |<A HREF="#matchadd()">matchadd()</A>|
		or one of the |<A HREF="pattern.html#:match">:match</A>| commands.  Returns 0 if successful,
		otherwise -1.  See example for |<A HREF="#matchadd()">matchadd()</A>|.  All matches can
		be deleted in one operation by |<A HREF="#clearmatches()">clearmatches()</A>|.


matchend({expr}, {pat}[, {start}[, {count}]])			*<A NAME="matchend()"></A><B>matchend()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#match()">match()</A>|, but return the index of first character
		after the match.  Example:
<B>			:echo matchend("testing", "ing")</B>
 		results in &quot;7&quot;.

							*<A NAME="strspn()"></A><B>strspn()</B>* *<A NAME="strcspn()"></A><B>strcspn()</B>*
		Vim doesn't have a <A HREF="#strspn()">strspn()</A> or <A HREF="#strcspn()">strcspn()</A> function, but you can
		<A HREF="diff.html#do">do</A> <A HREF="motion.html#it">it</A> with <A HREF="#matchend()">matchend()</A>:
<B>			:let span = matchend(line, '[a-zA-Z]')</B>
<B>			:let span = matchend(line, '[^a-zA-Z]')</B>
 		Except that -1 is returned when there are no matches.

		The {start}, if given, has the same meaning <A HREF="motion.html#as">as</A> for |<A HREF="#match()">match()</A>|.
<B>			:echo matchend("testing", "ing", 2)</B>
 		results in &quot;7&quot;.
<B>			:echo matchend("testing", "ing", 5)</B>
 		result is &quot;-1&quot;.
		When {expr} is a |<A HREF="#List">List</A>| the result is equal to |<A HREF="#match()">match()</A>|.


matchlist({expr}, {pat}[, {start}[, {count}]])			*<A NAME="matchlist()"></A><B>matchlist()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#match()">match()</A>|, but return a |<A HREF="#List">List</A>|.  The first item in the
		<A HREF="#list">list</A> is the matched <A HREF="#string">string</A>, same <A HREF="motion.html#as">as</A> what <A HREF="#matchstr()">matchstr()</A> would
		return.  Following items are submatches, like &quot;\1&quot;, &quot;\2&quot;, etc.
		in |<A HREF="change.html#:substitute">:substitute</A>|.  When an optional submatch didn't match an
		empty <A HREF="#string">string</A> is used.  Example:
<B>			echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')</B>
 		Results in: ['acd', '<A HREF="insert.html#a">a</A>', <A HREF="motion.html#''">''</A>, '<A HREF="change.html#c">c</A>', '<A HREF="change.html#d">d</A>', <A HREF="motion.html#''">''</A>, <A HREF="motion.html#''">''</A>, <A HREF="motion.html#''">''</A>, <A HREF="motion.html#''">''</A>, '']
		When there is no match an empty <A HREF="#list">list</A> is returned.


matchstr({expr}, {pat}[, {start}[, {count}]])			*<A NAME="matchstr()"></A><B>matchstr()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#match()">match()</A>|, but return the matched <A HREF="#string">string</A>.  Example:
<B>			:echo matchstr("testing", "ing")</B>
 		results in &quot;ing&quot;.
		When there is no match &quot;&quot; is returned.
		The {start}, if given, has the same meaning <A HREF="motion.html#as">as</A> for |<A HREF="#match()">match()</A>|.
<B>			:echo matchstr("testing", "ing", 2)</B>
 		results in &quot;ing&quot;.
<B>			:echo matchstr("testing", "ing", 5)</B>
 		result is &quot;&quot;.
		When {expr} is a |<A HREF="#List">List</A>| then the matching item is returned.
		The type isn't changed, it's not necessarily a <A HREF="#String">String</A>.


matchstrpos({expr}, {pat}[, {start}[, {count}]])		*<A NAME="matchstrpos()"></A><B>matchstrpos()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#matchstr()">matchstr()</A>|, but return the matched <A HREF="#string">string</A>, the start
		position and the end position of the match.  Example:
<B>			:echo matchstrpos("testing", "ing")</B>
 		results in [&quot;ing&quot;, 4, 7].
		When there is no match [&quot;&quot;, -1, -1] is returned.
		The {start}, if given, has the same meaning <A HREF="motion.html#as">as</A> for |<A HREF="#match()">match()</A>|.
<B>			:echo matchstrpos("testing", "ing", 2)</B>
 		results in [&quot;ing&quot;, 4, 7].
<B>			:echo matchstrpos("testing", "ing", 5)</B>
 		result is [&quot;&quot;, -1, -1].
		When {expr} is a |<A HREF="#List">List</A>| then the matching item, the index
		of first item where <A HREF="autocmd.html#{pat}">{pat}</A> matches, the start position and the
		end position of the match are returned.
<B>			:echo matchstrpos([1, '__x'], '\a')</B>
 		result is [&quot;x&quot;, 1, 2, 3].
		The type isn't changed, it's not necessarily a <A HREF="#String">String</A>.


							*<A NAME="max()"></A><B>max()</B>*
max({list})	Return the maximum value of all items in {list}.
		If {list} is not a <A HREF="#list">list</A> or one of the items in {list} cannot
		be used <A HREF="motion.html#as">as</A> a <A HREF="#Number">Number</A> this results in an error.
		An empty |<A HREF="#List">List</A>| results in zero.


							*<A NAME="min()"></A><B>min()</B>*
min({list})	Return the minimum value of all items in {list}.
		If {list} is not a <A HREF="#list">list</A> or one of the items in {list} cannot
		be used <A HREF="motion.html#as">as</A> a <A HREF="#Number">Number</A> this results in an error.
		An empty |<A HREF="#List">List</A>| results in zero.


							*<A NAME="mkdir()"></A><B>mkdir()</B>* *<A NAME="E739"></A><B>E739</B>*
mkdir({name} [, {path} [, {prot}]])
		Create directory {name}.
		If {path} is &quot;<A HREF="change.html#p">p</A>&quot; then intermediate directories are created <A HREF="motion.html#as">as</A>
		necessary.  Otherwise <A HREF="motion.html#it">it</A> must be &quot;&quot;.
		If {prot} is given <A HREF="motion.html#it">it</A> is used to set the protection bits of
		the new directory.  The default is 0755 (rwxr-xr-x: r/w for
		the user readable for others).	Use 0700 to make <A HREF="motion.html#it">it</A> unreadable
		for others.  This is only used for the last part of {name}.
		Thus if you create /tmp/foo/bar then /tmp/foo will be created
		with 0755.
		Example:
<B>			:call mkdir($HOME . "/tmp/foo/bar", "p", 0700)</B>
 		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		Not available on all systems.  To check use:
<B>			:if exists("*mkdir")</B>
 

							*<A NAME="mode()"></A><B>mode()</B>*
mode([expr])	Return a <A HREF="#string">string</A> that indicates the current mode.
		If [expr] is supplied and <A HREF="motion.html#it">it</A> evaluates to a non-zero <A HREF="#Number">Number</A> or
		a non-empty <A HREF="#String">String</A> (|<A HREF="#non-zero-arg">non-zero-arg</A>|), then the full mode is
		returned, otherwise only the first <A HREF="print.html#letter">letter</A> is returned.  Note
		that &quot; &quot; and &quot;<A HREF="motion.html#0">0</A>&quot; are also non-empty strings.

			<A HREF="pattern.html#n">n</A>	<A HREF="intro.html#Normal">Normal</A>
			no	<A HREF="intro.html#Operator-pending">Operator-pending</A>
			<A HREF="visual.html#v">v</A>	<A HREF="visual.html#Visual">Visual</A> by character
			<A HREF="visual.html#V">V</A>	<A HREF="visual.html#Visual">Visual</A> by line
			<A HREF="visual.html#CTRL-V">CTRL-V</A>	<A HREF="visual.html#Visual">Visual</A> blockwise
			<A HREF="change.html#s">s</A>	<A HREF="visual.html#Select">Select</A> by character
			<A HREF="change.html#S">S</A>	<A HREF="visual.html#Select">Select</A> by line
			CTRL-S	<A HREF="visual.html#Select">Select</A> blockwise
			<A HREF="insert.html#i">i</A>	<A HREF="insert.html#Insert">Insert</A>
			R	<A HREF="insert.html#Replace">Replace</A> |<A HREF="change.html#R">R</A>|
			Rv	Virtual <A HREF="insert.html#Replace">Replace</A> |<A HREF="change.html#gR">gR</A>|
			<A HREF="change.html#c">c</A>	<A HREF="cmdline.html#Command-line">Command-line</A>
			cv	Vim <A HREF="intro.html#Ex">Ex</A> mode |<A HREF="intro.html#gQ">gQ</A>|
			ce	<A HREF="intro.html#Normal">Normal</A> <A HREF="intro.html#Ex">Ex</A> mode |<A HREF="intro.html#Q">Q</A>|
			<A HREF="change.html#r">r</A>	Hit-enter prompt
			rm	The <A HREF="starting.html#--">--</A> more <A HREF="starting.html#--">--</A> prompt
			r?	A |<A HREF="editing.html#:confirm">:confirm</A>| query of some sort
			!	Shell or external command is executing
		This is useful in the <A HREF="options.html#'statusline'">'statusline'</A> option or when used
		with |<A HREF="#remote_expr()">remote_expr()</A>| In most other places <A HREF="motion.html#it">it</A> always returns
		&quot;<A HREF="change.html#c">c</A>&quot; or &quot;<A HREF="pattern.html#n">n</A>&quot;.
		Also see |<A HREF="#visualmode()">visualmode()</A>|.


mzeval({expr})							*<A NAME="mzeval()"></A><B>mzeval()</B>*
		Evaluate <A HREF="if_mzsch.html#MzScheme">MzScheme</A> <A HREF="#expression">expression</A> {expr} and return its result
		converted to Vim data structures.
		Numbers and strings are returned <A HREF="motion.html#as">as</A> they are.
		Pairs (including lists and improper lists) and vectors are
		returned <A HREF="motion.html#as">as</A> Vim |<A HREF="#Lists">Lists</A>|.
		Hash tables are represented <A HREF="motion.html#as">as</A> Vim |<A HREF="#Dictionary">Dictionary</A>| type with keys
		converted to strings.
		All other types are converted to <A HREF="#string">string</A> with display function.
		Examples:
<B>		    :mz (define l (list 1 2 3))</B>
<B>		    :mz (define h (make-hash)) (hash-set! h "list" l)</B>
<B>		    :echo mzeval("l")</B>
<B>		    :echo mzeval("h")</B>
 
		{only available when compiled with the |<A HREF="various.html#+mzscheme">+mzscheme</A>| feature}


nextnonblank({lnum})					*<A NAME="nextnonblank()"></A><B>nextnonblank()</B>*
		Return the line number of the first line at or below {lnum}
		that is not blank.  Example:
<B>			if getline(nextnonblank(1)) =~ "Java"</B>
 		When {lnum} is invalid or there is no non-blank line at or
		below <A HREF="motion.html#it">it</A>, zero is returned.
		See also |<A HREF="#prevnonblank()">prevnonblank()</A>|.


nr2char({expr}[, {utf8}])				*<A NAME="nr2char()"></A><B>nr2char()</B>*
		Return a <A HREF="#string">string</A> with a single character, which has the number
		value {expr}.  Examples:
<B>			nr2char(64)		returns "@"</B>
<B>			nr2char(32)		returns " "</B>
 		When {utf8} is omitted or zero, the current <A HREF="options.html#'encoding'">'encoding'</A> is used.
		Example for &quot;<A HREF="mbyte.html#utf-8">utf-8</A>&quot;:
<B>			nr2char(300)		returns I with bow character</B>
 		With {utf8} set to 1, always return <A HREF="mbyte.html#utf-8">utf-8</A> characters.
		Note that a NUL character in the file is specified with
		nr2char(10), because NULs are represented with newline
		characters.  nr2char(0) is a real NUL and terminates the
		<A HREF="#string">string</A>, thus results in an empty <A HREF="#string">string</A>.


or({expr}, {expr})					*<A NAME="or()"></A><B>or()</B>*
		Bitwise OR on the two arguments.  The arguments are converted
		to a number.  A <A HREF="#List">List</A>, Dict or <A HREF="#Float">Float</A> argument causes an error.
		Example:
<B>			:let bits = or(bits, 0x80)</B>



pathshorten({expr})					*<A NAME="pathshorten()"></A><B>pathshorten()</B>*
		Shorten directory names in the path {expr} and return the
		result.  The tail, the file name, is kept as-is.  The other
		components in the path are reduced to single letters.  Leading
		'<A HREF="change.html#~">~</A>' and '<A HREF="repeat.html#.">.</A>' characters are kept.  Example:
<B>			:echo pathshorten('~/.vim/autoload/myfile.vim')</B>
<B><FONT COLOR="PURPLE"> 			~/.v/a/myfile.vim </FONT></B>
		It doesn't matter if the path exists or not.


perleval({expr})					*<A NAME="perleval()"></A><B>perleval()</B>*
		Evaluate <A HREF="if_perl.html#Perl">Perl</A> <A HREF="#expression">expression</A> {expr} in scalar context and return
		its result converted to Vim data structures. If value can't be
		converted, <A HREF="motion.html#it">it</A> is returned <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A> <A HREF="if_perl.html#Perl">Perl</A> representation.
		Note: If you want an array or hash, {expr} must return a
		reference to <A HREF="motion.html#it">it</A>.
		Example:
<B>			:echo perleval('[1 .. 4]')</B>
 			[1, 2, 3, 4]
		{only available when compiled with the |<A HREF="various.html#+perl">+perl</A>| feature}


pow({x}, {y})						*<A NAME="pow()"></A><B>pow()</B>*
		Return the power of {x} to the exponent {y} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{x} and {y} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo pow(3, 3)</B>
 			27.0
<B>			:echo pow(2, 16)</B>
 			65536.0
<B>			:echo pow(32, 0.20)</B>
 			2.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		

prevnonblank({lnum})					*<A NAME="prevnonblank()"></A><B>prevnonblank()</B>*
		Return the line number of the first line at or above {lnum}
		that is not blank.  Example:
<B>			let ind = indent(prevnonblank(v:lnum - 1))</B>
 		When {lnum} is invalid or there is no non-blank line at or
		above <A HREF="motion.html#it">it</A>, zero is returned.
		Also see |<A HREF="#nextnonblank()">nextnonblank()</A>|.



printf({fmt}, {expr1} <A HREF="#...">...</A>)				*<A NAME="printf()"></A><B>printf()</B>*
		Return a <A HREF="#String">String</A> with {fmt}, where &quot;<A HREF="motion.html#&#37;">&#37;</A>&quot; items are replaced by
		the formatted form of their respective arguments.  Example:
<B>			printf("%4d: E%d %.30s", lnum, errno, msg)</B>
 		May result in:
<B><FONT COLOR="PURPLE">			"  99: E42 asdfasdfasdfasdfasdfasdfasdfas" </FONT></B>

		Often used items are:
		  &#37;s	<A HREF="#string">string</A>
		  &#37;6S	<A HREF="#string">string</A> right-aligned in 6 display cells
		  &#37;6s	<A HREF="#string">string</A> right-aligned in 6 bytes
		  &#37;.9s	<A HREF="#string">string</A> truncated to 9 bytes
		  &#37;c	single byte
		  &#37;d	decimal number
		  &#37;5d	decimal number padded with spaces to 5 characters
		  &#37;x	hex number
		  &#37;04x	hex number padded with zeros to at least 4 characters
		  &#37;X	hex number using upper <A HREF="change.html#case">case</A> letters
		  &#37;o	<A HREF="#octal">octal</A> number
		  &#37;f	floating point number in the form 123.456
		  &#37;e	floating point number in the form 1.234e3
		  &#37;E	floating point number in the form 1.234E3
		  &#37;g	floating point number, <A HREF="motion.html#as">as</A> &#37;f or &#37;e depending on value
		  &#37;G	floating point number, <A HREF="motion.html#as">as</A> &#37;f or &#37;E depending on value
		  &#37;&#37;	the <A HREF="motion.html#&#37;">&#37;</A> character itself

		Conversion specifications start with '<A HREF="motion.html#&#37;">&#37;</A>' and end with the
		conversion type.  All other characters are copied unchanged to
		the result.

		The &quot;<A HREF="motion.html#&#37;">&#37;</A>&quot; starts a conversion specification.  The following
		arguments appear in sequence:

			<A HREF="motion.html#&#37;">&#37;</A>  [flags]  [field-width]  [.precision]  type

		flags
			Zero or more of the following flags:

		    #	      The value should be converted to an &quot;alternate
			      form&quot;.  For <A HREF="change.html#c">c</A>, <A HREF="change.html#d">d</A>, and <A HREF="change.html#s">s</A> conversions, this option
			      has no effect.  For <A HREF="insert.html#o">o</A> conversions, the precision
			      of the number is increased to force the first
			      character of the output <A HREF="#string">string</A> to a zero (except
			      if a zero value is printed with an explicit
			      precision of zero).
			      For <A HREF="change.html#x">x</A> and X conversions, a non-zero result has
			      the <A HREF="#string">string</A> &quot;0x&quot; (or &quot;0X&quot; for X conversions)
			      prepended to <A HREF="motion.html#it">it</A>.

		    0 (zero)  Zero padding.  For all conversions the converted
			      value is padded on the left with zeros rather
			      than blanks.  If a precision is given with a
			      numeric conversion (d, <A HREF="insert.html#o">o</A>, <A HREF="change.html#x">x</A>, and X), the 0 flag
			      is ignored.

		    -	      A negative field width flag; the converted value
			      is to be left adjusted on the field boundary.
			      The converted value is padded on the right with
			      blanks, rather than on the left with blanks or
			      zeros.  A - overrides a 0 if both are given.

		    '' '' (space)  A blank should be left before a positive
			      number produced by a signed conversion (d).

		    +	      A sign must always be placed before a number
			      produced by a signed conversion.	A + overrides
			      a space if both are used.

		field-width
			An optional decimal digit <A HREF="#string">string</A> specifying a minimum
			field width.  If the converted value has fewer bytes
			than the field width, <A HREF="motion.html#it">it</A> will be padded with spaces on
			the left (or right, if the left-adjustment flag has
			been given) to fill out the field width.

		.precision
			An optional precision, in the form of a period '<A HREF="repeat.html#.">.</A>'
			followed by an optional digit <A HREF="#string">string</A>.  If the digit
			<A HREF="#string">string</A> is omitted, the precision is taken <A HREF="motion.html#as">as</A> zero.
			This gives the minimum number of digits to appear for
			<A HREF="change.html#d">d</A>, <A HREF="insert.html#o">o</A>, <A HREF="change.html#x">x</A>, and X conversions, or the maximum number of
			bytes to be printed from a <A HREF="#string">string</A> for <A HREF="change.html#s">s</A> conversions.
			For floating point <A HREF="motion.html#it">it</A> is the number of digits after
			the decimal point.

		type
			A character that specifies the type of conversion to
			be applied, see below.

		A field width or precision, or both, may be indicated by an
		asterisk '*' instead of a digit <A HREF="#string">string</A>.  In this <A HREF="change.html#case">case</A>, a
		<A HREF="#Number">Number</A> argument supplies the field width or precision.	A
		negative field width is treated <A HREF="motion.html#as">as</A> a left adjustment flag
		followed by a positive field width; a negative precision is
		treated <A HREF="motion.html#as">as</A> though <A HREF="motion.html#it">it</A> were missing.  Example:
<B>			:echo printf("%d: %.*s", nr, width, line)</B>
 		This <A HREF="vi_diff.html#limits">limits</A> the length of the text used from &quot;line&quot; to
		&quot;width&quot; bytes.

		The conversion specifiers and their meanings are:


				*<A NAME="printf-d"></A><B>printf-d</B>* *<A NAME="printf-o"></A><B>printf-o</B>* *<A NAME="printf-x"></A><B>printf-x</B>* *<A NAME="printf-X"></A><B>printf-X</B>*
		doxX	The <A HREF="#Number">Number</A> argument is converted to signed decimal
			(d), unsigned <A HREF="#octal">octal</A> (o), or unsigned hexadecimal (x
			and X) <A HREF="intro.html#notation">notation</A>.  The letters &quot;abcdef&quot; are used for
			<A HREF="change.html#x">x</A> conversions; the letters &quot;ABCDEF&quot; are used for X
			conversions.
			The precision, if any, gives the minimum number of
			digits that must appear; if the converted value
			requires fewer digits, <A HREF="motion.html#it">it</A> is padded on the left with
			zeros.
			In no <A HREF="change.html#case">case</A> does a non-existent or small field width
			cause truncation of a numeric field; if the result of
			a conversion is wider than the field width, the field
			is expanded to contain the conversion result.


							*<A NAME="printf-c"></A><B>printf-c</B>*
		<A HREF="change.html#c">c</A>	The <A HREF="#Number">Number</A> argument is converted to a byte, and the
			resulting character is written.


							*<A NAME="printf-s"></A><B>printf-s</B>*
		<A HREF="change.html#s">s</A>	The text of the <A HREF="#String">String</A> argument is used.  If a
			precision is specified, no more bytes than the number
			specified are used.

							*<A NAME="printf-S"></A><B>printf-S</B>*
		<A HREF="change.html#S">S</A>	The text of the <A HREF="#String">String</A> argument is used.  If a
			precision is specified, no more display cells than the
			number specified are used.  Without the |<A HREF="various.html#+multi_byte">+multi_byte</A>|
			feature works just like '<A HREF="change.html#s">s</A>'.


							*<A NAME="printf-f"></A><B>printf-f</B>* *<A NAME="E807"></A><B>E807</B>*
		<A HREF="motion.html#f">f</A>	The <A HREF="#Float">Float</A> argument is converted into a <A HREF="#string">string</A> of the 
			form 123.456.  The precision specifies the number of
			digits after the decimal point.  When the precision is
			zero the decimal point is omitted.  When the precision
			is not specified 6 is used.  A really big number
			(out of range or dividing by zero) results in &quot;inf&quot;.
			&quot;0.0 / 0.0&quot; results in &quot;nan&quot;.
			Example:
<B>				echo printf("%.2f", 12.115)</B>
 				12.12
			Note that roundoff depends on the system libraries.
			Use |<A HREF="#round()">round()</A>| when in doubt.


							*<A NAME="printf-e"></A><B>printf-e</B>* *<A NAME="printf-E"></A><B>printf-E</B>*
		<A HREF="motion.html#e">e</A> <A HREF="motion.html#E">E</A>	The <A HREF="#Float">Float</A> argument is converted into a <A HREF="#string">string</A> of the
			form 1.234e+03 or 1.234E+03 when using '<A HREF="motion.html#E">E</A>'.  The
			precision specifies the number of digits after the
			decimal point, like with '<A HREF="motion.html#f">f</A>'.


							*<A NAME="printf-g"></A><B>printf-g</B>* *<A NAME="printf-G"></A><B>printf-G</B>*
		<A HREF="index.html#g">g</A> <A HREF="motion.html#G">G</A>	The <A HREF="#Float">Float</A> argument is converted like with '<A HREF="motion.html#f">f</A>' if the
			value is between 0.001 (inclusive) and 10000000.0
			(exclusive).  Otherwise '<A HREF="motion.html#e">e</A>' is used for '<A HREF="index.html#g">g</A>' and '<A HREF="motion.html#E">E</A>'
			for '<A HREF="motion.html#G">G</A>'.  When no precision is specified superfluous
			zeroes and '<A HREF="motion.html#+">+</A>' <A HREF="sign.html#signs">signs</A> are removed, except for the zero
			immediately after the decimal point.  Thus 10000000.0
			results in 1.0e7.


							*<A NAME="printf-&#37;"></A><B>printf-&#37;</B>*
		<A HREF="motion.html#&#37;">&#37;</A>	A '<A HREF="motion.html#&#37;">&#37;</A>' is written.  No argument is converted.  The
			complete conversion specification is &quot;&#37;&#37;&quot;.

		When a <A HREF="#Number">Number</A> argument is expected a <A HREF="#String">String</A> argument is also
		accepted and automatically converted.
		When a <A HREF="#Float">Float</A> or <A HREF="#String">String</A> argument is expected a <A HREF="#Number">Number</A> argument
		is also accepted and automatically converted.
		Any other argument type results in an error message.


							*<A NAME="E766"></A><B>E766</B>* *<A NAME="E767"></A><B>E767</B>*
		The number of {exprN} arguments must exactly match the number
		of &quot;<A HREF="motion.html#&#37;">&#37;</A>&quot; items.  If there are not sufficient or too many
		arguments an error is given.  Up to 18 arguments can be used.



<A HREF="#pumvisible()">pumvisible()</A>						*<A NAME="pumvisible()"></A><B>pumvisible()</B>*
		Returns non-zero when the popup menu is visible, zero
		otherwise.  See |<A HREF="insert.html#ins-completion-menu">ins-completion-menu</A>|.
		This can be used to avoid some things that would remove the
		popup menu.


							*<A NAME="E860"></A><B>E860</B>*

py3eval({expr})						*<A NAME="py3eval()"></A><B>py3eval()</B>*
		Evaluate <A HREF="if_pyth.html#Python">Python</A> <A HREF="#expression">expression</A> {expr} and return its result
		converted to Vim data structures.
		Numbers and strings are returned <A HREF="motion.html#as">as</A> they are (strings are 
		copied though, <A HREF="mbyte.html#Unicode">Unicode</A> strings are additionally converted to 
		<A HREF="options.html#'encoding'">'encoding'</A>).
		<A HREF="#Lists">Lists</A> are represented <A HREF="motion.html#as">as</A> Vim |<A HREF="#List">List</A>| type.
		<A HREF="#Dictionaries">Dictionaries</A> are represented <A HREF="motion.html#as">as</A> Vim |<A HREF="#Dictionary">Dictionary</A>| type with 
		keys converted to strings.
		{only available when compiled with the |<A HREF="various.html#+python3">+python3</A>| feature}


							*<A NAME="E858"></A><B>E858</B>* *<A NAME="E859"></A><B>E859</B>*

pyeval({expr})						*<A NAME="pyeval()"></A><B>pyeval()</B>*
		Evaluate <A HREF="if_pyth.html#Python">Python</A> <A HREF="#expression">expression</A> {expr} and return its result
		converted to Vim data structures.
		Numbers and strings are returned <A HREF="motion.html#as">as</A> they are (strings are 
		copied though).
		<A HREF="#Lists">Lists</A> are represented <A HREF="motion.html#as">as</A> Vim |<A HREF="#List">List</A>| type.
		<A HREF="#Dictionaries">Dictionaries</A> are represented <A HREF="motion.html#as">as</A> Vim |<A HREF="#Dictionary">Dictionary</A>| type, 
		non-string keys result in error.
		{only available when compiled with the |<A HREF="various.html#+python">+python</A>| feature}


							*<A NAME="E726"></A><B>E726</B>* *<A NAME="E727"></A><B>E727</B>*

range({expr} [, {max} [, {stride}]])				*<A NAME="range()"></A><B>range()</B>*
		Returns a |<A HREF="#List">List</A>| with Numbers:
		- If only {expr} is specified: [0, 1, <A HREF="#...">...</A>, {expr} - 1]
		- If {max} is specified: [{expr}, {expr} + 1, <A HREF="#...">...</A>, {max}]
		- If {stride} is specified: [{expr}, {expr} + {stride}, <A HREF="#...">...</A>,
		  {max}] (increasing {expr} with {stride} each time, not
		  producing a value past {max}).
		When the maximum is one before the start the result is an
		empty <A HREF="#list">list</A>.  When the maximum is more than one before the
		start this is an error.
		Examples:
<B>			range(4)		" [0, 1, 2, 3]</B>
<B>			range(2, 4)		" [2, 3, 4]</B>
<B>			range(2, 9, 3)		" [2, 5, 8]</B>
<B>			range(2, -2, -1)	" [2, 1, 0, -1, -2]</B>
<B>			range(0)		" []</B>
<B>			range(2, 0)		" error!</B>
 

							*<A NAME="readfile()"></A><B>readfile()</B>*
readfile({fname} [, {binary} [, {max}]])
		Read file {fname} and return a |<A HREF="#List">List</A>|, each line of the file
		<A HREF="motion.html#as">as</A> an item.  Lines broken at NL characters.  <A HREF="os_mac.html#Macintosh">Macintosh</A> files
		separated with CR will result in a single long line (unless a
		NL appears somewhere).
		All NUL characters are replaced with a NL character.
		When {binary} contains &quot;<A HREF="motion.html#b">b</A>&quot; binary mode is used:
		- When the last line ends in a NL an extra empty <A HREF="#list">list</A> item is
		  added.
		- No CR characters are removed.
		Otherwise:
		- CR characters that appear before a NL are removed.
		- Whether the last line ends in a NL or not does not matter.
		- When <A HREF="options.html#'encoding'">'encoding'</A> is <A HREF="mbyte.html#Unicode">Unicode</A> any <A HREF="mbyte.html#UTF-8">UTF-8</A> byte order <A HREF="motion.html#mark">mark</A> is
		  removed from the text.
		When {max} is given this specifies the maximum number of lines
		to be read.  Useful if you only want to check the first ten
		lines of a file:
<B>			:for line in readfile(fname, '', 10)</B>
<B>			:  if line =~ 'Date' | echo line | endif</B>
<B>			:endfor</B>
 		When {max} is negative -{max} lines from the end of the file
		are returned, or <A HREF="motion.html#as">as</A> many <A HREF="motion.html#as">as</A> there are.
		When {max} is zero the result is an empty <A HREF="#list">list</A>.
		Note that without {max} the whole file is read into memory.
		Also note that there is no recognition of encoding.  Read a
		file into a buffer if you need to.
		When the file can't be opened an error message is given and
		the result is an empty <A HREF="#list">list</A>.
		Also see |<A HREF="#writefile()">writefile()</A>|.


reltime([{start} [, {end}]])				*<A NAME="reltime()"></A><B>reltime()</B>*
		Return an item that represents a time value.  The format of
		the item depends on the system.  It can be passed to
		|<A HREF="#reltimestr()">reltimestr()</A>| to convert <A HREF="motion.html#it">it</A> to a <A HREF="#string">string</A>.
		Without an argument <A HREF="motion.html#it">it</A> returns the current time.
		With one argument is returns the time passed since the time
		specified in the argument.
		With two arguments <A HREF="motion.html#it">it</A> returns the time passed between {start}
		and {end}.
		The {start} and {end} arguments must be values returned by
		<A HREF="#reltime()">reltime()</A>.
		{only available when compiled with the |<A HREF="various.html#+reltime">+reltime</A>| feature}


reltimestr({time})				*<A NAME="reltimestr()"></A><B>reltimestr()</B>*
		Return a <A HREF="#String">String</A> that represents the time value of {time}.
		This is the number of seconds, a dot and the number of
		microseconds.  Example:
<B>			let start = reltime()</B>
<B>			call MyFunction()</B>
<B>			echo reltimestr(reltime(start))</B>
 		Note that overhead for the commands will be added to the time.
		The accuracy depends on the system.
		Leading spaces are used to make the <A HREF="#string">string</A> align nicely.  You
		can use <A HREF="#split()">split()</A> to remove <A HREF="motion.html#it">it</A>.
<B>			echo split(reltimestr(reltime(start)))[0]</B>
 		Also see |<A HREF="repeat.html#profiling">profiling</A>|.
		{only available when compiled with the |<A HREF="various.html#+reltime">+reltime</A>| feature}


							*<A NAME="remote_expr()"></A><B>remote_expr()</B>* *<A NAME="E449"></A><B>E449</B>*
remote_expr({server}, {string} [, {idvar}])
		Send the {string} to {server}.	The <A HREF="#string">string</A> is sent <A HREF="motion.html#as">as</A> an
		<A HREF="#expression">expression</A> and the result is returned after evaluation.
		The result must be a <A HREF="#String">String</A> or a |<A HREF="#List">List</A>|.  A |<A HREF="#List">List</A>| is turned
		into a <A HREF="#String">String</A> by joining the items with a line break in
		between (not at the end), like with join(expr, &quot;\n&quot;).
		If {idvar} is present, <A HREF="motion.html#it">it</A> is taken <A HREF="motion.html#as">as</A> the name of a
		variable and a {serverid} for later use with
		<A HREF="#remote_read()">remote_read()</A> is stored there.
		See also |<A HREF="remote.html#clientserver">clientserver</A>| |<A HREF="autocmd.html#RemoteReply">RemoteReply</A>|.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Note: Any <A HREF="message.html#errors">errors</A> will cause a local error message to be issued
		and the result will be the empty <A HREF="#string">string</A>.
		Examples:
<B>			:echo remote_expr("gvim", "2+2")</B>
<B>			:echo remote_expr("gvim1", "b:current_syntax")</B>
 


remote_foreground({server})				*<A NAME="remote_foreground()"></A><B>remote_foreground()</B>*
		Move the Vim server with the name {server} to the foreground.
		This works like:
<B>			remote_expr({server}, "foreground()")</B>
 		Except that on <A HREF="os_win32.html#Win32">Win32</A> systems the client does the work, to work
		around the problem that the OS doesn't always allow the server
		to bring itself to the foreground.
		Note: This does not restore the <A HREF="windows.html#window">window</A> if <A HREF="motion.html#it">it</A> was minimized,
		like <A HREF="#foreground()">foreground()</A> does.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		{only in the <A HREF="os_win32.html#Win32">Win32</A>, <A HREF="gui_x11.html#Athena">Athena</A>, <A HREF="gui_x11.html#Motif">Motif</A> and <A HREF="gui_x11.html#GTK">GTK</A> <A HREF="gui.html#GUI">GUI</A> versions and the
		<A HREF="os_win32.html#Win32">Win32</A> console version}



remote_peek({serverid} [, {retvar}])		*<A NAME="remote_peek()"></A><B>remote_peek()</B>*
		Returns a positive number if there are available strings
		from {serverid}.  Copies any reply <A HREF="#string">string</A> into the variable
		{retvar} if specified.	{retvar} must be a <A HREF="#string">string</A> with the
		name of a variable.
		Returns zero if none are available.
		Returns -1 if something is wrong.
		See also |<A HREF="remote.html#clientserver">clientserver</A>|.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Examples:
<B>			:let repl = ""</B>
<B>			:echo "PEEK: ".remote_peek(id, "repl").": ".repl</B>


remote_read({serverid})				*<A NAME="remote_read()"></A><B>remote_read()</B>*
		Return the oldest available reply from {serverid} and consume
		<A HREF="motion.html#it">it</A>.  It blocks until a reply is available.
		See also |<A HREF="remote.html#clientserver">clientserver</A>|.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Example:
<B>			:echo remote_read(id)</B>
 

							*<A NAME="remote_send()"></A><B>remote_send()</B>* *<A NAME="E241"></A><B>E241</B>*
remote_send({server}, {string} [, {idvar}])
		Send the {string} to {server}.	The <A HREF="#string">string</A> is sent <A HREF="motion.html#as">as</A> input
		keys and the function returns immediately.  At the Vim server
		the keys are not mapped |<A HREF="map.html#:map">:map</A>|.
		If {idvar} is present, <A HREF="motion.html#it">it</A> is taken <A HREF="motion.html#as">as</A> the name of a variable
		and a {serverid} for later use with <A HREF="#remote_read()">remote_read()</A> is stored
		there.
		See also |<A HREF="remote.html#clientserver">clientserver</A>| |<A HREF="autocmd.html#RemoteReply">RemoteReply</A>|.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Note: Any <A HREF="message.html#errors">errors</A> will be reported in the server and may mess
		up the display.
		Examples:
<B>		:echo remote_send("gvim", ":DropAndReply ".file, "serverid").</B>
<B>		 \ remote_read(serverid)</B>

<B>		:autocmd NONE RemoteReply *</B>
<B>		 \ echo remote_read(expand("&lt;amatch&gt;"))</B>
<B>		:echo remote_send("gvim", ":sleep 10 | echo ".</B>
<B>		 \ 'server2client(expand("&lt;client&gt;"), "HELLO")&lt;CR&gt;')</B>
 

remove({list}, {idx} [, {end}])				*<A NAME="remove()"></A><B>remove()</B>*
		Without {end}: Remove the item at {idx} from |<A HREF="#List">List</A>| {list} and
		return the item.
		With {end}: Remove items from {idx} to {end} (inclusive) and
		return a <A HREF="#List">List</A> with these items.  When {idx} points to the same
		item <A HREF="motion.html#as">as</A> {end} a <A HREF="#list">list</A> with one item is returned.  When {end}
		points to an item before {idx} this is an error.
		See |<A HREF="#list-index">list-index</A>| for possible values of {idx} and {end}.
		Example:
<B>			:echo "last item: " . remove(mylist, -1)</B>
<B>			:call remove(mylist, 0, 9)</B>
remove({dict}, {key})
		Remove the entry from {dict} with key {key}.  Example:
<B>			:echo "removed " . remove(dict, "one")</B>
 		If there is no {key} in {dict} this is an error.

		Use |<A HREF="#delete()">delete()</A>| to remove a file.


rename({from}, {to})					*<A NAME="rename()"></A><B>rename()</B>*
		Rename the file by the name {from} to the name {to}.  This
		should also work to move files across file systems.  The
		result is a <A HREF="#Number">Number</A>, which is 0 if the file was renamed
		successfully, and non-zero when the renaming failed.
		NOTE: If {to} exists <A HREF="motion.html#it">it</A> is overwritten without warning.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.


repeat({expr}, {count})					*<A NAME="repeat()"></A><B>repeat()</B>*
		Repeat {expr} {count} times and return the concatenated
		result.  Example:
<B>			:let separator = repeat('-', 80)</B>
 		When {count} is zero or negative the result is empty.
		When {expr} is a |<A HREF="#List">List</A>| the result is {expr} concatenated
		{count} times.	Example:
<B>			:let longlist = repeat(['a', 'b'], 3)</B>
 		Results in ['a', '<A HREF="motion.html#b">b</A>', '<A HREF="insert.html#a">a</A>', '<A HREF="motion.html#b">b</A>', '<A HREF="insert.html#a">a</A>', 'b'].



resolve({filename})					*<A NAME="resolve()"></A><B>resolve()</B>* *<A NAME="E655"></A><B>E655</B>*
		On <A HREF="os_win32.html#MS-Windows">MS-Windows</A>, when {filename} is a shortcut (a .lnk file),
		returns the path the shortcut points to in a simplified form.
		On <A HREF="os_unix.html#Unix">Unix</A>, repeat resolving symbolic links in all path
		components of {filename} and return the simplified result.
		To cope with link cycles, resolving of symbolic links is
		stopped after 100 iterations.
		On other systems, return the simplified {filename}.
		The simplification step is done <A HREF="motion.html#as">as</A> by |<A HREF="#simplify()">simplify()</A>|.
		<A HREF="#resolve()">resolve()</A> keeps a leading path component specifying the
		current directory (provided the result is still a relative
		path name) and also keeps a trailing path separator.


							*<A NAME="reverse()"></A><B>reverse()</B>*
reverse({list})	Reverse the order of items in {list} in-place.	Returns
		{list}.
		If you want a <A HREF="#list">list</A> to remain unmodified make a copy first:
<B>			:let revlist = reverse(copy(mylist))</B>


round({expr})							*<A NAME="round()"></A><B>round()</B>*
		Round off {expr} to the nearest integral value and return <A HREF="motion.html#it">it</A>
		<A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.  If {expr} lies halfway between two integral
		values, then use the larger one (away from zero).
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			echo round(0.456)</B>
 			0.0 
<B>			echo round(4.5)</B>
 			5.0
<B>			echo round(-4.5)</B>
 			-5.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}


screenattr(row, col)						*<A NAME="screenattr()"></A><B>screenattr()</B>*
		Like <A HREF="#screenchar()">screenchar()</A>, but return the attribute.  This is a rather
		arbitrary number that can only be used to compare to the
		attribute at other positions.


screenchar(row, col)						*<A NAME="screenchar()"></A><B>screenchar()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the character at position
		[row, col] on the screen.  This works for every possible
		screen position, also status lines, <A HREF="windows.html#window">window</A> separators and the
		command line.  The top left position is row one, column one
		The character excludes composing characters.  For double-byte
		encodings <A HREF="motion.html#it">it</A> may only be the first byte.
		This is mainly to be used for testing.
		Returns -1 when row or col is out of range.


<A HREF="#screencol()">screencol()</A>							*<A NAME="screencol()"></A><B>screencol()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the current screen column of
		the cursor. The leftmost column has number 1.
		This function is mainly used for testing.

		Note: Always returns the current screen column, thus if used
		in a command (e.g. &quot;<A HREF="#:echo">:echo</A> screencol()&quot;) <A HREF="motion.html#it">it</A> will return the
		column inside the command line, which is 1 when the command is
		executed. To get the cursor position in the file use one of
		the following mappings:
<B>			nnoremap &lt;expr&gt; GG ":echom ".screencol()."\n"</B>
<B>			nnoremap &lt;silent&gt; GG :echom screencol()&lt;CR&gt;</B>
 

<A HREF="#screenrow()">screenrow()</A>							*<A NAME="screenrow()"></A><B>screenrow()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the current screen row of the
		cursor.  The top line has number one.
		This function is mainly used for testing.

		Note: Same restrictions <A HREF="motion.html#as">as</A> with |<A HREF="#screencol()">screencol()</A>|.


search({pattern} [, {flags} [, {stopline} [, {timeout}]]])	*<A NAME="search()"></A><B>search()</B>*
		Search for <A HREF="pattern.html#regexp">regexp</A> <A HREF="pattern.html#pattern">pattern</A> {pattern}.  The search starts at the
		cursor position (you can use |<A HREF="#cursor()">cursor()</A>| to set <A HREF="motion.html#it">it</A>).

		When a match has been found its line number is returned.
		If there is no match a 0 is returned and the cursor doesn't
		move.  No error message is given.

		{flags} is a <A HREF="#String">String</A>, which can contain these character flags:
		'<A HREF="motion.html#b">b</A>'	search Backward instead of forward
		'<A HREF="change.html#c">c</A>'	accept a match at the Cursor position
		'<A HREF="motion.html#e">e</A>'	move to the End of the match
		'<A HREF="pattern.html#n">n</A>'	<A HREF="diff.html#do">do</A> Not move the cursor
		'<A HREF="change.html#p">p</A>'	return number of matching sub-Pattern (see below)
		'<A HREF="change.html#s">s</A>'	Set the '' <A HREF="motion.html#mark">mark</A> at the previous location of the cursor
		'<A HREF="motion.html#w">w</A>'	Wrap around the end of the file
		'<A HREF="motion.html#W">W</A>'	don't Wrap around the end of the file
		'<A HREF="index.html#z">z</A>'	start searching at the cursor column instead of zero
		If neither '<A HREF="motion.html#w">w</A>' or '<A HREF="motion.html#W">W</A>' is given, the <A HREF="options.html#'wrapscan'">'wrapscan'</A> option applies.

		If the '<A HREF="change.html#s">s</A>' flag is supplied, the '' <A HREF="motion.html#mark">mark</A> is set, only if the
		cursor is moved. The '<A HREF="change.html#s">s</A>' flag cannot be combined with the '<A HREF="pattern.html#n">n</A>'
		flag.

		<A HREF="options.html#'ignorecase'">'ignorecase'</A>, <A HREF="options.html#'smartcase'">'smartcase'</A> and <A HREF="options.html#'magic'">'magic'</A> are used.
		
		When the '<A HREF="index.html#z">z</A>' flag is not given, searching always starts in
		column zero and then matches before the cursor are skipped.
		When the '<A HREF="change.html#c">c</A>' flag is present in <A HREF="options.html#'cpo'">'cpo'</A> the next search starts
		after the match.  Without the '<A HREF="change.html#c">c</A>' flag the next search starts
		one column further.

		When the {stopline} argument is given then the search stops
		after searching this line.  This is useful to restrict the
		search to a range of lines.  Examples:
<B>			let match = search('(', 'b', line("w0"))</B>
<B>			let end = search('END', '', line("w$"))</B>
 		When {stopline} is used and <A HREF="motion.html#it">it</A> is not zero this also implies
		that the search does not wrap around the end of the file.
		A zero value is equal to not giving the argument.

		When the {timeout} argument is given the search stops when
		more than this many milliseconds have passed.	Thus when
		{timeout} is 500 the search stops after half a second.
		The value must not be negative.  A zero value is like not
		giving the argument.
		{only available when compiled with the |<A HREF="various.html#+reltime">+reltime</A>| feature}


							*<A NAME="search()-sub-match"></A><B>search()-sub-match</B>*
		With the '<A HREF="change.html#p">p</A>' flag the returned value is one more than the
		first sub-match in \(\).  One if none of them matched but the
		whole <A HREF="pattern.html#pattern">pattern</A> did match.
		To get the column number too use |<A HREF="#searchpos()">searchpos()</A>|.

		The cursor will be positioned at the match, unless the '<A HREF="pattern.html#n">n</A>'
		flag is used.

		Example (goes over all files in the argument list):
<B>		    :let n = 1</B>
<B>		    :while n &lt;= argc()	    " loop over all files in arglist</B>
<B>		    :  exe "argument " . n</B>
<B>		    :  " start at the last char in the file and wrap for the</B>
<B>		    :  " first search to find match at start of file</B>
<B>		    :  normal G$</B>
<B>		    :  let flags = "w"</B>
<B>		    :  while search("foo", flags) &gt; 0</B>
<B>		    :	 s/foo/bar/g</B>
<B>		    :	 let flags = "W"</B>
<B>		    :  endwhile</B>
<B>		    :  update		    " write the file if modified</B>
<B>		    :  let n = n + 1</B>
<B>		    :endwhile</B>
 
		Example for using some flags:
<B>		    :echo search('\&lt;if\|\(else\)\|\(endif\)', 'ncpe')</B>
 		This will search for the keywords &quot;if&quot;, &quot;else&quot;, and &quot;endif&quot;
		under or after the cursor.  Because of the '<A HREF="change.html#p">p</A>' flag, <A HREF="motion.html#it">it</A>
		returns 1, 2, or 3 depending on which keyword is found, or 0
		if the search fails.  With the cursor on the first <A HREF="motion.html#word">word</A> of the
		line:
<B><FONT COLOR="PURPLE">		    if (foo == 0) | let foo = foo + 1 | endif </FONT></B>
		the function returns 1.  Without the '<A HREF="change.html#c">c</A>' flag, the function
		finds the &quot;endif&quot; and returns 3.  The same thing happens
		without the '<A HREF="motion.html#e">e</A>' flag if the cursor is on the &quot;<A HREF="motion.html#f">f</A>&quot; of &quot;if&quot;.
		The '<A HREF="pattern.html#n">n</A>' flag tells the function not to move the cursor.



searchdecl({name} [, {global} [, {thisblock}]])			*<A NAME="searchdecl()"></A><B>searchdecl()</B>*
		Search for the declaration of {name}.

		With a non-zero {global} argument <A HREF="motion.html#it">it</A> works like |<A HREF="pattern.html#gD">gD</A>|, find
		first match in the file.  Otherwise <A HREF="motion.html#it">it</A> works like |<A HREF="pattern.html#gd">gd</A>|, find
		first match in the function.

		With a non-zero {thisblock} argument matches in a <A HREF="intro.html#{}">{}</A> block
		that ends before the cursor position are ignored.  Avoids
		finding variable declarations only valid in another scope.

		Moves the cursor to the found match.
		Returns zero for success, non-zero for failure.
		Example:
<B>			if searchdecl('myvar') == 0</B>
<B>			   echo getline('.')</B>
<B>			endif</B>
 

							*<A NAME="searchpair()"></A><B>searchpair()</B>*
searchpair({start}, {middle}, {end} [, {flags} [, {skip}
				[, {stopline} [, {timeout}]]]])
		Search for the match of a nested start-end pair.  This can be
		used to find the &quot;endif&quot; that matches an &quot;if&quot;, while other
		if/endif pairs in between are ignored.
		The search starts at the cursor.  The default is to search
		forward, include '<A HREF="motion.html#b">b</A>' in {flags} to search backward.
		If a match is found, the cursor is positioned at <A HREF="motion.html#it">it</A> and the
		line number is returned.  If no match is found 0 or -1 is
		returned and the cursor doesn't move.  No error message is
		given.

		{start}, {middle} and {end} are patterns, see |<A HREF="pattern.html#pattern">pattern</A>|.  They
		must not contain \( \) pairs.  Use of \&#37;( \) is allowed.  When
		{middle} is not empty, <A HREF="motion.html#it">it</A> is found when searching from either
		direction, but only when not in a nested start-end pair.  A
		typical use is:
<B>			searchpair('\&lt;if\&gt;', '\&lt;else\&gt;', '\&lt;endif\&gt;')</B>
 		By leaving {middle} empty the &quot;else&quot; is skipped.

		{flags} '<A HREF="motion.html#b">b</A>', '<A HREF="change.html#c">c</A>', '<A HREF="pattern.html#n">n</A>', '<A HREF="change.html#s">s</A>', '<A HREF="motion.html#w">w</A>' and '<A HREF="motion.html#W">W</A>' are used like with
		|<A HREF="#search()">search()</A>|.  Additionally:
		'<A HREF="change.html#r">r</A>'	Repeat until no more matches found; will find the
			outer pair.  Implies the '<A HREF="motion.html#W">W</A>' flag.
		'<A HREF="motion.html#m">m</A>'	Return number of matches instead of line number with
			the match; will be <A HREF="change.html#&gt;">&gt;</A> 1 when '<A HREF="change.html#r">r</A>' is used.
		Note: it's nearly always a good idea to use the '<A HREF="motion.html#W">W</A>' flag, to
		avoid wrapping around the end of the file.

		When a match for {start}, {middle} or {end} is found, the
		{skip} <A HREF="#expression">expression</A> is evaluated with the cursor positioned on
		the start of the match.  It should return non-zero if this
		match is to be skipped.  E.g., because <A HREF="motion.html#it">it</A> is inside a comment
		or a <A HREF="#string">string</A>.
		When {skip} is omitted or empty, every match is accepted.
		When evaluating {skip} causes an error the search is aborted
		and -1 returned.

		For {stopline} and {timeout} see |<A HREF="#search()">search()</A>|.

		The value of <A HREF="options.html#'ignorecase'">'ignorecase'</A> is used.  <A HREF="options.html#'magic'">'magic'</A> is ignored, the
		patterns are used like it's on.

		The search starts exactly at the cursor.  A match with
		{start}, {middle} or {end} at the next character, in the
		direction of searching, is the first one found.  Example:
<B>			if 1</B>
<B>			  if 2</B>
<B>			  endif 2</B>
<B>			endif 1</B>
 		When starting at the &quot;if 2&quot;, with the cursor on the &quot;<A HREF="insert.html#i">i</A>&quot;, and
		searching forwards, the &quot;endif 2&quot; is found.  When starting on
		the character just before the &quot;if 2&quot;, the &quot;endif 1&quot; will be
		found.	That's because the &quot;if 2&quot; will be found first, and
		then this is considered to be a nested if/endif from &quot;if 2&quot; to
		&quot;endif 2&quot;.
		When searching backwards and {end} is more than one character,
		<A HREF="motion.html#it">it</A> may be useful to put &quot;\zs&quot; at the end of the <A HREF="pattern.html#pattern">pattern</A>, so
		that when the cursor is inside a match with the end <A HREF="motion.html#it">it</A> finds
		the matching start.

		Example, to find the &quot;endif&quot; command in a Vim <A HREF="usr_41.html#script">script</A>:

<B>	:echo searchpair('\&lt;if\&gt;', '\&lt;el\%[seif]\&gt;', '\&lt;en\%[dif]\&gt;', 'W',</B>
<B>			\ 'getline(".") =~ "^\\s*\""')</B>

 		The cursor must be at or after the &quot;if&quot; for which a match is
		to be found.  Note that single-quote strings are used to avoid
		having to double the backslashes.  The skip <A HREF="#expression">expression</A> only
		catches comments at the start of a line, not after a command.
		Also, a <A HREF="motion.html#word">word</A> &quot;en&quot; or &quot;if&quot; halfway a line is considered a
		match.
		Another example, to search for the matching &quot;<A HREF="motion.html#{">{</A>&quot; of a &quot;<A HREF="motion.html#}">}</A>&quot;:

<B>	:echo searchpair('{', '', '}', 'bW')</B>

 		This works when the cursor is at or before the &quot;<A HREF="motion.html#}">}</A>&quot; for which a
		match is to be found.  To reject matches that <A HREF="syntax.html#syntax">syntax</A>
		highlighting recognized <A HREF="motion.html#as">as</A> strings:

<B>	:echo searchpair('{', '', '}', 'bW',</B>
<B>	     \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')</B>
 

							*<A NAME="searchpairpos()"></A><B>searchpairpos()</B>*
searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
				[, {stopline} [, {timeout}]]]])
		Same <A HREF="motion.html#as">as</A> |<A HREF="#searchpair()">searchpair()</A>|, but returns a |<A HREF="#List">List</A>| with the line and
		column position of the match. The first element of the |<A HREF="#List">List</A>|
		is the line number and the second element is the byte index of
		the column position of the match.  If no match is found,
		returns [0, 0].

<B>			:let [lnum,col] = searchpairpos('{', '', '}', 'n')</B>
 
		See |<A HREF="tips.html#match-parens">match-parens</A>| for a bigger and more useful example.


searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])	*<A NAME="searchpos()"></A><B>searchpos()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#search()">search()</A>|, but returns a |<A HREF="#List">List</A>| with the line and
		column position of the match. The first element of the |<A HREF="#List">List</A>|
		is the line number and the second element is the byte index of
		the column position of the match. If no match is found,
		returns [0, 0].
		Example:
<B>	:let [lnum, col] = searchpos('mypattern', 'n')</B>

 		When the '<A HREF="change.html#p">p</A>' flag is given then there is an extra item with
		the sub-pattern match number |<A HREF="#search()-sub-match">search()-sub-match</A>|.  Example:
<B>	:let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')</B>
 		In this example &quot;submatch&quot; is 2 when a <A HREF="change.html#lowercase">lowercase</A> <A HREF="print.html#letter">letter</A> is
		found |<A HREF="pattern.html#/\l">/\l</A>|, 3 when an <A HREF="change.html#uppercase">uppercase</A> <A HREF="print.html#letter">letter</A> is found |<A HREF="pattern.html#/\u">/\u</A>|.


server2client( {clientid}, {string})			*<A NAME="server2client()"></A><B>server2client()</B>*
		Send a reply <A HREF="#string">string</A> to {clientid}.  The most recent {clientid}
		that sent a <A HREF="#string">string</A> can be retrieved with expand(&quot;&lt;client&gt;&quot;).
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Note:
		This id has to be stored before the next command can be
		received.  I.e. before returning from the received command and
		before calling any commands that waits for input.
		See also |<A HREF="remote.html#clientserver">clientserver</A>|.
		Example:
<B>			:echo server2client(expand("&lt;client&gt;"), "HELLO")</B>
 

<A HREF="#serverlist()">serverlist()</A>					*<A NAME="serverlist()"></A><B>serverlist()</B>*
		Return a <A HREF="#list">list</A> of available server names, one per line.
		When there are no servers or the information is not available
		an empty <A HREF="#string">string</A> is returned.  See also |<A HREF="remote.html#clientserver">clientserver</A>|.
		{only available when compiled with the |<A HREF="various.html#+clientserver">+clientserver</A>| feature}
		Example:
<B>			:echo serverlist()</B>
 

setbufvar({expr}, {varname}, {val})			*<A NAME="setbufvar()"></A><B>setbufvar()</B>*
		Set option or local variable {varname} in buffer {expr} to
		{val}.
		This also works for a global or local <A HREF="windows.html#window">window</A> option, but <A HREF="motion.html#it">it</A>
		doesn't work for a global or local <A HREF="windows.html#window">window</A> variable.
		For a local <A HREF="windows.html#window">window</A> option the global value is unchanged.
		For the use of {expr}, see |<A HREF="#bufname()">bufname()</A>| above.
		Note that the variable name without &quot;<A HREF="#b:">b:</A>&quot; must be used.
		Examples:
<B>			:call setbufvar(1, "&amp;mod", 1)</B>
<B>			:call setbufvar("todo", "myvar", "foobar")</B>
 		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.


setcharsearch({dict})					*<A NAME="setcharsearch()"></A><B>setcharsearch()</B>*
		Set the current character search information to {dict},
		which contains one or more of the following entries:

		    char	character which will be used for a subsequent
				|<A HREF="motion.html#,">,</A>| or |<A HREF="motion.html#;">;</A>| command; an empty <A HREF="#string">string</A> clears the
				character search
		    forward	direction of character search; 1 for forward,
				0 for backward
		    until	type of character search; 1 for a |<A HREF="motion.html#t">t</A>| or |<A HREF="motion.html#T">T</A>|
				character search, 0 for an |<A HREF="motion.html#f">f</A>| or |<A HREF="motion.html#F">F</A>|
				character search

		This can be useful to save/restore a user's character search
		from a <A HREF="usr_41.html#script">script</A>:
<B>			:let prevsearch = getcharsearch()</B>
<B>			:" Perform a command which clobbers user's search</B>
<B>			:call setcharsearch(prevsearch)</B>
 		Also see |<A HREF="#getcharsearch()">getcharsearch()</A>|.


setcmdpos({pos})					*<A NAME="setcmdpos()"></A><B>setcmdpos()</B>*
		Set the cursor position in the command line to byte position
		{pos}.	The first position is 1.
		Use |<A HREF="#getcmdpos()">getcmdpos()</A>| to obtain the current position.
		Only works while editing the command line, thus you must use
		|<A HREF="cmdline.html#c_CTRL-\_e">c_CTRL-\_e</A>|, |<A HREF="cmdline.html#c_CTRL-R_=">c_CTRL-R_=</A>| or |<A HREF="cmdline.html#c_CTRL-R_CTRL-R">c_CTRL-R_CTRL-R</A>| with '='.  For
		|<A HREF="cmdline.html#c_CTRL-\_e">c_CTRL-\_e</A>| and |<A HREF="cmdline.html#c_CTRL-R_CTRL-R">c_CTRL-R_CTRL-R</A>| with '<A HREF="change.html#=">=</A>' the position is
		set after the command line is set to the <A HREF="#expression">expression</A>.  For
		|<A HREF="cmdline.html#c_CTRL-R_=">c_CTRL-R_=</A>| <A HREF="motion.html#it">it</A> is set after evaluating the <A HREF="#expression">expression</A> but
		before <A HREF="insert.html#inserting">inserting</A> the resulting text.
		When the number is too big the cursor is put at the end of the
		line.  A number smaller than one has undefined results.
		Returns 0 when successful, 1 when not editing the command
		line.


setfperm({fname}, {mode})				*<A NAME="setfperm()"></A><B>setfperm()</B>* *<A NAME="chmod"></A><B>chmod</B>*
		Set the file permissions for {fname} to {mode}.
		{mode} must be a <A HREF="#string">string</A> with 9 characters.  It is of the form
		&quot;rwxrwxrwx&quot;, where each group of &quot;rwx&quot; flags represent, in
		turn, the permissions of the owner of the file, the group the
		file belongs to, and other users.  A '<A HREF="motion.html#-">-</A>' character means the
		permission is off, any other character means on.  Multi-byte
		characters are not supported.

		For example &quot;rw-r-----&quot; means read-write for the user,
		readable by the group, not accessible by others.  &quot;xx-x-----&quot;
		would <A HREF="diff.html#do">do</A> the same thing.

		Returns non-zero for success, zero for failure.

		To read permissions see |<A HREF="#getfperm()">getfperm()</A>|.



setline({lnum}, {text})					*<A NAME="setline()"></A><B>setline()</B>*
		Set line {lnum} of the current buffer to {text}.  To insert
		lines use |<A HREF="#append()">append()</A>|.
		{lnum} is used like with |<A HREF="#getline()">getline()</A>|.
		When {lnum} is just below the last line the {text} will be
		added <A HREF="motion.html#as">as</A> a new line.
		If this succeeds, 0 is returned.  If this fails (most likely
		because {lnum} is invalid) 1 is returned.  Example:
<B>			:call setline(5, strftime("%c"))</B>
 		When {text} is a |<A HREF="#List">List</A>| then line {lnum} and following lines
		will be set to the items in the <A HREF="#list">list</A>.  Example:
<B>			:call setline(5, ['aaa', 'bbb', 'ccc'])</B>
 		This is equivalent to:
<B>			:for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]</B>
<B>			:  call setline(n, l)</B>
<B>			:endfor</B>
 		Note: The <A HREF="motion.html#'[">'[</A> and <A HREF="motion.html#']">']</A> marks are not set.


setloclist({nr}, {list} [, {action}])			*<A NAME="setloclist()"></A><B>setloclist()</B>*
		Create or replace or add to the location <A HREF="#list">list</A> for <A HREF="windows.html#window">window</A> {nr}.
		When {nr} is zero the current <A HREF="windows.html#window">window</A> is used. For a location
		<A HREF="#list">list</A> <A HREF="windows.html#window">window</A>, the displayed location <A HREF="#list">list</A> is modified.  For an
		invalid <A HREF="windows.html#window">window</A> number {nr}, -1 is returned.
		Otherwise, same <A HREF="motion.html#as">as</A> |<A HREF="#setqflist()">setqflist()</A>|.
		Also see |<A HREF="quickfix.html#location-list">location-list</A>|.


setmatches({list})					*<A NAME="setmatches()"></A><B>setmatches()</B>*
		Restores a <A HREF="#list">list</A> of matches saved by |<A HREF="#getmatches()">getmatches()</A>|.  Returns 0
		if successful, otherwise -1.  All current matches are cleared
		before the <A HREF="#list">list</A> is restored.  See example for |<A HREF="#getmatches()">getmatches()</A>|.


							*<A NAME="setpos()"></A><B>setpos()</B>*
setpos({expr}, {list})
		Set the position for {expr}.  Possible values:
			.	the cursor
			'x	<A HREF="motion.html#mark">mark</A> <A HREF="change.html#x">x</A>

		{list} must be a |<A HREF="#List">List</A>| with four or five numbers:
		    [bufnum, lnum, col, off]
		    [bufnum, lnum, col, off, curswant]

		&quot;bufnum&quot; is the buffer number.	Zero can be used for the
		current buffer.  Setting the cursor is only possible for
		the current buffer.  To set a <A HREF="motion.html#mark">mark</A> in another buffer you can
		use the |<A HREF="#bufnr()">bufnr()</A>| function to turn a file name into a buffer
		number.
		Does not change the <A HREF="motion.html#jumplist">jumplist</A>.

		&quot;lnum&quot; and &quot;col&quot; are the position in the buffer.  The first
		column is 1.  Use a zero &quot;lnum&quot; to delete a <A HREF="motion.html#mark">mark</A>.  If &quot;col&quot; is
		smaller than 1 then 1 is used.

		The &quot;off&quot; number is only used when <A HREF="options.html#'virtualedit'">'virtualedit'</A> is set. Then
		<A HREF="motion.html#it">it</A> is the offset in screen columns from the start of the
		character.  E.g., a position within a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> or after the last
		character.

		The &quot;curswant&quot; number is only used when setting the cursor
		position.  It sets the preferred column for when moving the
		cursor vertically.  When the &quot;curswant&quot; number is missing the
		preferred column is not set.  When <A HREF="motion.html#it">it</A> is present and setting a
		<A HREF="motion.html#mark">mark</A> position <A HREF="motion.html#it">it</A> is not used.

		Note that for <A HREF="motion.html#'&lt;">'&lt;</A> and <A HREF="motion.html#'&gt;">'&gt;</A> <A HREF="change.html#changing">changing</A> the line number may result in
		the marks to be effectively be swapped, so that <A HREF="motion.html#'&lt;">'&lt;</A> is always
		before <A HREF="motion.html#'&gt;">'&gt;</A>.

		Returns 0 when the position could be set, -1 otherwise.
		An error message is given if {expr} is invalid.

		Also see |<A HREF="#getpos()">getpos()</A>| and |<A HREF="#getcurpos()">getcurpos()</A>|.

		This does not restore the preferred column for moving
		vertically; if you set the cursor position with this, |<A HREF="motion.html#j">j</A>| and
		|<A HREF="motion.html#k">k</A>| motions will jump to previous columns!  Use |<A HREF="#cursor()">cursor()</A>| to
		also set the preferred column.  Also see the &quot;curswant&quot; key in
		|<A HREF="#winrestview()">winrestview()</A>|.



setqflist({list} [, {action}])				*<A NAME="setqflist()"></A><B>setqflist()</B>*
		Create or replace or add to the <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A> using the items
		in {list}.  Each item in {list} is a dictionary.
		Non-dictionary items in {list} are ignored.  Each dictionary
		item can contain the following entries:

		    bufnr	buffer number; must be the number of a valid
				buffer
		    filename	name of a file; only used when &quot;bufnr&quot; is not
				present or <A HREF="motion.html#it">it</A> is invalid.
		    lnum	line number in the file
		    <A HREF="pattern.html#pattern">pattern</A>	search <A HREF="pattern.html#pattern">pattern</A> used to locate the error
		    col		column number
		    vcol	when non-zero: &quot;col&quot; is visual column
				when zero: &quot;col&quot; is byte index
		    nr		error number
		    text	description of the error
		    type	single-character error type, '<A HREF="motion.html#E">E</A>', '<A HREF="motion.html#W">W</A>', etc.

		The &quot;col&quot;, &quot;vcol&quot;, &quot;nr&quot;, &quot;type&quot; and &quot;text&quot; entries are
		optional.  Either &quot;lnum&quot; or &quot;<A HREF="pattern.html#pattern">pattern</A>&quot; entry can be used to
		locate a matching error line.
		If the &quot;filename&quot; and &quot;bufnr&quot; entries are not present or
		neither the &quot;lnum&quot; or &quot;<A HREF="pattern.html#pattern">pattern</A>&quot; entries are present, then the
		item will not be handled <A HREF="motion.html#as">as</A> an error line.
		If both &quot;<A HREF="pattern.html#pattern">pattern</A>&quot; and &quot;lnum&quot; are present then &quot;<A HREF="pattern.html#pattern">pattern</A>&quot; will
		be used.
		If you supply an empty {list}, the <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A> will be
		cleared.
		Note that the <A HREF="#list">list</A> is not exactly the same <A HREF="motion.html#as">as</A> what
		|<A HREF="#getqflist()">getqflist()</A>| returns.

		If {action} is set to '<A HREF="insert.html#a">a</A>', then the items from {list} are
		added to the existing <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A>. If there is no existing
		<A HREF="#list">list</A>, then a new <A HREF="#list">list</A> is created. If {action} is set to '<A HREF="change.html#r">r</A>',
		then the items from the current <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A> are replaced
		with the items from {list}. If {action} is not present or is
		set to '' '', then a new <A HREF="#list">list</A> is created.

		Returns zero for success, -1 for failure.

		This function can be used to create a <A HREF="quickfix.html#quickfix">quickfix</A> <A HREF="#list">list</A>
		independent of the <A HREF="options.html#'errorformat'">'errorformat'</A> setting.  Use a command like
		&quot;<A HREF="quickfix.html#:cc">:cc</A> 1&quot; to jump to the first position.



							*<A NAME="setreg()"></A><B>setreg()</B>*
setreg({regname}, {value} [, {options}])
		Set the <A HREF="sponsor.html#register">register</A> {regname} to {value}.
		{value} may be any value returned by |<A HREF="#getreg()">getreg()</A>|, including 
		a |<A HREF="#List">List</A>|.
		If {options} contains &quot;<A HREF="insert.html#a">a</A>&quot; or {regname} is upper <A HREF="change.html#case">case</A>,
		then the value is appended.
		{options} can also contain a <A HREF="sponsor.html#register">register</A> type specification:
		    &quot;c&quot; or &quot;<A HREF="visual.html#v">v</A>&quot;	      |<A HREF="motion.html#characterwise">characterwise</A>| mode
		    &quot;l&quot; or &quot;<A HREF="visual.html#V">V</A>&quot;	      |<A HREF="motion.html#linewise">linewise</A>| mode
		    &quot;b&quot; or &quot;&lt;CTRL-V&gt;&quot; |<A HREF="visual.html#blockwise-visual">blockwise-visual</A>| mode
		If a number immediately follows &quot;<A HREF="motion.html#b">b</A>&quot; or &quot;&lt;CTRL-V&gt;&quot; then this is
		used <A HREF="motion.html#as">as</A> the width of the selection - if <A HREF="motion.html#it">it</A> is not specified
		then the width of the block is set to the number of characters
		in the longest line (counting a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> <A HREF="motion.html#as">as</A> 1 character).

		If {options} contains no <A HREF="sponsor.html#register">register</A> settings, then the default
		is to use character mode unless {value} ends in a <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> for 
		<A HREF="#string">string</A> {value} and <A HREF="motion.html#linewise">linewise</A> mode for <A HREF="#list">list</A> {value}. Blockwise 
		mode is never selected automatically.
		Returns zero for success, non-zero for failure.


							*<A NAME="E883"></A><B>E883</B>*
		Note: you may not use |<A HREF="#List">List</A>| containing more than one item to 
		      set search and <A HREF="#expression">expression</A> <A HREF="change.html#registers">registers</A>. <A HREF="#Lists">Lists</A> containing no 
		      items act like empty strings.

		Examples:
<B>			:call setreg(v:register, @*)</B>
<B>			:call setreg('*', @%, 'ac')</B>
<B>			:call setreg('a', "1\n2\n3", 'b5')</B>

 		This example shows using the <A HREF="#functions">functions</A> to save and restore a
		<A HREF="sponsor.html#register">register</A> (note: you may not reliably restore <A HREF="sponsor.html#register">register</A> value 
		without using the third argument to |<A HREF="#getreg()">getreg()</A>| <A HREF="motion.html#as">as</A> without <A HREF="motion.html#it">it</A> 
		newlines are represented <A HREF="motion.html#as">as</A> newlines AND Nul bytes are 
		represented <A HREF="motion.html#as">as</A> newlines <A HREF="motion.html#as">as</A> well, see |<A HREF="pattern.html#NL-used-for-Nul">NL-used-for-Nul</A>|).
<B>			:let var_a = getreg('a', 1, 1)</B>
<B>			:let var_amode = getregtype('a')</B>
<B>			    ....</B>
<B>			:call setreg('a', var_a, var_amode)</B>

 		You can also change the type of a <A HREF="sponsor.html#register">register</A> by appending
		nothing:
<B>			:call setreg('a', '', 'al')</B>


settabvar({tabnr}, {varname}, {val})			*<A NAME="settabvar()"></A><B>settabvar()</B>*
		Set tab-local variable {varname} to {val} in <A HREF="intro.html#tab">tab</A> page {tabnr}.
		|<A HREF="#t:var">t:var</A>|
		Note that the variable name without &quot;<A HREF="#t:">t:</A>&quot; must be used.
		Tabs are numbered starting with one.
		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.


settabwinvar({tabnr}, {winnr}, {varname}, {val})	*<A NAME="settabwinvar()"></A><B>settabwinvar()</B>*
		Set option or local variable {varname} in <A HREF="windows.html#window">window</A> {winnr} to
		{val}.
		Tabs are numbered starting with one.  For the current <A HREF="tabpage.html#tabpage">tabpage</A>
		use |<A HREF="#setwinvar()">setwinvar()</A>|.
		When {winnr} is zero the current <A HREF="windows.html#window">window</A> is used.
		This also works for a global or local buffer option, but <A HREF="motion.html#it">it</A>
		doesn't work for a global or local buffer variable.
		For a local buffer option the global value is unchanged.
		Note that the variable name without &quot;<A HREF="#w:">w:</A>&quot; must be used.
		Examples:
<B>			:call settabwinvar(1, 1, "&amp;list", 0)</B>
<B>			:call settabwinvar(3, 2, "myvar", "foobar")</B>
 		This function is not available in the |<A HREF="#sandbox">sandbox</A>|.


setwinvar({nr}, {varname}, {val})			*<A NAME="setwinvar()"></A><B>setwinvar()</B>*
		Like |<A HREF="#settabwinvar()">settabwinvar()</A>| for the current tab page.
		Examples:
<B>			:call setwinvar(1, "&amp;list", 0)</B>
<B>			:call setwinvar(2, "myvar", "foobar")</B>


sha256({string})						*<A NAME="sha256()"></A><B>sha256()</B>*
		Returns a <A HREF="#String">String</A> with 64 hex characters, which is the SHA256
		checksum of {string}.
		{only available when compiled with the |<A HREF="various.html#+cryptv">+cryptv</A>| feature}


shellescape({string} [, {special}])			*<A NAME="shellescape()"></A><B>shellescape()</B>*
		Escape {string} for use <A HREF="motion.html#as">as</A> a shell command argument.
		On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> and <A HREF="os_msdos.html#MS-DOS">MS-DOS</A>, when <A HREF="options.html#'shellslash'">'shellslash'</A> is not set, <A HREF="motion.html#it">it</A>
		will enclose {string} in double <A HREF="quotes.html#quotes">quotes</A> and double all double
		<A HREF="quotes.html#quotes">quotes</A> within {string}.
		For other systems, <A HREF="motion.html#it">it</A> will enclose {string} in single <A HREF="quotes.html#quotes">quotes</A>
		and replace all &quot;&#39;&#34;' with &quot;'\'&#39;&#34;'.
		When the {special} argument is present and it's a non-zero
		<A HREF="#Number">Number</A> or a non-empty <A HREF="#String">String</A> (|<A HREF="#non-zero-arg">non-zero-arg</A>|), then special
		items such <A HREF="motion.html#as">as</A> &quot;<A HREF="change.html#!">!</A>&quot;, &quot;<A HREF="motion.html#&#37;">&#37;</A>&quot;, &quot;<A HREF="pattern.html##">#</A>&quot; and &quot;&lt;cword&gt;&quot; will be preceded by
		a <A HREF="intro.html#backslash">backslash</A>.  This <A HREF="intro.html#backslash">backslash</A> will be removed again by the |<A HREF="various.html#:!">:!</A>|
		command.
		The &quot;<A HREF="change.html#!">!</A>&quot; character will be escaped (again with a |<A HREF="#non-zero-arg">non-zero-arg</A>|
		{special}) when <A HREF="options.html#'shell'">'shell'</A> contains &quot;csh&quot; in the tail.  That is
		because for csh and tcsh &quot;<A HREF="change.html#!">!</A>&quot; is used for <A HREF="cmdline.html#history">history</A> replacement
		even when inside single <A HREF="quotes.html#quotes">quotes</A>.
		The <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> character is also escaped.  With a |<A HREF="#non-zero-arg">non-zero-arg</A>|
		{special} and <A HREF="options.html#'shell'">'shell'</A> containing &quot;csh&quot; in the tail it's
		escaped a second time.
		Example of use with a |<A HREF="various.html#:!">:!</A>| command:
<B>		    :exe '!dir ' . shellescape(expand('&lt;cfile&gt;'), 1)</B>
 		This results in a directory listing for the file under the
		cursor.  Example of use with YXXYsystem()|:
<B>		    :call system("chmod +w -- " . shellescape(expand("%")))</B>
 		See also |<A HREF="cmdline.html#::S">::S</A>|.



<A HREF="#shiftwidth()">shiftwidth()</A>						*<A NAME="shiftwidth()"></A><B>shiftwidth()</B>*
		Returns the effective value of <A HREF="options.html#'shiftwidth'">'shiftwidth'</A>. This is the
		<A HREF="options.html#'shiftwidth'">'shiftwidth'</A> value unless <A HREF="motion.html#it">it</A> is zero, in which <A HREF="change.html#case">case</A> <A HREF="motion.html#it">it</A> is the
		<A HREF="options.html#'tabstop'">'tabstop'</A> value.  This function was introduced with patch
		7.3.694 in 2012, everybody should have <A HREF="motion.html#it">it</A> by now.



simplify({filename})					*<A NAME="simplify()"></A><B>simplify()</B>*
		Simplify the file name <A HREF="motion.html#as">as</A> much <A HREF="motion.html#as">as</A> possible without <A HREF="change.html#changing">changing</A>
		the meaning.  Shortcuts (on <A HREF="os_win32.html#MS-Windows">MS-Windows</A>) or symbolic links (on
		<A HREF="os_unix.html#Unix">Unix</A>) are not resolved.  If the first path component in
		{filename} designates the current directory, this will be
		valid for the result <A HREF="motion.html#as">as</A> well.  A trailing path separator is
		not removed either.
		Example:
<B>			simplify("./dir/.././/file/") == "./file/"</B>
 		Note: The combination &quot;dir/..&quot; is only removed if &quot;dir&quot; is
		a searchable directory or does not exist.  On <A HREF="os_unix.html#Unix">Unix</A>, <A HREF="motion.html#it">it</A> is also
		removed when &quot;dir&quot; is a symbolic link within the same
		directory.  In order to resolve all the involved symbolic
		links before simplifying the path name, use |<A HREF="#resolve()">resolve()</A>|.



sin({expr})						*<A NAME="sin()"></A><B>sin()</B>*
		Return the sine of {expr}, measured in radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo sin(100)</B>
 			-0.506366
<B>			:echo sin(-4.01)</B>
 			0.763301
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		


sinh({expr})						*<A NAME="sinh()"></A><B>sinh()</B>*
		Return the hyperbolic sine of {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| in the range
		[-inf, inf].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo sinh(0.5)</B>
 			0.521095
<B>			:echo sinh(-0.9)</B>
 			-1.026517
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



sort({list} [, {func} [, {dict}]])			*<A NAME="sort()"></A><B>sort()</B>* *<A NAME="E702"></A><B>E702</B>*
		Sort the items in {list} in-place.  Returns {list}.
		
		If you want a <A HREF="#list">list</A> to remain unmodified make a copy first:
<B>			:let sortedlist = sort(copy(mylist))</B>

 		When {func} is omitted, is empty or zero, then <A HREF="#sort()">sort()</A> uses the
		<A HREF="#string">string</A> representation of each item to sort on.  Numbers sort
		after Strings, |<A HREF="#Lists">Lists</A>| after Numbers.  For <A HREF="change.html#sorting">sorting</A> text in the
		current buffer use |<A HREF="change.html#:sort">:sort</A>|.

		When {func} is given and <A HREF="motion.html#it">it</A> is '1' or '<A HREF="insert.html#i">i</A>' then <A HREF="change.html#case">case</A> is
		ignored.
		
		When {func} is given and <A HREF="motion.html#it">it</A> is '<A HREF="pattern.html#n">n</A>' then all items will be
		sorted numerical (Implementation detail: This uses the
		strtod() function to parse numbers, Strings, <A HREF="#Lists">Lists</A>, Dicts and
		Funcrefs will be considered <A HREF="motion.html#as">as</A> being 0).

		When {func} is given and <A HREF="motion.html#it">it</A> is '<A HREF="pattern.html#N">N</A>' then all items will be
		sorted numerical. This is like '<A HREF="pattern.html#n">n</A>' but a <A HREF="#string">string</A> containing
		digits will be used <A HREF="motion.html#as">as</A> the number they represent.

		When {func} is given and <A HREF="motion.html#it">it</A> is '<A HREF="motion.html#f">f</A>' then all items will be
		sorted numerical. All values must be a <A HREF="#Number">Number</A> or a <A HREF="#Float">Float</A>.

		When {func} is a |<A HREF="#Funcref">Funcref</A>| or a function name, this function
		is called to compare items.  The function is invoked with two
		items <A HREF="motion.html#as">as</A> argument and must return zero if they are equal, 1 or
		bigger if the first one sorts after the second one, -1 or
		smaller if the first one sorts before the second one.

		{dict} is for <A HREF="#functions">functions</A> with the &quot;<A HREF="#dict">dict</A>&quot; attribute.  It will be
		used to set the local variable &quot;<A HREF="#self">self</A>&quot;. |<A HREF="#Dictionary-function">Dictionary-function</A>|

		The sort is stable, items which compare equal (as number or <A HREF="motion.html#as">as</A>
		<A HREF="#string">string</A>) will keep their relative position. E.g., when <A HREF="change.html#sorting">sorting</A>
		on numbers, text strings will sort next to each other, in the
		same order <A HREF="motion.html#as">as</A> they were originally.

		Also see |<A HREF="#uniq()">uniq()</A>|.

		Example:
<B>			func MyCompare(i1, i2)</B>
<B>			   return a:i1 == a:i2 ? 0 : a:i1 &gt; a:i2 ? 1 : -1</B>
<B>			endfunc</B>
<B>			let sortedlist = sort(mylist, "MyCompare")</B>
 		A shorter compare version for this specific simple <A HREF="change.html#case">case</A>, which
		ignores overflow:
<B>			func MyCompare(i1, i2)</B>
<B>			   return a:i1 - a:i2</B>
<B>			endfunc</B>
 

							*<A NAME="soundfold()"></A><B>soundfold()</B>*
soundfold({word})
		Return the sound-folded equivalent of {word}.  Uses the first
		language in <A HREF="options.html#'spelllang'">'spelllang'</A> for the current <A HREF="windows.html#window">window</A> that supports
		soundfolding.  <A HREF="options.html#'spell'">'spell'</A> must be set.  When no sound <A HREF="fold.html#folding">folding</A> is
		possible the {word} is returned unmodified.
		This can be used for making spelling suggestions.  Note that
		the method can be quite slow.


							*<A NAME="spellbadword()"></A><B>spellbadword()</B>*
spellbadword([{sentence}])
		Without argument: The result is the badly spelled <A HREF="motion.html#word">word</A> under
		or after the cursor.  The cursor is moved to the start of the
		bad <A HREF="motion.html#word">word</A>.  When no bad <A HREF="motion.html#word">word</A> is found in the cursor line the
		result is an empty <A HREF="#string">string</A> and the cursor doesn't move.

		With argument: The result is the first <A HREF="motion.html#word">word</A> in {sentence} that
		is badly spelled.  If there are no spelling mistakes the
		result is an empty <A HREF="#string">string</A>.

		The return value is a <A HREF="#list">list</A> with two items:
		- The badly spelled <A HREF="motion.html#word">word</A> or an empty <A HREF="#string">string</A>.
		- The type of the spelling error:
			&quot;bad&quot;		spelling mistake
			&quot;rare&quot;		rare <A HREF="motion.html#word">word</A>
			&quot;local&quot;		<A HREF="motion.html#word">word</A> only valid in another region
			&quot;caps&quot;		<A HREF="motion.html#word">word</A> should start with Capital
		Example:
<B>			echo spellbadword("the quik brown fox")</B>
<B><FONT COLOR="PURPLE"> 			['quik', 'bad'] </FONT></B>

		The spelling information for the current <A HREF="windows.html#window">window</A> is used.  The
		<A HREF="options.html#'spell'">'spell'</A> option must be set and the value of <A HREF="options.html#'spelllang'">'spelllang'</A> is
		used.


							*<A NAME="spellsuggest()"></A><B>spellsuggest()</B>*
spellsuggest({word} [, {max} [, {capital}]])
		Return a |<A HREF="#List">List</A>| with spelling suggestions to replace {word}.
		When {max} is given up to this number of suggestions are
		returned.  Otherwise up to 25 suggestions are returned.

		When the {capital} argument is given and it's non-zero only
		suggestions with a leading capital will be given.  Use this
		after a match with <A HREF="options.html#'spellcapcheck'">'spellcapcheck'</A>.

		{word} can be a badly spelled <A HREF="motion.html#word">word</A> followed by other text.
		This allows for joining two words that were split.  The
		suggestions also include the following text, thus you can
		replace a line.

		{word} may also be a good <A HREF="motion.html#word">word</A>.  Similar words will then be
		returned.  {word} itself is not included in the suggestions,
		although <A HREF="motion.html#it">it</A> may appear capitalized.

		The spelling information for the current <A HREF="windows.html#window">window</A> is used.  The
		<A HREF="options.html#'spell'">'spell'</A> option must be set and the values of <A HREF="options.html#'spelllang'">'spelllang'</A> and
		<A HREF="options.html#'spellsuggest'">'spellsuggest'</A> are used.



split({expr} [, {pattern} [, {keepempty}]])			*<A NAME="split()"></A><B>split()</B>*
		Make a |<A HREF="#List">List</A>| out of {expr}.  When {pattern} is omitted or
		empty each white-separated sequence of characters becomes an
		item.
		Otherwise the <A HREF="#string">string</A> is split where {pattern} matches,
		removing the matched characters. <A HREF="options.html#'ignorecase'">'ignorecase'</A> is not used
		here, add \c to ignore <A HREF="change.html#case">case</A>. |<A HREF="pattern.html#/\c">/\c</A>|
		When the first or last item is empty <A HREF="motion.html#it">it</A> is omitted, unless the
		{keepempty} argument is given and it's non-zero.
		Other empty items are kept when {pattern} matches at least one
		character or when {keepempty} is non-zero.
		Example:
<B>			:let words = split(getline('.'), '\W\+')</B>
 		To split a <A HREF="#string">string</A> in individual characters:
<B>			:for c in split(mystring, '\zs')</B>
 		If you want to keep the separator you can also use '\zs' at
		the end of the <A HREF="pattern.html#pattern">pattern</A>:
<B>			:echo split('abc:def:ghi', ':\zs')</B>
<B><FONT COLOR="PURPLE"> 			['abc:', 'def:', 'ghi'] </FONT></B>
		Splitting a table where the first element can be empty:
<B>			:let items = split(line, ':', 1)</B>
 		The opposite function is |<A HREF="#join()">join()</A>|.



sqrt({expr})						*<A NAME="sqrt()"></A><B>sqrt()</B>*
		Return the non-negative square root of <A HREF="#Float">Float</A> {expr} <A HREF="motion.html#as">as</A> a
		|<A HREF="#Float">Float</A>|.
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.  When {expr}
		is negative the result is NaN (Not a <A HREF="#Number">Number</A>).
		Examples:
<B>			:echo sqrt(100)</B>
 			10.0
<B>			:echo sqrt(-4.01)</B>
 			nan
		&quot;nan&quot; may be different, <A HREF="motion.html#it">it</A> depends on system libraries.
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		


str2float( {expr})					*<A NAME="str2float()"></A><B>str2float()</B>*
		Convert <A HREF="#String">String</A> {expr} to a <A HREF="#Float">Float</A>.  This mostly works the same
		<A HREF="motion.html#as">as</A> when using a floating point number in an <A HREF="#expression">expression</A>, see
		|<A HREF="#floating-point-format">floating-point-format</A>|.  But it's a bit more permissive.
		E.g., &quot;1e40&quot; is accepted, while in an <A HREF="#expression">expression</A> you need to
		write &quot;1.0e40&quot;.
		Text after the number is silently ignored.
		The decimal point is always '<A HREF="repeat.html#.">.</A>', no matter what the <A HREF="mbyte.html#locale">locale</A> is
		set to.  A comma ends the number: &quot;12,345.67&quot; is converted to
		12.0.  You can strip out thousands separators with
		YXXYsubstitute()|:
<B>			let f = str2float(substitute(text, ',', '', 'g'))</B>
 		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



str2nr( {expr} [, {base}])				*<A NAME="str2nr()"></A><B>str2nr()</B>*
		Convert <A HREF="#string">string</A> {expr} to a number.
		{base} is the conversion base, <A HREF="motion.html#it">it</A> can be 2, 8, 10 or 16.
		When {base} is omitted base 10 is used.  This also means that
		a leading zero doesn't cause <A HREF="#octal">octal</A> conversion to be used, <A HREF="motion.html#as">as</A>
		with the default <A HREF="#String">String</A> to <A HREF="#Number">Number</A> conversion.
		When {base} is 16 a leading &quot;0x&quot; or &quot;0X&quot; is ignored.  With a
		different base the result will be zero.  Similarly, when
		{base} is 8 a leading &quot;<A HREF="motion.html#0">0</A>&quot; is ignored, and when {base} is 2 a
		leading &quot;0b&quot; or &quot;0B&quot; is ignored.
		Text after the number is silently ignored.



strchars({expr} [, {skipcc}])					*<A NAME="strchars()"></A><B>strchars()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the number of characters
		in <A HREF="#String">String</A> {expr}.
		When {skipcc} is omitted or zero, composing characters are
		counted separately.
		When {skipcc} set to 1, Composing characters are ignored.
		Also see |<A HREF="#strlen()">strlen()</A>|, |<A HREF="#strdisplaywidth()">strdisplaywidth()</A>| and |<A HREF="#strwidth()">strwidth()</A>|.

		
		{skipcc} is only available after 7.4.755.  For backward
		compatibility, you can define a wrapper function:
<B>		    if has("patch-7.4.755")</B>
<B>		      function s:strchars(str, skipcc)</B>
<B>			return strchars(a:str, a:skipcc)</B>
<B>		      endfunction</B>
<B>		    else</B>
<B>		      function s:strchars(str, skipcc)</B>
<B>			if a:skipcc</B>
<B>			  return strlen(substitute(a:str, ".", "x", "g"))</B>
<B>			else</B>
<B>			  return strchars(a:str)</B>
<B>			endif</B>
<B>		      endfunction</B>
<B>		    endif</B>
 


strdisplaywidth({expr}[, {col}])			*<A NAME="strdisplaywidth()"></A><B>strdisplaywidth()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the number of display cells
		<A HREF="#String">String</A> {expr} occupies on the screen when <A HREF="motion.html#it">it</A> starts at {col}.
		When {col} is omitted zero is used.  Otherwise <A HREF="motion.html#it">it</A> is the
		screen column where to start.  This matters for <A HREF="intro.html#Tab">Tab</A>
		characters.
		The option settings of the current <A HREF="windows.html#window">window</A> are used.  This
		matters for anything that's displayed differently, such <A HREF="motion.html#as">as</A>
		<A HREF="options.html#'tabstop'">'tabstop'</A> and <A HREF="options.html#'display'">'display'</A>.
		When {expr} contains characters with East Asian Width Class
		Ambiguous, this function's return value depends on <A HREF="options.html#'ambiwidth'">'ambiwidth'</A>.
		Also see |<A HREF="#strlen()">strlen()</A>|, |<A HREF="#strwidth()">strwidth()</A>| and |<A HREF="#strchars()">strchars()</A>|.


strftime({format} [, {time}])				*<A NAME="strftime()"></A><B>strftime()</B>*
		The result is a <A HREF="#String">String</A>, which is a formatted date and time, <A HREF="motion.html#as">as</A>
		specified by the {format} <A HREF="#string">string</A>.  The given {time} is used,
		or the current time if no time is given.  The accepted
		{format} depends on your system, thus this is not portable!
		See the manual page of the C function <A HREF="#strftime()">strftime()</A> for the
		format.  The maximum length of the result is 80 characters.
		See also |<A HREF="#localtime()">localtime()</A>| and |<A HREF="#getftime()">getftime()</A>|.
		The language can be changed with the |<A HREF="mlang.html#:language">:language</A>| command.
		Examples:
<B>		  :echo strftime("%c")		   Sun Apr 27 11:49:23 1997</B>
<B>		  :echo strftime("%Y %b %d %X")	   1997 Apr 27 11:53:25</B>
<B>		  :echo strftime("%y%m%d %T")	   970427 11:53:55</B>
<B>		  :echo strftime("%H:%M")	   11:55</B>
<B>		  :echo strftime("%c", getftime("file.c"))</B>
<B>						   Show mod time of file.c.</B>
 		Not available on all systems.  To check use:
<B>			:if exists("*strftime")</B>


stridx({haystack}, {needle} [, {start}])		*<A NAME="stridx()"></A><B>stridx()</B>*
		The result is a <A HREF="#Number">Number</A>, which gives the byte index in
		{haystack} of the first occurrence of the <A HREF="#String">String</A> {needle}.
		If {start} is specified, the search starts at index {start}.
		This can be used to find a second match:
<B>			:let colon1 = stridx(line, ":")</B>
<B>			:let colon2 = stridx(line, ":", colon1 + 1)</B>
 		The search is done case-sensitive.
		For <A HREF="pattern.html#pattern">pattern</A> searches use |<A HREF="#match()">match()</A>|.
		-1 is returned if the {needle} does not occur in {haystack}.
		See also |<A HREF="#strridx()">strridx()</A>|.
		Examples:
<B>		  :echo stridx("An Example", "Example")	     3</B>
<B>		  :echo stridx("Starting point", "Start")    0</B>
<B>		  :echo stridx("Starting point", "start")   -1</B>

 						*<A NAME="strstr()"></A><B>strstr()</B>* *<A NAME="strchr()"></A><B>strchr()</B>*
		<A HREF="#stridx()">stridx()</A> works similar to the C function <A HREF="#strstr()">strstr()</A>.  When used
		with a single character <A HREF="motion.html#it">it</A> works similar to <A HREF="#strchr()">strchr()</A>.


							*<A NAME="string()"></A><B>string()</B>*
string({expr})	Return {expr} converted to a <A HREF="#String">String</A>.  If {expr} is a <A HREF="#Number">Number</A>,
		<A HREF="#Float">Float</A>, <A HREF="#String">String</A> or a composition of them, then the result can be
		parsed back with |<A HREF="#eval()">eval()</A>|.
<B><FONT COLOR="PURPLE">			{expr} type	result </FONT></B>
			<A HREF="#String">String</A>		'<A HREF="#string">string</A>' (single <A HREF="quotes.html#quotes">quotes</A> are doubled)
			<A HREF="#Number">Number</A>		123
			<A HREF="#Float">Float</A>		123.123456 or 1.123456e8
			<A HREF="#Funcref">Funcref</A>		function('name')
			<A HREF="#List">List</A>		[item, item]
			<A HREF="#Dictionary">Dictionary</A>	{key: value, key: value}

		When a <A HREF="#List">List</A> or <A HREF="#Dictionary">Dictionary</A> has a recursive reference <A HREF="motion.html#it">it</A> is
		replaced by &quot;[...]&quot; or &quot;{...}&quot;.  Using <A HREF="#eval()">eval()</A> on the result
		will then fail.

		Also see |<A HREF="#strtrans()">strtrans()</A>|.


							*<A NAME="strlen()"></A><B>strlen()</B>*
strlen({expr})	The result is a <A HREF="#Number">Number</A>, which is the length of the <A HREF="#String">String</A>
		{expr} in bytes.
		If the argument is a <A HREF="#Number">Number</A> <A HREF="motion.html#it">it</A> is first converted to a <A HREF="#String">String</A>.
		For other types an error is given.
		If you want to <A HREF="intro.html#count">count</A> the number of <A HREF="mbyte.html#multi-byte">multi-byte</A> characters use
		|<A HREF="#strchars()">strchars()</A>|.
		Also see |<A HREF="#len()">len()</A>|, |<A HREF="#strdisplaywidth()">strdisplaywidth()</A>| and |<A HREF="#strwidth()">strwidth()</A>|.


strpart({src}, {start}[, {len}])			*<A NAME="strpart()"></A><B>strpart()</B>*
		The result is a <A HREF="#String">String</A>, which is part of {src}, starting from
		byte {start}, with the byte length {len}.
		When non-existing bytes are included, this doesn't result in
		an error, the bytes are simply omitted.
		If {len} is missing, the copy continues from {start} till the
		end of the {src}.
<B>			strpart("abcdefg", 3, 2)    == "de"</B>
<B>			strpart("abcdefg", -2, 4)   == "ab"</B>
<B>			strpart("abcdefg", 5, 4)    == "fg"</B>
<B>			strpart("abcdefg", 3)	    == "defg"</B>
 		Note: To get the first character, {start} must be 0.  For
		example, to get three bytes under and after the cursor:
<B>			strpart(getline("."), col(".") - 1, 3)</B>
 

strridx({haystack}, {needle} [, {start}])			*<A NAME="strridx()"></A><B>strridx()</B>*
		The result is a <A HREF="#Number">Number</A>, which gives the byte index in
		{haystack} of the last occurrence of the <A HREF="#String">String</A> {needle}.
		When {start} is specified, matches beyond this index are
		ignored.  This can be used to find a match before a previous
		match:
<B>			:let lastcomma = strridx(line, ",")</B>
<B>			:let comma2 = strridx(line, ",", lastcomma - 1)</B>
 		The search is done case-sensitive.
		For <A HREF="pattern.html#pattern">pattern</A> searches use |<A HREF="#match()">match()</A>|.
		-1 is returned if the {needle} does not occur in {haystack}.
		If the {needle} is empty the length of {haystack} is returned.
		See also |<A HREF="#stridx()">stridx()</A>|.  Examples:
<B>		  :echo strridx("an angry armadillo", "an")	     3</B>

 							*<A NAME="strrchr()"></A><B>strrchr()</B>*
		When used with a single character <A HREF="motion.html#it">it</A> works similar to the C
		function <A HREF="#strrchr()">strrchr()</A>.


strtrans({expr})					*<A NAME="strtrans()"></A><B>strtrans()</B>*
		The result is a <A HREF="#String">String</A>, which is {expr} with all unprintable
		characters translated into printable characters |<A HREF="options.html#'isprint'">'isprint'</A>|.
		Like they are shown in a <A HREF="windows.html#window">window</A>.  Example:
<B>			echo strtrans(@a)</B>
 		This displays a newline in <A HREF="sponsor.html#register">register</A> a <A HREF="motion.html#as">as</A> &quot;^@&quot; instead of
		starting a new line.


strwidth({expr})					*<A NAME="strwidth()"></A><B>strwidth()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the number of display cells
		<A HREF="#String">String</A> {expr} occupies.  A <A HREF="intro.html#Tab">Tab</A> character is counted <A HREF="motion.html#as">as</A> one
		cell, alternatively use |<A HREF="#strdisplaywidth()">strdisplaywidth()</A>|.
		When {expr} contains characters with East Asian Width Class
		Ambiguous, this function's return value depends on <A HREF="options.html#'ambiwidth'">'ambiwidth'</A>.
		Also see |<A HREF="#strlen()">strlen()</A>|, |<A HREF="#strdisplaywidth()">strdisplaywidth()</A>| and |<A HREF="#strchars()">strchars()</A>|.


submatch({nr}[, {list}])				*<A NAME="submatch()"></A><B>submatch()</B>*
		Only for an <A HREF="#expression">expression</A> in a |<A HREF="change.html#:substitute">:substitute</A>| command or
		<A HREF="#substitute()">substitute()</A> function.
		Returns the {nr}'th submatch of the matched text.  When {nr}
		is 0 the whole matched text is returned.
		Note that a NL in the <A HREF="#string">string</A> can stand for a line break of a
		multi-line match or a NUL character in the text.
		Also see |<A HREF="change.html#sub-replace-expression">sub-replace-expression</A>|.

		If {list} is present and non-zero then <A HREF="#submatch()">submatch()</A> returns 
		a <A HREF="#list">list</A> of strings, similar to |<A HREF="#getline()">getline()</A>| with two arguments. 
		NL characters in the text represent NUL characters in the
		text.
		Only returns more than one item for |<A HREF="change.html#:substitute">:substitute</A>|, inside
		|<A HREF="#substitute()">substitute()</A>| this <A HREF="#list">list</A> will always contain one or zero
		items, since there are no real line breaks.

		Example:
<B>			:s/\d\+/\=submatch(0) + 1/</B>
 		This finds the first number in the line and adds one to <A HREF="motion.html#it">it</A>.
		A line break is included <A HREF="motion.html#as">as</A> a newline character.


substitute({expr}, <A HREF="autocmd.html#{pat}">{pat}</A>, {sub}, {flags})		*<A NAME="substitute()"></A><B>substitute()</B>*
		The result is a <A HREF="#String">String</A>, which is a copy of {expr}, in which
		the first match of <A HREF="autocmd.html#{pat}">{pat}</A> is replaced with {sub}.
		When {flags} is &quot;<A HREF="index.html#g">g</A>&quot;, all matches of <A HREF="autocmd.html#{pat}">{pat}</A> in {expr} are
		replaced.  Otherwise {flags} should be &quot;&quot;.
		
		This works like the &quot;<A HREF="change.html#:substitute">:substitute</A>&quot; command (without any flags).
		But the matching with <A HREF="autocmd.html#{pat}">{pat}</A> is always done like the <A HREF="options.html#'magic'">'magic'</A>
		option is set and <A HREF="options.html#'cpoptions'">'cpoptions'</A> is empty (to make scripts
		portable).  <A HREF="options.html#'ignorecase'">'ignorecase'</A> is still relevant, use |<A HREF="pattern.html#/\c">/\c</A>| or |<A HREF="pattern.html#/\C">/\C</A>|
		if you want to ignore or match <A HREF="change.html#case">case</A> and ignore <A HREF="options.html#'ignorecase'">'ignorecase'</A>.
		<A HREF="options.html#'smartcase'">'smartcase'</A> is not used.  See |<A HREF="#string-match">string-match</A>| for how <A HREF="autocmd.html#{pat}">{pat}</A> is
		used.

		A &quot;<A HREF="change.html#~">~</A>&quot; in {sub} is not replaced with the previous {sub}.
		Note that some codes in {sub} have a special meaning
		|<A HREF="change.html#sub-replace-special">sub-replace-special</A>|.	For example, to replace something with
		&quot;\n&quot; (two characters), use &quot;\\\\n&quot; or '\\n'.

		When <A HREF="autocmd.html#{pat}">{pat}</A> does not match in {expr}, {expr} is returned
		unmodified.

		Example:
<B>			:let &amp;path = substitute(&amp;path, ",\\=[^,]*$", "", "")</B>
 		This removes the last component of the <A HREF="options.html#'path'">'path'</A> option.
<B>			:echo substitute("testing", ".*", "\\U\\0", "")</B>
 		results in &quot;TESTING&quot;.

		When {sub} starts with &quot;\=&quot;, the remainder is interpreted <A HREF="motion.html#as">as</A>
		an expression. See |<A HREF="change.html#sub-replace-expression">sub-replace-expression</A>|.  Example:
<B>			:echo substitute(s, '%\(\x\x\)',</B>
<B>			   \ '\=nr2char("0x" . submatch(1))', 'g')</B>


synID({lnum}, {col}, {trans})				*<A NAME="synID()"></A><B>synID()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the <A HREF="syntax.html#syntax">syntax</A> ID at the position
		{lnum} and {col} in the current <A HREF="windows.html#window">window</A>.
		The <A HREF="syntax.html#syntax">syntax</A> ID can be used with |<A HREF="#synIDattr()">synIDattr()</A>| and
		|<A HREF="#synIDtrans()">synIDtrans()</A>| to obtain <A HREF="syntax.html#syntax">syntax</A> information about text.

		{col} is 1 for the leftmost column, {lnum} is 1 for the first
		line.  <A HREF="options.html#'synmaxcol'">'synmaxcol'</A> applies, in a longer line zero is returned.
		Note that when the position is after the last character,
		that's where the cursor can be in <A HREF="insert.html#Insert">Insert</A> mode, <A HREF="#synID()">synID()</A> returns
		zero.

		When {trans} is non-zero, transparent items are reduced to the
		item that they reveal.	This is useful when wanting to know
		the effective color.  When {trans} is zero, the transparent
		item is returned.  This is useful when wanting to know which
		<A HREF="syntax.html#syntax">syntax</A> item is effective (e.g. inside parens).
		Warning: This function can be very slow.  Best speed is
		obtained by going through the file in forward direction.

		Example (echoes the name of the <A HREF="syntax.html#syntax">syntax</A> item under the cursor):
<B>			:echo synIDattr(synID(line("."), col("."), 1), "name")</B>
 


synIDattr({synID}, {what} [, {mode}])			*<A NAME="synIDattr()"></A><B>synIDattr()</B>*
		The result is a <A HREF="#String">String</A>, which is the {what} attribute of
		<A HREF="syntax.html#syntax">syntax</A> ID {synID}.  This can be used to obtain information
		about a <A HREF="syntax.html#syntax">syntax</A> item.
		{mode} can be &quot;<A HREF="gui.html#gui">gui</A>&quot;, &quot;cterm&quot; or &quot;term&quot;, to get the attributes
		for that mode.	When {mode} is omitted, or an invalid value is
		used, the attributes for the currently active highlighting are
		used (GUI, cterm or term).
		Use <A HREF="#synIDtrans()">synIDtrans()</A> to follow linked highlight groups.
		{what}		result
		&quot;name&quot;		the name of the <A HREF="syntax.html#syntax">syntax</A> item
		&quot;fg&quot;		foreground color (GUI: color name used to set
				the color, cterm: color number <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A>,
				term: empty <A HREF="#string">string</A>)
		&quot;bg&quot;		background color (as with &quot;fg&quot;)
		&quot;font&quot;		font name (only available in the <A HREF="gui.html#GUI">GUI</A>)
				|<A HREF="syntax.html#highlight-font">highlight-font</A>|
		&quot;sp&quot;		special color (as with &quot;fg&quot;) |<A HREF="syntax.html#highlight-guisp">highlight-guisp</A>|
		&quot;fg#&quot;		like &quot;fg&quot;, but for the <A HREF="gui.html#GUI">GUI</A> and the <A HREF="gui.html#GUI">GUI</A> is
				running the name in &quot;#RRGGBB&quot; form
		&quot;bg#&quot;		like &quot;fg#&quot; for &quot;bg&quot;
		&quot;sp#&quot;		like &quot;fg#&quot; for &quot;sp&quot;
		&quot;<A HREF="syntax.html#bold">bold</A>&quot;		&quot;1&quot; if <A HREF="syntax.html#bold">bold</A>
		&quot;<A HREF="syntax.html#italic">italic</A>&quot;	&quot;1&quot; if <A HREF="syntax.html#italic">italic</A>
		&quot;reverse&quot;	&quot;1&quot; if reverse
		&quot;<A HREF="syntax.html#inverse">inverse</A>&quot;	&quot;1&quot; if <A HREF="syntax.html#inverse">inverse</A> (= reverse)
		&quot;<A HREF="syntax.html#standout">standout</A>&quot;	&quot;1&quot; if <A HREF="syntax.html#standout">standout</A>
		&quot;<A HREF="syntax.html#underline">underline</A>&quot;	&quot;1&quot; if underlined
		&quot;<A HREF="syntax.html#undercurl">undercurl</A>&quot;	&quot;1&quot; if undercurled

		Example (echoes the color of the <A HREF="syntax.html#syntax">syntax</A> item under the
		cursor):
<B>	:echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")</B>
 

synIDtrans({synID})					*<A NAME="synIDtrans()"></A><B>synIDtrans()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the translated <A HREF="syntax.html#syntax">syntax</A> ID of
		{synID}.  This is the <A HREF="syntax.html#syntax">syntax</A> group ID of what is being used to
		highlight the character.  Highlight links given with
		&quot;<A HREF="syntax.html#:highlight">:highlight</A> link&quot; are followed.


synconcealed({lnum}, {col})				*<A NAME="synconcealed()"></A><B>synconcealed()</B>*
		The result is a <A HREF="#List">List</A>. The first item in the <A HREF="#list">list</A> is 0 if the
		character at the position {lnum} and {col} is not part of a
		concealable region, 1 if <A HREF="motion.html#it">it</A> is. The second item in the <A HREF="#list">list</A> is
		a <A HREF="#string">string</A>. If the first item is 1, the second item contains the
		text which will be displayed in place of the concealed text,
		depending on the current setting of <A HREF="options.html#'conceallevel'">'conceallevel'</A>. The third
		and final item in the <A HREF="#list">list</A> is a unique number representing the
		specific <A HREF="syntax.html#syntax">syntax</A> region matched. This allows detection of the
		beginning of a new concealable region if there are two
		consecutive regions with the same replacement character.
		For an example use see $VIMRUNTIME/syntax/2html.vim .



synstack({lnum}, {col})					*<A NAME="synstack()"></A><B>synstack()</B>*
		Return a |<A HREF="#List">List</A>|, which is the stack of <A HREF="syntax.html#syntax">syntax</A> items at the
		position {lnum} and {col} in the current <A HREF="windows.html#window">window</A>.  Each item in
		the <A HREF="#List">List</A> is an ID like what |<A HREF="#synID()">synID()</A>| returns.
		The first item in the <A HREF="#List">List</A> is the outer region, following are
		items contained in that one.  The last one is what |<A HREF="#synID()">synID()</A>|
		returns, unless not the whole item is highlighted or <A HREF="motion.html#it">it</A> is a
		transparent item.
		This function is useful for debugging a <A HREF="syntax.html#syntax">syntax</A> file.
		Example that shows the <A HREF="syntax.html#syntax">syntax</A> stack under the cursor:
<B>			for id in synstack(line("."), col("."))</B>
<B>			   echo synIDattr(id, "name")</B>
<B>			endfor</B>
 		When the position specified with {lnum} and {col} is invalid
		nothing is returned.  The position just after the last
		character in a line and the first column in an empty line are
		valid positions.


system({expr} [, {input}])				*<A NAME="system()"></A><B>system()</B>* *<A NAME="E677"></A><B>E677</B>*
		Get the output of the shell command {expr} <A HREF="motion.html#as">as</A> a <A HREF="#string">string</A>.  See
		|<A HREF="#systemlist()">systemlist()</A>| to get the output <A HREF="motion.html#as">as</A> a <A HREF="#List">List</A>.

		When {input} is given and is a <A HREF="#string">string</A> this <A HREF="#string">string</A> is written 
		to a file and passed <A HREF="motion.html#as">as</A> stdin to the command.  The <A HREF="#string">string</A> is 
		written as-is, you need to take care of using the correct line 
		separators yourself.
		If {input} is given and is a |<A HREF="#List">List</A>| <A HREF="motion.html#it">it</A> is written to the file
		in a way |<A HREF="#writefile()">writefile()</A>| does with {binary} set to &quot;<A HREF="motion.html#b">b</A>&quot; (i.e.
		with a newline between each <A HREF="#list">list</A> item with newlines inside
		<A HREF="#list">list</A> items converted to NULs).  
		Pipes are not used.

		When prepended by |<A HREF="various.html#:silent">:silent</A>| the shell will not be set to
		cooked mode.  This is meant to be used for commands that <A HREF="diff.html#do">do</A>
		not need the user to type.  It avoids stray characters showing
		up on the screen which require |<A HREF="various.html#CTRL-L">CTRL-L</A>| to remove.
<B>			:silent let f = system('ls *.vim')</B>
 
		Note: Use |<A HREF="#shellescape()">shellescape()</A>| or |<A HREF="cmdline.html#::S">::S</A>| with |<A HREF="#expand()">expand()</A>| or 
		|<A HREF="#fnamemodify()">fnamemodify()</A>| to <A HREF="intro.html#escape">escape</A> special characters in a command 
		argument.  Newlines in {expr} may cause the command to fail.  
		The characters in <A HREF="options.html#'shellquote'">'shellquote'</A> and <A HREF="options.html#'shellxquote'">'shellxquote'</A> may also 
		cause trouble.
		This is not to be used for interactive commands.

		The result is a <A HREF="#String">String</A>.  Example:
<B>		    :let files = system("ls " .  shellescape(expand('%:h')))</B>
<B>		    :let files = system('ls ' . expand('%:h:S'))</B>

 		To make the result more system-independent, the shell output
		is filtered to replace <A HREF="motion.html#&lt;CR&gt;">&lt;CR&gt;</A> with <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> for <A HREF="os_mac.html#Macintosh">Macintosh</A>, and
		&lt;CR&gt;&lt;NL&gt; with <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A> for DOS-like systems.
		To avoid the <A HREF="#string">string</A> being truncated at a NUL, all NUL
		characters are replaced with SOH (0x01).

		The command executed is constructed using several <A HREF="options.html#options">options</A>:
	<A HREF="options.html#'shell'">'shell'</A> <A HREF="options.html#'shellcmdflag'">'shellcmdflag'</A> <A HREF="options.html#'shellxquote'">'shellxquote'</A> {expr} <A HREF="options.html#'shellredir'">'shellredir'</A> {tmp} <A HREF="options.html#'shellxquote'">'shellxquote'</A>
		({tmp} is an automatically generated file name).
		For <A HREF="os_unix.html#Unix">Unix</A> and <A HREF="os_os2.html#OS/2">OS/2</A> braces are put around {expr} to allow for
		concatenated commands.

		The command will be executed in &quot;cooked&quot; mode, so that a
		<A HREF="pattern.html#CTRL-C">CTRL-C</A> will interrupt the command (on <A HREF="os_unix.html#Unix">Unix</A> at least).

		The resulting error code can be found in |<A HREF="#v:shell_error">v:shell_error</A>|.
		This function will fail in |<A HREF="starting.html#restricted-mode">restricted-mode</A>|.

		Note that any wrong value in the <A HREF="options.html#options">options</A> mentioned above may
		make the function fail.  It has also been reported to fail
		when using a security agent application.
		Unlike &quot;<A HREF="various.html#:!cmd">:!cmd</A>&quot; there is no automatic check for changed files.
		Use |<A HREF="editing.html#:checktime">:checktime</A>| to force a check.



systemlist({expr} [, {input}])				*<A NAME="systemlist()"></A><B>systemlist()</B>*
		Same <A HREF="motion.html#as">as</A> |<A HREF="#system()">system()</A>|, but returns a |<A HREF="#List">List</A>| with lines (parts of 
		output separated by NL) with NULs transformed into NLs. Output 
		is the same <A HREF="motion.html#as">as</A> |<A HREF="#readfile()">readfile()</A>| will output with {binary} argument 
		set to &quot;<A HREF="motion.html#b">b</A>&quot;.

		Returns an empty <A HREF="#string">string</A> on error.



tabpagebuflist([{arg}])					*<A NAME="tabpagebuflist()"></A><B>tabpagebuflist()</B>*
		The result is a |<A HREF="#List">List</A>|, where each item is the number of the
		buffer associated with each <A HREF="windows.html#window">window</A> in the current <A HREF="intro.html#tab">tab</A> page.
		{arg} specifies the number of <A HREF="intro.html#tab">tab</A> page to be used.  When
		omitted the current <A HREF="intro.html#tab">tab</A> page is used.
		When {arg} is invalid the number zero is returned.
		To get a <A HREF="#list">list</A> of all <A HREF="windows.html#buffers">buffers</A> in all tabs use this:
<B>			let buflist = []</B>
<B>			for i in range(tabpagenr('$'))</B>
<B>			   call extend(buflist, tabpagebuflist(i + 1))</B>
<B>			endfor</B>
 		Note that a buffer may appear in more than one <A HREF="windows.html#window">window</A>.



tabpagenr([{arg}])					*<A NAME="tabpagenr()"></A><B>tabpagenr()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the number of the current
		<A HREF="intro.html#tab">tab</A> page.  The first <A HREF="intro.html#tab">tab</A> page has number 1.
		When the optional argument is &quot;<A HREF="motion.html#$">$</A>&quot;, the number of the last <A HREF="intro.html#tab">tab</A>
		page is returned (the <A HREF="intro.html#tab">tab</A> page <A HREF="intro.html#count">count</A>).
		The number can be used with the |<A HREF="tabpage.html#:tab">:tab</A>| command.



tabpagewinnr({tabarg} [, {arg}])			*<A NAME="tabpagewinnr()"></A><B>tabpagewinnr()</B>*
		Like |<A HREF="#winnr()">winnr()</A>| but for <A HREF="intro.html#tab">tab</A> page {tabarg}.
		{tabarg} specifies the number of <A HREF="intro.html#tab">tab</A> page to be used.
		{arg} is used like with YXXYwinnr()|:
		- When omitted the current <A HREF="windows.html#window">window</A> number is returned.  This is
		  the <A HREF="windows.html#window">window</A> which will be used when going to this <A HREF="intro.html#tab">tab</A> page.
		- When &quot;<A HREF="motion.html#$">$</A>&quot; the number of <A HREF="windows.html#windows">windows</A> is returned.
		- When &quot;<A HREF="pattern.html##">#</A>&quot; the previous <A HREF="windows.html#window">window</A> nr is returned.
		Useful examples:
<B>		    tabpagewinnr(1)	    " current window of tab page 1</B>
<B>		    tabpagewinnr(4, '$')    " number of windows in tab page 4</B>
 		When {tabarg} is invalid zero is returned.


							*<A NAME="tagfiles()"></A><B>tagfiles()</B>*
<A HREF="#tagfiles()">tagfiles()</A>	Returns a |<A HREF="#List">List</A>| with the file names used to search for <A HREF="tagsrch.html#tags">tags</A>
		for the current buffer.  This is the <A HREF="options.html#'tags'">'tags'</A> option expanded.



taglist({expr})							*<A NAME="taglist()"></A><B>taglist()</B>*
		Returns a <A HREF="#list">list</A> of <A HREF="tagsrch.html#tags">tags</A> matching the regular <A HREF="#expression">expression</A> {expr}.
		Each <A HREF="#list">list</A> item is a dictionary with at least the following
		entries:
			name		Name of the <A HREF="tagsrch.html#tag">tag</A>.
			filename	Name of the file where the <A HREF="tagsrch.html#tag">tag</A> is
					defined.  It is either relative to the
					current directory or a full path.
			cmd		<A HREF="intro.html#Ex">Ex</A> command used to locate the <A HREF="tagsrch.html#tag">tag</A> in
					the file.
			kind		Type of the <A HREF="tagsrch.html#tag">tag</A>.  The value for this
					entry depends on the language specific
					kind values.  Only available when
					using a <A HREF="tagsrch.html#tags">tags</A> file generated by
					Exuberant <A HREF="tagsrch.html#ctags">ctags</A> or hdrtag.
			static		A file specific <A HREF="tagsrch.html#tag">tag</A>.  Refer to
					|<A HREF="tagsrch.html#static-tag">static-tag</A>| for more information.
		More entries may be present, depending on the content of the
		<A HREF="tagsrch.html#tags">tags</A> file: access, implementation, inherits and signature.
		Refer to the <A HREF="tagsrch.html#ctags">ctags</A> documentation for information about these
		fields.  For C code the fields &quot;struct&quot;, &quot;class&quot; and &quot;enum&quot;
		may appear, they give the name of the entity the <A HREF="tagsrch.html#tag">tag</A> is
		contained in.

		The ex-command 'cmd' can be either an <A HREF="starting.html#ex">ex</A> search <A HREF="pattern.html#pattern">pattern</A>, a
		line number or a line number followed by a byte number.

		If there are no matching <A HREF="tagsrch.html#tags">tags</A>, then an empty <A HREF="#list">list</A> is returned.

		To get an exact <A HREF="tagsrch.html#tag">tag</A> match, the anchors '<A HREF="motion.html#^">^</A>' and '<A HREF="motion.html#$">$</A>' should be
		used in {expr}.  This also make the function work faster.
		Refer to |<A HREF="tagsrch.html#tag-regexp">tag-regexp</A>| for more information about the tag
		search regular <A HREF="#expression">expression</A> <A HREF="pattern.html#pattern">pattern</A>.

		Refer to |<A HREF="options.html#'tags'">'tags'</A>| for information about how the tags file is
		located by Vim. Refer to |<A HREF="tagsrch.html#tags-file-format">tags-file-format</A>| for the format of
		the <A HREF="tagsrch.html#tags">tags</A> file generated by the different <A HREF="tagsrch.html#ctags">ctags</A> tools.


<A HREF="#tempname()">tempname()</A>					*<A NAME="tempname()"></A><B>tempname()</B>* *<A NAME="temp-file-name"></A><B>temp-file-name</B>*
		The result is a <A HREF="#String">String</A>, which is the name of a file that
		doesn't exist.	It can be used for a temporary file.  The name
		is different for at least 26 consecutive calls.  Example:
<B>			:let tmpfile = tempname()</B>
<B>			:exe "redir &gt; " . tmpfile</B>
 		For <A HREF="os_unix.html#Unix">Unix</A>, the file will be in a private directory |<A HREF="change.html#tempfile">tempfile</A>|.
		For <A HREF="os_win32.html#MS-Windows">MS-Windows</A> forward slashes are used when the <A HREF="options.html#'shellslash'">'shellslash'</A>
		option is set or when <A HREF="options.html#'shellcmdflag'">'shellcmdflag'</A> starts with '<A HREF="motion.html#-">-</A>'.



tan({expr})						*<A NAME="tan()"></A><B>tan()</B>*
		Return the tangent of {expr}, measured in radians, <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>|
		in the range [-inf, inf].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo tan(10)</B>
 			0.648361
<B>			:echo tan(-4.01)</B>
 			-1.181502
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



tanh({expr})						*<A NAME="tanh()"></A><B>tanh()</B>*
		Return the hyperbolic tangent of {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| in the
		range [-1, 1].
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			:echo tanh(0.5)</B>
 			0.462117
<B>			:echo tanh(-1)</B>
 			-0.761594
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}



							*<A NAME="timer_start()"></A><B>timer_start()</B>*
timer_start({time}, {callback} [, {options}])
		Create a timer and return the timer ID.

		{time} is the waiting time in milliseconds. This is the
		minimum time before invoking the callback.  When the system is
		busy or Vim is not waiting for input the time will be longer.

		{callback} is the function to call.  It can be the name of a
		function or a <A HREF="#Funcref">Funcref</A>.  It is called with one argument, which
		is the timer ID.  The callback is only invoked when Vim is
		waiting for input.

		{options} is a dictionary.  Supported entries:
		   &quot;repeat&quot;	<A HREF="#Number">Number</A> of times to repeat calling the
		   		callback.  -1 means forever.

		Example:
<B>			func MyHandler(timer)</B>
<B>			  echo 'Handler called'</B>
<B>			endfunc</B>
<B>			let timer = timer_start(500, 'MyHandler',</B>
<B>				\ {'repeat': 3})</B>
 		This will invoke MyHandler() three times at 500 msec
		intervals.
		{only available when compiled with the |<A HREF="various.html#+timers">+timers</A>| feature}


timer_stop({timer})					*<A NAME="timer_stop()"></A><B>timer_stop()</B>*
		Stop a timer.  {timer} is an ID returned by <A HREF="#timer_start()">timer_start()</A>.
		The timer callback will no longer be invoked.


tolower({expr})						*<A NAME="tolower()"></A><B>tolower()</B>*
		The result is a copy of the <A HREF="#String">String</A> given, with all <A HREF="change.html#uppercase">uppercase</A>
		characters turned into <A HREF="change.html#lowercase">lowercase</A> (just like applying |<A HREF="change.html#gu">gu</A>| to
		the <A HREF="#string">string</A>).


toupper({expr})						*<A NAME="toupper()"></A><B>toupper()</B>*
		The result is a copy of the <A HREF="#String">String</A> given, with all <A HREF="change.html#lowercase">lowercase</A>
		characters turned into <A HREF="change.html#uppercase">uppercase</A> (just like applying |<A HREF="change.html#gU">gU</A>| to
		the <A HREF="#string">string</A>).


tr({src}, {fromstr}, {tostr})				*<A NAME="tr()"></A><B>tr()</B>*
		The result is a copy of the {src} <A HREF="#string">string</A> with all characters
		which appear in {fromstr} replaced by the character in that
		position in the {tostr} <A HREF="#string">string</A>.  Thus the first character in
		{fromstr} is translated into the first character in {tostr}
		and so on.  Exactly like the <A HREF="os_unix.html#unix">unix</A> &quot;tr&quot; command.
		This code also deals with <A HREF="mbyte.html#multibyte">multibyte</A> characters properly.

		Examples:
<B>			echo tr("hello there", "ht", "HT")</B>
 		returns &quot;Hello THere&quot;
<B>			echo tr("&lt;blob&gt;", "&lt;&gt;", "{}")</B>
 		returns &quot;{blob}&quot;


trunc({expr})							*<A NAME="trunc()"></A><B>trunc()</B>*
		Return the largest integral value with magnitude <A HREF="various.html#less">less</A> than or
		equal to {expr} <A HREF="motion.html#as">as</A> a |<A HREF="#Float">Float</A>| (truncate towards zero).
		{expr} must evaluate to a |<A HREF="#Float">Float</A>| or a |<A HREF="#Number">Number</A>|.
		Examples:
<B>			echo trunc(1.456)</B>
 			1.0 
<B>			echo trunc(-5.456)</B>
 			-5.0 
<B>			echo trunc(4.0)</B>
 			4.0
		{only available when compiled with the |<A HREF="various.html#+float">+float</A>| feature}
		

							*<A NAME="type()"></A><B>type()</B>*
type({expr})	The result is a <A HREF="#Number">Number</A>, depending on the type of {expr}:
			<A HREF="#Number">Number</A>:	    0
			<A HREF="#String">String</A>:	    1
			<A HREF="#Funcref">Funcref</A>:    2
			<A HREF="#List">List</A>:	    3
			<A HREF="#Dictionary">Dictionary</A>: 4
			<A HREF="#Float">Float</A>:	    5
			Boolean:    6 (v:false and <A HREF="#v:true">v:true</A>)
			None	    7 (v:null and <A HREF="#v:none">v:none</A>)
			<A HREF="#Job">Job</A>	    8
			<A HREF="#Channel">Channel</A>	    9
		To avoid the magic numbers <A HREF="motion.html#it">it</A> should be used this way:
<B>			:if type(myvar) == type(0)</B>
<B>			:if type(myvar) == type("")</B>
<B>			:if type(myvar) == type(function("tr"))</B>
<B>			:if type(myvar) == type([])</B>
<B>			:if type(myvar) == type({})</B>
<B>			:if type(myvar) == type(0.0)</B>
<B>			:if type(myvar) == type(v:false)</B>
<B>			:if type(myvar) == type(v:none)</B>


undofile({name})					*<A NAME="undofile()"></A><B>undofile()</B>*
		Return the name of the <A HREF="undo.html#undo">undo</A> file that would be used for a file
		with name {name} when <A HREF="editing.html#writing">writing</A>.  This uses the <A HREF="options.html#'undodir'">'undodir'</A>
		option, finding directories that exist.  It does not check if
		the <A HREF="undo.html#undo">undo</A> file exists.
		{name} is always expanded to the full path, since that is what
		is used internally.
		If {name} is empty <A HREF="#undofile()">undofile()</A> returns an empty <A HREF="#string">string</A>, since a
		buffer without a file name will not write an <A HREF="undo.html#undo">undo</A> file.
		Useful in combination with |<A HREF="undo.html#:wundo">:wundo</A>| and |<A HREF="undo.html#:rundo">:rundo</A>|.
		When compiled without the <A HREF="various.html#+persistent_undo">+persistent_undo</A> option this always
		returns an empty <A HREF="#string">string</A>.


<A HREF="#undotree()">undotree()</A>						*<A NAME="undotree()"></A><B>undotree()</B>*
		Return the current state of the <A HREF="undo.html#undo">undo</A> tree in a dictionary with
		the following items:
		  &quot;seq_last&quot;	The highest <A HREF="undo.html#undo">undo</A> sequence number used.
		  &quot;seq_cur&quot;	The sequence number of the current position in
				the <A HREF="undo.html#undo">undo</A> tree.  This differs from &quot;seq_last&quot;
				when some changes were undone.
		  &quot;time_cur&quot;	Time last used for |<A HREF="undo.html#:earlier">:earlier</A>| and related
				commands.  Use |<A HREF="#strftime()">strftime()</A>| to convert to
				something readable.
		  &quot;save_last&quot;	<A HREF="#Number">Number</A> of the last file write.  Zero when no
				write yet.
		  &quot;save_cur&quot;	<A HREF="#Number">Number</A> of the current position in the <A HREF="undo.html#undo">undo</A>
				tree.  
		  &quot;synced&quot;	Non-zero when the last <A HREF="undo.html#undo">undo</A> block was synced.
				This happens when waiting from input from the
				user.  See |<A HREF="undo.html#undo-blocks">undo-blocks</A>|.
		  &quot;entries&quot;	A <A HREF="#list">list</A> of dictionaries with information about
				<A HREF="undo.html#undo">undo</A> blocks.

		The first item in the &quot;entries&quot; <A HREF="#list">list</A> is the oldest <A HREF="undo.html#undo">undo</A> item.
		Each <A HREF="#List">List</A> item is a <A HREF="#Dictionary">Dictionary</A> with these items:
		  &quot;seq&quot;		Undo sequence number.  Same <A HREF="motion.html#as">as</A> what appears in
				|<A HREF="undo.html#:undolist">:undolist</A>|.
		  &quot;time&quot;	Timestamp when the change happened.  Use
				|<A HREF="#strftime()">strftime()</A>| to convert to something readable.
		  &quot;newhead&quot;	Only appears in the item that is the last one
				that was added.  This marks the last change
				and where further changes will be added.
		  &quot;curhead&quot;	Only appears in the item that is the last one
				that was undone.  This marks the current
				position in the <A HREF="undo.html#undo">undo</A> tree, the block that will
				be used by a <A HREF="undo.html#redo">redo</A> command.  When nothing was
				undone after the last change this item will
				not appear anywhere.
		  &quot;save&quot;	Only appears on the last block before a file
				write.  The number is the write <A HREF="intro.html#count">count</A>.  The
				first write has number 1, the last one the
				&quot;save_last&quot; mentioned above.
		  &quot;<A HREF="intro.html#alt">alt</A>&quot;		Alternate entry.  This is again a <A HREF="#List">List</A> of <A HREF="undo.html#undo">undo</A>
				blocks.  Each item may again have an &quot;<A HREF="intro.html#alt">alt</A>&quot;
				item.


uniq({list} [, {func} [, {dict}]])			*<A NAME="uniq()"></A><B>uniq()</B>* *<A NAME="E882"></A><B>E882</B>*
		Remove second and succeeding copies of repeated adjacent
		{list} items in-place.  Returns {list}.  If you want a <A HREF="#list">list</A>
		to remain unmodified make a copy first:
<B>			:let newlist = uniq(copy(mylist))</B>
 		The default compare function uses the <A HREF="#string">string</A> representation of
		each item.  For the use of {func} and {dict} see |<A HREF="#sort()">sort()</A>|.


values({dict})						*<A NAME="values()"></A><B>values()</B>*
		Return a |<A HREF="#List">List</A>| with all the values of {dict}.	The |<A HREF="#List">List</A>| is
		in arbitrary order.



virtcol({expr})						*<A NAME="virtcol()"></A><B>virtcol()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the screen column of the file
		position given with {expr}.  That is, the last screen position
		occupied by the character at that position, when the screen
		would be of unlimited width.  When there is a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> at the
		position, the returned <A HREF="#Number">Number</A> will be the column at the end of
		the <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A>.  For example, for a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> in column 1, with <A HREF="options.html#'ts'">'ts'</A>
		set to 8, <A HREF="motion.html#it">it</A> returns 8. |<A HREF="syntax.html#conceal">conceal</A>| is ignored.
		For the byte position use |<A HREF="#col()">col()</A>|.
		For the use of {expr} see |<A HREF="#col()">col()</A>|.
		When <A HREF="options.html#'virtualedit'">'virtualedit'</A> is used {expr} can be [lnum, col, off], where
		&quot;off&quot; is the offset in screen columns from the start of the
		character.  E.g., a position within a <A HREF="motion.html#&lt;Tab&gt;">&lt;Tab&gt;</A> or after the last
		character.  When &quot;off&quot; is omitted zero is used.
		When Virtual editing is active in the current mode, a position
		beyond the end of the line can be returned. |<A HREF="options.html#'virtualedit'">'virtualedit'</A>|
		The accepted positions are:
		    .	    the cursor position
		    $	    the end of the cursor line (the result is the
			    number of displayed characters in the cursor line
			    plus one)
		    'x	    position of <A HREF="motion.html#mark">mark</A> <A HREF="change.html#x">x</A> (if the <A HREF="motion.html#mark">mark</A> is not set, 0 is
			    returned)
		    <A HREF="visual.html#v">v</A>       In <A HREF="visual.html#Visual">Visual</A> mode: the start of the <A HREF="visual.html#Visual">Visual</A> area (the
			    cursor is the end).  When not in <A HREF="visual.html#Visual">Visual</A> mode
			    returns the cursor position.  Differs from |<A HREF="motion.html#'&lt;">'&lt;</A>| in
			    that it's updated right away.
		Note that only marks in the current file can be used.
		Examples:
<B>  virtcol(".")	   with text "foo^Lbar", with cursor on the "^L", returns 5</B>
<B>  virtcol("$")	   with text "foo^Lbar", returns 9</B>
<B>  virtcol("'t")    with text "	  there", with 't at 'h', returns 6</B>
 		The first column is 1.	0 is returned for an error.
		A more advanced example that echoes the maximum length of
		all lines:
<B>		    echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))</B>



visualmode([expr])						*<A NAME="visualmode()"></A><B>visualmode()</B>*
		The result is a <A HREF="#String">String</A>, which describes the last <A HREF="visual.html#Visual">Visual</A> mode
		used in the current buffer.  Initially <A HREF="motion.html#it">it</A> returns an empty
		<A HREF="#string">string</A>, but once <A HREF="visual.html#Visual">Visual</A> mode has been used, <A HREF="motion.html#it">it</A> returns &quot;<A HREF="visual.html#v">v</A>&quot;,
		&quot;<A HREF="visual.html#V">V</A>&quot;, or &quot;&lt;CTRL-V&gt;&quot; (a single <A HREF="visual.html#CTRL-V">CTRL-V</A> character) for
		character-wise, line-wise, or block-wise <A HREF="visual.html#Visual">Visual</A> mode
		respectively.
		Example:
<B>			:exe "normal " . visualmode()</B>
 		This enters the same <A HREF="visual.html#Visual">Visual</A> mode <A HREF="motion.html#as">as</A> before.  It is also useful
		in scripts if you wish to act differently depending on the
		<A HREF="visual.html#Visual">Visual</A> mode that was used.
		If <A HREF="visual.html#Visual">Visual</A> mode is active, use |<A HREF="#mode()">mode()</A>| to get the <A HREF="visual.html#Visual">Visual</A> mode
		(e.g., in a |<A HREF="map.html#:vmap">:vmap</A>|).

							*<A NAME="non-zero-arg"></A><B>non-zero-arg</B>*
		If [expr] is supplied and <A HREF="motion.html#it">it</A> evaluates to a non-zero <A HREF="#Number">Number</A> or
		a non-empty <A HREF="#String">String</A>, then the <A HREF="visual.html#Visual">Visual</A> mode will be cleared and
		the old value is returned.  Note that &quot; &quot; and &quot;<A HREF="motion.html#0">0</A>&quot; are also
		non-empty strings, thus cause the mode to be cleared.  A <A HREF="#List">List</A>,
		<A HREF="#Dictionary">Dictionary</A> or <A HREF="#Float">Float</A> is not a <A HREF="#Number">Number</A> or <A HREF="#String">String</A>, thus does not
		cause the mode to be cleared.


<A HREF="#wildmenumode()">wildmenumode()</A>					*<A NAME="wildmenumode()"></A><B>wildmenumode()</B>*
		Returns non-zero when the wildmenu is active and zero
		otherwise.  See <A HREF="options.html#'wildmenu'">'wildmenu'</A> and <A HREF="options.html#'wildmode'">'wildmode'</A>.
		This can be used in mappings to handle the <A HREF="options.html#'wildcharm'">'wildcharm'</A> option
		gracefully. (Makes only sense with |<A HREF="map.html#mapmode-c">mapmode-c</A>| mappings).

		For example to make &lt;c-j&gt; work like &lt;down&gt; in wildmode, use:
<B>    :cnoremap &lt;expr&gt; &lt;C-j&gt; wildmenumode() ? "\&lt;Down&gt;\&lt;Tab&gt;" : "\&lt;c-j&gt;"</B>
 
		(Note, this needs the <A HREF="options.html#'wildcharm'">'wildcharm'</A> option set appropriately).



win_findbuf({bufnr})					*<A NAME="win_findbuf()"></A><B>win_findbuf()</B>*
		Returns a <A HREF="#list">list</A> with <A HREF="windows.html#window">window</A> IDs for <A HREF="windows.html#windows">windows</A> that contain buffer
		{bufnr}.  When there is none the <A HREF="#list">list</A> is empty.


win_getid([{win} [, {tab}]])				*<A NAME="win_getid()"></A><B>win_getid()</B>*
		Get the <A HREF="windows.html#window">window</A> ID for the specified <A HREF="windows.html#window">window</A>.
		When {win} is missing use the current <A HREF="windows.html#window">window</A>.
		With {win} this is the <A HREF="windows.html#window">window</A> number.  The top <A HREF="windows.html#window">window</A> has
		number 1.
		Without {tab} use the current <A HREF="intro.html#tab">tab</A>, otherwise the <A HREF="intro.html#tab">tab</A> with
		number {tab}.  The first <A HREF="intro.html#tab">tab</A> has number one.
		Return zero if the <A HREF="windows.html#window">window</A> cannot be found.


win_gotoid({expr})					*<A NAME="win_gotoid()"></A><B>win_gotoid()</B>*
		Go to <A HREF="windows.html#window">window</A> with ID {expr}.  This may also change the current
		<A HREF="tabpage.html#tabpage">tabpage</A>.
		Return 1 if successful, 0 if the <A HREF="windows.html#window">window</A> cannot be found.


win_id2tabwin({expr}					*<A NAME="win_id2tabwin()"></A><B>win_id2tabwin()</B>*
		Return a <A HREF="#list">list</A> with the <A HREF="intro.html#tab">tab</A> number and <A HREF="windows.html#window">window</A> number of <A HREF="windows.html#window">window</A>
		with ID {expr}: [tabnr, winnr].
		Return [0, 0] if the <A HREF="windows.html#window">window</A> cannot be found.


win_id2win({expr})					*<A NAME="win_id2win()"></A><B>win_id2win()</B>*
		Return the <A HREF="windows.html#window">window</A> number of <A HREF="windows.html#window">window</A> with ID {expr}.
		Return 0 if the <A HREF="windows.html#window">window</A> cannot be found in the current <A HREF="tabpage.html#tabpage">tabpage</A>.


							*<A NAME="winbufnr()"></A><B>winbufnr()</B>*
winbufnr({nr})	The result is a <A HREF="#Number">Number</A>, which is the number of the buffer
		associated with <A HREF="windows.html#window">window</A> {nr}.  When {nr} is zero, the number of
		the buffer in the current <A HREF="windows.html#window">window</A> is returned.  When <A HREF="windows.html#window">window</A>
		{nr} doesn't exist, -1 is returned.
		Example:
<B>  :echo "The file in the current window is " . bufname(winbufnr(0))</B>
 

							*<A NAME="wincol()"></A><B>wincol()</B>*
<A HREF="#wincol()">wincol()</A>	The result is a <A HREF="#Number">Number</A>, which is the virtual column of the
		cursor in the <A HREF="windows.html#window">window</A>.  This is counting screen cells from the
		left side of the <A HREF="windows.html#window">window</A>.  The leftmost column is one.


winheight({nr})						*<A NAME="winheight()"></A><B>winheight()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the height of <A HREF="windows.html#window">window</A> {nr}.
		When {nr} is zero, the height of the current <A HREF="windows.html#window">window</A> is
		returned.  When <A HREF="windows.html#window">window</A> {nr} doesn't exist, -1 is returned.
		An existing <A HREF="windows.html#window">window</A> always has a height of zero or more.
		Examples:
<B>  :echo "The current window has " . winheight(0) . " lines."</B>
 

							*<A NAME="winline()"></A><B>winline()</B>*
<A HREF="#winline()">winline()</A>	The result is a <A HREF="#Number">Number</A>, which is the screen line of the cursor
		in the <A HREF="windows.html#window">window</A>.	This is counting screen lines from the top of
		the <A HREF="windows.html#window">window</A>.  The first line is one.
		If the cursor was moved the <A HREF="starting.html#view">view</A> on the file will be updated
		first, this may cause a scroll.


							*<A NAME="winnr()"></A><B>winnr()</B>*
winnr([{arg}])	The result is a <A HREF="#Number">Number</A>, which is the number of the current
		<A HREF="windows.html#window">window</A>.  The top <A HREF="windows.html#window">window</A> has number 1.
		When the optional argument is &quot;<A HREF="motion.html#$">$</A>&quot;, the number of the
		last <A HREF="windows.html#window">window</A> is returned (the <A HREF="windows.html#window">window</A> <A HREF="intro.html#count">count</A>).
<B>			let window_count = winnr('$')</B>
 		When the optional argument is &quot;<A HREF="pattern.html##">#</A>&quot;, the number of the last
		accessed <A HREF="windows.html#window">window</A> is returned (where |<A HREF="windows.html#CTRL-W_p">CTRL-W_p</A>| goes to).
		If there is no previous <A HREF="windows.html#window">window</A> or <A HREF="motion.html#it">it</A> is in another <A HREF="intro.html#tab">tab</A> page 0
		is returned.
		The number can be used with |<A HREF="windows.html#CTRL-W_w">CTRL-W_w</A>| and &quot;<A HREF="windows.html#:wincmd">:wincmd</A> w&quot;
		|<A HREF="windows.html#:wincmd">:wincmd</A>|.
		Also see |<A HREF="#tabpagewinnr()">tabpagewinnr()</A>|.


							*<A NAME="winrestcmd()"></A><B>winrestcmd()</B>*
<A HREF="#winrestcmd()">winrestcmd()</A>	Returns a sequence of |<A HREF="windows.html#:resize">:resize</A>| commands that should restore
		the current <A HREF="windows.html#window">window</A> sizes.  Only works properly when no <A HREF="windows.html#windows">windows</A>
		are opened or closed and the current <A HREF="windows.html#window">window</A> and <A HREF="intro.html#tab">tab</A> page is
		unchanged.
		Example:
<B>			:let cmd = winrestcmd()</B>
<B>			:call MessWithWindowSizes()</B>
<B>			:exe cmd</B>
 

							*<A NAME="winrestview()"></A><B>winrestview()</B>*
winrestview({dict})
		Uses the |<A HREF="#Dictionary">Dictionary</A>| returned by |<A HREF="#winsaveview()">winsaveview()</A>| to restore
		the <A HREF="starting.html#view">view</A> of the current <A HREF="windows.html#window">window</A>.
		Note: The {dict} does not have to contain all values, that are
		returned by |<A HREF="#winsaveview()">winsaveview()</A>|. If values are missing, those
		settings won't be restored. So you can use:
<B>		    :call winrestview({'curswant': 4})</B>
 
		This will only set the curswant value (the column the cursor
		wants to move on vertical movements) of the cursor to column 5
		(yes, that is 5), while all other settings will remain the
		same. This is useful, if you set the cursor position manually.

		If you have changed the values the result is unpredictable.
		If the <A HREF="windows.html#window">window</A> size changed the result won't be the same.


							*<A NAME="winsaveview()"></A><B>winsaveview()</B>*
<A HREF="#winsaveview()">winsaveview()</A>	Returns a |<A HREF="#Dictionary">Dictionary</A>| that contains information to restore
		the view of the current <A HREF="windows.html#window">window</A>.  Use |<A HREF="#winrestview()">winrestview()</A>| to
		restore the <A HREF="starting.html#view">view</A>.
		This is useful if you have a <A HREF="map.html#mapping">mapping</A> that jumps around in the
		buffer and you want to go back to the original <A HREF="starting.html#view">view</A>.
		This does not save fold information.  Use the <A HREF="options.html#'foldenable'">'foldenable'</A>
		option to temporarily switch off <A HREF="fold.html#folding">folding</A>, so that <A HREF="fold.html#folds">folds</A> are
		not opened when moving around. This may have side effects.
		The return value includes:
			lnum		cursor line number
			col		cursor column (Note: the first column
					zero, <A HREF="motion.html#as">as</A> opposed to what <A HREF="#getpos()">getpos()</A>
					returns)
			coladd		cursor column offset for <A HREF="options.html#'virtualedit'">'virtualedit'</A>
			curswant	column for vertical <A HREF="intro.html#movement">movement</A>
			topline		first line in the <A HREF="windows.html#window">window</A>
			topfill		filler lines, only in <A HREF="diff.html#diff">diff</A> mode
			leftcol		first column displayed
			skipcol		columns skipped
		Note that no option values are saved.



winwidth({nr})						*<A NAME="winwidth()"></A><B>winwidth()</B>*
		The result is a <A HREF="#Number">Number</A>, which is the width of <A HREF="windows.html#window">window</A> {nr}.
		When {nr} is zero, the width of the current <A HREF="windows.html#window">window</A> is
		returned.  When <A HREF="windows.html#window">window</A> {nr} doesn't exist, -1 is returned.
		An existing <A HREF="windows.html#window">window</A> always has a width of zero or more.
		Examples:
<B>  :echo "The current window has " . winwidth(0) . " columns."</B>
<B>  :if winwidth(0) &lt;= 50</B>
<B>  :  exe "normal 50\&lt;C-W&gt;|"</B>
<B>  :endif</B>
 

<A HREF="#wordcount()">wordcount()</A>						*<A NAME="wordcount()"></A><B>wordcount()</B>*
		The result is a dictionary of byte/chars/word statistics for
		the current buffer.  This is the same info <A HREF="motion.html#as">as</A> provided by
		|<A HREF="editing.html#g_CTRL-G">g_CTRL-G</A>|
		The return value includes:
			bytes		<A HREF="#Number">Number</A> of bytes in the buffer
			chars		<A HREF="#Number">Number</A> of chars in the buffer
			words		<A HREF="#Number">Number</A> of words in the buffer
			cursor_bytes    <A HREF="#Number">Number</A> of bytes before cursor position
					(not in <A HREF="visual.html#Visual">Visual</A> mode)
			cursor_chars    <A HREF="#Number">Number</A> of chars before cursor position
					(not in <A HREF="visual.html#Visual">Visual</A> mode)
			cursor_words    <A HREF="#Number">Number</A> of words before cursor position
					(not in <A HREF="visual.html#Visual">Visual</A> mode)
			visual_bytes    <A HREF="#Number">Number</A> of bytes visually selected
			                (only in <A HREF="visual.html#Visual">Visual</A> mode)
			visual_chars    <A HREF="#Number">Number</A> of chars visually selected
			                (only in <A HREF="visual.html#Visual">Visual</A> mode)
			visual_words    <A HREF="#Number">Number</A> of chars visually selected
			                (only in <A HREF="visual.html#Visual">Visual</A> mode)



							*<A NAME="writefile()"></A><B>writefile()</B>*
writefile({list}, {fname} [, {flags}])
		Write |<A HREF="#List">List</A>| {list} to file {fname}.  Each <A HREF="#list">list</A> item is
		separated with a NL.  Each <A HREF="#list">list</A> item must be a <A HREF="#String">String</A> or
		<A HREF="#Number">Number</A>.
		When {flags} contains &quot;<A HREF="motion.html#b">b</A>&quot; then binary mode is used: There will
		not be a NL after the last <A HREF="#list">list</A> item.  An empty item at the
		end does cause the last line in the file to end in a NL.

		When {flags} contains &quot;<A HREF="insert.html#a">a</A>&quot; then append mode is used, lines are
		append to the file:
<B>			:call writefile(["foo"], "event.log", "a")</B>
<B>			:call writefile(["bar"], "event.log", "a")</B>

 		All NL characters are replaced with a NUL character.
		Inserting CR characters needs to be done before passing {list}
		to <A HREF="#writefile()">writefile()</A>.
		An existing file is overwritten, if possible.
		When the write fails -1 is returned, otherwise 0.  There is an
		error message if the file can't be created or when <A HREF="editing.html#writing">writing</A>
		fails.
		Also see |<A HREF="#readfile()">readfile()</A>|.
		To copy a file byte for byte:
<B>			:let fl = readfile("foo", "b")</B>
<B>			:call writefile(fl, "foocopy", "b")</B>



xor({expr}, {expr})					*<A NAME="xor()"></A><B>xor()</B>*
		Bitwise XOR on the two arguments.  The arguments are converted
		to a number.  A <A HREF="#List">List</A>, Dict or <A HREF="#Float">Float</A> argument causes an error.
		Example:
<B>			:let bits = xor(bits, 0x80)</B>
 



							*<A NAME="feature-list"></A><B>feature-list</B>*
There are four types of features:
1.  Features that are only supported when they have been enabled when Vim
    was compiled |<A HREF="various.html#+feature-list">+feature-list</A>|.  Example:
<B>	:if has("cindent")</B>
2.  Features that are only supported when certain conditions have been met.
    Example:
<B>	:if has("gui_running")</B>

 							*<A NAME="has-patch"></A><B>has-patch</B>*
3.  Included patches.  The &quot;patch123&quot; feature means that patch 123 has been
    included.  Note that this form does not check the version of Vim, you need
    to inspect |<A HREF="#v:version">v:version</A>| for that.
    Example (checking version 6.2.148 or later):
<B>	:if v:version &gt; 602 || v:version == 602 &amp;&amp; has("patch148")</B>
     Note that it's possible for patch 147 to be omitted even though 148 is
    included.

4.  Beyond a certain version or at a certain version and including a specific
    patch.  The &quot;patch-7.4.237&quot; feature means that the Vim version is 7.5 or
    later, or <A HREF="motion.html#it">it</A> is version 7.4 and patch 237 was included.
    Note that this only works for patch 7.4.237 and later, before that you
    need to use the example above that checks <A HREF="#v:version">v:version</A>.  Example:
<B>	:if has("patch-7.4.248")</B>
     Note that it's possible for patch 147 to be omitted even though 148 is
    included.

acl			Compiled with |<A HREF="editing.html#ACL">ACL</A>| support.
all_builtin_terms	Compiled with all builtin terminals enabled.
amiga			<A HREF="os_amiga.html#Amiga">Amiga</A> version of Vim.
arabic			Compiled with Arabic support |<A HREF="arabic.html#Arabic">Arabic</A>|.
arp			Compiled with ARP support (Amiga).
autocmd			Compiled with autocommand support. |<A HREF="autocmd.html#autocommand">autocommand</A>|
balloon_eval		Compiled with |<A HREF="debugger.html#balloon-eval">balloon-eval</A>| support.
balloon_multiline	<A HREF="gui.html#GUI">GUI</A> supports multiline balloons.
beos			<A HREF="os_beos.html#BeOS">BeOS</A> version of Vim.
browse			Compiled with |<A HREF="editing.html#:browse">:browse</A>| support, and <A HREF="#browse()">browse()</A> will
			work.
browsefilter		Compiled with support for |<A HREF="editing.html#browsefilter">browsefilter</A>|.
<A HREF="term.html#builtin_terms">builtin_terms</A>		Compiled with some builtin terminals.
byte_offset		Compiled with support for '<A HREF="insert.html#o">o</A>' in <A HREF="options.html#'statusline'">'statusline'</A>
cindent			Compiled with <A HREF="options.html#'cindent'">'cindent'</A> support.
clientserver		Compiled with remote invocation support |<A HREF="remote.html#clientserver">clientserver</A>|.
<A HREF="gui.html#clipboard">clipboard</A>		Compiled with <A HREF="options.html#'clipboard'">'clipboard'</A> support.
cmdline_compl		Compiled with |<A HREF="cmdline.html#cmdline-completion">cmdline-completion</A>| support.
cmdline_hist		Compiled with |<A HREF="cmdline.html#cmdline-history">cmdline-history</A>| support.
cmdline_info		Compiled with <A HREF="options.html#'showcmd'">'showcmd'</A> and <A HREF="options.html#'ruler'">'ruler'</A> support.
comments		Compiled with |<A HREF="options.html#'comments'">'comments'</A>| support.
compatible		Compiled to be very <A HREF="intro.html#Vi">Vi</A> compatible.
cryptv			Compiled with encryption support |<A HREF="editing.html#encryption">encryption</A>|.
cscope			Compiled with |<A HREF="if_cscop.html#cscope">cscope</A>| support.
debug			Compiled with &quot;DEBUG&quot; defined.
dialog_con		Compiled with console <A HREF="gui_w32.html#dialog">dialog</A> support.
dialog_gui		Compiled with <A HREF="gui.html#GUI">GUI</A> <A HREF="gui_w32.html#dialog">dialog</A> support.
diff			Compiled with |<A HREF="diff.html#vimdiff">vimdiff</A>| and <A HREF="options.html#'diff'">'diff'</A> support.
<A HREF="digraph.html#digraphs">digraphs</A>		Compiled with support for <A HREF="digraph.html#digraphs">digraphs</A>.
directx			Compiled with support for Direct-X and <A HREF="options.html#'renderoptions'">'renderoptions'</A>.
dnd			Compiled with support for the &quot;~ <A HREF="sponsor.html#register">register</A> |<A HREF="change.html#quote_~">quote_~</A>|.
dos16			16 bits <A HREF="os_dos.html#DOS">DOS</A> version of Vim.
dos32			32 bits <A HREF="os_dos.html#DOS">DOS</A> (DJGPP) version of Vim.
ebcdic			Compiled on a machine with ebcdic character set.
<A HREF="tagsrch.html#emacs_tags">emacs_tags</A>		Compiled with support for Emacs <A HREF="tagsrch.html#tags">tags</A>.
<A HREF="#eval">eval</A>			Compiled with <A HREF="#expression">expression</A> evaluation support.  Always
			true, of course!
ex_extra		|<A HREF="various.html#+ex_extra">+ex_extra</A>|, always true now
extra_search		Compiled with support for |<A HREF="options.html#'incsearch'">'incsearch'</A>| and
			|<A HREF="options.html#'hlsearch'">'hlsearch'</A>|
farsi			Compiled with <A HREF="farsi.html#Farsi">Farsi</A> support |<A HREF="farsi.html#farsi">farsi</A>|.
file_in_path		Compiled with support for |<A HREF="editing.html#gf">gf</A>| and |<A HREF="cmdline.html#&lt;cfile&gt;">&lt;cfile&gt;</A>|
filterpipe		When <A HREF="options.html#'shelltemp'">'shelltemp'</A> is off pipes are used for shell
			read/write/filter commands
find_in_path		Compiled with support for include file searches
			|<A HREF="various.html#+find_in_path">+find_in_path</A>|.
float			Compiled with support for |<A HREF="#Float">Float</A>|.
fname_case		Case in file names matters (for <A HREF="os_amiga.html#Amiga">Amiga</A>, <A HREF="os_msdos.html#MS-DOS">MS-DOS</A>, and
			Windows this is not present).
folding			Compiled with |<A HREF="fold.html#folding">folding</A>| support.
footer			Compiled with <A HREF="gui.html#GUI">GUI</A> footer support. |<A HREF="debugger.html#gui-footer">gui-footer</A>|
<A HREF="os_unix.html#fork">fork</A>			Compiled to use fork()/exec() instead of <A HREF="#system()">system()</A>.
gettext			Compiled with message translation |<A HREF="mlang.html#multi-lang">multi-lang</A>|
<A HREF="gui.html#gui">gui</A>			Compiled with <A HREF="gui.html#GUI">GUI</A> enabled.
gui_athena		Compiled with <A HREF="gui_x11.html#Athena">Athena</A> <A HREF="gui.html#GUI">GUI</A>.
gui_gnome		Compiled with <A HREF="gui_x11.html#Gnome">Gnome</A> support (gui_gtk is also defined).
gui_gtk			Compiled with <A HREF="gui_x11.html#GTK+">GTK+</A> <A HREF="gui.html#GUI">GUI</A> (any version).
gui_gtk2		Compiled with <A HREF="gui_x11.html#GTK+">GTK+</A> 2 <A HREF="gui.html#GUI">GUI</A> (gui_gtk is also defined).
gui_gtk3		Compiled with <A HREF="gui_x11.html#GTK+">GTK+</A> 3 <A HREF="gui.html#GUI">GUI</A> (gui_gtk is also defined).
gui_mac			Compiled with <A HREF="os_mac.html#Macintosh">Macintosh</A> <A HREF="gui.html#GUI">GUI</A>.
gui_motif		Compiled with <A HREF="gui_x11.html#Motif">Motif</A> <A HREF="gui.html#GUI">GUI</A>.
gui_photon		Compiled with Photon <A HREF="gui.html#GUI">GUI</A>.
gui_running		Vim is running in the <A HREF="gui.html#GUI">GUI</A>, or <A HREF="motion.html#it">it</A> will start soon.
gui_win32		Compiled with MS Windows <A HREF="os_win32.html#Win32">Win32</A> <A HREF="gui.html#GUI">GUI</A>.
gui_win32s		idem, and Win32s system being used (Windows 3.1)
hangul_input		Compiled with Hangul input support. |<A HREF="hangulin.html#hangul">hangul</A>|
iconv			Can use <A HREF="#iconv()">iconv()</A> for conversion.
<A HREF="insert.html#insert_expand">insert_expand</A>		Compiled with support for <A HREF="change.html#CTRL-X">CTRL-X</A> expansion commands in
			<A HREF="insert.html#Insert">Insert</A> mode.
jumplist		Compiled with |<A HREF="motion.html#jumplist">jumplist</A>| support.
keymap			Compiled with <A HREF="options.html#'keymap'">'keymap'</A> support.
langmap			Compiled with <A HREF="options.html#'langmap'">'langmap'</A> support.
libcall			Compiled with |<A HREF="#libcall()">libcall()</A>| support.
linebreak		Compiled with <A HREF="options.html#'linebreak'">'linebreak'</A>, <A HREF="options.html#'breakat'">'breakat'</A>, <A HREF="options.html#'showbreak'">'showbreak'</A> and
			<A HREF="options.html#'breakindent'">'breakindent'</A> support.
lispindent		Compiled with support for lisp indenting.
listcmds		Compiled with commands for the buffer <A HREF="#list">list</A> |<A HREF="windows.html#:files">:files</A>|
			and the argument list |<A HREF="editing.html#arglist">arglist</A>|.
localmap		Compiled with local mappings and abbr. |<A HREF="map.html#:map-local">:map-local</A>|
<A HREF="if_lua.html#lua">lua</A>			Compiled with Lua interface |<A HREF="if_lua.html#Lua">Lua</A>|.
<A HREF="os_mac.html#mac">mac</A>			Any <A HREF="os_mac.html#Macintosh">Macintosh</A> version of Vim.
macunix			Compiled for OS X, with darwin
osx			Compiled for OS X, with or without darwin
menu			Compiled with support for |<A HREF="gui.html#:menu">:menu</A>|.
mksession		Compiled with support for |<A HREF="starting.html#:mksession">:mksession</A>|.
modify_fname		Compiled with file name modifiers. |<A HREF="cmdline.html#filename-modifiers">filename-modifiers</A>|
mouse			Compiled with support mouse.
mouse_dec		Compiled with support for Dec terminal mouse.
mouse_gpm		Compiled with support for gpm (Linux console mouse)
mouse_netterm		Compiled with support for netterm mouse.
mouse_pterm		Compiled with support for <A HREF="os_qnx.html#qnx">qnx</A> pterm mouse.
mouse_sysmouse		Compiled with support for <A HREF="term.html#sysmouse">sysmouse</A> (*BSD console mouse)
mouse_sgr		Compiled with support for sgr mouse.
mouse_urxvt		Compiled with support for urxvt mouse.
mouse_xterm		Compiled with support for xterm mouse.
mouseshape		Compiled with support for <A HREF="options.html#'mouseshape'">'mouseshape'</A>.
multi_byte		Compiled with support for <A HREF="options.html#'encoding'">'encoding'</A>
multi_byte_encoding	<A HREF="options.html#'encoding'">'encoding'</A> is set to a <A HREF="mbyte.html#multi-byte">multi-byte</A> encoding.
multi_byte_ime		Compiled with support for <A HREF="mbyte.html#IME">IME</A> input method.
multi_lang		Compiled with support for multiple languages.
mzscheme		Compiled with <A HREF="if_mzsch.html#MzScheme">MzScheme</A> interface |<A HREF="if_mzsch.html#mzscheme">mzscheme</A>|.
netbeans_enabled	Compiled with support for |<A HREF="netbeans.html#netbeans">netbeans</A>| and connected.
netbeans_intg		Compiled with support for |<A HREF="netbeans.html#netbeans">netbeans</A>|.
ole			Compiled with OLE automation support for <A HREF="os_win32.html#Win32">Win32</A>.
<A HREF="os_os2.html#os2">os2</A>			<A HREF="os_os2.html#OS/2">OS/2</A> version of Vim.
path_extra		Compiled with up/downwards search in <A HREF="options.html#'path'">'path'</A> and <A HREF="options.html#'tags'">'tags'</A>
<A HREF="if_perl.html#perl">perl</A>			Compiled with <A HREF="if_perl.html#Perl">Perl</A> interface.
persistent_undo		Compiled with support for persistent <A HREF="undo.html#undo">undo</A> <A HREF="cmdline.html#history">history</A>.
postscript		Compiled with PostScript file <A HREF="print.html#printing">printing</A>.
printer			Compiled with |<A HREF="print.html#:hardcopy">:hardcopy</A>| support.
profile			Compiled with |<A HREF="repeat.html#:profile">:profile</A>| support.
python			Compiled with <A HREF="if_pyth.html#Python">Python</A> 2.x interface. |<A HREF="if_pyth.html#has-python">has-python</A>|
<A HREF="if_pyth.html#python3">python3</A>			Compiled with <A HREF="if_pyth.html#Python">Python</A> 3.x interface. |<A HREF="if_pyth.html#has-python">has-python</A>|
<A HREF="os_qnx.html#qnx">qnx</A>			<A HREF="os_qnx.html#QNX">QNX</A> version of Vim.
quickfix		Compiled with |<A HREF="quickfix.html#quickfix">quickfix</A>| support.
reltime			Compiled with |<A HREF="#reltime()">reltime()</A>| support.
rightleft		Compiled with <A HREF="options.html#'rightleft'">'rightleft'</A> support.
ruby			Compiled with <A HREF="if_ruby.html#Ruby">Ruby</A> interface |<A HREF="if_ruby.html#ruby">ruby</A>|.
scrollbind		Compiled with <A HREF="options.html#'scrollbind'">'scrollbind'</A> support.
showcmd			Compiled with <A HREF="options.html#'showcmd'">'showcmd'</A> support.
<A HREF="sign.html#signs">signs</A>			Compiled with |<A HREF="sign.html#:sign">:sign</A>| support.
smartindent		Compiled with <A HREF="options.html#'smartindent'">'smartindent'</A> support.
spell			Compiled with spell checking support |<A HREF="spell.html#spell">spell</A>|.
startuptime		Compiled with |<A HREF="starting.html#--startuptime">--startuptime</A>| support.
statusline		Compiled with support for <A HREF="options.html#'statusline'">'statusline'</A>, <A HREF="options.html#'rulerformat'">'rulerformat'</A>
			and special formats of <A HREF="options.html#'titlestring'">'titlestring'</A> and <A HREF="options.html#'iconstring'">'iconstring'</A>.
sun_workshop		Compiled with support for Sun |<A HREF="workshop.html#workshop">workshop</A>|.
syntax			Compiled with syntax highlighting support |<A HREF="syntax.html#syntax">syntax</A>|.
syntax_items		There are active <A HREF="syntax.html#syntax">syntax</A> highlighting items for the
			current buffer.
system			Compiled to use <A HREF="#system()">system()</A> instead of fork()/exec().
tag_binary		Compiled with binary searching in <A HREF="tagsrch.html#tags">tags</A> files
			|<A HREF="tagsrch.html#tag-binary-search">tag-binary-search</A>|.
tag_old_static		Compiled with support for old static <A HREF="tagsrch.html#tags">tags</A>
			|<A HREF="tagsrch.html#tag-old-static">tag-old-static</A>|.
tag_any_white		Compiled with support for any white characters in <A HREF="tagsrch.html#tags">tags</A>
			files |<A HREF="tagsrch.html#tag-any-white">tag-any-white</A>|.
<A HREF="if_tcl.html#tcl">tcl</A>			Compiled with <A HREF="if_tcl.html#Tcl">Tcl</A> interface.
<A HREF="term.html#terminfo">terminfo</A>		Compiled with <A HREF="term.html#terminfo">terminfo</A> instead of <A HREF="term.html#termcap">termcap</A>.
termresponse		Compiled with support for |<A HREF="term.html#t_RV">t_RV</A>| and |<A HREF="#v:termresponse">v:termresponse</A>|.
textobjects		Compiled with support for |<A HREF="motion.html#text-objects">text-objects</A>|.
tgetent			Compiled with tgetent support, able to use a <A HREF="term.html#termcap">termcap</A>
			or <A HREF="term.html#terminfo">terminfo</A> file.
timers			Compiled with |<A HREF="#timer_start()">timer_start()</A>| support.
title			Compiled with <A HREF="windows.html#window">window</A> title support |<A HREF="options.html#'title'">'title'</A>|.
toolbar			Compiled with support for |<A HREF="gui.html#gui-toolbar">gui-toolbar</A>|.
<A HREF="os_unix.html#unix">unix</A>			<A HREF="os_unix.html#Unix">Unix</A> version of Vim.
user_commands		User-defined commands.
vertsplit		Compiled with vertically split <A HREF="windows.html#windows">windows</A> |<A HREF="windows.html#:vsplit">:vsplit</A>|.
<A HREF="#vim_starting">vim_starting</A>		True while initial source'ing takes place. |<A HREF="starting.html#startup">startup</A>|

			*<A NAME="vim_starting"></A><B>vim_starting</B>*
<A HREF="starting.html#viminfo">viminfo</A>			Compiled with <A HREF="starting.html#viminfo">viminfo</A> support.
virtualedit		Compiled with <A HREF="options.html#'virtualedit'">'virtualedit'</A> option.
visual			Compiled with <A HREF="visual.html#Visual">Visual</A> mode.
visualextra		Compiled with extra <A HREF="visual.html#Visual">Visual</A> mode commands.
			|<A HREF="visual.html#blockwise-operators">blockwise-operators</A>|.
<A HREF="os_vms.html#vms">vms</A>			<A HREF="os_vms.html#VMS">VMS</A> version of Vim.
vreplace		Compiled with |<A HREF="change.html#gR">gR</A>| and |<A HREF="change.html#gr">gr</A>| commands.
wildignore		Compiled with <A HREF="options.html#'wildignore'">'wildignore'</A> option.
wildmenu		Compiled with <A HREF="options.html#'wildmenu'">'wildmenu'</A> option.
<A HREF="os_win32.html#win32">win32</A>			<A HREF="os_win32.html#Win32">Win32</A> version of Vim (MS-Windows 95 and later, 32 or
			64 bits)
win32unix		<A HREF="os_win32.html#Win32">Win32</A> version of Vim, using <A HREF="os_unix.html#Unix">Unix</A> files (Cygwin)
win64			Win64 version of Vim (MS-Windows 64 bit).
win95			<A HREF="os_win32.html#Win32">Win32</A> version for <A HREF="os_win32.html#MS-Windows">MS-Windows</A> 95/98/ME.
winaltkeys		Compiled with <A HREF="options.html#'winaltkeys'">'winaltkeys'</A> option.
<A HREF="windows.html#windows">windows</A>			Compiled with support for more than one <A HREF="windows.html#window">window</A>.
writebackup		Compiled with <A HREF="options.html#'writebackup'">'writebackup'</A> default on.
xfontset		Compiled with X fontset support |<A HREF="mbyte.html#xfontset">xfontset</A>|.
xim			Compiled with X input method support |<A HREF="mbyte.html#xim">xim</A>|.
xpm			Compiled with pixmap support.
xpm_w32			Compiled with pixmap support for <A HREF="os_win32.html#Win32">Win32</A>. (Only for
			backward compatibility. Use &quot;xpm&quot; instead.)
xsmp			Compiled with X session management support.
xsmp_interact		Compiled with interactive X session management support.
xterm_clipboard		Compiled with support for xterm <A HREF="gui.html#clipboard">clipboard</A>.
xterm_save		Compiled with support for saving and restoring the
			xterm screen.
x11			Compiled with <A HREF="options.html#X11">X11</A> support.


							*<A NAME="string-match"></A><B>string-match</B>*
Matching a <A HREF="pattern.html#pattern">pattern</A> in a <A HREF="#String">String</A>

A <A HREF="pattern.html#regexp">regexp</A> pattern <A HREF="motion.html#as">as</A> explained at |<A HREF="pattern.html#pattern">pattern</A>| is normally used to find a match in
the buffer lines.  When a <A HREF="pattern.html#pattern">pattern</A> is used to find a match in a <A HREF="#String">String</A>, almost
everything works in the same way.  The difference is that a <A HREF="#String">String</A> is handled
like <A HREF="motion.html#it">it</A> is one line.  When <A HREF="motion.html#it">it</A> contains a &quot;\n&quot; character, this is not seen <A HREF="motion.html#as">as</A> a
line break for the <A HREF="pattern.html#pattern">pattern</A>.  It can be matched with a &quot;\n&quot; in the <A HREF="pattern.html#pattern">pattern</A>, or
with &quot;<A HREF="repeat.html#.">.</A>&quot;.  Example:
<B>	:let a = "aaaa\nxxxx"</B>
<B>	:echo matchstr(a, "..\n..")</B>
<B>	aa</B>
<B>	xx</B>
<B>	:echo matchstr(a, "a.x")</B>
<B>	a</B>
<B>	x</B>

Don't forget that &quot;<A HREF="motion.html#^">^</A>&quot; will only match at the first character of the <A HREF="#String">String</A> and
&quot;<A HREF="motion.html#$">$</A>&quot; at the last character of the <A HREF="#string">string</A>.  They don't match after or before a
&quot;\n&quot;.

==============================================================================

5. Defining <A HREF="#functions">functions</A>					*<A NAME="user-functions"></A><B>user-functions</B>*

New <A HREF="#functions">functions</A> can be defined.  These can be called just like builtin
<A HREF="#functions">functions</A>.  The function executes a sequence of <A HREF="intro.html#Ex">Ex</A> commands.  <A HREF="intro.html#Normal">Normal</A> mode
commands can be executed with the |<A HREF="various.html#:normal">:normal</A>| command.

The function name must start with an <A HREF="change.html#uppercase">uppercase</A> <A HREF="print.html#letter">letter</A>, to avoid confusion with
builtin <A HREF="#functions">functions</A>.  To prevent from using the same name in different scripts
avoid obvious, short names.  A good habit is to start the function name with
the name of the <A HREF="usr_41.html#script">script</A>, e.g., &quot;HTMLcolor()&quot;.

It's also possible to use curly braces, see |<A HREF="#curly-braces-names">curly-braces-names</A>|.  And the
|<A HREF="#autoload">autoload</A>| facility is useful to define a function only when it's called.


							*<A NAME="local-function"></A><B>local-function</B>*
A function local to a <A HREF="usr_41.html#script">script</A> must start with &quot;s:&quot;.  A local <A HREF="usr_41.html#script">script</A> function
can only be called from within the <A HREF="usr_41.html#script">script</A> and from <A HREF="#functions">functions</A>, user commands
and autocommands defined in the <A HREF="usr_41.html#script">script</A>.  It is also possible to call the
function from a <A HREF="map.html#mapping">mapping</A> defined in the <A HREF="usr_41.html#script">script</A>, but then |<A HREF="map.html#&lt;SID&gt;">&lt;SID&gt;</A>| must be used
instead of &quot;s:&quot; when the <A HREF="map.html#mapping">mapping</A> is expanded outside of the <A HREF="usr_41.html#script">script</A>.
There are only <A HREF="map.html#script-local">script-local</A> <A HREF="#functions">functions</A>, no buffer-local or window-local
<A HREF="#functions">functions</A>.


					*<A NAME=":fu"></A><B>:fu</B>* *<A NAME=":function"></A><B>:function</B>* *<A NAME="E128"></A><B>E128</B>* *<A NAME="E129"></A><B>E129</B>* *<A NAME="E123"></A><B>E123</B>*
:fu[nction]		<A HREF="#List">List</A> all <A HREF="#functions">functions</A> and their arguments.

:fu[nction] {name}	<A HREF="#List">List</A> function {name}.
			{name} can also be a |<A HREF="#Dictionary">Dictionary</A>| entry that is a
			YXXYFuncref|:
<B>				:function dict.init</B>

:fu[nction] /{pattern}	<A HREF="#List">List</A> <A HREF="#functions">functions</A> with a name matching {pattern}.
			Example that lists all <A HREF="#functions">functions</A> ending with &quot;File&quot;:
<B>				:function /File$</B>
 

							*<A NAME=":function-verbose"></A><B>:function-verbose</B>*
When <A HREF="options.html#'verbose'">'verbose'</A> is non-zero, listing a function will also display where <A HREF="motion.html#it">it</A> was
last defined. Example:

<B>    :verbose function SetFileTypeSH</B>
<B>	function SetFileTypeSH(name)</B>
<B>	    Last set from /usr/share/vim/vim-7.0/filetype.vim</B>
 
See |<A HREF="various.html#:verbose-cmd">:verbose-cmd</A>| for more information.


						*<A NAME="E124"></A><B>E124</B>* *<A NAME="E125"></A><B>E125</B>* *<A NAME="E853"></A><B>E853</B>* *<A NAME="E884"></A><B>E884</B>*
:fu[nction][!] {name}([arguments]) <A HREF="cmdline.html#[range]">[range]</A> [abort] [dict]
			Define a new function by the name {name}.  The name
			must be made of alphanumeric characters and '<A HREF="motion.html#_">_</A>', and
			must start with a capital or &quot;s:&quot; (see above).  Note
			that using &quot;<A HREF="#b:">b:</A>&quot; or &quot;<A HREF="#g:">g:</A>&quot; is not allowed. (since patch
			7.4.260 <A HREF="#E884">E884</A> is given if the function name has a colon
			in the name, e.g. for &quot;foo:bar()&quot;.  Before that patch
			no error was given).

			{name} can also be a |<A HREF="#Dictionary">Dictionary</A>| entry that is a
			YXXYFuncref|:
<B>				:function dict.init(arg)</B>
 			&quot;<A HREF="#dict">dict</A>&quot; must be an existing dictionary.	The entry
			&quot;init&quot; is added if <A HREF="motion.html#it">it</A> didn't exist yet.  Otherwise [!]
			is required to overwrite an existing function.	The
			result is a |<A HREF="#Funcref">Funcref</A>| to a numbered function.  The
			function can only be used with a |<A HREF="#Funcref">Funcref</A>| and will be
			deleted if there are no more references to <A HREF="motion.html#it">it</A>.

								*<A NAME="E127"></A><B>E127</B>* *<A NAME="E122"></A><B>E122</B>*
			When a function by this name already exists and [!] is
			not used an error message is given.  When [!] is used,
			an existing function is silently replaced.  Unless <A HREF="motion.html#it">it</A>
			is currently being executed, that is an error.

			For the {arguments} see |<A HREF="#function-argument">function-argument</A>|.


					*<A NAME=":func-range"></A><B>:func-range</B>* *<A NAME="a:firstline"></A><B>a:firstline</B>* *<A NAME="a:lastline"></A><B>a:lastline</B>*
			When the <A HREF="cmdline.html#[range]">[range]</A> argument is added, the function is
			expected to take care of a range itself.  The range is
			passed <A HREF="motion.html#as">as</A> &quot;<A HREF="#a:firstline">a:firstline</A>&quot; and &quot;<A HREF="#a:lastline">a:lastline</A>&quot;.  If <A HREF="cmdline.html#[range]">[range]</A>
			is excluded, &quot;:{range}call&quot; will call the function for
			each line in the range, with the cursor on the start
			of each line.  See |<A HREF="#function-range-example">function-range-example</A>|.
			The cursor is still moved to the first line of the
			range, <A HREF="motion.html#as">as</A> is the <A HREF="change.html#case">case</A> with all <A HREF="intro.html#Ex">Ex</A> commands.

								*<A NAME=":func-abort"></A><B>:func-abort</B>*
			When the [abort] argument is added, the function will
			abort <A HREF="motion.html#as">as</A> soon <A HREF="motion.html#as">as</A> an error is detected.

								*<A NAME=":func-dict"></A><B>:func-dict</B>*
			When the [dict] argument is added, the function must
			be invoked through an entry in a |<A HREF="#Dictionary">Dictionary</A>|.	The
			local variable &quot;<A HREF="#self">self</A>&quot; will then be set to the
			dictionary.  See |<A HREF="#Dictionary-function">Dictionary-function</A>|.


						*<A NAME="function-search-undo"></A><B>function-search-undo</B>*
			The last used search <A HREF="pattern.html#pattern">pattern</A> and the <A HREF="undo.html#redo">redo</A> command &quot;<A HREF="repeat.html#.">.</A>&quot;
			will not be changed by the function.  This also
			implies that the effect of |<A HREF="pattern.html#:nohlsearch">:nohlsearch</A>| is undone
			when the function returns.


					*<A NAME=":endf"></A><B>:endf</B>* *<A NAME=":endfunction"></A><B>:endfunction</B>* *<A NAME="E126"></A><B>E126</B>* *<A NAME="E193"></A><B>E193</B>*
:endf[unction]		The end of a function definition.  Must be on a line
			by its own, without other commands.


					*<A NAME=":delf"></A><B>:delf</B>* *<A NAME=":delfunction"></A><B>:delfunction</B>* *<A NAME="E130"></A><B>E130</B>* *<A NAME="E131"></A><B>E131</B>*
:delf[unction] {name}	Delete function {name}.
			{name} can also be a |<A HREF="#Dictionary">Dictionary</A>| entry that is a
			YXXYFuncref|:
<B>				:delfunc dict.init</B>
 			This will remove the &quot;init&quot; entry from &quot;<A HREF="#dict">dict</A>&quot;.	The
			function is deleted if there are no more references to
			<A HREF="motion.html#it">it</A>.

							*<A NAME=":retu"></A><B>:retu</B>* *<A NAME=":return"></A><B>:return</B>* *<A NAME="E133"></A><B>E133</B>*
:retu[rn] [expr]	Return from a function.  When &quot;[expr]&quot; is given, <A HREF="motion.html#it">it</A> is
			evaluated and returned <A HREF="motion.html#as">as</A> the result of the function.
			If &quot;[expr]&quot; is not given, the number 0 is returned.
			When a function ends without an explicit &quot;<A HREF="#:return">:return</A>&quot;,
			the number 0 is returned.
			Note that there is no check for unreachable lines,
			thus there is no warning if commands follow &quot;<A HREF="#:return">:return</A>&quot;.

			If the &quot;<A HREF="#:return">:return</A>&quot; is used after a |<A HREF="#:try">:try</A>| but before the
			matching |<A HREF="#:finally">:finally</A>| (if present), the commands
			following the &quot;<A HREF="#:finally">:finally</A>&quot; up to the matching |<A HREF="#:endtry">:endtry</A>|
			are executed first.  This process applies to all
			nested &quot;<A HREF="#:try">:try</A>&quot;s inside the function.  The function
			returns at the outermost &quot;<A HREF="#:endtry">:endtry</A>&quot;.


						*<A NAME="function-argument"></A><B>function-argument</B>* *<A NAME="a:var"></A><B>a:var</B>*
An argument can be defined by giving its name.	In the function this can then
be used <A HREF="motion.html#as">as</A> &quot;a:name&quot; (&quot;a:&quot; for argument).

					*<A NAME="a:0"></A><B>a:0</B>* *<A NAME="a:1"></A><B>a:1</B>* *<A NAME="a:000"></A><B>a:000</B>* *<A NAME="E740"></A><B>E740</B>* *<A NAME="..."></A><B>...</B>*
Up to 20 arguments can be given, separated by commas.  After the named
arguments an argument &quot;<A HREF="#...">...</A>&quot; can be specified, which means that more arguments
may optionally be following.  In the function the extra arguments can be used
<A HREF="motion.html#as">as</A> &quot;<A HREF="#a:1">a:1</A>&quot;, &quot;a:2&quot;, etc.  &quot;<A HREF="#a:0">a:0</A>&quot; is set to the number of extra arguments (which
can be 0).  &quot;<A HREF="#a:000">a:000</A>&quot; is set to a |<A HREF="#List">List</A>| that contains these arguments.  Note
that &quot;<A HREF="#a:1">a:1</A>&quot; is the same <A HREF="motion.html#as">as</A> &quot;a:000[0]&quot;.

								*<A NAME="E742"></A><B>E742</B>*
The a: scope and the <A HREF="#variables">variables</A> in <A HREF="motion.html#it">it</A> cannot be changed, they are fixed.
However, if a |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| is used, you can change their contents.
Thus you can pass a |<A HREF="#List">List</A>| to a function and have the function add an item to
<A HREF="motion.html#it">it</A>.  If you want to make sure the function cannot change a |<A HREF="#List">List</A>| or
|<A HREF="#Dictionary">Dictionary</A>| use |<A HREF="#:lockvar">:lockvar</A>|.

When not using &quot;<A HREF="#...">...</A>&quot;, the number of arguments in a function call must be equal
to the number of named arguments.  When using &quot;<A HREF="#...">...</A>&quot;, the number of arguments
may be larger.

It is also possible to define a function without any arguments.  You must
still supply the () then.  The body of the function follows in the next lines,
until the matching |<A HREF="#:endfunction">:endfunction</A>|.  It is allowed to define another function
inside a function body.


							*<A NAME="local-variables"></A><B>local-variables</B>*
Inside a function <A HREF="#variables">variables</A> can be used.  These are local <A HREF="#variables">variables</A>, which
will disappear when the function returns.  Global <A HREF="#variables">variables</A> need to be
accessed with &quot;<A HREF="#g:">g:</A>&quot;.

Example:
<B>  :function Table(title, ...)</B>
<B>  :  echohl Title</B>
<B>  :  echo a:title</B>
<B>  :  echohl None</B>
<B>  :  echo a:0 . " items:"</B>
<B>  :  for s in a:000</B>
<B>  :    echon ' ' . s</B>
<B>  :  endfor</B>
<B>  :endfunction</B>

This function can then be called with:
<B>  call Table("Table", "line1", "line2")</B>
<B>  call Table("Empty Table")</B>

To return more than one value, return a YXXYList|:
<B>  :function Compute(n1, n2)</B>
<B>  :  if a:n2 == 0</B>
<B>  :    return ["fail", 0]</B>
<B>  :  endif</B>
<B>  :  return ["ok", a:n1 / a:n2]</B>
<B>  :endfunction</B>

This function can then be called with:
<B>  :let [success, div] = Compute(102, 6)</B>
<B>  :if success == "ok"</B>
<B>  :  echo div</B>
<B>  :endif</B>
 

						*<A NAME=":cal"></A><B>:cal</B>* *<A NAME=":call"></A><B>:call</B>* *<A NAME="E107"></A><B>E107</B>* *<A NAME="E117"></A><B>E117</B>*
:[range]cal[l] {name}([arguments])
		Call a function.  The name of the function and its arguments
		are <A HREF="motion.html#as">as</A> specified with |<A HREF="#:function">:function</A>|.  Up to 20 arguments can be
		used.  The returned value is discarded.
		Without a range and for <A HREF="#functions">functions</A> that accept a range, the
		function is called once.  When a range is given the cursor is
		positioned at the start of the first line before executing the
		function.
		When a range is given and the function doesn't handle <A HREF="motion.html#it">it</A>
		itself, the function is executed for each line in the range,
		with the cursor in the first column of that line.  The cursor
		is left at the last line (possibly moved by the last function
		call).	The arguments are re-evaluated for each line.  Thus
		this works:

						*<A NAME="function-range-example"></A><B>function-range-example</B>* 
<B>	:function Mynumber(arg)</B>
<B>	:  echo line(".") . " " . a:arg</B>
<B>	:endfunction</B>
<B>	:1,5call Mynumber(getline("."))</B>
 
		The &quot;<A HREF="#a:firstline">a:firstline</A>&quot; and &quot;<A HREF="#a:lastline">a:lastline</A>&quot; are defined anyway, they
		can be used to <A HREF="diff.html#do">do</A> something different at the start or end of
		the range.

		Example of a function that handles the range itself:

<B>	:function Cont() range</B>
<B>	:  execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '</B>
<B>	:endfunction</B>
<B>	:4,8call Cont()</B>
 
		This function inserts the continuation character &quot;\&quot; in front
		of all the lines in the range, except the first one.

		When the function returns a composite value <A HREF="motion.html#it">it</A> can be further
		dereferenced, but the range will not be used then.  Example:
<B>	:4,8call GetDict().method()</B>
 		Here GetDict() gets the range but method() does not.


								*<A NAME="E132"></A><B>E132</B>*
The recursiveness of user <A HREF="#functions">functions</A> is restricted with the |<A HREF="options.html#'maxfuncdepth'">'maxfuncdepth'</A>|
option.


<B><FONT COLOR="PURPLE">AUTOMATICALLY LOADING FUNCTIONS </FONT></B>

							*<A NAME="autoload-functions"></A><B>autoload-functions</B>*
When using many or large <A HREF="#functions">functions</A>, it's possible to automatically define them
only when they are used.  There are two methods: with an <A HREF="autocmd.html#autocommand">autocommand</A> and with
the &quot;<A HREF="#autoload">autoload</A>&quot; directory in <A HREF="options.html#'runtimepath'">'runtimepath'</A>.


<B><FONT COLOR="PURPLE">Using an autocommand </FONT></B>

This is introduced in the user manual, section |<A HREF="usr_41.html#41.14">41.14</A>|.

The <A HREF="autocmd.html#autocommand">autocommand</A> is useful if you have a <A HREF="usr_05.html#plugin">plugin</A> that is a long Vim <A HREF="usr_41.html#script">script</A> file.
You can define the <A HREF="autocmd.html#autocommand">autocommand</A> and quickly quit the <A HREF="usr_41.html#script">script</A> with |<A HREF="repeat.html#:finish">:finish</A>|.
That makes Vim <A HREF="starting.html#startup">startup</A> faster.	The <A HREF="autocmd.html#autocommand">autocommand</A> should then load the same file
again, setting a variable to skip the |<A HREF="repeat.html#:finish">:finish</A>| command.

Use the <A HREF="autocmd.html#FuncUndefined">FuncUndefined</A> <A HREF="autocmd.html#autocommand">autocommand</A> event with a <A HREF="pattern.html#pattern">pattern</A> that matches the
function(s) to be defined.  Example:

<B>	:au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim</B>

The file &quot;~/vim/bufnetfuncs.vim&quot; should then define <A HREF="#functions">functions</A> that start with
&quot;BufNet&quot;.  Also see |<A HREF="autocmd.html#FuncUndefined">FuncUndefined</A>|.


<B><FONT COLOR="PURPLE">Using an autoload script </FONT></B>

							*<A NAME="autoload"></A><B>autoload</B>* *<A NAME="E746"></A><B>E746</B>*
This is introduced in the user manual, section |<A HREF="usr_41.html#41.15">41.15</A>|.

Using a <A HREF="usr_41.html#script">script</A> in the &quot;<A HREF="#autoload">autoload</A>&quot; directory is simpler, but requires using
exactly the right file name.  A function that can be autoloaded has a name
like this:

<B>	:call filename#funcname()</B>

When such a function is called, and <A HREF="motion.html#it">it</A> is not defined yet, Vim will search the
&quot;<A HREF="#autoload">autoload</A>&quot; directories in <A HREF="options.html#'runtimepath'">'runtimepath'</A> for a <A HREF="usr_41.html#script">script</A> file called
&quot;filename.vim&quot;.  For example &quot;~/.vim/autoload/filename.vim&quot;.  That file should
then define the function like this:

<B>	function filename#funcname()</B>
<B>	   echo "Done!"</B>
<B>	endfunction</B>

The file name and the name used before the # in the function must match
exactly, and the defined function must have the name exactly <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> will be
called.

It is possible to use subdirectories.  Every # in the function name works like
a path separator.  Thus when calling a function:

<B>	:call foo#bar#func()</B>

Vim will look for the file &quot;autoload/foo/bar.vim&quot; in <A HREF="options.html#'runtimepath'">'runtimepath'</A>.

This also works when reading a variable that has not been set yet:

<B>	:let l = foo#bar#lvar</B>

However, when the <A HREF="#autoload">autoload</A> <A HREF="usr_41.html#script">script</A> was already loaded <A HREF="motion.html#it">it</A> won't be loaded again
for an unknown variable.

When assigning a value to such a variable nothing special happens.  This can
be used to pass settings to the <A HREF="#autoload">autoload</A> <A HREF="usr_41.html#script">script</A> before it's loaded:

<B>	:let foo#bar#toggle = 1</B>
<B>	:call foo#bar#func()</B>

Note that when you make a mistake and call a function that is supposed to be
defined in an <A HREF="#autoload">autoload</A> <A HREF="usr_41.html#script">script</A>, but the <A HREF="usr_41.html#script">script</A> doesn't actually define the
function, the <A HREF="usr_41.html#script">script</A> will be sourced every time you try to call the function.
And you will get an error message every time.

Also note that if you have two <A HREF="usr_41.html#script">script</A> files, and one calls a function in the
other and vice versa, before the used function is defined, <A HREF="motion.html#it">it</A> won't work.
Avoid using the <A HREF="#autoload">autoload</A> functionality at the toplevel.

Hint: If you distribute a bunch of scripts you can pack them together with the
|<A HREF="pi_vimball.html#vimball">vimball</A>| utility.  Also read the user manual |<A HREF="usr_41.html#distribute-script">distribute-script</A>|.

==============================================================================

6. Curly braces names					*<A NAME="curly-braces-names"></A><B>curly-braces-names</B>*

In most places where you can use a variable, you can use a &quot;curly braces name&quot;
variable.  This is a regular variable name with one or more expressions
wrapped in braces <A HREF="intro.html#{}">{}</A> like this:
<B>	my_{adjective}_variable</B>

When Vim encounters this, <A HREF="motion.html#it">it</A> evaluates the <A HREF="#expression">expression</A> inside the braces, puts
that in place of the <A HREF="#expression">expression</A>, and re-interprets the whole <A HREF="motion.html#as">as</A> a variable
name.  So in the above example, if the variable &quot;adjective&quot; was set to
&quot;noisy&quot;, then the reference would be to &quot;my_noisy_variable&quot;, whereas if
&quot;adjective&quot; was set to &quot;quiet&quot;, then <A HREF="motion.html#it">it</A> would be to &quot;my_quiet_variable&quot;.

One application for this is to create a set of <A HREF="#variables">variables</A> governed by an option
value.	For example, the statement
<B>	echo my_{&amp;background}_message</B>

would output the contents of &quot;my_dark_message&quot; or &quot;my_light_message&quot; depending
on the current value of <A HREF="options.html#'background'">'background'</A>.

You can use multiple brace pairs:
<B>	echo my_{adverb}_{adjective}_message</B>
..or even nest them:
<B>	echo my_{ad{end_of_word}}_message</B>
where &quot;end_of_word&quot; is either &quot;verb&quot; or &quot;jective&quot;.

However, the <A HREF="#expression">expression</A> inside the braces must evaluate to a valid single
variable name, e.g. this is invalid:
<B>	:let foo='a + b'</B>
<B>	:echo c{foo}d</B>
.. since the result of expansion is &quot;ca + bd&quot;, which is not a variable name.


						*<A NAME="curly-braces-function-names"></A><B>curly-braces-function-names</B>*
You can call and define <A HREF="#functions">functions</A> by an evaluated name in a similar way.
Example:
<B>	:let func_end='whizz'</B>
<B>	:call my_func_{func_end}(parameter)</B>

This would call the function &quot;my_func_whizz(parameter)&quot;.

This does NOT work:
<B>  :let i = 3</B>
<B>  :let @{i} = ''  " error</B>
<B>  :echo @{i}      " error</B>

==============================================================================

7. Commands						*<A NAME="expression-commands"></A><B>expression-commands</B>*


<A HREF="#:let">:let</A> {var-name} = {expr1}				*<A NAME=":let"></A><B>:let</B>* *<A NAME="E18"></A><B>E18</B>*
			Set internal variable {var-name} to the result of the
			<A HREF="#expression">expression</A> {expr1}.  The variable will get the type
			from the {expr}.  If {var-name} didn't exist yet, <A HREF="motion.html#it">it</A>
			is created.


<A HREF="#:let">:let</A> {var-name}[{idx}] = {expr1}			*<A NAME="E689"></A><B>E689</B>*
			Set a <A HREF="#list">list</A> item to the result of the <A HREF="#expression">expression</A>
			{expr1}.  {var-name} must refer to a <A HREF="#list">list</A> and {idx}
			must be a valid index in that <A HREF="#list">list</A>.  For nested <A HREF="#list">list</A>
			the index can be repeated.
			This cannot be used to add an item to a |<A HREF="#List">List</A>|.
			This cannot be used to set a byte in a <A HREF="#String">String</A>.	You
			can <A HREF="diff.html#do">do</A> that like this:
<B>				:let var = var[0:2] . 'X' . var[4:]</B>
 

							*<A NAME="E711"></A><B>E711</B>* *<A NAME="E719"></A><B>E719</B>*

<A HREF="#:let">:let</A> {var-name}[{idx1}:{idx2}] = {expr1}		*<A NAME="E708"></A><B>E708</B>* *<A NAME="E709"></A><B>E709</B>* *<A NAME="E710"></A><B>E710</B>*
			Set a sequence of items in a |<A HREF="#List">List</A>| to the result of
			the <A HREF="#expression">expression</A> {expr1}, which must be a <A HREF="#list">list</A> with the
			correct number of items.
			{idx1} can be omitted, zero is used instead.
			{idx2} can be omitted, meaning the end of the <A HREF="#list">list</A>.
			When the selected range of items is partly past the
			end of the <A HREF="#list">list</A>, items will be added.


					*<A NAME=":let+="></A><B>:let+=</B>* *<A NAME=":let-="></A><B>:let-=</B>* *<A NAME=":let.="></A><B>:let.=</B>* *<A NAME="E734"></A><B>E734</B>*
<A HREF="#:let">:let</A> {var} += {expr1}	Like &quot;<A HREF="#:let">:let</A> {var} = {var} + {expr1}&quot;.
<A HREF="#:let">:let</A> {var} -= {expr1}	Like &quot;<A HREF="#:let">:let</A> {var} = {var} - {expr1}&quot;.
<A HREF="#:let">:let</A> {var} .= {expr1}	Like &quot;<A HREF="#:let">:let</A> {var} = {var} . {expr1}&quot;.
			These fail if {var} was not set yet and when the type
			of {var} and {expr1} don't fit the <A HREF="motion.html#operator">operator</A>.



<A HREF="#:let">:let</A> ${env-name} = {expr1}			*<A NAME=":let-environment"></A><B>:let-environment</B>* *<A NAME=":let-$"></A><B>:let-$</B>*
			Set environment variable {env-name} to the result of
			the <A HREF="#expression">expression</A> {expr1}.  The type is always <A HREF="#String">String</A>.
<A HREF="#:let">:let</A> ${env-name} .= {expr1}
			Append {expr1} to the environment variable {env-name}.
			If the environment variable didn't exist yet this
			works like &quot;<A HREF="change.html#=">=</A>&quot;.


<A HREF="#:let">:let</A> @{reg-name} = {expr1}			*<A NAME=":let-register"></A><B>:let-register</B>* *<A NAME=":let-@"></A><B>:let-@</B>*
			Write the result of the <A HREF="#expression">expression</A> {expr1} in <A HREF="sponsor.html#register">register</A>
			{reg-name}.  {reg-name} must be a single <A HREF="print.html#letter">letter</A>, and
			must be the name of a writable <A HREF="sponsor.html#register">register</A> (see
			|<A HREF="change.html#registers">registers</A>|).  &quot;<A HREF="repeat.html#@@">@@</A>&quot; can be used for the unnamed
			<A HREF="sponsor.html#register">register</A>, &quot;<A HREF="change.html#@/">@/</A>&quot; for the search <A HREF="pattern.html#pattern">pattern</A>.
			If the result of {expr1} ends in a <A HREF="motion.html#&lt;CR&gt;">&lt;CR&gt;</A> or <A HREF="motion.html#&lt;NL&gt;">&lt;NL&gt;</A>, the
			<A HREF="sponsor.html#register">register</A> will be <A HREF="motion.html#linewise">linewise</A>, otherwise <A HREF="motion.html#it">it</A> will be set to
			<A HREF="motion.html#characterwise">characterwise</A>.
			This can be used to clear the last search <A HREF="pattern.html#pattern">pattern</A>:
<B>				:let @/ = ""</B>
 			This is different from searching for an empty <A HREF="#string">string</A>,
			that would match everywhere.

<A HREF="#:let">:let</A> @{reg-name} .= {expr1}
			Append {expr1} to <A HREF="sponsor.html#register">register</A> {reg-name}.	If the
			<A HREF="sponsor.html#register">register</A> was empty it's like setting <A HREF="motion.html#it">it</A> to {expr1}.


<A HREF="#:let">:let</A> &amp;{option-name} = {expr1}			*<A NAME=":let-option"></A><B>:let-option</B>* *<A NAME=":let-&amp;"></A><B>:let-&amp;</B>*
			Set option {option-name} to the result of the
			<A HREF="#expression">expression</A> {expr1}.  A <A HREF="#String">String</A> or <A HREF="#Number">Number</A> value is
			always converted to the type of the option.
			For an option local to a <A HREF="windows.html#window">window</A> or buffer the effect
			is just like using the |<A HREF="options.html#:set">:set</A>| command: both the local
			value and the global value are changed.
			Example:
<B>				:let &amp;path = &amp;path . ',/usr/local/include'</B>

<A HREF="#:let">:let</A> &amp;{option-name} .= {expr1}
			For a <A HREF="#string">string</A> option: Append {expr1} to the value.
			Does not insert a comma like |<A HREF="options.html#:set+=">:set+=</A>|.

<A HREF="#:let">:let</A> &amp;{option-name} += {expr1}
<A HREF="#:let">:let</A> &amp;{option-name} -= {expr1}
			For a number or <A HREF="options.html#boolean">boolean</A> option: Add or subtract
			{expr1}.

<A HREF="#:let">:let</A> &amp;l:{option-name} = {expr1}
<A HREF="#:let">:let</A> &amp;l:{option-name} .= {expr1}
<A HREF="#:let">:let</A> &amp;l:{option-name} += {expr1}
<A HREF="#:let">:let</A> &amp;l:{option-name} -= {expr1}
			Like above, but only set the local value of an option
			(if there is one).  Works like |<A HREF="options.html#:setlocal">:setlocal</A>|.

<A HREF="#:let">:let</A> &amp;g:{option-name} = {expr1}
<A HREF="#:let">:let</A> &amp;g:{option-name} .= {expr1}
<A HREF="#:let">:let</A> &amp;g:{option-name} += {expr1}
<A HREF="#:let">:let</A> &amp;g:{option-name} -= {expr1}
			Like above, but only set the global value of an option
			(if there is one).  Works like |<A HREF="options.html#:setglobal">:setglobal</A>|.


<A HREF="#:let">:let</A> [{name1}, {name2}, ...] = {expr1}		*<A NAME=":let-unpack"></A><B>:let-unpack</B>* *<A NAME="E687"></A><B>E687</B>* *<A NAME="E688"></A><B>E688</B>*
			{expr1} must evaluate to a |<A HREF="#List">List</A>|.  The first item in
			the <A HREF="#list">list</A> is assigned to {name1}, the second item to
			{name2}, etc.
			The number of names must match the number of items in
			the |<A HREF="#List">List</A>|.
			Each name can be one of the items of the &quot;<A HREF="#:let">:let</A>&quot;
			command <A HREF="motion.html#as">as</A> mentioned above.
			Example:
<B>				:let [s, item] = GetItem(s)</B>
 			Detail: {expr1} is evaluated first, then the
			assignments are done in sequence.  This matters if
			{name2} depends on {name1}.  Example:
<B>				:let x = [0, 1]</B>
<B>				:let i = 0</B>
<B>				:let [i, x[i]] = [1, 2]</B>
<B>				:echo x</B>
 			The result is [0, 2].

<A HREF="#:let">:let</A> [{name1}, {name2}, ...] .= {expr1}
<A HREF="#:let">:let</A> [{name1}, {name2}, ...] += {expr1}
<A HREF="#:let">:let</A> [{name1}, {name2}, ...] -= {expr1}
			Like above, but append/add/subtract the value for each
			|<A HREF="#List">List</A>| item.

<A HREF="#:let">:let</A> [{name}, <A HREF="#...">...</A>, ; {lastname}] = {expr1}
			Like |<A HREF="#:let-unpack">:let-unpack</A>| above, but the |<A HREF="#List">List</A>| may have more
			items than there are names.  A <A HREF="#list">list</A> of the remaining
			items is assigned to {lastname}.  If there are no
			remaining items {lastname} is set to an empty <A HREF="#list">list</A>.
			Example:
<B>				:let [a, b; rest] = ["aval", "bval", 3, 4]</B>
 
<A HREF="#:let">:let</A> [{name}, <A HREF="#...">...</A>, ; {lastname}] .= {expr1}
<A HREF="#:let">:let</A> [{name}, <A HREF="#...">...</A>, ; {lastname}] += {expr1}
<A HREF="#:let">:let</A> [{name}, <A HREF="#...">...</A>, ; {lastname}] -= {expr1}
			Like above, but append/add/subtract the value for each
			|<A HREF="#List">List</A>| item.


								*<A NAME="E121"></A><B>E121</B>*
<A HREF="#:let">:let</A> {var-name}	..	<A HREF="#List">List</A> the value of variable {var-name}.	Multiple
			variable names may be given.  <A HREF="#Special">Special</A> names recognized

			here:				*<A NAME="E738"></A><B>E738</B>*
			  <A HREF="#g:">g:</A>	global <A HREF="#variables">variables</A>
			  <A HREF="#b:">b:</A>	local buffer <A HREF="#variables">variables</A>
			  <A HREF="#w:">w:</A>	local <A HREF="windows.html#window">window</A> <A HREF="#variables">variables</A>
			  <A HREF="#t:">t:</A>	local <A HREF="intro.html#tab">tab</A> page <A HREF="#variables">variables</A>
			  <A HREF="change.html#s">s</A>:	<A HREF="map.html#script-local">script-local</A> <A HREF="#variables">variables</A>
			  <A HREF="#l:">l:</A>	local function <A HREF="#variables">variables</A>
			  <A HREF="#v:">v:</A>	Vim <A HREF="#variables">variables</A>.

<A HREF="#:let">:let</A>			<A HREF="#List">List</A> the values of all <A HREF="#variables">variables</A>.  The type of the
			variable is indicated before the value:
			    &lt;nothing&gt;	<A HREF="#String">String</A>
				#	<A HREF="#Number">Number</A>
				&#42;	<A HREF="#Funcref">Funcref</A>



:unl[et][!] {name} <A HREF="#...">...</A>				*<A NAME=":unlet"></A><B>:unlet</B>* *<A NAME=":unl"></A><B>:unl</B>* *<A NAME="E108"></A><B>E108</B>* *<A NAME="E795"></A><B>E795</B>*
			Remove the internal variable {name}.  Several variable
			names can be given, they are all removed.  The name
			may also be a |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| item.
			With [!] no error message is given for non-existing
			<A HREF="#variables">variables</A>.
			One or more items from a |<A HREF="#List">List</A>| can be removed:
<B>				:unlet list[3]	  " remove fourth item</B>
<B>				:unlet list[3:]   " remove fourth item to last</B>
 			One item from a |<A HREF="#Dictionary">Dictionary</A>| can be removed at a time:
<B>				:unlet dict['two']</B>
<B>				:unlet dict.two</B>
 			This is especially useful to clean up used global
			<A HREF="#variables">variables</A> and <A HREF="map.html#script-local">script-local</A> <A HREF="#variables">variables</A> (these are not
			deleted when the <A HREF="usr_41.html#script">script</A> ends).  Function-local
			<A HREF="#variables">variables</A> are automatically deleted when the function
			ends.


:lockv[ar][!] [depth] {name} <A HREF="#...">...</A>			*<A NAME=":lockvar"></A><B>:lockvar</B>* *<A NAME=":lockv"></A><B>:lockv</B>*
			Lock the internal variable {name}.  Locking means that
			<A HREF="motion.html#it">it</A> can no longer be changed (until <A HREF="motion.html#it">it</A> is unlocked).
			A locked variable can be deleted:
<B>				:lockvar v</B>
<B>				:let v = 'asdf'		" fails!</B>
<B>				:unlet v</B>

 							*<A NAME="E741"></A><B>E741</B>*
			If you try to change a locked variable you get an
			error message: &quot;E741: Value is locked: {name}&quot;

			[depth] is relevant when locking a |<A HREF="#List">List</A>| or
			|<A HREF="#Dictionary">Dictionary</A>|.  It specifies how deep the locking goes:
				1	Lock the |<A HREF="#List">List</A>| or |<A HREF="#Dictionary">Dictionary</A>| itself,
					cannot add or remove items, but can
					still change their values.
				2	Also lock the values, cannot change
					the items.  If an item is a |<A HREF="#List">List</A>| or
					|<A HREF="#Dictionary">Dictionary</A>|, cannot add or remove
					items, but can still change the
					values.
				3	Like 2 but for the |<A HREF="#List">List</A>| /
					|<A HREF="#Dictionary">Dictionary</A>| in the |<A HREF="#List">List</A>| /
					|<A HREF="#Dictionary">Dictionary</A>|, one level deeper.
			The default [depth] is 2, thus when {name} is a |<A HREF="#List">List</A>|
			or |<A HREF="#Dictionary">Dictionary</A>| the values cannot be changed.

								*<A NAME="E743"></A><B>E743</B>*
			For unlimited depth use [!] and omit [depth].
			However, there is a maximum depth of 100 to catch
			loops.

			Note that when two <A HREF="#variables">variables</A> refer to the same |<A HREF="#List">List</A>|
			and you lock one of them, the |<A HREF="#List">List</A>| will also be
			locked when used through the other variable.
			Example:
<B>				:let l = [0, 1, 2, 3]</B>
<B>				:let cl = l</B>
<B>				:lockvar l</B>
<B>				:let cl[1] = 99		" won't work!</B>
 			You may want to make a copy of a <A HREF="#list">list</A> to avoid this.
			See |<A HREF="#deepcopy()">deepcopy()</A>|.



:unlo[ckvar][!] [depth] {name} <A HREF="#...">...</A>			*<A NAME=":unlockvar"></A><B>:unlockvar</B>* *<A NAME=":unlo"></A><B>:unlo</B>*
			Unlock the internal variable {name}.  Does the
			opposite of |<A HREF="#:lockvar">:lockvar</A>|.



<A HREF="#:if">:if</A> {expr1}			*<A NAME=":if"></A><B>:if</B>* *<A NAME=":endif"></A><B>:endif</B>* *<A NAME=":en"></A><B>:en</B>* *<A NAME="E171"></A><B>E171</B>* *<A NAME="E579"></A><B>E579</B>* *<A NAME="E580"></A><B>E580</B>*
:en[dif]		Execute the commands until the next matching &quot;<A HREF="#:else">:else</A>&quot;
			or &quot;<A HREF="#:endif">:endif</A>&quot; if {expr1} evaluates to non-zero.

			From Vim version 4.5 until 5.0, every <A HREF="intro.html#Ex">Ex</A> command in
			between the &quot;<A HREF="#:if">:if</A>&quot; and &quot;<A HREF="#:endif">:endif</A>&quot; is ignored.  These two
			commands were just to allow for future expansions in a
			backward compatible way.  Nesting was allowed.  Note
			that any &quot;<A HREF="#:else">:else</A>&quot; or &quot;<A HREF="#:elseif">:elseif</A>&quot; was ignored, the &quot;else&quot;
			part was not executed either.

			You can use this to remain compatible with older
			versions:
<B>				:if version &gt;= 500</B>
<B>				:  version-5-specific-commands</B>
<B>				:endif</B>
 			The commands still need to be parsed to find the
			&quot;endif&quot;.  Sometimes an older Vim has a problem with a
			new command.  For example, &quot;<A HREF="various.html#:silent">:silent</A>&quot; is recognized <A HREF="motion.html#as">as</A>
			a &quot;<A HREF="change.html#:substitute">:substitute</A>&quot; command.  In that <A HREF="change.html#case">case</A> &quot;<A HREF="#:execute">:execute</A>&quot; can
			avoid problems:
<B>				:if version &gt;= 600</B>
<B>				:  execute "silent 1,$delete"</B>
<B>				:endif</B>
 
			NOTE: The &quot;<A HREF="insert.html#:append">:append</A>&quot; and &quot;<A HREF="insert.html#:insert">:insert</A>&quot; commands don't work
			properly in between &quot;<A HREF="#:if">:if</A>&quot; and &quot;<A HREF="#:endif">:endif</A>&quot;.


						*<A NAME=":else"></A><B>:else</B>* *<A NAME=":el"></A><B>:el</B>* *<A NAME="E581"></A><B>E581</B>* *<A NAME="E583"></A><B>E583</B>*
:el[se]			Execute the commands until the next matching &quot;<A HREF="#:else">:else</A>&quot;
			or &quot;<A HREF="#:endif">:endif</A>&quot; if they previously were not being
			executed.


					*<A NAME=":elseif"></A><B>:elseif</B>* *<A NAME=":elsei"></A><B>:elsei</B>* *<A NAME="E582"></A><B>E582</B>* *<A NAME="E584"></A><B>E584</B>*
:elsei[f] {expr1}	Short for &quot;<A HREF="#:else">:else</A>&quot; &quot;<A HREF="#:if">:if</A>&quot;, with the addition that there
			is no extra &quot;<A HREF="#:endif">:endif</A>&quot;.


:wh[ile] {expr1}			*<A NAME=":while"></A><B>:while</B>* *<A NAME=":endwhile"></A><B>:endwhile</B>* *<A NAME=":wh"></A><B>:wh</B>* *<A NAME=":endw"></A><B>:endw</B>*

						*<A NAME="E170"></A><B>E170</B>* *<A NAME="E585"></A><B>E585</B>* *<A NAME="E588"></A><B>E588</B>* *<A NAME="E733"></A><B>E733</B>*
:endw[hile]		Repeat the commands between &quot;<A HREF="#:while">:while</A>&quot; and &quot;<A HREF="#:endwhile">:endwhile</A>&quot;,
			<A HREF="motion.html#as">as</A> long <A HREF="motion.html#as">as</A> {expr1} evaluates to non-zero.
			When an error is detected from a command inside the
			loop, execution continues after the &quot;endwhile&quot;.
			Example:
<B>				:let lnum = 1</B>
<B>				:while lnum &lt;= line("$")</B>
<B>				   :call FixLine(lnum)</B>
<B>				   :let lnum = lnum + 1</B>
<B>				:endwhile</B>
 
			NOTE: The &quot;<A HREF="insert.html#:append">:append</A>&quot; and &quot;<A HREF="insert.html#:insert">:insert</A>&quot; commands don't work
			properly inside a &quot;<A HREF="#:while">:while</A>&quot; and &quot;<A HREF="#:for">:for</A>&quot; loop.


<A HREF="#:for">:for</A> {var} in {list}					*<A NAME=":for"></A><B>:for</B>* *<A NAME="E690"></A><B>E690</B>* *<A NAME="E732"></A><B>E732</B>*

:endfo[r]						*<A NAME=":endfo"></A><B>:endfo</B>* *<A NAME=":endfor"></A><B>:endfor</B>*
			Repeat the commands between &quot;<A HREF="#:for">:for</A>&quot; and &quot;<A HREF="#:endfor">:endfor</A>&quot; for
			each item in {list}.  Variable {var} is set to the
			value of each item.
			When an error is detected for a command inside the
			loop, execution continues after the &quot;endfor&quot;.
			Changing {list} inside the loop affects what items are
			used.  Make a copy if this is unwanted:
<B>				:for item in copy(mylist)</B>
 			When not making a copy, Vim stores a reference to the
			next item in the <A HREF="#list">list</A>, before executing the commands
			with the current item.	Thus the current item can be
			removed without effect.  Removing any later item means
			<A HREF="motion.html#it">it</A> will not be found.  Thus the following example
			works (an inefficient way to make a <A HREF="#list">list</A> empty):
<B>				for item in mylist</B>
<B>				   call remove(mylist, 0)</B>
<B>				endfor</B>
 			Note that reordering the <A HREF="#list">list</A> (e.g., with <A HREF="#sort()">sort()</A> or
			<A HREF="#reverse()">reverse()</A>) may have unexpected effects.
			Note that the type of each <A HREF="#list">list</A> item should be
			identical to avoid <A HREF="message.html#errors">errors</A> for the type of {var}
			<A HREF="change.html#changing">changing</A>.  Unlet the variable at the end of the loop
			to allow multiple item types:
<B>				for item in ["foo", ["bar"]]</B>
<B>				   echo item</B>
<B>				   unlet item  " E706 without this</B>
<B>				endfor</B>

<A HREF="#:for">:for</A> [{var1}, {var2}, ...] in {listlist}
:endfo[r]
			Like &quot;<A HREF="#:for">:for</A>&quot; above, but each item in {listlist} must be
			a <A HREF="#list">list</A>, of which each item is assigned to {var1},
			{var2}, etc.  Example:
<B>				:for [lnum, col] in [[1, 3], [2, 5], [3, 8]]</B>
<B>				   :echo getline(lnum)[col]</B>
<B>				:endfor</B>
 

						*<A NAME=":continue"></A><B>:continue</B>* *<A NAME=":con"></A><B>:con</B>* *<A NAME="E586"></A><B>E586</B>*
:con[tinue]		When used inside a &quot;<A HREF="#:while">:while</A>&quot; or &quot;<A HREF="#:for">:for</A>&quot; loop, jumps back
			to the start of the loop.
			If <A HREF="motion.html#it">it</A> is used after a |<A HREF="#:try">:try</A>| inside the loop but
			before the matching |<A HREF="#:finally">:finally</A>| (if present), the
			commands following the &quot;<A HREF="#:finally">:finally</A>&quot; up to the matching
			|<A HREF="#:endtry">:endtry</A>| are executed first.  This process applies to
			all nested &quot;<A HREF="#:try">:try</A>&quot;s inside the loop.  The outermost
			&quot;<A HREF="#:endtry">:endtry</A>&quot; then jumps back to the start of the loop.


						*<A NAME=":break"></A><B>:break</B>* *<A NAME=":brea"></A><B>:brea</B>* *<A NAME="E587"></A><B>E587</B>*
:brea[k]		When used inside a &quot;<A HREF="#:while">:while</A>&quot; or &quot;<A HREF="#:for">:for</A>&quot; loop, skips to
			the command after the matching &quot;<A HREF="#:endwhile">:endwhile</A>&quot; or
			&quot;<A HREF="#:endfor">:endfor</A>&quot;.
			If <A HREF="motion.html#it">it</A> is used after a |<A HREF="#:try">:try</A>| inside the loop but
			before the matching |<A HREF="#:finally">:finally</A>| (if present), the
			commands following the &quot;<A HREF="#:finally">:finally</A>&quot; up to the matching
			|<A HREF="#:endtry">:endtry</A>| are executed first.  This process applies to
			all nested &quot;<A HREF="#:try">:try</A>&quot;s inside the loop.  The outermost
			&quot;<A HREF="#:endtry">:endtry</A>&quot; then jumps to the command after the loop.


<A HREF="#:try">:try</A>				*<A NAME=":try"></A><B>:try</B>* *<A NAME=":endt"></A><B>:endt</B>* *<A NAME=":endtry"></A><B>:endtry</B>* *<A NAME="E600"></A><B>E600</B>* *<A NAME="E601"></A><B>E601</B>* *<A NAME="E602"></A><B>E602</B>*
:endt[ry]		Change the error handling for the commands between
			&quot;<A HREF="#:try">:try</A>&quot; and &quot;<A HREF="#:endtry">:endtry</A>&quot; including everything being
			executed across &quot;<A HREF="repeat.html#:source">:source</A>&quot; commands, function calls,
			or <A HREF="autocmd.html#autocommand">autocommand</A> invocations.

			When an error or interrupt is detected and there is
			a |<A HREF="#:finally">:finally</A>| command following, execution continues
			after the &quot;<A HREF="#:finally">:finally</A>&quot;.  Otherwise, or when the
			&quot;<A HREF="#:endtry">:endtry</A>&quot; is reached thereafter, the next
			(dynamically) surrounding &quot;<A HREF="#:try">:try</A>&quot; is checked for
			a corresponding &quot;<A HREF="#:finally">:finally</A>&quot; etc.  Then the <A HREF="usr_41.html#script">script</A>
			processing is terminated.  (Whether a function
			definition has an &quot;abort&quot; argument does not matter.)
			Example:
<B>		:try | edit too much | finally | echo "cleanup" | endtry</B>
<B>		:echo "impossible"	" not reached, script terminated above</B>
 
			Moreover, an error or interrupt (dynamically) inside
			&quot;<A HREF="#:try">:try</A>&quot; and &quot;<A HREF="#:endtry">:endtry</A>&quot; is converted to an exception.  It
			can be caught <A HREF="motion.html#as">as</A> if <A HREF="motion.html#it">it</A> were thrown by a |<A HREF="#:throw">:throw</A>|
			command (see |<A HREF="#:catch">:catch</A>|).  In this <A HREF="change.html#case">case</A>, the <A HREF="usr_41.html#script">script</A>
			processing is not terminated.

			The value &quot;Vim:Interrupt&quot; is used for an interrupt
			exception.  An error in a Vim command is converted
			to a value of the form &quot;Vim({command}):{errmsg}&quot;,
			other <A HREF="message.html#errors">errors</A> are converted to a value of the form
			&quot;Vim:{errmsg}&quot;.  {command} is the full command name,
			and {errmsg} is the message that is displayed if the
			error exception is not caught, always beginning with
			the error number.
			Examples:
<B>		:try | sleep 100 | catch /^Vim:Interrupt$/ | endtry</B>
<B>		:try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry</B>
 

					*<A NAME=":cat"></A><B>:cat</B>* *<A NAME=":catch"></A><B>:catch</B>* *<A NAME="E603"></A><B>E603</B>* *<A NAME="E604"></A><B>E604</B>* *<A NAME="E605"></A><B>E605</B>*
:cat[ch] /{pattern}/	The following commands until the next |<A HREF="#:catch">:catch</A>|,
			|<A HREF="#:finally">:finally</A>|, or |<A HREF="#:endtry">:endtry</A>| that belongs to the same
			|<A HREF="#:try">:try</A>| <A HREF="motion.html#as">as</A> the &quot;<A HREF="#:catch">:catch</A>&quot; are executed when an exception
			matching {pattern} is being thrown and has not yet
			been caught by a previous &quot;<A HREF="#:catch">:catch</A>&quot;.  Otherwise, these
			commands are skipped.
			When {pattern} is omitted all <A HREF="message.html#errors">errors</A> are caught.
			Examples:
<B>		:catch /^Vim:Interrupt$/	" catch interrupts (CTRL-C)</B>
<B>		:catch /^Vim\%((\a\+)\)\=:E/	" catch all Vim errors</B>
<B>		:catch /^Vim\%((\a\+)\)\=:/	" catch errors and interrupts</B>
<B>		:catch /^Vim(write):/		" catch all errors in :write</B>
<B>		:catch /^Vim\%((\a\+)\)\=:E123/	" catch error E123</B>
<B>		:catch /my-exception/		" catch user exception</B>
<B>		:catch /.*/			" catch everything</B>
<B>		:catch				" same as /.*/</B>
 
			Another character can be used instead of / around the
			{pattern}, so long <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> does not have a special
			meaning (e.g., '&#124;' or &#39;&#34;'') and doesn't occur inside
			{pattern}.
			Information about the exception is available in
			|<A HREF="#v:exception">v:exception</A>|.  Also see |<A HREF="#throw-variables">throw-variables</A>|.
			NOTE: It is not reliable to &quot;<A HREF="#:catch">:catch</A>&quot; the TEXT of
			an error message because <A HREF="motion.html#it">it</A> may vary in different
			locales.


					*<A NAME=":fina"></A><B>:fina</B>* *<A NAME=":finally"></A><B>:finally</B>* *<A NAME="E606"></A><B>E606</B>* *<A NAME="E607"></A><B>E607</B>*
:fina[lly]		The following commands until the matching |<A HREF="#:endtry">:endtry</A>|
			are executed whenever the part between the matching
			|<A HREF="#:try">:try</A>| and the &quot;<A HREF="#:finally">:finally</A>&quot; is left:  either by falling
			through to the &quot;<A HREF="#:finally">:finally</A>&quot; or by a |<A HREF="#:continue">:continue</A>|,
			|<A HREF="#:break">:break</A>|, |<A HREF="repeat.html#:finish">:finish</A>|, or |<A HREF="#:return">:return</A>|, or by an error or
			interrupt or exception (see |<A HREF="#:throw">:throw</A>|).


							*<A NAME=":th"></A><B>:th</B>* *<A NAME=":throw"></A><B>:throw</B>* *<A NAME="E608"></A><B>E608</B>*
:th[row] {expr1}	The {expr1} is evaluated and thrown <A HREF="motion.html#as">as</A> an exception.
			If the &quot;<A HREF="#:throw">:throw</A>&quot; is used after a |<A HREF="#:try">:try</A>| but before the
			first corresponding |<A HREF="#:catch">:catch</A>|, commands are skipped
			until the first &quot;<A HREF="#:catch">:catch</A>&quot; matching {expr1} is reached.
			If there is no such &quot;<A HREF="#:catch">:catch</A>&quot; or if the &quot;<A HREF="#:throw">:throw</A>&quot; is
			used after a &quot;<A HREF="#:catch">:catch</A>&quot; but before the |<A HREF="#:finally">:finally</A>|, the
			commands following the &quot;<A HREF="#:finally">:finally</A>&quot; (if present) up to
			the matching |<A HREF="#:endtry">:endtry</A>| are executed.  If the &quot;<A HREF="#:throw">:throw</A>&quot;
			is after the &quot;<A HREF="#:finally">:finally</A>&quot;, commands up to the &quot;<A HREF="#:endtry">:endtry</A>&quot;
			are skipped.  At the &quot;<A HREF="#:endtry">:endtry</A>&quot;, this process applies
			again for the next dynamically surrounding &quot;<A HREF="#:try">:try</A>&quot;
			(which may be found in a calling function or sourcing
			script), until a matching &quot;<A HREF="#:catch">:catch</A>&quot; has been found.
			If the exception is not caught, the command processing
			is terminated.
			Example:
<B>		:try | throw "oops" | catch /^oo/ | echo "caught" | endtry</B>
 			Note that &quot;catch&quot; may need to be on a separate line
			for when an error causes the parsing to skip the whole
			line and not see the &quot;|&quot; that separates the commands.


							*<A NAME=":ec"></A><B>:ec</B>* *<A NAME=":echo"></A><B>:echo</B>*
:ec[ho] {expr1} ..	Echoes each {expr1}, with a space in between.  The
			first {expr1} starts on a new line.
			Also see |<A HREF="cmdline.html#:comment">:comment</A>|.
			Use &quot;\n&quot; to start a new line.  Use &quot;\r&quot; to move the
			cursor to the first column.
			Uses the highlighting set by the |<A HREF="#:echohl">:echohl</A>| command.
			Cannot be followed by a comment.
			Example:
<B>		:echo "the value of 'shell' is" &amp;shell</B>

 							*<A NAME=":echo-redraw"></A><B>:echo-redraw</B>*
			A later redraw may make the message disappear again.
			And since Vim mostly postpones redrawing until it's
			finished with a sequence of commands this happens
			quite often.  To avoid that a command from before the
			&quot;<A HREF="#:echo">:echo</A>&quot; causes a redraw afterwards (redraws are often
			postponed until you type something), force a redraw
			with the |<A HREF="various.html#:redraw">:redraw</A>| command.  Example:
<B>		:new | redraw | echo "there is a new window"</B>
 

							*<A NAME=":echon"></A><B>:echon</B>*
<A HREF="#:echon">:echon</A> {expr1} ..	Echoes each {expr1}, without anything added.  Also see
			|<A HREF="cmdline.html#:comment">:comment</A>|.
			Uses the highlighting set by the |<A HREF="#:echohl">:echohl</A>| command.
			Cannot be followed by a comment.
			Example:
<B>				:echon "the value of 'shell' is " &amp;shell</B>
 
			Note the difference between using &quot;<A HREF="#:echo">:echo</A>&quot;, which is a
			Vim command, and &quot;:!echo&quot;, which is an external shell
			command:
<B>		:!echo %		--&gt; filename</B>
 			The arguments of &quot;<A HREF="various.html#:!">:!</A>&quot; are expanded, see |<A HREF="cmdline.html#:_&#37;">:_&#37;</A>|.
<B>		:!echo "%"		--&gt; filename or "filename"</B>
 			Like the previous example.  Whether you see the double
			<A HREF="quotes.html#quotes">quotes</A> or not depends on your <A HREF="options.html#'shell'">'shell'</A>.
<B>		:echo %			--&gt; nothing</B>
 			The '<A HREF="motion.html#&#37;">&#37;</A>' is an illegal character in an <A HREF="#expression">expression</A>.
<B>		:echo "%"		--&gt; %</B>
 			This just echoes the '<A HREF="motion.html#&#37;">&#37;</A>' character.
<B>		:echo expand("%")	--&gt; filename</B>
 			This calls the <A HREF="#expand()">expand()</A> function to expand the '<A HREF="motion.html#&#37;">&#37;</A>'.


							*<A NAME=":echoh"></A><B>:echoh</B>* *<A NAME=":echohl"></A><B>:echohl</B>*
:echoh[l] {name}	Use the highlight group {name} for the following
			|<A HREF="#:echo">:echo</A>|, |<A HREF="#:echon">:echon</A>| and |<A HREF="#:echomsg">:echomsg</A>| commands.  Also used
			for the |<A HREF="#input()">input()</A>| prompt.  Example:
<B>		:echohl WarningMsg | echo "Don't panic!" | echohl None</B>
 			Don't forget to set the group back to &quot;None&quot;,
			otherwise all following echo's will be highlighted.


							*<A NAME=":echom"></A><B>:echom</B>* *<A NAME=":echomsg"></A><B>:echomsg</B>*
:echom[sg] {expr1} ..	Echo the expression(s) <A HREF="motion.html#as">as</A> a true message, saving the
			message in the |<A HREF="message.html#message-history">message-history</A>|.
			Spaces are placed between the arguments <A HREF="motion.html#as">as</A> with the
			|<A HREF="#:echo">:echo</A>| command.  But unprintable characters are
			displayed, not interpreted.
			The parsing works slightly different from |<A HREF="#:echo">:echo</A>|,
			more like |<A HREF="#:execute">:execute</A>|.  All the expressions are first
			evaluated and concatenated before echoing anything.
			The expressions must evaluate to a <A HREF="#Number">Number</A> or <A HREF="#String">String</A>, a
			<A HREF="#Dictionary">Dictionary</A> or <A HREF="#List">List</A> causes an error.
			Uses the highlighting set by the |<A HREF="#:echohl">:echohl</A>| command.
			Example:
<B>		:echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."</B>
 			See |<A HREF="#:echo-redraw">:echo-redraw</A>| to avoid the message disappearing
			when the screen is redrawn.

							*<A NAME=":echoe"></A><B>:echoe</B>* *<A NAME=":echoerr"></A><B>:echoerr</B>*
:echoe[rr] {expr1} ..	Echo the expression(s) <A HREF="motion.html#as">as</A> an error message, saving the
			message in the |<A HREF="message.html#message-history">message-history</A>|.  When used in a
			<A HREF="usr_41.html#script">script</A> or function the line number will be added.
			Spaces are placed between the arguments <A HREF="motion.html#as">as</A> with the
			<A HREF="#:echo">:echo</A> command.	When used inside a try conditional,
			the message is raised <A HREF="motion.html#as">as</A> an error exception instead
			(see |<A HREF="#try-echoerr">try-echoerr</A>|).
			Example:
<B>		:echoerr "This script just failed!"</B>
 			If you just want a highlighted message use |<A HREF="#:echohl">:echohl</A>|.
			And to get a beep:
<B>		:exe "normal \&lt;Esc&gt;"</B>
 

							*<A NAME=":exe"></A><B>:exe</B>* *<A NAME=":execute"></A><B>:execute</B>*
:exe[cute] {expr1} ..	Executes the <A HREF="#string">string</A> that results from the evaluation
			of {expr1} <A HREF="motion.html#as">as</A> an <A HREF="intro.html#Ex">Ex</A> command.
			Multiple arguments are concatenated, with a space in
			between.  To avoid the extra space use the &quot;<A HREF="repeat.html#.">.</A>&quot;
			<A HREF="motion.html#operator">operator</A> to concatenate strings into one argument.
			{expr1} is used <A HREF="motion.html#as">as</A> the processed command, command line
			editing keys are not recognized.
			Cannot be followed by a comment.
			Examples:
<B>		:execute "buffer" nextbuf</B>
<B>		:execute "normal" count . "w"</B>
 
			&quot;<A HREF="#:execute">:execute</A>&quot; can be used to append a command to commands
			that don't accept a '&#124;'.  Example:
<B>		:execute '!ls' | echo "theend"</B>

 			&quot;<A HREF="#:execute">:execute</A>&quot; is also a <A HREF="todo.html#nice">nice</A> way to avoid having to type
			<A HREF="intro.html#control">control</A> characters in a Vim <A HREF="usr_41.html#script">script</A> for a &quot;<A HREF="various.html#:normal">:normal</A>&quot;
			command:
<B>		:execute "normal ixxx\&lt;Esc&gt;"</B>
 			This has an <A HREF="intro.html#&lt;Esc&gt;">&lt;Esc&gt;</A> character, see |<A HREF="#expr-string">expr-string</A>|.

			Be careful to correctly <A HREF="intro.html#escape">escape</A> special characters in
			file names.  The |<A HREF="#fnameescape()">fnameescape()</A>| function can be used
			for Vim commands, |<A HREF="#shellescape()">shellescape()</A>| for |<A HREF="various.html#:!">:!</A>| commands.
			Examples:
<B>		:execute "e " . fnameescape(filename)</B>
<B>		:execute "!ls " . shellescape(filename, 1)</B>
 
			Note: The executed <A HREF="#string">string</A> may be any command-line, but
			starting or ending &quot;if&quot;, &quot;while&quot; and &quot;for&quot; does not
			always work, because when commands are skipped the
			&quot;<A HREF="#:execute">:execute</A>&quot; is not evaluated and Vim loses track of
			where blocks start and end.  Also &quot;break&quot; and
			&quot;continue&quot; should not be inside &quot;<A HREF="#:execute">:execute</A>&quot;.
			This example does not work, because the &quot;<A HREF="#:execute">:execute</A>&quot; is
			not evaluated and Vim does not see the &quot;while&quot;, and
			gives an error for finding an &quot;<A HREF="#:endwhile">:endwhile</A>&quot;:
<B>		:if 0</B>
<B>		: execute 'while i &gt; 5'</B>
<B>		:  echo "test"</B>
<B>		: endwhile</B>
<B>		:endif</B>
 
			It is allowed to have a &quot;while&quot; or &quot;if&quot; command
			completely in the executed <A HREF="#string">string</A>:
<B>		:execute 'while i &lt; 5 | echo i | let i = i + 1 | endwhile'</B>
 


							*<A NAME=":exe-comment"></A><B>:exe-comment</B>*
			&quot;<A HREF="#:execute">:execute</A>&quot;, &quot;<A HREF="#:echo">:echo</A>&quot; and &quot;<A HREF="#:echon">:echon</A>&quot; cannot be followed by
			a comment directly, because they see the &#39;&#34;'' <A HREF="motion.html#as">as</A> the
			start of a <A HREF="#string">string</A>.  But, you can use '&#124;' followed by a
			comment.  Example:
<B>		:echo "foo" | "this is a comment</B>

==============================================================================

8. Exception handling					*<A NAME="exception-handling"></A><B>exception-handling</B>*

The Vim <A HREF="usr_41.html#script">script</A> language comprises an exception handling feature.  This section
explains how <A HREF="motion.html#it">it</A> can be used in a Vim <A HREF="usr_41.html#script">script</A>.

Exceptions may be raised by Vim on an error or on interrupt, see
|<A HREF="#catch-errors">catch-errors</A>| and |<A HREF="#catch-interrupt">catch-interrupt</A>|.  You can also explicitly throw an
exception by using the &quot;<A HREF="#:throw">:throw</A>&quot; command, see |<A HREF="#throw-catch">throw-catch</A>|.



TRY CONDITIONALS					*<A NAME="try-conditionals"></A><B>try-conditionals</B>*

Exceptions can be caught or can cause cleanup code to be executed.  You can
use a try conditional to specify catch clauses (that catch exceptions) and/or
a finally clause (to be executed for cleanup).
   A try conditional begins with a |<A HREF="#:try">:try</A>| command and ends at the matching
|<A HREF="#:endtry">:endtry</A>| command.  In between, you can use a |<A HREF="#:catch">:catch</A>| command to start
a catch clause, or a |<A HREF="#:finally">:finally</A>| command to start a finally clause.  There may
be none or multiple catch clauses, but there is at most one finally clause,
which must not be followed by any catch clauses.  The lines before the catch
clauses and the finally clause is called a try block.

<B>     :try</B>
<B>     :	...</B>
<B>     :	...				TRY BLOCK</B>
<B>     :	...</B>
<B>     :catch /{pattern}/</B>
<B>     :	...</B>
<B>     :	...				CATCH CLAUSE</B>
<B>     :	...</B>
<B>     :catch /{pattern}/</B>
<B>     :	...</B>
<B>     :	...				CATCH CLAUSE</B>
<B>     :	...</B>
<B>     :finally</B>
<B>     :	...</B>
<B>     :	...				FINALLY CLAUSE</B>
<B>     :	...</B>
<B>     :endtry</B>

The try conditional allows to watch code for exceptions and to take the
appropriate actions.  Exceptions from the try block may be caught.  Exceptions
from the try block and also the catch clauses may cause cleanup actions.
   When no exception is thrown during execution of the try block, the <A HREF="intro.html#control">control</A>
is transferred to the finally clause, if present.  After its execution, the
<A HREF="usr_41.html#script">script</A> continues with the line following the &quot;<A HREF="#:endtry">:endtry</A>&quot;.
   When an exception occurs during execution of the try block, the remaining
lines in the try block are skipped.  The exception is matched against the
patterns specified <A HREF="motion.html#as">as</A> arguments to the &quot;<A HREF="#:catch">:catch</A>&quot; commands.  The catch clause
after the first matching &quot;<A HREF="#:catch">:catch</A>&quot; is taken, other catch clauses are not
executed.  The catch clause ends when the next &quot;<A HREF="#:catch">:catch</A>&quot;, &quot;<A HREF="#:finally">:finally</A>&quot;, or
&quot;<A HREF="#:endtry">:endtry</A>&quot; command is reached - whatever is first.  Then, the finally clause
(if present) is executed.  When the &quot;<A HREF="#:endtry">:endtry</A>&quot; is reached, the <A HREF="usr_41.html#script">script</A> execution
continues in the following line <A HREF="motion.html#as">as</A> usual.
   When an exception that does not match any of the patterns specified by the
&quot;<A HREF="#:catch">:catch</A>&quot; commands is thrown in the try block, the exception is not caught by
that try conditional and none of the catch clauses is executed.  Only the
finally clause, if present, is taken.  The exception pends during execution of
the finally clause.  It is resumed at the &quot;<A HREF="#:endtry">:endtry</A>&quot;, so that commands after
the &quot;<A HREF="#:endtry">:endtry</A>&quot; are not executed and the exception might be caught elsewhere,
see |<A HREF="#try-nesting">try-nesting</A>|.
   When during execution of a catch clause another exception is thrown, the
remaining lines in that catch clause are not executed.	The new exception is
not matched against the patterns in any of the &quot;<A HREF="#:catch">:catch</A>&quot; commands of the same
try conditional and none of its catch clauses is taken.  If there is, however,
a finally clause, <A HREF="motion.html#it">it</A> is executed, and the exception pends during its
execution.  The commands following the &quot;<A HREF="#:endtry">:endtry</A>&quot; are not executed.  The new
exception might, however, be caught elsewhere, see |<A HREF="#try-nesting">try-nesting</A>|.
   When during execution of the finally clause (if present) an exception is
thrown, the remaining lines in the finally clause are skipped.	If the finally
clause has been taken because of an exception from the try block or one of the
catch clauses, the original (pending) exception is discarded.  The commands
following the &quot;<A HREF="#:endtry">:endtry</A>&quot; are not executed, and the exception from the finally
clause is propagated and can be caught elsewhere, see |<A HREF="#try-nesting">try-nesting</A>|.

The finally clause is also executed, when a &quot;<A HREF="#:break">:break</A>&quot; or &quot;<A HREF="#:continue">:continue</A>&quot; for
a &quot;<A HREF="#:while">:while</A>&quot; loop enclosing the complete try conditional is executed from the
try block or a catch clause.  Or when a &quot;<A HREF="#:return">:return</A>&quot; or &quot;<A HREF="repeat.html#:finish">:finish</A>&quot; is executed
from the try block or a catch clause of a try conditional in a function or
sourced <A HREF="usr_41.html#script">script</A>, respectively.  The &quot;<A HREF="#:break">:break</A>&quot;, &quot;<A HREF="#:continue">:continue</A>&quot;, &quot;<A HREF="#:return">:return</A>&quot;, or
&quot;<A HREF="repeat.html#:finish">:finish</A>&quot; pends during execution of the finally clause and is resumed when the
&quot;<A HREF="#:endtry">:endtry</A>&quot; is reached.  It is, however, discarded when an exception is thrown
from the finally clause.
   When a &quot;<A HREF="#:break">:break</A>&quot; or &quot;<A HREF="#:continue">:continue</A>&quot; for a &quot;<A HREF="#:while">:while</A>&quot; loop enclosing the complete
try conditional or when a &quot;<A HREF="#:return">:return</A>&quot; or &quot;<A HREF="repeat.html#:finish">:finish</A>&quot; is encountered in the finally
clause, the rest of the finally clause is skipped, and the &quot;<A HREF="#:break">:break</A>&quot;,
&quot;<A HREF="#:continue">:continue</A>&quot;, &quot;<A HREF="#:return">:return</A>&quot; or &quot;<A HREF="repeat.html#:finish">:finish</A>&quot; is executed <A HREF="motion.html#as">as</A> usual.  If the finally
clause has been taken because of an exception or an earlier &quot;<A HREF="#:break">:break</A>&quot;,
&quot;<A HREF="#:continue">:continue</A>&quot;, &quot;<A HREF="#:return">:return</A>&quot;, or &quot;<A HREF="repeat.html#:finish">:finish</A>&quot; from the try block or a catch clause,
this pending exception or command is discarded.

For examples see |<A HREF="#throw-catch">throw-catch</A>| and |<A HREF="#try-finally">try-finally</A>|.



NESTING	OF TRY CONDITIONALS				*<A NAME="try-nesting"></A><B>try-nesting</B>*

Try conditionals can be nested arbitrarily.  That is, a complete try
conditional can be put into the try block, a catch clause, or the finally
clause of another try conditional.  If the inner try conditional does not
catch an exception thrown in its try block or throws a new exception from one
of its catch clauses or its finally clause, the outer try conditional is
checked according to the rules above.  If the inner try conditional is in the
try block of the outer try conditional, its catch clauses are checked, but
otherwise only the finally clause is executed.	It does not matter for
nesting, whether the inner try conditional is directly contained in the outer
one, or whether the outer one sources a <A HREF="usr_41.html#script">script</A> or calls a function containing
the inner try conditional.

When none of the active try conditionals catches an exception, just their
finally clauses are executed.  Thereafter, the <A HREF="usr_41.html#script">script</A> processing terminates.
An error message is displayed in <A HREF="change.html#case">case</A> of an uncaught exception explicitly
thrown by a &quot;<A HREF="#:throw">:throw</A>&quot; command.  For uncaught error and interrupt exceptions
implicitly raised by Vim, the error message(s) or interrupt message are shown
<A HREF="motion.html#as">as</A> usual.

For examples see |<A HREF="#throw-catch">throw-catch</A>|.



EXAMINING EXCEPTION HANDLING CODE			*<A NAME="except-examine"></A><B>except-examine</B>*

Exception handling code can get tricky.  If you are in doubt what happens, set
<A HREF="options.html#'verbose'">'verbose'</A> to 13 or use the &quot;:13verbose&quot; command modifier when sourcing your
<A HREF="usr_41.html#script">script</A> file.  Then you see when an exception is thrown, discarded, caught, or
finished.  When using a verbosity level of at least 14, things pending in
a finally clause are also shown.  This information is also given in debug mode
(see |<A HREF="repeat.html#debug-scripts">debug-scripts</A>|).



THROWING AND CATCHING EXCEPTIONS			*<A NAME="throw-catch"></A><B>throw-catch</B>*

You can throw any number or <A HREF="#string">string</A> <A HREF="motion.html#as">as</A> an exception.  Use the |<A HREF="#:throw">:throw</A>| command
and pass the value to be thrown <A HREF="motion.html#as">as</A> argument:
<B>	:throw 4711</B>
<B>	:throw "string"</B>

 							*<A NAME="throw-expression"></A><B>throw-expression</B>*
You can also specify an <A HREF="#expression">expression</A> argument.  The <A HREF="#expression">expression</A> is then evaluated
first, and the result is thrown:
<B>	:throw 4705 + strlen("string")</B>
<B>	:throw strpart("strings", 0, 6)</B>

An exception might be thrown during evaluation of the argument of the &quot;<A HREF="#:throw">:throw</A>&quot;
command.  Unless <A HREF="motion.html#it">it</A> is caught there, the <A HREF="#expression">expression</A> evaluation is abandoned.
The &quot;<A HREF="#:throw">:throw</A>&quot; command then does not throw a new exception.
   Example:

<B>	:function! Foo(arg)</B>
<B>	:  try</B>
<B>	:    throw a:arg</B>
<B>	:  catch /foo/</B>
<B>	:  endtry</B>
<B>	:  return 1</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Bar()</B>
<B>	:  echo "in Bar"</B>
<B>	:  return 4710</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:throw Foo("arrgh") + Bar()</B>

This throws &quot;arrgh&quot;, and &quot;in Bar&quot; is not displayed since Bar() is not
executed.
<B>	:throw Foo("foo") + Bar()</B>
however displays &quot;in Bar&quot; and throws 4711.

Any other command that takes an <A HREF="#expression">expression</A> <A HREF="motion.html#as">as</A> argument might also be
abandoned by an (uncaught) exception during the <A HREF="#expression">expression</A> evaluation.	The
exception is then propagated to the caller of the command.
   Example:

<B>	:if Foo("arrgh")</B>
<B>	:  echo "then"</B>
<B>	:else</B>
<B>	:  echo "else"</B>
<B>	:endif</B>

Here neither of &quot;then&quot; or &quot;else&quot; is displayed.


							*<A NAME="catch-order"></A><B>catch-order</B>*
Exceptions can be caught by a try conditional with one or more |<A HREF="#:catch">:catch</A>|
commands, see |<A HREF="#try-conditionals">try-conditionals</A>|.   The values to be caught by each &quot;<A HREF="#:catch">:catch</A>&quot;
command can be specified <A HREF="motion.html#as">as</A> a <A HREF="pattern.html#pattern">pattern</A> argument.  The subsequent catch clause
gets executed when a matching exception is caught.
   Example:

<B>	:function! Foo(value)</B>
<B>	:  try</B>
<B>	:    throw a:value</B>
<B>	:  catch /^\d\+$/</B>
<B>	:    echo "Number thrown"</B>
<B>	:  catch /.*/</B>
<B>	:    echo "String thrown"</B>
<B>	:  endtry</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:call Foo(0x1267)</B>
<B>	:call Foo('string')</B>

The first call to Foo() displays &quot;<A HREF="#Number">Number</A> thrown&quot;, the second &quot;<A HREF="#String">String</A> thrown&quot;.
An exception is matched against the &quot;<A HREF="#:catch">:catch</A>&quot; commands in the order they are
specified.  Only the first match counts.  So you should place the more
specific &quot;<A HREF="#:catch">:catch</A>&quot; first.  The following order does not make sense:

<B>	:  catch /.*/</B>
<B>	:    echo "String thrown"</B>
<B>	:  catch /^\d\+$/</B>
<B>	:    echo "Number thrown"</B>

The first &quot;<A HREF="#:catch">:catch</A>&quot; here matches always, so that the second catch clause is
never taken.


							*<A NAME="throw-variables"></A><B>throw-variables</B>*
If you catch an exception by a general <A HREF="pattern.html#pattern">pattern</A>, you may access the exact value
in the variable YXXYv:exception|:

<B>	:  catch /^\d\+$/</B>
<B>	:    echo "Number thrown.  Value is" v:exception</B>

You may also be interested where an exception was thrown.  This is stored in
|<A HREF="#v:throwpoint">v:throwpoint</A>|.  Note that &quot;<A HREF="#v:exception">v:exception</A>&quot; and &quot;v:throwpoint&quot; are valid for the
exception most recently caught <A HREF="motion.html#as">as</A> long <A HREF="motion.html#it">it</A> is not finished.
   Example:

<B>	:function! Caught()</B>
<B>	:  if v:exception != ""</B>
<B>	:    echo 'Caught "' . v:exception . '" in ' . v:throwpoint</B>
<B>	:  else</B>
<B>	:    echo 'Nothing caught'</B>
<B>	:  endif</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Foo()</B>
<B>	:  try</B>
<B>	:    try</B>
<B>	:      try</B>
<B>	:	 throw 4711</B>
<B>	:      finally</B>
<B>	:	 call Caught()</B>
<B>	:      endtry</B>
<B>	:    catch /.*/</B>
<B>	:      call Caught()</B>
<B>	:      throw "oops"</B>
<B>	:    endtry</B>
<B>	:  catch /.*/</B>
<B>	:    call Caught()</B>
<B>	:  finally</B>
<B>	:    call Caught()</B>
<B>	:  endtry</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:call Foo()</B>

This displays

<B>	Nothing caught</B>
<B>	Caught "4711" in function Foo, line 4</B>
<B>	Caught "oops" in function Foo, line 10</B>
<B>	Nothing caught</B>

A practical example:  The following command &quot;:LineNumber&quot; displays the line
number in the <A HREF="usr_41.html#script">script</A> or function where <A HREF="motion.html#it">it</A> has been used:

<B>	:function! LineNumber()</B>
<B>	:    return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")</B>
<B>	:endfunction</B>
<B>	:command! LineNumber try | throw "" | catch | echo LineNumber() | endtry</B>
 

							*<A NAME="try-nested"></A><B>try-nested</B>*
An exception that is not caught by a try conditional can be caught by
a surrounding try conditional:

<B>	:try</B>
<B>	:  try</B>
<B>	:    throw "foo"</B>
<B>	:  catch /foobar/</B>
<B>	:    echo "foobar"</B>
<B>	:  finally</B>
<B>	:    echo "inner finally"</B>
<B>	:  endtry</B>
<B>	:catch /foo/</B>
<B>	:  echo "foo"</B>
<B>	:endtry</B>

The inner try conditional does not catch the exception, just its finally
clause is executed.  The exception is then caught by the outer try
conditional.  The example displays &quot;inner finally&quot; and then &quot;foo&quot;.


							*<A NAME="throw-from-catch"></A><B>throw-from-catch</B>*
You can catch an exception and throw a new one to be caught elsewhere from the
catch clause:

<B>	:function! Foo()</B>
<B>	:  throw "foo"</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Bar()</B>
<B>	:  try</B>
<B>	:    call Foo()</B>
<B>	:  catch /foo/</B>
<B>	:    echo "Caught foo, throw bar"</B>
<B>	:    throw "bar"</B>
<B>	:  endtry</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:try</B>
<B>	:  call Bar()</B>
<B>	:catch /.*/</B>
<B>	:  echo "Caught" v:exception</B>
<B>	:endtry</B>

This displays &quot;Caught foo, throw bar&quot; and then &quot;Caught bar&quot;.


							*<A NAME="rethrow"></A><B>rethrow</B>*
There is no real <A HREF="#rethrow">rethrow</A> in the Vim <A HREF="usr_41.html#script">script</A> language, but you may throw
&quot;<A HREF="#v:exception">v:exception</A>&quot; instead:

<B>	:function! Bar()</B>
<B>	:  try</B>
<B>	:    call Foo()</B>
<B>	:  catch /.*/</B>
<B>	:    echo "Rethrow" v:exception</B>
<B>	:    throw v:exception</B>
<B>	:  endtry</B>
<B>	:endfunction</B>

 							*<A NAME="try-echoerr"></A><B>try-echoerr</B>*
Note that this method cannot be used to &quot;<A HREF="#rethrow">rethrow</A>&quot; Vim error or interrupt
exceptions, because <A HREF="motion.html#it">it</A> is not possible to fake Vim internal exceptions.
Trying so causes an error exception.  You should throw your own exception
denoting the situation.  If you want to cause a Vim error exception containing
the original error exception value, you can use the |<A HREF="#:echoerr">:echoerr</A>| command:

<B>	:try</B>
<B>	:  try</B>
<B>	:    asdf</B>
<B>	:  catch /.*/</B>
<B>	:    echoerr v:exception</B>
<B>	:  endtry</B>
<B>	:catch /.*/</B>
<B>	:  echo v:exception</B>
<B>	:endtry</B>

This code displays

<B><FONT COLOR="PURPLE">	Vim(echoerr):Vim:E492: Not an editor command:	asdf </FONT></B>



CLEANUP CODE						*<A NAME="try-finally"></A><B>try-finally</B>*

Scripts often change global settings and restore them at their end.  If the
user however interrupts the <A HREF="usr_41.html#script">script</A> by pressing <A HREF="pattern.html#CTRL-C">CTRL-C</A>, the settings remain in
an inconsistent state.	The same may happen to you in the <A HREF="develop.html#development">development</A> phase of
a <A HREF="usr_41.html#script">script</A> when an error occurs or you explicitly throw an exception without
catching <A HREF="motion.html#it">it</A>.  You can solve these problems by using a try conditional with
a finally clause for restoring the settings.  Its execution is guaranteed on
normal <A HREF="intro.html#control">control</A> flow, on error, on an explicit &quot;<A HREF="#:throw">:throw</A>&quot;, and on interrupt.
(Note that <A HREF="message.html#errors">errors</A> and interrupts from inside the try conditional are converted
to exceptions.	When not caught, they terminate the <A HREF="usr_41.html#script">script</A> after the finally
clause has been executed.)
Example:

<B>	:try</B>
<B>	:  let s:saved_ts = &amp;ts</B>
<B>	:  set ts=17</B>
<B>	:</B>
<B>	:  " Do the hard work here.</B>
<B>	:</B>
<B>	:finally</B>
<B>	:  let &amp;ts = s:saved_ts</B>
<B>	:  unlet s:saved_ts</B>
<B>	:endtry</B>

This method should be used locally whenever a function or part of a <A HREF="usr_41.html#script">script</A>
changes global settings which need to be restored on failure or normal exit of
that function or <A HREF="usr_41.html#script">script</A> part.


							*<A NAME="break-finally"></A><B>break-finally</B>*
Cleanup code works also when the try block or a catch clause is left by
a &quot;<A HREF="#:continue">:continue</A>&quot;, &quot;<A HREF="#:break">:break</A>&quot;, &quot;<A HREF="#:return">:return</A>&quot;, or &quot;<A HREF="repeat.html#:finish">:finish</A>&quot;.
   Example:

<B>	:let first = 1</B>
<B>	:while 1</B>
<B>	:  try</B>
<B>	:    if first</B>
<B>	:      echo "first"</B>
<B>	:      let first = 0</B>
<B>	:      continue</B>
<B>	:    else</B>
<B>	:      throw "second"</B>
<B>	:    endif</B>
<B>	:  catch /.*/</B>
<B>	:    echo v:exception</B>
<B>	:    break</B>
<B>	:  finally</B>
<B>	:    echo "cleanup"</B>
<B>	:  endtry</B>
<B>	:  echo "still in while"</B>
<B>	:endwhile</B>
<B>	:echo "end"</B>

This displays &quot;first&quot;, &quot;cleanup&quot;, &quot;second&quot;, &quot;cleanup&quot;, and &quot;end&quot;.

<B>	:function! Foo()</B>
<B>	:  try</B>
<B>	:    return 4711</B>
<B>	:  finally</B>
<B>	:    echo "cleanup\n"</B>
<B>	:  endtry</B>
<B>	:  echo "Foo still active"</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:echo Foo() "returned by Foo"</B>

This displays &quot;cleanup&quot; and &quot;4711 returned by Foo&quot;.  You don't need to add an
extra &quot;<A HREF="#:return">:return</A>&quot; in the finally clause.	(Above all, this would override the
return value.)


							*<A NAME="except-from-finally"></A><B>except-from-finally</B>*
Using either of &quot;<A HREF="#:continue">:continue</A>&quot;, &quot;<A HREF="#:break">:break</A>&quot;, &quot;<A HREF="#:return">:return</A>&quot;, &quot;<A HREF="repeat.html#:finish">:finish</A>&quot;, or &quot;<A HREF="#:throw">:throw</A>&quot; in
a finally clause is possible, but not recommended since <A HREF="motion.html#it">it</A> abandons the
cleanup actions for the try conditional.  But, of course, interrupt and error
exceptions might get raised from a finally clause.
   Example where an error in the finally clause stops an interrupt from
working correctly:

<B>	:try</B>
<B>	:  try</B>
<B>	:    echo "Press CTRL-C for interrupt"</B>
<B>	:    while 1</B>
<B>	:    endwhile</B>
<B>	:  finally</B>
<B>	:    unlet novar</B>
<B>	:  endtry</B>
<B>	:catch /novar/</B>
<B>	:endtry</B>
<B>	:echo "Script still running"</B>
<B>	:sleep 1</B>

If you need to put commands that could fail into a finally clause, you should
think about catching or ignoring the <A HREF="message.html#errors">errors</A> in these commands, see
|<A HREF="#catch-errors">catch-errors</A>| and |<A HREF="#ignore-errors">ignore-errors</A>|.



CATCHING ERRORS						*<A NAME="catch-errors"></A><B>catch-errors</B>*

If you want to catch specific <A HREF="message.html#errors">errors</A>, you just have to put the code to be
watched in a try block and add a catch clause for the error message.  The
presence of the try conditional causes all <A HREF="message.html#errors">errors</A> to be converted to an
exception.  No message is displayed and |<A HREF="#v:errmsg">v:errmsg</A>| is not set then.  To find
the right <A HREF="pattern.html#pattern">pattern</A> for the &quot;<A HREF="#:catch">:catch</A>&quot; command, you have to know how the format of
the error exception is.
   Error exceptions have the following format:

<B>	Vim({cmdname}):{errmsg}</B>
or
<B>	Vim:{errmsg}</B>

{cmdname} is the name of the command that failed; the second form is used when
the command name is not known.	{errmsg} is the error message usually produced
when the error occurs outside try conditionals.  It always begins with
a capital &quot;<A HREF="motion.html#E">E</A>&quot;, followed by a two or three-digit error number, a colon, and
a space.

Examples:

The command
<B>	:unlet novar</B>
normally produces the error message
<B>	E108: No such variable: "novar"</B>
which is converted inside try conditionals to an exception
<B>	Vim(unlet):E108: No such variable: "novar"</B>

The command
<B>	:dwim</B>
normally produces the error message
<B>	E492: Not an editor command: dwim</B>
which is converted inside try conditionals to an exception
<B>	Vim:E492: Not an editor command: dwim</B>

You can catch all &quot;<A HREF="#:unlet">:unlet</A>&quot; <A HREF="message.html#errors">errors</A> by a
<B>	:catch /^Vim(unlet):/</B>
or all <A HREF="message.html#errors">errors</A> for misspelled command names by a
<B>	:catch /^Vim:E492:/</B>

Some error <A HREF="message.html#messages">messages</A> may be produced by different commands:
<B>	:function nofunc</B>
and
<B>	:delfunction nofunc</B>
both produce the error message
<B>	E128: Function name must start with a capital: nofunc</B>
which is converted inside try conditionals to an exception
<B>	Vim(function):E128: Function name must start with a capital: nofunc</B>
or
<B>	Vim(delfunction):E128: Function name must start with a capital: nofunc</B>
respectively.  You can catch the error by its number independently on the
command that caused <A HREF="motion.html#it">it</A> if you use the following <A HREF="pattern.html#pattern">pattern</A>:
<B>	:catch /^Vim(\a\+):E128:/</B>

Some commands like
<B>	:let x = novar</B>
produce multiple error <A HREF="message.html#messages">messages</A>, here:
<B>	E121: Undefined variable: novar</B>
<B>	E15: Invalid expression:  novar</B>
Only the first is used for the exception value, since <A HREF="motion.html#it">it</A> is the most specific
one (see |<A HREF="#except-several-errors">except-several-errors</A>|).  So you can catch <A HREF="motion.html#it">it</A> by
<B>	:catch /^Vim(\a\+):E121:/</B>

You can catch all <A HREF="message.html#errors">errors</A> related to the name &quot;nofunc&quot; by
<B>	:catch /\&lt;nofunc\&gt;/</B>

You can catch all Vim <A HREF="message.html#errors">errors</A> in the &quot;<A HREF="editing.html#:write">:write</A>&quot; and &quot;<A HREF="insert.html#:read">:read</A>&quot; commands by
<B>	:catch /^Vim(\(write\|read\)):E\d\+:/</B>

You can catch all Vim <A HREF="message.html#errors">errors</A> by the <A HREF="pattern.html#pattern">pattern</A>
<B>	:catch /^Vim\((\a\+)\)\=:E\d\+:/</B>
 

							*<A NAME="catch-text"></A><B>catch-text</B>*
NOTE: You should never catch the error message text itself:
<B>	:catch /No such variable/</B>
only works in the English <A HREF="mbyte.html#locale">locale</A>, but not when the user has selected
a different language by the |<A HREF="mlang.html#:language">:language</A>| command.  It is however helpful to
cite the message text in a comment:
<B>	:catch /^Vim(\a\+):E108:/   " No such variable</B>



IGNORING ERRORS						*<A NAME="ignore-errors"></A><B>ignore-errors</B>*

You can ignore <A HREF="message.html#errors">errors</A> in a specific Vim command by catching them locally:

<B>	:try</B>
<B>	:  write</B>
<B>	:catch</B>
<B>	:endtry</B>

But you are strongly recommended NOT to use this simple form, since <A HREF="motion.html#it">it</A> could
catch more than you want.  With the &quot;<A HREF="editing.html#:write">:write</A>&quot; command, some autocommands could
be executed and cause <A HREF="message.html#errors">errors</A> not related to <A HREF="editing.html#writing">writing</A>, for instance:

<B>	:au BufWritePre * unlet novar</B>

There could even be such <A HREF="message.html#errors">errors</A> you are not responsible for <A HREF="motion.html#as">as</A> a <A HREF="usr_41.html#script">script</A>
writer: a user of your <A HREF="usr_41.html#script">script</A> might have defined such autocommands.  You would
then hide the error from the user.
   It is much better to use

<B>	:try</B>
<B>	:  write</B>
<B>	:catch /^Vim(write):/</B>
<B>	:endtry</B>

which only catches real write <A HREF="message.html#errors">errors</A>.  So catch only what you'd like to ignore
intentionally.

For a single command that does not cause execution of autocommands, you could
even suppress the conversion of <A HREF="message.html#errors">errors</A> to exceptions by the &quot;<A HREF="various.html#:silent!">:silent!</A>&quot;
command:
<B>	:silent! nunmap k</B>
This works also when a try conditional is active.



CATCHING INTERRUPTS					*<A NAME="catch-interrupt"></A><B>catch-interrupt</B>*

When there are active try conditionals, an interrupt (CTRL-C) is converted to
the exception &quot;Vim:Interrupt&quot;.	You can catch <A HREF="motion.html#it">it</A> like every exception.	The
<A HREF="usr_41.html#script">script</A> is not terminated, then.
   Example:

<B>	:function! TASK1()</B>
<B>	:  sleep 10</B>
<B>	:endfunction</B>

<B>	:function! TASK2()</B>
<B>	:  sleep 20</B>
<B>	:endfunction</B>

<B>	:while 1</B>
<B>	:  let command = input("Type a command: ")</B>
<B>	:  try</B>
<B>	:    if command == ""</B>
<B>	:      continue</B>
<B>	:    elseif command == "END"</B>
<B>	:      break</B>
<B>	:    elseif command == "TASK1"</B>
<B>	:      call TASK1()</B>
<B>	:    elseif command == "TASK2"</B>
<B>	:      call TASK2()</B>
<B>	:    else</B>
<B>	:      echo "\nIllegal command:" command</B>
<B>	:      continue</B>
<B>	:    endif</B>
<B>	:  catch /^Vim:Interrupt$/</B>
<B>	:    echo "\nCommand interrupted"</B>
<B>	:    " Caught the interrupt.  Continue with next prompt.</B>
<B>	:  endtry</B>
<B>	:endwhile</B>

You can interrupt a task here by pressing <A HREF="pattern.html#CTRL-C">CTRL-C</A>; the <A HREF="usr_41.html#script">script</A> then asks for
a new command.	If you press <A HREF="pattern.html#CTRL-C">CTRL-C</A> at the prompt, the <A HREF="usr_41.html#script">script</A> is terminated.

For testing what happens when <A HREF="pattern.html#CTRL-C">CTRL-C</A> would be pressed on a specific line in
your <A HREF="usr_41.html#script">script</A>, use the debug mode and execute the |<A HREF="repeat.html#&gt;quit">&gt;quit</A>| or |<A HREF="repeat.html#&gt;interrupt">&gt;interrupt</A>|
command on that line.  See |<A HREF="repeat.html#debug-scripts">debug-scripts</A>|.



CATCHING ALL						*<A NAME="catch-all"></A><B>catch-all</B>*

The commands

<B>	:catch /.*/</B>
<B>	:catch //</B>
<B>	:catch</B>

catch everything, error exceptions, interrupt exceptions and exceptions
explicitly thrown by the |<A HREF="#:throw">:throw</A>| command.  This is useful at the top level of
a <A HREF="usr_41.html#script">script</A> in order to catch unexpected things.
   Example:

<B>	:try</B>
<B>	:</B>
<B>	:  " do the hard work here</B>
<B>	:</B>
<B>	:catch /MyException/</B>
<B>	:</B>
<B>	:  " handle known problem</B>
<B>	:</B>
<B>	:catch /^Vim:Interrupt$/</B>
<B>	:    echo "Script interrupted"</B>
<B>	:catch /.*/</B>
<B>	:  echo "Internal error (" . v:exception . ")"</B>
<B>	:  echo " - occurred at " . v:throwpoint</B>
<B>	:endtry</B>
<B>	:" end of script</B>

Note: Catching all might catch more things than you want.  Thus, you are
strongly encouraged to catch only for problems that you can really handle by
specifying a <A HREF="pattern.html#pattern">pattern</A> argument to the &quot;<A HREF="#:catch">:catch</A>&quot;.
   Example: Catching all could make <A HREF="motion.html#it">it</A> nearly impossible to interrupt a <A HREF="usr_41.html#script">script</A>
by pressing <A HREF="pattern.html#CTRL-C">CTRL-C</A>:

<B>	:while 1</B>
<B>	:  try</B>
<B>	:    sleep 1</B>
<B>	:  catch</B>
<B>	:  endtry</B>
<B>	:endwhile</B>



EXCEPTIONS AND AUTOCOMMANDS				*<A NAME="except-autocmd"></A><B>except-autocmd</B>*

Exceptions may be used during execution of autocommands.  Example:

<B>	:autocmd User x try</B>
<B>	:autocmd User x   throw "Oops!"</B>
<B>	:autocmd User x catch</B>
<B>	:autocmd User x   echo v:exception</B>
<B>	:autocmd User x endtry</B>
<B>	:autocmd User x throw "Arrgh!"</B>
<B>	:autocmd User x echo "Should not be displayed"</B>
<B>	:</B>
<B>	:try</B>
<B>	:  doautocmd User x</B>
<B>	:catch</B>
<B>	:  echo v:exception</B>
<B>	:endtry</B>

This displays &quot;Oops!&quot; and &quot;Arrgh!&quot;.


							*<A NAME="except-autocmd-Pre"></A><B>except-autocmd-Pre</B>*
For some commands, autocommands get executed before the main action of the
command takes place.  If an exception is thrown and not caught in the sequence
of autocommands, the sequence and the command that caused its execution are
abandoned and the exception is propagated to the caller of the command.
   Example:

<B>	:autocmd BufWritePre * throw "FAIL"</B>
<B>	:autocmd BufWritePre * echo "Should not be displayed"</B>
<B>	:</B>
<B>	:try</B>
<B>	:  write</B>
<B>	:catch</B>
<B>	:  echo "Caught:" v:exception "from" v:throwpoint</B>
<B>	:endtry</B>

Here, the &quot;<A HREF="editing.html#:write">:write</A>&quot; command does not write the file currently being edited (as
you can see by checking 'modified'), since the exception from the <A HREF="autocmd.html#BufWritePre">BufWritePre</A>
<A HREF="autocmd.html#autocommand">autocommand</A> abandons the &quot;<A HREF="editing.html#:write">:write</A>&quot;.  The exception is then caught and the
<A HREF="usr_41.html#script">script</A> displays:

<B>	Caught: FAIL from BufWrite Auto commands for "*"</B>
 

							*<A NAME="except-autocmd-Post"></A><B>except-autocmd-Post</B>*
For some commands, autocommands get executed after the main action of the
command has taken place.  If this main action fails and the command is inside
an active try conditional, the autocommands are skipped and an error exception
is thrown that can be caught by the caller of the command.
   Example:

<B>	:autocmd BufWritePost * echo "File successfully written!"</B>
<B>	:</B>
<B>	:try</B>
<B>	:  write /i/m/p/o/s/s/i/b/l/e</B>
<B>	:catch</B>
<B>	:  echo v:exception</B>
<B>	:endtry</B>

This just displays:

<B>	Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)</B>

If you really need to execute the autocommands even when the main action
fails, trigger the event from the catch clause.
   Example:

<B>	:autocmd BufWritePre  * set noreadonly</B>
<B>	:autocmd BufWritePost * set readonly</B>
<B>	:</B>
<B>	:try</B>
<B>	:  write /i/m/p/o/s/s/i/b/l/e</B>
<B>	:catch</B>
<B>	:  doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e</B>
<B>	:endtry</B>
 
You can also use &quot;<A HREF="various.html#:silent!">:silent!</A>&quot;:

<B>	:let x = "ok"</B>
<B>	:let v:errmsg = ""</B>
<B>	:autocmd BufWritePost * if v:errmsg != ""</B>
<B>	:autocmd BufWritePost *   let x = "after fail"</B>
<B>	:autocmd BufWritePost * endif</B>
<B>	:try</B>
<B>	:  silent! write /i/m/p/o/s/s/i/b/l/e</B>
<B>	:catch</B>
<B>	:endtry</B>
<B>	:echo x</B>

This displays &quot;after fail&quot;.

If the main action of the command does not fail, exceptions from the
autocommands will be catchable by the caller of the command: 

<B>	:autocmd BufWritePost * throw ":-("</B>
<B>	:autocmd BufWritePost * echo "Should not be displayed"</B>
<B>	:</B>
<B>	:try</B>
<B>	:  write</B>
<B>	:catch</B>
<B>	:  echo v:exception</B>
<B>	:endtry</B>
 

							*<A NAME="except-autocmd-Cmd"></A><B>except-autocmd-Cmd</B>*
For some commands, the normal action can be replaced by a sequence of
autocommands.  Exceptions from that sequence will be catchable by the caller
of the command.
   Example:  For the &quot;<A HREF="editing.html#:write">:write</A>&quot; command, the caller cannot know whether the file
had actually been written when the exception occurred.	You need to tell <A HREF="motion.html#it">it</A> in
some way.

<B>	:if !exists("cnt")</B>
<B>	:  let cnt = 0</B>
<B>	:</B>
<B>	:  autocmd BufWriteCmd * if &amp;modified</B>
<B>	:  autocmd BufWriteCmd *   let cnt = cnt + 1</B>
<B>	:  autocmd BufWriteCmd *   if cnt % 3 == 2</B>
<B>	:  autocmd BufWriteCmd *     throw "BufWriteCmdError"</B>
<B>	:  autocmd BufWriteCmd *   endif</B>
<B>	:  autocmd BufWriteCmd *   write | set nomodified</B>
<B>	:  autocmd BufWriteCmd *   if cnt % 3 == 0</B>
<B>	:  autocmd BufWriteCmd *     throw "BufWriteCmdError"</B>
<B>	:  autocmd BufWriteCmd *   endif</B>
<B>	:  autocmd BufWriteCmd *   echo "File successfully written!"</B>
<B>	:  autocmd BufWriteCmd * endif</B>
<B>	:endif</B>
<B>	:</B>
<B>	:try</B>
<B>	:	write</B>
<B>	:catch /^BufWriteCmdError$/</B>
<B>	:  if &amp;modified</B>
<B>	:    echo "Error on writing (file contents not changed)"</B>
<B>	:  else</B>
<B>	:    echo "Error after writing"</B>
<B>	:  endif</B>
<B>	:catch /^Vim(write):/</B>
<B>	:    echo "Error on writing"</B>
<B>	:endtry</B>

When this <A HREF="usr_41.html#script">script</A> is sourced several times after making changes, <A HREF="motion.html#it">it</A> displays
first
<B>	File successfully written!</B>
then
<B>	Error on writing (file contents not changed)</B>
then
<B>	Error after writing</B>
etc.


							*<A NAME="except-autocmd-ill"></A><B>except-autocmd-ill</B>*
You cannot spread a try conditional over autocommands for different events.
The following code is ill-formed:

<B>	:autocmd BufWritePre  * try</B>
<B>	:</B>
<B>	:autocmd BufWritePost * catch</B>
<B>	:autocmd BufWritePost *   echo v:exception</B>
<B>	:autocmd BufWritePost * endtry</B>
<B>	:</B>
<B>	:write</B>



EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS	*<A NAME="except-hier-param"></A><B>except-hier-param</B>*

Some programming languages allow to use hierarchies of exception classes or to
pass additional information with the object of an exception class.  You can <A HREF="diff.html#do">do</A>
similar things in Vim.
   In order to throw an exception from a hierarchy, just throw the complete
class name with the components separated by a colon, for instance throw the
<A HREF="#string">string</A> &quot;EXCEPT:MATHERR:OVERFLOW&quot; for an overflow in a mathematical library.
   When you want to pass additional information with your exception class, add
<A HREF="motion.html#it">it</A> in parentheses, for instance throw the <A HREF="#string">string</A> &quot;EXCEPT:IO:WRITEERR(myfile)&quot;
for an error when <A HREF="editing.html#writing">writing</A> &quot;myfile&quot;.
   With the appropriate patterns in the &quot;<A HREF="#:catch">:catch</A>&quot; command, you can catch for
base classes or derived classes of your hierarchy.  Additional information in
parentheses can be cut out from |<A HREF="#v:exception">v:exception</A>| with the &quot;<A HREF="change.html#:substitute">:substitute</A>&quot; command.
   Example:

<B>	:function! CheckRange(a, func)</B>
<B>	:  if a:a &lt; 0</B>
<B>	:    throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"</B>
<B>	:  endif</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Add(a, b)</B>
<B>	:  call CheckRange(a:a, "Add")</B>
<B>	:  call CheckRange(a:b, "Add")</B>
<B>	:  let c = a:a + a:b</B>
<B>	:  if c &lt; 0</B>
<B>	:    throw "EXCEPT:MATHERR:OVERFLOW"</B>
<B>	:  endif</B>
<B>	:  return c</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Div(a, b)</B>
<B>	:  call CheckRange(a:a, "Div")</B>
<B>	:  call CheckRange(a:b, "Div")</B>
<B>	:  if (a:b == 0)</B>
<B>	:    throw "EXCEPT:MATHERR:ZERODIV"</B>
<B>	:  endif</B>
<B>	:  return a:a / a:b</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:function! Write(file)</B>
<B>	:  try</B>
<B>	:    execute "write" fnameescape(a:file)</B>
<B>	:  catch /^Vim(write):/</B>
<B>	:    throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"</B>
<B>	:  endtry</B>
<B>	:endfunction</B>
<B>	:</B>
<B>	:try</B>
<B>	:</B>
<B>	:  " something with arithmetics and I/O</B>
<B>	:</B>
<B>	:catch /^EXCEPT:MATHERR:RANGE/</B>
<B>	:  let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")</B>
<B>	:  echo "Range error in" function</B>
<B>	:</B>
<B>	:catch /^EXCEPT:MATHERR/	" catches OVERFLOW and ZERODIV</B>
<B>	:  echo "Math error"</B>
<B>	:</B>
<B>	:catch /^EXCEPT:IO/</B>
<B>	:  let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")</B>
<B>	:  let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")</B>
<B>	:  if file !~ '^/'</B>
<B>	:    let file = dir . "/" . file</B>
<B>	:  endif</B>
<B>	:  echo 'I/O error for "' . file . '"'</B>
<B>	:</B>
<B>	:catch /^EXCEPT/</B>
<B>	:  echo "Unspecified error"</B>
<B>	:</B>
<B>	:endtry</B>

The exceptions raised by Vim itself (on error or when pressing <A HREF="pattern.html#CTRL-C">CTRL-C</A>) use
a flat hierarchy:  they are all in the &quot;Vim&quot; class.  You cannot throw yourself
exceptions with the &quot;Vim&quot; prefix; they are reserved for Vim.
   Vim error exceptions are parameterized with the name of the command that
failed, if known.  See |<A HREF="#catch-errors">catch-errors</A>|.


PECULIARITIES

							*<A NAME="except-compat"></A><B>except-compat</B>*
The exception handling concept requires that the command sequence causing the
exception is aborted immediately and <A HREF="intro.html#control">control</A> is transferred to finally clauses
and/or a catch clause.

In the Vim <A HREF="usr_41.html#script">script</A> language there are cases where scripts and <A HREF="#functions">functions</A>
continue after an error: in <A HREF="#functions">functions</A> without the &quot;abort&quot; flag or in a command
after &quot;<A HREF="various.html#:silent!">:silent!</A>&quot;, <A HREF="intro.html#control">control</A> flow goes to the following line, and outside
<A HREF="#functions">functions</A>, <A HREF="intro.html#control">control</A> flow goes to the line following the outermost &quot;<A HREF="#:endwhile">:endwhile</A>&quot;
or &quot;<A HREF="#:endif">:endif</A>&quot;.  On the other hand, <A HREF="message.html#errors">errors</A> should be catchable <A HREF="motion.html#as">as</A> exceptions
(thus, requiring the immediate abortion).

This problem has been solved by converting <A HREF="message.html#errors">errors</A> to exceptions and using
immediate abortion (if not suppressed by &quot;<A HREF="various.html#:silent!">:silent!</A>&quot;) only when a try
conditional is active.	This is no restriction since an (error) exception can
be caught only from an active try conditional.	If you want an immediate
termination without catching the error, just use a try conditional without
catch clause.  (You can cause cleanup code being executed before termination
by specifying a finally clause.)

When no try conditional is active, the usual abortion and continuation
behavior is used instead of immediate abortion.  This ensures compatibility of
scripts written for Vim 6.1 and earlier.

However, when sourcing an existing <A HREF="usr_41.html#script">script</A> that does not use exception handling
commands (or when calling one of its <A HREF="#functions">functions</A>) from inside an active try
conditional of a new <A HREF="usr_41.html#script">script</A>, you might change the <A HREF="intro.html#control">control</A> flow of the existing
<A HREF="usr_41.html#script">script</A> on error.  You get the immediate abortion on error and can catch the
error in the new <A HREF="usr_41.html#script">script</A>.  If however the sourced <A HREF="usr_41.html#script">script</A> suppresses error
<A HREF="message.html#messages">messages</A> by using the &quot;<A HREF="various.html#:silent!">:silent!</A>&quot; command (checking for <A HREF="message.html#errors">errors</A> by testing
|<A HREF="#v:errmsg">v:errmsg</A>| if appropriate), its execution path is not changed.	The error is
not converted to an exception.	(See |<A HREF="various.html#:silent">:silent</A>|.)  So the only remaining cause
where this happens is for scripts that don't care about <A HREF="message.html#errors">errors</A> and produce
error <A HREF="message.html#messages">messages</A>.  You probably won't want to use such code from your new
scripts.


							*<A NAME="except-syntax-err"></A><B>except-syntax-err</B>*
<A HREF="autocmd.html#Syntax">Syntax</A> <A HREF="message.html#errors">errors</A> in the exception handling commands are never caught by any of
the &quot;<A HREF="#:catch">:catch</A>&quot; commands of the try conditional they belong to.  Its finally
clauses, however, is executed.
   Example:

<B>	:try</B>
<B>	:  try</B>
<B>	:    throw 4711</B>
<B>	:  catch /\(/</B>
<B>	:    echo "in catch with syntax error"</B>
<B>	:  catch</B>
<B>	:    echo "inner catch-all"</B>
<B>	:  finally</B>
<B>	:    echo "inner finally"</B>
<B>	:  endtry</B>
<B>	:catch</B>
<B>	:  echo 'outer catch-all caught "' . v:exception . '"'</B>
<B>	:  finally</B>
<B>	:    echo "outer finally"</B>
<B>	:endtry</B>

This displays:
<B>    inner finally</B>
<B>    outer catch-all caught "Vim(catch):E54: Unmatched \("</B>
<B>    outer finally</B>
The original exception is discarded and an error exception is raised, instead.


							*<A NAME="except-single-line"></A><B>except-single-line</B>*
The &quot;<A HREF="#:try">:try</A>&quot;, &quot;<A HREF="#:catch">:catch</A>&quot;, &quot;<A HREF="#:finally">:finally</A>&quot;, and &quot;<A HREF="#:endtry">:endtry</A>&quot; commands can be put on
a single line, but then <A HREF="syntax.html#syntax">syntax</A> <A HREF="message.html#errors">errors</A> may make <A HREF="motion.html#it">it</A> difficult to recognize the
&quot;catch&quot; line, thus you better avoid this.
   Example:
<B>	:try | unlet! foo # | catch | endtry</B>
raises an error exception for the trailing characters after the &quot;:unlet!&quot;
argument, but does not see the &quot;<A HREF="#:catch">:catch</A>&quot; and &quot;<A HREF="#:endtry">:endtry</A>&quot; commands, so that the
error exception is discarded and the &quot;E488: Trailing characters&quot; message gets
displayed.


							*<A NAME="except-several-errors"></A><B>except-several-errors</B>*
When several <A HREF="message.html#errors">errors</A> appear in a single command, the first error message is
usually the most specific one and therefor converted to the error exception.
   Example:
<B>	echo novar</B>
causes
<B>	E121: Undefined variable: novar</B>
<B>	E15: Invalid expression: novar</B>
The value of the error exception inside try conditionals is:
<B>	Vim(echo):E121: Undefined variable: novar</B>

 							*<A NAME="except-syntax-error"></A><B>except-syntax-error</B>*
But when a <A HREF="syntax.html#syntax">syntax</A> error is detected after a normal error in the same command,
the <A HREF="syntax.html#syntax">syntax</A> error is used for the exception being thrown.
   Example:
<B>	unlet novar #</B>
causes
<B>	E108: No such variable: "novar"</B>
<B>	E488: Trailing characters</B>
The value of the error exception inside try conditionals is:
<B>	Vim(unlet):E488: Trailing characters</B>
This is done because the <A HREF="syntax.html#syntax">syntax</A> error might change the execution path in a way
not intended by the user.  Example:
<B>	try</B>
<B>	    try | unlet novar # | catch | echo v:exception | endtry</B>
<B>	catch /.*/</B>
<B>	    echo "outer catch:" v:exception</B>
<B>	endtry</B>
This displays &quot;outer catch: Vim(unlet):E488: Trailing characters&quot;, and then
a &quot;E600: Missing :endtry&quot; error message is given, see |<A HREF="#except-single-line">except-single-line</A>|.

==============================================================================

9. Examples						*<A NAME="eval-examples"></A><B>eval-examples</B>*

<B><FONT COLOR="PURPLE">Printing in Binary </FONT></B>

<B>  :" The function Nr2Bin() returns the binary string representation of a number.</B>
<B>  :func Nr2Bin(nr)</B>
<B>  :  let n = a:nr</B>
<B>  :  let r = ""</B>
<B>  :  while n</B>
<B>  :    let r = '01'[n % 2] . r</B>
<B>  :    let n = n / 2</B>
<B>  :  endwhile</B>
<B>  :  return r</B>
<B>  :endfunc</B>

<B>  :" The function String2Bin() converts each character in a string to a</B>
<B>  :" binary string, separated with dashes.</B>
<B>  :func String2Bin(str)</B>
<B>  :  let out = ''</B>
<B>  :  for ix in range(strlen(a:str))</B>
<B>  :    let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))</B>
<B>  :  endfor</B>
<B>  :  return out[1:]</B>
<B>  :endfunc</B>

Example of its use:
<B>  :echo Nr2Bin(32)</B>
result: &quot;100000&quot;
<B>  :echo String2Bin("32")</B>
result: &quot;110011-110010&quot;


<B><FONT COLOR="PURPLE">Sorting lines </FONT></B>

This example sorts lines with a specific compare function.

<B>  :func SortBuffer()</B>
<B>  :  let lines = getline(1, '$')</B>
<B>  :  call sort(lines, function("Strcmp"))</B>
<B>  :  call setline(1, lines)</B>
<B>  :endfunction</B>

As a one-liner:
<B>  :call setline(1, sort(getline(1, '$'), function("Strcmp")))</B>


<B><FONT COLOR="PURPLE">scanf() replacement </FONT></B>

							*<A NAME="sscanf"></A><B>sscanf</B>*
There is no sscanf() function in Vim.  If you need to extract parts from a
line, you can use <A HREF="#matchstr()">matchstr()</A> and <A HREF="#substitute()">substitute()</A> to <A HREF="diff.html#do">do</A> <A HREF="motion.html#it">it</A>.  This example shows
how to get the file name, line number and column number out of a line like
&quot;foobar.txt, 123, 45&quot;.
<B>   :" Set up the match bit</B>
<B>   :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'</B>
<B>   :"get the part matching the whole expression</B>
<B>   :let l = matchstr(line, mx)</B>
<B>   :"get each item out of the match</B>
<B>   :let file = substitute(l, mx, '\1', '')</B>
<B>   :let lnum = substitute(l, mx, '\2', '')</B>
<B>   :let col = substitute(l, mx, '\3', '')</B>

The input is in the variable &quot;line&quot;, the results in the <A HREF="#variables">variables</A> &quot;file&quot;,
&quot;lnum&quot; and &quot;col&quot;. (idea from Michael Geddes)


<B><FONT COLOR="PURPLE">getting the scriptnames in a Dictionary </FONT></B>

						*<A NAME="scriptnames-dictionary"></A><B>scriptnames-dictionary</B>*
The |<A HREF="repeat.html#:scriptnames">:scriptnames</A>| command can be used to get a <A HREF="#list">list</A> of all script files that
have been sourced.  There is no equivalent function or variable for this
(because it's rarely needed).  In <A HREF="change.html#case">case</A> you need to manipulate the <A HREF="#list">list</A> this
code can be used:
<B>    " Get the output of ":scriptnames" in the scriptnames_output variable.</B>
<B>    let scriptnames_output = ''</B>
<B>    redir =&gt; scriptnames_output</B>
<B>    silent scriptnames</B>
<B>    redir END</B>
<B>    </B>
<B>    " Split the output into lines and parse each line.	Add an entry to the</B>
<B>    " "scripts" dictionary.</B>
<B>    let scripts = {}</B>
<B>    for line in split(scriptnames_output, "\n")</B>
<B>      " Only do non-blank lines.</B>
<B>      if line =~ '\S'</B>
<B>	" Get the first number in the line.</B>
<B>	let nr = matchstr(line, '\d\+')</B>
<B>	" Get the file name, remove the script number " 123: ".</B>
<B>	let name = substitute(line, '.\+:\s*', '', '')</B>
<B>	" Add an item to the Dictionary</B>
<B>	let scripts[nr] = name</B>
<B>      endif</B>
<B>    endfor</B>
<B>    unlet scriptnames_output</B>

==============================================================================

10. No <A HREF="various.html#+eval">+eval</A> feature				*<A NAME="no-eval-feature"></A><B>no-eval-feature</B>*

When the |<A HREF="various.html#+eval">+eval</A>| feature was disabled at compile time, none of the <A HREF="#expression">expression</A>
evaluation commands are available.  To prevent this from causing Vim scripts
to generate all kinds of <A HREF="message.html#errors">errors</A>, the &quot;<A HREF="#:if">:if</A>&quot; and &quot;<A HREF="#:endif">:endif</A>&quot; commands are still
recognized, though the argument of the &quot;<A HREF="#:if">:if</A>&quot; and everything between the &quot;<A HREF="#:if">:if</A>&quot;
and the matching &quot;<A HREF="#:endif">:endif</A>&quot; is ignored.  Nesting of &quot;<A HREF="#:if">:if</A>&quot; blocks is allowed, but
only if the commands are at the start of the line.  The &quot;<A HREF="#:else">:else</A>&quot; command is not
recognized.

Example of how to avoid executing commands when the |<A HREF="various.html#+eval">+eval</A>| feature is
missing:

<B>	:if 1</B>
<B>	:  echo "Expression evaluation is compiled in"</B>
<B>	:else</B>
<B>	:  echo "You will _never_ see this message"</B>
<B>	:endif</B>

==============================================================================

11. The <A HREF="#sandbox">sandbox</A>					*<A NAME="eval-sandbox"></A><B>eval-sandbox</B>* *<A NAME="sandbox"></A><B>sandbox</B>* *<A NAME="E48"></A><B>E48</B>*

The <A HREF="options.html#'foldexpr'">'foldexpr'</A>, <A HREF="options.html#'formatexpr'">'formatexpr'</A>, <A HREF="options.html#'includeexpr'">'includeexpr'</A>, <A HREF="options.html#'indentexpr'">'indentexpr'</A>, <A HREF="options.html#'statusline'">'statusline'</A> and
<A HREF="options.html#'foldtext'">'foldtext'</A> <A HREF="options.html#options">options</A> may be evaluated in a <A HREF="#sandbox">sandbox</A>.  This means that you are
protected from these expressions having nasty side effects.  This gives some
safety for when these <A HREF="options.html#options">options</A> are set from a <A HREF="options.html#modeline">modeline</A>.  It is also used when
the command from a <A HREF="tagsrch.html#tags">tags</A> file is executed and for <A HREF="undo.html#CTRL-R">CTRL-R</A> = in the command line.
The sandbox is also used for the |<A HREF="#:sandbox">:sandbox</A>| command.

These items are not allowed in the <A HREF="#sandbox">sandbox</A>:
	- <A HREF="change.html#changing">changing</A> the buffer text
	- defining or <A HREF="change.html#changing">changing</A> <A HREF="map.html#mapping">mapping</A>, autocommands, <A HREF="#functions">functions</A>, user commands
	- setting certain <A HREF="options.html#options">options</A> (see |<A HREF="options.html#option-summary">option-summary</A>|)

	- setting certain v: <A HREF="#variables">variables</A> (see |<A HREF="#v:var">v:var</A>|)  *<A NAME="E794"></A><B>E794</B>*
	- executing a shell command
	- reading or <A HREF="editing.html#writing">writing</A> a file
	- jumping to another buffer or editing a file
	- executing <A HREF="if_pyth.html#Python">Python</A>, <A HREF="if_perl.html#Perl">Perl</A>, etc. commands
This is not guaranteed 100&#37; secure, but <A HREF="motion.html#it">it</A> should block most attacks.


							*<A NAME=":san"></A><B>:san</B>* *<A NAME=":sandbox"></A><B>:sandbox</B>*
:san[dbox] {cmd}	Execute {cmd} in the <A HREF="#sandbox">sandbox</A>.  Useful to evaluate an
			option that may have been set from a <A HREF="options.html#modeline">modeline</A>, e.g.
			<A HREF="options.html#'foldexpr'">'foldexpr'</A>.


							*<A NAME="sandbox-option"></A><B>sandbox-option</B>*
A few <A HREF="options.html#options">options</A> contain an <A HREF="#expression">expression</A>.  When this <A HREF="#expression">expression</A> is evaluated <A HREF="motion.html#it">it</A> may
have to be done in the <A HREF="#sandbox">sandbox</A> to avoid a security risk.  But the <A HREF="#sandbox">sandbox</A> is
restrictive, thus this only happens when the option was set from an insecure
location.  Insecure in this context are:
- sourcing a <A HREF="starting.html#.vimrc">.vimrc</A> or <A HREF="starting.html#.exrc">.exrc</A> in the current directory
- while executing in the <A HREF="#sandbox">sandbox</A>
- value coming from a <A HREF="options.html#modeline">modeline</A>

Note that when in the <A HREF="#sandbox">sandbox</A> and saving an option value and restoring <A HREF="motion.html#it">it</A>, the
option will still be marked <A HREF="motion.html#as">as</A> <A HREF="motion.html#it">it</A> was set in the <A HREF="#sandbox">sandbox</A>.

==============================================================================

12. Textlock							*<A NAME="textlock"></A><B>textlock</B>*

In a few situations <A HREF="motion.html#it">it</A> is not allowed to change the text in the buffer, jump
to another <A HREF="windows.html#window">window</A> and some other things that might confuse or break what Vim
is currently doing.  This mostly applies to things that happen when Vim is
actually doing something else.	For example, evaluating the <A HREF="options.html#'balloonexpr'">'balloonexpr'</A> may
happen any moment the mouse cursor is resting at some position.

This is not allowed when the <A HREF="#textlock">textlock</A> is active:
	- <A HREF="change.html#changing">changing</A> the buffer text
	- jumping to another buffer or <A HREF="windows.html#window">window</A>
	- editing another file
	- closing a <A HREF="windows.html#window">window</A> or quitting Vim
	- etc.


<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>


</HTML>
vim-doc 2:7.4.1689-3ubuntu1 / usr / share / doc / vim-doc / html / eval.html
