Searching Text

To search for text in a file that you have open in the editor, choose Edit > Find > Find.

The search bar appears below the editor toolbar, as shown in Figure 4-1.

The Find/Replace pop-up menu lets you choose between Find and Find & Replace. For more on Find & Replace, see Replacing Text.

You can search using a text string or a regular expression; choose the appropriate search type from the search-options menu in the search field:

• String Matching. Searches for text matching the string in the search field.

• Regular Expression. Searches for text matching the regular expression in the search field.

  Xcode uses the ICU library for regular expression matching (see http://icu-project.org/userguide).

Type the text string or regular expression pattern to use for the search in the search field. To minimize your typing, Xcode keeps track of search strings; to reuse a previous search string, choose it from the Recent Searches group in the search-options menu. You can clear the recent-searches list by choosing Clear Recent Searches from the search-options menu.

The other options in the search-options menu give you additional control over how the search is performed; these options are:

• Ignore Case. Select this option to ignore whether letters are uppercase or lowercase.

• Wrap around. Select this option to search the whole file; otherwise, Xcode searches from the current location of the insertion point to the end of the file.

• Contains. Searches for words that contain matching text in a substring.

• Starts with. Searches for words that begin with text matching the search term.

• Whole words. Searches for words that contain only text matching the contents of the Find field.

• Ends with. Searches for words that end with matching text.

Use the Next and Previous buttons (to the left of the search field) to continue searching for the same text in a file. You can also use menu commands. Choose Edit > Find > Find Next to move to the next match and Edit > Find > Find Previous to move to the previous match.

Replacing Text

You can replace some or all occurrences of text matching the string or regular expression specified in the search field.

To search for text in a file and replace it with other text, do one of the following:

• Choose Edit > Find > Find and Replace.

• In the search bar, choose Find & Replace from the Find/Replace menu.

The search & replace bar appears, as shown in Figure 4-2.

Use the replace buttons to perform the text substitution. The scope of the replacement varies, depending on the button you choose. Here are the buttons available to you:

• Replace All. Searches the entire file or selection and replaces all occurrences of text matching the contents of the Find field with the replacement text.

  Holding down Option changes the search & replace scope to the selected text.

• Replace. Substitutes the replacement text for the current match.

• Replace & Find. Substitutes the replacement text for the current match and then finds and selects the next match.

Each of these buttons also has a menu item equivalent in the Edit > Find menu: Replace, Replace All, Replace and Find Next, and Replace and Find Previous.

The Project Find Window

The Project Find window allows you to search for information in some or all of the files included in your project. Using the Project Find window, you can search your project for text, symbol definitions, or regular expressions. To open the Project Find window, choose Edit > Find > Find In Project. A window similar to the one in Figure 4-3appears.

Choosing What to Search For

Using the fields and menus at the top of the Project Find window, you can control what Xcode searches for.

• The Find field specifies what to find. Xcode interprets this field differently, depending on the value of the pop-up menu to the right of the Replace field.

• The pop-up menu to the right of the Replace field specifies the type of search; it contains the following options:

  • Textual. Finds any text that matches the text in the Find field.

  • Regular Expression. Finds any text that matches the regular expression in the Find field. Xcode uses the ICU library for regular expression matching; for more information, see the http://icu.sourceforge.net/userguide.

  • Definitions. Finds any symbol definition matching the symbol name in the Find field.

  • Symbol. Finds code that uses the symbol identified in the Find field.

• The pop-up menu to the right of the Display Results in Find Smart Group option controls how Xcode determines a match to the contents of the Find field. The available options are:

  • Contains. Choose this option to find text or symbol definitions that contain what is in the Find field.

  • Starts with. Choose this option to find text or symbol definitions that begin with the contents of the Find field.

  • Whole words. Choose this option to find text or symbol definitions that contain only what is in the Find field.

  • Ends with. Choose this option to find text or symbol definitions that end with the contents of the Find field.

• The “Ignore case” option specifies whether or not the search is case sensitive.

As a shortcut, you can also perform a quick search of selected text or regular expressions in an editor window, as described in Shortcuts for Finding Text and Symbol Definitions.

Specifying Which Files to Search

To control the scope of a search, use the pop-up menu to the right of the Find field in the Project Find window. This menu contains sets of search options that specify which projects and frameworks to search in. Xcode provides the following default sets of search options:

• In Project. Search the files that are directly included in your project.

• In Project and Frameworks. Search the files and the frameworks included in your project.

• In Frameworks. Search files that are in the frameworks included by your project.

• In All Open Files. Search all open files.

• In Selected Project Items. Search only in the currently selected project items.

You can further tailor these default sets of search options or define your own sets with the Batch Find Options window, described in Creating Sets of Search Options.

Creating Sets of Search Options

The Batch Find Options window lets you further tailor the scope of the search. You can further narrow which files and projects are searched, filter the list of files to be searched according to a regular expression, and add directories to the list of locations to search.

You can modify default sets of search options or define your own sets. Defining your own set is particularly useful if you find yourself searching the same set of files over and over again. Instead of configuring the set of files to search each time, simply configure it once and save it as a search option set. To reuse the search option set, simply choose it from the pop-up menu next to the Find button in the Project Find window.

To open the Batch Find Options window, click the Options button in the Project Find window. You should see a window similar to the one in Figure 4-4.

The Find Sets menu at the top of the Batch Find Options windows lists the available search option sets. To create a new set, click Add. Specify a name for the new set in the dialog that appears. Xcode creates a new set of search options with default values. To delete a set of search options, choose that set from the Find Sets menu and click Delete.

To edit a search option set, choose that set from the Find Sets menu and set the search options you wish to include. The Batch Find Options window provides the following options to control which files Xcode searches:

• “Search in open documents” includes all files that are open in an editor in the search.

• “Search in open projects” includes open projects in the search. You can further control which files in those projects are searched using the radio buttons below the “Search in open projects” option.

  The top set of radio buttons controls which projects are searched and bottom set of radio buttons lets you specify whether to include project or framework files in the search.

• “Search in files and folders” allows you to add specific files or directories to the search. Any files or directories listed in the table below this option are included in the search. To add an entry to this table, click the plus (+) button and choose a file or directory from the dialog that appears, or drag the file or directory from the Finder. You can also click in the table and press Return. To delete a file or directory from this table, select the entry and click the minus (-) button.

You can further restrict the files that are searched by a search option set using the radio buttons on the right side of the Batch Find Options window. You have the following options:

• “All candidate files” does not limit the searched files further. This searches all of the files in the search scope specified by the other options in the Batch Find Options window.

• “Source files only” limits the search to files containing source code.

• “Filter files using regex patterns” lets you filter the files to search using one or more regular expressions. These regular expressions are specified in the table beneath this radio button. To add an expression to this list, click the plus (+) button.

  The first column in the table specifies whether to use the corresponding regular expression. The second column specifies whether to return the files that match a given regular expression or the files that do not match the regular expression.

Viewing Search Results

When you perform a projectwide find, the results of the search are listed below the search criteria; results are organized according to the file in which they appear. You can view a particular search result in the file it was found in by selecting it in the Project Find window; Xcode opens the file to the matching text and displays it in the attached editor. Double-click a search result to open it in a separate editor window.

Each search, and its results, is also collected in the Find Results smart group that appears in the Groups & Files list of the project window, as shown in Figure 4-3. If you select the Display Results in Find Smart Group option, Xcode automatically brings the project window to the front and discloses the contents of the Find Results smart group when you perform a search, instead of showing the results in the Project Find window.

You can see all the searches you have performed by clicking the disclosure triangle next to the Find Results smart group in the Groups & Files list. To view the results of a given search, select that search in the Groups & Files list and, if necessary, open a detail view. The detail view shows all of the results for the selected search, as shown in Figure 4-5. You can view the combined results of several searches by selecting those searches in the Groups & Files list. Double-clicking an item in the Find Results group in the Groups & Files list opens a Project Find window with the corresponding search specification as well as a detailed find results list. This allows you to rerun previous searches.

To delete a search result from the Groups & Files list, select the result and press Delete.

The detail view shows the context for each search result and the file in which the match occurs. The context of a search result is the surrounding text in which it appears for text searches, and the type and name of the matching symbol for a symbol definition search. To show or hide either of these two columns, use the View > Detail View Columns menu items or Control-click in any column header and choose the desired column from the contextual menu.

To view the source for a particular result, select the result in the detail view. If the project window or detail view has an attached editor, selecting a search result displays the source in the editor. You can double-click a search result to open the source for the result in a separate window.

You can sort the results of a search according to the file in which they occur. Click the Location column heading to sort the detail view by location. You can also filter the search results using the search field in the project window toolbar. Using the location of the search result as an example again, you can type all or part of a filename to see only those results that occur in the file of that name.

Replacing Text in Multiple Files

You can use the Project Find window to replace some or all occurrences of the search string specified in the Find field. To replace text in multiple files:

1. Type the substitution text in the Replace field

2. Select one or more entries to replace. To choose which occurrences of the given search string to replace, do either of the following:

   • Select one or more entries to replace in the find results pane of the Project Find window.

   • Choose a search from the Find Results smart group in the project window. In the detail view, select one or more occurrences of the search string to replace.

3. Click the Replace button in the Project Find window.

If the contents of the Project Find window’s find results pane are disclosed, Xcode uses the selection in the Project Find window to determine which occurrences to replace. If the find results group is closed, Xcode uses the selection in the detail view of the project window.