comparison runtime/doc/eval.txt @ 26777:629e7046ef63 v8.2.3917

patch 8.2.3917: the eval.txt help file is way too big Commit: https://github.com/vim/vim/commit/1cae5a0a034d0545360387407a7a409310f1efe2 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Dec 27 21:28:34 2021 +0000 patch 8.2.3917: the eval.txt help file is way too big Problem: The eval.txt help file is way too big. Solution: Move the builtin function details to a separate file.
author Bram Moolenaar <Bram@vim.org>
date Mon, 27 Dec 2021 22:30:02 +0100
parents 30972227ac8d
children eafb9fd4ec32
comparison
equal deleted inserted replaced
26776:7560ecdb2a6e 26777:629e7046ef63
10 10
11 Note: Expression evaluation can be disabled at compile time. If this has been 11 Note: Expression evaluation can be disabled at compile time. If this has been
12 done, the features in this document are not available. See |+eval| and 12 done, the features in this document are not available. See |+eval| and
13 |no-eval-feature|. 13 |no-eval-feature|.
14 14
15 This file is about the backwards compatible Vim script. For Vim9 script, 15 This file is mainly about the backwards compatible (legacy) Vim script. For
16 which executes much faster, supports type checking and much more, see 16 specifics of Vim9 script, which executes much faster, supports type checking
17 |vim9.txt|. 17 and much more, see |vim9.txt|. Where the syntax or semantics differ a remark
18 is given.
18 19
19 1. Variables |variables| 20 1. Variables |variables|
20 1.1 Variable types 21 1.1 Variable types
21 1.2 Function references |Funcref| 22 1.2 Function references |Funcref|
22 1.3 Lists |Lists| 23 1.3 Lists |Lists|
2531 ============================================================================== 2532 ==============================================================================
2532 4. Builtin Functions *functions* 2533 4. Builtin Functions *functions*
2533 2534
2534 See |function-list| for a list grouped by what the function is used for. 2535 See |function-list| for a list grouped by what the function is used for.
2535 2536
2536 (Use CTRL-] on the function name to jump to the full explanation.) 2537 The alphabetic list of all builtin functions and details are in a separate
2537 2538 help file: |builtin-functions|.
2538 USAGE RESULT DESCRIPTION ~
2539
2540 abs({expr}) Float or Number absolute value of {expr}
2541 acos({expr}) Float arc cosine of {expr}
2542 add({object}, {item}) List/Blob append {item} to {object}
2543 and({expr}, {expr}) Number bitwise AND
2544 append({lnum}, {text}) Number append {text} below line {lnum}
2545 appendbufline({expr}, {lnum}, {text})
2546 Number append {text} below line {lnum}
2547 in buffer {expr}
2548 argc([{winid}]) Number number of files in the argument list
2549 argidx() Number current index in the argument list
2550 arglistid([{winnr} [, {tabnr}]]) Number argument list id
2551 argv({nr} [, {winid}]) String {nr} entry of the argument list
2552 argv([-1, {winid}]) List the argument list
2553 asin({expr}) Float arc sine of {expr}
2554 assert_beeps({cmd}) Number assert {cmd} causes a beep
2555 assert_equal({exp}, {act} [, {msg}])
2556 Number assert {exp} is equal to {act}
2557 assert_equalfile({fname-one}, {fname-two} [, {msg}])
2558 Number assert file contents are equal
2559 assert_exception({error} [, {msg}])
2560 Number assert {error} is in v:exception
2561 assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])
2562 Number assert {cmd} fails
2563 assert_false({actual} [, {msg}])
2564 Number assert {actual} is false
2565 assert_inrange({lower}, {upper}, {actual} [, {msg}])
2566 Number assert {actual} is inside the range
2567 assert_match({pat}, {text} [, {msg}])
2568 Number assert {pat} matches {text}
2569 assert_nobeep({cmd}) Number assert {cmd} does not cause a beep
2570 assert_notequal({exp}, {act} [, {msg}])
2571 Number assert {exp} is not equal {act}
2572 assert_notmatch({pat}, {text} [, {msg}])
2573 Number assert {pat} not matches {text}
2574 assert_report({msg}) Number report a test failure
2575 assert_true({actual} [, {msg}]) Number assert {actual} is true
2576 atan({expr}) Float arc tangent of {expr}
2577 atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
2578 balloon_gettext() String current text in the balloon
2579 balloon_show({expr}) none show {expr} inside the balloon
2580 balloon_split({msg}) List split {msg} as used for a balloon
2581 blob2list({blob}) List convert {blob} into a list of numbers
2582 browse({save}, {title}, {initdir}, {default})
2583 String put up a file requester
2584 browsedir({title}, {initdir}) String put up a directory requester
2585 bufadd({name}) Number add a buffer to the buffer list
2586 bufexists({buf}) Number |TRUE| if buffer {buf} exists
2587 buflisted({buf}) Number |TRUE| if buffer {buf} is listed
2588 bufload({buf}) Number load buffer {buf} if not loaded yet
2589 bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded
2590 bufname([{buf}]) String Name of the buffer {buf}
2591 bufnr([{buf} [, {create}]]) Number Number of the buffer {buf}
2592 bufwinid({buf}) Number window ID of buffer {buf}
2593 bufwinnr({buf}) Number window number of buffer {buf}
2594 byte2line({byte}) Number line number at byte count {byte}
2595 byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2596 byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2597 call({func}, {arglist} [, {dict}])
2598 any call {func} with arguments {arglist}
2599 ceil({expr}) Float round {expr} up
2600 ch_canread({handle}) Number check if there is something to read
2601 ch_close({handle}) none close {handle}
2602 ch_close_in({handle}) none close in part of {handle}
2603 ch_evalexpr({handle}, {expr} [, {options}])
2604 any evaluate {expr} on JSON {handle}
2605 ch_evalraw({handle}, {string} [, {options}])
2606 any evaluate {string} on raw {handle}
2607 ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2608 ch_getjob({channel}) Job get the Job of {channel}
2609 ch_info({handle}) String info about channel {handle}
2610 ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2611 ch_logfile({fname} [, {mode}]) none start logging channel activity
2612 ch_open({address} [, {options}])
2613 Channel open a channel to {address}
2614 ch_read({handle} [, {options}]) String read from {handle}
2615 ch_readblob({handle} [, {options}])
2616 Blob read Blob from {handle}
2617 ch_readraw({handle} [, {options}])
2618 String read raw from {handle}
2619 ch_sendexpr({handle}, {expr} [, {options}])
2620 any send {expr} over JSON {handle}
2621 ch_sendraw({handle}, {expr} [, {options}])
2622 any send {expr} over raw {handle}
2623 ch_setoptions({handle}, {options})
2624 none set options for {handle}
2625 ch_status({handle} [, {options}])
2626 String status of channel {handle}
2627 changenr() Number current change number
2628 char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr}
2629 charclass({string}) Number character class of {string}
2630 charcol({expr}) Number column number of cursor or mark
2631 charidx({string}, {idx} [, {countcc}])
2632 Number char index of byte {idx} in {string}
2633 chdir({dir}) String change current working directory
2634 cindent({lnum}) Number C indent for line {lnum}
2635 clearmatches([{win}]) none clear all matches
2636 col({expr}) Number column byte index of cursor or mark
2637 complete({startcol}, {matches}) none set Insert mode completion
2638 complete_add({expr}) Number add completion match
2639 complete_check() Number check for key typed during completion
2640 complete_info([{what}]) Dict get current completion information
2641 confirm({msg} [, {choices} [, {default} [, {type}]]])
2642 Number number of choice picked by user
2643 copy({expr}) any make a shallow copy of {expr}
2644 cos({expr}) Float cosine of {expr}
2645 cosh({expr}) Float hyperbolic cosine of {expr}
2646 count({comp}, {expr} [, {ic} [, {start}]])
2647 Number count how many {expr} are in {comp}
2648 cscope_connection([{num}, {dbpath} [, {prepend}]])
2649 Number checks existence of cscope connection
2650 cursor({lnum}, {col} [, {off}])
2651 Number move cursor to {lnum}, {col}, {off}
2652 cursor({list}) Number move cursor to position in {list}
2653 debugbreak({pid}) Number interrupt process being debugged
2654 deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2655 delete({fname} [, {flags}]) Number delete the file or directory {fname}
2656 deletebufline({buf}, {first} [, {last}])
2657 Number delete lines from buffer {buf}
2658 did_filetype() Number |TRUE| if FileType autocmd event used
2659 diff_filler({lnum}) Number diff filler lines about {lnum}
2660 diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
2661 digraph_get({chars}) String get the |digraph| of {chars}
2662 digraph_getlist([{listall}]) List get all |digraph|s
2663 digraph_set({chars}, {digraph}) Boolean register |digraph|
2664 digraph_setlist({digraphlist}) Boolean register multiple |digraph|s
2665 echoraw({expr}) none output {expr} as-is
2666 empty({expr}) Number |TRUE| if {expr} is empty
2667 environ() Dict return environment variables
2668 escape({string}, {chars}) String escape {chars} in {string} with '\'
2669 eval({string}) any evaluate {string} into its value
2670 eventhandler() Number |TRUE| if inside an event handler
2671 executable({expr}) Number 1 if executable {expr} exists
2672 execute({command}) String execute {command} and get the output
2673 exepath({expr}) String full path of the command {expr}
2674 exists({expr}) Number |TRUE| if {expr} exists
2675 exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time
2676 exp({expr}) Float exponential of {expr}
2677 expand({expr} [, {nosuf} [, {list}]])
2678 any expand special keywords in {expr}
2679 expandcmd({expr}) String expand {expr} like with `:edit`
2680 extend({expr1}, {expr2} [, {expr3}])
2681 List/Dict insert items of {expr2} into {expr1}
2682 extendnew({expr1}, {expr2} [, {expr3}])
2683 List/Dict like |extend()| but creates a new
2684 List or Dictionary
2685 feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
2686 filereadable({file}) Number |TRUE| if {file} is a readable file
2687 filewritable({file}) Number |TRUE| if {file} is a writable file
2688 filter({expr1}, {expr2}) List/Dict/Blob/String
2689 remove items from {expr1} where
2690 {expr2} is 0
2691 finddir({name} [, {path} [, {count}]])
2692 String find directory {name} in {path}
2693 findfile({name} [, {path} [, {count}]])
2694 String find file {name} in {path}
2695 flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels
2696 flattennew({list} [, {maxdepth}])
2697 List flatten a copy of {list}
2698 float2nr({expr}) Number convert Float {expr} to a Number
2699 floor({expr}) Float round {expr} down
2700 fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2701 fnameescape({fname}) String escape special characters in {fname}
2702 fnamemodify({fname}, {mods}) String modify file name
2703 foldclosed({lnum}) Number first line of fold at {lnum} if closed
2704 foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2705 foldlevel({lnum}) Number fold level at {lnum}
2706 foldtext() String line displayed for closed fold
2707 foldtextresult({lnum}) String text for closed fold at {lnum}
2708 foreground() Number bring the Vim window to the foreground
2709 fullcommand({name}) String get full command from {name}
2710 funcref({name} [, {arglist}] [, {dict}])
2711 Funcref reference to function {name}
2712 function({name} [, {arglist}] [, {dict}])
2713 Funcref named reference to function {name}
2714 garbagecollect([{atexit}]) none free memory, breaking cyclic references
2715 get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2716 get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
2717 get({func}, {what}) any get property of funcref/partial {func}
2718 getbufinfo([{buf}]) List information about buffers
2719 getbufline({buf}, {lnum} [, {end}])
2720 List lines {lnum} to {end} of buffer {buf}
2721 getbufvar({buf}, {varname} [, {def}])
2722 any variable {varname} in buffer {buf}
2723 getchangelist([{buf}]) List list of change list items
2724 getchar([expr]) Number or String
2725 get one character from the user
2726 getcharmod() Number modifiers for the last typed character
2727 getcharpos({expr}) List position of cursor, mark, etc.
2728 getcharsearch() Dict last character search
2729 getcharstr([expr]) String get one character from the user
2730 getcmdline() String return the current command-line
2731 getcmdpos() Number return cursor position in command-line
2732 getcmdtype() String return current command-line type
2733 getcmdwintype() String return current command-line window type
2734 getcompletion({pat}, {type} [, {filtered}])
2735 List list of cmdline completion matches
2736 getcurpos([{winnr}]) List position of the cursor
2737 getcursorcharpos([{winnr}]) List character position of the cursor
2738 getcwd([{winnr} [, {tabnr}]]) String get the current working directory
2739 getenv({name}) String return environment variable
2740 getfontname([{name}]) String name of font being used
2741 getfperm({fname}) String file permissions of file {fname}
2742 getfsize({fname}) Number size in bytes of file {fname}
2743 getftime({fname}) Number last modification time of file
2744 getftype({fname}) String description of type of file {fname}
2745 getimstatus() Number |TRUE| if the IME status is active
2746 getjumplist([{winnr} [, {tabnr}]])
2747 List list of jump list items
2748 getline({lnum}) String line {lnum} of current buffer
2749 getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
2750 getloclist({nr}) List list of location list items
2751 getloclist({nr}, {what}) Dict get specific location list properties
2752 getmarklist([{buf}]) List list of global/local marks
2753 getmatches([{win}]) List list of current matches
2754 getmousepos() Dict last known mouse position
2755 getpid() Number process ID of Vim
2756 getpos({expr}) List position of cursor, mark, etc.
2757 getqflist() List list of quickfix items
2758 getqflist({what}) Dict get specific quickfix list properties
2759 getreg([{regname} [, 1 [, {list}]]])
2760 String or List contents of a register
2761 getreginfo([{regname}]) Dict information about a register
2762 getregtype([{regname}]) String type of a register
2763 gettabinfo([{expr}]) List list of tab pages
2764 gettabvar({nr}, {varname} [, {def}])
2765 any variable {varname} in tab {nr} or {def}
2766 gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
2767 any {name} in {winnr} in tab page {tabnr}
2768 gettagstack([{nr}]) Dict get the tag stack of window {nr}
2769 gettext({text}) String lookup translation of {text}
2770 getwininfo([{winid}]) List list of info about each window
2771 getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
2772 getwinposx() Number X coord in pixels of the Vim window
2773 getwinposy() Number Y coord in pixels of the Vim window
2774 getwinvar({nr}, {varname} [, {def}])
2775 any variable {varname} in window {nr}
2776 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
2777 any expand file wildcards in {expr}
2778 glob2regpat({expr}) String convert a glob pat into a search pat
2779 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
2780 String do glob({expr}) for all dirs in {path}
2781 has({feature} [, {check}]) Number |TRUE| if feature {feature} supported
2782 has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
2783 haslocaldir([{winnr} [, {tabnr}]])
2784 Number |TRUE| if the window executed |:lcd|
2785 or |:tcd|
2786 hasmapto({what} [, {mode} [, {abbr}]])
2787 Number |TRUE| if mapping to {what} exists
2788 histadd({history}, {item}) Number add an item to a history
2789 histdel({history} [, {item}]) Number remove an item from a history
2790 histget({history} [, {index}]) String get the item {index} from a history
2791 histnr({history}) Number highest index of a history
2792 hlID({name}) Number syntax ID of highlight group {name}
2793 hlexists({name}) Number |TRUE| if highlight group {name} exists
2794 hlget([{name} [, {resolve}]]) List get highlight group attributes
2795 hlset({list}) Number set highlight group attributes
2796 hostname() String name of the machine Vim is running on
2797 iconv({expr}, {from}, {to}) String convert encoding of {expr}
2798 indent({lnum}) Number indent of line {lnum}
2799 index({object}, {expr} [, {start} [, {ic}]])
2800 Number index in {object} where {expr} appears
2801 input({prompt} [, {text} [, {completion}]])
2802 String get input from the user
2803 inputdialog({prompt} [, {text} [, {completion}]])
2804 String like input() but in a GUI dialog
2805 inputlist({textlist}) Number let the user pick from a choice list
2806 inputrestore() Number restore typeahead
2807 inputsave() Number save and clear typeahead
2808 inputsecret({prompt} [, {text}]) String like input() but hiding the text
2809 insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
2810 interrupt() none interrupt script execution
2811 invert({expr}) Number bitwise invert
2812 isdirectory({directory}) Number |TRUE| if {directory} is a directory
2813 isinf({expr}) Number determine if {expr} is infinity value
2814 (positive or negative)
2815 islocked({expr}) Number |TRUE| if {expr} is locked
2816 isnan({expr}) Number |TRUE| if {expr} is NaN
2817 items({dict}) List key-value pairs in {dict}
2818 job_getchannel({job}) Channel get the channel handle for {job}
2819 job_info([{job}]) Dict get information about {job}
2820 job_setoptions({job}, {options}) none set options for {job}
2821 job_start({command} [, {options}])
2822 Job start a job
2823 job_status({job}) String get the status of {job}
2824 job_stop({job} [, {how}]) Number stop {job}
2825 join({list} [, {sep}]) String join {list} items into one String
2826 js_decode({string}) any decode JS style JSON
2827 js_encode({expr}) String encode JS style JSON
2828 json_decode({string}) any decode JSON
2829 json_encode({expr}) String encode JSON
2830 keys({dict}) List keys in {dict}
2831 len({expr}) Number the length of {expr}
2832 libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
2833 libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
2834 line({expr} [, {winid}]) Number line nr of cursor, last line or mark
2835 line2byte({lnum}) Number byte count of line {lnum}
2836 lispindent({lnum}) Number Lisp indent for line {lnum}
2837 list2blob({list}) Blob turn {list} of numbers into a Blob
2838 list2str({list} [, {utf8}]) String turn {list} of numbers into a String
2839 listener_add({callback} [, {buf}])
2840 Number add a callback to listen to changes
2841 listener_flush([{buf}]) none invoke listener callbacks
2842 listener_remove({id}) none remove a listener callback
2843 localtime() Number current time
2844 log({expr}) Float natural logarithm (base e) of {expr}
2845 log10({expr}) Float logarithm of Float {expr} to base 10
2846 luaeval({expr} [, {expr}]) any evaluate |Lua| expression
2847 map({expr1}, {expr2}) List/Dict/Blob/String
2848 change each item in {expr1} to {expr2}
2849 maparg({name} [, {mode} [, {abbr} [, {dict}]]])
2850 String or Dict
2851 rhs of mapping {name} in mode {mode}
2852 mapcheck({name} [, {mode} [, {abbr}]])
2853 String check for mappings matching {name}
2854 mapnew({expr1}, {expr2}) List/Dict/Blob/String
2855 like |map()| but creates a new List or
2856 Dictionary
2857 mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result
2858 match({expr}, {pat} [, {start} [, {count}]])
2859 Number position where {pat} matches in {expr}
2860 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
2861 Number highlight {pattern} with {group}
2862 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
2863 Number highlight positions with {group}
2864 matcharg({nr}) List arguments of |:match|
2865 matchdelete({id} [, {win}]) Number delete match identified by {id}
2866 matchend({expr}, {pat} [, {start} [, {count}]])
2867 Number position where {pat} ends in {expr}
2868 matchfuzzy({list}, {str} [, {dict}])
2869 List fuzzy match {str} in {list}
2870 matchfuzzypos({list}, {str} [, {dict}])
2871 List fuzzy match {str} in {list}
2872 matchlist({expr}, {pat} [, {start} [, {count}]])
2873 List match and submatches of {pat} in {expr}
2874 matchstr({expr}, {pat} [, {start} [, {count}]])
2875 String {count}'th match of {pat} in {expr}
2876 matchstrpos({expr}, {pat} [, {start} [, {count}]])
2877 List {count}'th match of {pat} in {expr}
2878 max({expr}) Number maximum value of items in {expr}
2879 menu_info({name} [, {mode}]) Dict get menu item information
2880 min({expr}) Number minimum value of items in {expr}
2881 mkdir({name} [, {path} [, {prot}]])
2882 Number create directory {name}
2883 mode([expr]) String current editing mode
2884 mzeval({expr}) any evaluate |MzScheme| expression
2885 nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
2886 nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr}
2887 or({expr}, {expr}) Number bitwise OR
2888 pathshorten({expr} [, {len}]) String shorten directory names in a path
2889 perleval({expr}) any evaluate |Perl| expression
2890 popup_atcursor({what}, {options}) Number create popup window near the cursor
2891 popup_beval({what}, {options}) Number create popup window for 'ballooneval'
2892 popup_clear() none close all popup windows
2893 popup_close({id} [, {result}]) none close popup window {id}
2894 popup_create({what}, {options}) Number create a popup window
2895 popup_dialog({what}, {options}) Number create a popup window used as a dialog
2896 popup_filter_menu({id}, {key}) Number filter for a menu popup window
2897 popup_filter_yesno({id}, {key}) Number filter for a dialog popup window
2898 popup_findinfo() Number get window ID of info popup window
2899 popup_findpreview() Number get window ID of preview popup window
2900 popup_getoptions({id}) Dict get options of popup window {id}
2901 popup_getpos({id}) Dict get position of popup window {id}
2902 popup_hide({id}) none hide popup menu {id}
2903 popup_list() List get a list of window IDs of all popups
2904 popup_locate({row}, {col}) Number get window ID of popup at position
2905 popup_menu({what}, {options}) Number create a popup window used as a menu
2906 popup_move({id}, {options}) none set position of popup window {id}
2907 popup_notification({what}, {options})
2908 Number create a notification popup window
2909 popup_setoptions({id}, {options})
2910 none set options for popup window {id}
2911 popup_settext({id}, {text}) none set the text of popup window {id}
2912 popup_show({id}) none unhide popup window {id}
2913 pow({x}, {y}) Float {x} to the power of {y}
2914 prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2915 printf({fmt}, {expr1}...) String format text
2916 prompt_getprompt({buf}) String get prompt text
2917 prompt_setcallback({buf}, {expr}) none set prompt callback function
2918 prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2919 prompt_setprompt({buf}, {text}) none set prompt text
2920 prop_add({lnum}, {col}, {props}) none add one text property
2921 prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...])
2922 none add multiple text properties
2923 prop_clear({lnum} [, {lnum-end} [, {props}]])
2924 none remove all text properties
2925 prop_find({props} [, {direction}])
2926 Dict search for a text property
2927 prop_list({lnum} [, {props}]) List text properties in {lnum}
2928 prop_remove({props} [, {lnum} [, {lnum-end}]])
2929 Number remove a text property
2930 prop_type_add({name}, {props}) none define a new property type
2931 prop_type_change({name}, {props})
2932 none change an existing property type
2933 prop_type_delete({name} [, {props}])
2934 none delete a property type
2935 prop_type_get({name} [, {props}])
2936 Dict get property type values
2937 prop_type_list([{props}]) List get list of property types
2938 pum_getpos() Dict position and size of pum if visible
2939 pumvisible() Number whether popup menu is visible
2940 py3eval({expr}) any evaluate |python3| expression
2941 pyeval({expr}) any evaluate |Python| expression
2942 pyxeval({expr}) any evaluate |python_x| expression
2943 rand([{expr}]) Number get pseudo-random number
2944 range({expr} [, {max} [, {stride}]])
2945 List items from {expr} to {max}
2946 readblob({fname}) Blob read a |Blob| from {fname}
2947 readdir({dir} [, {expr} [, {dict}]])
2948 List file names in {dir} selected by {expr}
2949 readdirex({dir} [, {expr} [, {dict}]])
2950 List file info in {dir} selected by {expr}
2951 readfile({fname} [, {type} [, {max}]])
2952 List get list of lines from file {fname}
2953 reduce({object}, {func} [, {initial}])
2954 any reduce {object} using {func}
2955 reg_executing() String get the executing register name
2956 reg_recording() String get the recording register name
2957 reltime([{start} [, {end}]]) List get time value
2958 reltimefloat({time}) Float turn the time value into a Float
2959 reltimestr({time}) String turn time value into a String
2960 remote_expr({server}, {string} [, {idvar} [, {timeout}]])
2961 String send expression
2962 remote_foreground({server}) Number bring Vim server to the foreground
2963 remote_peek({serverid} [, {retvar}])
2964 Number check for reply string
2965 remote_read({serverid} [, {timeout}])
2966 String read reply string
2967 remote_send({server}, {string} [, {idvar}])
2968 String send key sequence
2969 remote_startserver({name}) none become server {name}
2970 remove({list}, {idx} [, {end}]) any/List
2971 remove items {idx}-{end} from {list}
2972 remove({blob}, {idx} [, {end}]) Number/Blob
2973 remove bytes {idx}-{end} from {blob}
2974 remove({dict}, {key}) any remove entry {key} from {dict}
2975 rename({from}, {to}) Number rename (move) file from {from} to {to}
2976 repeat({expr}, {count}) String repeat {expr} {count} times
2977 resolve({filename}) String get filename a shortcut points to
2978 reverse({list}) List reverse {list} in-place
2979 round({expr}) Float round off {expr}
2980 rubyeval({expr}) any evaluate |Ruby| expression
2981 screenattr({row}, {col}) Number attribute at screen position
2982 screenchar({row}, {col}) Number character at screen position
2983 screenchars({row}, {col}) List List of characters at screen position
2984 screencol() Number current cursor column
2985 screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character
2986 screenrow() Number current cursor row
2987 screenstring({row}, {col}) String characters at screen position
2988 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
2989 Number search for {pattern}
2990 searchcount([{options}]) Dict get or update search stats
2991 searchdecl({name} [, {global} [, {thisblock}]])
2992 Number search for variable declaration
2993 searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
2994 Number search for other end of start/end pair
2995 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
2996 List search for other end of start/end pair
2997 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
2998 List search for {pattern}
2999 server2client({clientid}, {string})
3000 Number send reply string
3001 serverlist() String get a list of available servers
3002 setbufline({expr}, {lnum}, {text})
3003 Number set line {lnum} to {text} in buffer
3004 {expr}
3005 setbufvar({buf}, {varname}, {val})
3006 none set {varname} in buffer {buf} to {val}
3007 setcellwidths({list}) none set character cell width overrides
3008 setcharpos({expr}, {list}) Number set the {expr} position to {list}
3009 setcharsearch({dict}) Dict set character search from {dict}
3010 setcmdpos({pos}) Number set cursor position in command-line
3011 setcursorcharpos({list}) Number move cursor to position in {list}
3012 setenv({name}, {val}) none set environment variable
3013 setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
3014 setline({lnum}, {line}) Number set line {lnum} to {line}
3015 setloclist({nr}, {list} [, {action}])
3016 Number modify location list using {list}
3017 setloclist({nr}, {list}, {action}, {what})
3018 Number modify specific location list props
3019 setmatches({list} [, {win}]) Number restore a list of matches
3020 setpos({expr}, {list}) Number set the {expr} position to {list}
3021 setqflist({list} [, {action}]) Number modify quickfix list using {list}
3022 setqflist({list}, {action}, {what})
3023 Number modify specific quickfix list props
3024 setreg({n}, {v} [, {opt}]) Number set register to value and type
3025 settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
3026 settabwinvar({tabnr}, {winnr}, {varname}, {val})
3027 none set {varname} in window {winnr} in tab
3028 page {tabnr} to {val}
3029 settagstack({nr}, {dict} [, {action}])
3030 Number modify tag stack using {dict}
3031 setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
3032 sha256({string}) String SHA256 checksum of {string}
3033 shellescape({string} [, {special}])
3034 String escape {string} for use as shell
3035 command argument
3036 shiftwidth([{col}]) Number effective value of 'shiftwidth'
3037 sign_define({name} [, {dict}]) Number define or update a sign
3038 sign_define({list}) List define or update a list of signs
3039 sign_getdefined([{name}]) List get a list of defined signs
3040 sign_getplaced([{buf} [, {dict}]])
3041 List get a list of placed signs
3042 sign_jump({id}, {group}, {buf})
3043 Number jump to a sign
3044 sign_place({id}, {group}, {name}, {buf} [, {dict}])
3045 Number place a sign
3046 sign_placelist({list}) List place a list of signs
3047 sign_undefine([{name}]) Number undefine a sign
3048 sign_undefine({list}) List undefine a list of signs
3049 sign_unplace({group} [, {dict}])
3050 Number unplace a sign
3051 sign_unplacelist({list}) List unplace a list of signs
3052 simplify({filename}) String simplify filename as much as possible
3053 sin({expr}) Float sine of {expr}
3054 sinh({expr}) Float hyperbolic sine of {expr}
3055 slice({expr}, {start} [, {end}]) String, List or Blob
3056 slice of a String, List or Blob
3057 sort({list} [, {func} [, {dict}]])
3058 List sort {list}, using {func} to compare
3059 sound_clear() none stop playing all sounds
3060 sound_playevent({name} [, {callback}])
3061 Number play an event sound
3062 sound_playfile({path} [, {callback}])
3063 Number play sound file {path}
3064 sound_stop({id}) none stop playing sound {id}
3065 soundfold({word}) String sound-fold {word}
3066 spellbadword() String badly spelled word at cursor
3067 spellsuggest({word} [, {max} [, {capital}]])
3068 List spelling suggestions
3069 split({expr} [, {pat} [, {keepempty}]])
3070 List make |List| from {pat} separated {expr}
3071 sqrt({expr}) Float square root of {expr}
3072 srand([{expr}]) List get seed for |rand()|
3073 state([{what}]) String current state of Vim
3074 str2float({expr} [, {quoted}]) Float convert String to Float
3075 str2list({expr} [, {utf8}]) List convert each character of {expr} to
3076 ASCII/UTF-8 value
3077 str2nr({expr} [, {base} [, {quoted}]])
3078 Number convert String to Number
3079 strcharlen({expr}) Number character length of the String {expr}
3080 strcharpart({str}, {start} [, {len} [, {skipcc}]])
3081 String {len} characters of {str} at
3082 character {start}
3083 strchars({expr} [, {skipcc}]) Number character count of the String {expr}
3084 strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
3085 strftime({format} [, {time}]) String format time with a specified format
3086 strgetchar({str}, {index}) Number get char {index} from {str}
3087 stridx({haystack}, {needle} [, {start}])
3088 Number index of {needle} in {haystack}
3089 string({expr}) String String representation of {expr} value
3090 strlen({expr}) Number length of the String {expr}
3091 strpart({str}, {start} [, {len} [, {chars}]])
3092 String {len} bytes/chars of {str} at
3093 byte {start}
3094 strptime({format}, {timestring})
3095 Number Convert {timestring} to unix timestamp
3096 strridx({haystack}, {needle} [, {start}])
3097 Number last index of {needle} in {haystack}
3098 strtrans({expr}) String translate string to make it printable
3099 strwidth({expr}) Number display cell length of the String {expr}
3100 submatch({nr} [, {list}]) String or List
3101 specific match in ":s" or substitute()
3102 substitute({expr}, {pat}, {sub}, {flags})
3103 String all {pat} in {expr} replaced with {sub}
3104 swapinfo({fname}) Dict information about swap file {fname}
3105 swapname({buf}) String swap file of buffer {buf}
3106 synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
3107 synIDattr({synID}, {what} [, {mode}])
3108 String attribute {what} of syntax ID {synID}
3109 synIDtrans({synID}) Number translated syntax ID of {synID}
3110 synconcealed({lnum}, {col}) List info about concealing
3111 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
3112 system({expr} [, {input}]) String output of shell command/filter {expr}
3113 systemlist({expr} [, {input}]) List output of shell command/filter {expr}
3114 tabpagebuflist([{arg}]) List list of buffer numbers in tab page
3115 tabpagenr([{arg}]) Number number of current or last tab page
3116 tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
3117 tagfiles() List tags files used
3118 taglist({expr} [, {filename}]) List list of tags matching {expr}
3119 tan({expr}) Float tangent of {expr}
3120 tanh({expr}) Float hyperbolic tangent of {expr}
3121 tempname() String name for a temporary file
3122 term_dumpdiff({filename}, {filename} [, {options}])
3123 Number display difference between two dumps
3124 term_dumpload({filename} [, {options}])
3125 Number displaying a screen dump
3126 term_dumpwrite({buf}, {filename} [, {options}])
3127 none dump terminal window contents
3128 term_getaltscreen({buf}) Number get the alternate screen flag
3129 term_getansicolors({buf}) List get ANSI palette in GUI color mode
3130 term_getattr({attr}, {what}) Number get the value of attribute {what}
3131 term_getcursor({buf}) List get the cursor position of a terminal
3132 term_getjob({buf}) Job get the job associated with a terminal
3133 term_getline({buf}, {row}) String get a line of text from a terminal
3134 term_getscrolled({buf}) Number get the scroll count of a terminal
3135 term_getsize({buf}) List get the size of a terminal
3136 term_getstatus({buf}) String get the status of a terminal
3137 term_gettitle({buf}) String get the title of a terminal
3138 term_gettty({buf}, [{input}]) String get the tty name of a terminal
3139 term_list() List get the list of terminal buffers
3140 term_scrape({buf}, {row}) List get row of a terminal screen
3141 term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
3142 term_setansicolors({buf}, {colors})
3143 none set ANSI palette in GUI color mode
3144 term_setapi({buf}, {expr}) none set |terminal-api| function name prefix
3145 term_setkill({buf}, {how}) none set signal to stop job in terminal
3146 term_setrestore({buf}, {command}) none set command to restore terminal
3147 term_setsize({buf}, {rows}, {cols})
3148 none set the size of a terminal
3149 term_start({cmd} [, {options}]) Number open a terminal window and run a job
3150 term_wait({buf} [, {time}]) Number wait for screen to be updated
3151 terminalprops() Dict properties of the terminal
3152 test_alloc_fail({id}, {countdown}, {repeat})
3153 none make memory allocation fail
3154 test_autochdir() none enable 'autochdir' during startup
3155 test_feedinput({string}) none add key sequence to input buffer
3156 test_garbagecollect_now() none free memory right now for testing
3157 test_garbagecollect_soon() none free memory soon for testing
3158 test_getvalue({string}) any get value of an internal variable
3159 test_gui_drop_files({list}, {row}, {col}, {mods})
3160 none drop a list of files in a window
3161 test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods})
3162 none add a mouse event to the input buffer
3163 test_ignore_error({expr}) none ignore a specific error
3164 test_null_blob() Blob null value for testing
3165 test_null_channel() Channel null value for testing
3166 test_null_dict() Dict null value for testing
3167 test_null_function() Funcref null value for testing
3168 test_null_job() Job null value for testing
3169 test_null_list() List null value for testing
3170 test_null_partial() Funcref null value for testing
3171 test_null_string() String null value for testing
3172 test_option_not_set({name}) none reset flag indicating option was set
3173 test_override({expr}, {val}) none test with Vim internal overrides
3174 test_refcount({expr}) Number get the reference count of {expr}
3175 test_scrollbar({which}, {value}, {dragging})
3176 none scroll in the GUI for testing
3177 test_setmouse({row}, {col}) none set the mouse position for testing
3178 test_settime({expr}) none set current time for testing
3179 test_srand_seed([seed]) none set seed for testing srand()
3180 test_unknown() any unknown value for testing
3181 test_void() any void value for testing
3182 timer_info([{id}]) List information about timers
3183 timer_pause({id}, {pause}) none pause or unpause a timer
3184 timer_start({time}, {callback} [, {options}])
3185 Number create a timer
3186 timer_stop({timer}) none stop a timer
3187 timer_stopall() none stop all timers
3188 tolower({expr}) String the String {expr} switched to lowercase
3189 toupper({expr}) String the String {expr} switched to uppercase
3190 tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
3191 to chars in {tostr}
3192 trim({text} [, {mask} [, {dir}]])
3193 String trim characters in {mask} from {text}
3194 trunc({expr}) Float truncate Float {expr}
3195 type({expr}) Number type of value {expr}
3196 typename({expr}) String representation of the type of {expr}
3197 undofile({name}) String undo file name for {name}
3198 undotree() List undo file tree
3199 uniq({list} [, {func} [, {dict}]])
3200 List remove adjacent duplicates from a list
3201 values({dict}) List values in {dict}
3202 virtcol({expr}) Number screen column of cursor or mark
3203 visualmode([expr]) String last visual mode used
3204 wildmenumode() Number whether 'wildmenu' mode is active
3205 win_execute({id}, {command} [, {silent}])
3206 String execute {command} in window {id}
3207 win_findbuf({bufnr}) List find windows containing {bufnr}
3208 win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
3209 win_gettype([{nr}]) String type of window {nr}
3210 win_gotoid({expr}) Number go to window with ID {expr}
3211 win_id2tabwin({expr}) List get tab and window nr from window ID
3212 win_id2win({expr}) Number get window nr from window ID
3213 win_screenpos({nr}) List get screen position of window {nr}
3214 win_splitmove({nr}, {target} [, {options}])
3215 Number move window {nr} to split of {target}
3216 winbufnr({nr}) Number buffer number of window {nr}
3217 wincol() Number window column of the cursor
3218 windowsversion() String MS-Windows OS version
3219 winheight({nr}) Number height of window {nr}
3220 winlayout([{tabnr}]) List layout of windows in tab {tabnr}
3221 winline() Number window line of the cursor
3222 winnr([{expr}]) Number number of current window
3223 winrestcmd() String returns command to restore window sizes
3224 winrestview({dict}) none restore view of current window
3225 winsaveview() Dict save view of current window
3226 winwidth({nr}) Number width of window {nr}
3227 wordcount() Dict get byte/char/word statistics
3228 writefile({object}, {fname} [, {flags}])
3229 Number write |Blob| or |List| of lines to file
3230 xor({expr}, {expr}) Number bitwise XOR
3231
3232
3233 abs({expr}) *abs()*
3234 Return the absolute value of {expr}. When {expr} evaluates to
3235 a |Float| abs() returns a |Float|. When {expr} can be
3236 converted to a |Number| abs() returns a |Number|. Otherwise
3237 abs() gives an error message and returns -1.
3238 Examples: >
3239 echo abs(1.456)
3240 < 1.456 >
3241 echo abs(-5.456)
3242 < 5.456 >
3243 echo abs(-4)
3244 < 4
3245
3246 Can also be used as a |method|: >
3247 Compute()->abs()
3248
3249 < {only available when compiled with the |+float| feature}
3250
3251
3252 acos({expr}) *acos()*
3253 Return the arc cosine of {expr} measured in radians, as a
3254 |Float| in the range of [0, pi].
3255 {expr} must evaluate to a |Float| or a |Number| in the range
3256 [-1, 1].
3257 Examples: >
3258 :echo acos(0)
3259 < 1.570796 >
3260 :echo acos(-0.5)
3261 < 2.094395
3262
3263 Can also be used as a |method|: >
3264 Compute()->acos()
3265
3266 < {only available when compiled with the |+float| feature}
3267
3268
3269 add({object}, {expr}) *add()*
3270 Append the item {expr} to |List| or |Blob| {object}. Returns
3271 the resulting |List| or |Blob|. Examples: >
3272 :let alist = add([1, 2, 3], item)
3273 :call add(mylist, "woodstock")
3274 < Note that when {expr} is a |List| it is appended as a single
3275 item. Use |extend()| to concatenate |Lists|.
3276 When {object} is a |Blob| then {expr} must be a number.
3277 Use |insert()| to add an item at another position.
3278
3279 Can also be used as a |method|: >
3280 mylist->add(val1)->add(val2)
3281
3282
3283 and({expr}, {expr}) *and()*
3284 Bitwise AND on the two arguments. The arguments are converted
3285 to a number. A List, Dict or Float argument causes an error.
3286 Example: >
3287 :let flag = and(bits, 0x80)
3288 < Can also be used as a |method|: >
3289 :let flag = bits->and(0x80)
3290
3291
3292 append({lnum}, {text}) *append()*
3293 When {text} is a |List|: Append each item of the |List| as a
3294 text line below line {lnum} in the current buffer.
3295 Otherwise append {text} as one text line below line {lnum} in
3296 the current buffer.
3297 Any type of item is accepted and converted to a String.
3298 {lnum} can be zero to insert a line before the first one.
3299 {lnum} is used like with |getline()|.
3300 Returns 1 for failure ({lnum} out of range or out of memory),
3301 0 for success. Example: >
3302 :let failed = append(line('$'), "# THE END")
3303 :let failed = append(0, ["Chapter 1", "the beginning"])
3304
3305 < Can also be used as a |method| after a List, the base is
3306 passed as the second argument: >
3307 mylist->append(lnum)
3308
3309
3310 appendbufline({buf}, {lnum}, {text}) *appendbufline()*
3311 Like |append()| but append the text in buffer {buf}.
3312
3313 This function works only for loaded buffers. First call
3314 |bufload()| if needed.
3315
3316 For the use of {buf}, see |bufname()|.
3317
3318 {lnum} is used like with |append()|. Note that using |line()|
3319 would use the current buffer, not the one appending to.
3320 Use "$" to append at the end of the buffer.
3321
3322 On success 0 is returned, on failure 1 is returned.
3323
3324 If {buf} is not a valid buffer or {lnum} is not valid, an
3325 error message is given. Example: >
3326 :let failed = appendbufline(13, 0, "# THE START")
3327 <
3328 Can also be used as a |method| after a List, the base is
3329 passed as the second argument: >
3330 mylist->appendbufline(buf, lnum)
3331
3332
3333 argc([{winid}]) *argc()*
3334 The result is the number of files in the argument list. See
3335 |arglist|.
3336 If {winid} is not supplied, the argument list of the current
3337 window is used.
3338 If {winid} is -1, the global argument list is used.
3339 Otherwise {winid} specifies the window of which the argument
3340 list is used: either the window number or the window ID.
3341 Returns -1 if the {winid} argument is invalid.
3342
3343 *argidx()*
3344 argidx() The result is the current index in the argument list. 0 is
3345 the first file. argc() - 1 is the last one. See |arglist|.
3346
3347 *arglistid()*
3348 arglistid([{winnr} [, {tabnr}]])
3349 Return the argument list ID. This is a number which
3350 identifies the argument list being used. Zero is used for the
3351 global argument list. See |arglist|.
3352 Returns -1 if the arguments are invalid.
3353
3354 Without arguments use the current window.
3355 With {winnr} only use this window in the current tab page.
3356 With {winnr} and {tabnr} use the window in the specified tab
3357 page.
3358 {winnr} can be the window number or the |window-ID|.
3359
3360 *argv()*
3361 argv([{nr} [, {winid}]])
3362 The result is the {nr}th file in the argument list. See
3363 |arglist|. "argv(0)" is the first one. Example: >
3364 :let i = 0
3365 :while i < argc()
3366 : let f = escape(fnameescape(argv(i)), '.')
3367 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
3368 : let i = i + 1
3369 :endwhile
3370 < Without the {nr} argument, or when {nr} is -1, a |List| with
3371 the whole |arglist| is returned.
3372
3373 The {winid} argument specifies the window ID, see |argc()|.
3374 For the Vim command line arguments see |v:argv|.
3375
3376 asin({expr}) *asin()*
3377 Return the arc sine of {expr} measured in radians, as a |Float|
3378 in the range of [-pi/2, pi/2].
3379 {expr} must evaluate to a |Float| or a |Number| in the range
3380 [-1, 1].
3381 Examples: >
3382 :echo asin(0.8)
3383 < 0.927295 >
3384 :echo asin(-0.5)
3385 < -0.523599
3386
3387 Can also be used as a |method|: >
3388 Compute()->asin()
3389 <
3390 {only available when compiled with the |+float| feature}
3391
3392
3393 assert_ functions are documented here: |assert-functions-details|
3394
3395
3396
3397 atan({expr}) *atan()*
3398 Return the principal value of the arc tangent of {expr}, in
3399 the range [-pi/2, +pi/2] radians, as a |Float|.
3400 {expr} must evaluate to a |Float| or a |Number|.
3401 Examples: >
3402 :echo atan(100)
3403 < 1.560797 >
3404 :echo atan(-4.01)
3405 < -1.326405
3406
3407 Can also be used as a |method|: >
3408 Compute()->atan()
3409 <
3410 {only available when compiled with the |+float| feature}
3411
3412
3413 atan2({expr1}, {expr2}) *atan2()*
3414 Return the arc tangent of {expr1} / {expr2}, measured in
3415 radians, as a |Float| in the range [-pi, pi].
3416 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
3417 Examples: >
3418 :echo atan2(-1, 1)
3419 < -0.785398 >
3420 :echo atan2(1, -1)
3421 < 2.356194
3422
3423 Can also be used as a |method|: >
3424 Compute()->atan2(1)
3425 <
3426 {only available when compiled with the |+float| feature}
3427
3428 balloon_gettext() *balloon_gettext()*
3429 Return the current text in the balloon. Only for the string,
3430 not used for the List.
3431
3432 balloon_show({expr}) *balloon_show()*
3433 Show {expr} inside the balloon. For the GUI {expr} is used as
3434 a string. For a terminal {expr} can be a list, which contains
3435 the lines of the balloon. If {expr} is not a list it will be
3436 split with |balloon_split()|.
3437 If {expr} is an empty string any existing balloon is removed.
3438
3439 Example: >
3440 func GetBalloonContent()
3441 " ... initiate getting the content
3442 return ''
3443 endfunc
3444 set balloonexpr=GetBalloonContent()
3445
3446 func BalloonCallback(result)
3447 call balloon_show(a:result)
3448 endfunc
3449 < Can also be used as a |method|: >
3450 GetText()->balloon_show()
3451 <
3452 The intended use is that fetching the content of the balloon
3453 is initiated from 'balloonexpr'. It will invoke an
3454 asynchronous method, in which a callback invokes
3455 balloon_show(). The 'balloonexpr' itself can return an
3456 empty string or a placeholder.
3457
3458 When showing a balloon is not possible nothing happens, no
3459 error message.
3460 {only available when compiled with the |+balloon_eval| or
3461 |+balloon_eval_term| feature}
3462
3463 balloon_split({msg}) *balloon_split()*
3464 Split String {msg} into lines to be displayed in a balloon.
3465 The splits are made for the current window size and optimize
3466 to show debugger output.
3467 Returns a |List| with the split lines.
3468 Can also be used as a |method|: >
3469 GetText()->balloon_split()->balloon_show()
3470
3471 < {only available when compiled with the |+balloon_eval_term|
3472 feature}
3473
3474 blob2list({blob}) *blob2list()*
3475 Return a List containing the number value of each byte in Blob
3476 {blob}. Examples: >
3477 blob2list(0z0102.0304) returns [1, 2, 3, 4]
3478 blob2list(0z) returns []
3479 < Returns an empty List on error. |list2blob()| does the
3480 opposite.
3481
3482 Can also be used as a |method|: >
3483 GetBlob()->blob2list()
3484
3485 *browse()*
3486 browse({save}, {title}, {initdir}, {default})
3487 Put up a file requester. This only works when "has("browse")"
3488 returns |TRUE| (only in some GUI versions).
3489 The input fields are:
3490 {save} when |TRUE|, select file to write
3491 {title} title for the requester
3492 {initdir} directory to start browsing in
3493 {default} default file name
3494 An empty string is returned when the "Cancel" button is hit,
3495 something went wrong, or browsing is not possible.
3496
3497 *browsedir()*
3498 browsedir({title}, {initdir})
3499 Put up a directory requester. This only works when
3500 "has("browse")" returns |TRUE| (only in some GUI versions).
3501 On systems where a directory browser is not supported a file
3502 browser is used. In that case: select a file in the directory
3503 to be used.
3504 The input fields are:
3505 {title} title for the requester
3506 {initdir} directory to start browsing in
3507 When the "Cancel" button is hit, something went wrong, or
3508 browsing is not possible, an empty string is returned.
3509
3510 bufadd({name}) *bufadd()*
3511 Add a buffer to the buffer list with String {name}.
3512 If a buffer for file {name} already exists, return that buffer
3513 number. Otherwise return the buffer number of the newly
3514 created buffer. When {name} is an empty string then a new
3515 buffer is always created.
3516 The buffer will not have 'buflisted' set and not be loaded
3517 yet. To add some text to the buffer use this: >
3518 let bufnr = bufadd('someName')
3519 call bufload(bufnr)
3520 call setbufline(bufnr, 1, ['some', 'text'])
3521 < Can also be used as a |method|: >
3522 let bufnr = 'somename'->bufadd()
3523
3524 bufexists({buf}) *bufexists()*
3525 The result is a Number, which is |TRUE| if a buffer called
3526 {buf} exists.
3527 If the {buf} argument is a number, buffer numbers are used.
3528 Number zero is the alternate buffer for the current window.
3529
3530 If the {buf} argument is a string it must match a buffer name
3531 exactly. The name can be:
3532 - Relative to the current directory.
3533 - A full path.
3534 - The name of a buffer with 'buftype' set to "nofile".
3535 - A URL name.
3536 Unlisted buffers will be found.
3537 Note that help files are listed by their short name in the
3538 output of |:buffers|, but bufexists() requires using their
3539 long name to be able to find them.
3540 bufexists() may report a buffer exists, but to use the name
3541 with a |:buffer| command you may need to use |expand()|. Esp
3542 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
3543 Use "bufexists(0)" to test for the existence of an alternate
3544 file name.
3545
3546 Can also be used as a |method|: >
3547 let exists = 'somename'->bufexists()
3548 <
3549 Obsolete name: buffer_exists(). *buffer_exists()*
3550
3551 buflisted({buf}) *buflisted()*
3552 The result is a Number, which is |TRUE| if a buffer called
3553 {buf} exists and is listed (has the 'buflisted' option set).
3554 The {buf} argument is used like with |bufexists()|.
3555
3556 Can also be used as a |method|: >
3557 let listed = 'somename'->buflisted()
3558
3559 bufload({buf}) *bufload()*
3560 Ensure the buffer {buf} is loaded. When the buffer name
3561 refers to an existing file then the file is read. Otherwise
3562 the buffer will be empty. If the buffer was already loaded
3563 then there is no change.
3564 If there is an existing swap file for the file of the buffer,
3565 there will be no dialog, the buffer will be loaded anyway.
3566 The {buf} argument is used like with |bufexists()|.
3567
3568 Can also be used as a |method|: >
3569 eval 'somename'->bufload()
3570
3571 bufloaded({buf}) *bufloaded()*
3572 The result is a Number, which is |TRUE| if a buffer called
3573 {buf} exists and is loaded (shown in a window or hidden).
3574 The {buf} argument is used like with |bufexists()|.
3575
3576 Can also be used as a |method|: >
3577 let loaded = 'somename'->bufloaded()
3578
3579 bufname([{buf}]) *bufname()*
3580 The result is the name of a buffer. Mostly as it is displayed
3581 by the `:ls` command, but not using special names such as
3582 "[No Name]".
3583 If {buf} is omitted the current buffer is used.
3584 If {buf} is a Number, that buffer number's name is given.
3585 Number zero is the alternate buffer for the current window.
3586 If {buf} is a String, it is used as a |file-pattern| to match
3587 with the buffer names. This is always done like 'magic' is
3588 set and 'cpoptions' is empty. When there is more than one
3589 match an empty string is returned.
3590 "" or "%" can be used for the current buffer, "#" for the
3591 alternate buffer.
3592 A full match is preferred, otherwise a match at the start, end
3593 or middle of the buffer name is accepted. If you only want a
3594 full match then put "^" at the start and "$" at the end of the
3595 pattern.
3596 Listed buffers are found first. If there is a single match
3597 with a listed buffer, that one is returned. Next unlisted
3598 buffers are searched for.
3599 If the {buf} is a String, but you want to use it as a buffer
3600 number, force it to be a Number by adding zero to it: >
3601 :echo bufname("3" + 0)
3602 < Can also be used as a |method|: >
3603 echo bufnr->bufname()
3604
3605 < If the buffer doesn't exist, or doesn't have a name, an empty
3606 string is returned. >
3607 bufname("#") alternate buffer name
3608 bufname(3) name of buffer 3
3609 bufname("%") name of current buffer
3610 bufname("file2") name of buffer where "file2" matches.
3611 < *buffer_name()*
3612 Obsolete name: buffer_name().
3613
3614 *bufnr()*
3615 bufnr([{buf} [, {create}]])
3616 The result is the number of a buffer, as it is displayed by
3617 the `:ls` command. For the use of {buf}, see |bufname()|
3618 above.
3619
3620 If the buffer doesn't exist, -1 is returned. Or, if the
3621 {create} argument is present and TRUE, a new, unlisted,
3622 buffer is created and its number is returned. Example: >
3623 let newbuf = bufnr('Scratch001', 1)
3624 < Using an empty name uses the current buffer. To create a new
3625 buffer with an empty name use |bufadd()|.
3626
3627 bufnr("$") is the last buffer: >
3628 :let last_buffer = bufnr("$")
3629 < The result is a Number, which is the highest buffer number
3630 of existing buffers. Note that not all buffers with a smaller
3631 number necessarily exist, because ":bwipeout" may have removed
3632 them. Use bufexists() to test for the existence of a buffer.
3633
3634 Can also be used as a |method|: >
3635 echo bufref->bufnr()
3636 <
3637 Obsolete name: buffer_number(). *buffer_number()*
3638 *last_buffer_nr()*
3639 Obsolete name for bufnr("$"): last_buffer_nr().
3640
3641 bufwinid({buf}) *bufwinid()*
3642 The result is a Number, which is the |window-ID| of the first
3643 window associated with buffer {buf}. For the use of {buf},
3644 see |bufname()| above. If buffer {buf} doesn't exist or
3645 there is no such window, -1 is returned. Example: >
3646
3647 echo "A window containing buffer 1 is " . (bufwinid(1))
3648 <
3649 Only deals with the current tab page.
3650
3651 Can also be used as a |method|: >
3652 FindBuffer()->bufwinid()
3653
3654 bufwinnr({buf}) *bufwinnr()*
3655 Like |bufwinid()| but return the window number instead of the
3656 |window-ID|.
3657 If buffer {buf} doesn't exist or there is no such window, -1
3658 is returned. Example: >
3659
3660 echo "A window containing buffer 1 is " . (bufwinnr(1))
3661
3662 < The number can be used with |CTRL-W_w| and ":wincmd w"
3663 |:wincmd|.
3664
3665 Can also be used as a |method|: >
3666 FindBuffer()->bufwinnr()
3667
3668 byte2line({byte}) *byte2line()*
3669 Return the line number that contains the character at byte
3670 count {byte} in the current buffer. This includes the
3671 end-of-line character, depending on the 'fileformat' option
3672 for the current buffer. The first character has byte count
3673 one.
3674 Also see |line2byte()|, |go| and |:goto|.
3675
3676 Can also be used as a |method|: >
3677 GetOffset()->byte2line()
3678
3679 < {not available when compiled without the |+byte_offset|
3680 feature}
3681
3682 byteidx({expr}, {nr}) *byteidx()*
3683 Return byte index of the {nr}'th character in the String
3684 {expr}. Use zero for the first character, it then returns
3685 zero.
3686 If there are no multibyte characters the returned value is
3687 equal to {nr}.
3688 Composing characters are not counted separately, their byte
3689 length is added to the preceding base character. See
3690 |byteidxcomp()| below for counting composing characters
3691 separately.
3692 Example : >
3693 echo matchstr(str, ".", byteidx(str, 3))
3694 < will display the fourth character. Another way to do the
3695 same: >
3696 let s = strpart(str, byteidx(str, 3))
3697 echo strpart(s, 0, byteidx(s, 1))
3698 < Also see |strgetchar()| and |strcharpart()|.
3699
3700 If there are less than {nr} characters -1 is returned.
3701 If there are exactly {nr} characters the length of the string
3702 in bytes is returned.
3703
3704 Can also be used as a |method|: >
3705 GetName()->byteidx(idx)
3706
3707 byteidxcomp({expr}, {nr}) *byteidxcomp()*
3708 Like byteidx(), except that a composing character is counted
3709 as a separate character. Example: >
3710 let s = 'e' . nr2char(0x301)
3711 echo byteidx(s, 1)
3712 echo byteidxcomp(s, 1)
3713 echo byteidxcomp(s, 2)
3714 < The first and third echo result in 3 ('e' plus composing
3715 character is 3 bytes), the second echo results in 1 ('e' is
3716 one byte).
3717 Only works differently from byteidx() when 'encoding' is set
3718 to a Unicode encoding.
3719
3720 Can also be used as a |method|: >
3721 GetName()->byteidxcomp(idx)
3722
3723 call({func}, {arglist} [, {dict}]) *call()* *E699*
3724 Call function {func} with the items in |List| {arglist} as
3725 arguments.
3726 {func} can either be a |Funcref| or the name of a function.
3727 a:firstline and a:lastline are set to the cursor line.
3728 Returns the return value of the called function.
3729 {dict} is for functions with the "dict" attribute. It will be
3730 used to set the local variable "self". |Dictionary-function|
3731
3732 Can also be used as a |method|: >
3733 GetFunc()->call([arg, arg], dict)
3734
3735 ceil({expr}) *ceil()*
3736 Return the smallest integral value greater than or equal to
3737 {expr} as a |Float| (round up).
3738 {expr} must evaluate to a |Float| or a |Number|.
3739 Examples: >
3740 echo ceil(1.456)
3741 < 2.0 >
3742 echo ceil(-5.456)
3743 < -5.0 >
3744 echo ceil(4.0)
3745 < 4.0
3746
3747 Can also be used as a |method|: >
3748 Compute()->ceil()
3749 <
3750 {only available when compiled with the |+float| feature}
3751
3752
3753 ch_ functions are documented here: |channel-functions-details|
3754
3755
3756 changenr() *changenr()*
3757 Return the number of the most recent change. This is the same
3758 number as what is displayed with |:undolist| and can be used
3759 with the |:undo| command.
3760 When a change was made it is the number of that change. After
3761 redo it is the number of the redone change. After undo it is
3762 one less than the number of the undone change.
3763
3764 char2nr({string} [, {utf8}]) *char2nr()*
3765 Return number value of the first char in {string}.
3766 Examples: >
3767 char2nr(" ") returns 32
3768 char2nr("ABC") returns 65
3769 < When {utf8} is omitted or zero, the current 'encoding' is used.
3770 Example for "utf-8": >
3771 char2nr("á") returns 225
3772 char2nr("á"[0]) returns 195
3773 < When {utf8} is TRUE, always treat as UTF-8 characters.
3774 A combining character is a separate character.
3775 |nr2char()| does the opposite.
3776 To turn a string into a list of character numbers: >
3777 let str = "ABC"
3778 let list = map(split(str, '\zs'), {_, val -> char2nr(val)})
3779 < Result: [65, 66, 67]
3780
3781 Can also be used as a |method|: >
3782 GetChar()->char2nr()
3783
3784
3785 charclass({string}) *charclass()*
3786 Return the character class of the first character in {string}.
3787 The character class is one of:
3788 0 blank
3789 1 punctuation
3790 2 word character
3791 3 emoji
3792 other specific Unicode class
3793 The class is used in patterns and word motions.
3794
3795
3796 charcol({expr}) *charcol()*
3797 Same as |col()| but returns the character index of the column
3798 position given with {expr} instead of the byte position.
3799
3800 Example:
3801 With the cursor on '세' in line 5 with text "여보세요": >
3802 charcol('.') returns 3
3803 col('.') returns 7
3804
3805 < Can also be used as a |method|: >
3806 GetPos()->col()
3807 <
3808 *charidx()*
3809 charidx({string}, {idx} [, {countcc}])
3810 Return the character index of the byte at {idx} in {string}.
3811 The index of the first character is zero.
3812 If there are no multibyte characters the returned value is
3813 equal to {idx}.
3814 When {countcc} is omitted or |FALSE|, then composing characters
3815 are not counted separately, their byte length is
3816 added to the preceding base character.
3817 When {countcc} is |TRUE|, then composing characters are
3818 counted as separate characters.
3819 Returns -1 if the arguments are invalid or if {idx} is greater
3820 than the index of the last byte in {string}. An error is
3821 given if the first argument is not a string, the second
3822 argument is not a number or when the third argument is present
3823 and is not zero or one.
3824 See |byteidx()| and |byteidxcomp()| for getting the byte index
3825 from the character index.
3826 Examples: >
3827 echo charidx('áb́ć', 3) returns 1
3828 echo charidx('áb́ć', 6, 1) returns 4
3829 echo charidx('áb́ć', 16) returns -1
3830 <
3831 Can also be used as a |method|: >
3832 GetName()->charidx(idx)
3833
3834 chdir({dir}) *chdir()*
3835 Change the current working directory to {dir}. The scope of
3836 the directory change depends on the directory of the current
3837 window:
3838 - If the current window has a window-local directory
3839 (|:lcd|), then changes the window local directory.
3840 - Otherwise, if the current tabpage has a local
3841 directory (|:tcd|) then changes the tabpage local
3842 directory.
3843 - Otherwise, changes the global directory.
3844 {dir} must be a String.
3845 If successful, returns the previous working directory. Pass
3846 this to another chdir() to restore the directory.
3847 On failure, returns an empty string.
3848
3849 Example: >
3850 let save_dir = chdir(newdir)
3851 if save_dir != ""
3852 " ... do some work
3853 call chdir(save_dir)
3854 endif
3855
3856 < Can also be used as a |method|: >
3857 GetDir()->chdir()
3858 <
3859 cindent({lnum}) *cindent()*
3860 Get the amount of indent for line {lnum} according the C
3861 indenting rules, as with 'cindent'.
3862 The indent is counted in spaces, the value of 'tabstop' is
3863 relevant. {lnum} is used just like in |getline()|.
3864 When {lnum} is invalid or Vim was not compiled the |+cindent|
3865 feature, -1 is returned.
3866 See |C-indenting|.
3867
3868 Can also be used as a |method|: >
3869 GetLnum()->cindent()
3870
3871 clearmatches([{win}]) *clearmatches()*
3872 Clears all matches previously defined for the current window
3873 by |matchadd()| and the |:match| commands.
3874 If {win} is specified, use the window with this number or
3875 window ID instead of the current window.
3876
3877 Can also be used as a |method|: >
3878 GetWin()->clearmatches()
3879 <
3880 *col()*
3881 col({expr}) The result is a Number, which is the byte index of the column
3882 position given with {expr}. The accepted positions are:
3883 . the cursor position
3884 $ the end of the cursor line (the result is the
3885 number of bytes in the cursor line plus one)
3886 'x position of mark x (if the mark is not set, 0 is
3887 returned)
3888 v In Visual mode: the start of the Visual area (the
3889 cursor is the end). When not in Visual mode
3890 returns the cursor position. Differs from |'<| in
3891 that it's updated right away.
3892 Additionally {expr} can be [lnum, col]: a |List| with the line
3893 and column number. Most useful when the column is "$", to get
3894 the last column of a specific line. When "lnum" or "col" is
3895 out of range then col() returns zero.
3896 To get the line number use |line()|. To get both use
3897 |getpos()|.
3898 For the screen column position use |virtcol()|. For the
3899 character position use |charcol()|.
3900 Note that only marks in the current file can be used.
3901 Examples: >
3902 col(".") column of cursor
3903 col("$") length of cursor line plus one
3904 col("'t") column of mark t
3905 col("'" . markname) column of mark markname
3906 < The first column is 1. 0 is returned for an error.
3907 For an uppercase mark the column may actually be in another
3908 buffer.
3909 For the cursor position, when 'virtualedit' is active, the
3910 column is one higher if the cursor is after the end of the
3911 line. This can be used to obtain the column in Insert mode: >
3912 :imap <F2> <C-O>:let save_ve = &ve<CR>
3913 \<C-O>:set ve=all<CR>
3914 \<C-O>:echo col(".") . "\n" <Bar>
3915 \let &ve = save_ve<CR>
3916
3917 < Can also be used as a |method|: >
3918 GetPos()->col()
3919 <
3920
3921 complete({startcol}, {matches}) *complete()* *E785*
3922 Set the matches for Insert mode completion.
3923 Can only be used in Insert mode. You need to use a mapping
3924 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3925 or with an expression mapping.
3926 {startcol} is the byte offset in the line where the completed
3927 text start. The text up to the cursor is the original text
3928 that will be replaced by the matches. Use col('.') for an
3929 empty string. "col('.') - 1" will replace one character by a
3930 match.
3931 {matches} must be a |List|. Each |List| item is one match.
3932 See |complete-items| for the kind of items that are possible.
3933 "longest" in 'completeopt' is ignored.
3934 Note that the after calling this function you need to avoid
3935 inserting anything that would cause completion to stop.
3936 The match can be selected with CTRL-N and CTRL-P as usual with
3937 Insert mode completion. The popup menu will appear if
3938 specified, see |ins-completion-menu|.
3939 Example: >
3940 inoremap <F5> <C-R>=ListMonths()<CR>
3941
3942 func! ListMonths()
3943 call complete(col('.'), ['January', 'February', 'March',
3944 \ 'April', 'May', 'June', 'July', 'August', 'September',
3945 \ 'October', 'November', 'December'])
3946 return ''
3947 endfunc
3948 < This isn't very useful, but it shows how it works. Note that
3949 an empty string is returned to avoid a zero being inserted.
3950
3951 Can also be used as a |method|, the base is passed as the
3952 second argument: >
3953 GetMatches()->complete(col('.'))
3954
3955 complete_add({expr}) *complete_add()*
3956 Add {expr} to the list of matches. Only to be used by the
3957 function specified with the 'completefunc' option.
3958 Returns 0 for failure (empty string or out of memory),
3959 1 when the match was added, 2 when the match was already in
3960 the list.
3961 See |complete-functions| for an explanation of {expr}. It is
3962 the same as one item in the list that 'omnifunc' would return.
3963
3964 Can also be used as a |method|: >
3965 GetMoreMatches()->complete_add()
3966
3967 complete_check() *complete_check()*
3968 Check for a key typed while looking for completion matches.
3969 This is to be used when looking for matches takes some time.
3970 Returns |TRUE| when searching for matches is to be aborted,
3971 zero otherwise.
3972 Only to be used by the function specified with the
3973 'completefunc' option.
3974
3975
3976 complete_info([{what}]) *complete_info()*
3977 Returns a |Dictionary| with information about Insert mode
3978 completion. See |ins-completion|.
3979 The items are:
3980 mode Current completion mode name string.
3981 See |complete_info_mode| for the values.
3982 pum_visible |TRUE| if popup menu is visible.
3983 See |pumvisible()|.
3984 items List of completion matches. Each item is a
3985 dictionary containing the entries "word",
3986 "abbr", "menu", "kind", "info" and "user_data".
3987 See |complete-items|.
3988 selected Selected item index. First index is zero.
3989 Index is -1 if no item is selected (showing
3990 typed text only, or the last completion after
3991 no item is selected when using the <Up> or
3992 <Down> keys)
3993 inserted Inserted string. [NOT IMPLEMENT YET]
3994
3995 *complete_info_mode*
3996 mode values are:
3997 "" Not in completion mode
3998 "keyword" Keyword completion |i_CTRL-X_CTRL-N|
3999 "ctrl_x" Just pressed CTRL-X |i_CTRL-X|
4000 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or
4001 |i_CTRL-X_CTRL-Y|
4002 "whole_line" Whole lines |i_CTRL-X_CTRL-L|
4003 "files" File names |i_CTRL-X_CTRL-F|
4004 "tags" Tags |i_CTRL-X_CTRL-]|
4005 "path_defines" Definition completion |i_CTRL-X_CTRL-D|
4006 "path_patterns" Include completion |i_CTRL-X_CTRL-I|
4007 "dictionary" Dictionary |i_CTRL-X_CTRL-K|
4008 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T|
4009 "cmdline" Vim Command line |i_CTRL-X_CTRL-V|
4010 "function" User defined completion |i_CTRL-X_CTRL-U|
4011 "omni" Omni completion |i_CTRL-X_CTRL-O|
4012 "spell" Spelling suggestions |i_CTRL-X_s|
4013 "eval" |complete()| completion
4014 "unknown" Other internal modes
4015
4016 If the optional {what} list argument is supplied, then only
4017 the items listed in {what} are returned. Unsupported items in
4018 {what} are silently ignored.
4019
4020 To get the position and size of the popup menu, see
4021 |pum_getpos()|. It's also available in |v:event| during the
4022 |CompleteChanged| event.
4023
4024 Examples: >
4025 " Get all items
4026 call complete_info()
4027 " Get only 'mode'
4028 call complete_info(['mode'])
4029 " Get only 'mode' and 'pum_visible'
4030 call complete_info(['mode', 'pum_visible'])
4031
4032 < Can also be used as a |method|: >
4033 GetItems()->complete_info()
4034 <
4035 *confirm()*
4036 confirm({msg} [, {choices} [, {default} [, {type}]]])
4037 confirm() offers the user a dialog, from which a choice can be
4038 made. It returns the number of the choice. For the first
4039 choice this is 1.
4040 Note: confirm() is only supported when compiled with dialog
4041 support, see |+dialog_con| and |+dialog_gui|.
4042
4043 {msg} is displayed in a |dialog| with {choices} as the
4044 alternatives. When {choices} is missing or empty, "&OK" is
4045 used (and translated).
4046 {msg} is a String, use '\n' to include a newline. Only on
4047 some systems the string is wrapped when it doesn't fit.
4048
4049 {choices} is a String, with the individual choices separated
4050 by '\n', e.g. >
4051 confirm("Save changes?", "&Yes\n&No\n&Cancel")
4052 < The letter after the '&' is the shortcut key for that choice.
4053 Thus you can type 'c' to select "Cancel". The shortcut does
4054 not need to be the first letter: >
4055 confirm("file has been modified", "&Save\nSave &All")
4056 < For the console, the first letter of each choice is used as
4057 the default shortcut key. Case is ignored.
4058
4059 The optional {default} argument is the number of the choice
4060 that is made if the user hits <CR>. Use 1 to make the first
4061 choice the default one. Use 0 to not set a default. If
4062 {default} is omitted, 1 is used.
4063
4064 The optional {type} String argument gives the type of dialog.
4065 This is only used for the icon of the GTK, Mac, Motif and
4066 Win32 GUI. It can be one of these values: "Error",
4067 "Question", "Info", "Warning" or "Generic". Only the first
4068 character is relevant. When {type} is omitted, "Generic" is
4069 used.
4070
4071 If the user aborts the dialog by pressing <Esc>, CTRL-C,
4072 or another valid interrupt key, confirm() returns 0.
4073
4074 An example: >
4075 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
4076 :if choice == 0
4077 : echo "make up your mind!"
4078 :elseif choice == 3
4079 : echo "tasteful"
4080 :else
4081 : echo "I prefer bananas myself."
4082 :endif
4083 < In a GUI dialog, buttons are used. The layout of the buttons
4084 depends on the 'v' flag in 'guioptions'. If it is included,
4085 the buttons are always put vertically. Otherwise, confirm()
4086 tries to put the buttons in one horizontal line. If they
4087 don't fit, a vertical layout is used anyway. For some systems
4088 the horizontal layout is always used.
4089
4090 Can also be used as a |method|in: >
4091 BuildMessage()->confirm("&Yes\n&No")
4092 <
4093 *copy()*
4094 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
4095 different from using {expr} directly.
4096 When {expr} is a |List| a shallow copy is created. This means
4097 that the original |List| can be changed without changing the
4098 copy, and vice versa. But the items are identical, thus
4099 changing an item changes the contents of both |Lists|.
4100 A |Dictionary| is copied in a similar way as a |List|.
4101 Also see |deepcopy()|.
4102 Can also be used as a |method|: >
4103 mylist->copy()
4104
4105 cos({expr}) *cos()*
4106 Return the cosine of {expr}, measured in radians, as a |Float|.
4107 {expr} must evaluate to a |Float| or a |Number|.
4108 Examples: >
4109 :echo cos(100)
4110 < 0.862319 >
4111 :echo cos(-4.01)
4112 < -0.646043
4113
4114 Can also be used as a |method|: >
4115 Compute()->cos()
4116 <
4117 {only available when compiled with the |+float| feature}
4118
4119
4120 cosh({expr}) *cosh()*
4121 Return the hyperbolic cosine of {expr} as a |Float| in the range
4122 [1, inf].
4123 {expr} must evaluate to a |Float| or a |Number|.
4124 Examples: >
4125 :echo cosh(0.5)
4126 < 1.127626 >
4127 :echo cosh(-0.5)
4128 < -1.127626
4129
4130 Can also be used as a |method|: >
4131 Compute()->cosh()
4132 <
4133 {only available when compiled with the |+float| feature}
4134
4135
4136 count({comp}, {expr} [, {ic} [, {start}]]) *count()*
4137 Return the number of times an item with value {expr} appears
4138 in |String|, |List| or |Dictionary| {comp}.
4139
4140 If {start} is given then start with the item with this index.
4141 {start} can only be used with a |List|.
4142
4143 When {ic} is given and it's |TRUE| then case is ignored.
4144
4145 When {comp} is a string then the number of not overlapping
4146 occurrences of {expr} is returned. Zero is returned when
4147 {expr} is an empty string.
4148
4149 Can also be used as a |method|: >
4150 mylist->count(val)
4151 <
4152 *cscope_connection()*
4153 cscope_connection([{num} , {dbpath} [, {prepend}]])
4154 Checks for the existence of a |cscope| connection. If no
4155 parameters are specified, then the function returns:
4156 0, if cscope was not available (not compiled in), or
4157 if there are no cscope connections;
4158 1, if there is at least one cscope connection.
4159
4160 If parameters are specified, then the value of {num}
4161 determines how existence of a cscope connection is checked:
4162
4163 {num} Description of existence check
4164 ----- ------------------------------
4165 0 Same as no parameters (e.g., "cscope_connection()").
4166 1 Ignore {prepend}, and use partial string matches for
4167 {dbpath}.
4168 2 Ignore {prepend}, and use exact string matches for
4169 {dbpath}.
4170 3 Use {prepend}, use partial string matches for both
4171 {dbpath} and {prepend}.
4172 4 Use {prepend}, use exact string matches for both
4173 {dbpath} and {prepend}.
4174
4175 Note: All string comparisons are case sensitive!
4176
4177 Examples. Suppose we had the following (from ":cs show"): >
4178
4179 # pid database name prepend path
4180 0 27664 cscope.out /usr/local
4181 <
4182 Invocation Return Val ~
4183 ---------- ---------- >
4184 cscope_connection() 1
4185 cscope_connection(1, "out") 1
4186 cscope_connection(2, "out") 0
4187 cscope_connection(3, "out") 0
4188 cscope_connection(3, "out", "local") 1
4189 cscope_connection(4, "out") 0
4190 cscope_connection(4, "out", "local") 0
4191 cscope_connection(4, "cscope.out", "/usr/local") 1
4192 <
4193 cursor({lnum}, {col} [, {off}]) *cursor()*
4194 cursor({list})
4195 Positions the cursor at the column (byte count) {col} in the
4196 line {lnum}. The first column is one.
4197
4198 When there is one argument {list} this is used as a |List|
4199 with two, three or four item:
4200 [{lnum}, {col}]
4201 [{lnum}, {col}, {off}]
4202 [{lnum}, {col}, {off}, {curswant}]
4203 This is like the return value of |getpos()| or |getcurpos()|,
4204 but without the first item.
4205
4206 To position the cursor using the character count, use
4207 |setcursorcharpos()|.
4208
4209 Does not change the jumplist.
4210 {lnum} is used like with |getline()|.
4211 If {lnum} is greater than the number of lines in the buffer,
4212 the cursor will be positioned at the last line in the buffer.
4213 If {lnum} is zero, the cursor will stay in the current line.
4214 If {col} is greater than the number of bytes in the line,
4215 the cursor will be positioned at the last character in the
4216 line.
4217 If {col} is zero, the cursor will stay in the current column.
4218 If {curswant} is given it is used to set the preferred column
4219 for vertical movement. Otherwise {col} is used.
4220
4221 When 'virtualedit' is used {off} specifies the offset in
4222 screen columns from the start of the character. E.g., a
4223 position within a <Tab> or after the last character.
4224 Returns 0 when the position could be set, -1 otherwise.
4225
4226 Can also be used as a |method|: >
4227 GetCursorPos()->cursor()
4228
4229 debugbreak({pid}) *debugbreak()*
4230 Specifically used to interrupt a program being debugged. It
4231 will cause process {pid} to get a SIGTRAP. Behavior for other
4232 processes is undefined. See |terminal-debugger|.
4233 {only available on MS-Windows}
4234
4235 Can also be used as a |method|: >
4236 GetPid()->debugbreak()
4237
4238 deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
4239 Make a copy of {expr}. For Numbers and Strings this isn't
4240 different from using {expr} directly.
4241 When {expr} is a |List| a full copy is created. This means
4242 that the original |List| can be changed without changing the
4243 copy, and vice versa. When an item is a |List| or
4244 |Dictionary|, a copy for it is made, recursively. Thus
4245 changing an item in the copy does not change the contents of
4246 the original |List|.
4247 A |Dictionary| is copied in a similar way as a |List|.
4248
4249 When {noref} is omitted or zero a contained |List| or
4250 |Dictionary| is only copied once. All references point to
4251 this single copy. With {noref} set to 1 every occurrence of a
4252 |List| or |Dictionary| results in a new copy. This also means
4253 that a cyclic reference causes deepcopy() to fail.
4254 *E724*
4255 Nesting is possible up to 100 levels. When there is an item
4256 that refers back to a higher level making a deep copy with
4257 {noref} set to 1 will fail.
4258 Also see |copy()|.
4259
4260 Can also be used as a |method|: >
4261 GetObject()->deepcopy()
4262
4263 delete({fname} [, {flags}]) *delete()*
4264 Without {flags} or with {flags} empty: Deletes the file by the
4265 name {fname}. This also works when {fname} is a symbolic link.
4266
4267 When {flags} is "d": Deletes the directory by the name
4268 {fname}. This fails when directory {fname} is not empty.
4269
4270 When {flags} is "rf": Deletes the directory by the name
4271 {fname} and everything in it, recursively. BE CAREFUL!
4272 Note: on MS-Windows it is not possible to delete a directory
4273 that is being used.
4274
4275 A symbolic link itself is deleted, not what it points to.
4276
4277 The result is a Number, which is 0/false if the delete
4278 operation was successful and -1/true when the deletion failed
4279 or partly failed.
4280
4281 Use |remove()| to delete an item from a |List|.
4282 To delete a line from the buffer use |:delete| or
4283 |deletebufline()|.
4284
4285 Can also be used as a |method|: >
4286 GetName()->delete()
4287
4288 deletebufline({buf}, {first} [, {last}]) *deletebufline()*
4289 Delete lines {first} to {last} (inclusive) from buffer {buf}.
4290 If {last} is omitted then delete line {first} only.
4291 On success 0 is returned, on failure 1 is returned.
4292
4293 This function works only for loaded buffers. First call
4294 |bufload()| if needed.
4295
4296 For the use of {buf}, see |bufname()| above.
4297
4298 {first} and {last} are used like with |getline()|. Note that
4299 when using |line()| this refers to the current buffer. Use "$"
4300 to refer to the last line in buffer {buf}.
4301
4302 Can also be used as a |method|: >
4303 GetBuffer()->deletebufline(1)
4304 <
4305 *did_filetype()*
4306 did_filetype() Returns |TRUE| when autocommands are being executed and the
4307 FileType event has been triggered at least once. Can be used
4308 to avoid triggering the FileType event again in the scripts
4309 that detect the file type. |FileType|
4310 Returns |FALSE| when `:setf FALLBACK` was used.
4311 When editing another file, the counter is reset, thus this
4312 really checks if the FileType event has been triggered for the
4313 current buffer. This allows an autocommand that starts
4314 editing another buffer to set 'filetype' and load a syntax
4315 file.
4316
4317 diff_filler({lnum}) *diff_filler()*
4318 Returns the number of filler lines above line {lnum}.
4319 These are the lines that were inserted at this point in
4320 another diff'ed window. These filler lines are shown in the
4321 display but don't exist in the buffer.
4322 {lnum} is used like with |getline()|. Thus "." is the current
4323 line, "'m" mark m, etc.
4324 Returns 0 if the current window is not in diff mode.
4325
4326 Can also be used as a |method|: >
4327 GetLnum()->diff_filler()
4328
4329 diff_hlID({lnum}, {col}) *diff_hlID()*
4330 Returns the highlight ID for diff mode at line {lnum} column
4331 {col} (byte index). When the current line does not have a
4332 diff change zero is returned.
4333 {lnum} is used like with |getline()|. Thus "." is the current
4334 line, "'m" mark m, etc.
4335 {col} is 1 for the leftmost column, {lnum} is 1 for the first
4336 line.
4337 The highlight ID can be used with |synIDattr()| to obtain
4338 syntax information about the highlighting.
4339
4340 Can also be used as a |method|: >
4341 GetLnum()->diff_hlID(col)
4342 <
4343
4344 digraph_get({chars}) *digraph_get()* *E1214*
4345 Return the digraph of {chars}. This should be a string with
4346 exactly two characters. If {chars} are not just two
4347 characters, or the digraph of {chars} does not exist, an error
4348 is given and an empty string is returned.
4349
4350 The character will be converted from Unicode to 'encoding'
4351 when needed. This does require the conversion to be
4352 available, it might fail.
4353
4354 Also see |digraph_getlist()|.
4355
4356 Examples: >
4357 " Get a built-in digraph
4358 :echo digraph_get('00') " Returns '∞'
4359
4360 " Get a user-defined digraph
4361 :call digraph_set('aa', 'あ')
4362 :echo digraph_get('aa') " Returns 'あ'
4363 <
4364 Can also be used as a |method|: >
4365 GetChars()->digraph_get()
4366 <
4367 This function works only when compiled with the |+digraphs|
4368 feature. If this feature is disabled, this function will
4369 display an error message.
4370
4371
4372 digraph_getlist([{listall}]) *digraph_getlist()*
4373 Return a list of digraphs. If the {listall} argument is given
4374 and it is TRUE, return all digraphs, including the default
4375 digraphs. Otherwise, return only user-defined digraphs.
4376
4377 The characters will be converted from Unicode to 'encoding'
4378 when needed. This does require the conservation to be
4379 available, it might fail.
4380
4381 Also see |digraph_get()|.
4382
4383 Examples: >
4384 " Get user-defined digraphs
4385 :echo digraph_getlist()
4386
4387 " Get all the digraphs, including default digraphs
4388 :echo digraph_getlist(1)
4389 <
4390 Can also be used as a |method|: >
4391 GetNumber()->digraph_getlist()
4392 <
4393 This function works only when compiled with the |+digraphs|
4394 feature. If this feature is disabled, this function will
4395 display an error message.
4396
4397
4398 digraph_set({chars}, {digraph}) *digraph_set()* *E1205*
4399 Add digraph {chars} to the list. {chars} must be a string
4400 with two characters. {digraph} is a string with one UTF-8
4401 encoded character. Be careful, composing characters are NOT
4402 ignored. This function is similar to |:digraphs| command, but
4403 useful to add digraphs start with a white space.
4404
4405 The function result is v:true if |digraph| is registered. If
4406 this fails an error message is given and v:false is returned.
4407
4408 If you want to define multiple digraphs at once, you can use
4409 |digraph_setlist()|.
4410
4411 Example: >
4412 call digraph_set(' ', 'あ')
4413 <
4414 Can be used as a |method|: >
4415 GetString()->digraph_set('あ')
4416 <
4417 This function works only when compiled with the |+digraphs|
4418 feature. If this feature is disabled, this function will
4419 display an error message.
4420
4421
4422 digraph_setlist({digraphlist}) *digraph_setlist()*
4423 Similar to |digraph_set()| but this function can add multiple
4424 digraphs at once. {digraphlist} is a list composed of lists,
4425 where each list contains two strings with {chars} and
4426 {digraph} as in |digraph_set()|.
4427 Example: >
4428 call digraph_setlist([['aa', 'あ'], ['ii', 'い']])
4429 <
4430 It is similar to the following: >
4431 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
4432 call digraph_set(chars, digraph)
4433 endfor
4434 < Except that the function returns after the first error,
4435 following digraphs will not be added.
4436
4437 Can be used as a |method|: >
4438 GetList()->digraph_setlist()
4439 <
4440 This function works only when compiled with the |+digraphs|
4441 feature. If this feature is disabled, this function will
4442 display an error message.
4443
4444
4445 echoraw({string}) *echoraw()*
4446 Output {string} as-is, including unprintable characters.
4447 This can be used to output a terminal code. For example, to
4448 disable modifyOtherKeys: >
4449 call echoraw(&t_TE)
4450 < and to enable it again: >
4451 call echoraw(&t_TI)
4452 < Use with care, you can mess up the terminal this way.
4453
4454
4455 empty({expr}) *empty()*
4456 Return the Number 1 if {expr} is empty, zero otherwise.
4457 - A |List| or |Dictionary| is empty when it does not have any
4458 items.
4459 - A |String| is empty when its length is zero.
4460 - A |Number| and |Float| are empty when their value is zero.
4461 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
4462 - A |Job| is empty when it failed to start.
4463 - A |Channel| is empty when it is closed.
4464 - A |Blob| is empty when its length is zero.
4465
4466 For a long |List| this is much faster than comparing the
4467 length with zero.
4468
4469 Can also be used as a |method|: >
4470 mylist->empty()
4471
4472 environ() *environ()*
4473 Return all of environment variables as dictionary. You can
4474 check if an environment variable exists like this: >
4475 :echo has_key(environ(), 'HOME')
4476 < Note that the variable name may be CamelCase; to ignore case
4477 use this: >
4478 :echo index(keys(environ()), 'HOME', 0, 1) != -1
4479
4480 escape({string}, {chars}) *escape()*
4481 Escape the characters in {chars} that occur in {string} with a
4482 backslash. Example: >
4483 :echo escape('c:\program files\vim', ' \')
4484 < results in: >
4485 c:\\program\ files\\vim
4486 < Also see |shellescape()| and |fnameescape()|.
4487
4488 Can also be used as a |method|: >
4489 GetText()->escape(' \')
4490 <
4491 *eval()*
4492 eval({string}) Evaluate {string} and return the result. Especially useful to
4493 turn the result of |string()| back into the original value.
4494 This works for Numbers, Floats, Strings, Blobs and composites
4495 of them. Also works for |Funcref|s that refer to existing
4496 functions.
4497
4498 Can also be used as a |method|: >
4499 argv->join()->eval()
4500
4501 eventhandler() *eventhandler()*
4502 Returns 1 when inside an event handler. That is that Vim got
4503 interrupted while waiting for the user to type a character,
4504 e.g., when dropping a file on Vim. This means interactive
4505 commands cannot be used. Otherwise zero is returned.
4506
4507 executable({expr}) *executable()*
4508 This function checks if an executable with the name {expr}
4509 exists. {expr} must be the name of the program without any
4510 arguments.
4511 executable() uses the value of $PATH and/or the normal
4512 searchpath for programs. *PATHEXT*
4513 On MS-Windows the ".exe", ".bat", etc. can optionally be
4514 included. Then the extensions in $PATHEXT are tried. Thus if
4515 "foo.exe" does not exist, "foo.exe.bat" can be found. If
4516 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot
4517 by itself can be used in $PATHEXT to try using the name
4518 without an extension. When 'shell' looks like a Unix shell,
4519 then the name is also tried without adding an extension.
4520 On MS-Windows it only checks if the file exists and is not a
4521 directory, not if it's really executable.
4522 On MS-Windows an executable in the same directory as Vim is
4523 always found. Since this directory is added to $PATH it
4524 should also work to execute it |win32-PATH|.
4525 The result is a Number:
4526 1 exists
4527 0 does not exist
4528 -1 not implemented on this system
4529 |exepath()| can be used to get the full path of an executable.
4530
4531 Can also be used as a |method|: >
4532 GetCommand()->executable()
4533
4534 execute({command} [, {silent}]) *execute()*
4535 Execute an Ex command or commands and return the output as a
4536 string.
4537 {command} can be a string or a List. In case of a List the
4538 lines are executed one by one.
4539 This is equivalent to: >
4540 redir => var
4541 {command}
4542 redir END
4543 <
4544 The optional {silent} argument can have these values:
4545 "" no `:silent` used
4546 "silent" `:silent` used
4547 "silent!" `:silent!` used
4548 The default is "silent". Note that with "silent!", unlike
4549 `:redir`, error messages are dropped. When using an external
4550 command the screen may be messed up, use `system()` instead.
4551 *E930*
4552 It is not possible to use `:redir` anywhere in {command}.
4553
4554 To get a list of lines use |split()| on the result: >
4555 split(execute('args'), "\n")
4556
4557 < To execute a command in another window than the current one
4558 use `win_execute()`.
4559
4560 When used recursively the output of the recursive call is not
4561 included in the output of the higher level call.
4562
4563 Can also be used as a |method|: >
4564 GetCommand()->execute()
4565
4566 exepath({expr}) *exepath()*
4567 If {expr} is an executable and is either an absolute path, a
4568 relative path or found in $PATH, return the full path.
4569 Note that the current directory is used when {expr} starts
4570 with "./", which may be a problem for Vim: >
4571 echo exepath(v:progpath)
4572 < If {expr} cannot be found in $PATH or is not executable then
4573 an empty string is returned.
4574
4575 Can also be used as a |method|: >
4576 GetCommand()->exepath()
4577 <
4578 *exists()*
4579 exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
4580 zero otherwise.
4581
4582 Note: In a compiled |:def| function the evaluation is done at
4583 runtime. Use `exists_compiled()` to evaluate the expression
4584 at compile time.
4585
4586 For checking for a supported feature use |has()|.
4587 For checking if a file exists use |filereadable()|.
4588
4589 The {expr} argument is a string, which contains one of these:
4590 &option-name Vim option (only checks if it exists,
4591 not if it really works)
4592 +option-name Vim option that works.
4593 $ENVNAME environment variable (could also be
4594 done by comparing with an empty
4595 string)
4596 *funcname built-in function (see |functions|)
4597 or user defined function (see
4598 |user-functions|) that is implemented.
4599 Also works for a variable that is a
4600 Funcref.
4601 ?funcname built-in function that could be
4602 implemented; to be used to check if
4603 "funcname" is valid
4604 varname internal variable (see
4605 |internal-variables|). Also works
4606 for |curly-braces-names|, |Dictionary|
4607 entries, |List| items, etc.
4608 Does not work for local variables in a
4609 compiled `:def` function.
4610 Beware that evaluating an index may
4611 cause an error message for an invalid
4612 expression. E.g.: >
4613 :let l = [1, 2, 3]
4614 :echo exists("l[5]")
4615 < 0 >
4616 :echo exists("l[xx]")
4617 < E121: Undefined variable: xx
4618 0
4619 :cmdname Ex command: built-in command, user
4620 command or command modifier |:command|.
4621 Returns:
4622 1 for match with start of a command
4623 2 full match with a command
4624 3 matches several user commands
4625 To check for a supported command
4626 always check the return value to be 2.
4627 :2match The |:2match| command.
4628 :3match The |:3match| command.
4629 #event autocommand defined for this event
4630 #event#pattern autocommand defined for this event and
4631 pattern (the pattern is taken
4632 literally and compared to the
4633 autocommand patterns character by
4634 character)
4635 #group autocommand group exists
4636 #group#event autocommand defined for this group and
4637 event.
4638 #group#event#pattern
4639 autocommand defined for this group,
4640 event and pattern.
4641 ##event autocommand for this event is
4642 supported.
4643
4644 Examples: >
4645 exists("&shortname")
4646 exists("$HOSTNAME")
4647 exists("*strftime")
4648 exists("*s:MyFunc")
4649 exists("bufcount")
4650 exists(":Make")
4651 exists("#CursorHold")
4652 exists("#BufReadPre#*.gz")
4653 exists("#filetypeindent")
4654 exists("#filetypeindent#FileType")
4655 exists("#filetypeindent#FileType#*")
4656 exists("##ColorScheme")
4657 < There must be no space between the symbol (&/$/*/#) and the
4658 name.
4659 There must be no extra characters after the name, although in
4660 a few cases this is ignored. That may become more strict in
4661 the future, thus don't count on it!
4662 Working example: >
4663 exists(":make")
4664 < NOT working example: >
4665 exists(":make install")
4666
4667 < Note that the argument must be a string, not the name of the
4668 variable itself. For example: >
4669 exists(bufcount)
4670 < This doesn't check for existence of the "bufcount" variable,
4671 but gets the value of "bufcount", and checks if that exists.
4672
4673 Can also be used as a |method|: >
4674 Varname()->exists()
4675 <
4676
4677 exists_compiled({expr}) *exists_compiled()*
4678 Like `exists()` but evaluated at compile time. This is useful
4679 to skip a block where a function is used that would otherwise
4680 give an error: >
4681 if exists_compiled('*ThatFunction')
4682 ThatFunction('works')
4683 endif
4684 < If `exists()` were used then a compilation error would be
4685 given if ThatFunction() is not defined.
4686
4687 {expr} must be a literal string. *E1232*
4688 Can only be used in a |:def| function. *E1233*
4689 This does not work to check for arguments or local variables.
4690
4691
4692 exp({expr}) *exp()*
4693 Return the exponential of {expr} as a |Float| in the range
4694 [0, inf].
4695 {expr} must evaluate to a |Float| or a |Number|.
4696 Examples: >
4697 :echo exp(2)
4698 < 7.389056 >
4699 :echo exp(-1)
4700 < 0.367879
4701
4702 Can also be used as a |method|: >
4703 Compute()->exp()
4704 <
4705 {only available when compiled with the |+float| feature}
4706
4707
4708 expand({string} [, {nosuf} [, {list}]]) *expand()*
4709 Expand wildcards and the following special keywords in
4710 {string}. 'wildignorecase' applies.
4711
4712 If {list} is given and it is |TRUE|, a List will be returned.
4713 Otherwise the result is a String and when there are several
4714 matches, they are separated by <NL> characters. [Note: in
4715 version 5.0 a space was used, which caused problems when a
4716 file name contains a space]
4717
4718 If the expansion fails, the result is an empty string. A name
4719 for a non-existing file is not included, unless {string} does
4720 not start with '%', '#' or '<', see below.
4721
4722 When {string} starts with '%', '#' or '<', the expansion is
4723 done like for the |cmdline-special| variables with their
4724 associated modifiers. Here is a short overview:
4725
4726 % current file name
4727 # alternate file name
4728 #n alternate file name n
4729 <cfile> file name under the cursor
4730 <afile> autocmd file name
4731 <abuf> autocmd buffer number (as a String!)
4732 <amatch> autocmd matched name
4733 <cexpr> C expression under the cursor
4734 <sfile> sourced script file or function name
4735 <slnum> sourced script line number or function
4736 line number
4737 <sflnum> script file line number, also when in
4738 a function
4739 <SID> "<SNR>123_" where "123" is the
4740 current script ID |<SID>|
4741 <stack> call stack
4742 <cword> word under the cursor
4743 <cWORD> WORD under the cursor
4744 <client> the {clientid} of the last received
4745 message |server2client()|
4746 Modifiers:
4747 :p expand to full path
4748 :h head (last path component removed)
4749 :t tail (last path component only)
4750 :r root (one extension removed)
4751 :e extension only
4752
4753 Example: >
4754 :let &tags = expand("%:p:h") . "/tags"
4755 < Note that when expanding a string that starts with '%', '#' or
4756 '<', any following text is ignored. This does NOT work: >
4757 :let doesntwork = expand("%:h.bak")
4758 < Use this: >
4759 :let doeswork = expand("%:h") . ".bak"
4760 < Also note that expanding "<cfile>" and others only returns the
4761 referenced file name without further expansion. If "<cfile>"
4762 is "~/.cshrc", you need to do another expand() to have the
4763 "~/" expanded into the path of the home directory: >
4764 :echo expand(expand("<cfile>"))
4765 <
4766 There cannot be white space between the variables and the
4767 following modifier. The |fnamemodify()| function can be used
4768 to modify normal file names.
4769
4770 When using '%' or '#', and the current or alternate file name
4771 is not defined, an empty string is used. Using "%:p" in a
4772 buffer with no name, results in the current directory, with a
4773 '/' added.
4774
4775 When {string} does not start with '%', '#' or '<', it is
4776 expanded like a file name is expanded on the command line.
4777 'suffixes' and 'wildignore' are used, unless the optional
4778 {nosuf} argument is given and it is |TRUE|.
4779 Names for non-existing files are included. The "**" item can
4780 be used to search in a directory tree. For example, to find
4781 all "README" files in the current directory and below: >
4782 :echo expand("**/README")
4783 <
4784 expand() can also be used to expand variables and environment
4785 variables that are only known in a shell. But this can be
4786 slow, because a shell may be used to do the expansion. See
4787 |expr-env-expand|.
4788 The expanded variable is still handled like a list of file
4789 names. When an environment variable cannot be expanded, it is
4790 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4791 "$FOOBAR".
4792
4793 See |glob()| for finding existing files. See |system()| for
4794 getting the raw output of an external command.
4795
4796 Can also be used as a |method|: >
4797 Getpattern()->expand()
4798
4799 expandcmd({string}) *expandcmd()*
4800 Expand special items in String {string} like what is done for
4801 an Ex command such as `:edit`. This expands special keywords,
4802 like with |expand()|, and environment variables, anywhere in
4803 {string}. "~user" and "~/path" are only expanded at the
4804 start.
4805 Returns the expanded string. Example: >
4806 :echo expandcmd('make %<.o')
4807
4808 < Can also be used as a |method|: >
4809 GetCommand()->expandcmd()
4810 <
4811 extend({expr1}, {expr2} [, {expr3}]) *extend()*
4812 {expr1} and {expr2} must be both |Lists| or both
4813 |Dictionaries|.
4814
4815 If they are |Lists|: Append {expr2} to {expr1}.
4816 If {expr3} is given insert the items of {expr2} before the
4817 item with index {expr3} in {expr1}. When {expr3} is zero
4818 insert before the first item. When {expr3} is equal to
4819 len({expr1}) then {expr2} is appended.
4820 Examples: >
4821 :echo sort(extend(mylist, [7, 5]))
4822 :call extend(mylist, [2, 3], 1)
4823 < When {expr1} is the same List as {expr2} then the number of
4824 items copied is equal to the original length of the List.
4825 E.g., when {expr3} is 1 you get N new copies of the first item
4826 (where N is the original length of the List).
4827 Use |add()| to concatenate one item to a list. To concatenate
4828 two lists into a new list use the + operator: >
4829 :let newlist = [1, 2, 3] + [4, 5]
4830 <
4831 If they are |Dictionaries|:
4832 Add all entries from {expr2} to {expr1}.
4833 If a key exists in both {expr1} and {expr2} then {expr3} is
4834 used to decide what to do:
4835 {expr3} = "keep": keep the value of {expr1}
4836 {expr3} = "force": use the value of {expr2}
4837 {expr3} = "error": give an error message *E737*
4838 When {expr3} is omitted then "force" is assumed.
4839
4840 {expr1} is changed when {expr2} is not empty. If necessary
4841 make a copy of {expr1} first.
4842 {expr2} remains unchanged.
4843 When {expr1} is locked and {expr2} is not empty the operation
4844 fails.
4845 Returns {expr1}.
4846
4847 Can also be used as a |method|: >
4848 mylist->extend(otherlist)
4849
4850
4851 extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()*
4852 Like |extend()| but instead of adding items to {expr1} a new
4853 List or Dictionary is created and returned. {expr1} remains
4854 unchanged. Items can still be changed by {expr2}, if you
4855 don't want that use |deepcopy()| first.
4856
4857
4858 feedkeys({string} [, {mode}]) *feedkeys()*
4859 Characters in {string} are queued for processing as if they
4860 come from a mapping or were typed by the user.
4861
4862 By default the string is added to the end of the typeahead
4863 buffer, thus if a mapping is still being executed the
4864 characters come after them. Use the 'i' flag to insert before
4865 other characters, they will be executed next, before any
4866 characters from a mapping.
4867
4868 The function does not wait for processing of keys contained in
4869 {string}.
4870
4871 To include special keys into {string}, use double-quotes
4872 and "\..." notation |expr-quote|. For example,
4873 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
4874 feedkeys('\<CR>') pushes 5 characters.
4875 A special code that might be useful is <Ignore>, it exits the
4876 wait for a character without doing anything. *<Ignore>*
4877
4878 {mode} is a String, which can contain these character flags:
4879 'm' Remap keys. This is default. If {mode} is absent,
4880 keys are remapped.
4881 'n' Do not remap keys.
4882 't' Handle keys as if typed; otherwise they are handled as
4883 if coming from a mapping. This matters for undo,
4884 opening folds, etc.
4885 'L' Lowlevel input. Only works for Unix or when using the
4886 GUI. Keys are used as if they were coming from the
4887 terminal. Other flags are not used. *E980*
4888 When a CTRL-C interrupts and 't' is included it sets
4889 the internal "got_int" flag.
4890 'i' Insert the string instead of appending (see above).
4891 'x' Execute commands until typeahead is empty. This is
4892 similar to using ":normal!". You can call feedkeys()
4893 several times without 'x' and then one time with 'x'
4894 (possibly with an empty {string}) to execute all the
4895 typeahead. Note that when Vim ends in Insert mode it
4896 will behave as if <Esc> is typed, to avoid getting
4897 stuck, waiting for a character to be typed before the
4898 script continues.
4899 Note that if you manage to call feedkeys() while
4900 executing commands, thus calling it recursively, then
4901 all typeahead will be consumed by the last call.
4902 '!' When used with 'x' will not end Insert mode. Can be
4903 used in a test when a timer is set to exit Insert mode
4904 a little later. Useful for testing CursorHoldI.
4905
4906 Return value is always 0.
4907
4908 Can also be used as a |method|: >
4909 GetInput()->feedkeys()
4910
4911 filereadable({file}) *filereadable()*
4912 The result is a Number, which is |TRUE| when a file with the
4913 name {file} exists, and can be read. If {file} doesn't exist,
4914 or is a directory, the result is |FALSE|. {file} is any
4915 expression, which is used as a String.
4916 If you don't care about the file being readable you can use
4917 |glob()|.
4918 {file} is used as-is, you may want to expand wildcards first: >
4919 echo filereadable('~/.vimrc')
4920 0
4921 echo filereadable(expand('~/.vimrc'))
4922 1
4923
4924 < Can also be used as a |method|: >
4925 GetName()->filereadable()
4926 < *file_readable()*
4927 Obsolete name: file_readable().
4928
4929
4930 filewritable({file}) *filewritable()*
4931 The result is a Number, which is 1 when a file with the
4932 name {file} exists, and can be written. If {file} doesn't
4933 exist, or is not writable, the result is 0. If {file} is a
4934 directory, and we can write to it, the result is 2.
4935
4936 Can also be used as a |method|: >
4937 GetName()->filewritable()
4938
4939
4940 filter({expr1}, {expr2}) *filter()*
4941 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
4942 For each item in {expr1} evaluate {expr2} and when the result
4943 is zero or false remove the item from the |List| or
4944 |Dictionary|. Similarly for each byte in a |Blob| and each
4945 charactor in a |String|.
4946
4947 {expr2} must be a |string| or |Funcref|.
4948
4949 If {expr2} is a |string|, inside {expr2} |v:val| has the value
4950 of the current item. For a |Dictionary| |v:key| has the key
4951 of the current item and for a |List| |v:key| has the index of
4952 the current item. For a |Blob| |v:key| has the index of the
4953 current byte. For a |String| |v:key| has the index of the
4954 current character.
4955 Examples: >
4956 call filter(mylist, 'v:val !~ "OLD"')
4957 < Removes the items where "OLD" appears. >
4958 call filter(mydict, 'v:key >= 8')
4959 < Removes the items with a key below 8. >
4960 call filter(var, 0)
4961 < Removes all the items, thus clears the |List| or |Dictionary|.
4962
4963 Note that {expr2} is the result of expression and is then
4964 used as an expression again. Often it is good to use a
4965 |literal-string| to avoid having to double backslashes.
4966
4967 If {expr2} is a |Funcref| it must take two arguments:
4968 1. the key or the index of the current item.
4969 2. the value of the current item.
4970 The function must return |TRUE| if the item should be kept.
4971 Example that keeps the odd items of a list: >
4972 func Odd(idx, val)
4973 return a:idx % 2 == 1
4974 endfunc
4975 call filter(mylist, function('Odd'))
4976 < It is shorter when using a |lambda|: >
4977 call filter(myList, {idx, val -> idx * val <= 42})
4978 < If you do not use "val" you can leave it out: >
4979 call filter(myList, {idx -> idx % 2 == 1})
4980 <
4981 In |Vim9| script the result must be true, false, zero or one.
4982 Other values will result in a type error.
4983
4984 For a |List| and a |Dictionary| the operation is done
4985 in-place. If you want it to remain unmodified make a copy
4986 first: >
4987 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
4988
4989 < Returns {expr1}, the |List| or |Dictionary| that was filtered,
4990 or a new |Blob| or |String|.
4991 When an error is encountered while evaluating {expr2} no
4992 further items in {expr1} are processed.
4993 When {expr2} is a Funcref errors inside a function are ignored,
4994 unless it was defined with the "abort" flag.
4995
4996 Can also be used as a |method|: >
4997 mylist->filter(expr2)
4998
4999 finddir({name} [, {path} [, {count}]]) *finddir()*
5000 Find directory {name} in {path}. Supports both downwards and
5001 upwards recursive directory searches. See |file-searching|
5002 for the syntax of {path}.
5003
5004 Returns the path of the first found match. When the found
5005 directory is below the current directory a relative path is
5006 returned. Otherwise a full path is returned.
5007 If {path} is omitted or empty then 'path' is used.
5008
5009 If the optional {count} is given, find {count}'s occurrence of
5010 {name} in {path} instead of the first one.
5011 When {count} is negative return all the matches in a |List|.
5012
5013 This is quite similar to the ex-command `:find`.
5014 {only available when compiled with the |+file_in_path|
5015 feature}
5016
5017 Can also be used as a |method|: >
5018 GetName()->finddir()
5019
5020 findfile({name} [, {path} [, {count}]]) *findfile()*
5021 Just like |finddir()|, but find a file instead of a directory.
5022 Uses 'suffixesadd'.
5023 Example: >
5024 :echo findfile("tags.vim", ".;")
5025 < Searches from the directory of the current file upwards until
5026 it finds the file "tags.vim".
5027
5028 Can also be used as a |method|: >
5029 GetName()->findfile()
5030
5031 flatten({list} [, {maxdepth}]) *flatten()*
5032 Flatten {list} up to {maxdepth} levels. Without {maxdepth}
5033 the result is a |List| without nesting, as if {maxdepth} is
5034 a very large number.
5035 The {list} is changed in place, use |flattennew()| if you do
5036 not want that.
5037 In Vim9 script flatten() cannot be used, you must always use
5038 |flattennew()|.
5039 *E900*
5040 {maxdepth} means how deep in nested lists changes are made.
5041 {list} is not modified when {maxdepth} is 0.
5042 {maxdepth} must be positive number.
5043
5044 If there is an error the number zero is returned.
5045
5046 Example: >
5047 :echo flatten([1, [2, [3, 4]], 5])
5048 < [1, 2, 3, 4, 5] >
5049 :echo flatten([1, [2, [3, 4]], 5], 1)
5050 < [1, 2, [3, 4], 5]
5051
5052 Can also be used as a |method|: >
5053 mylist->flatten()
5054 <
5055 flattennew({list} [, {maxdepth}]) *flattennew()*
5056 Like |flatten()| but first make a copy of {list}.
5057
5058
5059 float2nr({expr}) *float2nr()*
5060 Convert {expr} to a Number by omitting the part after the
5061 decimal point.
5062 {expr} must evaluate to a |Float| or a Number.
5063 When the value of {expr} is out of range for a |Number| the
5064 result is truncated to 0x7fffffff or -0x7fffffff (or when
5065 64-bit Number support is enabled, 0x7fffffffffffffff or
5066 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
5067 64-bit Number support is enabled, -0x8000000000000000).
5068 Examples: >
5069 echo float2nr(3.95)
5070 < 3 >
5071 echo float2nr(-23.45)
5072 < -23 >
5073 echo float2nr(1.0e100)
5074 < 2147483647 (or 9223372036854775807) >
5075 echo float2nr(-1.0e150)
5076 < -2147483647 (or -9223372036854775807) >
5077 echo float2nr(1.0e-100)
5078 < 0
5079
5080 Can also be used as a |method|: >
5081 Compute()->float2nr()
5082 <
5083 {only available when compiled with the |+float| feature}
5084
5085
5086 floor({expr}) *floor()*
5087 Return the largest integral value less than or equal to
5088 {expr} as a |Float| (round down).
5089 {expr} must evaluate to a |Float| or a |Number|.
5090 Examples: >
5091 echo floor(1.856)
5092 < 1.0 >
5093 echo floor(-5.456)
5094 < -6.0 >
5095 echo floor(4.0)
5096 < 4.0
5097
5098 Can also be used as a |method|: >
5099 Compute()->floor()
5100 <
5101 {only available when compiled with the |+float| feature}
5102
5103
5104 fmod({expr1}, {expr2}) *fmod()*
5105 Return the remainder of {expr1} / {expr2}, even if the
5106 division is not representable. Returns {expr1} - i * {expr2}
5107 for some integer i such that if {expr2} is non-zero, the
5108 result has the same sign as {expr1} and magnitude less than
5109 the magnitude of {expr2}. If {expr2} is zero, the value
5110 returned is zero. The value returned is a |Float|.
5111 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
5112 Examples: >
5113 :echo fmod(12.33, 1.22)
5114 < 0.13 >
5115 :echo fmod(-12.33, 1.22)
5116 < -0.13
5117
5118 Can also be used as a |method|: >
5119 Compute()->fmod(1.22)
5120 <
5121 {only available when compiled with |+float| feature}
5122
5123
5124 fnameescape({string}) *fnameescape()*
5125 Escape {string} for use as file name command argument. All
5126 characters that have a special meaning, such as '%' and '|'
5127 are escaped with a backslash.
5128 For most systems the characters escaped are
5129 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
5130 appears in a filename, it depends on the value of 'isfname'.
5131 A leading '+' and '>' is also escaped (special after |:edit|
5132 and |:write|). And a "-" by itself (special after |:cd|).
5133 Example: >
5134 :let fname = '+some str%nge|name'
5135 :exe "edit " . fnameescape(fname)
5136 < results in executing: >
5137 edit \+some\ str\%nge\|name
5138 <
5139 Can also be used as a |method|: >
5140 GetName()->fnameescape()
5141
5142 fnamemodify({fname}, {mods}) *fnamemodify()*
5143 Modify file name {fname} according to {mods}. {mods} is a
5144 string of characters like it is used for file names on the
5145 command line. See |filename-modifiers|.
5146 Example: >
5147 :echo fnamemodify("main.c", ":p:h")
5148 < results in: >
5149 /home/mool/vim/vim/src
5150 < If {mods} is empty then {fname} is returned.
5151 Note: Environment variables don't work in {fname}, use
5152 |expand()| first then.
5153
5154 Can also be used as a |method|: >
5155 GetName()->fnamemodify(':p:h')
5156
5157 foldclosed({lnum}) *foldclosed()*
5158 The result is a Number. If the line {lnum} is in a closed
5159 fold, the result is the number of the first line in that fold.
5160 If the line {lnum} is not in a closed fold, -1 is returned.
5161 {lnum} is used like with |getline()|. Thus "." is the current
5162 line, "'m" mark m, etc.
5163
5164 Can also be used as a |method|: >
5165 GetLnum()->foldclosed()
5166
5167 foldclosedend({lnum}) *foldclosedend()*
5168 The result is a Number. If the line {lnum} is in a closed
5169 fold, the result is the number of the last line in that fold.
5170 If the line {lnum} is not in a closed fold, -1 is returned.
5171 {lnum} is used like with |getline()|. Thus "." is the current
5172 line, "'m" mark m, etc.
5173
5174 Can also be used as a |method|: >
5175 GetLnum()->foldclosedend()
5176
5177 foldlevel({lnum}) *foldlevel()*
5178 The result is a Number, which is the foldlevel of line {lnum}
5179 in the current buffer. For nested folds the deepest level is
5180 returned. If there is no fold at line {lnum}, zero is
5181 returned. It doesn't matter if the folds are open or closed.
5182 When used while updating folds (from 'foldexpr') -1 is
5183 returned for lines where folds are still to be updated and the
5184 foldlevel is unknown. As a special case the level of the
5185 previous line is usually available.
5186 {lnum} is used like with |getline()|. Thus "." is the current
5187 line, "'m" mark m, etc.
5188
5189 Can also be used as a |method|: >
5190 GetLnum()->foldlevel()
5191 <
5192 *foldtext()*
5193 foldtext() Returns a String, to be displayed for a closed fold. This is
5194 the default function used for the 'foldtext' option and should
5195 only be called from evaluating 'foldtext'. It uses the
5196 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
5197 The returned string looks like this: >
5198 +-- 45 lines: abcdef
5199 < The number of leading dashes depends on the foldlevel. The
5200 "45" is the number of lines in the fold. "abcdef" is the text
5201 in the first non-blank line of the fold. Leading white space,
5202 "//" or "/*" and the text from the 'foldmarker' and
5203 'commentstring' options is removed.
5204 When used to draw the actual foldtext, the rest of the line
5205 will be filled with the fold char from the 'fillchars'
5206 setting.
5207 {not available when compiled without the |+folding| feature}
5208
5209 foldtextresult({lnum}) *foldtextresult()*
5210 Returns the text that is displayed for the closed fold at line
5211 {lnum}. Evaluates 'foldtext' in the appropriate context.
5212 When there is no closed fold at {lnum} an empty string is
5213 returned.
5214 {lnum} is used like with |getline()|. Thus "." is the current
5215 line, "'m" mark m, etc.
5216 Useful when exporting folded text, e.g., to HTML.
5217 {not available when compiled without the |+folding| feature}
5218
5219
5220 Can also be used as a |method|: >
5221 GetLnum()->foldtextresult()
5222 <
5223 *foreground()*
5224 foreground() Move the Vim window to the foreground. Useful when sent from
5225 a client to a Vim server. |remote_send()|
5226 On Win32 systems this might not work, the OS does not always
5227 allow a window to bring itself to the foreground. Use
5228 |remote_foreground()| instead.
5229 {only in the Win32, Athena, Motif and GTK GUI versions and the
5230 Win32 console version}
5231
5232 fullcommand({name}) *fullcommand()*
5233 Get the full command name from a short abbreviated command
5234 name; see |20.2| for details on command abbreviations.
5235
5236 The string argument {name} may start with a `:` and can
5237 include a [range], these are skipped and not returned.
5238 Returns an empty string if a command doesn't exist or if it's
5239 ambiguous (for user-defined commands).
5240
5241 For example `fullcommand('s')`, `fullcommand('sub')`,
5242 `fullcommand(':%substitute')` all return "substitute".
5243
5244 Can also be used as a |method|: >
5245 GetName()->fullcommand()
5246 <
5247 *funcref()*
5248 funcref({name} [, {arglist}] [, {dict}])
5249 Just like |function()|, but the returned Funcref will lookup
5250 the function by reference, not by name. This matters when the
5251 function {name} is redefined later.
5252
5253 Unlike |function()|, {name} must be an existing user function.
5254 Also for autoloaded functions. {name} cannot be a builtin
5255 function.
5256
5257 Can also be used as a |method|: >
5258 GetFuncname()->funcref([arg])
5259 <
5260 *function()* *partial* *E700* *E922* *E923*
5261 function({name} [, {arglist}] [, {dict}])
5262 Return a |Funcref| variable that refers to function {name}.
5263 {name} can be the name of a user defined function or an
5264 internal function.
5265
5266 {name} can also be a Funcref or a partial. When it is a
5267 partial the dict stored in it will be used and the {dict}
5268 argument is not allowed. E.g.: >
5269 let FuncWithArg = function(dict.Func, [arg])
5270 let Broken = function(dict.Func, [arg], dict)
5271 <
5272 When using the Funcref the function will be found by {name},
5273 also when it was redefined later. Use |funcref()| to keep the
5274 same function.
5275
5276 When {arglist} or {dict} is present this creates a partial.
5277 That means the argument list and/or the dictionary is stored in
5278 the Funcref and will be used when the Funcref is called.
5279
5280 The arguments are passed to the function in front of other
5281 arguments, but after any argument from |method|. Example: >
5282 func Callback(arg1, arg2, name)
5283 ...
5284 let Partial = function('Callback', ['one', 'two'])
5285 ...
5286 call Partial('name')
5287 < Invokes the function as with: >
5288 call Callback('one', 'two', 'name')
5289
5290 < With a |method|: >
5291 func Callback(one, two, three)
5292 ...
5293 let Partial = function('Callback', ['two'])
5294 ...
5295 eval 'one'->Partial('three')
5296 < Invokes the function as with: >
5297 call Callback('one', 'two', 'three')
5298
5299 < The function() call can be nested to add more arguments to the
5300 Funcref. The extra arguments are appended to the list of
5301 arguments. Example: >
5302 func Callback(arg1, arg2, name)
5303 ...
5304 let Func = function('Callback', ['one'])
5305 let Func2 = function(Func, ['two'])
5306 ...
5307 call Func2('name')
5308 < Invokes the function as with: >
5309 call Callback('one', 'two', 'name')
5310
5311 < The Dictionary is only useful when calling a "dict" function.
5312 In that case the {dict} is passed in as "self". Example: >
5313 function Callback() dict
5314 echo "called for " . self.name
5315 endfunction
5316 ...
5317 let context = {"name": "example"}
5318 let Func = function('Callback', context)
5319 ...
5320 call Func() " will echo: called for example
5321 < The use of function() is not needed when there are no extra
5322 arguments, these two are equivalent: >
5323 let Func = function('Callback', context)
5324 let Func = context.Callback
5325
5326 < The argument list and the Dictionary can be combined: >
5327 function Callback(arg1, count) dict
5328 ...
5329 let context = {"name": "example"}
5330 let Func = function('Callback', ['one'], context)
5331 ...
5332 call Func(500)
5333 < Invokes the function as with: >
5334 call context.Callback('one', 500)
5335 <
5336 Can also be used as a |method|: >
5337 GetFuncname()->function([arg])
5338
5339
5340 garbagecollect([{atexit}]) *garbagecollect()*
5341 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
5342 that have circular references.
5343
5344 There is hardly ever a need to invoke this function, as it is
5345 automatically done when Vim runs out of memory or is waiting
5346 for the user to press a key after 'updatetime'. Items without
5347 circular references are always freed when they become unused.
5348 This is useful if you have deleted a very big |List| and/or
5349 |Dictionary| with circular references in a script that runs
5350 for a long time.
5351
5352 When the optional {atexit} argument is one, garbage
5353 collection will also be done when exiting Vim, if it wasn't
5354 done before. This is useful when checking for memory leaks.
5355
5356 The garbage collection is not done immediately but only when
5357 it's safe to perform. This is when waiting for the user to
5358 type a character. To force garbage collection immediately use
5359 |test_garbagecollect_now()|.
5360
5361 get({list}, {idx} [, {default}]) *get()*
5362 Get item {idx} from |List| {list}. When this item is not
5363 available return {default}. Return zero when {default} is
5364 omitted.
5365 Preferably used as a |method|: >
5366 mylist->get(idx)
5367 get({blob}, {idx} [, {default}])
5368 Get byte {idx} from |Blob| {blob}. When this byte is not
5369 available return {default}. Return -1 when {default} is
5370 omitted.
5371 Preferably used as a |method|: >
5372 myblob->get(idx)
5373 get({dict}, {key} [, {default}])
5374 Get item with key {key} from |Dictionary| {dict}. When this
5375 item is not available return {default}. Return zero when
5376 {default} is omitted. Useful example: >
5377 let val = get(g:, 'var_name', 'default')
5378 < This gets the value of g:var_name if it exists, and uses
5379 'default' when it does not exist.
5380 Preferably used as a |method|: >
5381 mydict->get(key)
5382 get({func}, {what})
5383 Get an item with from Funcref {func}. Possible values for
5384 {what} are:
5385 "name" The function name
5386 "func" The function
5387 "dict" The dictionary
5388 "args" The list with arguments
5389 Preferably used as a |method|: >
5390 myfunc->get(what)
5391 <
5392 *getbufinfo()*
5393 getbufinfo([{buf}])
5394 getbufinfo([{dict}])
5395 Get information about buffers as a List of Dictionaries.
5396
5397 Without an argument information about all the buffers is
5398 returned.
5399
5400 When the argument is a |Dictionary| only the buffers matching
5401 the specified criteria are returned. The following keys can
5402 be specified in {dict}:
5403 buflisted include only listed buffers.
5404 bufloaded include only loaded buffers.
5405 bufmodified include only modified buffers.
5406
5407 Otherwise, {buf} specifies a particular buffer to return
5408 information for. For the use of {buf}, see |bufname()|
5409 above. If the buffer is found the returned List has one item.
5410 Otherwise the result is an empty list.
5411
5412 Each returned List item is a dictionary with the following
5413 entries:
5414 bufnr Buffer number.
5415 changed TRUE if the buffer is modified.
5416 changedtick Number of changes made to the buffer.
5417 hidden TRUE if the buffer is hidden.
5418 lastused Timestamp in seconds, like
5419 |localtime()|, when the buffer was
5420 last used.
5421 {only with the |+viminfo| feature}
5422 listed TRUE if the buffer is listed.
5423 lnum Line number used for the buffer when
5424 opened in the current window.
5425 Only valid if the buffer has been
5426 displayed in the window in the past.
5427 If you want the line number of the
5428 last known cursor position in a given
5429 window, use |line()|: >
5430 :echo line('.', {winid})
5431 <
5432 linecount Number of lines in the buffer (only
5433 valid when loaded)
5434 loaded TRUE if the buffer is loaded.
5435 name Full path to the file in the buffer.
5436 signs List of signs placed in the buffer.
5437 Each list item is a dictionary with
5438 the following fields:
5439 id sign identifier
5440 lnum line number
5441 name sign name
5442 variables A reference to the dictionary with
5443 buffer-local variables.
5444 windows List of |window-ID|s that display this
5445 buffer
5446 popups List of popup |window-ID|s that
5447 display this buffer
5448
5449 Examples: >
5450 for buf in getbufinfo()
5451 echo buf.name
5452 endfor
5453 for buf in getbufinfo({'buflisted':1})
5454 if buf.changed
5455 ....
5456 endif
5457 endfor
5458 <
5459 To get buffer-local options use: >
5460 getbufvar({bufnr}, '&option_name')
5461 <
5462 Can also be used as a |method|: >
5463 GetBufnr()->getbufinfo()
5464 <
5465
5466 *getbufline()*
5467 getbufline({buf}, {lnum} [, {end}])
5468 Return a |List| with the lines starting from {lnum} to {end}
5469 (inclusive) in the buffer {buf}. If {end} is omitted, a
5470 |List| with only the line {lnum} is returned.
5471
5472 For the use of {buf}, see |bufname()| above.
5473
5474 For {lnum} and {end} "$" can be used for the last line of the
5475 buffer. Otherwise a number must be used.
5476
5477 When {lnum} is smaller than 1 or bigger than the number of
5478 lines in the buffer, an empty |List| is returned.
5479
5480 When {end} is greater than the number of lines in the buffer,
5481 it is treated as {end} is set to the number of lines in the
5482 buffer. When {end} is before {lnum} an empty |List| is
5483 returned.
5484
5485 This function works only for loaded buffers. For unloaded and
5486 non-existing buffers, an empty |List| is returned.
5487
5488 Example: >
5489 :let lines = getbufline(bufnr("myfile"), 1, "$")
5490
5491 < Can also be used as a |method|: >
5492 GetBufnr()->getbufline(lnum)
5493
5494 getbufvar({buf}, {varname} [, {def}]) *getbufvar()*
5495 The result is the value of option or local buffer variable
5496 {varname} in buffer {buf}. Note that the name without "b:"
5497 must be used.
5498 The {varname} argument is a string.
5499 When {varname} is empty returns a |Dictionary| with all the
5500 buffer-local variables.
5501 When {varname} is equal to "&" returns a |Dictionary| with all
5502 the buffer-local options.
5503 Otherwise, when {varname} starts with "&" returns the value of
5504 a buffer-local option.
5505 This also works for a global or buffer-local option, but it
5506 doesn't work for a global variable, window-local variable or
5507 window-local option.
5508 For the use of {buf}, see |bufname()| above.
5509 When the buffer or variable doesn't exist {def} or an empty
5510 string is returned, there is no error message.
5511 Examples: >
5512 :let bufmodified = getbufvar(1, "&mod")
5513 :echo "todo myvar = " . getbufvar("todo", "myvar")
5514
5515 < Can also be used as a |method|: >
5516 GetBufnr()->getbufvar(varname)
5517 <
5518 getchangelist([{buf}]) *getchangelist()*
5519 Returns the |changelist| for the buffer {buf}. For the use
5520 of {buf}, see |bufname()| above. If buffer {buf} doesn't
5521 exist, an empty list is returned.
5522
5523 The returned list contains two entries: a list with the change
5524 locations and the current position in the list. Each
5525 entry in the change list is a dictionary with the following
5526 entries:
5527 col column number
5528 coladd column offset for 'virtualedit'
5529 lnum line number
5530 If buffer {buf} is the current buffer, then the current
5531 position refers to the position in the list. For other
5532 buffers, it is set to the length of the list.
5533
5534 Can also be used as a |method|: >
5535 GetBufnr()->getchangelist()
5536
5537 getchar([expr]) *getchar()*
5538 Get a single character from the user or input stream.
5539 If [expr] is omitted, wait until a character is available.
5540 If [expr] is 0, only get a character when one is available.
5541 Return zero otherwise.
5542 If [expr] is 1, only check if a character is available, it is
5543 not consumed. Return zero if no character available.
5544 If you prefer always getting a string use |getcharstr()|.
5545
5546 Without [expr] and when [expr] is 0 a whole character or
5547 special key is returned. If it is a single character, the
5548 result is a number. Use nr2char() to convert it to a String.
5549 Otherwise a String is returned with the encoded character.
5550 For a special key it's a String with a sequence of bytes
5551 starting with 0x80 (decimal: 128). This is the same value as
5552 the String "\<Key>", e.g., "\<Left>". The returned value is
5553 also a String when a modifier (shift, control, alt) was used
5554 that is not included in the character.
5555
5556 When [expr] is 0 and Esc is typed, there will be a short delay
5557 while Vim waits to see if this is the start of an escape
5558 sequence.
5559
5560 When [expr] is 1 only the first byte is returned. For a
5561 one-byte character it is the character itself as a number.
5562 Use nr2char() to convert it to a String.
5563
5564 Use getcharmod() to obtain any additional modifiers.
5565
5566 When the user clicks a mouse button, the mouse event will be
5567 returned. The position can then be found in |v:mouse_col|,
5568 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
5569 |getmousepos()| can also be used. Mouse move events will be
5570 ignored.
5571 This example positions the mouse as it would normally happen: >
5572 let c = getchar()
5573 if c == "\<LeftMouse>" && v:mouse_win > 0
5574 exe v:mouse_win . "wincmd w"
5575 exe v:mouse_lnum
5576 exe "normal " . v:mouse_col . "|"
5577 endif
5578 <
5579 When using bracketed paste only the first character is
5580 returned, the rest of the pasted text is dropped.
5581 |xterm-bracketed-paste|.
5582
5583 There is no prompt, you will somehow have to make clear to the
5584 user that a character has to be typed. The screen is not
5585 redrawn, e.g. when resizing the window. When using a popup
5586 window it should work better with a |popup-filter|.
5587
5588 There is no mapping for the character.
5589 Key codes are replaced, thus when the user presses the <Del>
5590 key you get the code for the <Del> key, not the raw character
5591 sequence. Examples: >
5592 getchar() == "\<Del>"
5593 getchar() == "\<S-Left>"
5594 < This example redefines "f" to ignore case: >
5595 :nmap f :call FindChar()<CR>
5596 :function FindChar()
5597 : let c = nr2char(getchar())
5598 : while col('.') < col('$') - 1
5599 : normal l
5600 : if getline('.')[col('.') - 1] ==? c
5601 : break
5602 : endif
5603 : endwhile
5604 :endfunction
5605 <
5606 You may also receive synthetic characters, such as
5607 |<CursorHold>|. Often you will want to ignore this and get
5608 another character: >
5609 :function GetKey()
5610 : let c = getchar()
5611 : while c == "\<CursorHold>"
5612 : let c = getchar()
5613 : endwhile
5614 : return c
5615 :endfunction
5616
5617 getcharmod() *getcharmod()*
5618 The result is a Number which is the state of the modifiers for
5619 the last obtained character with getchar() or in another way.
5620 These values are added together:
5621 2 shift
5622 4 control
5623 8 alt (meta)
5624 16 meta (when it's different from ALT)
5625 32 mouse double click
5626 64 mouse triple click
5627 96 mouse quadruple click (== 32 + 64)
5628 128 command (Macintosh only)
5629 Only the modifiers that have not been included in the
5630 character itself are obtained. Thus Shift-a results in "A"
5631 without a modifier.
5632
5633 *getcharpos()*
5634 getcharpos({expr})
5635 Get the position for String {expr}. Same as |getpos()| but the
5636 column number in the returned List is a character index
5637 instead of a byte index.
5638 If |getpos()| returns a very large column number, such as
5639 2147483647, then getcharpos() will return the character index
5640 of the last character.
5641
5642 Example:
5643 With the cursor on '세' in line 5 with text "여보세요": >
5644 getcharpos('.') returns [0, 5, 3, 0]
5645 getpos('.') returns [0, 5, 7, 0]
5646 <
5647 Can also be used as a |method|: >
5648 GetMark()->getcharpos()
5649
5650 getcharsearch() *getcharsearch()*
5651 Return the current character search information as a {dict}
5652 with the following entries:
5653
5654 char character previously used for a character
5655 search (|t|, |f|, |T|, or |F|); empty string
5656 if no character search has been performed
5657 forward direction of character search; 1 for forward,
5658 0 for backward
5659 until type of character search; 1 for a |t| or |T|
5660 character search, 0 for an |f| or |F|
5661 character search
5662
5663 This can be useful to always have |;| and |,| search
5664 forward/backward regardless of the direction of the previous
5665 character search: >
5666 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
5667 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
5668 < Also see |setcharsearch()|.
5669
5670
5671 getcharstr([expr]) *getcharstr()*
5672 Get a single character from the user or input stream as a
5673 string.
5674 If [expr] is omitted, wait until a character is available.
5675 If [expr] is 0 or false, only get a character when one is
5676 available. Return an empty string otherwise.
5677 If [expr] is 1 or true, only check if a character is
5678 available, it is not consumed. Return an empty string
5679 if no character is available.
5680 Otherwise this works like |getchar()|, except that a number
5681 result is converted to a string.
5682
5683
5684 getcmdline() *getcmdline()*
5685 Return the current command-line. Only works when the command
5686 line is being edited, thus requires use of |c_CTRL-\_e| or
5687 |c_CTRL-R_=|.
5688 Example: >
5689 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
5690 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
5691 Returns an empty string when entering a password or using
5692 |inputsecret()|.
5693
5694 getcmdpos() *getcmdpos()*
5695 Return the position of the cursor in the command line as a
5696 byte count. The first column is 1.
5697 Only works when editing the command line, thus requires use of
5698 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5699 Returns 0 otherwise.
5700 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
5701
5702 getcmdtype() *getcmdtype()*
5703 Return the current command-line type. Possible return values
5704 are:
5705 : normal Ex command
5706 > debug mode command |debug-mode|
5707 / forward search command
5708 ? backward search command
5709 @ |input()| command
5710 - |:insert| or |:append| command
5711 = |i_CTRL-R_=|
5712 Only works when editing the command line, thus requires use of
5713 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
5714 Returns an empty string otherwise.
5715 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
5716
5717 getcmdwintype() *getcmdwintype()*
5718 Return the current |command-line-window| type. Possible return
5719 values are the same as |getcmdtype()|. Returns an empty string
5720 when not in the command-line window.
5721
5722 getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
5723 Return a list of command-line completion matches. The String
5724 {type} argument specifies what for. The following completion
5725 types are supported:
5726
5727 arglist file names in argument list
5728 augroup autocmd groups
5729 buffer buffer names
5730 behave :behave suboptions
5731 color color schemes
5732 command Ex command
5733 cmdline |cmdline-completion| result
5734 compiler compilers
5735 cscope |:cscope| suboptions
5736 diff_buffer |:diffget| and |:diffput| completion
5737 dir directory names
5738 environment environment variable names
5739 event autocommand events
5740 expression Vim expression
5741 file file and directory names
5742 file_in_path file and directory names in |'path'|
5743 filetype filetype names |'filetype'|
5744 function function name
5745 help help subjects
5746 highlight highlight groups
5747 history :history suboptions
5748 locale locale names (as output of locale -a)
5749 mapclear buffer argument
5750 mapping mapping name
5751 menu menus
5752 messages |:messages| suboptions
5753 option options
5754 packadd optional package |pack-add| names
5755 shellcmd Shell command
5756 sign |:sign| suboptions
5757 syntax syntax file names |'syntax'|
5758 syntime |:syntime| suboptions
5759 tag tags
5760 tag_listfiles tags, file names
5761 user user names
5762 var user variables
5763
5764 If {pat} is an empty string, then all the matches are
5765 returned. Otherwise only items matching {pat} are returned.
5766 See |wildcards| for the use of special characters in {pat}.
5767
5768 If the optional {filtered} flag is set to 1, then 'wildignore'
5769 is applied to filter the results. Otherwise all the matches
5770 are returned. The 'wildignorecase' option always applies.
5771
5772 If {type} is "cmdline", then the |cmdline-completion| result is
5773 returned. For example, to complete the possible values after
5774 a ":call" command: >
5775 echo getcompletion('call ', 'cmdline')
5776 <
5777 If there are no matches, an empty list is returned. An
5778 invalid value for {type} produces an error.
5779
5780 Can also be used as a |method|: >
5781 GetPattern()->getcompletion('color')
5782 <
5783 *getcurpos()*
5784 getcurpos([{winid}])
5785 Get the position of the cursor. This is like getpos('.'), but
5786 includes an extra "curswant" item in the list:
5787 [0, lnum, col, off, curswant] ~
5788 The "curswant" number is the preferred column when moving the
5789 cursor vertically. Also see |getcursorcharpos()| and
5790 |getpos()|.
5791 The first "bufnum" item is always zero. The byte position of
5792 the cursor is returned in 'col'. To get the character
5793 position, use |getcursorcharpos()|.
5794
5795 The optional {winid} argument can specify the window. It can
5796 be the window number or the |window-ID|. The last known
5797 cursor position is returned, this may be invalid for the
5798 current value of the buffer if it is not the current window.
5799 If {winid} is invalid a list with zeroes is returned.
5800
5801 This can be used to save and restore the cursor position: >
5802 let save_cursor = getcurpos()
5803 MoveTheCursorAround
5804 call setpos('.', save_cursor)
5805 < Note that this only works within the window. See
5806 |winrestview()| for restoring more state.
5807
5808 Can also be used as a |method|: >
5809 GetWinid()->getcurpos()
5810 <
5811 *getcursorcharpos()*
5812 getcursorcharpos([{winid}])
5813 Same as |getcurpos()| but the column number in the returned
5814 List is a character index instead of a byte index.
5815
5816 Example:
5817 With the cursor on '보' in line 3 with text "여보세요": >
5818 getcursorcharpos() returns [0, 3, 2, 0, 3]
5819 getcurpos() returns [0, 3, 4, 0, 3]
5820 <
5821 Can also be used as a |method|: >
5822 GetWinid()->getcursorcharpos()
5823
5824 < *getcwd()*
5825 getcwd([{winnr} [, {tabnr}]])
5826 The result is a String, which is the name of the current
5827 working directory. 'autochdir' is ignored.
5828
5829 With {winnr} return the local current directory of this window
5830 in the current tab page. {winnr} can be the window number or
5831 the |window-ID|.
5832 If {winnr} is -1 return the name of the global working
5833 directory. See also |haslocaldir()|.
5834
5835 With {winnr} and {tabnr} return the local current directory of
5836 the window in the specified tab page. If {winnr} is -1 return
5837 the working directory of the tabpage.
5838 If {winnr} is zero use the current window, if {tabnr} is zero
5839 use the current tabpage.
5840 Without any arguments, return the actual working directory of
5841 the current window.
5842 Return an empty string if the arguments are invalid.
5843
5844 Examples: >
5845 " Get the working directory of the current window
5846 :echo getcwd()
5847 :echo getcwd(0)
5848 :echo getcwd(0, 0)
5849 " Get the working directory of window 3 in tabpage 2
5850 :echo getcwd(3, 2)
5851 " Get the global working directory
5852 :echo getcwd(-1)
5853 " Get the working directory of tabpage 3
5854 :echo getcwd(-1, 3)
5855 " Get the working directory of current tabpage
5856 :echo getcwd(-1, 0)
5857
5858 < Can also be used as a |method|: >
5859 GetWinnr()->getcwd()
5860
5861 getenv({name}) *getenv()*
5862 Return the value of environment variable {name}. The {name}
5863 argument is a string, without a leading '$'. Example: >
5864 myHome = getenv('HOME')
5865
5866 < When the variable does not exist |v:null| is returned. That
5867 is different from a variable set to an empty string, although
5868 some systems interpret the empty value as the variable being
5869 deleted. See also |expr-env|.
5870
5871 Can also be used as a |method|: >
5872 GetVarname()->getenv()
5873
5874 getfontname([{name}]) *getfontname()*
5875 Without an argument returns the name of the normal font being
5876 used. Like what is used for the Normal highlight group
5877 |hl-Normal|.
5878 With an argument a check is done whether String {name} is a
5879 valid font name. If not then an empty string is returned.
5880 Otherwise the actual font name is returned, or {name} if the
5881 GUI does not support obtaining the real name.
5882 Only works when the GUI is running, thus not in your vimrc or
5883 gvimrc file. Use the |GUIEnter| autocommand to use this
5884 function just after the GUI has started.
5885 Note that the GTK GUI accepts any font name, thus checking for
5886 a valid name does not work.
5887
5888 getfperm({fname}) *getfperm()*
5889 The result is a String, which is the read, write, and execute
5890 permissions of the given file {fname}.
5891 If {fname} does not exist or its directory cannot be read, an
5892 empty string is returned.
5893 The result is of the form "rwxrwxrwx", where each group of
5894 "rwx" flags represent, in turn, the permissions of the owner
5895 of the file, the group the file belongs to, and other users.
5896 If a user does not have a given permission the flag for this
5897 is replaced with the string "-". Examples: >
5898 :echo getfperm("/etc/passwd")
5899 :echo getfperm(expand("~/.vimrc"))
5900 < This will hopefully (from a security point of view) display
5901 the string "rw-r--r--" or even "rw-------".
5902
5903 Can also be used as a |method|: >
5904 GetFilename()->getfperm()
5905 <
5906 For setting permissions use |setfperm()|.
5907
5908 getfsize({fname}) *getfsize()*
5909 The result is a Number, which is the size in bytes of the
5910 given file {fname}.
5911 If {fname} is a directory, 0 is returned.
5912 If the file {fname} can't be found, -1 is returned.
5913 If the size of {fname} is too big to fit in a Number then -2
5914 is returned.
5915
5916 Can also be used as a |method|: >
5917 GetFilename()->getfsize()
5918
5919 getftime({fname}) *getftime()*
5920 The result is a Number, which is the last modification time of
5921 the given file {fname}. The value is measured as seconds
5922 since 1st Jan 1970, and may be passed to strftime(). See also
5923 |localtime()| and |strftime()|.
5924 If the file {fname} can't be found -1 is returned.
5925
5926 Can also be used as a |method|: >
5927 GetFilename()->getftime()
5928
5929 getftype({fname}) *getftype()*
5930 The result is a String, which is a description of the kind of
5931 file of the given file {fname}.
5932 If {fname} does not exist an empty string is returned.
5933 Here is a table over different kinds of files and their
5934 results:
5935 Normal file "file"
5936 Directory "dir"
5937 Symbolic link "link"
5938 Block device "bdev"
5939 Character device "cdev"
5940 Socket "socket"
5941 FIFO "fifo"
5942 All other "other"
5943 Example: >
5944 getftype("/home")
5945 < Note that a type such as "link" will only be returned on
5946 systems that support it. On some systems only "dir" and
5947 "file" are returned. On MS-Windows a symbolic link to a
5948 directory returns "dir" instead of "link".
5949
5950 Can also be used as a |method|: >
5951 GetFilename()->getftype()
5952
5953 getimstatus() *getimstatus()*
5954 The result is a Number, which is |TRUE| when the IME status is
5955 active.
5956 See 'imstatusfunc'.
5957
5958 getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
5959 Returns the |jumplist| for the specified window.
5960
5961 Without arguments use the current window.
5962 With {winnr} only use this window in the current tab page.
5963 {winnr} can also be a |window-ID|.
5964 With {winnr} and {tabnr} use the window in the specified tab
5965 page.
5966
5967 The returned list contains two entries: a list with the jump
5968 locations and the last used jump position number in the list.
5969 Each entry in the jump location list is a dictionary with
5970 the following entries:
5971 bufnr buffer number
5972 col column number
5973 coladd column offset for 'virtualedit'
5974 filename filename if available
5975 lnum line number
5976
5977 Can also be used as a |method|: >
5978 GetWinnr()->getjumplist()
5979
5980 < *getline()*
5981 getline({lnum} [, {end}])
5982 Without {end} the result is a String, which is line {lnum}
5983 from the current buffer. Example: >
5984 getline(1)
5985 < When {lnum} is a String that doesn't start with a
5986 digit, |line()| is called to translate the String into a Number.
5987 To get the line under the cursor: >
5988 getline(".")
5989 < When {lnum} is a number smaller than 1 or bigger than the
5990 number of lines in the buffer, an empty string is returned.
5991
5992 When {end} is given the result is a |List| where each item is
5993 a line from the current buffer in the range {lnum} to {end},
5994 including line {end}.
5995 {end} is used in the same way as {lnum}.
5996 Non-existing lines are silently omitted.
5997 When {end} is before {lnum} an empty |List| is returned.
5998 Example: >
5999 :let start = line('.')
6000 :let end = search("^$") - 1
6001 :let lines = getline(start, end)
6002
6003 < Can also be used as a |method|: >
6004 ComputeLnum()->getline()
6005
6006 < To get lines from another buffer see |getbufline()|
6007
6008 getloclist({nr} [, {what}]) *getloclist()*
6009 Returns a |List| with all the entries in the location list for
6010 window {nr}. {nr} can be the window number or the |window-ID|.
6011 When {nr} is zero the current window is used.
6012
6013 For a location list window, the displayed location list is
6014 returned. For an invalid window number {nr}, an empty list is
6015 returned. Otherwise, same as |getqflist()|.
6016
6017 If the optional {what} dictionary argument is supplied, then
6018 returns the items listed in {what} as a dictionary. Refer to
6019 |getqflist()| for the supported items in {what}.
6020
6021 In addition to the items supported by |getqflist()| in {what},
6022 the following item is supported by |getloclist()|:
6023
6024 filewinid id of the window used to display files
6025 from the location list. This field is
6026 applicable only when called from a
6027 location list window. See
6028 |location-list-file-window| for more
6029 details.
6030
6031 Returns a |Dictionary| with default values if there is no
6032 location list for the window {nr}.
6033 Returns an empty Dictionary if window {nr} does not exist.
6034
6035 Examples (See also |getqflist-examples|): >
6036 :echo getloclist(3, {'all': 0})
6037 :echo getloclist(5, {'filewinid': 0})
6038
6039
6040 getmarklist([{buf}]) *getmarklist()*
6041 Without the {buf} argument returns a |List| with information
6042 about all the global marks. |mark|
6043
6044 If the optional {buf} argument is specified, returns the
6045 local marks defined in buffer {buf}. For the use of {buf},
6046 see |bufname()|.
6047
6048 Each item in the returned List is a |Dict| with the following:
6049 mark name of the mark prefixed by "'"
6050 pos a |List| with the position of the mark:
6051 [bufnum, lnum, col, off]
6052 Refer to |getpos()| for more information.
6053 file file name
6054
6055 Refer to |getpos()| for getting information about a specific
6056 mark.
6057
6058 Can also be used as a |method|: >
6059 GetBufnr()->getmarklist()
6060
6061 getmatches([{win}]) *getmatches()*
6062 Returns a |List| with all matches previously defined for the
6063 current window by |matchadd()| and the |:match| commands.
6064 |getmatches()| is useful in combination with |setmatches()|,
6065 as |setmatches()| can restore a list of matches saved by
6066 |getmatches()|.
6067 If {win} is specified, use the window with this number or
6068 window ID instead of the current window.
6069 Example: >
6070 :echo getmatches()
6071 < [{'group': 'MyGroup1', 'pattern': 'TODO',
6072 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
6073 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
6074 :let m = getmatches()
6075 :call clearmatches()
6076 :echo getmatches()
6077 < [] >
6078 :call setmatches(m)
6079 :echo getmatches()
6080 < [{'group': 'MyGroup1', 'pattern': 'TODO',
6081 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
6082 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
6083 :unlet m
6084 <
6085 getmousepos() *getmousepos()*
6086 Returns a |Dictionary| with the last known position of the
6087 mouse. This can be used in a mapping for a mouse click or in
6088 a filter of a popup window. The items are:
6089 screenrow screen row
6090 screencol screen column
6091 winid Window ID of the click
6092 winrow row inside "winid"
6093 wincol column inside "winid"
6094 line text line inside "winid"
6095 column text column inside "winid"
6096 All numbers are 1-based.
6097
6098 If not over a window, e.g. when in the command line, then only
6099 "screenrow" and "screencol" are valid, the others are zero.
6100
6101 When on the status line below a window or the vertical
6102 separator right of a window, the "line" and "column" values
6103 are zero.
6104
6105 When the position is after the text then "column" is the
6106 length of the text in bytes plus one.
6107
6108 If the mouse is over a popup window then that window is used.
6109
6110 When using |getchar()| the Vim variables |v:mouse_lnum|,
6111 |v:mouse_col| and |v:mouse_winid| also provide these values.
6112
6113 *getpid()*
6114 getpid() Return a Number which is the process ID of the Vim process.
6115 On Unix and MS-Windows this is a unique number, until Vim
6116 exits.
6117
6118 *getpos()*
6119 getpos({expr}) Get the position for String {expr}. For possible values of
6120 {expr} see |line()|. For getting the cursor position see
6121 |getcurpos()|.
6122 The result is a |List| with four numbers:
6123 [bufnum, lnum, col, off]
6124 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
6125 is the buffer number of the mark.
6126 "lnum" and "col" are the position in the buffer. The first
6127 column is 1.
6128 The "off" number is zero, unless 'virtualedit' is used. Then
6129 it is the offset in screen columns from the start of the
6130 character. E.g., a position within a <Tab> or after the last
6131 character.
6132 Note that for '< and '> Visual mode matters: when it is "V"
6133 (visual line mode) the column of '< is zero and the column of
6134 '> is a large number.
6135 The column number in the returned List is the byte position
6136 within the line. To get the character position in the line,
6137 use |getcharpos()|.
6138 The column number can be very large, e.g. 2147483647, in which
6139 case it means "after the end of the line".
6140 This can be used to save and restore the position of a mark: >
6141 let save_a_mark = getpos("'a")
6142 ...
6143 call setpos("'a", save_a_mark)
6144 < Also see |getcharpos()|, |getcurpos()| and |setpos()|.
6145
6146 Can also be used as a |method|: >
6147 GetMark()->getpos()
6148
6149 getqflist([{what}]) *getqflist()*
6150 Returns a |List| with all the current quickfix errors. Each
6151 list item is a dictionary with these entries:
6152 bufnr number of buffer that has the file name, use
6153 bufname() to get the name
6154 module module name
6155 lnum line number in the buffer (first line is 1)
6156 end_lnum
6157 end of line number if the item is multiline
6158 col column number (first column is 1)
6159 end_col end of column number if the item has range
6160 vcol |TRUE|: "col" is visual column
6161 |FALSE|: "col" is byte index
6162 nr error number
6163 pattern search pattern used to locate the error
6164 text description of the error
6165 type type of the error, 'E', '1', etc.
6166 valid |TRUE|: recognized error message
6167
6168 When there is no error list or it's empty, an empty list is
6169 returned. Quickfix list entries with a non-existing buffer
6170 number are returned with "bufnr" set to zero (Note: some
6171 functions accept buffer number zero for the alternate buffer,
6172 you may need to explicitly check for zero).
6173
6174 Useful application: Find pattern matches in multiple files and
6175 do something with them: >
6176 :vimgrep /theword/jg *.c
6177 :for d in getqflist()
6178 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
6179 :endfor
6180 <
6181 If the optional {what} dictionary argument is supplied, then
6182 returns only the items listed in {what} as a dictionary. The
6183 following string items are supported in {what}:
6184 changedtick get the total number of changes made
6185 to the list |quickfix-changedtick|
6186 context get the |quickfix-context|
6187 efm errorformat to use when parsing "lines". If
6188 not present, then the 'errorformat' option
6189 value is used.
6190 id get information for the quickfix list with
6191 |quickfix-ID|; zero means the id for the
6192 current list or the list specified by "nr"
6193 idx get information for the quickfix entry at this
6194 index in the list specified by 'id' or 'nr'.
6195 If set to zero, then uses the current entry.
6196 See |quickfix-index|
6197 items quickfix list entries
6198 lines parse a list of lines using 'efm' and return
6199 the resulting entries. Only a |List| type is
6200 accepted. The current quickfix list is not
6201 modified. See |quickfix-parse|.
6202 nr get information for this quickfix list; zero
6203 means the current quickfix list and "$" means
6204 the last quickfix list
6205 qfbufnr number of the buffer displayed in the quickfix
6206 window. Returns 0 if the quickfix buffer is
6207 not present. See |quickfix-buffer|.
6208 size number of entries in the quickfix list
6209 title get the list title |quickfix-title|
6210 winid get the quickfix |window-ID|
6211 all all of the above quickfix properties
6212 Non-string items in {what} are ignored. To get the value of a
6213 particular item, set it to zero.
6214 If "nr" is not present then the current quickfix list is used.
6215 If both "nr" and a non-zero "id" are specified, then the list
6216 specified by "id" is used.
6217 To get the number of lists in the quickfix stack, set "nr" to
6218 "$" in {what}. The "nr" value in the returned dictionary
6219 contains the quickfix stack size.
6220 When "lines" is specified, all the other items except "efm"
6221 are ignored. The returned dictionary contains the entry
6222 "items" with the list of entries.
6223
6224 The returned dictionary contains the following entries:
6225 changedtick total number of changes made to the
6226 list |quickfix-changedtick|
6227 context quickfix list context. See |quickfix-context|
6228 If not present, set to "".
6229 id quickfix list ID |quickfix-ID|. If not
6230 present, set to 0.
6231 idx index of the quickfix entry in the list. If not
6232 present, set to 0.
6233 items quickfix list entries. If not present, set to
6234 an empty list.
6235 nr quickfix list number. If not present, set to 0
6236 qfbufnr number of the buffer displayed in the quickfix
6237 window. If not present, set to 0.
6238 size number of entries in the quickfix list. If not
6239 present, set to 0.
6240 title quickfix list title text. If not present, set
6241 to "".
6242 winid quickfix |window-ID|. If not present, set to 0
6243
6244 Examples (See also |getqflist-examples|): >
6245 :echo getqflist({'all': 1})
6246 :echo getqflist({'nr': 2, 'title': 1})
6247 :echo getqflist({'lines' : ["F1:10:L10"]})
6248 <
6249 getreg([{regname} [, 1 [, {list}]]]) *getreg()*
6250 The result is a String, which is the contents of register
6251 {regname}. Example: >
6252 :let cliptext = getreg('*')
6253 < When register {regname} was not set the result is an empty
6254 string.
6255 The {regname} argument must be a string.
6256
6257 getreg('=') returns the last evaluated value of the expression
6258 register. (For use in maps.)
6259 getreg('=', 1) returns the expression itself, so that it can
6260 be restored with |setreg()|. For other registers the extra
6261 argument is ignored, thus you can always give it.
6262
6263 If {list} is present and |TRUE|, the result type is changed
6264 to |List|. Each list item is one text line. Use it if you care
6265 about zero bytes possibly present inside register: without
6266 third argument both NLs and zero bytes are represented as NLs
6267 (see |NL-used-for-Nul|).
6268 When the register was not set an empty list is returned.
6269
6270 If {regname} is "", the unnamed register '"' is used.
6271 If {regname} is not specified, |v:register| is used.
6272 In |Vim9-script| {regname} must be one character.
6273
6274 Can also be used as a |method|: >
6275 GetRegname()->getreg()
6276
6277 getreginfo([{regname}]) *getreginfo()*
6278 Returns detailed information about register {regname} as a
6279 Dictionary with the following entries:
6280 regcontents List of lines contained in register
6281 {regname}, like
6282 |getreg|({regname}, 1, 1).
6283 regtype the type of register {regname}, as in
6284 |getregtype()|.
6285 isunnamed Boolean flag, v:true if this register
6286 is currently pointed to by the unnamed
6287 register.
6288 points_to for the unnamed register, gives the
6289 single letter name of the register
6290 currently pointed to (see |quotequote|).
6291 For example, after deleting a line
6292 with `dd`, this field will be "1",
6293 which is the register that got the
6294 deleted text.
6295
6296 The {regname} argument is a string. If {regname} is invalid
6297 or not set, an empty Dictionary will be returned.
6298 If {regname} is "" or "@", the unnamed register '"' is used.
6299 If {regname} is not specified, |v:register| is used.
6300 The returned Dictionary can be passed to |setreg()|.
6301 In |Vim9-script| {regname} must be one character.
6302
6303 Can also be used as a |method|: >
6304 GetRegname()->getreginfo()
6305
6306 getregtype([{regname}]) *getregtype()*
6307 The result is a String, which is type of register {regname}.
6308 The value will be one of:
6309 "v" for |characterwise| text
6310 "V" for |linewise| text
6311 "<CTRL-V>{width}" for |blockwise-visual| text
6312 "" for an empty or unknown register
6313 <CTRL-V> is one character with value 0x16.
6314 The {regname} argument is a string. If {regname} is "", the
6315 unnamed register '"' is used. If {regname} is not specified,
6316 |v:register| is used.
6317 In |Vim9-script| {regname} must be one character.
6318
6319 Can also be used as a |method|: >
6320 GetRegname()->getregtype()
6321
6322 gettabinfo([{tabnr}]) *gettabinfo()*
6323 If {tabnr} is not specified, then information about all the
6324 tab pages is returned as a |List|. Each List item is a
6325 |Dictionary|. Otherwise, {tabnr} specifies the tab page
6326 number and information about that one is returned. If the tab
6327 page does not exist an empty List is returned.
6328
6329 Each List item is a |Dictionary| with the following entries:
6330 tabnr tab page number.
6331 variables a reference to the dictionary with
6332 tabpage-local variables
6333 windows List of |window-ID|s in the tab page.
6334
6335 Can also be used as a |method|: >
6336 GetTabnr()->gettabinfo()
6337
6338 gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
6339 Get the value of a tab-local variable {varname} in tab page
6340 {tabnr}. |t:var|
6341 Tabs are numbered starting with one.
6342 The {varname} argument is a string. When {varname} is empty a
6343 dictionary with all tab-local variables is returned.
6344 Note that the name without "t:" must be used.
6345 When the tab or variable doesn't exist {def} or an empty
6346 string is returned, there is no error message.
6347
6348 Can also be used as a |method|: >
6349 GetTabnr()->gettabvar(varname)
6350
6351 gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
6352 Get the value of window-local variable {varname} in window
6353 {winnr} in tab page {tabnr}.
6354 The {varname} argument is a string. When {varname} is empty a
6355 dictionary with all window-local variables is returned.
6356 When {varname} is equal to "&" get the values of all
6357 window-local options in a |Dictionary|.
6358 Otherwise, when {varname} starts with "&" get the value of a
6359 window-local option.
6360 Note that {varname} must be the name without "w:".
6361 Tabs are numbered starting with one. For the current tabpage
6362 use |getwinvar()|.
6363 {winnr} can be the window number or the |window-ID|.
6364 When {winnr} is zero the current window is used.
6365 This also works for a global option, buffer-local option and
6366 window-local option, but it doesn't work for a global variable
6367 or buffer-local variable.
6368 When the tab, window or variable doesn't exist {def} or an
6369 empty string is returned, there is no error message.
6370 Examples: >
6371 :let list_is_on = gettabwinvar(1, 2, '&list')
6372 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
6373 <
6374 To obtain all window-local variables use: >
6375 gettabwinvar({tabnr}, {winnr}, '&')
6376
6377 < Can also be used as a |method|: >
6378 GetTabnr()->gettabwinvar(winnr, varname)
6379
6380 gettagstack([{winnr}]) *gettagstack()*
6381 The result is a Dict, which is the tag stack of window {winnr}.
6382 {winnr} can be the window number or the |window-ID|.
6383 When {winnr} is not specified, the current window is used.
6384 When window {winnr} doesn't exist, an empty Dict is returned.
6385
6386 The returned dictionary contains the following entries:
6387 curidx Current index in the stack. When at
6388 top of the stack, set to (length + 1).
6389 Index of bottom of the stack is 1.
6390 items List of items in the stack. Each item
6391 is a dictionary containing the
6392 entries described below.
6393 length Number of entries in the stack.
6394
6395 Each item in the stack is a dictionary with the following
6396 entries:
6397 bufnr buffer number of the current jump
6398 from cursor position before the tag jump.
6399 See |getpos()| for the format of the
6400 returned list.
6401 matchnr current matching tag number. Used when
6402 multiple matching tags are found for a
6403 name.
6404 tagname name of the tag
6405
6406 See |tagstack| for more information about the tag stack.
6407
6408 Can also be used as a |method|: >
6409 GetWinnr()->gettagstack()
6410
6411
6412 gettext({text}) *gettext()*
6413 Translate String {text} if possible.
6414 This is mainly for use in the distributed Vim scripts. When
6415 generating message translations the {text} is extracted by
6416 xgettext, the translator can add the translated message in the
6417 .po file and Vim will lookup the translation when gettext() is
6418 called.
6419 For {text} double quoted strings are preferred, because
6420 xgettext does not understand escaping in single quoted
6421 strings.
6422
6423
6424 getwininfo([{winid}]) *getwininfo()*
6425 Returns information about windows as a |List| with Dictionaries.
6426
6427 If {winid} is given Information about the window with that ID
6428 is returned, as a |List| with one item. If the window does not
6429 exist the result is an empty list.
6430
6431 Without {winid} information about all the windows in all the
6432 tab pages is returned.
6433
6434 Each List item is a |Dictionary| with the following entries:
6435 botline last complete displayed buffer line
6436 bufnr number of buffer in the window
6437 height window height (excluding winbar)
6438 loclist 1 if showing a location list
6439 {only with the +quickfix feature}
6440 quickfix 1 if quickfix or location list window
6441 {only with the +quickfix feature}
6442 terminal 1 if a terminal window
6443 {only with the +terminal feature}
6444 tabnr tab page number
6445 topline first displayed buffer line
6446 variables a reference to the dictionary with
6447 window-local variables
6448 width window width
6449 winbar 1 if the window has a toolbar, 0
6450 otherwise
6451 wincol leftmost screen column of the window;
6452 "col" from |win_screenpos()|
6453 textoff number of columns occupied by any
6454 'foldcolumn', 'signcolumn' and line
6455 number in front of the text
6456 winid |window-ID|
6457 winnr window number
6458 winrow topmost screen line of the window;
6459 "row" from |win_screenpos()|
6460
6461 Can also be used as a |method|: >
6462 GetWinnr()->getwininfo()
6463
6464 getwinpos([{timeout}]) *getwinpos()*
6465 The result is a |List| with two numbers, the result of
6466 |getwinposx()| and |getwinposy()| combined:
6467 [x-pos, y-pos]
6468 {timeout} can be used to specify how long to wait in msec for
6469 a response from the terminal. When omitted 100 msec is used.
6470 Use a longer time for a remote terminal.
6471 When using a value less than 10 and no response is received
6472 within that time, a previously reported position is returned,
6473 if available. This can be used to poll for the position and
6474 do some work in the meantime: >
6475 while 1
6476 let res = getwinpos(1)
6477 if res[0] >= 0
6478 break
6479 endif
6480 " Do some work here
6481 endwhile
6482 <
6483
6484 Can also be used as a |method|: >
6485 GetTimeout()->getwinpos()
6486 <
6487 *getwinposx()*
6488 getwinposx() The result is a Number, which is the X coordinate in pixels of
6489 the left hand side of the GUI Vim window. Also works for an
6490 xterm (uses a timeout of 100 msec).
6491 The result will be -1 if the information is not available.
6492 The value can be used with `:winpos`.
6493
6494 *getwinposy()*
6495 getwinposy() The result is a Number, which is the Y coordinate in pixels of
6496 the top of the GUI Vim window. Also works for an xterm (uses
6497 a timeout of 100 msec).
6498 The result will be -1 if the information is not available.
6499 The value can be used with `:winpos`.
6500
6501 getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
6502 Like |gettabwinvar()| for the current tabpage.
6503 Examples: >
6504 :let list_is_on = getwinvar(2, '&list')
6505 :echo "myvar = " . getwinvar(1, 'myvar')
6506
6507 < Can also be used as a |method|: >
6508 GetWinnr()->getwinvar(varname)
6509 <
6510 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
6511 Expand the file wildcards in {expr}. See |wildcards| for the
6512 use of special characters.
6513
6514 Unless the optional {nosuf} argument is given and is |TRUE|,
6515 the 'suffixes' and 'wildignore' options apply: Names matching
6516 one of the patterns in 'wildignore' will be skipped and
6517 'suffixes' affect the ordering of matches.
6518 'wildignorecase' always applies.
6519
6520 When {list} is present and it is |TRUE| the result is a |List|
6521 with all matching files. The advantage of using a List is,
6522 you also get filenames containing newlines correctly.
6523 Otherwise the result is a String and when there are several
6524 matches, they are separated by <NL> characters.
6525
6526 If the expansion fails, the result is an empty String or List.
6527
6528 You can also use |readdir()| if you need to do complicated
6529 things, such as limiting the number of matches.
6530
6531 A name for a non-existing file is not included. A symbolic
6532 link is only included if it points to an existing file.
6533 However, when the {alllinks} argument is present and it is
6534 |TRUE| then all symbolic links are included.
6535
6536 For most systems backticks can be used to get files names from
6537 any external command. Example: >
6538 :let tagfiles = glob("`find . -name tags -print`")
6539 :let &tags = substitute(tagfiles, "\n", ",", "g")
6540 < The result of the program inside the backticks should be one
6541 item per line. Spaces inside an item are allowed.
6542
6543 See |expand()| for expanding special Vim variables. See
6544 |system()| for getting the raw output of an external command.
6545
6546 Can also be used as a |method|: >
6547 GetExpr()->glob()
6548
6549 glob2regpat({string}) *glob2regpat()*
6550 Convert a file pattern, as used by glob(), into a search
6551 pattern. The result can be used to match with a string that
6552 is a file name. E.g. >
6553 if filename =~ glob2regpat('Make*.mak')
6554 < This is equivalent to: >
6555 if filename =~ '^Make.*\.mak$'
6556 < When {string} is an empty string the result is "^$", match an
6557 empty string.
6558 Note that the result depends on the system. On MS-Windows
6559 a backslash usually means a path separator.
6560
6561 Can also be used as a |method|: >
6562 GetExpr()->glob2regpat()
6563 < *globpath()*
6564 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
6565 Perform glob() for String {expr} on all directories in {path}
6566 and concatenate the results. Example: >
6567 :echo globpath(&rtp, "syntax/c.vim")
6568 <
6569 {path} is a comma-separated list of directory names. Each
6570 directory name is prepended to {expr} and expanded like with
6571 |glob()|. A path separator is inserted when needed.
6572 To add a comma inside a directory name escape it with a
6573 backslash. Note that on MS-Windows a directory may have a
6574 trailing backslash, remove it if you put a comma after it.
6575 If the expansion fails for one of the directories, there is no
6576 error message.
6577
6578 Unless the optional {nosuf} argument is given and is |TRUE|,
6579 the 'suffixes' and 'wildignore' options apply: Names matching
6580 one of the patterns in 'wildignore' will be skipped and
6581 'suffixes' affect the ordering of matches.
6582
6583 When {list} is present and it is |TRUE| the result is a |List|
6584 with all matching files. The advantage of using a List is, you
6585 also get filenames containing newlines correctly. Otherwise
6586 the result is a String and when there are several matches,
6587 they are separated by <NL> characters. Example: >
6588 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
6589 <
6590 {alllinks} is used as with |glob()|.
6591
6592 The "**" item can be used to search in a directory tree.
6593 For example, to find all "README.txt" files in the directories
6594 in 'runtimepath' and below: >
6595 :echo globpath(&rtp, "**/README.txt")
6596 < Upwards search and limiting the depth of "**" is not
6597 supported, thus using 'path' will not always work properly.
6598
6599 Can also be used as a |method|, the base is passed as the
6600 second argument: >
6601 GetExpr()->globpath(&rtp)
6602 <
6603 *has()*
6604 has({feature} [, {check}])
6605 When {check} is omitted or is zero: The result is a Number,
6606 which is 1 if the feature {feature} is supported, zero
6607 otherwise. The {feature} argument is a string, case is
6608 ignored. See |feature-list| below.
6609
6610 When {check} is present and not zero: The result is a Number,
6611 which is 1 if the feature {feature} could ever be supported,
6612 zero otherwise. This is useful to check for a typo in
6613 {feature} and to detect dead code. Keep in mind that an older
6614 Vim version will not know about a feature added later and
6615 features that have been abandoned will not be known by the
6616 current Vim version.
6617
6618 Also see |exists()| and |exists_compiled()|.
6619
6620 Note that to skip code that has a syntax error when the
6621 feature is not available, Vim may skip the rest of the line
6622 and miss a following `endif`. Therefore put the `endif` on a
6623 separate line: >
6624 if has('feature')
6625 let x = this->breaks->without->the->feature
6626 endif
6627 < If the `endif` would be moved to the second line as "| endif" it
6628 would not be found.
6629
6630
6631 has_key({dict}, {key}) *has_key()*
6632 The result is a Number, which is TRUE if |Dictionary| {dict}
6633 has an entry with key {key}. FALSE otherwise. The {key}
6634 argument is a string.
6635
6636 Can also be used as a |method|: >
6637 mydict->has_key(key)
6638
6639 haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
6640 The result is a Number:
6641 1 when the window has set a local directory via |:lcd|
6642 2 when the tab-page has set a local directory via |:tcd|
6643 0 otherwise.
6644
6645 Without arguments use the current window.
6646 With {winnr} use this window in the current tab page.
6647 With {winnr} and {tabnr} use the window in the specified tab
6648 page.
6649 {winnr} can be the window number or the |window-ID|.
6650 If {winnr} is -1 it is ignored and only the tabpage is used.
6651 Return 0 if the arguments are invalid.
6652 Examples: >
6653 if haslocaldir() == 1
6654 " window local directory case
6655 elseif haslocaldir() == 2
6656 " tab-local directory case
6657 else
6658 " global directory case
6659 endif
6660
6661 " current window
6662 :echo haslocaldir()
6663 :echo haslocaldir(0)
6664 :echo haslocaldir(0, 0)
6665 " window n in current tab page
6666 :echo haslocaldir(n)
6667 :echo haslocaldir(n, 0)
6668 " window n in tab page m
6669 :echo haslocaldir(n, m)
6670 " tab page m
6671 :echo haslocaldir(-1, m)
6672 <
6673 Can also be used as a |method|: >
6674 GetWinnr()->haslocaldir()
6675
6676 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
6677 The result is a Number, which is TRUE if there is a mapping
6678 that contains {what} in somewhere in the rhs (what it is
6679 mapped to) and this mapping exists in one of the modes
6680 indicated by {mode}.
6681 The arguments {what} and {mode} are strings.
6682 When {abbr} is there and it is |TRUE| use abbreviations
6683 instead of mappings. Don't forget to specify Insert and/or
6684 Command-line mode.
6685 Both the global mappings and the mappings local to the current
6686 buffer are checked for a match.
6687 If no matching mapping is found FALSE is returned.
6688 The following characters are recognized in {mode}:
6689 n Normal mode
6690 v Visual and Select mode
6691 x Visual mode
6692 s Select mode
6693 o Operator-pending mode
6694 i Insert mode
6695 l Language-Argument ("r", "f", "t", etc.)
6696 c Command-line mode
6697 When {mode} is omitted, "nvo" is used.
6698
6699 This function is useful to check if a mapping already exists
6700 to a function in a Vim script. Example: >
6701 :if !hasmapto('\ABCdoit')
6702 : map <Leader>d \ABCdoit
6703 :endif
6704 < This installs the mapping to "\ABCdoit" only if there isn't
6705 already a mapping to "\ABCdoit".
6706
6707 Can also be used as a |method|: >
6708 GetRHS()->hasmapto()
6709
6710 histadd({history}, {item}) *histadd()*
6711 Add the String {item} to the history {history} which can be
6712 one of: *hist-names*
6713 "cmd" or ":" command line history
6714 "search" or "/" search pattern history
6715 "expr" or "=" typed expression history
6716 "input" or "@" input line history
6717 "debug" or ">" debug command history
6718 empty the current or last used history
6719 The {history} string does not need to be the whole name, one
6720 character is sufficient.
6721 If {item} does already exist in the history, it will be
6722 shifted to become the newest entry.
6723 The result is a Number: TRUE if the operation was successful,
6724 otherwise FALSE is returned.
6725
6726 Example: >
6727 :call histadd("input", strftime("%Y %b %d"))
6728 :let date=input("Enter date: ")
6729 < This function is not available in the |sandbox|.
6730
6731 Can also be used as a |method|, the base is passed as the
6732 second argument: >
6733 GetHistory()->histadd('search')
6734
6735 histdel({history} [, {item}]) *histdel()*
6736 Clear {history}, i.e. delete all its entries. See |hist-names|
6737 for the possible values of {history}.
6738
6739 If the parameter {item} evaluates to a String, it is used as a
6740 regular expression. All entries matching that expression will
6741 be removed from the history (if there are any).
6742 Upper/lowercase must match, unless "\c" is used |/\c|.
6743 If {item} evaluates to a Number, it will be interpreted as
6744 an index, see |:history-indexing|. The respective entry will
6745 be removed if it exists.
6746
6747 The result is TRUE for a successful operation, otherwise FALSE
6748 is returned.
6749
6750 Examples:
6751 Clear expression register history: >
6752 :call histdel("expr")
6753 <
6754 Remove all entries starting with "*" from the search history: >
6755 :call histdel("/", '^\*')
6756 <
6757 The following three are equivalent: >
6758 :call histdel("search", histnr("search"))
6759 :call histdel("search", -1)
6760 :call histdel("search", '^'.histget("search", -1).'$')
6761 <
6762 To delete the last search pattern and use the last-but-one for
6763 the "n" command and 'hlsearch': >
6764 :call histdel("search", -1)
6765 :let @/ = histget("search", -1)
6766 <
6767 Can also be used as a |method|: >
6768 GetHistory()->histdel()
6769
6770 histget({history} [, {index}]) *histget()*
6771 The result is a String, the entry with Number {index} from
6772 {history}. See |hist-names| for the possible values of
6773 {history}, and |:history-indexing| for {index}. If there is
6774 no such entry, an empty String is returned. When {index} is
6775 omitted, the most recent item from the history is used.
6776
6777 Examples:
6778 Redo the second last search from history. >
6779 :execute '/' . histget("search", -2)
6780
6781 < Define an Ex command ":H {num}" that supports re-execution of
6782 the {num}th entry from the output of |:history|. >
6783 :command -nargs=1 H execute histget("cmd", 0+<args>)
6784 <
6785 Can also be used as a |method|: >
6786 GetHistory()->histget()
6787
6788 histnr({history}) *histnr()*
6789 The result is the Number of the current entry in {history}.
6790 See |hist-names| for the possible values of {history}.
6791 If an error occurred, -1 is returned.
6792
6793 Example: >
6794 :let inp_index = histnr("expr")
6795
6796 < Can also be used as a |method|: >
6797 GetHistory()->histnr()
6798 <
6799 hlexists({name}) *hlexists()*
6800 The result is a Number, which is TRUE if a highlight group
6801 called {name} exists. This is when the group has been
6802 defined in some way. Not necessarily when highlighting has
6803 been defined for it, it may also have been used for a syntax
6804 item.
6805 *highlight_exists()*
6806 Obsolete name: highlight_exists().
6807
6808 Can also be used as a |method|: >
6809 GetName()->hlexists()
6810 <
6811 hlget([{name} [, {resolve}]]) *hlget()*
6812 Returns a List of all the highlight group attributes. If the
6813 optional {name} is specified, then returns a List with only
6814 the attributes of the specified highlight group. Returns an
6815 empty List if the highlight group {name} is not present.
6816
6817 If the optional {resolve} argument is set to v:true and the
6818 highlight group {name} is linked to another group, then the
6819 link is resolved recursively and the attributes of the
6820 resolved highlight group are returned.
6821
6822 Each entry in the returned List is a Dictionary with the
6823 following items:
6824 cleared boolean flag, set to v:true if the highlight
6825 group attributes are cleared or not yet
6826 specified. See |highlight-clear|.
6827 cterm cterm attributes. See |highlight-cterm|.
6828 ctermbg cterm background color.
6829 See |highlight-ctermbg|.
6830 ctermfg cterm foreground color.
6831 See |highlight-ctermfg|.
6832 ctermul cterm underline color. See |highlight-ctermul|.
6833 default boolean flag, set to v:true if the highlight
6834 group link is a default link. See
6835 |highlight-default|.
6836 font highlight group font. See |highlight-font|.
6837 gui gui attributes. See |highlight-gui|.
6838 guibg gui background color. See |highlight-guibg|.
6839 guifg gui foreground color. See |highlight-guifg|.
6840 guisp gui special color. See |highlight-guisp|.
6841 id highlight group ID.
6842 linksto linked highlight group name.
6843 See |:highlight-link|.
6844 name highlight group name. See |group-name|.
6845 start start terminal keycode. See |highlight-start|.
6846 stop stop terminal keycode. See |highlight-stop|.
6847 term term attributes. See |highlight-term|.
6848
6849 The 'term', 'cterm' and 'gui' items in the above Dictionary
6850 have a dictionary value with the following optional boolean
6851 items: 'bold', 'standout', 'underline', 'undercurl', 'italic',
6852 'reverse', 'inverse' and 'strikethrough'.
6853
6854 Example(s): >
6855 :echo hlget()
6856 :echo hlget('ModeMsg')
6857 :echo hlget('Number', v:true)
6858 <
6859 Can also be used as a |method|: >
6860 GetName()->hlget()
6861 <
6862 hlset({list}) *hlset()*
6863 Creates or modifies the attributes of a List of highlight
6864 groups. Each item in {list} is a dictionary containing the
6865 attributes of a highlight group. See |hlget()| for the list of
6866 supported items in this dictionary.
6867
6868 In addition to the items described in |hlget()|, the following
6869 additional items are supported in the dictionary:
6870
6871 force boolean flag to force the creation of
6872 a link for an existing highlight group
6873 with attributes.
6874
6875 The highlight group is identified using the 'name' item and
6876 the 'id' item (if supplied) is ignored. If a highlight group
6877 with a specified name doesn't exist, then it is created.
6878 Otherwise the attributes of an existing highlight group are
6879 modified.
6880
6881 If an empty dictionary value is used for the 'term' or 'cterm'
6882 or 'gui' entries, then the corresponding attributes are
6883 cleared. If the 'cleared' item is set to v:true, then all the
6884 attributes of the highlight group are cleared.
6885
6886 The 'linksto' item can be used to link a highlight group to
6887 another highlight group. See |:highlight-link|.
6888
6889 Returns zero for success, -1 for failure.
6890
6891 Example(s): >
6892 " add bold attribute to the Visual highlight group
6893 :call hlset([#{name: 'Visual',
6894 \ term: #{reverse: 1 , bold: 1}}])
6895 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}])
6896 :let l = hlget()
6897 :call hlset(l)
6898 " clear the Search highlight group
6899 :call hlset([#{name: 'Search', cleared: v:true}])
6900 " clear the 'term' attributes for a highlight group
6901 :call hlset([#{name: 'Title', term: {}}])
6902 " create the MyHlg group linking it to DiffAdd
6903 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}])
6904 " remove the MyHlg group link
6905 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}])
6906 " clear the attributes and a link
6907 :call hlset([#{name: 'MyHlg', cleared: v:true,
6908 \ linksto: 'NONE'}])
6909 <
6910 Can also be used as a |method|: >
6911 GetAttrList()->hlset()
6912 <
6913 *hlID()*
6914 hlID({name}) The result is a Number, which is the ID of the highlight group
6915 with name {name}. When the highlight group doesn't exist,
6916 zero is returned.
6917 This can be used to retrieve information about the highlight
6918 group. For example, to get the background color of the
6919 "Comment" group: >
6920 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
6921 < *highlightID()*
6922 Obsolete name: highlightID().
6923
6924 Can also be used as a |method|: >
6925 GetName()->hlID()
6926
6927 hostname() *hostname()*
6928 The result is a String, which is the name of the machine on
6929 which Vim is currently running. Machine names greater than
6930 256 characters long are truncated.
6931
6932 iconv({string}, {from}, {to}) *iconv()*
6933 The result is a String, which is the text {string} converted
6934 from encoding {from} to encoding {to}.
6935 When the conversion completely fails an empty string is
6936 returned. When some characters could not be converted they
6937 are replaced with "?".
6938 The encoding names are whatever the iconv() library function
6939 can accept, see ":!man 3 iconv".
6940 Most conversions require Vim to be compiled with the |+iconv|
6941 feature. Otherwise only UTF-8 to latin1 conversion and back
6942 can be done.
6943 This can be used to display messages with special characters,
6944 no matter what 'encoding' is set to. Write the message in
6945 UTF-8 and use: >
6946 echo iconv(utf8_str, "utf-8", &enc)
6947 < Note that Vim uses UTF-8 for all Unicode encodings, conversion
6948 from/to UCS-2 is automatically changed to use UTF-8. You
6949 cannot use UCS-2 in a string anyway, because of the NUL bytes.
6950
6951 Can also be used as a |method|: >
6952 GetText()->iconv('latin1', 'utf-8')
6953 <
6954 *indent()*
6955 indent({lnum}) The result is a Number, which is indent of line {lnum} in the
6956 current buffer. The indent is counted in spaces, the value
6957 of 'tabstop' is relevant. {lnum} is used just like in
6958 |getline()|.
6959 When {lnum} is invalid -1 is returned.
6960
6961 Can also be used as a |method|: >
6962 GetLnum()->indent()
6963
6964 index({object}, {expr} [, {start} [, {ic}]]) *index()*
6965 If {object} is a |List| return the lowest index where the item
6966 has a value equal to {expr}. There is no automatic
6967 conversion, so the String "4" is different from the Number 4.
6968 And the number 4 is different from the Float 4.0. The value
6969 of 'ignorecase' is not used here, case always matters.
6970
6971 If {object} is |Blob| return the lowest index where the byte
6972 value is equal to {expr}.
6973
6974 If {start} is given then start looking at the item with index
6975 {start} (may be negative for an item relative to the end).
6976 When {ic} is given and it is |TRUE|, ignore case. Otherwise
6977 case must match.
6978 -1 is returned when {expr} is not found in {object}.
6979 Example: >
6980 :let idx = index(words, "the")
6981 :if index(numbers, 123) >= 0
6982
6983 < Can also be used as a |method|: >
6984 GetObject()->index(what)
6985
6986 input({prompt} [, {text} [, {completion}]]) *input()*
6987 The result is a String, which is whatever the user typed on
6988 the command-line. The {prompt} argument is either a prompt
6989 string, or a blank string (for no prompt). A '\n' can be used
6990 in the prompt to start a new line.
6991 The highlighting set with |:echohl| is used for the prompt.
6992 The input is entered just like a command-line, with the same
6993 editing commands and mappings. There is a separate history
6994 for lines typed for input().
6995 Example: >
6996 :if input("Coffee or beer? ") == "beer"
6997 : echo "Cheers!"
6998 :endif
6999 <
7000 If the optional {text} argument is present and not empty, this
7001 is used for the default reply, as if the user typed this.
7002 Example: >
7003 :let color = input("Color? ", "white")
7004
7005 < The optional {completion} argument specifies the type of
7006 completion supported for the input. Without it completion is
7007 not performed. The supported completion types are the same as
7008 that can be supplied to a user-defined command using the
7009 "-complete=" argument. Refer to |:command-completion| for
7010 more information. Example: >
7011 let fname = input("File: ", "", "file")
7012 <
7013 NOTE: This function must not be used in a startup file, for
7014 the versions that only run in GUI mode (e.g., the Win32 GUI).
7015 Note: When input() is called from within a mapping it will
7016 consume remaining characters from that mapping, because a
7017 mapping is handled like the characters were typed.
7018 Use |inputsave()| before input() and |inputrestore()|
7019 after input() to avoid that. Another solution is to avoid
7020 that further characters follow in the mapping, e.g., by using
7021 |:execute| or |:normal|.
7022
7023 Example with a mapping: >
7024 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
7025 :function GetFoo()
7026 : call inputsave()
7027 : let g:Foo = input("enter search pattern: ")
7028 : call inputrestore()
7029 :endfunction
7030
7031 < Can also be used as a |method|: >
7032 GetPrompt()->input()
7033
7034 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
7035 Like |input()|, but when the GUI is running and text dialogs
7036 are supported, a dialog window pops up to input the text.
7037 Example: >
7038 :let n = inputdialog("value for shiftwidth", shiftwidth())
7039 :if n != ""
7040 : let &sw = n
7041 :endif
7042 < When the dialog is cancelled {cancelreturn} is returned. When
7043 omitted an empty string is returned.
7044 Hitting <Enter> works like pressing the OK button. Hitting
7045 <Esc> works like pressing the Cancel button.
7046 NOTE: Command-line completion is not supported.
7047
7048 Can also be used as a |method|: >
7049 GetPrompt()->inputdialog()
7050
7051 inputlist({textlist}) *inputlist()*
7052 {textlist} must be a |List| of strings. This |List| is
7053 displayed, one string per line. The user will be prompted to
7054 enter a number, which is returned.
7055 The user can also select an item by clicking on it with the
7056 mouse, if the mouse is enabled in the command line ('mouse' is
7057 "a" or includes "c"). For the first string 0 is returned.
7058 When clicking above the first item a negative number is
7059 returned. When clicking on the prompt one more than the
7060 length of {textlist} is returned.
7061 Make sure {textlist} has less than 'lines' entries, otherwise
7062 it won't work. It's a good idea to put the entry number at
7063 the start of the string. And put a prompt in the first item.
7064 Example: >
7065 let color = inputlist(['Select color:', '1. red',
7066 \ '2. green', '3. blue'])
7067
7068 < Can also be used as a |method|: >
7069 GetChoices()->inputlist()
7070
7071 inputrestore() *inputrestore()*
7072 Restore typeahead that was saved with a previous |inputsave()|.
7073 Should be called the same number of times inputsave() is
7074 called. Calling it more often is harmless though.
7075 Returns TRUE when there is nothing to restore, FALSE otherwise.
7076
7077 inputsave() *inputsave()*
7078 Preserve typeahead (also from mappings) and clear it, so that
7079 a following prompt gets input from the user. Should be
7080 followed by a matching inputrestore() after the prompt. Can
7081 be used several times, in which case there must be just as
7082 many inputrestore() calls.
7083 Returns TRUE when out of memory, FALSE otherwise.
7084
7085 inputsecret({prompt} [, {text}]) *inputsecret()*
7086 This function acts much like the |input()| function with but
7087 two exceptions:
7088 a) the user's response will be displayed as a sequence of
7089 asterisks ("*") thereby keeping the entry secret, and
7090 b) the user's response will not be recorded on the input
7091 |history| stack.
7092 The result is a String, which is whatever the user actually
7093 typed on the command-line in response to the issued prompt.
7094 NOTE: Command-line completion is not supported.
7095
7096 Can also be used as a |method|: >
7097 GetPrompt()->inputsecret()
7098
7099 insert({object}, {item} [, {idx}]) *insert()*
7100 When {object} is a |List| or a |Blob| insert {item} at the start
7101 of it.
7102
7103 If {idx} is specified insert {item} before the item with index
7104 {idx}. If {idx} is zero it goes before the first item, just
7105 like omitting {idx}. A negative {idx} is also possible, see
7106 |list-index|. -1 inserts just before the last item.
7107
7108 Returns the resulting |List| or |Blob|. Examples: >
7109 :let mylist = insert([2, 3, 5], 1)
7110 :call insert(mylist, 4, -1)
7111 :call insert(mylist, 6, len(mylist))
7112 < The last example can be done simpler with |add()|.
7113 Note that when {item} is a |List| it is inserted as a single
7114 item. Use |extend()| to concatenate |Lists|.
7115
7116 Can also be used as a |method|: >
7117 mylist->insert(item)
7118
7119 interrupt() *interrupt()*
7120 Interrupt script execution. It works more or less like the
7121 user typing CTRL-C, most commands won't execute and control
7122 returns to the user. This is useful to abort execution
7123 from lower down, e.g. in an autocommand. Example: >
7124 :function s:check_typoname(file)
7125 : if fnamemodify(a:file, ':t') == '['
7126 : echomsg 'Maybe typo'
7127 : call interrupt()
7128 : endif
7129 :endfunction
7130 :au BufWritePre * call s:check_typoname(expand('<amatch>'))
7131
7132 invert({expr}) *invert()*
7133 Bitwise invert. The argument is converted to a number. A
7134 List, Dict or Float argument causes an error. Example: >
7135 :let bits = invert(bits)
7136 < Can also be used as a |method|: >
7137 :let bits = bits->invert()
7138
7139 isdirectory({directory}) *isdirectory()*
7140 The result is a Number, which is |TRUE| when a directory
7141 with the name {directory} exists. If {directory} doesn't
7142 exist, or isn't a directory, the result is |FALSE|. {directory}
7143 is any expression, which is used as a String.
7144
7145 Can also be used as a |method|: >
7146 GetName()->isdirectory()
7147
7148 isinf({expr}) *isinf()*
7149 Return 1 if {expr} is a positive infinity, or -1 a negative
7150 infinity, otherwise 0. >
7151 :echo isinf(1.0 / 0.0)
7152 < 1 >
7153 :echo isinf(-1.0 / 0.0)
7154 < -1
7155
7156 Can also be used as a |method|: >
7157 Compute()->isinf()
7158 <
7159 {only available when compiled with the |+float| feature}
7160
7161 islocked({expr}) *islocked()* *E786*
7162 The result is a Number, which is |TRUE| when {expr} is the
7163 name of a locked variable.
7164 The string argument {expr} must be the name of a variable,
7165 |List| item or |Dictionary| entry, not the variable itself!
7166 Example: >
7167 :let alist = [0, ['a', 'b'], 2, 3]
7168 :lockvar 1 alist
7169 :echo islocked('alist') " 1
7170 :echo islocked('alist[1]') " 0
7171
7172 < When {expr} is a variable that does not exist you get an error
7173 message. Use |exists()| to check for existence.
7174 In Vim9 script it does not work for local variables.
7175
7176 Can also be used as a |method|: >
7177 GetName()->islocked()
7178
7179 isnan({expr}) *isnan()*
7180 Return |TRUE| if {expr} is a float with value NaN. >
7181 echo isnan(0.0 / 0.0)
7182 < 1
7183
7184 Can also be used as a |method|: >
7185 Compute()->isnan()
7186 <
7187 {only available when compiled with the |+float| feature}
7188
7189 items({dict}) *items()*
7190 Return a |List| with all the key-value pairs of {dict}. Each
7191 |List| item is a list with two items: the key of a {dict}
7192 entry and the value of this entry. The |List| is in arbitrary
7193 order. Also see |keys()| and |values()|.
7194 Example: >
7195 for [key, value] in items(mydict)
7196 echo key . ': ' . value
7197 endfor
7198
7199 < Can also be used as a |method|: >
7200 mydict->items()
7201
7202 job_ functions are documented here: |job-functions-details|
7203
7204
7205 join({list} [, {sep}]) *join()*
7206 Join the items in {list} together into one String.
7207 When {sep} is specified it is put in between the items. If
7208 {sep} is omitted a single space is used.
7209 Note that {sep} is not added at the end. You might want to
7210 add it there too: >
7211 let lines = join(mylist, "\n") . "\n"
7212 < String items are used as-is. |Lists| and |Dictionaries| are
7213 converted into a string like with |string()|.
7214 The opposite function is |split()|.
7215
7216 Can also be used as a |method|: >
7217 mylist->join()
7218
7219 js_decode({string}) *js_decode()*
7220 This is similar to |json_decode()| with these differences:
7221 - Object key names do not have to be in quotes.
7222 - Strings can be in single quotes.
7223 - Empty items in an array (between two commas) are allowed and
7224 result in v:none items.
7225
7226 Can also be used as a |method|: >
7227 ReadObject()->js_decode()
7228
7229 js_encode({expr}) *js_encode()*
7230 This is similar to |json_encode()| with these differences:
7231 - Object key names are not in quotes.
7232 - v:none items in an array result in an empty item between
7233 commas.
7234 For example, the Vim object:
7235 [1,v:none,{"one":1},v:none] ~
7236 Will be encoded as:
7237 [1,,{one:1},,] ~
7238 While json_encode() would produce:
7239 [1,null,{"one":1},null] ~
7240 This encoding is valid for JavaScript. It is more efficient
7241 than JSON, especially when using an array with optional items.
7242
7243 Can also be used as a |method|: >
7244 GetObject()->js_encode()
7245
7246 json_decode({string}) *json_decode()*
7247 This parses a JSON formatted string and returns the equivalent
7248 in Vim values. See |json_encode()| for the relation between
7249 JSON and Vim values.
7250 The decoding is permissive:
7251 - A trailing comma in an array and object is ignored, e.g.
7252 "[1, 2, ]" is the same as "[1, 2]".
7253 - Integer keys are accepted in objects, e.g. {1:2} is the
7254 same as {"1":2}.
7255 - More floating point numbers are recognized, e.g. "1." for
7256 "1.0", or "001.2" for "1.2". Special floating point values
7257 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
7258 are accepted.
7259 - Leading zeroes in integer numbers are ignored, e.g. "012"
7260 for "12" or "-012" for "-12".
7261 - Capitalization is ignored in literal names null, true or
7262 false, e.g. "NULL" for "null", "True" for "true".
7263 - Control characters U+0000 through U+001F which are not
7264 escaped in strings are accepted, e.g. " " (tab
7265 character in string) for "\t".
7266 - An empty JSON expression or made of only spaces is accepted
7267 and results in v:none.
7268 - Backslash in an invalid 2-character sequence escape is
7269 ignored, e.g. "\a" is decoded as "a".
7270 - A correct surrogate pair in JSON strings should normally be
7271 a 12 character sequence such as "\uD834\uDD1E", but
7272 json_decode() silently accepts truncated surrogate pairs
7273 such as "\uD834" or "\uD834\u"
7274 *E938*
7275 A duplicate key in an object, valid in rfc7159, is not
7276 accepted by json_decode() as the result must be a valid Vim
7277 type, e.g. this fails: {"a":"b", "a":"c"}
7278
7279 Can also be used as a |method|: >
7280 ReadObject()->json_decode()
7281
7282 json_encode({expr}) *json_encode()*
7283 Encode {expr} as JSON and return this as a string.
7284 The encoding is specified in:
7285 https://tools.ietf.org/html/rfc7159.html
7286 Vim values are converted as follows:
7287 |Number| decimal number
7288 |Float| floating point number
7289 Float nan "NaN"
7290 Float inf "Infinity"
7291 Float -inf "-Infinity"
7292 |String| in double quotes (possibly null)
7293 |Funcref| not possible, error
7294 |List| as an array (possibly null); when
7295 used recursively: []
7296 |Dict| as an object (possibly null); when
7297 used recursively: {}
7298 |Blob| as an array of the individual bytes
7299 v:false "false"
7300 v:true "true"
7301 v:none "null"
7302 v:null "null"
7303 Note that NaN and Infinity are passed on as values. This is
7304 missing in the JSON standard, but several implementations do
7305 allow it. If not then you will get an error.
7306
7307 Can also be used as a |method|: >
7308 GetObject()->json_encode()
7309
7310 keys({dict}) *keys()*
7311 Return a |List| with all the keys of {dict}. The |List| is in
7312 arbitrary order. Also see |items()| and |values()|.
7313
7314 Can also be used as a |method|: >
7315 mydict->keys()
7316
7317 < *len()* *E701*
7318 len({expr}) The result is a Number, which is the length of the argument.
7319 When {expr} is a String or a Number the length in bytes is
7320 used, as with |strlen()|.
7321 When {expr} is a |List| the number of items in the |List| is
7322 returned.
7323 When {expr} is a |Blob| the number of bytes is returned.
7324 When {expr} is a |Dictionary| the number of entries in the
7325 |Dictionary| is returned.
7326 Otherwise an error is given.
7327
7328 Can also be used as a |method|: >
7329 mylist->len()
7330
7331 < *libcall()* *E364* *E368*
7332 libcall({libname}, {funcname}, {argument})
7333 Call function {funcname} in the run-time library {libname}
7334 with single argument {argument}.
7335 This is useful to call functions in a library that you
7336 especially made to be used with Vim. Since only one argument
7337 is possible, calling standard library functions is rather
7338 limited.
7339 The result is the String returned by the function. If the
7340 function returns NULL, this will appear as an empty string ""
7341 to Vim.
7342 If the function returns a number, use libcallnr()!
7343 If {argument} is a number, it is passed to the function as an
7344 int; if {argument} is a string, it is passed as a
7345 null-terminated string.
7346 This function will fail in |restricted-mode|.
7347
7348 libcall() allows you to write your own 'plug-in' extensions to
7349 Vim without having to recompile the program. It is NOT a
7350 means to call system functions! If you try to do so Vim will
7351 very probably crash.
7352
7353 For Win32, the functions you write must be placed in a DLL
7354 and use the normal C calling convention (NOT Pascal which is
7355 used in Windows System DLLs). The function must take exactly
7356 one parameter, either a character pointer or a long integer,
7357 and must return a character pointer or NULL. The character
7358 pointer returned must point to memory that will remain valid
7359 after the function has returned (e.g. in static data in the
7360 DLL). If it points to allocated memory, that memory will
7361 leak away. Using a static buffer in the function should work,
7362 it's then freed when the DLL is unloaded.
7363
7364 WARNING: If the function returns a non-valid pointer, Vim may
7365 crash! This also happens if the function returns a number,
7366 because Vim thinks it's a pointer.
7367 For Win32 systems, {libname} should be the filename of the DLL
7368 without the ".DLL" suffix. A full path is only required if
7369 the DLL is not in the usual places.
7370 For Unix: When compiling your own plugins, remember that the
7371 object code must be compiled as position-independent ('PIC').
7372 {only in Win32 and some Unix versions, when the |+libcall|
7373 feature is present}
7374 Examples: >
7375 :echo libcall("libc.so", "getenv", "HOME")
7376
7377 < Can also be used as a |method|, the base is passed as the
7378 third argument: >
7379 GetValue()->libcall("libc.so", "getenv")
7380 <
7381 *libcallnr()*
7382 libcallnr({libname}, {funcname}, {argument})
7383 Just like |libcall()|, but used for a function that returns an
7384 int instead of a string.
7385 {only in Win32 on some Unix versions, when the |+libcall|
7386 feature is present}
7387 Examples: >
7388 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
7389 :call libcallnr("libc.so", "printf", "Hello World!\n")
7390 :call libcallnr("libc.so", "sleep", 10)
7391 <
7392 Can also be used as a |method|, the base is passed as the
7393 third argument: >
7394 GetValue()->libcallnr("libc.so", "printf")
7395 <
7396
7397 line({expr} [, {winid}]) *line()*
7398 The result is a Number, which is the line number of the file
7399 position given with {expr}. The {expr} argument is a string.
7400 The accepted positions are:
7401 . the cursor position
7402 $ the last line in the current buffer
7403 'x position of mark x (if the mark is not set, 0 is
7404 returned)
7405 w0 first line visible in current window (one if the
7406 display isn't updated, e.g. in silent Ex mode)
7407 w$ last line visible in current window (this is one
7408 less than "w0" if no lines are visible)
7409 v In Visual mode: the start of the Visual area (the
7410 cursor is the end). When not in Visual mode
7411 returns the cursor position. Differs from |'<| in
7412 that it's updated right away.
7413 Note that a mark in another file can be used. The line number
7414 then applies to another buffer.
7415 To get the column number use |col()|. To get both use
7416 |getpos()|.
7417 With the optional {winid} argument the values are obtained for
7418 that window instead of the current window.
7419 Examples: >
7420 line(".") line number of the cursor
7421 line(".", winid) idem, in window "winid"
7422 line("'t") line number of mark t
7423 line("'" . marker) line number of mark marker
7424 <
7425 To jump to the last known position when opening a file see
7426 |last-position-jump|.
7427
7428 Can also be used as a |method|: >
7429 GetValue()->line()
7430
7431 line2byte({lnum}) *line2byte()*
7432 Return the byte count from the start of the buffer for line
7433 {lnum}. This includes the end-of-line character, depending on
7434 the 'fileformat' option for the current buffer. The first
7435 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
7436 This can also be used to get the byte count for the line just
7437 below the last line: >
7438 line2byte(line("$") + 1)
7439 < This is the buffer size plus one. If 'fileencoding' is empty
7440 it is the file size plus one. {lnum} is used like with
7441 |getline()|. When {lnum} is invalid, or the |+byte_offset|
7442 feature has been disabled at compile time, -1 is returned.
7443 Also see |byte2line()|, |go| and |:goto|.
7444
7445 Can also be used as a |method|: >
7446 GetLnum()->line2byte()
7447
7448 lispindent({lnum}) *lispindent()*
7449 Get the amount of indent for line {lnum} according the lisp
7450 indenting rules, as with 'lisp'.
7451 The indent is counted in spaces, the value of 'tabstop' is
7452 relevant. {lnum} is used just like in |getline()|.
7453 When {lnum} is invalid or Vim was not compiled the
7454 |+lispindent| feature, -1 is returned.
7455
7456 Can also be used as a |method|: >
7457 GetLnum()->lispindent()
7458
7459 list2blob({list}) *list2blob()*
7460 Return a Blob concatenating all the number values in {list}.
7461 Examples: >
7462 list2blob([1, 2, 3, 4]) returns 0z01020304
7463 list2blob([]) returns 0z
7464 < Returns an empty Blob on error. If one of the numbers is
7465 negative or more than 255 error *E1239* is given.
7466
7467 |blob2list()| does the opposite.
7468
7469 Can also be used as a |method|: >
7470 GetList()->list2blob()
7471
7472 list2str({list} [, {utf8}]) *list2str()*
7473 Convert each number in {list} to a character string can
7474 concatenate them all. Examples: >
7475 list2str([32]) returns " "
7476 list2str([65, 66, 67]) returns "ABC"
7477 < The same can be done (slowly) with: >
7478 join(map(list, {nr, val -> nr2char(val)}), '')
7479 < |str2list()| does the opposite.
7480
7481 When {utf8} is omitted or zero, the current 'encoding' is used.
7482 When {utf8} is TRUE, always return UTF-8 characters.
7483 With UTF-8 composing characters work as expected: >
7484 list2str([97, 769]) returns "á"
7485 <
7486 Can also be used as a |method|: >
7487 GetList()->list2str()
7488
7489 listener_add({callback} [, {buf}]) *listener_add()*
7490 Add a callback function that will be invoked when changes have
7491 been made to buffer {buf}.
7492 {buf} refers to a buffer name or number. For the accepted
7493 values, see |bufname()|. When {buf} is omitted the current
7494 buffer is used.
7495 Returns a unique ID that can be passed to |listener_remove()|.
7496
7497 The {callback} is invoked with five arguments:
7498 a:bufnr the buffer that was changed
7499 a:start first changed line number
7500 a:end first line number below the change
7501 a:added number of lines added, negative if lines were
7502 deleted
7503 a:changes a List of items with details about the changes
7504
7505 Example: >
7506 func Listener(bufnr, start, end, added, changes)
7507 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
7508 endfunc
7509 call listener_add('Listener', bufnr)
7510
7511 < The List cannot be changed. Each item in a:changes is a
7512 dictionary with these entries:
7513 lnum the first line number of the change
7514 end the first line below the change
7515 added number of lines added; negative if lines were
7516 deleted
7517 col first column in "lnum" that was affected by
7518 the change; one if unknown or the whole line
7519 was affected; this is a byte index, first
7520 character has a value of one.
7521 When lines are inserted the values are:
7522 lnum line above which the new line is added
7523 end equal to "lnum"
7524 added number of lines inserted
7525 col 1
7526 When lines are deleted the values are:
7527 lnum the first deleted line
7528 end the line below the first deleted line, before
7529 the deletion was done
7530 added negative, number of lines deleted
7531 col 1
7532 When lines are changed:
7533 lnum the first changed line
7534 end the line below the last changed line
7535 added 0
7536 col first column with a change or 1
7537
7538 The entries are in the order the changes were made, thus the
7539 most recent change is at the end. The line numbers are valid
7540 when the callback is invoked, but later changes may make them
7541 invalid, thus keeping a copy for later might not work.
7542
7543 The {callback} is invoked just before the screen is updated,
7544 when |listener_flush()| is called or when a change is being
7545 made that changes the line count in a way it causes a line
7546 number in the list of changes to become invalid.
7547
7548 The {callback} is invoked with the text locked, see
7549 |textlock|. If you do need to make changes to the buffer, use
7550 a timer to do this later |timer_start()|.
7551
7552 The {callback} is not invoked when the buffer is first loaded.
7553 Use the |BufReadPost| autocmd event to handle the initial text
7554 of a buffer.
7555 The {callback} is also not invoked when the buffer is
7556 unloaded, use the |BufUnload| autocmd event for that.
7557
7558 Can also be used as a |method|, the base is passed as the
7559 second argument: >
7560 GetBuffer()->listener_add(callback)
7561
7562 listener_flush([{buf}]) *listener_flush()*
7563 Invoke listener callbacks for buffer {buf}. If there are no
7564 pending changes then no callbacks are invoked.
7565
7566 {buf} refers to a buffer name or number. For the accepted
7567 values, see |bufname()|. When {buf} is omitted the current
7568 buffer is used.
7569
7570 Can also be used as a |method|: >
7571 GetBuffer()->listener_flush()
7572
7573 listener_remove({id}) *listener_remove()*
7574 Remove a listener previously added with listener_add().
7575 Returns FALSE when {id} could not be found, TRUE when {id} was
7576 removed.
7577
7578 Can also be used as a |method|: >
7579 GetListenerId()->listener_remove()
7580
7581 localtime() *localtime()*
7582 Return the current time, measured as seconds since 1st Jan
7583 1970. See also |strftime()|, |strptime()| and |getftime()|.
7584
7585
7586 log({expr}) *log()*
7587 Return the natural logarithm (base e) of {expr} as a |Float|.
7588 {expr} must evaluate to a |Float| or a |Number| in the range
7589 (0, inf].
7590 Examples: >
7591 :echo log(10)
7592 < 2.302585 >
7593 :echo log(exp(5))
7594 < 5.0
7595
7596 Can also be used as a |method|: >
7597 Compute()->log()
7598 <
7599 {only available when compiled with the |+float| feature}
7600
7601
7602 log10({expr}) *log10()*
7603 Return the logarithm of Float {expr} to base 10 as a |Float|.
7604 {expr} must evaluate to a |Float| or a |Number|.
7605 Examples: >
7606 :echo log10(1000)
7607 < 3.0 >
7608 :echo log10(0.01)
7609 < -2.0
7610
7611 Can also be used as a |method|: >
7612 Compute()->log10()
7613 <
7614 {only available when compiled with the |+float| feature}
7615
7616 luaeval({expr} [, {expr}]) *luaeval()*
7617 Evaluate Lua expression {expr} and return its result converted
7618 to Vim data structures. Second {expr} may hold additional
7619 argument accessible as _A inside first {expr}.
7620 Strings are returned as they are.
7621 Boolean objects are converted to numbers.
7622 Numbers are converted to |Float| values if vim was compiled
7623 with |+float| and to numbers otherwise.
7624 Dictionaries and lists obtained by vim.eval() are returned
7625 as-is.
7626 Other objects are returned as zero without any errors.
7627 See |lua-luaeval| for more details.
7628 Note that in a `:def` function local variables are not visible
7629 to {expr}.
7630
7631 Can also be used as a |method|: >
7632 GetExpr()->luaeval()
7633
7634 < {only available when compiled with the |+lua| feature}
7635
7636 map({expr1}, {expr2}) *map()*
7637 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
7638 When {expr1} is a |List|| or |Dictionary|, replace each
7639 item in {expr1} with the result of evaluating {expr2}.
7640 For a |Blob| each byte is replaced.
7641 For a |String|, each character, including composing
7642 characters, is replaced.
7643 If the item type changes you may want to use |mapnew()| to
7644 create a new List or Dictionary. This is required when using
7645 Vim9 script.
7646
7647 {expr2} must be a |String| or |Funcref|.
7648
7649 If {expr2} is a |String|, inside {expr2} |v:val| has the value
7650 of the current item. For a |Dictionary| |v:key| has the key
7651 of the current item and for a |List| |v:key| has the index of
7652 the current item. For a |Blob| |v:key| has the index of the
7653 current byte. For a |String| |v:key| has the index of the
7654 current character.
7655 Example: >
7656 :call map(mylist, '"> " . v:val . " <"')
7657 < This puts "> " before and " <" after each item in "mylist".
7658
7659 Note that {expr2} is the result of an expression and is then
7660 used as an expression again. Often it is good to use a
7661 |literal-string| to avoid having to double backslashes. You
7662 still have to double ' quotes
7663
7664 If {expr2} is a |Funcref| it is called with two arguments:
7665 1. The key or the index of the current item.
7666 2. the value of the current item.
7667 The function must return the new value of the item. Example
7668 that changes each value by "key-value": >
7669 func KeyValue(key, val)
7670 return a:key . '-' . a:val
7671 endfunc
7672 call map(myDict, function('KeyValue'))
7673 < It is shorter when using a |lambda|: >
7674 call map(myDict, {key, val -> key . '-' . val})
7675 < If you do not use "val" you can leave it out: >
7676 call map(myDict, {key -> 'item: ' . key})
7677 < If you do not use "key" you can use a short name: >
7678 call map(myDict, {_, val -> 'item: ' . val})
7679 <
7680 The operation is done in-place for a |List| and |Dictionary|.
7681 If you want it to remain unmodified make a copy first: >
7682 :let tlist = map(copy(mylist), ' v:val . "\t"')
7683
7684 < Returns {expr1}, the |List| or |Dictionary| that was filtered,
7685 or a new |Blob| or |String|.
7686 When an error is encountered while evaluating {expr2} no
7687 further items in {expr1} are processed.
7688 When {expr2} is a Funcref errors inside a function are ignored,
7689 unless it was defined with the "abort" flag.
7690
7691 Can also be used as a |method|: >
7692 mylist->map(expr2)
7693
7694
7695 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
7696 When {dict} is omitted or zero: Return the rhs of mapping
7697 {name} in mode {mode}. The returned String has special
7698 characters translated like in the output of the ":map" command
7699 listing.
7700
7701 When there is no mapping for {name}, an empty String is
7702 returned. When the mapping for {name} is empty, then "<Nop>"
7703 is returned.
7704
7705 The {name} can have special key names, like in the ":map"
7706 command.
7707
7708 {mode} can be one of these strings:
7709 "n" Normal
7710 "v" Visual (including Select)
7711 "o" Operator-pending
7712 "i" Insert
7713 "c" Cmd-line
7714 "s" Select
7715 "x" Visual
7716 "l" langmap |language-mapping|
7717 "t" Terminal-Job
7718 "" Normal, Visual and Operator-pending
7719 When {mode} is omitted, the modes for "" are used.
7720
7721 When {abbr} is there and it is |TRUE| use abbreviations
7722 instead of mappings.
7723
7724 When {dict} is there and it is |TRUE| return a dictionary
7725 containing all the information of the mapping with the
7726 following items:
7727 "lhs" The {lhs} of the mapping as it would be typed
7728 "lhsraw" The {lhs} of the mapping as raw bytes
7729 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
7730 form, only present when it differs from "lhsraw"
7731 "rhs" The {rhs} of the mapping as typed.
7732 "silent" 1 for a |:map-silent| mapping, else 0.
7733 "noremap" 1 if the {rhs} of the mapping is not remappable.
7734 "script" 1 if mapping was defined with <script>.
7735 "expr" 1 for an expression mapping (|:map-<expr>|).
7736 "buffer" 1 for a buffer local mapping (|:map-local|).
7737 "mode" Modes for which the mapping is defined. In
7738 addition to the modes mentioned above, these
7739 characters will be used:
7740 " " Normal, Visual and Operator-pending
7741 "!" Insert and Commandline mode
7742 (|mapmode-ic|)
7743 "sid" The script local ID, used for <sid> mappings
7744 (|<SID>|).
7745 "lnum" The line number in "sid", zero if unknown.
7746 "nowait" Do not wait for other, longer mappings.
7747 (|:map-<nowait>|).
7748
7749 The dictionary can be used to restore a mapping with
7750 |mapset()|.
7751
7752 The mappings local to the current buffer are checked first,
7753 then the global mappings.
7754 This function can be used to map a key even when it's already
7755 mapped, and have it do the original mapping too. Sketch: >
7756 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
7757
7758 < Can also be used as a |method|: >
7759 GetKey()->maparg('n')
7760
7761 mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
7762 Check if there is a mapping that matches with {name} in mode
7763 {mode}. See |maparg()| for {mode} and special names in
7764 {name}.
7765 When {abbr} is there and it is |TRUE| use abbreviations
7766 instead of mappings.
7767 A match happens with a mapping that starts with {name} and
7768 with a mapping which is equal to the start of {name}.
7769
7770 matches mapping "a" "ab" "abc" ~
7771 mapcheck("a") yes yes yes
7772 mapcheck("abc") yes yes yes
7773 mapcheck("ax") yes no no
7774 mapcheck("b") no no no
7775
7776 The difference with maparg() is that mapcheck() finds a
7777 mapping that matches with {name}, while maparg() only finds a
7778 mapping for {name} exactly.
7779 When there is no mapping that starts with {name}, an empty
7780 String is returned. If there is one, the RHS of that mapping
7781 is returned. If there are several mappings that start with
7782 {name}, the RHS of one of them is returned. This will be
7783 "<Nop>" if the RHS is empty.
7784 The mappings local to the current buffer are checked first,
7785 then the global mappings.
7786 This function can be used to check if a mapping can be added
7787 without being ambiguous. Example: >
7788 :if mapcheck("_vv") == ""
7789 : map _vv :set guifont=7x13<CR>
7790 :endif
7791 < This avoids adding the "_vv" mapping when there already is a
7792 mapping for "_v" or for "_vvv".
7793
7794 Can also be used as a |method|: >
7795 GetKey()->mapcheck('n')
7796
7797
7798 mapnew({expr1}, {expr2}) *mapnew()*
7799 Like |map()| but instead of replacing items in {expr1} a new
7800 List or Dictionary is created and returned. {expr1} remains
7801 unchanged. Items can still be changed by {expr2}, if you
7802 don't want that use |deepcopy()| first.
7803
7804
7805 mapset({mode}, {abbr}, {dict}) *mapset()*
7806 Restore a mapping from a dictionary returned by |maparg()|.
7807 {mode} and {abbr} should be the same as for the call to
7808 |maparg()|. *E460*
7809 {mode} is used to define the mode in which the mapping is set,
7810 not the "mode" entry in {dict}.
7811 Example for saving and restoring a mapping: >
7812 let save_map = maparg('K', 'n', 0, 1)
7813 nnoremap K somethingelse
7814 ...
7815 call mapset('n', 0, save_map)
7816 < Note that if you are going to replace a map in several modes,
7817 e.g. with `:map!`, you need to save the mapping for all of
7818 them, since they can differ.
7819
7820
7821 match({expr}, {pat} [, {start} [, {count}]]) *match()*
7822 When {expr} is a |List| then this returns the index of the
7823 first item where {pat} matches. Each item is used as a
7824 String, |Lists| and |Dictionaries| are used as echoed.
7825
7826 Otherwise, {expr} is used as a String. The result is a
7827 Number, which gives the index (byte offset) in {expr} where
7828 {pat} matches.
7829
7830 A match at the first character or |List| item returns zero.
7831 If there is no match -1 is returned.
7832
7833 For getting submatches see |matchlist()|.
7834 Example: >
7835 :echo match("testing", "ing") " results in 4
7836 :echo match([1, 'x'], '\a') " results in 1
7837 < See |string-match| for how {pat} is used.
7838 *strpbrk()*
7839 Vim doesn't have a strpbrk() function. But you can do: >
7840 :let sepidx = match(line, '[.,;: \t]')
7841 < *strcasestr()*
7842 Vim doesn't have a strcasestr() function. But you can add
7843 "\c" to the pattern to ignore case: >
7844 :let idx = match(haystack, '\cneedle')
7845 <
7846 If {start} is given, the search starts from byte index
7847 {start} in a String or item {start} in a |List|.
7848 The result, however, is still the index counted from the
7849 first character/item. Example: >
7850 :echo match("testing", "ing", 2)
7851 < result is again "4". >
7852 :echo match("testing", "ing", 4)
7853 < result is again "4". >
7854 :echo match("testing", "t", 2)
7855 < result is "3".
7856 For a String, if {start} > 0 then it is like the string starts
7857 {start} bytes later, thus "^" will match at {start}. Except
7858 when {count} is given, then it's like matches before the
7859 {start} byte are ignored (this is a bit complicated to keep it
7860 backwards compatible).
7861 For a String, if {start} < 0, it will be set to 0. For a list
7862 the index is counted from the end.
7863 If {start} is out of range ({start} > strlen({expr}) for a
7864 String or {start} > len({expr}) for a |List|) -1 is returned.
7865
7866 When {count} is given use the {count}'th match. When a match
7867 is found in a String the search for the next one starts one
7868 character further. Thus this example results in 1: >
7869 echo match("testing", "..", 0, 2)
7870 < In a |List| the search continues in the next item.
7871 Note that when {count} is added the way {start} works changes,
7872 see above.
7873
7874 See |pattern| for the patterns that are accepted.
7875 The 'ignorecase' option is used to set the ignore-caseness of
7876 the pattern. 'smartcase' is NOT used. The matching is always
7877 done like 'magic' is set and 'cpoptions' is empty.
7878 Note that a match at the start is preferred, thus when the
7879 pattern is using "*" (any number of matches) it tends to find
7880 zero matches at the start instead of a number of matches
7881 further down in the text.
7882
7883 Can also be used as a |method|: >
7884 GetText()->match('word')
7885 GetList()->match('word')
7886 <
7887 *matchadd()* *E798* *E799* *E801* *E957*
7888 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
7889 Defines a pattern to be highlighted in the current window (a
7890 "match"). It will be highlighted with {group}. Returns an
7891 identification number (ID), which can be used to delete the
7892 match using |matchdelete()|. The ID is bound to the window.
7893 Matching is case sensitive and magic, unless case sensitivity
7894 or magicness are explicitly overridden in {pattern}. The
7895 'magic', 'smartcase' and 'ignorecase' options are not used.
7896 The "Conceal" value is special, it causes the match to be
7897 concealed.
7898
7899 The optional {priority} argument assigns a priority to the
7900 match. A match with a high priority will have its
7901 highlighting overrule that of a match with a lower priority.
7902 A priority is specified as an integer (negative numbers are no
7903 exception). If the {priority} argument is not specified, the
7904 default priority is 10. The priority of 'hlsearch' is zero,
7905 hence all matches with a priority greater than zero will
7906 overrule it. Syntax highlighting (see 'syntax') is a separate
7907 mechanism, and regardless of the chosen priority a match will
7908 always overrule syntax highlighting.
7909
7910 The optional {id} argument allows the request for a specific
7911 match ID. If a specified ID is already taken, an error
7912 message will appear and the match will not be added. An ID
7913 is specified as a positive integer (zero excluded). IDs 1, 2
7914 and 3 are reserved for |:match|, |:2match| and |:3match|,
7915 respectively. If the {id} argument is not specified or -1,
7916 |matchadd()| automatically chooses a free ID.
7917
7918 The optional {dict} argument allows for further custom
7919 values. Currently this is used to specify a match specific
7920 conceal character that will be shown for |hl-Conceal|
7921 highlighted matches. The dict can have the following members:
7922
7923 conceal Special character to show instead of the
7924 match (only for |hl-Conceal| highlighted
7925 matches, see |:syn-cchar|)
7926 window Instead of the current window use the
7927 window with this number or window ID.
7928
7929 The number of matches is not limited, as it is the case with
7930 the |:match| commands.
7931
7932 Example: >
7933 :highlight MyGroup ctermbg=green guibg=green
7934 :let m = matchadd("MyGroup", "TODO")
7935 < Deletion of the pattern: >
7936 :call matchdelete(m)
7937
7938 < A list of matches defined by |matchadd()| and |:match| are
7939 available from |getmatches()|. All matches can be deleted in
7940 one operation by |clearmatches()|.
7941
7942 Can also be used as a |method|: >
7943 GetGroup()->matchadd('TODO')
7944 <
7945 *matchaddpos()*
7946 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
7947 Same as |matchadd()|, but requires a list of positions {pos}
7948 instead of a pattern. This command is faster than |matchadd()|
7949 because it does not require to handle regular expressions and
7950 sets buffer line boundaries to redraw screen. It is supposed
7951 to be used when fast match additions and deletions are
7952 required, for example to highlight matching parentheses.
7953
7954 {pos} is a list of positions. Each position can be one of
7955 these:
7956 - A number. This whole line will be highlighted. The first
7957 line has number 1.
7958 - A list with one number, e.g., [23]. The whole line with this
7959 number will be highlighted.
7960 - A list with two numbers, e.g., [23, 11]. The first number is
7961 the line number, the second one is the column number (first
7962 column is 1, the value must correspond to the byte index as
7963 |col()| would return). The character at this position will
7964 be highlighted.
7965 - A list with three numbers, e.g., [23, 11, 3]. As above, but
7966 the third number gives the length of the highlight in bytes.
7967
7968 The maximum number of positions in {pos} is 8.
7969
7970 Example: >
7971 :highlight MyGroup ctermbg=green guibg=green
7972 :let m = matchaddpos("MyGroup", [[23, 24], 34])
7973 < Deletion of the pattern: >
7974 :call matchdelete(m)
7975
7976 < Matches added by |matchaddpos()| are returned by
7977 |getmatches()|.
7978
7979 Can also be used as a |method|: >
7980 GetGroup()->matchaddpos([23, 11])
7981
7982 matcharg({nr}) *matcharg()*
7983 Selects the {nr} match item, as set with a |:match|,
7984 |:2match| or |:3match| command.
7985 Return a |List| with two elements:
7986 The name of the highlight group used
7987 The pattern used.
7988 When {nr} is not 1, 2 or 3 returns an empty |List|.
7989 When there is no match item set returns ['', ''].
7990 This is useful to save and restore a |:match|.
7991 Highlighting matches using the |:match| commands are limited
7992 to three matches. |matchadd()| does not have this limitation.
7993
7994 Can also be used as a |method|: >
7995 GetMatch()->matcharg()
7996
7997 matchdelete({id} [, {win}) *matchdelete()* *E802* *E803*
7998 Deletes a match with ID {id} previously defined by |matchadd()|
7999 or one of the |:match| commands. Returns 0 if successful,
8000 otherwise -1. See example for |matchadd()|. All matches can
8001 be deleted in one operation by |clearmatches()|.
8002 If {win} is specified, use the window with this number or
8003 window ID instead of the current window.
8004
8005 Can also be used as a |method|: >
8006 GetMatch()->matchdelete()
8007
8008 matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
8009 Same as |match()|, but return the index of first character
8010 after the match. Example: >
8011 :echo matchend("testing", "ing")
8012 < results in "7".
8013 *strspn()* *strcspn()*
8014 Vim doesn't have a strspn() or strcspn() function, but you can
8015 do it with matchend(): >
8016 :let span = matchend(line, '[a-zA-Z]')
8017 :let span = matchend(line, '[^a-zA-Z]')
8018 < Except that -1 is returned when there are no matches.
8019
8020 The {start}, if given, has the same meaning as for |match()|. >
8021 :echo matchend("testing", "ing", 2)
8022 < results in "7". >
8023 :echo matchend("testing", "ing", 5)
8024 < result is "-1".
8025 When {expr} is a |List| the result is equal to |match()|.
8026
8027 Can also be used as a |method|: >
8028 GetText()->matchend('word')
8029
8030
8031 matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()*
8032 If {list} is a list of strings, then returns a |List| with all
8033 the strings in {list} that fuzzy match {str}. The strings in
8034 the returned list are sorted based on the matching score.
8035
8036 The optional {dict} argument always supports the following
8037 items:
8038 matchseq When this item is present and {str} contains
8039 multiple words separated by white space, then
8040 returns only matches that contain the words in
8041 the given sequence.
8042
8043 If {list} is a list of dictionaries, then the optional {dict}
8044 argument supports the following additional items:
8045 key key of the item which is fuzzy matched against
8046 {str}. The value of this item should be a
8047 string.
8048 text_cb |Funcref| that will be called for every item
8049 in {list} to get the text for fuzzy matching.
8050 This should accept a dictionary item as the
8051 argument and return the text for that item to
8052 use for fuzzy matching.
8053
8054 {str} is treated as a literal string and regular expression
8055 matching is NOT supported. The maximum supported {str} length
8056 is 256.
8057
8058 When {str} has multiple words each separated by white space,
8059 then the list of strings that have all the words is returned.
8060
8061 If there are no matching strings or there is an error, then an
8062 empty list is returned. If length of {str} is greater than
8063 256, then returns an empty list.
8064
8065 Refer to |fuzzy-match| for more information about fuzzy
8066 matching strings.
8067
8068 Example: >
8069 :echo matchfuzzy(["clay", "crow"], "cay")
8070 < results in ["clay"]. >
8071 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
8072 < results in a list of buffer names fuzzy matching "ndl". >
8073 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'})
8074 < results in a list of buffer information dicts with buffer
8075 names fuzzy matching "ndl". >
8076 :echo getbufinfo()->matchfuzzy("spl",
8077 \ {'text_cb' : {v -> v.name}})
8078 < results in a list of buffer information dicts with buffer
8079 names fuzzy matching "spl". >
8080 :echo v:oldfiles->matchfuzzy("test")
8081 < results in a list of file names fuzzy matching "test". >
8082 :let l = readfile("buffer.c")->matchfuzzy("str")
8083 < results in a list of lines in "buffer.c" fuzzy matching "str". >
8084 :echo ['one two', 'two one']->matchfuzzy('two one')
8085 < results in ['two one', 'one two']. >
8086 :echo ['one two', 'two one']->matchfuzzy('two one',
8087 \ {'matchseq': 1})
8088 < results in ['two one'].
8089
8090 matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()*
8091 Same as |matchfuzzy()|, but returns the list of matched
8092 strings, the list of character positions where characters
8093 in {str} matches and a list of matching scores. You can
8094 use |byteidx()| to convert a character position to a byte
8095 position.
8096
8097 If {str} matches multiple times in a string, then only the
8098 positions for the best match is returned.
8099
8100 If there are no matching strings or there is an error, then a
8101 list with three empty list items is returned.
8102
8103 Example: >
8104 :echo matchfuzzypos(['testing'], 'tsg')
8105 < results in [['testing'], [[0, 2, 6]], [99]] >
8106 :echo matchfuzzypos(['clay', 'lacy'], 'la')
8107 < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] >
8108 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'})
8109 < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]]
8110
8111 matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
8112 Same as |match()|, but return a |List|. The first item in the
8113 list is the matched string, same as what matchstr() would
8114 return. Following items are submatches, like "\1", "\2", etc.
8115 in |:substitute|. When an optional submatch didn't match an
8116 empty string is used. Example: >
8117 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
8118 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
8119 When there is no match an empty list is returned.
8120
8121 You can pass in a List, but that is not very useful.
8122
8123 Can also be used as a |method|: >
8124 GetText()->matchlist('word')
8125
8126 matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
8127 Same as |match()|, but return the matched string. Example: >
8128 :echo matchstr("testing", "ing")
8129 < results in "ing".
8130 When there is no match "" is returned.
8131 The {start}, if given, has the same meaning as for |match()|. >
8132 :echo matchstr("testing", "ing", 2)
8133 < results in "ing". >
8134 :echo matchstr("testing", "ing", 5)
8135 < result is "".
8136 When {expr} is a |List| then the matching item is returned.
8137 The type isn't changed, it's not necessarily a String.
8138
8139 Can also be used as a |method|: >
8140 GetText()->matchstr('word')
8141
8142 matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
8143 Same as |matchstr()|, but return the matched string, the start
8144 position and the end position of the match. Example: >
8145 :echo matchstrpos("testing", "ing")
8146 < results in ["ing", 4, 7].
8147 When there is no match ["", -1, -1] is returned.
8148 The {start}, if given, has the same meaning as for |match()|. >
8149 :echo matchstrpos("testing", "ing", 2)
8150 < results in ["ing", 4, 7]. >
8151 :echo matchstrpos("testing", "ing", 5)
8152 < result is ["", -1, -1].
8153 When {expr} is a |List| then the matching item, the index
8154 of first item where {pat} matches, the start position and the
8155 end position of the match are returned. >
8156 :echo matchstrpos([1, '__x'], '\a')
8157 < result is ["x", 1, 2, 3].
8158 The type isn't changed, it's not necessarily a String.
8159
8160 Can also be used as a |method|: >
8161 GetText()->matchstrpos('word')
8162 <
8163
8164 *max()*
8165 max({expr}) Return the maximum value of all items in {expr}. Example: >
8166 echo max([apples, pears, oranges])
8167
8168 < {expr} can be a |List| or a |Dictionary|. For a Dictionary,
8169 it returns the maximum of all values in the Dictionary.
8170 If {expr} is neither a List nor a Dictionary, or one of the
8171 items in {expr} cannot be used as a Number this results in
8172 an error. An empty |List| or |Dictionary| results in zero.
8173
8174 Can also be used as a |method|: >
8175 mylist->max()
8176
8177
8178 menu_info({name} [, {mode}]) *menu_info()*
8179 Return information about the specified menu {name} in
8180 mode {mode}. The menu name should be specified without the
8181 shortcut character ('&'). If {name} is "", then the top-level
8182 menu names are returned.
8183
8184 {mode} can be one of these strings:
8185 "n" Normal
8186 "v" Visual (including Select)
8187 "o" Operator-pending
8188 "i" Insert
8189 "c" Cmd-line
8190 "s" Select
8191 "x" Visual
8192 "t" Terminal-Job
8193 "" Normal, Visual and Operator-pending
8194 "!" Insert and Cmd-line
8195 When {mode} is omitted, the modes for "" are used.
8196
8197 Returns a |Dictionary| containing the following items:
8198 accel menu item accelerator text |menu-text|
8199 display display name (name without '&')
8200 enabled v:true if this menu item is enabled
8201 Refer to |:menu-enable|
8202 icon name of the icon file (for toolbar)
8203 |toolbar-icon|
8204 iconidx index of a built-in icon
8205 modes modes for which the menu is defined. In
8206 addition to the modes mentioned above, these
8207 characters will be used:
8208 " " Normal, Visual and Operator-pending
8209 name menu item name.
8210 noremenu v:true if the {rhs} of the menu item is not
8211 remappable else v:false.
8212 priority menu order priority |menu-priority|
8213 rhs right-hand-side of the menu item. The returned
8214 string has special characters translated like
8215 in the output of the ":menu" command listing.
8216 When the {rhs} of a menu item is empty, then
8217 "<Nop>" is returned.
8218 script v:true if script-local remapping of {rhs} is
8219 allowed else v:false. See |:menu-script|.
8220 shortcut shortcut key (character after '&' in
8221 the menu name) |menu-shortcut|
8222 silent v:true if the menu item is created
8223 with <silent> argument |:menu-silent|
8224 submenus |List| containing the names of
8225 all the submenus. Present only if the menu
8226 item has submenus.
8227
8228 Returns an empty dictionary if the menu item is not found.
8229
8230 Examples: >
8231 :echo menu_info('Edit.Cut')
8232 :echo menu_info('File.Save', 'n')
8233
8234 " Display the entire menu hierarchy in a buffer
8235 func ShowMenu(name, pfx)
8236 let m = menu_info(a:name)
8237 call append(line('$'), a:pfx .. m.display)
8238 for child in m->get('submenus', [])
8239 call ShowMenu(a:name .. '.' .. escape(child, '.'),
8240 \ a:pfx .. ' ')
8241 endfor
8242 endfunc
8243 new
8244 for topmenu in menu_info('').submenus
8245 call ShowMenu(topmenu, '')
8246 endfor
8247 <
8248 Can also be used as a |method|: >
8249 GetMenuName()->menu_info('v')
8250
8251
8252 < *min()*
8253 min({expr}) Return the minimum value of all items in {expr}. Example: >
8254 echo min([apples, pears, oranges])
8255
8256 < {expr} can be a |List| or a |Dictionary|. For a Dictionary,
8257 it returns the minimum of all values in the Dictionary.
8258 If {expr} is neither a List nor a Dictionary, or one of the
8259 items in {expr} cannot be used as a Number this results in
8260 an error. An empty |List| or |Dictionary| results in zero.
8261
8262 Can also be used as a |method|: >
8263 mylist->min()
8264
8265 < *mkdir()* *E739*
8266 mkdir({name} [, {path} [, {prot}]])
8267 Create directory {name}.
8268
8269 If {path} is "p" then intermediate directories are created as
8270 necessary. Otherwise it must be "".
8271
8272 If {prot} is given it is used to set the protection bits of
8273 the new directory. The default is 0o755 (rwxr-xr-x: r/w for
8274 the user, readable for others). Use 0o700 to make it
8275 unreadable for others. This is only used for the last part of
8276 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be
8277 created with 0o755.
8278 Example: >
8279 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700)
8280
8281 < This function is not available in the |sandbox|.
8282
8283 There is no error if the directory already exists and the "p"
8284 flag is passed (since patch 8.0.1708). However, without the
8285 "p" option the call will fail.
8286
8287 The function result is a Number, which is TRUE if the call was
8288 successful or FALSE if the directory creation failed or partly
8289 failed.
8290
8291 Not available on all systems. To check use: >
8292 :if exists("*mkdir")
8293
8294 < Can also be used as a |method|: >
8295 GetName()->mkdir()
8296 <
8297 *mode()*
8298 mode([expr]) Return a string that indicates the current mode.
8299 If [expr] is supplied and it evaluates to a non-zero Number or
8300 a non-empty String (|non-zero-arg|), then the full mode is
8301 returned, otherwise only the first letter is returned.
8302 Also see |state()|.
8303
8304 n Normal
8305 no Operator-pending
8306 nov Operator-pending (forced characterwise |o_v|)
8307 noV Operator-pending (forced linewise |o_V|)
8308 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
8309 CTRL-V is one character
8310 niI Normal using |i_CTRL-O| in |Insert-mode|
8311 niR Normal using |i_CTRL-O| in |Replace-mode|
8312 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
8313 nt Terminal-Normal (insert goes to Terminal-Job mode)
8314 v Visual by character
8315 vs Visual by character using |v_CTRL-O| in Select mode
8316 V Visual by line
8317 Vs Visual by line using |v_CTRL-O| in Select mode
8318 CTRL-V Visual blockwise
8319 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode
8320 s Select by character
8321 S Select by line
8322 CTRL-S Select blockwise
8323 i Insert
8324 ic Insert mode completion |compl-generic|
8325 ix Insert mode |i_CTRL-X| completion
8326 R Replace |R|
8327 Rc Replace mode completion |compl-generic|
8328 Rx Replace mode |i_CTRL-X| completion
8329 Rv Virtual Replace |gR|
8330 Rvc Virtual Replace mode completion |compl-generic|
8331 Rvx Virtual Replace mode |i_CTRL-X| completion
8332 c Command-line editing
8333 cv Vim Ex mode |gQ|
8334 ce Normal Ex mode |Q|
8335 r Hit-enter prompt
8336 rm The -- more -- prompt
8337 r? A |:confirm| query of some sort
8338 ! Shell or external command is executing
8339 t Terminal-Job mode: keys go to the job
8340
8341 This is useful in the 'statusline' option or when used
8342 with |remote_expr()| In most other places it always returns
8343 "c" or "n".
8344 Note that in the future more modes and more specific modes may
8345 be added. It's better not to compare the whole string but only
8346 the leading character(s).
8347 Also see |visualmode()|.
8348
8349 Can also be used as a |method|: >
8350 DoFull()->mode()
8351
8352 mzeval({expr}) *mzeval()*
8353 Evaluate MzScheme expression {expr} and return its result
8354 converted to Vim data structures.
8355 Numbers and strings are returned as they are.
8356 Pairs (including lists and improper lists) and vectors are
8357 returned as Vim |Lists|.
8358 Hash tables are represented as Vim |Dictionary| type with keys
8359 converted to strings.
8360 All other types are converted to string with display function.
8361 Examples: >
8362 :mz (define l (list 1 2 3))
8363 :mz (define h (make-hash)) (hash-set! h "list" l)
8364 :echo mzeval("l")
8365 :echo mzeval("h")
8366 <
8367 Note that in a `:def` function local variables are not visible
8368 to {expr}.
8369
8370 Can also be used as a |method|: >
8371 GetExpr()->mzeval()
8372 <
8373 {only available when compiled with the |+mzscheme| feature}
8374
8375 nextnonblank({lnum}) *nextnonblank()*
8376 Return the line number of the first line at or below {lnum}
8377 that is not blank. Example: >
8378 if getline(nextnonblank(1)) =~ "Java"
8379 < When {lnum} is invalid or there is no non-blank line at or
8380 below it, zero is returned.
8381 {lnum} is used like with |getline()|.
8382 See also |prevnonblank()|.
8383
8384 Can also be used as a |method|: >
8385 GetLnum()->nextnonblank()
8386
8387 nr2char({expr} [, {utf8}]) *nr2char()*
8388 Return a string with a single character, which has the number
8389 value {expr}. Examples: >
8390 nr2char(64) returns "@"
8391 nr2char(32) returns " "
8392 < When {utf8} is omitted or zero, the current 'encoding' is used.
8393 Example for "utf-8": >
8394 nr2char(300) returns I with bow character
8395 < When {utf8} is TRUE, always return UTF-8 characters.
8396 Note that a NUL character in the file is specified with
8397 nr2char(10), because NULs are represented with newline
8398 characters. nr2char(0) is a real NUL and terminates the
8399 string, thus results in an empty string.
8400 To turn a list of character numbers into a string: >
8401 let list = [65, 66, 67]
8402 let str = join(map(list, {_, val -> nr2char(val)}), '')
8403 < Result: "ABC"
8404
8405 Can also be used as a |method|: >
8406 GetNumber()->nr2char()
8407
8408 or({expr}, {expr}) *or()*
8409 Bitwise OR on the two arguments. The arguments are converted
8410 to a number. A List, Dict or Float argument causes an error.
8411 Example: >
8412 :let bits = or(bits, 0x80)
8413 < Can also be used as a |method|: >
8414 :let bits = bits->or(0x80)
8415
8416
8417 pathshorten({path} [, {len}]) *pathshorten()*
8418 Shorten directory names in the path {path} and return the
8419 result. The tail, the file name, is kept as-is. The other
8420 components in the path are reduced to {len} letters in length.
8421 If {len} is omitted or smaller than 1 then 1 is used (single
8422 letters). Leading '~' and '.' characters are kept. Examples: >
8423 :echo pathshorten('~/.vim/autoload/myfile.vim')
8424 < ~/.v/a/myfile.vim ~
8425 >
8426 :echo pathshorten('~/.vim/autoload/myfile.vim', 2)
8427 < ~/.vi/au/myfile.vim ~
8428 It doesn't matter if the path exists or not.
8429
8430 Can also be used as a |method|: >
8431 GetDirectories()->pathshorten()
8432
8433 perleval({expr}) *perleval()*
8434 Evaluate Perl expression {expr} in scalar context and return
8435 its result converted to Vim data structures. If value can't be
8436 converted, it is returned as a string Perl representation.
8437 Note: If you want an array or hash, {expr} must return a
8438 reference to it.
8439 Example: >
8440 :echo perleval('[1 .. 4]')
8441 < [1, 2, 3, 4]
8442
8443 Note that in a `:def` function local variables are not visible
8444 to {expr}.
8445
8446 Can also be used as a |method|: >
8447 GetExpr()->perleval()
8448
8449 < {only available when compiled with the |+perl| feature}
8450
8451
8452 popup_ functions are documented here: |popup-functions|
8453
8454
8455 pow({x}, {y}) *pow()*
8456 Return the power of {x} to the exponent {y} as a |Float|.
8457 {x} and {y} must evaluate to a |Float| or a |Number|.
8458 Examples: >
8459 :echo pow(3, 3)
8460 < 27.0 >
8461 :echo pow(2, 16)
8462 < 65536.0 >
8463 :echo pow(32, 0.20)
8464 < 2.0
8465
8466 Can also be used as a |method|: >
8467 Compute()->pow(3)
8468 <
8469 {only available when compiled with the |+float| feature}
8470
8471 prevnonblank({lnum}) *prevnonblank()*
8472 Return the line number of the first line at or above {lnum}
8473 that is not blank. Example: >
8474 let ind = indent(prevnonblank(v:lnum - 1))
8475 < When {lnum} is invalid or there is no non-blank line at or
8476 above it, zero is returned.
8477 {lnum} is used like with |getline()|.
8478 Also see |nextnonblank()|.
8479
8480 Can also be used as a |method|: >
8481 GetLnum()->prevnonblank()
8482
8483 printf({fmt}, {expr1} ...) *printf()*
8484 Return a String with {fmt}, where "%" items are replaced by
8485 the formatted form of their respective arguments. Example: >
8486 printf("%4d: E%d %.30s", lnum, errno, msg)
8487 < May result in:
8488 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
8489
8490 When used as a |method| the base is passed as the second
8491 argument: >
8492 Compute()->printf("result: %d")
8493
8494 < Often used items are:
8495 %s string
8496 %6S string right-aligned in 6 display cells
8497 %6s string right-aligned in 6 bytes
8498 %.9s string truncated to 9 bytes
8499 %c single byte
8500 %d decimal number
8501 %5d decimal number padded with spaces to 5 characters
8502 %x hex number
8503 %04x hex number padded with zeros to at least 4 characters
8504 %X hex number using upper case letters
8505 %o octal number
8506 %08b binary number padded with zeros to at least 8 chars
8507 %f floating point number as 12.23, inf, -inf or nan
8508 %F floating point number as 12.23, INF, -INF or NAN
8509 %e floating point number as 1.23e3, inf, -inf or nan
8510 %E floating point number as 1.23E3, INF, -INF or NAN
8511 %g floating point number, as %f or %e depending on value
8512 %G floating point number, as %F or %E depending on value
8513 %% the % character itself
8514
8515 Conversion specifications start with '%' and end with the
8516 conversion type. All other characters are copied unchanged to
8517 the result.
8518
8519 The "%" starts a conversion specification. The following
8520 arguments appear in sequence:
8521
8522 % [flags] [field-width] [.precision] type
8523
8524 flags
8525 Zero or more of the following flags:
8526
8527 # The value should be converted to an "alternate
8528 form". For c, d, and s conversions, this option
8529 has no effect. For o conversions, the precision
8530 of the number is increased to force the first
8531 character of the output string to a zero (except
8532 if a zero value is printed with an explicit
8533 precision of zero).
8534 For b and B conversions, a non-zero result has
8535 the string "0b" (or "0B" for B conversions)
8536 prepended to it.
8537 For x and X conversions, a non-zero result has
8538 the string "0x" (or "0X" for X conversions)
8539 prepended to it.
8540
8541 0 (zero) Zero padding. For all conversions the converted
8542 value is padded on the left with zeros rather
8543 than blanks. If a precision is given with a
8544 numeric conversion (d, b, B, o, x, and X), the 0
8545 flag is ignored.
8546
8547 - A negative field width flag; the converted value
8548 is to be left adjusted on the field boundary.
8549 The converted value is padded on the right with
8550 blanks, rather than on the left with blanks or
8551 zeros. A - overrides a 0 if both are given.
8552
8553 ' ' (space) A blank should be left before a positive
8554 number produced by a signed conversion (d).
8555
8556 + A sign must always be placed before a number
8557 produced by a signed conversion. A + overrides
8558 a space if both are used.
8559
8560 field-width
8561 An optional decimal digit string specifying a minimum
8562 field width. If the converted value has fewer bytes
8563 than the field width, it will be padded with spaces on
8564 the left (or right, if the left-adjustment flag has
8565 been given) to fill out the field width. For the S
8566 conversion the count is in cells.
8567
8568 .precision
8569 An optional precision, in the form of a period '.'
8570 followed by an optional digit string. If the digit
8571 string is omitted, the precision is taken as zero.
8572 This gives the minimum number of digits to appear for
8573 d, o, x, and X conversions, the maximum number of
8574 bytes to be printed from a string for s conversions,
8575 or the maximum number of cells to be printed from a
8576 string for S conversions.
8577 For floating point it is the number of digits after
8578 the decimal point.
8579
8580 type
8581 A character that specifies the type of conversion to
8582 be applied, see below.
8583
8584 A field width or precision, or both, may be indicated by an
8585 asterisk '*' instead of a digit string. In this case, a
8586 Number argument supplies the field width or precision. A
8587 negative field width is treated as a left adjustment flag
8588 followed by a positive field width; a negative precision is
8589 treated as though it were missing. Example: >
8590 :echo printf("%d: %.*s", nr, width, line)
8591 < This limits the length of the text used from "line" to
8592 "width" bytes.
8593
8594 The conversion specifiers and their meanings are:
8595
8596 *printf-d* *printf-b* *printf-B* *printf-o*
8597 *printf-x* *printf-X*
8598 dbBoxX The Number argument is converted to signed decimal
8599 (d), unsigned binary (b and B), unsigned octal (o), or
8600 unsigned hexadecimal (x and X) notation. The letters
8601 "abcdef" are used for x conversions; the letters
8602 "ABCDEF" are used for X conversions.
8603 The precision, if any, gives the minimum number of
8604 digits that must appear; if the converted value
8605 requires fewer digits, it is padded on the left with
8606 zeros.
8607 In no case does a non-existent or small field width
8608 cause truncation of a numeric field; if the result of
8609 a conversion is wider than the field width, the field
8610 is expanded to contain the conversion result.
8611 The 'h' modifier indicates the argument is 16 bits.
8612 The 'l' modifier indicates the argument is 32 bits.
8613 The 'L' modifier indicates the argument is 64 bits.
8614 Generally, these modifiers are not useful. They are
8615 ignored when type is known from the argument.
8616
8617 i alias for d
8618 D alias for ld
8619 U alias for lu
8620 O alias for lo
8621
8622 *printf-c*
8623 c The Number argument is converted to a byte, and the
8624 resulting character is written.
8625
8626 *printf-s*
8627 s The text of the String argument is used. If a
8628 precision is specified, no more bytes than the number
8629 specified are used.
8630 If the argument is not a String type, it is
8631 automatically converted to text with the same format
8632 as ":echo".
8633 *printf-S*
8634 S The text of the String argument is used. If a
8635 precision is specified, no more display cells than the
8636 number specified are used.
8637
8638 *printf-f* *E807*
8639 f F The Float argument is converted into a string of the
8640 form 123.456. The precision specifies the number of
8641 digits after the decimal point. When the precision is
8642 zero the decimal point is omitted. When the precision
8643 is not specified 6 is used. A really big number
8644 (out of range or dividing by zero) results in "inf"
8645 or "-inf" with %f (INF or -INF with %F).
8646 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
8647 Example: >
8648 echo printf("%.2f", 12.115)
8649 < 12.12
8650 Note that roundoff depends on the system libraries.
8651 Use |round()| when in doubt.
8652
8653 *printf-e* *printf-E*
8654 e E The Float argument is converted into a string of the
8655 form 1.234e+03 or 1.234E+03 when using 'E'. The
8656 precision specifies the number of digits after the
8657 decimal point, like with 'f'.
8658
8659 *printf-g* *printf-G*
8660 g G The Float argument is converted like with 'f' if the
8661 value is between 0.001 (inclusive) and 10000000.0
8662 (exclusive). Otherwise 'e' is used for 'g' and 'E'
8663 for 'G'. When no precision is specified superfluous
8664 zeroes and '+' signs are removed, except for the zero
8665 immediately after the decimal point. Thus 10000000.0
8666 results in 1.0e7.
8667
8668 *printf-%*
8669 % A '%' is written. No argument is converted. The
8670 complete conversion specification is "%%".
8671
8672 When a Number argument is expected a String argument is also
8673 accepted and automatically converted.
8674 When a Float or String argument is expected a Number argument
8675 is also accepted and automatically converted.
8676 Any other argument type results in an error message.
8677
8678 *E766* *E767*
8679 The number of {exprN} arguments must exactly match the number
8680 of "%" items. If there are not sufficient or too many
8681 arguments an error is given. Up to 18 arguments can be used.
8682
8683
8684 prompt_getprompt({buf}) *prompt_getprompt()*
8685 Returns the effective prompt text for buffer {buf}. {buf} can
8686 be a buffer name or number. See |prompt-buffer|.
8687
8688 If the buffer doesn't exist or isn't a prompt buffer, an empty
8689 string is returned.
8690
8691 Can also be used as a |method|: >
8692 GetBuffer()->prompt_getprompt()
8693
8694 < {only available when compiled with the |+channel| feature}
8695
8696
8697 prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
8698 Set prompt callback for buffer {buf} to {expr}. When {expr}
8699 is an empty string the callback is removed. This has only
8700 effect if {buf} has 'buftype' set to "prompt".
8701
8702 The callback is invoked when pressing Enter. The current
8703 buffer will always be the prompt buffer. A new line for a
8704 prompt is added before invoking the callback, thus the prompt
8705 for which the callback was invoked will be in the last but one
8706 line.
8707 If the callback wants to add text to the buffer, it must
8708 insert it above the last line, since that is where the current
8709 prompt is. This can also be done asynchronously.
8710 The callback is invoked with one argument, which is the text
8711 that was entered at the prompt. This can be an empty string
8712 if the user only typed Enter.
8713 Example: >
8714 call prompt_setcallback(bufnr(), function('s:TextEntered'))
8715 func s:TextEntered(text)
8716 if a:text == 'exit' || a:text == 'quit'
8717 stopinsert
8718 close
8719 else
8720 call append(line('$') - 1, 'Entered: "' . a:text . '"')
8721 " Reset 'modified' to allow the buffer to be closed.
8722 set nomodified
8723 endif
8724 endfunc
8725
8726 < Can also be used as a |method|: >
8727 GetBuffer()->prompt_setcallback(callback)
8728
8729 < {only available when compiled with the |+channel| feature}
8730
8731 prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
8732 Set a callback for buffer {buf} to {expr}. When {expr} is an
8733 empty string the callback is removed. This has only effect if
8734 {buf} has 'buftype' set to "prompt".
8735
8736 This callback will be invoked when pressing CTRL-C in Insert
8737 mode. Without setting a callback Vim will exit Insert mode,
8738 as in any buffer.
8739
8740 Can also be used as a |method|: >
8741 GetBuffer()->prompt_setinterrupt(callback)
8742
8743 < {only available when compiled with the |+channel| feature}
8744
8745 prompt_setprompt({buf}, {text}) *prompt_setprompt()*
8746 Set prompt for buffer {buf} to {text}. You most likely want
8747 {text} to end in a space.
8748 The result is only visible if {buf} has 'buftype' set to
8749 "prompt". Example: >
8750 call prompt_setprompt(bufnr(), 'command: ')
8751 <
8752 Can also be used as a |method|: >
8753 GetBuffer()->prompt_setprompt('command: ')
8754
8755 < {only available when compiled with the |+channel| feature}
8756
8757 prop_ functions are documented here: |text-prop-functions|
8758
8759 pum_getpos() *pum_getpos()*
8760 If the popup menu (see |ins-completion-menu|) is not visible,
8761 returns an empty |Dictionary|, otherwise, returns a
8762 |Dictionary| with the following keys:
8763 height nr of items visible
8764 width screen cells
8765 row top screen row (0 first row)
8766 col leftmost screen column (0 first col)
8767 size total nr of items
8768 scrollbar |TRUE| if scrollbar is visible
8769
8770 The values are the same as in |v:event| during
8771 |CompleteChanged|.
8772
8773 pumvisible() *pumvisible()*
8774 Returns non-zero when the popup menu is visible, zero
8775 otherwise. See |ins-completion-menu|.
8776 This can be used to avoid some things that would remove the
8777 popup menu.
8778
8779 py3eval({expr}) *py3eval()*
8780 Evaluate Python expression {expr} and return its result
8781 converted to Vim data structures.
8782 Numbers and strings are returned as they are (strings are
8783 copied though, Unicode strings are additionally converted to
8784 'encoding').
8785 Lists are represented as Vim |List| type.
8786 Dictionaries are represented as Vim |Dictionary| type with
8787 keys converted to strings.
8788 Note that in a `:def` function local variables are not visible
8789 to {expr}.
8790
8791 Can also be used as a |method|: >
8792 GetExpr()->py3eval()
8793
8794 < {only available when compiled with the |+python3| feature}
8795
8796 *E858* *E859*
8797 pyeval({expr}) *pyeval()*
8798 Evaluate Python expression {expr} and return its result
8799 converted to Vim data structures.
8800 Numbers and strings are returned as they are (strings are
8801 copied though).
8802 Lists are represented as Vim |List| type.
8803 Dictionaries are represented as Vim |Dictionary| type,
8804 non-string keys result in error.
8805 Note that in a `:def` function local variables are not visible
8806 to {expr}.
8807
8808 Can also be used as a |method|: >
8809 GetExpr()->pyeval()
8810
8811 < {only available when compiled with the |+python| feature}
8812
8813 pyxeval({expr}) *pyxeval()*
8814 Evaluate Python expression {expr} and return its result
8815 converted to Vim data structures.
8816 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
8817 See also: |pyeval()|, |py3eval()|
8818
8819 Can also be used as a |method|: >
8820 GetExpr()->pyxeval()
8821
8822 < {only available when compiled with the |+python| or the
8823 |+python3| feature}
8824
8825 rand([{expr}]) *rand()* *random*
8826 Return a pseudo-random Number generated with an xoshiro128**
8827 algorithm using seed {expr}. The returned number is 32 bits,
8828 also on 64 bits systems, for consistency.
8829 {expr} can be initialized by |srand()| and will be updated by
8830 rand(). If {expr} is omitted, an internal seed value is used
8831 and updated.
8832
8833 Examples: >
8834 :echo rand()
8835 :let seed = srand()
8836 :echo rand(seed)
8837 :echo rand(seed) % 16 " random number 0 - 15
8838 <
8839
8840 *E726* *E727*
8841 range({expr} [, {max} [, {stride}]]) *range()*
8842 Returns a |List| with Numbers:
8843 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
8844 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
8845 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
8846 {max}] (increasing {expr} with {stride} each time, not
8847 producing a value past {max}).
8848 When the maximum is one before the start the result is an
8849 empty list. When the maximum is more than one before the
8850 start this is an error.
8851 Examples: >
8852 range(4) " [0, 1, 2, 3]
8853 range(2, 4) " [2, 3, 4]
8854 range(2, 9, 3) " [2, 5, 8]
8855 range(2, -2, -1) " [2, 1, 0, -1, -2]
8856 range(0) " []
8857 range(2, 0) " error!
8858 <
8859 Can also be used as a |method|: >
8860 GetExpr()->range()
8861 <
8862
8863 readblob({fname}) *readblob()*
8864 Read file {fname} in binary mode and return a |Blob|.
8865 When the file can't be opened an error message is given and
8866 the result is an empty |Blob|.
8867 Also see |readfile()| and |writefile()|.
8868
8869
8870 readdir({directory} [, {expr} [, {dict}]]) *readdir()*
8871 Return a list with file and directory names in {directory}.
8872 You can also use |glob()| if you don't need to do complicated
8873 things, such as limiting the number of matches.
8874 The list will be sorted (case sensitive), see the {dict}
8875 argument below for changing the sort order.
8876
8877 When {expr} is omitted all entries are included.
8878 When {expr} is given, it is evaluated to check what to do:
8879 If {expr} results in -1 then no further entries will
8880 be handled.
8881 If {expr} results in 0 then this entry will not be
8882 added to the list.
8883 If {expr} results in 1 then this entry will be added
8884 to the list.
8885 The entries "." and ".." are always excluded.
8886 Each time {expr} is evaluated |v:val| is set to the entry name.
8887 When {expr} is a function the name is passed as the argument.
8888 For example, to get a list of files ending in ".txt": >
8889 readdir(dirname, {n -> n =~ '.txt$'})
8890 < To skip hidden and backup files: >
8891 readdir(dirname, {n -> n !~ '^\.\|\~$'})
8892
8893 < The optional {dict} argument allows for further custom
8894 values. Currently this is used to specify if and how sorting
8895 should be performed. The dict can have the following members:
8896
8897 sort How to sort the result returned from the system.
8898 Valid values are:
8899 "none" do not sort (fastest method)
8900 "case" sort case sensitive (byte value of
8901 each character, technically, using
8902 strcmp()) (default)
8903 "icase" sort case insensitive (technically
8904 using strcasecmp())
8905 "collate" sort using the collation order
8906 of the "POSIX" or "C" |locale|
8907 (technically using strcoll())
8908 Other values are silently ignored.
8909
8910 For example, to get a list of all files in the current
8911 directory without sorting the individual entries: >
8912 readdir('.', '1', #{sort: 'none'})
8913 < If you want to get a directory tree: >
8914 function! s:tree(dir)
8915 return {a:dir : map(readdir(a:dir),
8916 \ {_, x -> isdirectory(x) ?
8917 \ {x : s:tree(a:dir . '/' . x)} : x})}
8918 endfunction
8919 echo s:tree(".")
8920 <
8921 Can also be used as a |method|: >
8922 GetDirName()->readdir()
8923 <
8924 readdirex({directory} [, {expr} [, {dict}]]) *readdirex()*
8925 Extended version of |readdir()|.
8926 Return a list of Dictionaries with file and directory
8927 information in {directory}.
8928 This is useful if you want to get the attributes of file and
8929 directory at the same time as getting a list of a directory.
8930 This is much faster than calling |readdir()| then calling
8931 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for
8932 each file and directory especially on MS-Windows.
8933 The list will by default be sorted by name (case sensitive),
8934 the sorting can be changed by using the optional {dict}
8935 argument, see |readdir()|.
8936
8937 The Dictionary for file and directory information has the
8938 following items:
8939 group Group name of the entry. (Only on Unix)
8940 name Name of the entry.
8941 perm Permissions of the entry. See |getfperm()|.
8942 size Size of the entry. See |getfsize()|.
8943 time Timestamp of the entry. See |getftime()|.
8944 type Type of the entry.
8945 On Unix, almost same as |getftype()| except:
8946 Symlink to a dir "linkd"
8947 Other symlink "link"
8948 On MS-Windows:
8949 Normal file "file"
8950 Directory "dir"
8951 Junction "junction"
8952 Symlink to a dir "linkd"
8953 Other symlink "link"
8954 Other reparse point "reparse"
8955 user User name of the entry's owner. (Only on Unix)
8956 On Unix, if the entry is a symlink, the Dictionary includes
8957 the information of the target (except the "type" item).
8958 On MS-Windows, it includes the information of the symlink
8959 itself because of performance reasons.
8960
8961 When {expr} is omitted all entries are included.
8962 When {expr} is given, it is evaluated to check what to do:
8963 If {expr} results in -1 then no further entries will
8964 be handled.
8965 If {expr} results in 0 then this entry will not be
8966 added to the list.
8967 If {expr} results in 1 then this entry will be added
8968 to the list.
8969 The entries "." and ".." are always excluded.
8970 Each time {expr} is evaluated |v:val| is set to a |Dictionary|
8971 of the entry.
8972 When {expr} is a function the entry is passed as the argument.
8973 For example, to get a list of files ending in ".txt": >
8974 readdirex(dirname, {e -> e.name =~ '.txt$'})
8975 <
8976 For example, to get a list of all files in the current
8977 directory without sorting the individual entries: >
8978 readdirex(dirname, '1', #{sort: 'none'})
8979
8980 <
8981 Can also be used as a |method|: >
8982 GetDirName()->readdirex()
8983 <
8984
8985 *readfile()*
8986 readfile({fname} [, {type} [, {max}]])
8987 Read file {fname} and return a |List|, each line of the file
8988 as an item. Lines are broken at NL characters. Macintosh
8989 files separated with CR will result in a single long line
8990 (unless a NL appears somewhere).
8991 All NUL characters are replaced with a NL character.
8992 When {type} contains "b" binary mode is used:
8993 - When the last line ends in a NL an extra empty list item is
8994 added.
8995 - No CR characters are removed.
8996 Otherwise:
8997 - CR characters that appear before a NL are removed.
8998 - Whether the last line ends in a NL or not does not matter.
8999 - When 'encoding' is Unicode any UTF-8 byte order mark is
9000 removed from the text.
9001 When {max} is given this specifies the maximum number of lines
9002 to be read. Useful if you only want to check the first ten
9003 lines of a file: >
9004 :for line in readfile(fname, '', 10)
9005 : if line =~ 'Date' | echo line | endif
9006 :endfor
9007 < When {max} is negative -{max} lines from the end of the file
9008 are returned, or as many as there are.
9009 When {max} is zero the result is an empty list.
9010 Note that without {max} the whole file is read into memory.
9011 Also note that there is no recognition of encoding. Read a
9012 file into a buffer if you need to.
9013 Deprecated (use |readblob()| instead): When {type} contains
9014 "B" a |Blob| is returned with the binary data of the file
9015 unmodified.
9016 When the file can't be opened an error message is given and
9017 the result is an empty list.
9018 Also see |writefile()|.
9019
9020 Can also be used as a |method|: >
9021 GetFileName()->readfile()
9022
9023 reduce({object}, {func} [, {initial}]) *reduce()* *E998*
9024 {func} is called for every item in {object}, which can be a
9025 |String|, |List| or a |Blob|. {func} is called with two
9026 arguments: the result so far and current item. After
9027 processing all items the result is returned.
9028
9029 {initial} is the initial result. When omitted, the first item
9030 in {object} is used and {func} is first called for the second
9031 item. If {initial} is not given and {object} is empty no
9032 result can be computed, an E998 error is given.
9033
9034 Examples: >
9035 echo reduce([1, 3, 5], { acc, val -> acc + val })
9036 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a')
9037 echo reduce(0z1122, { acc, val -> 2 * acc + val })
9038 echo reduce('xyz', { acc, val -> acc .. ',' .. val })
9039 <
9040 Can also be used as a |method|: >
9041 echo mylist->reduce({ acc, val -> acc + val }, 0)
9042
9043
9044 reg_executing() *reg_executing()*
9045 Returns the single letter name of the register being executed.
9046 Returns an empty string when no register is being executed.
9047 See |@|.
9048
9049 reg_recording() *reg_recording()*
9050 Returns the single letter name of the register being recorded.
9051 Returns an empty string when not recording. See |q|.
9052
9053 reltime([{start} [, {end}]]) *reltime()*
9054 Return an item that represents a time value. The item is a
9055 list with items that depend on the system. In Vim 9 script
9056 list<any> can be used.
9057 The item can be passed to |reltimestr()| to convert it to a
9058 string or |reltimefloat()| to convert to a Float.
9059
9060 Without an argument reltime() returns the current time.
9061 With one argument is returns the time passed since the time
9062 specified in the argument.
9063 With two arguments it returns the time passed between {start}
9064 and {end}.
9065
9066 The {start} and {end} arguments must be values returned by
9067 reltime(). If there is an error zero is returned in legacy
9068 script, in Vim9 script an error is given.
9069
9070 Can also be used as a |method|: >
9071 GetStart()->reltime()
9072 <
9073 {only available when compiled with the |+reltime| feature}
9074
9075 reltimefloat({time}) *reltimefloat()*
9076 Return a Float that represents the time value of {time}.
9077 Example: >
9078 let start = reltime()
9079 call MyFunction()
9080 let seconds = reltimefloat(reltime(start))
9081 < See the note of reltimestr() about overhead.
9082 Also see |profiling|.
9083 If there is an error 0.0 is returned in legacy script, in Vim9
9084 script an error is given.
9085
9086 Can also be used as a |method|: >
9087 reltime(start)->reltimefloat()
9088
9089 < {only available when compiled with the |+reltime| feature}
9090
9091 reltimestr({time}) *reltimestr()*
9092 Return a String that represents the time value of {time}.
9093 This is the number of seconds, a dot and the number of
9094 microseconds. Example: >
9095 let start = reltime()
9096 call MyFunction()
9097 echo reltimestr(reltime(start))
9098 < Note that overhead for the commands will be added to the time.
9099 The accuracy depends on the system.
9100 Leading spaces are used to make the string align nicely. You
9101 can use split() to remove it. >
9102 echo split(reltimestr(reltime(start)))[0]
9103 < Also see |profiling|.
9104 If there is an error an empty string is returned in legacy
9105 script, in Vim9 script an error is given.
9106
9107 Can also be used as a |method|: >
9108 reltime(start)->reltimestr()
9109
9110 < {only available when compiled with the |+reltime| feature}
9111
9112 *remote_expr()* *E449*
9113 remote_expr({server}, {string} [, {idvar} [, {timeout}]])
9114 Send the {string} to {server}. The string is sent as an
9115 expression and the result is returned after evaluation.
9116 The result must be a String or a |List|. A |List| is turned
9117 into a String by joining the items with a line break in
9118 between (not at the end), like with join(expr, "\n").
9119 If {idvar} is present and not empty, it is taken as the name
9120 of a variable and a {serverid} for later use with
9121 |remote_read()| is stored there.
9122 If {timeout} is given the read times out after this many
9123 seconds. Otherwise a timeout of 600 seconds is used.
9124 See also |clientserver| |RemoteReply|.
9125 This function is not available in the |sandbox|.
9126 {only available when compiled with the |+clientserver| feature}
9127 Note: Any errors will cause a local error message to be issued
9128 and the result will be the empty string.
9129
9130 Variables will be evaluated in the global namespace,
9131 independent of a function currently being active. Except
9132 when in debug mode, then local function variables and
9133 arguments can be evaluated.
9134
9135 Examples: >
9136 :echo remote_expr("gvim", "2+2")
9137 :echo remote_expr("gvim1", "b:current_syntax")
9138 <
9139 Can also be used as a |method|: >
9140 ServerName()->remote_expr(expr)
9141
9142 remote_foreground({server}) *remote_foreground()*
9143 Move the Vim server with the name {server} to the foreground.
9144 The {server} argument is a string.
9145 This works like: >
9146 remote_expr({server}, "foreground()")
9147 < Except that on Win32 systems the client does the work, to work
9148 around the problem that the OS doesn't always allow the server
9149 to bring itself to the foreground.
9150 Note: This does not restore the window if it was minimized,
9151 like foreground() does.
9152 This function is not available in the |sandbox|.
9153
9154 Can also be used as a |method|: >
9155 ServerName()->remote_foreground()
9156
9157 < {only in the Win32, Athena, Motif and GTK GUI versions and the
9158 Win32 console version}
9159
9160
9161 remote_peek({serverid} [, {retvar}]) *remote_peek()*
9162 Returns a positive number if there are available strings
9163 from {serverid}. Copies any reply string into the variable
9164 {retvar} if specified. {retvar} must be a string with the
9165 name of a variable.
9166 Returns zero if none are available.
9167 Returns -1 if something is wrong.
9168 See also |clientserver|.
9169 This function is not available in the |sandbox|.
9170 {only available when compiled with the |+clientserver| feature}
9171 Examples: >
9172 :let repl = ""
9173 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
9174
9175 < Can also be used as a |method|: >
9176 ServerId()->remote_peek()
9177
9178 remote_read({serverid}, [{timeout}]) *remote_read()*
9179 Return the oldest available reply from {serverid} and consume
9180 it. Unless a {timeout} in seconds is given, it blocks until a
9181 reply is available.
9182 See also |clientserver|.
9183 This function is not available in the |sandbox|.
9184 {only available when compiled with the |+clientserver| feature}
9185 Example: >
9186 :echo remote_read(id)
9187
9188 < Can also be used as a |method|: >
9189 ServerId()->remote_read()
9190 <
9191 *remote_send()* *E241*
9192 remote_send({server}, {string} [, {idvar}])
9193 Send the {string} to {server}. The string is sent as input
9194 keys and the function returns immediately. At the Vim server
9195 the keys are not mapped |:map|.
9196 If {idvar} is present, it is taken as the name of a variable
9197 and a {serverid} for later use with remote_read() is stored
9198 there.
9199 See also |clientserver| |RemoteReply|.
9200 This function is not available in the |sandbox|.
9201 {only available when compiled with the |+clientserver| feature}
9202
9203 Note: Any errors will be reported in the server and may mess
9204 up the display.
9205 Examples: >
9206 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
9207 \ remote_read(serverid)
9208
9209 :autocmd NONE RemoteReply *
9210 \ echo remote_read(expand("<amatch>"))
9211 :echo remote_send("gvim", ":sleep 10 | echo ".
9212 \ 'server2client(expand("<client>"), "HELLO")<CR>')
9213 <
9214 Can also be used as a |method|: >
9215 ServerName()->remote_send(keys)
9216 <
9217 *remote_startserver()* *E941* *E942*
9218 remote_startserver({name})
9219 Become the server {name}. This fails if already running as a
9220 server, when |v:servername| is not empty.
9221
9222 Can also be used as a |method|: >
9223 ServerName()->remote_startserver()
9224
9225 < {only available when compiled with the |+clientserver| feature}
9226
9227 remove({list}, {idx} [, {end}]) *remove()*
9228 Without {end}: Remove the item at {idx} from |List| {list} and
9229 return the item.
9230 With {end}: Remove items from {idx} to {end} (inclusive) and
9231 return a |List| with these items. When {idx} points to the same
9232 item as {end} a list with one item is returned. When {end}
9233 points to an item before {idx} this is an error.
9234 See |list-index| for possible values of {idx} and {end}.
9235 Example: >
9236 :echo "last item: " . remove(mylist, -1)
9237 :call remove(mylist, 0, 9)
9238 <
9239 Use |delete()| to remove a file.
9240
9241 Can also be used as a |method|: >
9242 mylist->remove(idx)
9243
9244 remove({blob}, {idx} [, {end}])
9245 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
9246 return the byte.
9247 With {end}: Remove bytes from {idx} to {end} (inclusive) and
9248 return a |Blob| with these bytes. When {idx} points to the same
9249 byte as {end} a |Blob| with one byte is returned. When {end}
9250 points to a byte before {idx} this is an error.
9251 Example: >
9252 :echo "last byte: " . remove(myblob, -1)
9253 :call remove(mylist, 0, 9)
9254
9255 remove({dict}, {key})
9256 Remove the entry from {dict} with key {key} and return it.
9257 Example: >
9258 :echo "removed " . remove(dict, "one")
9259 < If there is no {key} in {dict} this is an error.
9260
9261 rename({from}, {to}) *rename()*
9262 Rename the file by the name {from} to the name {to}. This
9263 should also work to move files across file systems. The
9264 result is a Number, which is 0 if the file was renamed
9265 successfully, and non-zero when the renaming failed.
9266 NOTE: If {to} exists it is overwritten without warning.
9267 This function is not available in the |sandbox|.
9268
9269 Can also be used as a |method|: >
9270 GetOldName()->rename(newname)
9271
9272 repeat({expr}, {count}) *repeat()*
9273 Repeat {expr} {count} times and return the concatenated
9274 result. Example: >
9275 :let separator = repeat('-', 80)
9276 < When {count} is zero or negative the result is empty.
9277 When {expr} is a |List| the result is {expr} concatenated
9278 {count} times. Example: >
9279 :let longlist = repeat(['a', 'b'], 3)
9280 < Results in ['a', 'b', 'a', 'b', 'a', 'b'].
9281
9282 Can also be used as a |method|: >
9283 mylist->repeat(count)
9284
9285 resolve({filename}) *resolve()* *E655*
9286 On MS-Windows, when {filename} is a shortcut (a .lnk file),
9287 returns the path the shortcut points to in a simplified form.
9288 When {filename} is a symbolic link or junction point, return
9289 the full path to the target. If the target of junction is
9290 removed, return {filename}.
9291 On Unix, repeat resolving symbolic links in all path
9292 components of {filename} and return the simplified result.
9293 To cope with link cycles, resolving of symbolic links is
9294 stopped after 100 iterations.
9295 On other systems, return the simplified {filename}.
9296 The simplification step is done as by |simplify()|.
9297 resolve() keeps a leading path component specifying the
9298 current directory (provided the result is still a relative
9299 path name) and also keeps a trailing path separator.
9300
9301 Can also be used as a |method|: >
9302 GetName()->resolve()
9303
9304 reverse({object}) *reverse()*
9305 Reverse the order of items in {object} in-place.
9306 {object} can be a |List| or a |Blob|.
9307 Returns {object}.
9308 If you want an object to remain unmodified make a copy first: >
9309 :let revlist = reverse(copy(mylist))
9310 < Can also be used as a |method|: >
9311 mylist->reverse()
9312
9313 round({expr}) *round()*
9314 Round off {expr} to the nearest integral value and return it
9315 as a |Float|. If {expr} lies halfway between two integral
9316 values, then use the larger one (away from zero).
9317 {expr} must evaluate to a |Float| or a |Number|.
9318 Examples: >
9319 echo round(0.456)
9320 < 0.0 >
9321 echo round(4.5)
9322 < 5.0 >
9323 echo round(-4.5)
9324 < -5.0
9325
9326 Can also be used as a |method|: >
9327 Compute()->round()
9328 <
9329 {only available when compiled with the |+float| feature}
9330
9331 rubyeval({expr}) *rubyeval()*
9332 Evaluate Ruby expression {expr} and return its result
9333 converted to Vim data structures.
9334 Numbers, floats and strings are returned as they are (strings
9335 are copied though).
9336 Arrays are represented as Vim |List| type.
9337 Hashes are represented as Vim |Dictionary| type.
9338 Other objects are represented as strings resulted from their
9339 "Object#to_s" method.
9340 Note that in a `:def` function local variables are not visible
9341 to {expr}.
9342
9343 Can also be used as a |method|: >
9344 GetRubyExpr()->rubyeval()
9345
9346 < {only available when compiled with the |+ruby| feature}
9347
9348 screenattr({row}, {col}) *screenattr()*
9349 Like |screenchar()|, but return the attribute. This is a rather
9350 arbitrary number that can only be used to compare to the
9351 attribute at other positions.
9352
9353 Can also be used as a |method|: >
9354 GetRow()->screenattr(col)
9355
9356 screenchar({row}, {col}) *screenchar()*
9357 The result is a Number, which is the character at position
9358 [row, col] on the screen. This works for every possible
9359 screen position, also status lines, window separators and the
9360 command line. The top left position is row one, column one
9361 The character excludes composing characters. For double-byte
9362 encodings it may only be the first byte.
9363 This is mainly to be used for testing.
9364 Returns -1 when row or col is out of range.
9365
9366 Can also be used as a |method|: >
9367 GetRow()->screenchar(col)
9368
9369 screenchars({row}, {col}) *screenchars()*
9370 The result is a |List| of Numbers. The first number is the same
9371 as what |screenchar()| returns. Further numbers are
9372 composing characters on top of the base character.
9373 This is mainly to be used for testing.
9374 Returns an empty List when row or col is out of range.
9375
9376 Can also be used as a |method|: >
9377 GetRow()->screenchars(col)
9378
9379 screencol() *screencol()*
9380 The result is a Number, which is the current screen column of
9381 the cursor. The leftmost column has number 1.
9382 This function is mainly used for testing.
9383
9384 Note: Always returns the current screen column, thus if used
9385 in a command (e.g. ":echo screencol()") it will return the
9386 column inside the command line, which is 1 when the command is
9387 executed. To get the cursor position in the file use one of
9388 the following mappings: >
9389 nnoremap <expr> GG ":echom ".screencol()."\n"
9390 nnoremap <silent> GG :echom screencol()<CR>
9391 nnoremap GG <Cmd>echom screencol()<CR>
9392 <
9393 screenpos({winid}, {lnum}, {col}) *screenpos()*
9394 The result is a Dict with the screen position of the text
9395 character in window {winid} at buffer line {lnum} and column
9396 {col}. {col} is a one-based byte index.
9397 The Dict has these members:
9398 row screen row
9399 col first screen column
9400 endcol last screen column
9401 curscol cursor screen column
9402 If the specified position is not visible, all values are zero.
9403 The "endcol" value differs from "col" when the character
9404 occupies more than one screen cell. E.g. for a Tab "col" can
9405 be 1 and "endcol" can be 8.
9406 The "curscol" value is where the cursor would be placed. For
9407 a Tab it would be the same as "endcol", while for a double
9408 width character it would be the same as "col".
9409 The |conceal| feature is ignored here, the column numbers are
9410 as if 'conceallevel' is zero. You can set the cursor to the
9411 right position and use |screencol()| to get the value with
9412 |conceal| taken into account.
9413
9414 Can also be used as a |method|: >
9415 GetWinid()->screenpos(lnum, col)
9416
9417 screenrow() *screenrow()*
9418 The result is a Number, which is the current screen row of the
9419 cursor. The top line has number one.
9420 This function is mainly used for testing.
9421 Alternatively you can use |winline()|.
9422
9423 Note: Same restrictions as with |screencol()|.
9424
9425 screenstring({row}, {col}) *screenstring()*
9426 The result is a String that contains the base character and
9427 any composing characters at position [row, col] on the screen.
9428 This is like |screenchars()| but returning a String with the
9429 characters.
9430 This is mainly to be used for testing.
9431 Returns an empty String when row or col is out of range.
9432
9433 Can also be used as a |method|: >
9434 GetRow()->screenstring(col)
9435 <
9436 *search()*
9437 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9438 Search for regexp pattern {pattern}. The search starts at the
9439 cursor position (you can use |cursor()| to set it).
9440
9441 When a match has been found its line number is returned.
9442 If there is no match a 0 is returned and the cursor doesn't
9443 move. No error message is given.
9444
9445 {flags} is a String, which can contain these character flags:
9446 'b' search Backward instead of forward
9447 'c' accept a match at the Cursor position
9448 'e' move to the End of the match
9449 'n' do Not move the cursor
9450 'p' return number of matching sub-Pattern (see below)
9451 's' Set the ' mark at the previous location of the cursor
9452 'w' Wrap around the end of the file
9453 'W' don't Wrap around the end of the file
9454 'z' start searching at the cursor column instead of zero
9455 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
9456
9457 If the 's' flag is supplied, the ' mark is set, only if the
9458 cursor is moved. The 's' flag cannot be combined with the 'n'
9459 flag.
9460
9461 'ignorecase', 'smartcase' and 'magic' are used.
9462
9463 When the 'z' flag is not given, forward searching always
9464 starts in column zero and then matches before the cursor are
9465 skipped. When the 'c' flag is present in 'cpo' the next
9466 search starts after the match. Without the 'c' flag the next
9467 search starts one column further. This matters for
9468 overlapping matches.
9469 When searching backwards and the 'z' flag is given then the
9470 search starts in column zero, thus no match in the current
9471 line will be found (unless wrapping around the end of the
9472 file).
9473
9474 When the {stopline} argument is given then the search stops
9475 after searching this line. This is useful to restrict the
9476 search to a range of lines. Examples: >
9477 let match = search('(', 'b', line("w0"))
9478 let end = search('END', '', line("w$"))
9479 < When {stopline} is used and it is not zero this also implies
9480 that the search does not wrap around the end of the file.
9481 A zero value is equal to not giving the argument.
9482
9483 When the {timeout} argument is given the search stops when
9484 more than this many milliseconds have passed. Thus when
9485 {timeout} is 500 the search stops after half a second.
9486 The value must not be negative. A zero value is like not
9487 giving the argument.
9488 {only available when compiled with the |+reltime| feature}
9489
9490 If the {skip} expression is given it is evaluated with the
9491 cursor positioned on the start of a match. If it evaluates to
9492 non-zero this match is skipped. This can be used, for
9493 example, to skip a match in a comment or a string.
9494 {skip} can be a string, which is evaluated as an expression, a
9495 function reference or a lambda.
9496 When {skip} is omitted or empty, every match is accepted.
9497 When evaluating {skip} causes an error the search is aborted
9498 and -1 returned.
9499 *search()-sub-match*
9500 With the 'p' flag the returned value is one more than the
9501 first sub-match in \(\). One if none of them matched but the
9502 whole pattern did match.
9503 To get the column number too use |searchpos()|.
9504
9505 The cursor will be positioned at the match, unless the 'n'
9506 flag is used.
9507
9508 Example (goes over all files in the argument list): >
9509 :let n = 1
9510 :while n <= argc() " loop over all files in arglist
9511 : exe "argument " . n
9512 : " start at the last char in the file and wrap for the
9513 : " first search to find match at start of file
9514 : normal G$
9515 : let flags = "w"
9516 : while search("foo", flags) > 0
9517 : s/foo/bar/g
9518 : let flags = "W"
9519 : endwhile
9520 : update " write the file if modified
9521 : let n = n + 1
9522 :endwhile
9523 <
9524 Example for using some flags: >
9525 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
9526 < This will search for the keywords "if", "else", and "endif"
9527 under or after the cursor. Because of the 'p' flag, it
9528 returns 1, 2, or 3 depending on which keyword is found, or 0
9529 if the search fails. With the cursor on the first word of the
9530 line:
9531 if (foo == 0) | let foo = foo + 1 | endif ~
9532 the function returns 1. Without the 'c' flag, the function
9533 finds the "endif" and returns 3. The same thing happens
9534 without the 'e' flag if the cursor is on the "f" of "if".
9535 The 'n' flag tells the function not to move the cursor.
9536
9537 Can also be used as a |method|: >
9538 GetPattern()->search()
9539
9540 searchcount([{options}]) *searchcount()*
9541 Get or update the last search count, like what is displayed
9542 without the "S" flag in 'shortmess'. This works even if
9543 'shortmess' does contain the "S" flag.
9544
9545 This returns a |Dictionary|. The dictionary is empty if the
9546 previous pattern was not set and "pattern" was not specified.
9547
9548 key type meaning ~
9549 current |Number| current position of match;
9550 0 if the cursor position is
9551 before the first match
9552 exact_match |Boolean| 1 if "current" is matched on
9553 "pos", otherwise 0
9554 total |Number| total count of matches found
9555 incomplete |Number| 0: search was fully completed
9556 1: recomputing was timed out
9557 2: max count exceeded
9558
9559 For {options} see further down.
9560
9561 To get the last search count when |n| or |N| was pressed, call
9562 this function with `recompute: 0` . This sometimes returns
9563 wrong information because |n| and |N|'s maximum count is 99.
9564 If it exceeded 99 the result must be max count + 1 (100). If
9565 you want to get correct information, specify `recompute: 1`: >
9566
9567 " result == maxcount + 1 (100) when many matches
9568 let result = searchcount(#{recompute: 0})
9569
9570 " Below returns correct result (recompute defaults
9571 " to 1)
9572 let result = searchcount()
9573 <
9574 The function is useful to add the count to |statusline|: >
9575 function! LastSearchCount() abort
9576 let result = searchcount(#{recompute: 0})
9577 if empty(result)
9578 return ''
9579 endif
9580 if result.incomplete ==# 1 " timed out
9581 return printf(' /%s [?/??]', @/)
9582 elseif result.incomplete ==# 2 " max count exceeded
9583 if result.total > result.maxcount &&
9584 \ result.current > result.maxcount
9585 return printf(' /%s [>%d/>%d]', @/,
9586 \ result.current, result.total)
9587 elseif result.total > result.maxcount
9588 return printf(' /%s [%d/>%d]', @/,
9589 \ result.current, result.total)
9590 endif
9591 endif
9592 return printf(' /%s [%d/%d]', @/,
9593 \ result.current, result.total)
9594 endfunction
9595 let &statusline .= '%{LastSearchCount()}'
9596
9597 " Or if you want to show the count only when
9598 " 'hlsearch' was on
9599 " let &statusline .=
9600 " \ '%{v:hlsearch ? LastSearchCount() : ""}'
9601 <
9602 You can also update the search count, which can be useful in a
9603 |CursorMoved| or |CursorMovedI| autocommand: >
9604
9605 autocmd CursorMoved,CursorMovedI *
9606 \ let s:searchcount_timer = timer_start(
9607 \ 200, function('s:update_searchcount'))
9608 function! s:update_searchcount(timer) abort
9609 if a:timer ==# s:searchcount_timer
9610 call searchcount(#{
9611 \ recompute: 1, maxcount: 0, timeout: 100})
9612 redrawstatus
9613 endif
9614 endfunction
9615 <
9616 This can also be used to count matched texts with specified
9617 pattern in the current buffer using "pattern": >
9618
9619 " Count '\<foo\>' in this buffer
9620 " (Note that it also updates search count)
9621 let result = searchcount(#{pattern: '\<foo\>'})
9622
9623 " To restore old search count by old pattern,
9624 " search again
9625 call searchcount()
9626 <
9627 {options} must be a |Dictionary|. It can contain:
9628 key type meaning ~
9629 recompute |Boolean| if |TRUE|, recompute the count
9630 like |n| or |N| was executed.
9631 otherwise returns the last
9632 computed result (when |n| or
9633 |N| was used when "S" is not
9634 in 'shortmess', or this
9635 function was called).
9636 (default: |TRUE|)
9637 pattern |String| recompute if this was given
9638 and different with |@/|.
9639 this works as same as the
9640 below command is executed
9641 before calling this function >
9642 let @/ = pattern
9643 < (default: |@/|)
9644 timeout |Number| 0 or negative number is no
9645 timeout. timeout milliseconds
9646 for recomputing the result
9647 (default: 0)
9648 maxcount |Number| 0 or negative number is no
9649 limit. max count of matched
9650 text while recomputing the
9651 result. if search exceeded
9652 total count, "total" value
9653 becomes `maxcount + 1`
9654 (default: 99)
9655 pos |List| `[lnum, col, off]` value
9656 when recomputing the result.
9657 this changes "current" result
9658 value. see |cursor()|,
9659 |getpos()|
9660 (default: cursor's position)
9661
9662 Can also be used as a |method|: >
9663 GetSearchOpts()->searchcount()
9664 <
9665 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
9666 Search for the declaration of {name}.
9667
9668 With a non-zero {global} argument it works like |gD|, find
9669 first match in the file. Otherwise it works like |gd|, find
9670 first match in the function.
9671
9672 With a non-zero {thisblock} argument matches in a {} block
9673 that ends before the cursor position are ignored. Avoids
9674 finding variable declarations only valid in another scope.
9675
9676 Moves the cursor to the found match.
9677 Returns zero for success, non-zero for failure.
9678 Example: >
9679 if searchdecl('myvar') == 0
9680 echo getline('.')
9681 endif
9682 <
9683 Can also be used as a |method|: >
9684 GetName()->searchdecl()
9685 <
9686 *searchpair()*
9687 searchpair({start}, {middle}, {end} [, {flags} [, {skip}
9688 [, {stopline} [, {timeout}]]]])
9689 Search for the match of a nested start-end pair. This can be
9690 used to find the "endif" that matches an "if", while other
9691 if/endif pairs in between are ignored.
9692 The search starts at the cursor. The default is to search
9693 forward, include 'b' in {flags} to search backward.
9694 If a match is found, the cursor is positioned at it and the
9695 line number is returned. If no match is found 0 or -1 is
9696 returned and the cursor doesn't move. No error message is
9697 given.
9698
9699 {start}, {middle} and {end} are patterns, see |pattern|. They
9700 must not contain \( \) pairs. Use of \%( \) is allowed. When
9701 {middle} is not empty, it is found when searching from either
9702 direction, but only when not in a nested start-end pair. A
9703 typical use is: >
9704 searchpair('\<if\>', '\<else\>', '\<endif\>')
9705 < By leaving {middle} empty the "else" is skipped.
9706
9707 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
9708 |search()|. Additionally:
9709 'r' Repeat until no more matches found; will find the
9710 outer pair. Implies the 'W' flag.
9711 'm' Return number of matches instead of line number with
9712 the match; will be > 1 when 'r' is used.
9713 Note: it's nearly always a good idea to use the 'W' flag, to
9714 avoid wrapping around the end of the file.
9715
9716 When a match for {start}, {middle} or {end} is found, the
9717 {skip} expression is evaluated with the cursor positioned on
9718 the start of the match. It should return non-zero if this
9719 match is to be skipped. E.g., because it is inside a comment
9720 or a string.
9721 When {skip} is omitted or empty, every match is accepted.
9722 When evaluating {skip} causes an error the search is aborted
9723 and -1 returned.
9724 {skip} can be a string, a lambda, a funcref or a partial.
9725 Anything else makes the function fail.
9726 In a `:def` function when the {skip} argument is a string
9727 constant it is compiled into instructions.
9728
9729 For {stopline} and {timeout} see |search()|.
9730
9731 The value of 'ignorecase' is used. 'magic' is ignored, the
9732 patterns are used like it's on.
9733
9734 The search starts exactly at the cursor. A match with
9735 {start}, {middle} or {end} at the next character, in the
9736 direction of searching, is the first one found. Example: >
9737 if 1
9738 if 2
9739 endif 2
9740 endif 1
9741 < When starting at the "if 2", with the cursor on the "i", and
9742 searching forwards, the "endif 2" is found. When starting on
9743 the character just before the "if 2", the "endif 1" will be
9744 found. That's because the "if 2" will be found first, and
9745 then this is considered to be a nested if/endif from "if 2" to
9746 "endif 2".
9747 When searching backwards and {end} is more than one character,
9748 it may be useful to put "\zs" at the end of the pattern, so
9749 that when the cursor is inside a match with the end it finds
9750 the matching start.
9751
9752 Example, to find the "endif" command in a Vim script: >
9753
9754 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
9755 \ 'getline(".") =~ "^\\s*\""')
9756
9757 < The cursor must be at or after the "if" for which a match is
9758 to be found. Note that single-quote strings are used to avoid
9759 having to double the backslashes. The skip expression only
9760 catches comments at the start of a line, not after a command.
9761 Also, a word "en" or "if" halfway a line is considered a
9762 match.
9763 Another example, to search for the matching "{" of a "}": >
9764
9765 :echo searchpair('{', '', '}', 'bW')
9766
9767 < This works when the cursor is at or before the "}" for which a
9768 match is to be found. To reject matches that syntax
9769 highlighting recognized as strings: >
9770
9771 :echo searchpair('{', '', '}', 'bW',
9772 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
9773 <
9774 *searchpairpos()*
9775 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
9776 [, {stopline} [, {timeout}]]]])
9777 Same as |searchpair()|, but returns a |List| with the line and
9778 column position of the match. The first element of the |List|
9779 is the line number and the second element is the byte index of
9780 the column position of the match. If no match is found,
9781 returns [0, 0]. >
9782
9783 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
9784 <
9785 See |match-parens| for a bigger and more useful example.
9786
9787 *searchpos()*
9788 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
9789 Same as |search()|, but returns a |List| with the line and
9790 column position of the match. The first element of the |List|
9791 is the line number and the second element is the byte index of
9792 the column position of the match. If no match is found,
9793 returns [0, 0].
9794 Example: >
9795 :let [lnum, col] = searchpos('mypattern', 'n')
9796
9797 < When the 'p' flag is given then there is an extra item with
9798 the sub-pattern match number |search()-sub-match|. Example: >
9799 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
9800 < In this example "submatch" is 2 when a lowercase letter is
9801 found |/\l|, 3 when an uppercase letter is found |/\u|.
9802
9803 Can also be used as a |method|: >
9804 GetPattern()->searchpos()
9805
9806 server2client({clientid}, {string}) *server2client()*
9807 Send a reply string to {clientid}. The most recent {clientid}
9808 that sent a string can be retrieved with expand("<client>").
9809 {only available when compiled with the |+clientserver| feature}
9810 Returns zero for success, -1 for failure.
9811 Note:
9812 This id has to be stored before the next command can be
9813 received. I.e. before returning from the received command and
9814 before calling any commands that waits for input.
9815 See also |clientserver|.
9816 Example: >
9817 :echo server2client(expand("<client>"), "HELLO")
9818
9819 < Can also be used as a |method|: >
9820 GetClientId()->server2client(string)
9821 <
9822 serverlist() *serverlist()*
9823 Return a list of available server names, one per line.
9824 When there are no servers or the information is not available
9825 an empty string is returned. See also |clientserver|.
9826 {only available when compiled with the |+clientserver| feature}
9827 Example: >
9828 :echo serverlist()
9829 <
9830 setbufline({buf}, {lnum}, {text}) *setbufline()*
9831 Set line {lnum} to {text} in buffer {buf}. This works like
9832 |setline()| for the specified buffer.
9833
9834 This function works only for loaded buffers. First call
9835 |bufload()| if needed.
9836
9837 To insert lines use |appendbufline()|.
9838 Any text properties in {lnum} are cleared.
9839
9840 {text} can be a string to set one line, or a list of strings
9841 to set multiple lines. If the list extends below the last
9842 line then those lines are added.
9843
9844 For the use of {buf}, see |bufname()| above.
9845
9846 {lnum} is used like with |setline()|.
9847 Use "$" to refer to the last line in buffer {buf}.
9848 When {lnum} is just below the last line the {text} will be
9849 added below the last line.
9850
9851 When {buf} is not a valid buffer, the buffer is not loaded or
9852 {lnum} is not valid then 1 is returned. On success 0 is
9853 returned.
9854
9855 Can also be used as a |method|, the base is passed as the
9856 third argument: >
9857 GetText()->setbufline(buf, lnum)
9858
9859 setbufvar({buf}, {varname}, {val}) *setbufvar()*
9860 Set option or local variable {varname} in buffer {buf} to
9861 {val}.
9862 This also works for a global or local window option, but it
9863 doesn't work for a global or local window variable.
9864 For a local window option the global value is unchanged.
9865 For the use of {buf}, see |bufname()| above.
9866 The {varname} argument is a string.
9867 Note that the variable name without "b:" must be used.
9868 Examples: >
9869 :call setbufvar(1, "&mod", 1)
9870 :call setbufvar("todo", "myvar", "foobar")
9871 < This function is not available in the |sandbox|.
9872
9873 Can also be used as a |method|, the base is passed as the
9874 third argument: >
9875 GetValue()->setbufvar(buf, varname)
9876
9877
9878 setcellwidths({list}) *setcellwidths()*
9879 Specify overrides for cell widths of character ranges. This
9880 tells Vim how wide characters are, counted in screen cells.
9881 This overrides 'ambiwidth'. Example: >
9882 setcellwidths([[0xad, 0xad, 1],
9883 \ [0x2194, 0x2199, 2]])
9884
9885 < *E1109* *E1110* *E1111* *E1112* *E1113*
9886 The {list} argument is a list of lists with each three
9887 numbers. These three numbers are [low, high, width]. "low"
9888 and "high" can be the same, in which case this refers to one
9889 character. Otherwise it is the range of characters from "low"
9890 to "high" (inclusive). "width" is either 1 or 2, indicating
9891 the character width in screen cells.
9892 An error is given if the argument is invalid, also when a
9893 range overlaps with another.
9894 Only characters with value 0x100 and higher can be used.
9895
9896 If the new value causes 'fillchars' or 'listchars' to become
9897 invalid it is rejected and an error is given.
9898
9899 To clear the overrides pass an empty list: >
9900 setcellwidths([]);
9901 < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see
9902 the effect for known emoji characters.
9903
9904 setcharpos({expr}, {list}) *setcharpos()*
9905 Same as |setpos()| but uses the specified column number as the
9906 character index instead of the byte index in the line.
9907
9908 Example:
9909 With the text "여보세요" in line 8: >
9910 call setcharpos('.', [0, 8, 4, 0])
9911 < positions the cursor on the fourth character '요'. >
9912 call setpos('.', [0, 8, 4, 0])
9913 < positions the cursor on the second character '보'.
9914
9915 Can also be used as a |method|: >
9916 GetPosition()->setcharpos('.')
9917
9918 setcharsearch({dict}) *setcharsearch()*
9919 Set the current character search information to {dict},
9920 which contains one or more of the following entries:
9921
9922 char character which will be used for a subsequent
9923 |,| or |;| command; an empty string clears the
9924 character search
9925 forward direction of character search; 1 for forward,
9926 0 for backward
9927 until type of character search; 1 for a |t| or |T|
9928 character search, 0 for an |f| or |F|
9929 character search
9930
9931 This can be useful to save/restore a user's character search
9932 from a script: >
9933 :let prevsearch = getcharsearch()
9934 :" Perform a command which clobbers user's search
9935 :call setcharsearch(prevsearch)
9936 < Also see |getcharsearch()|.
9937
9938 Can also be used as a |method|: >
9939 SavedSearch()->setcharsearch()
9940
9941 setcmdpos({pos}) *setcmdpos()*
9942 Set the cursor position in the command line to byte position
9943 {pos}. The first position is 1.
9944 Use |getcmdpos()| to obtain the current position.
9945 Only works while editing the command line, thus you must use
9946 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
9947 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
9948 set after the command line is set to the expression. For
9949 |c_CTRL-R_=| it is set after evaluating the expression but
9950 before inserting the resulting text.
9951 When the number is too big the cursor is put at the end of the
9952 line. A number smaller than one has undefined results.
9953 Returns FALSE when successful, TRUE when not editing the
9954 command line.
9955
9956 Can also be used as a |method|: >
9957 GetPos()->setcmdpos()
9958
9959 setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()*
9960 setcursorcharpos({list})
9961 Same as |cursor()| but uses the specified column number as the
9962 character index instead of the byte index in the line.
9963
9964 Example:
9965 With the text "여보세요" in line 4: >
9966 call setcursorcharpos(4, 3)
9967 < positions the cursor on the third character '세'. >
9968 call cursor(4, 3)
9969 < positions the cursor on the first character '여'.
9970
9971 Can also be used as a |method|: >
9972 GetCursorPos()->setcursorcharpos()
9973
9974
9975 setenv({name}, {val}) *setenv()*
9976 Set environment variable {name} to {val}. Example: >
9977 call setenv('HOME', '/home/myhome')
9978
9979 < When {val} is |v:null| the environment variable is deleted.
9980 See also |expr-env|.
9981
9982 Can also be used as a |method|, the base is passed as the
9983 second argument: >
9984 GetPath()->setenv('PATH')
9985
9986 setfperm({fname}, {mode}) *setfperm()* *chmod*
9987 Set the file permissions for {fname} to {mode}.
9988 {mode} must be a string with 9 characters. It is of the form
9989 "rwxrwxrwx", where each group of "rwx" flags represent, in
9990 turn, the permissions of the owner of the file, the group the
9991 file belongs to, and other users. A '-' character means the
9992 permission is off, any other character means on. Multi-byte
9993 characters are not supported.
9994
9995 For example "rw-r-----" means read-write for the user,
9996 readable by the group, not accessible by others. "xx-x-----"
9997 would do the same thing.
9998
9999 Returns non-zero for success, zero for failure.
10000
10001 Can also be used as a |method|: >
10002 GetFilename()->setfperm(mode)
10003 <
10004 To read permissions see |getfperm()|.
10005
10006
10007 setline({lnum}, {text}) *setline()*
10008 Set line {lnum} of the current buffer to {text}. To insert
10009 lines use |append()|. To set lines in another buffer use
10010 |setbufline()|. Any text properties in {lnum} are cleared.
10011
10012 {lnum} is used like with |getline()|.
10013 When {lnum} is just below the last line the {text} will be
10014 added below the last line.
10015 {text} can be any type or a List of any type, each item is
10016 converted to a String.
10017
10018 If this succeeds, FALSE is returned. If this fails (most likely
10019 because {lnum} is invalid) TRUE is returned.
10020
10021 Example: >
10022 :call setline(5, strftime("%c"))
10023
10024 < When {text} is a |List| then line {lnum} and following lines
10025 will be set to the items in the list. Example: >
10026 :call setline(5, ['aaa', 'bbb', 'ccc'])
10027 < This is equivalent to: >
10028 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
10029 : call setline(n, l)
10030 :endfor
10031
10032 < Note: The '[ and '] marks are not set.
10033
10034 Can also be used as a |method|, the base is passed as the
10035 second argument: >
10036 GetText()->setline(lnum)
10037
10038 setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
10039 Create or replace or add to the location list for window {nr}.
10040 {nr} can be the window number or the |window-ID|.
10041 When {nr} is zero the current window is used.
10042
10043 For a location list window, the displayed location list is
10044 modified. For an invalid window number {nr}, -1 is returned.
10045 Otherwise, same as |setqflist()|.
10046 Also see |location-list|.
10047
10048 For {action} see |setqflist-action|.
10049
10050 If the optional {what} dictionary argument is supplied, then
10051 only the items listed in {what} are set. Refer to |setqflist()|
10052 for the list of supported keys in {what}.
10053
10054 Can also be used as a |method|, the base is passed as the
10055 second argument: >
10056 GetLoclist()->setloclist(winnr)
10057
10058 setmatches({list} [, {win}]) *setmatches()*
10059 Restores a list of matches saved by |getmatches()| for the
10060 current window. Returns 0 if successful, otherwise -1. All
10061 current matches are cleared before the list is restored. See
10062 example for |getmatches()|.
10063 If {win} is specified, use the window with this number or
10064 window ID instead of the current window.
10065
10066 Can also be used as a |method|: >
10067 GetMatches()->setmatches()
10068 <
10069 *setpos()*
10070 setpos({expr}, {list})
10071 Set the position for String {expr}. Possible values:
10072 . the cursor
10073 'x mark x
10074
10075 {list} must be a |List| with four or five numbers:
10076 [bufnum, lnum, col, off]
10077 [bufnum, lnum, col, off, curswant]
10078
10079 "bufnum" is the buffer number. Zero can be used for the
10080 current buffer. When setting an uppercase mark "bufnum" is
10081 used for the mark position. For other marks it specifies the
10082 buffer to set the mark in. You can use the |bufnr()| function
10083 to turn a file name into a buffer number.
10084 For setting the cursor and the ' mark "bufnum" is ignored,
10085 since these are associated with a window, not a buffer.
10086 Does not change the jumplist.
10087
10088 "lnum" and "col" are the position in the buffer. The first
10089 column is 1. Use a zero "lnum" to delete a mark. If "col" is
10090 smaller than 1 then 1 is used. To use the character count
10091 instead of the byte count, use |setcharpos()|.
10092
10093 The "off" number is only used when 'virtualedit' is set. Then
10094 it is the offset in screen columns from the start of the
10095 character. E.g., a position within a <Tab> or after the last
10096 character.
10097
10098 The "curswant" number is only used when setting the cursor
10099 position. It sets the preferred column for when moving the
10100 cursor vertically. When the "curswant" number is missing the
10101 preferred column is not set. When it is present and setting a
10102 mark position it is not used.
10103
10104 Note that for '< and '> changing the line number may result in
10105 the marks to be effectively be swapped, so that '< is always
10106 before '>.
10107
10108 Returns 0 when the position could be set, -1 otherwise.
10109 An error message is given if {expr} is invalid.
10110
10111 Also see |setcharpos()|, |getpos()| and |getcurpos()|.
10112
10113 This does not restore the preferred column for moving
10114 vertically; if you set the cursor position with this, |j| and
10115 |k| motions will jump to previous columns! Use |cursor()| to
10116 also set the preferred column. Also see the "curswant" key in
10117 |winrestview()|.
10118
10119 Can also be used as a |method|: >
10120 GetPosition()->setpos('.')
10121
10122 setqflist({list} [, {action} [, {what}]]) *setqflist()*
10123 Create or replace or add to the quickfix list.
10124
10125 If the optional {what} dictionary argument is supplied, then
10126 only the items listed in {what} are set. The first {list}
10127 argument is ignored. See below for the supported items in
10128 {what}.
10129 *setqflist-what*
10130 When {what} is not present, the items in {list} are used. Each
10131 item must be a dictionary. Non-dictionary items in {list} are
10132 ignored. Each dictionary item can contain the following
10133 entries:
10134
10135 bufnr buffer number; must be the number of a valid
10136 buffer
10137 filename name of a file; only used when "bufnr" is not
10138 present or it is invalid.
10139 module name of a module; if given it will be used in
10140 quickfix error window instead of the filename.
10141 lnum line number in the file
10142 pattern search pattern used to locate the error
10143 col column number
10144 vcol when non-zero: "col" is visual column
10145 when zero: "col" is byte index
10146 nr error number
10147 text description of the error
10148 type single-character error type, 'E', 'W', etc.
10149 valid recognized error message
10150
10151 The "col", "vcol", "nr", "type" and "text" entries are
10152 optional. Either "lnum" or "pattern" entry can be used to
10153 locate a matching error line.
10154 If the "filename" and "bufnr" entries are not present or
10155 neither the "lnum" or "pattern" entries are present, then the
10156 item will not be handled as an error line.
10157 If both "pattern" and "lnum" are present then "pattern" will
10158 be used.
10159 If the "valid" entry is not supplied, then the valid flag is
10160 set when "bufnr" is a valid buffer or "filename" exists.
10161 If you supply an empty {list}, the quickfix list will be
10162 cleared.
10163 Note that the list is not exactly the same as what
10164 |getqflist()| returns.
10165
10166 {action} values: *setqflist-action* *E927*
10167 'a' The items from {list} are added to the existing
10168 quickfix list. If there is no existing list, then a
10169 new list is created.
10170
10171 'r' The items from the current quickfix list are replaced
10172 with the items from {list}. This can also be used to
10173 clear the list: >
10174 :call setqflist([], 'r')
10175 <
10176 'f' All the quickfix lists in the quickfix stack are
10177 freed.
10178
10179 If {action} is not present or is set to ' ', then a new list
10180 is created. The new quickfix list is added after the current
10181 quickfix list in the stack and all the following lists are
10182 freed. To add a new quickfix list at the end of the stack,
10183 set "nr" in {what} to "$".
10184
10185 The following items can be specified in dictionary {what}:
10186 context quickfix list context. See |quickfix-context|
10187 efm errorformat to use when parsing text from
10188 "lines". If this is not present, then the
10189 'errorformat' option value is used.
10190 See |quickfix-parse|
10191 id quickfix list identifier |quickfix-ID|
10192 idx index of the current entry in the quickfix
10193 list specified by 'id' or 'nr'. If set to '$',
10194 then the last entry in the list is set as the
10195 current entry. See |quickfix-index|
10196 items list of quickfix entries. Same as the {list}
10197 argument.
10198 lines use 'errorformat' to parse a list of lines and
10199 add the resulting entries to the quickfix list
10200 {nr} or {id}. Only a |List| value is supported.
10201 See |quickfix-parse|
10202 nr list number in the quickfix stack; zero
10203 means the current quickfix list and "$" means
10204 the last quickfix list.
10205 quickfixtextfunc
10206 function to get the text to display in the
10207 quickfix window. The value can be the name of
10208 a function or a funcref or a lambda. Refer to
10209 |quickfix-window-function| for an explanation
10210 of how to write the function and an example.
10211 title quickfix list title text. See |quickfix-title|
10212 Unsupported keys in {what} are ignored.
10213 If the "nr" item is not present, then the current quickfix list
10214 is modified. When creating a new quickfix list, "nr" can be
10215 set to a value one greater than the quickfix stack size.
10216 When modifying a quickfix list, to guarantee that the correct
10217 list is modified, "id" should be used instead of "nr" to
10218 specify the list.
10219
10220 Examples (See also |setqflist-examples|): >
10221 :call setqflist([], 'r', {'title': 'My search'})
10222 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
10223 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
10224 <
10225 Returns zero for success, -1 for failure.
10226
10227 This function can be used to create a quickfix list
10228 independent of the 'errorformat' setting. Use a command like
10229 `:cc 1` to jump to the first position.
10230
10231 Can also be used as a |method|, the base is passed as the
10232 second argument: >
10233 GetErrorlist()->setqflist()
10234 <
10235 *setreg()*
10236 setreg({regname}, {value} [, {options}])
10237 Set the register {regname} to {value}.
10238 If {regname} is "" or "@", the unnamed register '"' is used.
10239 The {regname} argument is a string. In |Vim9-script|
10240 {regname} must be one character.
10241
10242 {value} may be any value returned by |getreg()| or
10243 |getreginfo()|, including a |List| or |Dict|.
10244 If {options} contains "a" or {regname} is upper case,
10245 then the value is appended.
10246
10247 {options} can also contain a register type specification:
10248 "c" or "v" |characterwise| mode
10249 "l" or "V" |linewise| mode
10250 "b" or "<CTRL-V>" |blockwise-visual| mode
10251 If a number immediately follows "b" or "<CTRL-V>" then this is
10252 used as the width of the selection - if it is not specified
10253 then the width of the block is set to the number of characters
10254 in the longest line (counting a <Tab> as 1 character).
10255
10256 If {options} contains no register settings, then the default
10257 is to use character mode unless {value} ends in a <NL> for
10258 string {value} and linewise mode for list {value}. Blockwise
10259 mode is never selected automatically.
10260 Returns zero for success, non-zero for failure.
10261
10262 *E883*
10263 Note: you may not use |List| containing more than one item to
10264 set search and expression registers. Lists containing no
10265 items act like empty strings.
10266
10267 Examples: >
10268 :call setreg(v:register, @*)
10269 :call setreg('*', @%, 'ac')
10270 :call setreg('a', "1\n2\n3", 'b5')
10271 :call setreg('"', { 'points_to': 'a'})
10272
10273 < This example shows using the functions to save and restore a
10274 register: >
10275 :let var_a = getreginfo()
10276 :call setreg('a', var_a)
10277 < or: >
10278 :let var_a = getreg('a', 1, 1)
10279 :let var_amode = getregtype('a')
10280 ....
10281 :call setreg('a', var_a, var_amode)
10282 < Note: you may not reliably restore register value
10283 without using the third argument to |getreg()| as without it
10284 newlines are represented as newlines AND Nul bytes are
10285 represented as newlines as well, see |NL-used-for-Nul|.
10286
10287 You can also change the type of a register by appending
10288 nothing: >
10289 :call setreg('a', '', 'al')
10290
10291 < Can also be used as a |method|, the base is passed as the
10292 second argument: >
10293 GetText()->setreg('a')
10294
10295 settabvar({tabnr}, {varname}, {val}) *settabvar()*
10296 Set tab-local variable {varname} to {val} in tab page {tabnr}.
10297 |t:var|
10298 The {varname} argument is a string.
10299 Note that autocommands are blocked, side effects may not be
10300 triggered, e.g. when setting 'filetype'.
10301 Note that the variable name without "t:" must be used.
10302 Tabs are numbered starting with one.
10303 This function is not available in the |sandbox|.
10304
10305 Can also be used as a |method|, the base is passed as the
10306 third argument: >
10307 GetValue()->settabvar(tab, name)
10308
10309 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
10310 Set option or local variable {varname} in window {winnr} to
10311 {val}.
10312 Tabs are numbered starting with one. For the current tabpage
10313 use |setwinvar()|.
10314 {winnr} can be the window number or the |window-ID|.
10315 When {winnr} is zero the current window is used.
10316 Note that autocommands are blocked, side effects may not be
10317 triggered, e.g. when setting 'filetype' or 'syntax'.
10318 This also works for a global or local buffer option, but it
10319 doesn't work for a global or local buffer variable.
10320 For a local buffer option the global value is unchanged.
10321 Note that the variable name without "w:" must be used.
10322 Examples: >
10323 :call settabwinvar(1, 1, "&list", 0)
10324 :call settabwinvar(3, 2, "myvar", "foobar")
10325 < This function is not available in the |sandbox|.
10326
10327 Can also be used as a |method|, the base is passed as the
10328 fourth argument: >
10329 GetValue()->settabwinvar(tab, winnr, name)
10330
10331 settagstack({nr}, {dict} [, {action}]) *settagstack()*
10332 Modify the tag stack of the window {nr} using {dict}.
10333 {nr} can be the window number or the |window-ID|.
10334
10335 For a list of supported items in {dict}, refer to
10336 |gettagstack()|. "curidx" takes effect before changing the tag
10337 stack.
10338 *E962*
10339 How the tag stack is modified depends on the {action}
10340 argument:
10341 - If {action} is not present or is set to 'r', then the tag
10342 stack is replaced.
10343 - If {action} is set to 'a', then new entries from {dict} are
10344 pushed (added) onto the tag stack.
10345 - If {action} is set to 't', then all the entries from the
10346 current entry in the tag stack or "curidx" in {dict} are
10347 removed and then new entries are pushed to the stack.
10348
10349 The current index is set to one after the length of the tag
10350 stack after the modification.
10351
10352 Returns zero for success, -1 for failure.
10353
10354 Examples (for more examples see |tagstack-examples|):
10355 Empty the tag stack of window 3: >
10356 call settagstack(3, {'items' : []})
10357
10358 < Save and restore the tag stack: >
10359 let stack = gettagstack(1003)
10360 " do something else
10361 call settagstack(1003, stack)
10362 unlet stack
10363 <
10364 Can also be used as a |method|, the base is passed as the
10365 second argument: >
10366 GetStack()->settagstack(winnr)
10367
10368 setwinvar({winnr}, {varname}, {val}) *setwinvar()*
10369 Like |settabwinvar()| for the current tab page.
10370 Examples: >
10371 :call setwinvar(1, "&list", 0)
10372 :call setwinvar(2, "myvar", "foobar")
10373
10374 < Can also be used as a |method|, the base is passed as the
10375 third argument: >
10376 GetValue()->setwinvar(winnr, name)
10377
10378 sha256({string}) *sha256()*
10379 Returns a String with 64 hex characters, which is the SHA256
10380 checksum of {string}.
10381
10382 Can also be used as a |method|: >
10383 GetText()->sha256()
10384
10385 < {only available when compiled with the |+cryptv| feature}
10386
10387 shellescape({string} [, {special}]) *shellescape()*
10388 Escape {string} for use as a shell command argument.
10389 When the 'shell' contains powershell (MS-Windows) or pwsh
10390 (MS-Windows, Linux, and MacOS) then it will enclose {string}
10391 in single quotes and will double up all internal single
10392 quotes.
10393 On MS-Windows, when 'shellslash' is not set, it will enclose
10394 {string} in double quotes and double all double quotes within
10395 {string}.
10396 Otherwise it will enclose {string} in single quotes and
10397 replace all "'" with "'\''".
10398
10399 When the {special} argument is present and it's a non-zero
10400 Number or a non-empty String (|non-zero-arg|), then special
10401 items such as "!", "%", "#" and "<cword>" will be preceded by
10402 a backslash. This backslash will be removed again by the |:!|
10403 command.
10404
10405 The "!" character will be escaped (again with a |non-zero-arg|
10406 {special}) when 'shell' contains "csh" in the tail. That is
10407 because for csh and tcsh "!" is used for history replacement
10408 even when inside single quotes.
10409
10410 With a |non-zero-arg| {special} the <NL> character is also
10411 escaped. When 'shell' containing "csh" in the tail it's
10412 escaped a second time.
10413
10414 The "\" character will be escaped when 'shell' contains "fish"
10415 in the tail. That is because for fish "\" is used as an escape
10416 character inside single quotes.
10417
10418 Example of use with a |:!| command: >
10419 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
10420 < This results in a directory listing for the file under the
10421 cursor. Example of use with |system()|: >
10422 :call system("chmod +w -- " . shellescape(expand("%")))
10423 < See also |::S|.
10424
10425 Can also be used as a |method|: >
10426 GetCommand()->shellescape()
10427
10428 shiftwidth([{col}]) *shiftwidth()*
10429 Returns the effective value of 'shiftwidth'. This is the
10430 'shiftwidth' value unless it is zero, in which case it is the
10431 'tabstop' value. This function was introduced with patch
10432 7.3.694 in 2012, everybody should have it by now (however it
10433 did not allow for the optional {col} argument until 8.1.542).
10434
10435 When there is one argument {col} this is used as column number
10436 for which to return the 'shiftwidth' value. This matters for the
10437 'vartabstop' feature. If the 'vartabstop' setting is enabled and
10438 no {col} argument is given, column 1 will be assumed.
10439
10440 Can also be used as a |method|: >
10441 GetColumn()->shiftwidth()
10442
10443 sign_ functions are documented here: |sign-functions-details|
10444
10445
10446 simplify({filename}) *simplify()*
10447 Simplify the file name as much as possible without changing
10448 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
10449 Unix) are not resolved. If the first path component in
10450 {filename} designates the current directory, this will be
10451 valid for the result as well. A trailing path separator is
10452 not removed either. On Unix "//path" is unchanged, but
10453 "///path" is simplified to "/path" (this follows the Posix
10454 standard).
10455 Example: >
10456 simplify("./dir/.././/file/") == "./file/"
10457 < Note: The combination "dir/.." is only removed if "dir" is
10458 a searchable directory or does not exist. On Unix, it is also
10459 removed when "dir" is a symbolic link within the same
10460 directory. In order to resolve all the involved symbolic
10461 links before simplifying the path name, use |resolve()|.
10462
10463 Can also be used as a |method|: >
10464 GetName()->simplify()
10465
10466 sin({expr}) *sin()*
10467 Return the sine of {expr}, measured in radians, as a |Float|.
10468 {expr} must evaluate to a |Float| or a |Number|.
10469 Examples: >
10470 :echo sin(100)
10471 < -0.506366 >
10472 :echo sin(-4.01)
10473 < 0.763301
10474
10475 Can also be used as a |method|: >
10476 Compute()->sin()
10477 <
10478 {only available when compiled with the |+float| feature}
10479
10480
10481 sinh({expr}) *sinh()*
10482 Return the hyperbolic sine of {expr} as a |Float| in the range
10483 [-inf, inf].
10484 {expr} must evaluate to a |Float| or a |Number|.
10485 Examples: >
10486 :echo sinh(0.5)
10487 < 0.521095 >
10488 :echo sinh(-0.9)
10489 < -1.026517
10490
10491 Can also be used as a |method|: >
10492 Compute()->sinh()
10493 <
10494 {only available when compiled with the |+float| feature}
10495
10496
10497 slice({expr}, {start} [, {end}]) *slice()*
10498 Similar to using a |slice| "expr[start : end]", but "end" is
10499 used exclusive. And for a string the indexes are used as
10500 character indexes instead of byte indexes, like in
10501 |vim9script|. Also, composing characters are not counted.
10502 When {end} is omitted the slice continues to the last item.
10503 When {end} is -1 the last item is omitted.
10504
10505 Can also be used as a |method|: >
10506 GetList()->slice(offset)
10507
10508
10509 sort({list} [, {func} [, {dict}]]) *sort()* *E702*
10510 Sort the items in {list} in-place. Returns {list}.
10511
10512 If you want a list to remain unmodified make a copy first: >
10513 :let sortedlist = sort(copy(mylist))
10514
10515 < When {func} is omitted, is empty or zero, then sort() uses the
10516 string representation of each item to sort on. Numbers sort
10517 after Strings, |Lists| after Numbers. For sorting text in the
10518 current buffer use |:sort|.
10519
10520 When {func} is given and it is '1' or 'i' then case is
10521 ignored.
10522
10523 When {func} is given and it is 'l' then the current collation
10524 locale is used for ordering. Implementation details: strcoll()
10525 is used to compare strings. See |:language| check or set the
10526 collation locale. |v:collate| can also be used to check the
10527 current locale. Sorting using the locale typically ignores
10528 case. Example: >
10529 " ö is sorted similarly to o with English locale.
10530 :language collate en_US.UTF8
10531 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10532 < ['n', 'o', 'O', 'ö', 'p', 'z'] ~
10533 >
10534 " ö is sorted after z with Swedish locale.
10535 :language collate sv_SE.UTF8
10536 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l')
10537 < ['n', 'o', 'O', 'p', 'z', 'ö'] ~
10538 This does not work properly on Mac.
10539
10540 When {func} is given and it is 'n' then all items will be
10541 sorted numerical (Implementation detail: this uses the
10542 strtod() function to parse numbers, Strings, Lists, Dicts and
10543 Funcrefs will be considered as being 0).
10544
10545 When {func} is given and it is 'N' then all items will be
10546 sorted numerical. This is like 'n' but a string containing
10547 digits will be used as the number they represent.
10548
10549 When {func} is given and it is 'f' then all items will be
10550 sorted numerical. All values must be a Number or a Float.
10551
10552 When {func} is a |Funcref| or a function name, this function
10553 is called to compare items. The function is invoked with two
10554 items as argument and must return zero if they are equal, 1 or
10555 bigger if the first one sorts after the second one, -1 or
10556 smaller if the first one sorts before the second one.
10557
10558 {dict} is for functions with the "dict" attribute. It will be
10559 used to set the local variable "self". |Dictionary-function|
10560
10561 The sort is stable, items which compare equal (as number or as
10562 string) will keep their relative position. E.g., when sorting
10563 on numbers, text strings will sort next to each other, in the
10564 same order as they were originally.
10565
10566 Can also be used as a |method|: >
10567 mylist->sort()
10568
10569 < Also see |uniq()|.
10570
10571 Example: >
10572 func MyCompare(i1, i2)
10573 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
10574 endfunc
10575 eval mylist->sort("MyCompare")
10576 < A shorter compare version for this specific simple case, which
10577 ignores overflow: >
10578 func MyCompare(i1, i2)
10579 return a:i1 - a:i2
10580 endfunc
10581 < For a simple expression you can use a lambda: >
10582 eval mylist->sort({i1, i2 -> i1 - i2})
10583 <
10584 sound_clear() *sound_clear()*
10585 Stop playing all sounds.
10586
10587 On some Linux systems you may need the libcanberra-pulse
10588 package, otherwise sound may not stop.
10589
10590 {only available when compiled with the |+sound| feature}
10591
10592 *sound_playevent()*
10593 sound_playevent({name} [, {callback}])
10594 Play a sound identified by {name}. Which event names are
10595 supported depends on the system. Often the XDG sound names
10596 are used. On Ubuntu they may be found in
10597 /usr/share/sounds/freedesktop/stereo. Example: >
10598 call sound_playevent('bell')
10599 < On MS-Windows, {name} can be SystemAsterisk, SystemDefault,
10600 SystemExclamation, SystemExit, SystemHand, SystemQuestion,
10601 SystemStart, SystemWelcome, etc.
10602
10603 When {callback} is specified it is invoked when the sound is
10604 finished. The first argument is the sound ID, the second
10605 argument is the status:
10606 0 sound was played to the end
10607 1 sound was interrupted
10608 2 error occurred after sound started
10609 Example: >
10610 func Callback(id, status)
10611 echomsg "sound " .. a:id .. " finished with " .. a:status
10612 endfunc
10613 call sound_playevent('bell', 'Callback')
10614
10615 < MS-Windows: {callback} doesn't work for this function.
10616
10617 Returns the sound ID, which can be passed to `sound_stop()`.
10618 Returns zero if the sound could not be played.
10619
10620 Can also be used as a |method|: >
10621 GetSoundName()->sound_playevent()
10622
10623 < {only available when compiled with the |+sound| feature}
10624
10625 *sound_playfile()*
10626 sound_playfile({path} [, {callback}])
10627 Like `sound_playevent()` but play sound file {path}. {path}
10628 must be a full path. On Ubuntu you may find files to play
10629 with this command: >
10630 :!find /usr/share/sounds -type f | grep -v index.theme
10631
10632 < Can also be used as a |method|: >
10633 GetSoundPath()->sound_playfile()
10634
10635 < {only available when compiled with the |+sound| feature}
10636
10637
10638 sound_stop({id}) *sound_stop()*
10639 Stop playing sound {id}. {id} must be previously returned by
10640 `sound_playevent()` or `sound_playfile()`.
10641
10642 On some Linux systems you may need the libcanberra-pulse
10643 package, otherwise sound may not stop.
10644
10645 On MS-Windows, this does not work for event sound started by
10646 `sound_playevent()`. To stop event sounds, use `sound_clear()`.
10647
10648 Can also be used as a |method|: >
10649 soundid->sound_stop()
10650
10651 < {only available when compiled with the |+sound| feature}
10652
10653 *soundfold()*
10654 soundfold({word})
10655 Return the sound-folded equivalent of {word}. Uses the first
10656 language in 'spelllang' for the current window that supports
10657 soundfolding. 'spell' must be set. When no sound folding is
10658 possible the {word} is returned unmodified.
10659 This can be used for making spelling suggestions. Note that
10660 the method can be quite slow.
10661
10662 Can also be used as a |method|: >
10663 GetWord()->soundfold()
10664 <
10665 *spellbadword()*
10666 spellbadword([{sentence}])
10667 Without argument: The result is the badly spelled word under
10668 or after the cursor. The cursor is moved to the start of the
10669 bad word. When no bad word is found in the cursor line the
10670 result is an empty string and the cursor doesn't move.
10671
10672 With argument: The result is the first word in {sentence} that
10673 is badly spelled. If there are no spelling mistakes the
10674 result is an empty string.
10675
10676 The return value is a list with two items:
10677 - The badly spelled word or an empty string.
10678 - The type of the spelling error:
10679 "bad" spelling mistake
10680 "rare" rare word
10681 "local" word only valid in another region
10682 "caps" word should start with Capital
10683 Example: >
10684 echo spellbadword("the quik brown fox")
10685 < ['quik', 'bad'] ~
10686
10687 The spelling information for the current window and the value
10688 of 'spelllang' are used.
10689
10690 Can also be used as a |method|: >
10691 GetText()->spellbadword()
10692 <
10693 *spellsuggest()*
10694 spellsuggest({word} [, {max} [, {capital}]])
10695 Return a |List| with spelling suggestions to replace {word}.
10696 When {max} is given up to this number of suggestions are
10697 returned. Otherwise up to 25 suggestions are returned.
10698
10699 When the {capital} argument is given and it's non-zero only
10700 suggestions with a leading capital will be given. Use this
10701 after a match with 'spellcapcheck'.
10702
10703 {word} can be a badly spelled word followed by other text.
10704 This allows for joining two words that were split. The
10705 suggestions also include the following text, thus you can
10706 replace a line.
10707
10708 {word} may also be a good word. Similar words will then be
10709 returned. {word} itself is not included in the suggestions,
10710 although it may appear capitalized.
10711
10712 The spelling information for the current window is used. The
10713 values of 'spelllang' and 'spellsuggest' are used.
10714
10715 Can also be used as a |method|: >
10716 GetWord()->spellsuggest()
10717
10718 split({string} [, {pattern} [, {keepempty}]]) *split()*
10719 Make a |List| out of {string}. When {pattern} is omitted or
10720 empty each white-separated sequence of characters becomes an
10721 item.
10722 Otherwise the string is split where {pattern} matches,
10723 removing the matched characters. 'ignorecase' is not used
10724 here, add \c to ignore case. |/\c|
10725 When the first or last item is empty it is omitted, unless the
10726 {keepempty} argument is given and it's non-zero.
10727 Other empty items are kept when {pattern} matches at least one
10728 character or when {keepempty} is non-zero.
10729 Example: >
10730 :let words = split(getline('.'), '\W\+')
10731 < To split a string in individual characters: >
10732 :for c in split(mystring, '\zs')
10733 < If you want to keep the separator you can also use '\zs' at
10734 the end of the pattern: >
10735 :echo split('abc:def:ghi', ':\zs')
10736 < ['abc:', 'def:', 'ghi'] ~
10737 Splitting a table where the first element can be empty: >
10738 :let items = split(line, ':', 1)
10739 < The opposite function is |join()|.
10740
10741 Can also be used as a |method|: >
10742 GetString()->split()
10743
10744 sqrt({expr}) *sqrt()*
10745 Return the non-negative square root of Float {expr} as a
10746 |Float|.
10747 {expr} must evaluate to a |Float| or a |Number|. When {expr}
10748 is negative the result is NaN (Not a Number).
10749 Examples: >
10750 :echo sqrt(100)
10751 < 10.0 >
10752 :echo sqrt(-4.01)
10753 < nan
10754 "nan" may be different, it depends on system libraries.
10755
10756 Can also be used as a |method|: >
10757 Compute()->sqrt()
10758 <
10759 {only available when compiled with the |+float| feature}
10760
10761
10762 srand([{expr}]) *srand()*
10763 Initialize seed used by |rand()|:
10764 - If {expr} is not given, seed values are initialized by
10765 reading from /dev/urandom, if possible, or using time(NULL)
10766 a.k.a. epoch time otherwise; this only has second accuracy.
10767 - If {expr} is given it must be a Number. It is used to
10768 initialize the seed values. This is useful for testing or
10769 when a predictable sequence is intended.
10770
10771 Examples: >
10772 :let seed = srand()
10773 :let seed = srand(userinput)
10774 :echo rand(seed)
10775
10776 state([{what}]) *state()*
10777 Return a string which contains characters indicating the
10778 current state. Mostly useful in callbacks that want to do
10779 work that may not always be safe. Roughly this works like:
10780 - callback uses state() to check if work is safe to do.
10781 Yes: then do it right away.
10782 No: add to work queue and add a |SafeState| and/or
10783 |SafeStateAgain| autocommand (|SafeState| triggers at
10784 toplevel, |SafeStateAgain| triggers after handling
10785 messages and callbacks).
10786 - When SafeState or SafeStateAgain is triggered and executes
10787 your autocommand, check with `state()` if the work can be
10788 done now, and if yes remove it from the queue and execute.
10789 Remove the autocommand if the queue is now empty.
10790 Also see |mode()|.
10791
10792 When {what} is given only characters in this string will be
10793 added. E.g, this checks if the screen has scrolled: >
10794 if state('s') == ''
10795 " screen has not scrolled
10796 <
10797 These characters indicate the state, generally indicating that
10798 something is busy:
10799 m halfway a mapping, :normal command, feedkeys() or
10800 stuffed command
10801 o operator pending, e.g. after |d|
10802 a Insert mode autocomplete active
10803 x executing an autocommand
10804 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and
10805 ch_readraw() when reading json
10806 S not triggering SafeState or SafeStateAgain, e.g. after
10807 |f| or a count
10808 c callback invoked, including timer (repeats for
10809 recursiveness up to "ccc")
10810 s screen has scrolled for messages
10811
10812 str2float({string} [, {quoted}]) *str2float()*
10813 Convert String {string} to a Float. This mostly works the
10814 same as when using a floating point number in an expression,
10815 see |floating-point-format|. But it's a bit more permissive.
10816 E.g., "1e40" is accepted, while in an expression you need to
10817 write "1.0e40". The hexadecimal form "0x123" is also
10818 accepted, but not others, like binary or octal.
10819 When {quoted} is present and non-zero then embedded single
10820 quotes before the dot are ignored, thus "1'000.0" is a
10821 thousand.
10822 Text after the number is silently ignored.
10823 The decimal point is always '.', no matter what the locale is
10824 set to. A comma ends the number: "12,345.67" is converted to
10825 12.0. You can strip out thousands separators with
10826 |substitute()|: >
10827 let f = str2float(substitute(text, ',', '', 'g'))
10828 <
10829 Can also be used as a |method|: >
10830 let f = text->substitute(',', '', 'g')->str2float()
10831 <
10832 {only available when compiled with the |+float| feature}
10833
10834 str2list({string} [, {utf8}]) *str2list()*
10835 Return a list containing the number values which represent
10836 each character in String {string}. Examples: >
10837 str2list(" ") returns [32]
10838 str2list("ABC") returns [65, 66, 67]
10839 < |list2str()| does the opposite.
10840
10841 When {utf8} is omitted or zero, the current 'encoding' is used.
10842 When {utf8} is TRUE, always treat the String as UTF-8
10843 characters. With UTF-8 composing characters are handled
10844 properly: >
10845 str2list("á") returns [97, 769]
10846
10847 < Can also be used as a |method|: >
10848 GetString()->str2list()
10849
10850
10851 str2nr({string} [, {base} [, {quoted}]]) *str2nr()*
10852 Convert string {string} to a number.
10853 {base} is the conversion base, it can be 2, 8, 10 or 16.
10854 When {quoted} is present and non-zero then embedded single
10855 quotes are ignored, thus "1'000'000" is a million.
10856
10857 When {base} is omitted base 10 is used. This also means that
10858 a leading zero doesn't cause octal conversion to be used, as
10859 with the default String to Number conversion. Example: >
10860 let nr = str2nr('0123')
10861 <
10862 When {base} is 16 a leading "0x" or "0X" is ignored. With a
10863 different base the result will be zero. Similarly, when
10864 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when
10865 {base} is 2 a leading "0b" or "0B" is ignored.
10866 Text after the number is silently ignored.
10867
10868 Can also be used as a |method|: >
10869 GetText()->str2nr()
10870
10871
10872 strcharlen({string}) *strcharlen()*
10873 The result is a Number, which is the number of characters
10874 in String {string}. Composing characters are ignored.
10875 |strchars()| can count the number of characters, counting
10876 composing characters separately.
10877
10878 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10879
10880 Can also be used as a |method|: >
10881 GetText()->strcharlen()
10882
10883
10884 strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()*
10885 Like |strpart()| but using character index and length instead
10886 of byte index and length.
10887 When {skipcc} is omitted or zero, composing characters are
10888 counted separately.
10889 When {skipcc} set to 1, Composing characters are ignored,
10890 similar to |slice()|.
10891 When a character index is used where a character does not
10892 exist it is omitted and counted as one character. For
10893 example: >
10894 strcharpart('abc', -1, 2)
10895 < results in 'a'.
10896
10897 Can also be used as a |method|: >
10898 GetText()->strcharpart(5)
10899
10900
10901 strchars({string} [, {skipcc}]) *strchars()*
10902 The result is a Number, which is the number of characters
10903 in String {string}.
10904 When {skipcc} is omitted or zero, composing characters are
10905 counted separately.
10906 When {skipcc} set to 1, Composing characters are ignored.
10907 |strcharlen()| always does this.
10908
10909 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
10910
10911 {skipcc} is only available after 7.4.755. For backward
10912 compatibility, you can define a wrapper function: >
10913 if has("patch-7.4.755")
10914 function s:strchars(str, skipcc)
10915 return strchars(a:str, a:skipcc)
10916 endfunction
10917 else
10918 function s:strchars(str, skipcc)
10919 if a:skipcc
10920 return strlen(substitute(a:str, ".", "x", "g"))
10921 else
10922 return strchars(a:str)
10923 endif
10924 endfunction
10925 endif
10926 <
10927 Can also be used as a |method|: >
10928 GetText()->strchars()
10929
10930 strdisplaywidth({string} [, {col}]) *strdisplaywidth()*
10931 The result is a Number, which is the number of display cells
10932 String {string} occupies on the screen when it starts at {col}
10933 (first column is zero). When {col} is omitted zero is used.
10934 Otherwise it is the screen column where to start. This
10935 matters for Tab characters.
10936 The option settings of the current window are used. This
10937 matters for anything that's displayed differently, such as
10938 'tabstop' and 'display'.
10939 When {string} contains characters with East Asian Width Class
10940 Ambiguous, this function's return value depends on 'ambiwidth'.
10941 Also see |strlen()|, |strwidth()| and |strchars()|.
10942
10943 Can also be used as a |method|: >
10944 GetText()->strdisplaywidth()
10945
10946 strftime({format} [, {time}]) *strftime()*
10947 The result is a String, which is a formatted date and time, as
10948 specified by the {format} string. The given {time} is used,
10949 or the current time if no time is given. The accepted
10950 {format} depends on your system, thus this is not portable!
10951 See the manual page of the C function strftime() for the
10952 format. The maximum length of the result is 80 characters.
10953 See also |localtime()|, |getftime()| and |strptime()|.
10954 The language can be changed with the |:language| command.
10955 Examples: >
10956 :echo strftime("%c") Sun Apr 27 11:49:23 1997
10957 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
10958 :echo strftime("%y%m%d %T") 970427 11:53:55
10959 :echo strftime("%H:%M") 11:55
10960 :echo strftime("%c", getftime("file.c"))
10961 Show mod time of file.c.
10962 < Not available on all systems. To check use: >
10963 :if exists("*strftime")
10964
10965 < Can also be used as a |method|: >
10966 GetFormat()->strftime()
10967
10968 strgetchar({str}, {index}) *strgetchar()*
10969 Get character {index} from {str}. This uses a character
10970 index, not a byte index. Composing characters are considered
10971 separate characters here.
10972 Also see |strcharpart()| and |strchars()|.
10973
10974 Can also be used as a |method|: >
10975 GetText()->strgetchar(5)
10976
10977 stridx({haystack}, {needle} [, {start}]) *stridx()*
10978 The result is a Number, which gives the byte index in
10979 {haystack} of the first occurrence of the String {needle}.
10980 If {start} is specified, the search starts at index {start}.
10981 This can be used to find a second match: >
10982 :let colon1 = stridx(line, ":")
10983 :let colon2 = stridx(line, ":", colon1 + 1)
10984 < The search is done case-sensitive.
10985 For pattern searches use |match()|.
10986 -1 is returned if the {needle} does not occur in {haystack}.
10987 See also |strridx()|.
10988 Examples: >
10989 :echo stridx("An Example", "Example") 3
10990 :echo stridx("Starting point", "Start") 0
10991 :echo stridx("Starting point", "start") -1
10992 < *strstr()* *strchr()*
10993 stridx() works similar to the C function strstr(). When used
10994 with a single character it works similar to strchr().
10995
10996 Can also be used as a |method|: >
10997 GetHaystack()->stridx(needle)
10998 <
10999 *string()*
11000 string({expr}) Return {expr} converted to a String. If {expr} is a Number,
11001 Float, String, Blob or a composition of them, then the result
11002 can be parsed back with |eval()|.
11003 {expr} type result ~
11004 String 'string' (single quotes are doubled)
11005 Number 123
11006 Float 123.123456 or 1.123456e8
11007 Funcref function('name')
11008 Blob 0z00112233.44556677.8899
11009 List [item, item]
11010 Dictionary {key: value, key: value}
11011
11012 When a |List| or |Dictionary| has a recursive reference it is
11013 replaced by "[...]" or "{...}". Using eval() on the result
11014 will then fail.
11015
11016 Can also be used as a |method|: >
11017 mylist->string()
11018
11019 < Also see |strtrans()|.
11020
11021
11022 strlen({string}) *strlen()*
11023 The result is a Number, which is the length of the String
11024 {string} in bytes.
11025 If the argument is a Number it is first converted to a String.
11026 For other types an error is given.
11027 If you want to count the number of multibyte characters use
11028 |strchars()|.
11029 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
11030
11031 Can also be used as a |method|: >
11032 GetString()->strlen()
11033
11034 strpart({src}, {start} [, {len} [, {chars}]]) *strpart()*
11035 The result is a String, which is part of {src}, starting from
11036 byte {start}, with the byte length {len}.
11037 When {chars} is present and TRUE then {len} is the number of
11038 characters positions (composing characters are not counted
11039 separately, thus "1" means one base character and any
11040 following composing characters).
11041 To count {start} as characters instead of bytes use
11042 |strcharpart()|.
11043
11044 When bytes are selected which do not exist, this doesn't
11045 result in an error, the bytes are simply omitted.
11046 If {len} is missing, the copy continues from {start} till the
11047 end of the {src}. >
11048 strpart("abcdefg", 3, 2) == "de"
11049 strpart("abcdefg", -2, 4) == "ab"
11050 strpart("abcdefg", 5, 4) == "fg"
11051 strpart("abcdefg", 3) == "defg"
11052
11053 < Note: To get the first character, {start} must be 0. For
11054 example, to get the character under the cursor: >
11055 strpart(getline("."), col(".") - 1, 1, v:true)
11056 <
11057 Can also be used as a |method|: >
11058 GetText()->strpart(5)
11059
11060 strptime({format}, {timestring}) *strptime()*
11061 The result is a Number, which is a unix timestamp representing
11062 the date and time in {timestring}, which is expected to match
11063 the format specified in {format}.
11064
11065 The accepted {format} depends on your system, thus this is not
11066 portable! See the manual page of the C function strptime()
11067 for the format. Especially avoid "%c". The value of $TZ also
11068 matters.
11069
11070 If the {timestring} cannot be parsed with {format} zero is
11071 returned. If you do not know the format of {timestring} you
11072 can try different {format} values until you get a non-zero
11073 result.
11074
11075 See also |strftime()|.
11076 Examples: >
11077 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23")
11078 < 862156163 >
11079 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55"))
11080 < Sun Apr 27 11:53:55 1997 >
11081 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600)
11082 < Sun Apr 27 12:53:55 1997
11083
11084 Can also be used as a |method|: >
11085 GetFormat()->strptime(timestring)
11086 <
11087 Not available on all systems. To check use: >
11088 :if exists("*strptime")
11089
11090 strridx({haystack}, {needle} [, {start}]) *strridx()*
11091 The result is a Number, which gives the byte index in
11092 {haystack} of the last occurrence of the String {needle}.
11093 When {start} is specified, matches beyond this index are
11094 ignored. This can be used to find a match before a previous
11095 match: >
11096 :let lastcomma = strridx(line, ",")
11097 :let comma2 = strridx(line, ",", lastcomma - 1)
11098 < The search is done case-sensitive.
11099 For pattern searches use |match()|.
11100 -1 is returned if the {needle} does not occur in {haystack}.
11101 If the {needle} is empty the length of {haystack} is returned.
11102 See also |stridx()|. Examples: >
11103 :echo strridx("an angry armadillo", "an") 3
11104 < *strrchr()*
11105 When used with a single character it works similar to the C
11106 function strrchr().
11107
11108 Can also be used as a |method|: >
11109 GetHaystack()->strridx(needle)
11110
11111 strtrans({string}) *strtrans()*
11112 The result is a String, which is {string} with all unprintable
11113 characters translated into printable characters |'isprint'|.
11114 Like they are shown in a window. Example: >
11115 echo strtrans(@a)
11116 < This displays a newline in register a as "^@" instead of
11117 starting a new line.
11118
11119 Can also be used as a |method|: >
11120 GetString()->strtrans()
11121
11122 strwidth({string}) *strwidth()*
11123 The result is a Number, which is the number of display cells
11124 String {string} occupies. A Tab character is counted as one
11125 cell, alternatively use |strdisplaywidth()|.
11126 When {string} contains characters with East Asian Width Class
11127 Ambiguous, this function's return value depends on 'ambiwidth'.
11128 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
11129
11130 Can also be used as a |method|: >
11131 GetString()->strwidth()
11132
11133 submatch({nr} [, {list}]) *submatch()* *E935*
11134 Only for an expression in a |:substitute| command or
11135 substitute() function.
11136 Returns the {nr}'th submatch of the matched text. When {nr}
11137 is 0 the whole matched text is returned.
11138 Note that a NL in the string can stand for a line break of a
11139 multi-line match or a NUL character in the text.
11140 Also see |sub-replace-expression|.
11141
11142 If {list} is present and non-zero then submatch() returns
11143 a list of strings, similar to |getline()| with two arguments.
11144 NL characters in the text represent NUL characters in the
11145 text.
11146 Only returns more than one item for |:substitute|, inside
11147 |substitute()| this list will always contain one or zero
11148 items, since there are no real line breaks.
11149
11150 When substitute() is used recursively only the submatches in
11151 the current (deepest) call can be obtained.
11152
11153 Examples: >
11154 :s/\d\+/\=submatch(0) + 1/
11155 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
11156 < This finds the first number in the line and adds one to it.
11157 A line break is included as a newline character.
11158
11159 Can also be used as a |method|: >
11160 GetNr()->submatch()
11161
11162 substitute({string}, {pat}, {sub}, {flags}) *substitute()*
11163 The result is a String, which is a copy of {string}, in which
11164 the first match of {pat} is replaced with {sub}.
11165 When {flags} is "g", all matches of {pat} in {string} are
11166 replaced. Otherwise {flags} should be "".
11167
11168 This works like the ":substitute" command (without any flags).
11169 But the matching with {pat} is always done like the 'magic'
11170 option is set and 'cpoptions' is empty (to make scripts
11171 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
11172 if you want to ignore or match case and ignore 'ignorecase'.
11173 'smartcase' is not used. See |string-match| for how {pat} is
11174 used.
11175
11176 A "~" in {sub} is not replaced with the previous {sub}.
11177 Note that some codes in {sub} have a special meaning
11178 |sub-replace-special|. For example, to replace something with
11179 "\n" (two characters), use "\\\\n" or '\\n'.
11180
11181 When {pat} does not match in {string}, {string} is returned
11182 unmodified.
11183
11184 Example: >
11185 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
11186 < This removes the last component of the 'path' option. >
11187 :echo substitute("testing", ".*", "\\U\\0", "")
11188 < results in "TESTING".
11189
11190 When {sub} starts with "\=", the remainder is interpreted as
11191 an expression. See |sub-replace-expression|. Example: >
11192 :echo substitute(s, '%\(\x\x\)',
11193 \ '\=nr2char("0x" . submatch(1))', 'g')
11194
11195 < When {sub} is a Funcref that function is called, with one
11196 optional argument. Example: >
11197 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
11198 < The optional argument is a list which contains the whole
11199 matched string and up to nine submatches, like what
11200 |submatch()| returns. Example: >
11201 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
11202
11203 < Can also be used as a |method|: >
11204 GetString()->substitute(pat, sub, flags)
11205
11206 swapinfo({fname}) *swapinfo()*
11207 The result is a dictionary, which holds information about the
11208 swapfile {fname}. The available fields are:
11209 version Vim version
11210 user user name
11211 host host name
11212 fname original file name
11213 pid PID of the Vim process that created the swap
11214 file
11215 mtime last modification time in seconds
11216 inode Optional: INODE number of the file
11217 dirty 1 if file was modified, 0 if not
11218 Note that "user" and "host" are truncated to at most 39 bytes.
11219 In case of failure an "error" item is added with the reason:
11220 Cannot open file: file not found or in accessible
11221 Cannot read file: cannot read first block
11222 Not a swap file: does not contain correct block ID
11223 Magic number mismatch: Info in first block is invalid
11224
11225 Can also be used as a |method|: >
11226 GetFilename()->swapinfo()
11227
11228 swapname({buf}) *swapname()*
11229 The result is the swap file path of the buffer {expr}.
11230 For the use of {buf}, see |bufname()| above.
11231 If buffer {buf} is the current buffer, the result is equal to
11232 |:swapname| (unless there is no swap file).
11233 If buffer {buf} has no swap file, returns an empty string.
11234
11235 Can also be used as a |method|: >
11236 GetBufname()->swapname()
11237
11238 synID({lnum}, {col}, {trans}) *synID()*
11239 The result is a Number, which is the syntax ID at the position
11240 {lnum} and {col} in the current window.
11241 The syntax ID can be used with |synIDattr()| and
11242 |synIDtrans()| to obtain syntax information about text.
11243
11244 {col} is 1 for the leftmost column, {lnum} is 1 for the first
11245 line. 'synmaxcol' applies, in a longer line zero is returned.
11246 Note that when the position is after the last character,
11247 that's where the cursor can be in Insert mode, synID() returns
11248 zero. {lnum} is used like with |getline()|.
11249
11250 When {trans} is |TRUE|, transparent items are reduced to the
11251 item that they reveal. This is useful when wanting to know
11252 the effective color. When {trans} is |FALSE|, the transparent
11253 item is returned. This is useful when wanting to know which
11254 syntax item is effective (e.g. inside parens).
11255 Warning: This function can be very slow. Best speed is
11256 obtained by going through the file in forward direction.
11257
11258 Example (echoes the name of the syntax item under the cursor): >
11259 :echo synIDattr(synID(line("."), col("."), 1), "name")
11260 <
11261
11262 synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
11263 The result is a String, which is the {what} attribute of
11264 syntax ID {synID}. This can be used to obtain information
11265 about a syntax item.
11266 {mode} can be "gui", "cterm" or "term", to get the attributes
11267 for that mode. When {mode} is omitted, or an invalid value is
11268 used, the attributes for the currently active highlighting are
11269 used (GUI, cterm or term).
11270 Use synIDtrans() to follow linked highlight groups.
11271 {what} result
11272 "name" the name of the syntax item
11273 "fg" foreground color (GUI: color name used to set
11274 the color, cterm: color number as a string,
11275 term: empty string)
11276 "bg" background color (as with "fg")
11277 "font" font name (only available in the GUI)
11278 |highlight-font|
11279 "sp" special color for the GUI (as with "fg")
11280 |highlight-guisp|
11281 "ul" underline color for cterm: number as a string
11282 "fg#" like "fg", but for the GUI and the GUI is
11283 running the name in "#RRGGBB" form
11284 "bg#" like "fg#" for "bg"
11285 "sp#" like "fg#" for "sp"
11286 "bold" "1" if bold
11287 "italic" "1" if italic
11288 "reverse" "1" if reverse
11289 "inverse" "1" if inverse (= reverse)
11290 "standout" "1" if standout
11291 "underline" "1" if underlined
11292 "undercurl" "1" if undercurled
11293 "strike" "1" if strikethrough
11294
11295 Example (echoes the color of the syntax item under the
11296 cursor): >
11297 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
11298 <
11299 Can also be used as a |method|: >
11300 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
11301
11302
11303 synIDtrans({synID}) *synIDtrans()*
11304 The result is a Number, which is the translated syntax ID of
11305 {synID}. This is the syntax group ID of what is being used to
11306 highlight the character. Highlight links given with
11307 ":highlight link" are followed.
11308
11309 Can also be used as a |method|: >
11310 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
11311
11312 synconcealed({lnum}, {col}) *synconcealed()*
11313 The result is a |List| with currently three items:
11314 1. The first item in the list is 0 if the character at the
11315 position {lnum} and {col} is not part of a concealable
11316 region, 1 if it is. {lnum} is used like with |getline()|.
11317 2. The second item in the list is a string. If the first item
11318 is 1, the second item contains the text which will be
11319 displayed in place of the concealed text, depending on the
11320 current setting of 'conceallevel' and 'listchars'.
11321 3. The third and final item in the list is a number
11322 representing the specific syntax region matched in the
11323 line. When the character is not concealed the value is
11324 zero. This allows detection of the beginning of a new
11325 concealable region if there are two consecutive regions
11326 with the same replacement character. For an example, if
11327 the text is "123456" and both "23" and "45" are concealed
11328 and replaced by the character "X", then:
11329 call returns ~
11330 synconcealed(lnum, 1) [0, '', 0]
11331 synconcealed(lnum, 2) [1, 'X', 1]
11332 synconcealed(lnum, 3) [1, 'X', 1]
11333 synconcealed(lnum, 4) [1, 'X', 2]
11334 synconcealed(lnum, 5) [1, 'X', 2]
11335 synconcealed(lnum, 6) [0, '', 0]
11336
11337
11338 synstack({lnum}, {col}) *synstack()*
11339 Return a |List|, which is the stack of syntax items at the
11340 position {lnum} and {col} in the current window. {lnum} is
11341 used like with |getline()|. Each item in the List is an ID
11342 like what |synID()| returns.
11343 The first item in the List is the outer region, following are
11344 items contained in that one. The last one is what |synID()|
11345 returns, unless not the whole item is highlighted or it is a
11346 transparent item.
11347 This function is useful for debugging a syntax file.
11348 Example that shows the syntax stack under the cursor: >
11349 for id in synstack(line("."), col("."))
11350 echo synIDattr(id, "name")
11351 endfor
11352 < When the position specified with {lnum} and {col} is invalid
11353 nothing is returned. The position just after the last
11354 character in a line and the first column in an empty line are
11355 valid positions.
11356
11357 system({expr} [, {input}]) *system()* *E677*
11358 Get the output of the shell command {expr} as a |String|. See
11359 |systemlist()| to get the output as a |List|.
11360
11361 When {input} is given and is a |String| this string is written
11362 to a file and passed as stdin to the command. The string is
11363 written as-is, you need to take care of using the correct line
11364 separators yourself.
11365 If {input} is given and is a |List| it is written to the file
11366 in a way |writefile()| does with {binary} set to "b" (i.e.
11367 with a newline between each list item with newlines inside
11368 list items converted to NULs).
11369 When {input} is given and is a number that is a valid id for
11370 an existing buffer then the content of the buffer is written
11371 to the file line by line, each line terminated by a NL and
11372 NULs characters where the text has a NL.
11373
11374 Pipes are not used, the 'shelltemp' option is not used.
11375
11376 When prepended by |:silent| the terminal will not be set to
11377 cooked mode. This is meant to be used for commands that do
11378 not need the user to type. It avoids stray characters showing
11379 up on the screen which require |CTRL-L| to remove. >
11380 :silent let f = system('ls *.vim')
11381 <
11382 Note: Use |shellescape()| or |::S| with |expand()| or
11383 |fnamemodify()| to escape special characters in a command
11384 argument. Newlines in {expr} may cause the command to fail.
11385 The characters in 'shellquote' and 'shellxquote' may also
11386 cause trouble.
11387 This is not to be used for interactive commands.
11388
11389 The result is a String. Example: >
11390 :let files = system("ls " . shellescape(expand('%:h')))
11391 :let files = system('ls ' . expand('%:h:S'))
11392
11393 < To make the result more system-independent, the shell output
11394 is filtered to replace <CR> with <NL> for Macintosh, and
11395 <CR><NL> with <NL> for DOS-like systems.
11396 To avoid the string being truncated at a NUL, all NUL
11397 characters are replaced with SOH (0x01).
11398
11399 The command executed is constructed using several options:
11400 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
11401 ({tmp} is an automatically generated file name).
11402 For Unix, braces are put around {expr} to allow for
11403 concatenated commands.
11404
11405 The command will be executed in "cooked" mode, so that a
11406 CTRL-C will interrupt the command (on Unix at least).
11407
11408 The resulting error code can be found in |v:shell_error|.
11409 This function will fail in |restricted-mode|.
11410
11411 Note that any wrong value in the options mentioned above may
11412 make the function fail. It has also been reported to fail
11413 when using a security agent application.
11414 Unlike ":!cmd" there is no automatic check for changed files.
11415 Use |:checktime| to force a check.
11416
11417 Can also be used as a |method|: >
11418 :echo GetCmd()->system()
11419
11420
11421 systemlist({expr} [, {input}]) *systemlist()*
11422 Same as |system()|, but returns a |List| with lines (parts of
11423 output separated by NL) with NULs transformed into NLs. Output
11424 is the same as |readfile()| will output with {binary} argument
11425 set to "b", except that there is no extra empty item when the
11426 result ends in a NL.
11427 Note that on MS-Windows you may get trailing CR characters.
11428
11429 To see the difference between "echo hello" and "echo -n hello"
11430 use |system()| and |split()|: >
11431 echo system('echo hello')->split('\n', 1)
11432 <
11433 Returns an empty string on error.
11434
11435 Can also be used as a |method|: >
11436 :echo GetCmd()->systemlist()
11437
11438
11439 tabpagebuflist([{arg}]) *tabpagebuflist()*
11440 The result is a |List|, where each item is the number of the
11441 buffer associated with each window in the current tab page.
11442 {arg} specifies the number of the tab page to be used. When
11443 omitted the current tab page is used.
11444 When {arg} is invalid the number zero is returned.
11445 To get a list of all buffers in all tabs use this: >
11446 let buflist = []
11447 for i in range(tabpagenr('$'))
11448 call extend(buflist, tabpagebuflist(i + 1))
11449 endfor
11450 < Note that a buffer may appear in more than one window.
11451
11452 Can also be used as a |method|: >
11453 GetTabpage()->tabpagebuflist()
11454
11455 tabpagenr([{arg}]) *tabpagenr()*
11456 The result is a Number, which is the number of the current
11457 tab page. The first tab page has number 1.
11458
11459 The optional argument {arg} supports the following values:
11460 $ the number of the last tab page (the tab page
11461 count).
11462 # the number of the last accessed tab page
11463 (where |g<Tab>| goes to). if there is no
11464 previous tab page 0 is returned.
11465 The number can be used with the |:tab| command.
11466
11467
11468 tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
11469 Like |winnr()| but for tab page {tabarg}.
11470 {tabarg} specifies the number of tab page to be used.
11471 {arg} is used like with |winnr()|:
11472 - When omitted the current window number is returned. This is
11473 the window which will be used when going to this tab page.
11474 - When "$" the number of windows is returned.
11475 - When "#" the previous window nr is returned.
11476 Useful examples: >
11477 tabpagewinnr(1) " current window of tab page 1
11478 tabpagewinnr(4, '$') " number of windows in tab page 4
11479 < When {tabarg} is invalid zero is returned.
11480
11481 Can also be used as a |method|: >
11482 GetTabpage()->tabpagewinnr()
11483 <
11484 *tagfiles()*
11485 tagfiles() Returns a |List| with the file names used to search for tags
11486 for the current buffer. This is the 'tags' option expanded.
11487
11488
11489 taglist({expr} [, {filename}]) *taglist()*
11490 Returns a |List| of tags matching the regular expression {expr}.
11491
11492 If {filename} is passed it is used to prioritize the results
11493 in the same way that |:tselect| does. See |tag-priority|.
11494 {filename} should be the full path of the file.
11495
11496 Each list item is a dictionary with at least the following
11497 entries:
11498 name Name of the tag.
11499 filename Name of the file where the tag is
11500 defined. It is either relative to the
11501 current directory or a full path.
11502 cmd Ex command used to locate the tag in
11503 the file.
11504 kind Type of the tag. The value for this
11505 entry depends on the language specific
11506 kind values. Only available when
11507 using a tags file generated by
11508 Exuberant ctags or hdrtag.
11509 static A file specific tag. Refer to
11510 |static-tag| for more information.
11511 More entries may be present, depending on the content of the
11512 tags file: access, implementation, inherits and signature.
11513 Refer to the ctags documentation for information about these
11514 fields. For C code the fields "struct", "class" and "enum"
11515 may appear, they give the name of the entity the tag is
11516 contained in.
11517
11518 The ex-command "cmd" can be either an ex search pattern, a
11519 line number or a line number followed by a byte number.
11520
11521 If there are no matching tags, then an empty list is returned.
11522
11523 To get an exact tag match, the anchors '^' and '$' should be
11524 used in {expr}. This also make the function work faster.
11525 Refer to |tag-regexp| for more information about the tag
11526 search regular expression pattern.
11527
11528 Refer to |'tags'| for information about how the tags file is
11529 located by Vim. Refer to |tags-file-format| for the format of
11530 the tags file generated by the different ctags tools.
11531
11532 Can also be used as a |method|: >
11533 GetTagpattern()->taglist()
11534
11535 tan({expr}) *tan()*
11536 Return the tangent of {expr}, measured in radians, as a |Float|
11537 in the range [-inf, inf].
11538 {expr} must evaluate to a |Float| or a |Number|.
11539 Examples: >
11540 :echo tan(10)
11541 < 0.648361 >
11542 :echo tan(-4.01)
11543 < -1.181502
11544
11545 Can also be used as a |method|: >
11546 Compute()->tan()
11547 <
11548 {only available when compiled with the |+float| feature}
11549
11550
11551 tanh({expr}) *tanh()*
11552 Return the hyperbolic tangent of {expr} as a |Float| in the
11553 range [-1, 1].
11554 {expr} must evaluate to a |Float| or a |Number|.
11555 Examples: >
11556 :echo tanh(0.5)
11557 < 0.462117 >
11558 :echo tanh(-1)
11559 < -0.761594
11560
11561 Can also be used as a |method|: >
11562 Compute()->tanh()
11563 <
11564 {only available when compiled with the |+float| feature}
11565
11566
11567 tempname() *tempname()* *temp-file-name*
11568 The result is a String, which is the name of a file that
11569 doesn't exist. It can be used for a temporary file. The name
11570 is different for at least 26 consecutive calls. Example: >
11571 :let tmpfile = tempname()
11572 :exe "redir > " . tmpfile
11573 < For Unix, the file will be in a private directory |tempfile|.
11574 For MS-Windows forward slashes are used when the 'shellslash'
11575 option is set, or when 'shellcmdflag' starts with '-' and
11576 'shell' does not contain powershell or pwsh.
11577
11578
11579 term_ functions are documented here: |terminal-function-details|
11580
11581
11582 terminalprops() *terminalprops()*
11583 Returns a |Dictionary| with properties of the terminal that Vim
11584 detected from the response to |t_RV| request. See
11585 |v:termresponse| for the response itself. If |v:termresponse|
11586 is empty most values here will be 'u' for unknown.
11587 cursor_style whether sending |t_RS| works **
11588 cursor_blink_mode whether sending |t_RC| works **
11589 underline_rgb whether |t_8u| works **
11590 mouse mouse type supported
11591
11592 ** value 'u' for unknown, 'y' for yes, 'n' for no
11593
11594 If the |+termresponse| feature is missing then the result is
11595 an empty dictionary.
11596
11597 If "cursor_style" is 'y' then |t_RS| will be sent to request the
11598 current cursor style.
11599 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to
11600 request the cursor blink status.
11601 "cursor_style" and "cursor_blink_mode" are also set if |t_u7|
11602 is not empty, Vim will detect the working of sending |t_RS|
11603 and |t_RC| on startup.
11604
11605 When "underline_rgb" is not 'y', then |t_8u| will be made empty.
11606 This avoids sending it to xterm, which would clear the colors.
11607
11608 For "mouse" the value 'u' is unknown
11609
11610 Also see:
11611 - 'ambiwidth' - detected by using |t_u7|.
11612 - |v:termstyleresp| and |v:termblinkresp| for the response to
11613 |t_RS| and |t_RC|.
11614
11615
11616 test_ functions are documented here: |test-functions-details|
11617
11618
11619 *timer_info()*
11620 timer_info([{id}])
11621 Return a list with information about timers.
11622 When {id} is given only information about this timer is
11623 returned. When timer {id} does not exist an empty list is
11624 returned.
11625 When {id} is omitted information about all timers is returned.
11626
11627 For each timer the information is stored in a |Dictionary| with
11628 these items:
11629 "id" the timer ID
11630 "time" time the timer was started with
11631 "remaining" time until the timer fires
11632 "repeat" number of times the timer will still fire;
11633 -1 means forever
11634 "callback" the callback
11635 "paused" 1 if the timer is paused, 0 otherwise
11636
11637 Can also be used as a |method|: >
11638 GetTimer()->timer_info()
11639
11640 < {only available when compiled with the |+timers| feature}
11641
11642 timer_pause({timer}, {paused}) *timer_pause()*
11643 Pause or unpause a timer. A paused timer does not invoke its
11644 callback when its time expires. Unpausing a timer may cause
11645 the callback to be invoked almost immediately if enough time
11646 has passed.
11647
11648 Pausing a timer is useful to avoid the callback to be called
11649 for a short time.
11650
11651 If {paused} evaluates to a non-zero Number or a non-empty
11652 String, then the timer is paused, otherwise it is unpaused.
11653 See |non-zero-arg|.
11654
11655 Can also be used as a |method|: >
11656 GetTimer()->timer_pause(1)
11657
11658 < {only available when compiled with the |+timers| feature}
11659
11660 *timer_start()* *timer* *timers*
11661 timer_start({time}, {callback} [, {options}])
11662 Create a timer and return the timer ID.
11663
11664 {time} is the waiting time in milliseconds. This is the
11665 minimum time before invoking the callback. When the system is
11666 busy or Vim is not waiting for input the time will be longer.
11667
11668 {callback} is the function to call. It can be the name of a
11669 function or a |Funcref|. It is called with one argument, which
11670 is the timer ID. The callback is only invoked when Vim is
11671 waiting for input.
11672 If you want to show a message look at |popup_notification()|
11673 to avoid interfering with what the user is doing.
11674
11675 {options} is a dictionary. Supported entries:
11676 "repeat" Number of times to repeat calling the
11677 callback. -1 means forever. When not present
11678 the callback will be called once.
11679 If the timer causes an error three times in a
11680 row the repeat is cancelled. This avoids that
11681 Vim becomes unusable because of all the error
11682 messages.
11683
11684 Example: >
11685 func MyHandler(timer)
11686 echo 'Handler called'
11687 endfunc
11688 let timer = timer_start(500, 'MyHandler',
11689 \ {'repeat': 3})
11690 < This will invoke MyHandler() three times at 500 msec
11691 intervals.
11692
11693 Can also be used as a |method|: >
11694 GetMsec()->timer_start(callback)
11695
11696 < Not available in the |sandbox|.
11697 {only available when compiled with the |+timers| feature}
11698
11699 timer_stop({timer}) *timer_stop()*
11700 Stop a timer. The timer callback will no longer be invoked.
11701 {timer} is an ID returned by timer_start(), thus it must be a
11702 Number. If {timer} does not exist there is no error.
11703
11704 Can also be used as a |method|: >
11705 GetTimer()->timer_stop()
11706
11707 < {only available when compiled with the |+timers| feature}
11708
11709 timer_stopall() *timer_stopall()*
11710 Stop all timers. The timer callbacks will no longer be
11711 invoked. Useful if a timer is misbehaving. If there are no
11712 timers there is no error.
11713
11714 {only available when compiled with the |+timers| feature}
11715
11716 tolower({expr}) *tolower()*
11717 The result is a copy of the String given, with all uppercase
11718 characters turned into lowercase (just like applying |gu| to
11719 the string).
11720
11721 Can also be used as a |method|: >
11722 GetText()->tolower()
11723
11724 toupper({expr}) *toupper()*
11725 The result is a copy of the String given, with all lowercase
11726 characters turned into uppercase (just like applying |gU| to
11727 the string).
11728
11729 Can also be used as a |method|: >
11730 GetText()->toupper()
11731
11732 tr({src}, {fromstr}, {tostr}) *tr()*
11733 The result is a copy of the {src} string with all characters
11734 which appear in {fromstr} replaced by the character in that
11735 position in the {tostr} string. Thus the first character in
11736 {fromstr} is translated into the first character in {tostr}
11737 and so on. Exactly like the unix "tr" command.
11738 This code also deals with multibyte characters properly.
11739
11740 Examples: >
11741 echo tr("hello there", "ht", "HT")
11742 < returns "Hello THere" >
11743 echo tr("<blob>", "<>", "{}")
11744 < returns "{blob}"
11745
11746 Can also be used as a |method|: >
11747 GetText()->tr(from, to)
11748
11749 trim({text} [, {mask} [, {dir}]]) *trim()*
11750 Return {text} as a String where any character in {mask} is
11751 removed from the beginning and/or end of {text}.
11752
11753 If {mask} is not given, {mask} is all characters up to 0x20,
11754 which includes Tab, space, NL and CR, plus the non-breaking
11755 space character 0xa0.
11756
11757 The optional {dir} argument specifies where to remove the
11758 characters:
11759 0 remove from the beginning and end of {text}
11760 1 remove only at the beginning of {text}
11761 2 remove only at the end of {text}
11762 When omitted both ends are trimmed.
11763
11764 This function deals with multibyte characters properly.
11765
11766 Examples: >
11767 echo trim(" some text ")
11768 < returns "some text" >
11769 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
11770 < returns "RESERVE_TAIL" >
11771 echo trim("rm<Xrm<>X>rrm", "rm<>")
11772 < returns "Xrm<>X" (characters in the middle are not removed) >
11773 echo trim(" vim ", " ", 2)
11774 < returns " vim"
11775
11776 Can also be used as a |method|: >
11777 GetText()->trim()
11778
11779 trunc({expr}) *trunc()*
11780 Return the largest integral value with magnitude less than or
11781 equal to {expr} as a |Float| (truncate towards zero).
11782 {expr} must evaluate to a |Float| or a |Number|.
11783 Examples: >
11784 echo trunc(1.456)
11785 < 1.0 >
11786 echo trunc(-5.456)
11787 < -5.0 >
11788 echo trunc(4.0)
11789 < 4.0
11790
11791 Can also be used as a |method|: >
11792 Compute()->trunc()
11793 <
11794 {only available when compiled with the |+float| feature}
11795
11796 *type()*
11797 type({expr}) The result is a Number representing the type of {expr}.
11798 Instead of using the number directly, it is better to use the
11799 v:t_ variable that has the value:
11800 Number: 0 |v:t_number|
11801 String: 1 |v:t_string|
11802 Funcref: 2 |v:t_func|
11803 List: 3 |v:t_list|
11804 Dictionary: 4 |v:t_dict|
11805 Float: 5 |v:t_float|
11806 Boolean: 6 |v:t_bool| (v:false and v:true)
11807 None: 7 |v:t_none| (v:null and v:none)
11808 Job: 8 |v:t_job|
11809 Channel: 9 |v:t_channel|
11810 Blob: 10 |v:t_blob|
11811 For backward compatibility, this method can be used: >
11812 :if type(myvar) == type(0)
11813 :if type(myvar) == type("")
11814 :if type(myvar) == type(function("tr"))
11815 :if type(myvar) == type([])
11816 :if type(myvar) == type({})
11817 :if type(myvar) == type(0.0)
11818 :if type(myvar) == type(v:false)
11819 :if type(myvar) == type(v:none)
11820 < To check if the v:t_ variables exist use this: >
11821 :if exists('v:t_number')
11822
11823 < Can also be used as a |method|: >
11824 mylist->type()
11825
11826
11827 typename({expr}) *typename()*
11828 Return a string representation of the type of {expr}.
11829 Example: >
11830 echo typename([1, 2, 3])
11831 list<number>
11832
11833
11834 undofile({name}) *undofile()*
11835 Return the name of the undo file that would be used for a file
11836 with name {name} when writing. This uses the 'undodir'
11837 option, finding directories that exist. It does not check if
11838 the undo file exists.
11839 {name} is always expanded to the full path, since that is what
11840 is used internally.
11841 If {name} is empty undofile() returns an empty string, since a
11842 buffer without a file name will not write an undo file.
11843 Useful in combination with |:wundo| and |:rundo|.
11844 When compiled without the |+persistent_undo| option this always
11845 returns an empty string.
11846
11847 Can also be used as a |method|: >
11848 GetFilename()->undofile()
11849
11850 undotree() *undotree()*
11851 Return the current state of the undo tree in a dictionary with
11852 the following items:
11853 "seq_last" The highest undo sequence number used.
11854 "seq_cur" The sequence number of the current position in
11855 the undo tree. This differs from "seq_last"
11856 when some changes were undone.
11857 "time_cur" Time last used for |:earlier| and related
11858 commands. Use |strftime()| to convert to
11859 something readable.
11860 "save_last" Number of the last file write. Zero when no
11861 write yet.
11862 "save_cur" Number of the current position in the undo
11863 tree.
11864 "synced" Non-zero when the last undo block was synced.
11865 This happens when waiting from input from the
11866 user. See |undo-blocks|.
11867 "entries" A list of dictionaries with information about
11868 undo blocks.
11869
11870 The first item in the "entries" list is the oldest undo item.
11871 Each List item is a |Dictionary| with these items:
11872 "seq" Undo sequence number. Same as what appears in
11873 |:undolist|.
11874 "time" Timestamp when the change happened. Use
11875 |strftime()| to convert to something readable.
11876 "newhead" Only appears in the item that is the last one
11877 that was added. This marks the last change
11878 and where further changes will be added.
11879 "curhead" Only appears in the item that is the last one
11880 that was undone. This marks the current
11881 position in the undo tree, the block that will
11882 be used by a redo command. When nothing was
11883 undone after the last change this item will
11884 not appear anywhere.
11885 "save" Only appears on the last block before a file
11886 write. The number is the write count. The
11887 first write has number 1, the last one the
11888 "save_last" mentioned above.
11889 "alt" Alternate entry. This is again a List of undo
11890 blocks. Each item may again have an "alt"
11891 item.
11892
11893 uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
11894 Remove second and succeeding copies of repeated adjacent
11895 {list} items in-place. Returns {list}. If you want a list
11896 to remain unmodified make a copy first: >
11897 :let newlist = uniq(copy(mylist))
11898 < The default compare function uses the string representation of
11899 each item. For the use of {func} and {dict} see |sort()|.
11900
11901 Can also be used as a |method|: >
11902 mylist->uniq()
11903
11904 values({dict}) *values()*
11905 Return a |List| with all the values of {dict}. The |List| is
11906 in arbitrary order. Also see |items()| and |keys()|.
11907
11908 Can also be used as a |method|: >
11909 mydict->values()
11910
11911 virtcol({expr}) *virtcol()*
11912 The result is a Number, which is the screen column of the file
11913 position given with {expr}. That is, the last screen position
11914 occupied by the character at that position, when the screen
11915 would be of unlimited width. When there is a <Tab> at the
11916 position, the returned Number will be the column at the end of
11917 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
11918 set to 8, it returns 8. |conceal| is ignored.
11919 For the byte position use |col()|.
11920 For the use of {expr} see |col()|.
11921 When 'virtualedit' is used {expr} can be [lnum, col, off], where
11922 "off" is the offset in screen columns from the start of the
11923 character. E.g., a position within a <Tab> or after the last
11924 character. When "off" is omitted zero is used.
11925 When Virtual editing is active in the current mode, a position
11926 beyond the end of the line can be returned. |'virtualedit'|
11927 The accepted positions are:
11928 . the cursor position
11929 $ the end of the cursor line (the result is the
11930 number of displayed characters in the cursor line
11931 plus one)
11932 'x position of mark x (if the mark is not set, 0 is
11933 returned)
11934 v In Visual mode: the start of the Visual area (the
11935 cursor is the end). When not in Visual mode
11936 returns the cursor position. Differs from |'<| in
11937 that it's updated right away.
11938 Note that only marks in the current file can be used.
11939 Examples: >
11940 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
11941 virtcol("$") with text "foo^Lbar", returns 9
11942 virtcol("'t") with text " there", with 't at 'h', returns 6
11943 < The first column is 1. 0 is returned for an error.
11944 A more advanced example that echoes the maximum length of
11945 all lines: >
11946 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
11947
11948 < Can also be used as a |method|: >
11949 GetPos()->virtcol()
11950
11951
11952 visualmode([{expr}]) *visualmode()*
11953 The result is a String, which describes the last Visual mode
11954 used in the current buffer. Initially it returns an empty
11955 string, but once Visual mode has been used, it returns "v",
11956 "V", or "<CTRL-V>" (a single CTRL-V character) for
11957 character-wise, line-wise, or block-wise Visual mode
11958 respectively.
11959 Example: >
11960 :exe "normal " . visualmode()
11961 < This enters the same Visual mode as before. It is also useful
11962 in scripts if you wish to act differently depending on the
11963 Visual mode that was used.
11964 If Visual mode is active, use |mode()| to get the Visual mode
11965 (e.g., in a |:vmap|).
11966 If {expr} is supplied and it evaluates to a non-zero Number or
11967 a non-empty String, then the Visual mode will be cleared and
11968 the old value is returned. See |non-zero-arg|.
11969
11970 wildmenumode() *wildmenumode()*
11971 Returns |TRUE| when the wildmenu is active and |FALSE|
11972 otherwise. See 'wildmenu' and 'wildmode'.
11973 This can be used in mappings to handle the 'wildcharm' option
11974 gracefully. (Makes only sense with |mapmode-c| mappings).
11975
11976 For example to make <c-j> work like <down> in wildmode, use: >
11977 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
11978 <
11979 (Note, this needs the 'wildcharm' option set appropriately).
11980
11981 win_execute({id}, {command} [, {silent}]) *win_execute()*
11982 Like `execute()` but in the context of window {id}.
11983 The window will temporarily be made the current window,
11984 without triggering autocommands or changing directory. When
11985 executing {command} autocommands will be triggered, this may
11986 have unexpected side effects. Use |:noautocmd| if needed.
11987 Example: >
11988 call win_execute(winid, 'set syntax=python')
11989 < Doing the same with `setwinvar()` would not trigger
11990 autocommands and not actually show syntax highlighting.
11991
11992 *E994*
11993 Not all commands are allowed in popup windows.
11994 When window {id} does not exist then no error is given and
11995 an empty string is returned.
11996
11997 Can also be used as a |method|, the base is passed as the
11998 second argument: >
11999 GetCommand()->win_execute(winid)
12000
12001 win_findbuf({bufnr}) *win_findbuf()*
12002 Returns a |List| with |window-ID|s for windows that contain
12003 buffer {bufnr}. When there is none the list is empty.
12004
12005 Can also be used as a |method|: >
12006 GetBufnr()->win_findbuf()
12007
12008 win_getid([{win} [, {tab}]]) *win_getid()*
12009 Get the |window-ID| for the specified window.
12010 When {win} is missing use the current window.
12011 With {win} this is the window number. The top window has
12012 number 1.
12013 Without {tab} use the current tab, otherwise the tab with
12014 number {tab}. The first tab has number one.
12015 Return zero if the window cannot be found.
12016
12017 Can also be used as a |method|: >
12018 GetWinnr()->win_getid()
12019
12020
12021 win_gettype([{nr}]) *win_gettype()*
12022 Return the type of the window:
12023 "autocmd" autocommand window. Temporary window
12024 used to execute autocommands.
12025 "command" command-line window |cmdwin|
12026 (empty) normal window
12027 "loclist" |location-list-window|
12028 "popup" popup window |popup|
12029 "preview" preview window |preview-window|
12030 "quickfix" |quickfix-window|
12031 "unknown" window {nr} not found
12032
12033 When {nr} is omitted return the type of the current window.
12034 When {nr} is given return the type of this window by number or
12035 |window-ID|.
12036
12037 Also see the 'buftype' option. When running a terminal in a
12038 popup window then 'buftype' is "terminal" and win_gettype()
12039 returns "popup".
12040
12041 Can also be used as a |method|: >
12042 GetWinid()->win_gettype()
12043 <
12044 win_gotoid({expr}) *win_gotoid()*
12045 Go to window with ID {expr}. This may also change the current
12046 tabpage.
12047 Return TRUE if successful, FALSE if the window cannot be found.
12048
12049 Can also be used as a |method|: >
12050 GetWinid()->win_gotoid()
12051
12052 win_id2tabwin({expr}) *win_id2tabwin()*
12053 Return a list with the tab number and window number of window
12054 with ID {expr}: [tabnr, winnr].
12055 Return [0, 0] if the window cannot be found.
12056
12057 Can also be used as a |method|: >
12058 GetWinid()->win_id2tabwin()
12059
12060 win_id2win({expr}) *win_id2win()*
12061 Return the window number of window with ID {expr}.
12062 Return 0 if the window cannot be found in the current tabpage.
12063
12064 Can also be used as a |method|: >
12065 GetWinid()->win_id2win()
12066
12067 win_screenpos({nr}) *win_screenpos()*
12068 Return the screen position of window {nr} as a list with two
12069 numbers: [row, col]. The first window always has position
12070 [1, 1], unless there is a tabline, then it is [2, 1].
12071 {nr} can be the window number or the |window-ID|. Use zero
12072 for the current window.
12073 Returns [0, 0] if the window cannot be found in the current
12074 tabpage.
12075
12076 Can also be used as a |method|: >
12077 GetWinid()->win_screenpos()
12078 <
12079 win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
12080 Move the window {nr} to a new split of the window {target}.
12081 This is similar to moving to {target}, creating a new window
12082 using |:split| but having the same contents as window {nr}, and
12083 then closing {nr}.
12084
12085 Both {nr} and {target} can be window numbers or |window-ID|s.
12086 Both must be in the current tab page.
12087
12088 Returns zero for success, non-zero for failure.
12089
12090 {options} is a |Dictionary| with the following optional entries:
12091 "vertical" When TRUE, the split is created vertically,
12092 like with |:vsplit|.
12093 "rightbelow" When TRUE, the split is made below or to the
12094 right (if vertical). When FALSE, it is done
12095 above or to the left (if vertical). When not
12096 present, the values of 'splitbelow' and
12097 'splitright' are used.
12098
12099 Can also be used as a |method|: >
12100 GetWinid()->win_splitmove(target)
12101 <
12102
12103 *winbufnr()*
12104 winbufnr({nr}) The result is a Number, which is the number of the buffer
12105 associated with window {nr}. {nr} can be the window number or
12106 the |window-ID|.
12107 When {nr} is zero, the number of the buffer in the current
12108 window is returned.
12109 When window {nr} doesn't exist, -1 is returned.
12110 Example: >
12111 :echo "The file in the current window is " . bufname(winbufnr(0))
12112 <
12113 Can also be used as a |method|: >
12114 FindWindow()->winbufnr()->bufname()
12115 <
12116 *wincol()*
12117 wincol() The result is a Number, which is the virtual column of the
12118 cursor in the window. This is counting screen cells from the
12119 left side of the window. The leftmost column is one.
12120
12121 *windowsversion()*
12122 windowsversion()
12123 The result is a String. For MS-Windows it indicates the OS
12124 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2",
12125 Windows XP is "5.1". For non-MS-Windows systems the result is
12126 an empty string.
12127
12128 winheight({nr}) *winheight()*
12129 The result is a Number, which is the height of window {nr}.
12130 {nr} can be the window number or the |window-ID|.
12131 When {nr} is zero, the height of the current window is
12132 returned. When window {nr} doesn't exist, -1 is returned.
12133 An existing window always has a height of zero or more.
12134 This excludes any window toolbar line.
12135 Examples: >
12136 :echo "The current window has " . winheight(0) . " lines."
12137
12138 < Can also be used as a |method|: >
12139 GetWinid()->winheight()
12140 <
12141 winlayout([{tabnr}]) *winlayout()*
12142 The result is a nested List containing the layout of windows
12143 in a tabpage.
12144
12145 Without {tabnr} use the current tabpage, otherwise the tabpage
12146 with number {tabnr}. If the tabpage {tabnr} is not found,
12147 returns an empty list.
12148
12149 For a leaf window, it returns:
12150 ['leaf', {winid}]
12151 For horizontally split windows, which form a column, it
12152 returns:
12153 ['col', [{nested list of windows}]]
12154 For vertically split windows, which form a row, it returns:
12155 ['row', [{nested list of windows}]]
12156
12157 Example: >
12158 " Only one window in the tab page
12159 :echo winlayout()
12160 ['leaf', 1000]
12161 " Two horizontally split windows
12162 :echo winlayout()
12163 ['col', [['leaf', 1000], ['leaf', 1001]]]
12164 " The second tab page, with three horizontally split
12165 " windows, with two vertically split windows in the
12166 " middle window
12167 :echo winlayout(2)
12168 ['col', [['leaf', 1002], ['row', [['leaf', 1003],
12169 ['leaf', 1001]]], ['leaf', 1000]]]
12170 <
12171 Can also be used as a |method|: >
12172 GetTabnr()->winlayout()
12173 <
12174 *winline()*
12175 winline() The result is a Number, which is the screen line of the cursor
12176 in the window. This is counting screen lines from the top of
12177 the window. The first line is one.
12178 If the cursor was moved the view on the file will be updated
12179 first, this may cause a scroll.
12180
12181 *winnr()*
12182 winnr([{arg}]) The result is a Number, which is the number of the current
12183 window. The top window has number 1.
12184 Returns zero for a popup window.
12185
12186 The optional argument {arg} supports the following values:
12187 $ the number of the last window (the window
12188 count).
12189 # the number of the last accessed window (where
12190 |CTRL-W_p| goes to). If there is no previous
12191 window or it is in another tab page 0 is
12192 returned.
12193 {N}j the number of the Nth window below the
12194 current window (where |CTRL-W_j| goes to).
12195 {N}k the number of the Nth window above the current
12196 window (where |CTRL-W_k| goes to).
12197 {N}h the number of the Nth window left of the
12198 current window (where |CTRL-W_h| goes to).
12199 {N}l the number of the Nth window right of the
12200 current window (where |CTRL-W_l| goes to).
12201 The number can be used with |CTRL-W_w| and ":wincmd w"
12202 |:wincmd|.
12203 Also see |tabpagewinnr()| and |win_getid()|.
12204 Examples: >
12205 let window_count = winnr('$')
12206 let prev_window = winnr('#')
12207 let wnum = winnr('3k')
12208
12209 < Can also be used as a |method|: >
12210 GetWinval()->winnr()
12211 <
12212 *winrestcmd()*
12213 winrestcmd() Returns a sequence of |:resize| commands that should restore
12214 the current window sizes. Only works properly when no windows
12215 are opened or closed and the current window and tab page is
12216 unchanged.
12217 Example: >
12218 :let cmd = winrestcmd()
12219 :call MessWithWindowSizes()
12220 :exe cmd
12221 <
12222 *winrestview()*
12223 winrestview({dict})
12224 Uses the |Dictionary| returned by |winsaveview()| to restore
12225 the view of the current window.
12226 Note: The {dict} does not have to contain all values, that are
12227 returned by |winsaveview()|. If values are missing, those
12228 settings won't be restored. So you can use: >
12229 :call winrestview({'curswant': 4})
12230 <
12231 This will only set the curswant value (the column the cursor
12232 wants to move on vertical movements) of the cursor to column 5
12233 (yes, that is 5), while all other settings will remain the
12234 same. This is useful, if you set the cursor position manually.
12235
12236 If you have changed the values the result is unpredictable.
12237 If the window size changed the result won't be the same.
12238
12239 Can also be used as a |method|: >
12240 GetView()->winrestview()
12241 <
12242 *winsaveview()*
12243 winsaveview() Returns a |Dictionary| that contains information to restore
12244 the view of the current window. Use |winrestview()| to
12245 restore the view.
12246 This is useful if you have a mapping that jumps around in the
12247 buffer and you want to go back to the original view.
12248 This does not save fold information. Use the 'foldenable'
12249 option to temporarily switch off folding, so that folds are
12250 not opened when moving around. This may have side effects.
12251 The return value includes:
12252 lnum cursor line number
12253 col cursor column (Note: the first column
12254 zero, as opposed to what getpos()
12255 returns)
12256 coladd cursor column offset for 'virtualedit'
12257 curswant column for vertical movement
12258 topline first line in the window
12259 topfill filler lines, only in diff mode
12260 leftcol first column displayed; only used when
12261 'wrap' is off
12262 skipcol columns skipped
12263 Note that no option values are saved.
12264
12265
12266 winwidth({nr}) *winwidth()*
12267 The result is a Number, which is the width of window {nr}.
12268 {nr} can be the window number or the |window-ID|.
12269 When {nr} is zero, the width of the current window is
12270 returned. When window {nr} doesn't exist, -1 is returned.
12271 An existing window always has a width of zero or more.
12272 Examples: >
12273 :echo "The current window has " . winwidth(0) . " columns."
12274 :if winwidth(0) <= 50
12275 : 50 wincmd |
12276 :endif
12277 < For getting the terminal or screen size, see the 'columns'
12278 option.
12279
12280 Can also be used as a |method|: >
12281 GetWinid()->winwidth()
12282
12283
12284 wordcount() *wordcount()*
12285 The result is a dictionary of byte/chars/word statistics for
12286 the current buffer. This is the same info as provided by
12287 |g_CTRL-G|
12288 The return value includes:
12289 bytes Number of bytes in the buffer
12290 chars Number of chars in the buffer
12291 words Number of words in the buffer
12292 cursor_bytes Number of bytes before cursor position
12293 (not in Visual mode)
12294 cursor_chars Number of chars before cursor position
12295 (not in Visual mode)
12296 cursor_words Number of words before cursor position
12297 (not in Visual mode)
12298 visual_bytes Number of bytes visually selected
12299 (only in Visual mode)
12300 visual_chars Number of chars visually selected
12301 (only in Visual mode)
12302 visual_words Number of words visually selected
12303 (only in Visual mode)
12304
12305
12306 *writefile()*
12307 writefile({object}, {fname} [, {flags}])
12308 When {object} is a |List| write it to file {fname}. Each list
12309 item is separated with a NL. Each list item must be a String
12310 or Number.
12311 When {flags} contains "b" then binary mode is used: There will
12312 not be a NL after the last list item. An empty item at the
12313 end does cause the last line in the file to end in a NL.
12314
12315 When {object} is a |Blob| write the bytes to file {fname}
12316 unmodified.
12317
12318 When {flags} contains "a" then append mode is used, lines are
12319 appended to the file: >
12320 :call writefile(["foo"], "event.log", "a")
12321 :call writefile(["bar"], "event.log", "a")
12322 <
12323 When {flags} contains "s" then fsync() is called after writing
12324 the file. This flushes the file to disk, if possible. This
12325 takes more time but avoids losing the file if the system
12326 crashes.
12327 When {flags} does not contain "S" or "s" then fsync() is
12328 called if the 'fsync' option is set.
12329 When {flags} contains "S" then fsync() is not called, even
12330 when 'fsync' is set.
12331
12332 All NL characters are replaced with a NUL character.
12333 Inserting CR characters needs to be done before passing {list}
12334 to writefile().
12335 An existing file is overwritten, if possible.
12336 When the write fails -1 is returned, otherwise 0. There is an
12337 error message if the file can't be created or when writing
12338 fails.
12339 Also see |readfile()|.
12340 To copy a file byte for byte: >
12341 :let fl = readfile("foo", "b")
12342 :call writefile(fl, "foocopy", "b")
12343
12344 < Can also be used as a |method|: >
12345 GetText()->writefile("thefile")
12346
12347
12348 xor({expr}, {expr}) *xor()*
12349 Bitwise XOR on the two arguments. The arguments are converted
12350 to a number. A List, Dict or Float argument causes an error.
12351 Example: >
12352 :let bits = xor(bits, 0x80)
12353 <
12354 Can also be used as a |method|: >
12355 :let bits = bits->xor(0x80)
12356 <
12357
12358 *feature-list*
12359 There are three types of features:
12360 1. Features that are only supported when they have been enabled when Vim
12361 was compiled |+feature-list|. Example: >
12362 :if has("cindent")
12363 < *gui_running*
12364 2. Features that are only supported when certain conditions have been met.
12365 Example: >
12366 :if has("gui_running")
12367 < *has-patch*
12368 3. Beyond a certain version or at a certain version and including a specific
12369 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
12370 later, or it is version 7.4 and patch 248 was included. Example: >
12371 :if has("patch-7.4.248")
12372 < Note that it's possible for patch 248 to be omitted even though 249 is
12373 included. Only happens when cherry-picking patches.
12374 Note that this form only works for patch 7.4.237 and later, before that
12375 you need to check for the patch and the v:version. Example (checking
12376 version 6.2.148 or later): >
12377 :if v:version > 602 || (v:version == 602 && has("patch148"))
12378
12379 Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
12380 use: `if exists('+shellslash')`
12381
12382
12383 acl Compiled with |ACL| support.
12384 all_builtin_terms Compiled with all builtin terminals enabled.
12385 amiga Amiga version of Vim.
12386 arabic Compiled with Arabic support |Arabic|.
12387 arp Compiled with ARP support (Amiga).
12388 autocmd Compiled with autocommand support. (always true)
12389 autochdir Compiled with support for 'autochdir'
12390 autoservername Automatically enable |clientserver|
12391 balloon_eval Compiled with |balloon-eval| support.
12392 balloon_multiline GUI supports multiline balloons.
12393 beos BeOS version of Vim.
12394 browse Compiled with |:browse| support, and browse() will
12395 work.
12396 browsefilter Compiled with support for |browsefilter|.
12397 bsd Compiled on an OS in the BSD family (excluding macOS).
12398 builtin_terms Compiled with some builtin terminals.
12399 byte_offset Compiled with support for 'o' in 'statusline'
12400 channel Compiled with support for |channel| and |job|
12401 cindent Compiled with 'cindent' support.
12402 clientserver Compiled with remote invocation support |clientserver|.
12403 clipboard Compiled with 'clipboard' support.
12404 clipboard_working Compiled with 'clipboard' support and it can be used.
12405 cmdline_compl Compiled with |cmdline-completion| support.
12406 cmdline_hist Compiled with |cmdline-history| support.
12407 cmdline_info Compiled with 'showcmd' and 'ruler' support.
12408 comments Compiled with |'comments'| support.
12409 compatible Compiled to be very Vi compatible.
12410 conpty Platform where |ConPTY| can be used.
12411 cryptv Compiled with encryption support |encryption|.
12412 cscope Compiled with |cscope| support.
12413 cursorbind Compiled with |'cursorbind'| (always true)
12414 debug Compiled with "DEBUG" defined.
12415 dialog_con Compiled with console dialog support.
12416 dialog_gui Compiled with GUI dialog support.
12417 diff Compiled with |vimdiff| and 'diff' support.
12418 digraphs Compiled with support for digraphs.
12419 directx Compiled with support for DirectX and 'renderoptions'.
12420 dnd Compiled with support for the "~ register |quote_~|.
12421 drop_file Compiled with |drop_file| support.
12422 ebcdic Compiled on a machine with ebcdic character set.
12423 emacs_tags Compiled with support for Emacs tags.
12424 eval Compiled with expression evaluation support. Always
12425 true, of course!
12426 ex_extra |+ex_extra| (always true)
12427 extra_search Compiled with support for |'incsearch'| and
12428 |'hlsearch'|
12429 farsi Support for Farsi was removed |farsi|.
12430 file_in_path Compiled with support for |gf| and |<cfile>|
12431 filterpipe When 'shelltemp' is off pipes are used for shell
12432 read/write/filter commands
12433 find_in_path Compiled with support for include file searches
12434 |+find_in_path|.
12435 float Compiled with support for |Float|.
12436 fname_case Case in file names matters (for Amiga and MS-Windows
12437 this is not present).
12438 folding Compiled with |folding| support.
12439 footer Compiled with GUI footer support. |gui-footer|
12440 fork Compiled to use fork()/exec() instead of system().
12441 gettext Compiled with message translation |multi-lang|
12442 gui Compiled with GUI enabled.
12443 gui_athena Compiled with Athena GUI.
12444 gui_gnome Compiled with Gnome support (gui_gtk is also defined).
12445 gui_gtk Compiled with GTK+ GUI (any version).
12446 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
12447 gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
12448 gui_haiku Compiled with Haiku GUI.
12449 gui_mac Compiled with Macintosh GUI.
12450 gui_motif Compiled with Motif GUI.
12451 gui_photon Compiled with Photon GUI.
12452 gui_running Vim is running in the GUI, or it will start soon.
12453 gui_win32 Compiled with MS-Windows Win32 GUI.
12454 gui_win32s idem, and Win32s system being used (Windows 3.1)
12455 haiku Haiku version of Vim.
12456 hangul_input Compiled with Hangul input support. |hangul|
12457 hpux HP-UX version of Vim.
12458 iconv Can use iconv() for conversion.
12459 insert_expand Compiled with support for CTRL-X expansion commands in
12460 Insert mode. (always true)
12461 job Compiled with support for |channel| and |job|
12462 ipv6 Compiled with support for IPv6 networking in |channel|.
12463 jumplist Compiled with |jumplist| support.
12464 keymap Compiled with 'keymap' support.
12465 lambda Compiled with |lambda| support.
12466 langmap Compiled with 'langmap' support.
12467 libcall Compiled with |libcall()| support.
12468 linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
12469 'breakindent' support.
12470 linux Linux version of Vim.
12471 lispindent Compiled with support for lisp indenting.
12472 listcmds Compiled with commands for the buffer list |:files|
12473 and the argument list |arglist|.
12474 localmap Compiled with local mappings and abbr. |:map-local|
12475 lua Compiled with Lua interface |Lua|.
12476 mac Any Macintosh version of Vim cf. osx
12477 macunix Synonym for osxdarwin
12478 menu Compiled with support for |:menu|.
12479 mksession Compiled with support for |:mksession|.
12480 modify_fname Compiled with file name modifiers. |filename-modifiers|
12481 (always true)
12482 mouse Compiled with support for mouse.
12483 mouse_dec Compiled with support for Dec terminal mouse.
12484 mouse_gpm Compiled with support for gpm (Linux console mouse)
12485 mouse_gpm_enabled GPM mouse is working
12486 mouse_netterm Compiled with support for netterm mouse.
12487 mouse_pterm Compiled with support for qnx pterm mouse.
12488 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
12489 mouse_sgr Compiled with support for sgr mouse.
12490 mouse_urxvt Compiled with support for urxvt mouse.
12491 mouse_xterm Compiled with support for xterm mouse.
12492 mouseshape Compiled with support for 'mouseshape'.
12493 multi_byte Compiled with support for 'encoding' (always true)
12494 multi_byte_encoding 'encoding' is set to a multibyte encoding.
12495 multi_byte_ime Compiled with support for IME input method.
12496 multi_lang Compiled with support for multiple languages.
12497 mzscheme Compiled with MzScheme interface |mzscheme|.
12498 nanotime Compiled with sub-second time stamp checks.
12499 netbeans_enabled Compiled with support for |netbeans| and connected.
12500 netbeans_intg Compiled with support for |netbeans|.
12501 num64 Compiled with 64-bit |Number| support.
12502 ole Compiled with OLE automation support for Win32.
12503 osx Compiled for macOS cf. mac
12504 osxdarwin Compiled for macOS, with |mac-darwin-feature|
12505 packages Compiled with |packages| support.
12506 path_extra Compiled with up/downwards search in 'path' and 'tags'
12507 perl Compiled with Perl interface.
12508 persistent_undo Compiled with support for persistent undo history.
12509 postscript Compiled with PostScript file printing.
12510 printer Compiled with |:hardcopy| support.
12511 profile Compiled with |:profile| support.
12512 python Python 2.x interface available. |has-python|
12513 python_compiled Compiled with Python 2.x interface. |has-python|
12514 python_dynamic Python 2.x interface is dynamically loaded. |has-python|
12515 python3 Python 3.x interface available. |has-python|
12516 python3_compiled Compiled with Python 3.x interface. |has-python|
12517 python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
12518 pythonx Python 2.x and/or 3.x interface available. |python_x|
12519 qnx QNX version of Vim.
12520 quickfix Compiled with |quickfix| support.
12521 reltime Compiled with |reltime()| support.
12522 rightleft Compiled with 'rightleft' support.
12523 ruby Compiled with Ruby interface |ruby|.
12524 scrollbind Compiled with 'scrollbind' support. (always true)
12525 showcmd Compiled with 'showcmd' support.
12526 signs Compiled with |:sign| support.
12527 smartindent Compiled with 'smartindent' support.
12528 sodium Compiled with libsodium for better crypt support
12529 sound Compiled with sound support, e.g. `sound_playevent()`
12530 spell Compiled with spell checking support |spell|.
12531 startuptime Compiled with |--startuptime| support.
12532 statusline Compiled with support for 'statusline', 'rulerformat'
12533 and special formats of 'titlestring' and 'iconstring'.
12534 sun SunOS version of Vim.
12535 sun_workshop Support for Sun |workshop| has been removed.
12536 syntax Compiled with syntax highlighting support |syntax|.
12537 syntax_items There are active syntax highlighting items for the
12538 current buffer.
12539 system Compiled to use system() instead of fork()/exec().
12540 tag_binary Compiled with binary searching in tags files
12541 |tag-binary-search|.
12542 tag_old_static Support for old static tags was removed, see
12543 |tag-old-static|.
12544 tcl Compiled with Tcl interface.
12545 termguicolors Compiled with true color in terminal support.
12546 terminal Compiled with |terminal| support.
12547 terminfo Compiled with terminfo instead of termcap.
12548 termresponse Compiled with support for |t_RV| and |v:termresponse|.
12549 textobjects Compiled with support for |text-objects|.
12550 textprop Compiled with support for |text-properties|.
12551 tgetent Compiled with tgetent support, able to use a termcap
12552 or terminfo file.
12553 timers Compiled with |timer_start()| support.
12554 title Compiled with window title support |'title'|.
12555 toolbar Compiled with support for |gui-toolbar|.
12556 ttyin input is a terminal (tty)
12557 ttyout output is a terminal (tty)
12558 unix Unix version of Vim. *+unix*
12559 unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
12560 user_commands User-defined commands. (always true)
12561 vartabs Compiled with variable tabstop support |'vartabstop'|.
12562 vcon Win32: Virtual console support is working, can use
12563 'termguicolors'. Also see |+vtp|.
12564 vertsplit Compiled with vertically split windows |:vsplit|.
12565 (always true)
12566 vim_starting True while initial source'ing takes place. |startup|
12567 *vim_starting*
12568 viminfo Compiled with viminfo support.
12569 vimscript-1 Compiled Vim script version 1 support
12570 vimscript-2 Compiled Vim script version 2 support
12571 vimscript-3 Compiled Vim script version 3 support
12572 virtualedit Compiled with 'virtualedit' option. (always true)
12573 visual Compiled with Visual mode. (always true)
12574 visualextra Compiled with extra Visual mode commands. (always
12575 true) |blockwise-operators|.
12576 vms VMS version of Vim.
12577 vreplace Compiled with |gR| and |gr| commands. (always true)
12578 vtp Compiled for vcon support |+vtp| (check vcon to find
12579 out if it works in the current console).
12580 wildignore Compiled with 'wildignore' option.
12581 wildmenu Compiled with 'wildmenu' option.
12582 win16 old version for MS-Windows 3.1 (always false)
12583 win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
12584 64 bits)
12585 win32unix Win32 version of Vim, using Unix files (Cygwin)
12586 win64 Win64 version of Vim (MS-Windows 64 bit).
12587 win95 Win32 version for MS-Windows 95/98/ME (always false)
12588 winaltkeys Compiled with 'winaltkeys' option.
12589 windows Compiled with support for more than one window.
12590 (always true)
12591 writebackup Compiled with 'writebackup' default on.
12592 xfontset Compiled with X fontset support |xfontset|.
12593 xim Compiled with X input method support |xim|.
12594 xpm Compiled with pixmap support.
12595 xpm_w32 Compiled with pixmap support for Win32. (Only for
12596 backward compatibility. Use "xpm" instead.)
12597 xsmp Compiled with X session management support.
12598 xsmp_interact Compiled with interactive X session management support.
12599 xterm_clipboard Compiled with support for xterm clipboard.
12600 xterm_save Compiled with support for saving and restoring the
12601 xterm screen.
12602 x11 Compiled with X11 support.
12603
12604 *string-match*
12605 Matching a pattern in a String
12606
12607 A regexp pattern as explained at |pattern| is normally used to find a match in
12608 the buffer lines. When a pattern is used to find a match in a String, almost
12609 everything works in the same way. The difference is that a String is handled
12610 like it is one line. When it contains a "\n" character, this is not seen as a
12611 line break for the pattern. It can be matched with a "\n" in the pattern, or
12612 with ".". Example: >
12613 :let a = "aaaa\nxxxx"
12614 :echo matchstr(a, "..\n..")
12615 aa
12616 xx
12617 :echo matchstr(a, "a.x")
12618 a
12619 x
12620
12621 Don't forget that "^" will only match at the first character of the String and
12622 "$" at the last character of the string. They don't match after or before a
12623 "\n".
12624 2539
12625 ============================================================================== 2540 ==============================================================================
12626 5. Defining functions *user-functions* 2541 5. Defining functions *user-functions*
12627 2542
12628 New functions can be defined. These can be called just like builtin 2543 New functions can be defined. These can be called just like builtin