codekingpro/portable-devtools

1*usr_27.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7			 Search commands and patterns8 9 10In chapter 3 a few simple search patterns were mentioned |03.9|.  Vim can do11much more complex searches.  This chapter explains the most often used ones.12A detailed specification can be found here: |pattern|13Options affecting how search is done can be found here: |search-options|14 15|27.1|	Ignoring case16|27.2|	Wrapping around the file end17|27.3|	Offsets18|27.4|	Matching multiple times19|27.5|	Alternatives20|27.6|	Character ranges21|27.7|	Character classes22|27.8|	Matching a line break23|27.9|	Examples24 25     Next chapter: |usr_28.txt|  Folding26 Previous chapter: |usr_26.txt|  Repeating27Table of contents: |usr_toc.txt|28 29==============================================================================30*27.1*	Ignoring case31 32By default, Vim's searches are case sensitive.  Therefore, "include",33"INCLUDE", and "Include" are three different words and a search will match34only one of them.35   Now switch on the 'ignorecase' option: >36 37	:set ignorecase38 39Search for "include" again, and now it will match "Include", "INCLUDE" and40"InClUDe".  (Set the 'hlsearch' option to quickly see where a pattern41matches.)42   You can switch this off again with: >43 44	:set noignorecase45 46But let's keep it set, and search for "INCLUDE".  It will match exactly the47same text as "include" did.  Now set the 'smartcase' option: >48 49	:set ignorecase smartcase50 51If you have a pattern with at least one uppercase character, the search52becomes case sensitive.  The idea is that you didn't have to type that53uppercase character, so you must have done it because you wanted case to54match.  That's smart!55    With these two options set you find the following matches:56 57	pattern			matches	~58	word			word, Word, WORD, WoRd, etc.59	Word			Word60	WORD			WORD61	WoRd			WoRd62 63 64CASE IN ONE PATTERN65 66If you want to ignore case for one specific pattern, you can do this by67prepending the "\c" string.  Using "\C" will make the pattern to match case.68This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is69used their value doesn't matter.70 71	pattern			matches	~72	\Cword			word73	\CWord			Word74	\cword			word, Word, WORD, WoRd, etc.75	\cWord			word, Word, WORD, WoRd, etc.76 77A big advantage of using "\c" and "\C" is that it sticks with the pattern.78Thus if you repeat a pattern from the search history, the same will happen, no79matter if 'ignorecase' or 'smartcase' was changed.80 81	Note:82	The use of "\" items in search patterns depends on the 'magic' option.83	In this chapter we will assume 'magic' is on, because that is the84	standard and recommended setting.  If you would change 'magic', many85	search patterns would suddenly become invalid.86 87	Note:88	If your search takes much longer than you expected, you can interrupt89	it with CTRL-C on Unix and CTRL-Break on MS-Windows.90 91==============================================================================92*27.2*	Wrapping around the file end93 94By default, a forward search starts searching for the given string at the95current cursor location.  It then proceeds to the end of the file.  If it has96not found the string by that time, it starts from the beginning and searches97from the start of the file to the cursor location.98   Keep in mind that when repeating the "n" command to search for the next99match, you eventually get back to the first match.  If you don't notice this100you keep searching forever!  To give you a hint, Vim displays this message:101 102	search hit BOTTOM, continuing at TOP ~103 104If you use the "?" command, to search in the other direction, you get this105message:106 107	search hit TOP, continuing at BOTTOM ~108 109Still, you don't know when you are back at the first match.  One way to see110this is by switching on the 'ruler' option: >111 112	:set ruler113 114Vim will display the cursor position in the lower righthand corner of the115window (in the status line if there is one).  It looks like this:116 117	101,29       84% ~118 119The first number is the line number of the cursor.  Remember the line number120where you started, so that you can check if you passed this position again.121 122 123NOT WRAPPING124 125To turn off search wrapping, use the following command: >126 127	:set nowrapscan128 129Now when the search hits the end of the file, an error message displays:130 131	E385: search hit BOTTOM without match for: forever ~132 133Thus you can find all matches by going to the start of the file with "gg" and134keep searching until you see this message.135   If you search in the other direction, using "?", you get:136 137	E384: search hit TOP without match for: forever ~138 139==============================================================================140*27.3*	Offsets141 142By default, the search command leaves the cursor positioned on the beginning143of the pattern.  You can tell Vim to leave it some other place by specifying144an offset.  For the forward search command "/", the offset is specified by145appending a slash (/) and the offset: >146 147	/default/2148 149This command searches for the pattern "default" and then moves to the150beginning of the second line past the pattern.  Using this command on the151paragraph above, Vim finds the word "default" in the first line.  Then the152cursor is moved two lines down and lands on "an offset".153 154If the offset is a simple number, the cursor will be placed at the beginning155of the line that many lines from the match.  The offset number can be positive156or negative.  If it is positive, the cursor moves down that many lines; if157negative, it moves up.158 159 160CHARACTER OFFSETS161 162The "e" offset indicates an offset from the end of the match.  It moves the163cursor onto the last character of the match.  The command: >164 165	/const/e166 167puts the cursor on the "t" of "const".168   From that position, adding a number moves forward that many characters.169This command moves to the character just after the match: >170 171	/const/e+1172 173A positive number moves the cursor to the right, a negative number moves it to174the left.  For example: >175 176	/const/e-1177 178moves the cursor to the "s" of "const".179 180If the offset begins with "b", the cursor moves to the beginning of the181pattern.  That's not very useful, since leaving out the "b" does the same182thing.  It does get useful when a number is added or subtracted.  The cursor183then goes forward or backward that many characters.  For example: >184 185	/const/b+2186 187Moves the cursor to the beginning of the match and then two characters to the188right.  Thus it lands on the "n".189 190 191REPEATING192 193To repeat searching for the previously used search pattern, but with a194different offset, leave out the pattern: >195 196	/that197	//e198 199Is equal to: >200 201	/that/e202 203To repeat with the same offset: >204 205	/206 207"n" does the same thing.  To repeat while removing a previously used offset: >208 209	//210 211 212SEARCHING BACKWARDS213 214The "?" command uses offsets in the same way, but you must use "?" to separate215the offset from the pattern, instead of "/": >216 217	?const?e-2218 219The "b" and "e" keep their meaning, they don't change direction with the use220of "?".221 222 223START POSITION224 225When starting a search, it normally starts at the cursor position.  When you226specify a line offset, this can cause trouble.  For example: >227 228	/const/-2229 230This finds the next word "const" and then moves two lines up.  If you231use "n" to search again, Vim could start at the current position and find the232same "const" match.  Then using the offset again, you would be back where you233started.  You would be stuck!234   It could be worse: Suppose there is another match with "const" in the next235line.  Then repeating the forward search would find this match and move two236lines up.  Thus you would actually move the cursor back!237 238When you specify a character offset, Vim will compensate for this.  Thus the239search starts a few characters forward or backward, so that the same match240isn't found again.241 242==============================================================================243*27.4*	Matching multiple times244 245The "*" item specifies that the item before it can match any number of times.246Thus: >247 248	/a*249 250matches "a", "aa", "aaa", etc.  But also "" (the empty string), because zero251times is included.252   The "*" only applies to the item directly before it.  Thus "ab*" matches253"a", "ab", "abb", "abbb", etc.  To match a whole string multiple times, it254must be grouped into one item.  This is done by putting "\(" before it and255"\)" after it.  Thus this command: >256 257	/\(ab\)*258 259Matches: "ab", "abab", "ababab", etc.  And also "".260 261To avoid matching the empty string, use "\+".  This makes the previous item262match one or more times. >263 264	/ab\+265 266Matches "ab", "abb", "abbb", etc.  It does not match "a" when no "b" follows.267 268To match an optional item, use "\=".  Example: >269 270	/folders\=271 272Matches "folder" and "folders".273 274 275SPECIFIC COUNTS276 277To match a specific number of items use the form "\{n,m}".  "n" and "m" are278numbers.  The item before it will be matched "n" to "m" times |inclusive|.279Example: >280 281	/ab\{3,5}282 283matches "abbb", "abbbb" and "abbbbb".284  When "n" is omitted, it defaults to zero.  When "m" is omitted it defaults285to infinity.  When ",m" is omitted, it matches exactly "n" times.286Examples:287 288	pattern		match count ~289	\{,4}		0, 1, 2, 3 or 4290	\{3,}		3, 4, 5, etc.291	\{0,1}		0 or 1, same as \=292	\{0,}		0 or more, same as *293	\{1,}		1 or more, same as \+294	\{3}		3295 296 297MATCHING AS LITTLE AS POSSIBLE298 299The items so far match as many characters as they can find.  To match as few300as possible, use "\{-n,m}".  It works the same as "\{n,m}", except that the301minimal amount possible is used.302   For example, use: >303 304	/ab\{-1,3}305 306Will match "ab" in "abbb".  Actually, it will never match more than one b,307because there is no reason to match more.  It requires something else to force308it to match more than the lower limit.309   The same rules apply to removing "n" and "m".  It's even possible to remove310both of the numbers, resulting in "\{-}".  This matches the item before it311zero or more times, as few as possible.  The item by itself always matches312zero times.  It is useful when combined with something else.  Example: >313 314	/a.\{-}b315 316This matches "axb" in "axbxb".  If this pattern would be used: >317 318	/a.*b319 320It would try to match as many characters as possible with ".*", thus it321matches "axbxb" as a whole.322 323==============================================================================324*27.5*	Alternatives325 326The "or" operator in a pattern is "\|".  Example: >327 328	/foo\|bar329 330This matches "foo" or "bar".  More alternatives can be concatenated: >331 332	/one\|two\|three333 334Matches "one", "two" and "three".335   To match multiple times, the whole thing must be placed in "\(" and "\)": >336 337	/\(foo\|bar\)\+338 339This matches "foo", "foobar", "foofoo", "barfoobar", etc.340   Another example: >341 342	/end\(if\|while\|for\)343 344This matches "endif", "endwhile" and "endfor".345 346A related item is "\&".  This requires that both alternatives match in the347same place.  The resulting match uses the last alternative.  Example: >348 349	/forever\&...350 351This matches "for" in "forever".  It will not match "fortuin", for example.352 353==============================================================================354*27.6*	Character ranges355 356To match "a", "b" or "c" you could use "/a\|b\|c".  When you want to match all357letters from "a" to "z" this gets very long.  There is a shorter method: >358 359	/[a-z]360 361The [] construct matches a single character.  Inside you specify which362characters to match.  You can include a list of characters, like this: >363 364	/[0123456789abcdef]365 366This will match any of the characters included.  For consecutive characters367you can specify the range.  "0-3" stands for "0123".  "w-z" stands for "wxyz".368Thus the same command as above can be shortened to: >369 370	/[0-9a-f]371 372To match the "-" character itself make it the first or last one in the range.373These special characters are accepted to make it easier to use them inside a374[] range (they can actually be used anywhere in the search pattern):375 376	\e	<Esc>377	\t	<Tab>378	\r	<CR>379	\b	<BS>380 381There are a few more special cases for [] ranges, see |/[]| for the whole382story.383 384 385COMPLEMENTED RANGE386 387To avoid matching a specific character, use "^" at the start of the range.388The [] item then matches everything but the characters included.  Example: >389 390	/"[^"]*"391<392	 "	  a double quote393	  [^"]	  any character that is not a double quote394	      *	  as many as possible395	       "  a double quote again396 397This matches "foo" and "3!x", including the double quotes.398 399 400PREDEFINED RANGES401 402A number of ranges are used very often.  Vim provides a shortcut for these.403For example: >404 405	/\a406 407Finds alphabetic characters.  This is equal to using "/[a-zA-Z]".  Here are a408few more of these:409 410	item	matches			equivalent ~411	\d	digit			[0-9]412	\D	non-digit		[^0-9]413	\x	hex digit		[0-9a-fA-F]414	\X	non-hex digit		[^0-9a-fA-F]415	\s	white space		[ 	]     (<Tab> and <Space>)416	\S	non-white characters	[^ 	]     (not <Tab> and <Space>)417	\l	lowercase alpha		[a-z]418	\L	non-lowercase alpha	[^a-z]419	\u	uppercase alpha		[A-Z]420	\U	non-uppercase alpha	[^A-Z]421 422	Note:423	Using these predefined ranges works a lot faster than the character424	range it stands for.425	These items can not be used inside [].  Thus "[\d\l]" does NOT work to426	match a digit or lowercase alpha.  Use "\(\d\|\l\)" instead.427 428See |/\s| for the whole list of these ranges.429 430==============================================================================431*27.7*	Character classes432 433The character range matches a fixed set of characters.  A character class is434similar, but with an essential difference: The set of characters can be435redefined without changing the search pattern.436   For example, search for this pattern: >437 438	/\f\+439 440The "\f" item stands for file name characters.  Thus this matches a sequence441of characters that can be a file name.442   Which characters can be part of a file name depends on the system you are443using.  On MS-Windows, the backslash is included, on Unix it is not.  This is444specified with the 'isfname' option.  The default value for Unix is: >445 446	:set isfname447	isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,=448 449For other systems the default value is different.  Thus you can make a search450pattern with "\f" to match a file name, and it will automatically adjust to451the system you are using it on.452 453	Note:454	Actually, Unix allows using just about any character in a file name,455	including white space.  Including these characters in 'isfname' would456	be theoretically correct.  But it would make it impossible to find the457	end of a file name in text.  Thus the default value of 'isfname' is a458	compromise.459 460The character classes are:461 462	item	matches				option ~463	\i	identifier characters		'isident'464	\I	like \i, excluding digits465	\k	keyword characters		'iskeyword'466	\K	like \k, excluding digits467	\p	printable characters		'isprint'468	\P	like \p, excluding digits469	\f	file name characters		'isfname'470	\F	like \f, excluding digits471 472==============================================================================473*27.8*	Matching a line break474 475Vim can find a pattern that includes a line break.  You need to specify where476the line break happens, because all items mentioned so far don't match a line477break.478   To check for a line break in a specific place, use the "\n" item: >479 480	/one\ntwo481 482This will match at a line that ends in "one" and the next line starts with483"two".  To match "one two" as well, you need to match a space or a line484break.  The item to use for it is "\_s": >485 486	/one\_stwo487 488To allow any amount of white space: >489 490	/one\_s\+two491 492This also matches when "one  " is at the end of a line and "   two" at the493start of the next one.494 495"\s" matches white space, "\_s" matches white space or a line break.496Similarly, "\a" matches an alphabetic character, and "\_a" matches an497alphabetic character or a line break.  The other character classes and ranges498can be modified in the same way by inserting a "_".499 500Many other items can be made to match a line break by prepending "\_".  For501example: "\_." matches any character or a line break.502 503	Note:504	"\_.*" matches everything until the end of the file.  Be careful with505	this, it can make a search command very slow.506 507Another example is "\_[]", a character range that includes a line break: >508 509	/"\_[^"]*"510 511This finds a text in double quotes that may be split up in several lines.512 513==============================================================================514*27.9*	Examples515 516Here are a few search patterns you might find useful.  This shows how the517items mentioned above can be combined.518 519 520FINDING A CALIFORNIA LICENSE PLATE521 522A sample license plate number is "1MGU103".  It has one digit, three uppercase523letters and three digits.  Directly putting this into a search pattern: >524 525	/\d\u\u\u\d\d\d526 527Another way is to specify that there are three digits and letters with a528count: >529 530	/\d\u\{3}\d\{3}531 532Using [] ranges instead: >533 534	/[0-9][A-Z]\{3}[0-9]\{3}535 536Which one of these you should use?  Whichever one you can remember.  The537simple way you can remember is much faster than the fancy way that you can't.538If you can remember them all, then avoid the last one, because it's both more539typing and slower to execute.540 541 542FINDING AN IDENTIFIER543 544In C programs (and many other computer languages) an identifier starts with a545letter and further consists of letters and digits.  Underscores can be used546too.  This can be found with: >547 548	/\<\h\w*\>549 550"\<" and "\>" are used to find only whole words.  "\h" stands for "[A-Za-z_]"551and "\w" for "[0-9A-Za-z_]".552 553	Note:554	"\<" and "\>" depend on the 'iskeyword' option.  If it includes "-",555	for example, then "ident-" is not matched.  In this situation use: >556 557		/\w\@<!\h\w*\w\@!558<559	This checks if "\w" does not match before or after the identifier.560	See |/\@<!| and |/\@!|.561 562==============================================================================563 564Next chapter: |usr_28.txt|  Folding565 566Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:567