vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 87:014ba200db86

updated for version 7.0035

author	vimboss
date	Sat, 08 Jan 2005 21:45:39 +0000
parents	fc244e0a6e7e
children	9d4f762cc1d9

comparison

equal deleted inserted replaced

-:8173ec1e9f1f
+:014ba200db86
 done, the features in this document are not available.  See |+eval| and the
 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|
 4.  Builtin Functions		|functions|
 5.  Defining functions		|user-functions|
 								*E706*
 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
 of a function name, before the parenthesis around the arguments.  Example: >
 <
 							*E704* *E705* *E707*
 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)
 You can use |call()| to invoke a Funcref and use a list variable for the
 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
 position in the sequence.
 An item in the List can be accessed by putting the index in square brackets
 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
 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")
 List concatenation ~
 	:echo bb
 	[1, 2, 3, 4]
 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]
 	:let aa[0][1] = 'aaa'
 	:echo aa
 	[[1, aaa], 2, 3, 4]
 	: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 ~
 To unpack the items in a list to individual variables, put the variables in
 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'
 	:call insert(list, 'a', 3)	" insert item 'a' before list[3]
 	:call add(list, [1, 2])		" append List as one new item
 	:call extend(list, [1, 2])	" extend the list with two more items
 	: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
 This works like: >
 	:   :call Doit(i)
 	:   let index = index + 1
 	: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. >
 	:for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
 	:   call Doit(lnum, col)
 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
 	:let s = string()		" String representation of a list
 An internal variable name can be made up of letters, digits and '_'.  But it
 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:
 		(nothing) In a function: local to a function; otherwise: global
 				Number	position where {pat} matches in {expr}
 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}
 prevnonblank( {lnum})		Number	line nr of non-blank line <= {lnum}
 remote_expr( {server}, {string} [, {idvar}])
 		When {ic} is given and it is non-zero, ignore case.  Otherwise
 		case must match.
 		-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()*
 		The result is a String, which is whatever the user typed on
 		the command-line.  The parameter is either a prompt string, or
 			:echo matchstr("testing", "ing", 2)
 <		results in "ing". >
 			: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
 			v	Visual by character
 			V	Visual by line
 repeat({expr}, {count})					*repeat()*
 		Repeat {expr} {count} times and return the concatenated
 		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'].
 			echo tr("hello there", "ht", "HT")
 <		returns "Hello THere" >
 			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
 		position given with {expr}.  That is, the last screen position
 		occupied by the character at that position, when the screen
 			{expr1}.  {var-name} must refer to a list and {idx}
 			must be a valid index in that list.  For nested list
 			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.
 :let @{reg-name} = {expr1}			*:let-register* *:let-@*
 			it will not be found.  Thus the following example
 			works (an inefficient way to make a list empty): >
 				: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.
 :for {var} in {string}

Mercurial > vim

comparison runtime/doc/eval.txt @ 87:014ba200db86