Searching and Substituting

Searching for and replacing a character, a string of text, or a string that is matched by a regular expression is a key feature of any editor. The vim editor provides simple commands for searching for a character on the current line. It also provides more complex commands for searching for and optionally substituting for single and multiple occurrences of strings or regular expressions anywhere in the Work buffer.

Searching for a Character

Find (f/F)

You can search for and move the cursor to the next occurrence of a specified character on the current line using the f (Find) command. Refer to "Moving the Cursor to a Specific Character" on page 161.

t/T

The next two commands are used in the same manner as the Find command. The t command places the cursor on the character before the next occurrence of the specified character. The T command places the cursor on the character after the previous occurrence of the specified character.

A semicolon (;) repeats the last f, F, t, or T command.

You can combine these search commands with other commands. For example, the command d2fq deletes the text from the location of the cursor to the second occurrence of the letter q on the current line.

Searching for a String

The vim editor can search backward or forward through the Work buffer to find a string of text or a string that matches a regular expression (see Appendix A). To find the next occurrence of a string (forward), press the forward slash (/) key, enter the text you want to find (called the search string), and press RETURN. When you press the slash key, vim displays a slash on the status line. As you enter the string of text, it is also displayed on the status line. When you press RETURN, vim searches for the string. If this search is successful, vim positions the cursor on the first character of the string. If you use a question mark (?) in place of the forward slash, vim searches for the previous occurrence of the string. If you need to include a forward slash in a forward search or a question mark in a backward search, you must quote it by preceding it with a backslash (\).

Tip: Two distinct ways of quoting characters

You use CONTROL-V to quote special characters in text that you are entering into a file (page 164). This section discusses the use of a backslash (\) to quote special characters in a search string. The two techniques of quoting characters are not interchangeable.

The N and n keys repeat the last search without any need for you to reenter the search string. The n key repeats the original search exactly, and the N key repeats the search in the opposite direction of the original search.

If you are searching forward and vim does not find the search string before it gets to the end of the Work buffer, the editor typically wraps around and continues the search at the beginning of the Work buffer. During a backward search, vim wraps around from the beginning of the Work buffer to the end. Also, vim normally performs case-sensitive searches. Refer to "Wrap scan" (page 184) and "Ignore case in searches" (page 182) for information about how to change these search parameters.

Normal Versus Incremental Searches

When vim performs a normal search (its default behavior), you enter a slash or question mark followed by the search string and press RETURN. The vim editor moves the cursor to the next or previous occurrence of the string you are searching for.

When vim performs an incremental search, you enter a slash or question mark. As you enter each character of the search string, vim moves the highlight to the next or previous occurrence of the string you have entered so far. When the highlight is on the string you are searching for, you must press RETURN to move the cursor to the highlighted string. If the string you enter does not match any text, vim does not highlight anything.

The type of search that vim performs depends on the incsearch parameter (page 182). Give the command :set incsearch to turn on incremental searching. Use noincsearch to turn it off. When you set the compatible parameter (page 153), vim turns off incremental searching.

Special Characters in Search Strings

Because the search string is a regular expression, some characters take on a special meaning within the search string. The following paragraphs list some of these characters. See also "Extended Regular Expressions" on page 903.

The first two items in the following list (^ and $) always have their special meanings within a search string unless you quote them by preceding them with a backslash (\). You can turn off the special meanings within a search string for the rest of the items in the list by setting the nomagic parameter. See "Allow special characters in searches" (page 181) for more information.

^ Beginning-of-Line Indicator

When the first character in a search string is a caret (also called a circumflex) it matches the beginning of a line. For example, the command /^the finds the next line that begins with the string the.

$ End-of-Line Indicator

A dollar sign matches the end of a line. For example, the command /!$ finds the next line that ends with an exclamation point and / $ matches the next line that ends with a SPACE.

. Any-Character Indicator

A period matches any character, anywhere in the search string. For example, the command /l..e finds line, followed, like, included, all memory, or any other word or character string that contains an l followed by any two characters and an e. To search for a period, use a backslash to quote the period (\.).

\> End-of-Word Indicator

This pair of characters matches the end of a word. For example, the command /s\> finds the next word that ends with an s. Whereas a backslash (\) is typically used to turn off the special meaning of a character, the character sequence \> has a special meaning, while > alone does not.

\< Beginning-of-Word Indicator

This pair of characters matches the beginning of a word. For example, the command /\<The finds the next word that begins with the string The. The beginning-of-word indicator uses the backslash in the same, atypical way as the end-of-word indicator.

* Zero or More Occurrences

This character is a modifier that will match zero or more occurrences of the character immediately preceding it. For example, the command /dis*m will match the string di followed by zero or more s characters followed by an m. Examples of successful matches are dim or dism or dissm.

[ ] Character-Class Definition

Brackets surrounding two or more characters match any single character located between the brackets. For example, the command /dis[ck] finds the next occurrence of either disk or disc.

There are two special characters you can use within a character-class definition. A caret (^) as the first character following the left bracket defines the character class to be any except the following characters. A hyphen between two characters indicates a range of characters. Refer to the examples in Table 6-4.

Table 6-4. Search examples

Search string	What it finds
/and	Finds the next occurrence of the string and Examples: sand and standard slander andiron
/\<and\>	Finds the next occurrence of the word and Example: and
/^The	Finds the next line that starts with The Examples: The ... There ...
/^[0-9][0-9])	Finds the next line that starts with a two-digit number followed by a right parenthesis Examples: 77)... 01)... 15)...
/\<[adr]	Finds the next word that starts with an a, d, or r Examples: apple drive road argument right
/^[A-Za-z]	Finds the next line that starts with an uppercase or lowercase letter Examples: will not find a line starting with the number 7 ... Dear Mr. Jones ... in the middle of a sentence like this ...

Substituting One String for Another

A Substitute command combines the effects of a Search command and a Change command. That is, it searches for a string (regular expression) just as the / command does, allowing the same special characters discussed in the previous section. When it finds the string or matches the regular expression, the Substitute command changes the string or regular expression it matches. The syntax of the Substitute command is

:[g][address]s/search-string/replacement-string[/option]

As with all commands that begin with a colon, vim executes a Substitute command from the status line.

The Substitute Address

If you do not specify an address, Substitute searches only the current line. If you use a single line number as the address, Substitute searches that line. If the address is two line numbers separated by a comma, Substitute searches those lines and the lines between them. Refer to "Line numbers" on page 182 if you want vim to display line numbers. Wherever a line number is allowed in the address, you may also use an address-string enclosed between slashes. The vim editor operates on the next line that the address-string matches. When you precede the first slash of the address-string with the letter g (for global), vim operates on all lines in the file that the address-string matches. (This g is not the same as the one that goes at the end of the Substitute command to cause multiple replacements on a single line; see "Searching for and Replacing Strings" below).

Within the address, a period represents the current line, a dollar sign represents the last line in the Work buffer, and a percent sign represents the entire Work buffer. You can perform address arithmetic using plus and minus signs. Table 6-5 shows some examples of addresses.

Table 6-5. Addresses

Address	Portion of Work buffer addressed
5	Line 5
77,100	Lines 77 through 100 inclusive
1,.	Beginning of Work buffer through current line
.,$	Current line through end of Work buffer
1,$	Entire Work buffer
%	Entire Work buffer
/pine/	The next line containing the word pine
g/pine/	All lines containing the word pine
.,.+10	Current line through tenth following line (11 lines in all)

Searching for and Replacing Strings

An s comes after the address in the command syntax, indicating that this is a Substitute command. A delimiter follows the s, marking the beginning of the search-string. Although the examples in this book use a forward slash, you can use as a delimiter any character that is not a letter, number, blank, or backslash. You must use the same delimiter at the end of the search-string.

Next comes the search-string. It has the same format as the search string in the / command and can include the same special characters (page 170). (The search-string is a regular expression; refer to Appendix A for more information.) Another delimiter marks the end of the search-string and the beginning of the replace-string.

The replace-string replaces the text matched by the search-string. It should be followed by the delimiter character. You can omit the final delimiter when no option follows the replace-string; a final delimiter is required if an option is present.

Several characters have special meanings in the search-string, and other characters have special meanings in the replace-string. For example, an ampersand (&) in the replace-string represents the text that was matched by the search-string. A backslash in the replace-string quotes the character that follows it. Refer to Table 6-6 and Appendix A.

Table 6-6. Search and replace examples

Command	Result
:s/bigger/biggest/	Replaces the first occurrence of the string bigger on the current line with biggest Example: bigger biggest
:1,.s/Ch 1/Ch 2/g	Replaces every occurrence of the string Ch 1, before or on the current line, with the string Ch 2 Examples: Ch 1 Ch 2 Ch 12 Ch 22
:1,$s/ten/10/g	Replaces every occurrence of the string ten with the string 10 Examples: ten 10 often of10 tenant 10ant
:g/chapter/s/ten/10/	Replaces the first occurrence of the string ten with the string 10 on all lines containing the word chapter Examples: chapter ten chapter 10 chapters will often chapters will of10
:%s/\<ten\>/10/g	Replaces every occurrence of the word ten with the string 10 Example: ten 10
:.,.+10s/every/each/g	Replaces every occurrence of the string every with the string each on the current line through the tenth following line Examples: every each everything eachthing
:s/\<short\>/"&"/	Replaces the word short on the current line with "short" (enclosed within quotation marks) Example: the shortest of the short the shortest of the "short"

Normally, the Substitute command replaces only the first occurrence of any text that matches the search-string on a line. If you want a global substitutionthat is, if you want to replace all matching occurrences of text on a lineappend the g (global) option after the delimiter that ends the replace-string. Another useful option, c (check), causes vim to ask whether you would like to make the change each time it finds text that matches the search-string. Pressing y replaces the search-string, q terminates the command, l (last) makes the replacement and quits, a (all) makes all remaining replacements, and n continues the search without making that replacement.

The address-string need not be the same as the search-string. For example,

:/candle/s/wick/flame/

substitutes flame for the first occurrence of wick on the next line that contains the string candle. Similarly,

:g/candle/s/wick/flame/

performs the same substitution for the first occurrence of wick on each line of the file containing the string candle and

:g/candle/s/wick/flame/g

performs the same substitution for all occurrences of wick on each line that contains the string candle.

If the search-string is the same as the address, you can leave the search-string blank. For example, the command :/candle/s//lamp/ is equivalent to the command :/candle/s/candle/lamp/.