updated for version 7.0035

runtime/doc/eval.txt

@@ -14,8 +14,8 @@ last chapter below.
 
 1.  Variables			|variables|
     1.1 Variable types
-    1.2 Function reference		|Funcref|
+    1.2 Function references		|Funcref|
-    1.3 List				|List|
+    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
+Note that a Funcref cannot be used with the |:call| command, because its
-an expression.
+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
+To make a completely independent list use |deepcopy()|.  This also makes a
-values in the list, recursively.
+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
+results in an error |E706|.  To avoid this |:unlet| the variable at the end of
-loop.
+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 big = max(list)		" maximum value in a list
-	:let i = index(list, 'x')	" find a value
+	: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|.
+An internal variable is explicitly destroyed with the ":unlet" command
-Using a name that isn't an internal variable, or an internal variable that has
+|:unlet|.
-been destroyed, results in an error.
+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()*
+							*type()*
-		The result is a Number:
+type({expr})	The result is a Number, depending on the type of {expr}:
-			0 if {expr} has the type Number
+			Number:  0
-			1 if {expr} has the type String
+			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.

src/gui.c

@@ -4201,22 +4201,22 @@ gui_mouse_correct()
     win_T	*wp = NULL;
 
     need_mouse_correct = FALSE;
-    if (gui.in_use && p_mousef)
+
+    if (!(gui.in_use && p_mousef))
+	return;
+
+    gui_mch_getmouse(&x, &y);
+    /* Don't move the mouse when it's left or right of the Vim window */
+    if (x < 0 || x > Columns * gui.char_width)
+	return;
+    if (y >= 0)
+	wp = xy2win(x, y);
+    if (wp != curwin && wp != NULL)	/* If in other than current window */
     {
-	x = gui_mch_get_mouse_x();
+	validate_cline_row();
-	/* Don't move the mouse when it's left or right of the Vim window */
+	gui_mch_setmouse((int)W_ENDCOL(curwin) * gui.char_width - 3,
-	if (x < 0 || x > Columns * gui.char_width)
+		(W_WINROW(curwin) + curwin->w_wrow) * gui.char_height
-	    return;
-	y = gui_mch_get_mouse_y();
-	if (y >= 0)
-	    wp = xy2win(x, y);
-	if (wp != curwin && wp != NULL)	/* If in other than current window */
-	{
-	    validate_cline_row();
-	    gui_mch_setmouse((int)W_ENDCOL(curwin) * gui.char_width - 3,
-			 (W_WINROW(curwin) + curwin->w_wrow) * gui.char_height
 						     + (gui.char_height) / 2);
-	}
     }
 }
 

src/gui_kde_x11.cc

@@ -1303,19 +1303,13 @@ gui_mch_get_rgb(guicolor_T pixel)//{{{
 }//}}}
 
 /*
- * Get current y mouse coordinate in text window.
+ * Get current mouse coordinates in text window.
- * Return -1 when unknown.
  */
-    int
+    void
-gui_mch_get_mouse_x(void)//{{{
+gui_mch_getmouse(int *x, int *y)//{{{
 {
-    return vmw->mapFromGlobal(QCursor::pos()).x();
+    *x = vmw->mapFromGlobal(QCursor::pos()).x();
-}//}}}
+    *y = vmw->mapFromGlobal(QCursor::pos()).y();
-
-    int
-gui_mch_get_mouse_y(void)//{{{
-{
-    return vmw->mapFromGlobal(QCursor::pos()).y();
 }//}}}
 
     void

src/gui_mac.c

@@ -5672,27 +5672,16 @@ display_errors()
 #endif
 
 /*
- * Get current y mouse coordinate in text window.
+ * Get current mouse coordinates in text window.
- * Return -1 when unknown.
  */
-    int
+void gui_mch_getmouse(int *x, int *y)
-gui_mch_get_mouse_x()
 {
     Point where;
 
     GetMouse(&where);
 
-    return (where.h);
+    *x = where.h;
-}
+    *y = where.v;
-
-    int
-gui_mch_get_mouse_y()
-{
-    Point where;
-
-    GetMouse(&where);
-
-    return (where.v);
 }
 
     void

src/gui_photon.c

@@ -1896,29 +1896,18 @@ gui_mch_mousehide(int hide)
 }
 
     int
-gui_mch_get_mouse_x(void)
+gui_mch_getmouse(int *x, int *y)
 {
     PhCursorInfo_t info;
-    short x, y;
+    short ix, iy;
 
     /* FIXME: does this return the correct position,
      * with respect to the border? */
     PhQueryCursor( PhInputGroup( NULL ), &info );
-    PtGetAbsPosition( gui.vimTextArea , &x, &y );
+    PtGetAbsPosition( gui.vimTextArea , &ix, &iy );
 
-    return( info.pos.x - x );
+    *x = info.pos.x - ix;
-}
+    *y = info.pos.y - iy;
-
-    int
-gui_mch_get_mouse_y(void)
-{
-    PhCursorInfo_t info;
-    short x, y;
-
-    PhQueryCursor( PhInputGroup( NULL ), &info );
-    PtGetAbsPosition( gui.vimTextArea , &x, &y );
-    /* TODO: Add border offset? */
-    return( info.pos.y - y );
 }
 
     void

src/gui_riscos.c

@@ -3014,40 +3014,26 @@ gui_mch_set_scrollbar_colors(scrollbar_T *sb)
 }
 
 /*
- * Get current x mouse coordinate in text window.
+ * Get current mouse coordinates in text window.
  * Note: (0,0) is the bottom left corner, positive y is UP.
- * Return -1 when unknown.
  */
-    int
+    void
-gui_mch_get_mouse_x()
+gui_mch_getmouse(x, y)
+    int *x;
+    int *y;
 {
     int left;
-    int block[10];
-
-    block[0] = gui.window_handle;
-    swi(Wimp_GetWindowState, 0, block);
-    left = block[1];
-
-    swi(Wimp_GetPointerInfo, 0, block);
-    return block[0] - left;
-}
-
-/*
- * Get current y mouse coordinate in text window.
- * Return -1 when unknown.
- */
-    int
-gui_mch_get_mouse_y()
-{
     int top;
     int block[10];
 
     block[0] = gui.window_handle;
     swi(Wimp_GetWindowState, 0, block);
+    left = block[1];
     top = block[4];
 
     swi(Wimp_GetPointerInfo, 0, block);
-    return top - block[1];
+    *x = block[0] - left;
+    *y = top - block[1];
 }
 
 /* MouseTo(x, y) */

src/gui_w32.c

@@ -3184,6 +3184,8 @@ gui_mch_tearoff(
     int		nameLen;
     int		padding0, padding1, padding2 = 0;
     int		sepPadding=0;
+    int		x;
+    int		y;
 #ifdef USE_SYSMENU_FONT
     LOGFONT	lfSysmenu;
     int		use_lfSysmenu = FALSE;
@@ -3304,12 +3306,13 @@ gui_mch_tearoff(
     *p++ = HIWORD(lExtendedStyle);
     pnumitems = p;	/* save where the number of items must be stored */
     *p++ = 0;		// NumberOfItems(will change later)
+    gui_mch_getmouse(&x, &y);
     if (initX == 0xffffL)
-	*p++ = PixelToDialogX(gui_mch_get_mouse_x()); // x
+	*p++ = PixelToDialogX(x); // x
     else
 	*p++ = PixelToDialogX(initX); // x
     if (initY == 0xffffL)
-	*p++ = PixelToDialogY(gui_mch_get_mouse_y()); // y
+	*p++ = PixelToDialogY(y); // y
     else
 	*p++ = PixelToDialogY(initY); // y
     *p++ = PixelToDialogX(dlgwidth);    // cx

src/gui_w48.c

@@ -2411,33 +2411,18 @@ gui_mch_destroy_scrollbar(scrollbar_T *sb)
 #endif
 
 /*
- * Get current x mouse coordinate in text window.
+ * Get current mouse coordinates in text window.
- * Return -1 when unknown.
  */
-    int
+    void
-gui_mch_get_mouse_x(void)
+gui_mch_get_mouse_(int *x, int *y)
 {
     RECT rct;
     POINT mp;
 
     (void)GetWindowRect(s_textArea, &rct);
     (void)GetCursorPos((LPPOINT)&mp);
-    return (int)(mp.x - rct.left);
+    *x = (int)(mp.x - rct.left);
-}
+    *y = (int)(mp.y - rct.top);
-
-/*
- * Get current y mouse coordinate in text window.
- * Return -1 when unknown.
- */
-    int
-gui_mch_get_mouse_y(void)
-{
-    RECT rct;
-    POINT mp;
-
-    (void)GetWindowRect(s_textArea, &rct);
-    (void)GetCursorPos((LPPOINT)&mp);
-    return (int)(mp.y - rct.top);
 }
 
 /*

src/misc2.c

@@ -3026,7 +3026,9 @@ get_shape_idx(mouse)
     if (mouse && (State == HITRETURN || State == ASKMORE))
     {
 # ifdef FEAT_GUI
-	if (Y_2_ROW(gui_mch_get_mouse_y()) == Rows - 1)
+	int x, y;
+	gui_mch_getmouse(&x, &y);
+	if (Y_2_ROW(y) == Rows - 1)
 	    return SHAPE_IDX_MOREL;
 # endif
 	return SHAPE_IDX_MORE;

src/proto/gui_gtk_x11.pro

@@ -57,8 +57,7 @@ void gui_mch_menu_hidden __ARGS((vimmenu_T *menu, int hidden));
 void gui_mch_draw_menubar __ARGS((void));
 void gui_mch_enable_scrollbar __ARGS((scrollbar_T *sb, int flag));
 long_u gui_mch_get_rgb __ARGS((guicolor_T pixel));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 void gui_mch_mousehide __ARGS((int hide));
 void mch_set_mouse_shape __ARGS((int shape));

src/proto/gui_kde_x11.pro

@@ -52,8 +52,7 @@ void gui_mch_menu_hidden __ARGS((vimmenu_T *menu, int hidden));
 void gui_mch_draw_menubar __ARGS((void));
 void gui_mch_enable_scrollbar __ARGS((scrollbar_T *sb, int flag));
 long_u gui_mch_get_rgb __ARGS((guicolor_T pixel));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 void gui_mch_mousehide __ARGS((int hide));
 void mch_set_mouse_shape __ARGS((int shape));

src/proto/gui_mac.pro

@@ -17,8 +17,7 @@ short gui_mch_get_mac_menu_item_index __ARGS((vimmenu_T *menu, vimmenu_T *parent
 void gui_mch_set_blinking __ARGS((long wait, long on, long off));
 void gui_mch_stop_blink __ARGS((void));
 void gui_mch_start_blink __ARGS((void));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 void gui_mch_prepare __ARGS((int *argc, char **argv));
 int gui_mch_init_check __ARGS((void));

src/proto/gui_photon.pro

@@ -23,8 +23,7 @@ void gui_mch_enable_scrollbar __ARGS((scrollbar_T *sb, int flag));
 void gui_mch_destroy_scrollbar __ARGS((scrollbar_T *sb));
 void mch_set_mouse_shape __ARGS((int shape));
 void gui_mch_mousehide __ARGS((int hide));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 long_u gui_mch_get_rgb __ARGS((guicolor_T pixel));
 void gui_mch_new_colors __ARGS((void));

src/proto/gui_w16.pro

@@ -39,8 +39,7 @@ void gui_mch_find_dialog __ARGS((exarg_T *eap));
 void gui_mch_replace_dialog __ARGS((exarg_T *eap));
 void gui_mch_mousehide __ARGS((int hide));
 void gui_mch_destroy_scrollbar __ARGS((scrollbar_T *sb));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 void gui_mch_get_screen_dimensions __ARGS((int *screen_w, int *screen_h));
 void gui_mch_flash __ARGS((int msec));

src/proto/gui_w32.pro

@@ -39,8 +39,7 @@ void gui_mch_find_dialog __ARGS((exarg_T *eap));
 void gui_mch_replace_dialog __ARGS((exarg_T *eap));
 void gui_mch_mousehide __ARGS((int hide));
 void gui_mch_destroy_scrollbar __ARGS((scrollbar_T *sb));
-int gui_mch_get_mouse_x __ARGS((void));
+void gui_mch_getmouse __ARGS((int *x, int *y));
-int gui_mch_get_mouse_y __ARGS((void));
 void gui_mch_setmouse __ARGS((int x, int y));
 void gui_mch_get_screen_dimensions __ARGS((int *screen_w, int *screen_h));
 void gui_mch_flash __ARGS((int msec));