updated for version 7.0035

1 files changed, 80 insertions, 29 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 5eccc448d1..73b50fc766 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -14,8 +14,8 @@ last chapter below.
 
 1.  Variables			|variables|
     1.1 Variable types
-    1.2 Function reference		|Funcref|
-    1.3 List				|List|
+    1.2 Function references		|Funcref|
+    1.3 Lists				|List|
     1.4 More about variables		|more-variables|
 2.  Expression syntax		|expression-syntax|
 3.  Internal variable		|internal-variables|
@@ -80,11 +80,11 @@ You will get an error if you try to change the type of a variable.  You need
 to |:unlet| it first to avoid this error.  String and Number are considered
 equivalent though. >
 	:let l = "string"
-	:let l = 44
+	:let l = 44		" changes type from String to Number
 	:let l = [1, 2, 3]	" error!
 
 
-1.2 Function reference ~
+1.2 Function references ~
 						*Funcref* *E695* *E703*
 A Funcref variable is obtained with the |function()| function.  It can be used
 in an expression to invoke the function it refers to by using it in the place
@@ -97,8 +97,8 @@ of a function name, before the parenthesis around the arguments.  Example: >
 A Funcref variable must start with a capital, "s:", "w:" or "b:".  You cannot
 have both a Funcref variable and a function with the same name.
 
-Note that a Funcref cannot be used with |:call|, because its argument is not
-an expression.
+Note that a Funcref cannot be used with the |:call| command, because its
+argument is not an expression.
 
 The name of the referenced function can be obtained with |string()|. >
 	:echo "The function is " . string(Myfunc)
@@ -108,7 +108,7 @@ arguments: >
 	:let r = call(Myfunc, mylist)
 
 
-1.3 List ~
+1.3 Lists ~
 							*List* *E686*
 A List 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
@@ -136,7 +136,7 @@ after the List.  Indexes are zero-based, thus the first item has index zero. >
 	:let item = mylist[0]		" get the first item: 1
 	:let item = mylist[2]		" get the third item: 3
 
-When the item is a list again this can be repeated: >
+When the resulting item is a list this can be repeated: >
 	:let item = nestlist[0][1]	" get the first list, second item: 12
 <
 A negative index is counted from the end.  Index -1 refers to the last item in
@@ -144,7 +144,7 @@ the List, -2 to the last but one item, etc. >
 	:let last = mylist[-1]		" get the last item: "four"
 
 To avoid an error for an invalid index use the |get()| function.  When an item
-is not available it returns zero, unless you specify a default value: >
+is not available it returns zero or the default value you specify: >
 	:echo get(mylist, idx)
 	:echo get(mylist, idx, "NONE")
 
@@ -185,7 +185,7 @@ change "bb": >
 
 Making a copy of a list is done with the |copy()| function.  Using [:] also
 works, as explained above.  This creates a shallow copy of the list: Changing
-a list in the list will also change the copied list: >
+a list item in the list will also change the item in the copied list: >
 	:let aa = [[1, 'a'], 2, 3]
 	:let bb = copy(aa)
 	:let aa = aa + [4]
@@ -195,12 +195,18 @@ a list in the list will also change the copied list: >
 	:echo bb
 	[[1, aaa], 2, 3]
 
-To make a completely independent list use |deepcopy()|.  This also copies the
-values in the list, recursively.
+To make a completely independent list use |deepcopy()|.  This also makes a
+copy of the values in the list, recursively.
 
 The operator "is" can be used to check if two variables refer to the same
 list.  "isnot" does the opposite.  In contrast "==" compares if two lists have
-the same value.
+the same value. >
+	:let alist = [1, 2, 3]
+	:let blist = [1, 2, 3]
+	:echo alist is blist
+	0
+	:echo alist == blist
+	1
 
 
 List unpack ~
@@ -225,10 +231,14 @@ empty list then.
 
 List modification ~
 							*list-modification*
-To change a specific item of a list use |:let|: >
+To change a specific item of a list use |:let| this way: >
 	:let list[4] = "four"
 	:let listlist[0][3] = item
 
+To change part of a list you can specify the first and last item to be
+modified.  The value must mach the range of replaced items: >
+	:let list[3:5] = [3, 4, 5]
+
 Adding and removing items from a list is done with functions.  Here are a few
 examples: >
 	:call insert(list, 'a')		" prepend item 'a'
@@ -239,10 +249,15 @@ examples: >
 	:let i = remove(list, 3)	" remove item 3
 	:let l = remove(list, 3, -1)	" remove items 3 to last item
 
+Changing the oder of items in a list: >
+	:call sort(list)		" sort a list alphabetically
+	:call reverse(list)		" reverse the order of items
+
 
 For loop ~
 
-The |:for| loop executes commands for each item in a list.  Example: >
+The |:for| loop executes commands for each item in a list.  A variable is set
+to each item in the list in sequence.  Example: >
 	:for i in mylist
 	:   call Doit(i)
 	:endfor
@@ -256,8 +271,8 @@ This works like: >
 	:endwhile
 
 Note that all items in the list should be of the same type, otherwise this
-results in an error.  To avoid this |:unlet| the variable at the end of the
-loop.
+results in an error |E706|.  To avoid this |:unlet| the variable at the end of
+the loop.
 
 Just like the |:let| command, |:for| also accepts a list of variables.  This
 requires the argument to be a list of lists. >
@@ -280,11 +295,13 @@ It is also possible to put remaining items in a list: >
 List functions ~
 
 Functions that are useful with a List: >
-	:let r = call(funcname, list)	" invoke a function with argument list
+	:let r = call(funcname, list)	" call a function with an argument list
 	:if empty(list)			" check if list is empty
 	:let l = len(list)		" number of items in a list
-	:let xs = count(list, 'x')	" count occurrences of a value
-	:let i = index(list, 'x')	" find a value
+	:let big = max(list)		" maximum value in a list
+	:let small = min(list)		" minumum value in a list
+	:let xs = count(list, 'x')	" count nr of times 'x' appears in list
+	:let i = index(list, 'x')	" index of first 'x' in list
 	:let lines = getline(1, 10)	" get ten text lines from buffer
 	:call append('$', lines)	" append text lines in buffer
 	:let list = str2list("a b c")	" create list from items in a string
@@ -737,9 +754,10 @@ cannot start with a digit.  It's also possible to use curly braces, see
 |curly-braces-names|.
 
 An internal variable is created with the ":let" command |:let|.
-An internal variable is destroyed with the ":unlet" command |:unlet|.
-Using a name that isn't an internal variable, or an internal variable that has
-been destroyed, results in an error.
+An internal variable is explicitly destroyed with the ":unlet" command
+|:unlet|.
+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 variables.  Which one is to be used is
 specified by what is prepended:
@@ -1208,6 +1226,8 @@ matchend( {expr}, {pat}[, {start}[, {count}]])
 				Number	position where {pat} ends in {expr}
 matchstr( {expr}, {pat}[, {start}[, {count}]])
 				String	{count}'th match of {pat} in {expr}
+max({list})			Number	maximum value of items in {list}
+min({list})			Number	minumum value of items in {list}
 mode()				String	current editing mode
 nextnonblank( {lnum})		Number	line nr of non-blank line >= {lnum}
 nr2char( {expr})		String	single char with ASCII value {expr}
@@ -2346,6 +2366,7 @@ index({list}, {expr} [, {ic}])				*index()*
 		-1 is returned when {expr} is not found in {list}.
 		Example: >
 			:let idx = index(words, "the")
+			:if index(numbers, 123) >= 0
 
 
 input({prompt} [, {text}])				*input()*
@@ -2646,6 +2667,18 @@ matchstr({expr}, {pat}[, {start}[, {count}]])			*matchstr()*
 			:echo matchstr("testing", "ing", 5)
 <		result is "".
 
+							*max()*
+max({list})	Return the maximum value of all items in {list}.
+		If {list} is not a list or one of the items in {list} cannot
+		be used as a Number this results in an error.
+		An empty List results in zero.
+
+							*min()*
+min({list})	Return the minumum value of all items in {list}.
+		If {list} is not a list or one of the items in {list} cannot
+		be used as a Number this results in an error.
+		An empty List results in zero.
+
 							*mode()*
 mode()		Return a string that indicates the current mode:
 			n	Normal
@@ -2789,7 +2822,7 @@ repeat({expr}, {count})					*repeat()*
 		result.  Example: >
 			:let seperator = repeat('-', 80)
 <		When {count} is zero or negative the result is empty.
-		When {expr} is a list the result is {expr} concatenated
+		When {expr} is a List the result is {expr} concatenated
 		{count} times. Example: >
 			:let longlist = repeat(['a', 'b'], 3)
 <		Results in ['a', 'b', 'a', 'b', 'a', 'b'].
@@ -3297,10 +3330,17 @@ tr({src}, {fromstr}, {tostr})				*tr()*
 			echo tr("<blob>", "<>", "{}")
 <		returns "{blob}"
 
-type({expr})						*type()*
-		The result is a Number:
-			0 if {expr} has the type Number
-			1 if {expr} has the type String
+							*type()*
+type({expr})	The result is a Number, depending on the type of {expr}:
+			Number:  0
+			String:  1
+			Funcref: 2
+			List:    3
+		To avoid the magic numbers it can be used this way: >
+			:if type(myvar) == type(0)
+			:if type(myvar) == type("")
+			:if type(myvar) == type(function("tr"))
+			:if type(myvar) == type([])
 
 virtcol({expr})						*virtcol()*
 		The result is a Number, which is the screen column of the file
@@ -3841,6 +3881,15 @@ This would call the function "my_func_whizz(parameter)".
 			the index can be repeated.
 			This cannot be used to add an item to a list.
 
+:let {var-name}[{idx1}:{idx2}] = {expr1}	*E708* *E709* *E710* *E711*
+			Set a sequence of items in a List to the result of the
+			expression {expr1}, which must be a list with the
+			correct number of items.
+			{idx1} can be omitted, zero is used instead.
+			{idx2} can be omitted, meaning the end of the list.
+			When the selected range of items is partly past the
+			end of the list, items will be added.
+
 :let ${env-name} = {expr1}			*:let-environment* *:let-$*
 			Set environment variable {env-name} to the result of
 			the expression {expr1}.  The type is always String.
@@ -3985,7 +4034,9 @@ This would call the function "my_func_whizz(parameter)".
 				:for item in mylist
 				   :call remove(mylist, 0)
 				:endfor
-<			Note that the type of each list item should be
+<			Note that reordering the list (e.g., with sort() or
+			reverse()) may have unexpected effects.
+			Note that the type of each list item should be
 			identical to avoid errors for the type of {var}
 			changing.  Unlet the variable at the end of the loop
 			to allow multiple item types.