vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 82:366d9947baf2

updated for version 7.0033

author	vimboss
date	Fri, 07 Jan 2005 21:48:26 +0000
parents	e918d3e340a4
children	fc244e0a6e7e

comparison

equal deleted inserted replaced

-:bf3f798c35c6
+:366d9947baf2
-*eval.txt*      For Vim version 7.0aa.  Last change: 2005 Jan 06
+*eval.txt*      For Vim version 7.0aa.  Last change: 2005 Jan 07
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
 (Use CTRL-] on the function name to jump to the full explanation)
 USAGE				RESULT	DESCRIPTION	~
+add( {list}, {item})		List	append {item} to List {list}
 append( {lnum}, {string})	Number	append {string} below line {lnum}
-append( {list}, {item})		List	append {item} to List {list}
 argc()				Number	number of files in the argument list
 argidx()			Number	current index in the argument list
 argv( {nr})			String	{nr} entry of the argument list
 browse( {save}, {title}, {initdir}, {default})
 				String	put up a file requester
 foldclosedend( {lnum})		Number	last line of fold at {lnum} if closed
 foldlevel( {lnum})		Number	fold level at {lnum}
 foldtext( )			String	line displayed for closed fold
 foreground( )			Number	bring the Vim window to the foreground
 function( {name})		Funcref reference to function {name}
+get( {list}, {idx} [, {def}])	any	get item {idx} from {list} or {def}
 getchar( [expr])		Number	get one character from the user
 getcharmod( )			Number	modifiers for the last typed character
 getbufvar( {expr}, {varname})		variable {varname} in buffer {expr}
 getcmdline()			String	return the current command-line
 getcmdpos()			Number	return cursor position in command-line
 				String	send key sequence
 remove( {list}, {idx} [, {end}])  any	remove items {idx}-{end} from {list}
 rename( {from}, {to})		Number	rename (move) file from {from} to {to}
 repeat( {expr}, {count})	String	repeat {expr} {count} times
 resolve( {filename})		String	get filename a shortcut points to
+reverse( {list})		List	reverse {list} in-place
 search( {pattern} [, {flags}])	Number	search for {pattern}
 searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]])
 				Number	search for other end of start/end pair
 server2client( {clientid}, {string})
 				Number	send reply string
 setcmdpos( {pos})		Number	set cursor position in command-line
 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}
 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
 strlen( {expr})			Number	length of the String {expr}
 strpart( {src}, {start}[, {len}])
 winline()			Number	window line of the cursor
 winnr()				Number	number of current window
 winrestcmd()			String	returns command to restore window sizes
 winwidth( {nr})			Number	width of window {nr}
-append({expr1}, {expr2})				*append()*
+add({list}, {expr})					*add()*
-		If {expr1} is a List: Append the item {expr2} to List {expr1}.
+		Append the item {expr} to List {list}.  Returns the resulting
-		Returns the resulting List. Examples: >
+		List. Examples: >
-			:let alist = append([1, 2, 3], item)
+			:let alist = add([1, 2, 3], item)
-			:call append(mylist, "woodstock")
+			:call add(mylist, "woodstock")
-<		Note that when {expr2} is a List it is appended as a single
+<		Note that when {expr} is a List it is appended as a single
 		item.  Use |extend()| to concatenate Lists.
-		When {expr1} is not a List: Append the text {expr2} after line
-		{expr1} in the current buffer.  {expr1} can be zero, to insert
+append({lnum}, {expr})					*append()*
-		a line before the first one.  Returns 1 for failure ({expr1}
+		When {expr} is a List: Append each item of the list as a text
-		out of range or out of memory), 0 for success.  Example: >
+		line below line {lnum} in the current buffer.
+		Otherwise append the text line {expr} 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: >
 			:let failed = append(line('$'), "# THE END")
+			:let failed = append(0, ["Chapter 1", "the beginning"])
 <
 							*argc()*
 argc()		The result is the number of files in the argument list of the
 		current window.  See |arglist|.
 		{list1} and {list2} must be Lists.
 		Returns {list1}.
 		Examples: >
 			:echo sort(extend(mylist, [7, 5]))
 			:call extend(mylist, [2, 3], 1)
-<		Use |append()| to concatenate one item to a list.  To
+<		Use |add()| to concatenate one item to a list.  To concatenate
-		concatenate two lists into a new list use the + operator: >
+		two lists into a new list use the + operator: >
 			:let newlist = [1, 2, 3] + [4, 5]
 filereadable({file})					*filereadable()*
 		The result is a Number, which is TRUE when a file with the
 		name {file} exists, and can be read.  If {file} doesn't exist,
 		allow a window to bring itself to the foreground.  Use
 		|remote_foreground()| instead.
 		{only in the Win32, Athena, Motif and GTK GUI versions and the
 		Win32 console version}
 function({name})					*function()*
 		Return a Funcref variable that refers to function {name}.
 		{name} can be a user defined function or an internal function.
+get({list}, {idx} [, {default}])			*get*
+		Get item {idx} from List {list}.  When this item is not
+		available return {default}.  Return zero when {default} is
+		omitted.
+getbufvar({expr}, {varname})				*getbufvar()*
+		The result is the value of option or local buffer variable
+		{varname} in buffer {expr}.  Note that the name without "b:"
+		must be used.
+		This also works for a global or local window option, but it
+		doesn't work for a global or local window variable.
+		For the use of {expr}, see |bufname()| above.
+		When the buffer or variable doesn't exist an empty string is
+		returned, there is no error message.
+		Examples: >
+			:let bufmodified = getbufvar(1, "&mod")
+			:echo "todo myvar = " . getbufvar("todo", "myvar")
+<
 getchar([expr])						*getchar()*
 		Get a single character from the user.  If it is an 8-bit
 		character, the result is a number.  Otherwise a String is
 		returned with the encoded character.  For a special key it's a
 		sequence of bytes starting with 0x80 (decimal: 128).
 			128	Macintosh only: command
 		Only the modifiers that have not been included in the
 		character itself are obtained.  Thus Shift-a results in "A"
 		with no modifier.
-getbufvar({expr}, {varname})				*getbufvar()*
-		The result is the value of option or local buffer variable
-		{varname} in buffer {expr}.  Note that the name without "b:"
-		must be used.
-		This also works for a global or local window option, but it
-		doesn't work for a global or local window variable.
-		For the use of {expr}, see |bufname()| above.
-		When the buffer or variable doesn't exist an empty string is
-		returned, there is no error message.
-		Examples: >
-			:let bufmodified = getbufvar(1, "&mod")
-			:echo "todo myvar = " . getbufvar("todo", "myvar")
-<
 getcmdline()						*getcmdline()*
 		Return the current command-line.  Only works when the command
 		line is being edited, thus requires use of |c_CTRL-\_e| or
 		|c_CTRL-R_=|.
 		Example: >
 <		Note that a type such as "link" will only be returned on
 		systems that support it.  On some systems only "dir" and
 		"file" are returned.
 							*getline()*
-getline({lnum}) The result is a String, which is line {lnum} from the current
+getline({lnum} [, {end}])
-		buffer.  Example: >
+		Without {end} the result is a String, which is line {lnum}
+		from the current buffer.  Example: >
 			getline(1)
 <		When {lnum} is a String that doesn't start with a
 		digit, line() is called to translate the String into a Number.
 		To get the line under the cursor: >
 			getline(".")
 <		When {lnum} is smaller than 1 or bigger than the number of
 		lines in the buffer, an empty string is returned.
+		When {end} is given the result is a List 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 as {lnum}.
+		Non-existing lines are silently omitted.
+		When {end} is before {lnum} an error is given.
+		Example: >
+			:let start = line('.')
+			:let end = search("^$") - 1
+			:let lines = getline(start, end)
 getreg([{regname}])					*getreg()*
 		The result is a String, which is the contents of register
 		{regname}. Example: >
 			:let cliptext = getreg('*')
 <		getreg('=') returns the last evaluated value of the expression
 		register. (For use in maps).
 		If {regname} is not specified, |v:register| is used.
 getregtype([{regname}])					*getregtype()*
 		The result is a String, which is type of register {regname}.
 		The value will be one of:
 		    "v"			for |characterwise| text
 		    "V"			for |linewise| text
 		    "<CTRL-V>{width}"	for |blockwise-visual| text
 		    0			for an empty or unknown register
 		<CTRL-V> is one character with value 0x16.
 		If {regname} is not specified, |v:register| is used.
 							*getwinposx()*
 getwinposx()	The result is a Number, which is the X coordinate in pixels of
 		the left hand side of the GUI Vim window.  The result will be
 		-1 if the information is not available.
 		|list-index|.  -1 inserts just before the last item.
 		Returns the resulting List. Examples: >
 			:let mylist = insert([2, 3, 5], 1)
 			:call insert(mylist, 4, -1)
 			:call insert(mylist, 6, len(mylist))
-<		The last example can be done simpler with |append()|.
+<		The last example can be done simpler with |add()|.
 		Note that when {item} is a List it is inserted as a single
 		item.  Use |extend()| to concatenate Lists.
 isdirectory({directory})				*isdirectory()*
 		The result is a Number, which is non-zero when a directory
 		:autocmd NONE RemoteReply *
 		 \ echo remote_read(expand("<amatch>"))
 		:echo remote_send("gvim", ":sleep 10 | echo ".
 		 \ 'server2client(expand("<client>"), "HELLO")<CR>')
+<
 remove({list}, {idx} [, {end}])				*remove()*
 		Without {end}: Remove the item at {idx} from List {list} and
 		return it.
 		With {end}: Remove items from {idx} to {end} (inclusive) and
 		return a list with these items.  When {idx} points to the same
 		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'].
 resolve({filename})					*resolve()* *E655*
 		On MS-Windows, when {filename} is a shortcut (a .lnk file),
 		returns the path the shortcut points to in a simplified form.
 		On Unix, repeat resolving symbolic links in all path
 		components of {filename} and return the simplified result.
 		On other systems, return the simplified {filename}.
 		The simplification step is done as by |simplify()|.
 		resolve() 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.
+							*reverse()*
+reverse({list})	Reverse the order of items in {list} in-place.  Returns
+		{list}.
+		If you want a list to remain unmodified make a copy first: >
+			:let revlist = reverse(copy(mylist))
 search({pattern} [, {flags}])				*search()*
 		Search for regexp pattern {pattern}.  The search starts at the
 		cursor position.
 		{flags} is a String, which can contain these character flags:
 		a searchable directory or does not exist.  On Unix, it is also
 		removed when "dir" is a symbolic link within the same
 		directory.  In order to resolve all the involved symbolic
 		links before simplifying the path name, use |resolve()|.
+sort({list} [, {func}])					*sort()*
+		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.
+		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
+		sorts before the second one.  Example: >
+			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()*
+		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\+')
+<		Since empty strings are not added the "\+" isn't required but
+		it makes the function work a bit faster.
 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,
 		or the current time if no time is given.  The accepted
 		{format} depends on your system, thus this is not portable!
 		  :echo strftime("%Y %b %d %X")	   1997 Apr 27 11:53:25
 		  :echo strftime("%y%m%d %T")	   970427 11:53:55
 		  :echo strftime("%H:%M")	   11:55
 		  :echo strftime("%c", getftime("file.c"))
 						   Show mod time of file.c.
-<
+<		Not available on all systems.  To check use: >
+			:if exists("*strftime")
 stridx({haystack}, {needle})				*stridx()*
 		The result is a Number, which gives the index in {haystack} of
 		the first occurrence of the String {needle} in the String
 		{haystack}. The search is done case-sensitive. For advanced
 		searches use |match()|.

Mercurial > vim

comparison runtime/doc/eval.txt @ 82:366d9947baf2