vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 95:a2081e6febb8

updated for version 7.0037

author	vimboss
date	Tue, 11 Jan 2005 21:29:04 +0000
parents	9d4f762cc1d9
children	04f2e519ab18

comparison

equal deleted inserted replaced

-:0c2e08de4a75
+:a2081e6febb8
-*eval.txt*      For Vim version 7.0aa.  Last change: 2005 Jan 09
+*eval.txt*      For Vim version 7.0aa.  Last change: 2005 Jan 11
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
 	:let [var1, var2; rest] = mylist
 This works like: >
 	:let var1 = mylist[0]
 	:let var2 = mylist[1]
-	:let rest = mjlist[2:]
+	:let rest = mylist[2:]
 Except that there is no error if there are only two items.  "rest" will be an
 empty list then.
 	:call add(list, "new")		" append String item
 	: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
+	:call filter(list, #& =~ 'x'#)	" remove items with an 'x'
 Changing the oder of items in a list: >
 	:call sort(list)		" sort a list alphabetically
 	:call reverse(list)		" reverse the order of items
 	:endwhile
 Note that all items in the list should be of the same type, otherwise this
 results in an error |E706|.  To avoid this |:unlet| the variable at the end of
 the loop.
+If all you want to do is modify each item in the list then the |map()|
+function might be a simpler method than a for 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)
 	: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 list = split("a b c")	" create list from items in a string
+	:let string = join(list, ', ')	" create string from list items
 	:let s = string()		" String representation of a list
+	:call map(list, #'>> ' . &#)	" prepend ">> " to each item
 1.4 More about variables ~
 							*more-variables*
 If you need to know the type of a variable or expression, use the |type()|
 	expr9[expr1 : expr2]	substring of a String or sublist of a List
 |expr9|	number			number constant
 	"string"		string constant, backslash is special
 	'string'		string constant
+	#string#		string constant
 	[expr1, ...]		List
 	&option			option value
 	(expr1)			nested expression
 	variable		internal variable
 	va{ria}ble		internal variable with curly braces
 'string'		string constant			*expr-'*
 Note that single quotes are used.
 This string is taken as it is.  No backslashes are removed or have a special
-meaning.  A literal-string cannot contain a single quote.  Use a normal,
+meaning.  A literal-string cannot contain a single quote.  Use a double-quoted
-double-quoted string for that.
+string or sharp-string for that.
 Single quoted strings are useful for patterns, so that backslashes do not need
 to be doubled.  These two commands are equivalent: >
 	if a =~ "\\s*"
 	if a =~ '\s*'
+sharp-string						*sharp-string*
+---------------
+#string#		string constant			*expr-#*
+Most characters in the string are taken as-is.  Only the '#' character is
+special: It needs to be double to get one.
+Sharp-strings are useful when a string may contain single quotes, double
+quotes and/or backslashes.
 option						*expr-option* *E112* *E113*
 ------
 &option			option value, local value if possible
 cindent( {lnum})		Number	C indent for line {lnum}
 col( {expr})			Number	column nr of cursor or mark
 confirm( {msg} [, {choices} [, {default} [, {type}]]])
 				Number	number of choice picked by user
 copy( {expr})			any	make a shallow copy of {expr}
-count( {list}, {expr} [, {ic}])	 Number	 count how many {expr} are in {list}
+count( {list}, {expr} [, {start} [, {ic}]])
+				Number	 count how many {expr} are in {list}
 cscope_connection( [{num} , {dbpath} [, {prepend}]])
 				Number	checks existence of cscope connection
 cursor( {lnum}, {col})		Number	position cursor at {lnum}, {col}
 deepcopy( {expr})		any	make a full copy of {expr}
 delete( {fname})		Number	delete file {fname}
 did_filetype()			Number	TRUE if FileType autocommand event used
 diff_filler( {lnum})		Number	diff filler lines about {lnum}
 diff_hlID( {lnum}, {col})	Number	diff highlighting at {lnum}/{col}
 empty( {expr})			Number	TRUE if {expr} is empty
 escape( {string}, {chars})	String	escape {chars} in {string} with '\'
+eval( {string})			any	evaluate {string} into its value
 eventhandler( )			Number	TRUE if inside an event handler
 executable( {expr})		Number	1 if executable {expr} exists
 exists( {expr})			Number	TRUE if {expr} exists
 expand( {expr})			String	expand special keywords in {expr}
 filereadable( {file})		Number	TRUE if {file} is a readable file
+filter( {list}, {expr})		List	remove from {list} where {expr} is 0
+finddir( {name}[, {path}[, {count}]])
+				String	Find directory {name} in {path}
 findfile( {name}[, {path}[, {count}]])
-				String	Find fine {name} in {path}
+				String	Find file {name} in {path}
 filewritable( {file})		Number	TRUE if {file} is a writable file
 fnamemodify( {fname}, {mods})	String	modify file name
 foldclosed( {lnum})		Number	first line of fold at {lnum} if closed
 foldclosedend( {lnum})		Number	last line of fold at {lnum} if closed
 foldlevel( {lnum})		Number	fold level at {lnum}
 hlexists( {name})		Number	TRUE if highlight group {name} exists
 hlID( {name})			Number	syntax ID of highlight group {name}
 hostname()			String	name of the machine Vim is running on
 iconv( {expr}, {from}, {to})	String	convert encoding of {expr}
 indent( {lnum})			Number	indent of line {lnum}
-index( {list}, {expr} [, {ic}]) Number	index in {list} where {expr} appears
+index( {list}, {expr} [, {start} [, {ic}]])
+				Number	index in {list} where {expr} appears
 input( {prompt} [, {text}])	String	get input from the user
 inputdialog( {p} [, {t} [, {c}]]) String  like input() but in a GUI dialog
 inputrestore()			Number	restore typeahead
 inputsave()			Number	save and clear typeahead
 inputsecret( {prompt} [, {text}]) String  like input() but hiding the text
 insert( {list}, {item} [, {idx}]) List	insert {item} in {list} [before {idx}]
 isdirectory( {directory})	Number	TRUE if {directory} is a directory
+join( {list} [, {sep}])		String	join {list} items into one String
 len( {expr})			Number	the length of {expr}
 libcall( {lib}, {func}, {arg})	String	call {func} in library {lib} with {arg}
 libcallnr( {lib}, {func}, {arg})  Number  idem, but return a Number
 line( {expr})			Number	line nr of cursor, last line or mark
 line2byte( {lnum})		Number	byte count of line {lnum}
 lispindent( {lnum})		Number	Lisp indent for line {lnum}
 localtime()			Number	current time
+map( {list}, {expr})		List	change each item in {list} to {expr}
 maparg( {name}[, {mode}])	String	rhs of mapping {name} in mode {mode}
 mapcheck( {name}[, {mode}])	String	check for mappings matching {name}
 match( {expr}, {pat}[, {start}[, {count}]])
 				Number	position where {pat} matches in {expr}
 matchend( {expr}, {pat}[, {start}[, {count}]])
 setline( {lnum}, {line})	Number	set line {lnum} to {line}
 setreg( {n}, {v}[, {opt}])	Number	set register to value and type
 setwinvar( {nr}, {varname}, {val})	set {varname} in window {nr} to {val}
 simplify( {filename})		String	simplify filename as much as possible
 sort( {list} [, {func}])	List	sort {list}, using {func} to compare
-str2list( {expr} [, {pat}])	List	make List from {pat} separated {expr}
+split( {expr} [, {pat}])	List	make List from {pat} separated {expr}
 strftime( {format}[, {time}])	String	time in specified format
 stridx( {haystack}, {needle})	Number	first index of {needle} in {haystack}
-string( {expr})			String	{expr} converted to a String
+string( {expr})			String	String representation of {expr} value
 strlen( {expr})			Number	length of the String {expr}
 strpart( {src}, {start}[, {len}])
 				String	{len} characters of {src} at {start}
 strridx( {haystack}, {needle})	Number	last index of {needle} in {haystack}
 strtrans( {expr})		String	translate string to make it printable
 		that the original List can be changed without changing the
 		copy, and vise versa.  But the items are identical, thus
 		changing an item changes the contents of both Lists.  Also see
 		|deepcopy()|.
-count({list}, {expr} [, {ic}])					*count()*
+count({list}, {expr} [, {start} [, {ic}]])			*count()*
 		Return the number of times an item with value {expr} appears
 		in List {list}.
+		If {start} is given then don't count items with a lower index.
 		When {ic} is given and it's non-zero then case is ignored.
 							*cscope_connection()*
 cscope_connection([{num} , {dbpath} [, {prepend}]])
 		Escape the characters in {chars} that occur in {string} with a
 		backslash.  Example: >
 			:echo escape('c:\program files\vim', ' \')
 <		results in: >
 			c:\\program\ files\\vim
-<
+<							*eval()*
+eval({string})	Evaluate {string} and return the result.  Especially useful to
+		turn the result of |string()| back into the original value.
+		This works for Numbers, Strings and composites of them.
+		Also works for Funcrefs that refer to existing functions.
 eventhandler()						*eventhandler()*
 		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.
 extend({list1}, {list2} [, {idx}])			*extend()*
 		Append {list2} to {list1}.
 		If {idx} is given insert the items of {list2} before item
 		{idx} in {list1}.  When {idx} is zero insert before the first
-		item.  When {idx} is equal to len({list1}) {list2} is
+		item.  When {idx} is equal to len({list1}) then {list2} is
 		appended.
 		{list1} is changed when {list2} is not empty.
 		{list2} remains unchanged.
 		{list1} and {list2} must be Lists.
 		Returns {list1}.
 		name {file} exists, and can be read.  If {file} doesn't exist,
 		or is a directory, the result is FALSE.  {file} is any
 		expression, which is used as a String.
 							*file_readable()*
 		Obsolete name: file_readable().
+filter({list}, {expr})					*filter()* *E712*
+		For each item in {list} evaluate {expr} and when the result is
+		zero remove the item from the List.
+		Inside {expr} the symbol "&" stands for the existing
+		item.  Example: >
+			:call filter(mylist, #& !~ "OLD"#)
+<		Removes the items where "OLD" appears.
+		Note that {expr} is an expression that evaluates to an
+		expression.  Often it is good to use a |sharp-string| to avoid
+		having to double backslashes.
+		The operation is done in-place.  If you want a list to remain
+		unmodified make a copy first: >
+			:let l = filter(copy(mylist), #& =~ "KEEP"#)
+<		Returns {list}.
 finddir({name}[, {path}[, {count}]])				*finddir()*
 		Find directory {name} in {path}.
 		If {path} is omitted or empty then 'path' is used.
 		If the optional {count} is given, find {count}'s occurrence of
 		|c_CTRL-R_=|.
 		Example: >
 			:cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
 <		Also see |getcmdpos()| and |setcmdpos()|.
-getcmdpos({pos})					*getcmdpos()*
+getcmdpos()						*getcmdpos()*
 		Return the position of the cursor in the command line as a
 		byte count.  The first column is 1.
 		Only works when editing the command line, thus requires use of
 		|c_CTRL-\_e| or |c_CTRL-R_=|.  Returns 0 otherwise.
 		Also see |setcmdpos()| and |getcmdline()|.
 		of 'tabstop' is relevant.  {lnum} is used just like in
 		|getline()|.
 		When {lnum} is invalid -1 is returned.
-index({list}, {expr} [, {ic}])				*index()*
+index({list}, {expr} [, {start} [, {ic}]])			*index()*
 		Return the lowest index in List {list} where the item has a
 		value equal to {expr}.
+		If {start} is given then skip items with a lower index.
 		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")
 		The result is a Number, 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 expression, which is used as a String.
+join({list} [, {sep}])					*join()*
+		Join the items in {list} together into one String.
+		When {sep} is specified it 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 it there too: >
+			let lines = join(mylist, "\n") . "\n"
+<		String items are used as-is.  Lists and Dictionaries are
+		converted into a string like with |string()|.
+		The opposite function is |split()|.
 							*len()* *E701*
 len({expr})	The result is a Number, which is the length of the argument.
 		When {expr} is a String or a Number the length in bytes is
 		used, as with |strlen()|.
 		When {expr} is a List the number of items in the List is
 		|+lispindent| feature, -1 is returned.
 localtime()						*localtime()*
 		Return the current time, measured as seconds since 1st Jan
 		1970.  See also |strftime()| and |getftime()|.
+map({list}, {expr})					*map()*
+		Replace each item in {list} with the result of evaluating
+		{expr}.
+		Inside {expr} the symbol "&" stands for the existing
+		item.  Example: >
+			:call map(mylist, #"> " . & . " <"#)
+<		This puts "> " before and " <" after each item in "mylist".
+		Note that {expr} is an expression that evaluates to an
+		expression.  Often it is good to use a |sharp-string| to avoid
+		having to double backslashes.
+		The operation is done in-place.  If you want a list to remain
+		unmodified make a copy first: >
+			:let tlist = map(copy(mylist), # & . "\t"#)
+<		Returns {list}.
 maparg({name}[, {mode}])				*maparg()*
 		Return the rhs of mapping {name} in mode {mode}.  When there
 		is no mapping for {name}, an empty String is returned.
 		These characters can be used for {mode}:
 	:endif
 <		This avoids adding the "_vv" mapping when there already is a
 		mapping for "_v" or for "_vvv".
 match({expr}, {pat}[, {start}[, {count}]])			*match()*
-		The result is a Number, which gives the index (byte offset) in
+		When {expr} is a List then this returns the index of the first
-		{expr} where {pat} matches.
+		item where {pat} matches.  Each item is used as a String,
-		A match at the first character returns zero.
+		Lists and Dictionaries are used as echoed.
+		Otherwise, {expr} is used as a String.  The result is a
+		Number, which gives the index (byte offset) in {expr} where
+		{pat} matches.
+		A match at the first character or List item returns zero.
 		If there is no match -1 is returned.
 		Example: >
-			:echo match("testing", "ing")
+			:echo match("testing", "ing")	" results in 4
-<		results in "4".
+			:echo match([1, 'x'], '\a')	" results in 2
-		See |string-match| for how {pat} is used.
+<		See |string-match| for how {pat} is used.
 		When {count} is given use the {count}'th match.  When a match
-		is found the search for the next one starts on character
+		is found in a String the search for the next one starts on
-		further.  Thus this example results in 1: >
+		character further.  Thus this example results in 1: >
 			echo match("testing", "..", 0, 2)
-<		If {start} is given, the search starts from index {start}.
+<		In a List the search continues in the next item.
+		If {start} is given, the search starts from byte index
+		{start} in a String or item {start} in a List.
 		The result, however, is still the index counted from the
-		first character. Example: >
+		first character/item. Example: >
 			:echo match("testing", "ing", 2)
 <		result is again "4". >
 			:echo match("testing", "ing", 4)
 <		result is again "4". >
 			:echo match("testing", "t", 2)
 <		result is "3".
-		If {start} < 0, it will be set to 0.
+		For a String, if {start} < 0, it will be set to 0.  For a list
-		If {start} > strlen({expr}) -1 is returned.
+		the index is counted from the end.
+		If {start} is out of range (> strlen({expr} for a String or
+		> len({expr} for a List) -1 is returned.
 		See |pattern| for the patterns that are accepted.
 		The 'ignorecase' option is used to set the ignore-caseness of
 		the pattern.  'smartcase' is NOT used.  The matching is always
 		done like 'magic' is set and 'cpoptions' is empty.
 		The {start}, if given, has the same meaning as for match(). >
 			:echo matchend("testing", "ing", 2)
 <		results in "7". >
 			:echo matchend("testing", "ing", 5)
 <		result is "-1".
+		When {expr} is a List the result is equal to match().
 matchstr({expr}, {pat}[, {start}[, {count}]])			*matchstr()*
 		Same as match(), but return the matched string.  Example: >
 			:echo matchstr("testing", "ing")
 <		results in "ing".
 		The {start}, if given, has the same meaning as for match(). >
 			:echo matchstr("testing", "ing", 2)
 <		results in "ing". >
 			:echo matchstr("testing", "ing", 5)
 <		result is "".
+		When {expr} is a List then the matching item is returned.
+		The type isn't changed, it's not necessarily a String.
 							*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.
 sort({list} [, {func}])					*sort()* *E702*
 		Sort the items in {list} in-place.  Returns {list}.  If you
 		want a list to remain unmodified make a copy first: >
 			:let sortedlist = sort(copy(mylist))
 <		Uses the string representation of each item to sort on.
+		Numbers sort after Strings, Lists after Numbers.
 		When {func} is given and it is one then case is ignored.
 		When {func} is a Funcref or a function name, this function is
 		called to compare items.  The function is invoked with two
 		items as argument and must return zero if they are equal, 1 if
 		the first one sorts after the second one, -1 if the first one
 			func MyCompare(i1, i2)
 			   return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
 			endfunc
 			let sortedlist = sort(mylist, "MyCompare")
-str2list({expr} [, {pattern}])				*str2list()*
+split({expr} [, {pattern}])				*split()*
 		Make a List out of {expr}.  When {pattern} is omitted each
 		white-separated sequence of characters becomes an item.
 		Otherwise the string is split where {pattern} matches,
 		removing the matched characters.  Empty strings are omitted.
 		Example: >
-			:let words = str2list(getline('.'), '\W\+')
+			:let words = split(getline('.'), '\W\+')
 <		Since empty strings are not added the "\+" isn't required but
 		it makes the function work a bit faster.
+		The opposite function is |join()|.
 strftime({format} [, {time}])				*strftime()*
 		The result is a String, which is a formatted date and time, as
 		specified by the {format} string.  The given {time} is used,
 		  :echo stridx("An Example", "Example")	     3
 		  :echo stridx("Starting point", "Start")    0
 		  :echo stridx("Starting point", "start")   -1
 <
 							*string()*
-string({expr})	Return {expr} converted to a String.
+string({expr})	Return {expr} converted to a String.  If {expr} is a Number,
+		String or a composition of them, then the result can be parsed
+		back with |eval()|.
 			{expr} type	result ~
-			String		identical
+			String		#string#
-			Number		decimal representation
+			Number		123
-			Funcref		name of the function
+			Funcref		function(#name#)
-			List		"[item, item]" form
+			List		[item, item]
-		Note that string values are not in quotes, thus the result
+		Note that in String values the # character is doubled.
-		can't be parsed back to a List.
 							*strlen()*
 strlen({expr})	The result is a Number, which is the length of the String
 		{expr} in bytes.  If you want to count the number of
 		multi-byte characters use something like this: >

Mercurial > vim

comparison runtime/doc/eval.txt @ 95:a2081e6febb8