1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
//
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.
//
namespace Microsoft.VisualStudio.Text.Operations
{
using System;
using System.Collections.Generic;
/// <summary>
/// Provides methods for searching contents of a <see cref="ITextSnapshot"/>. Additionally, provides
/// helper methods for performing replace operations.
/// </summary>
public interface ITextSearchService2 : ITextSearchService
{
/// <summary>
/// Searches for the next occurrence of the search string.
/// </summary>
/// <param name="startingPosition">
/// The position from which to begin the search. The search will be performed on the <see cref="ITextSnapshot"/> to which
/// this parameter belongs.
/// </param>
/// <param name="searchPattern">
/// The pattern to search for.
/// </param>
/// <param name="options">
/// Specifies options used for the search operation.
/// </param>
/// <returns>
/// A <see cref="SnapshotSpan"/> containing the match if a match was found, or null if no matches were found.
/// </returns>
/// <remarks>
/// This method is safe to be executed from any thread.
/// </remarks>
/// <exception cref="ArgumentException">
/// The <see cref="FindOptions.UseRegularExpressions"/> flag is set and the search string is an invalid regular expression.
/// </exception>
SnapshotSpan? Find(SnapshotPoint startingPosition, string searchPattern, FindOptions options);
/// <summary>
/// Searches for the next occurrence of the search string.
/// </summary>
/// <param name="searchRange">
/// The range of text to search in.
/// </param>
/// <param name="startingPosition">
/// The position from which to begin the search. The search will be performed on the <see cref="ITextSnapshot"/> to which
/// this parameter belongs.
/// </param>
/// <param name="options">
/// Specifies options used for the search operation.
/// </param>
/// <param name="searchPattern">
/// The pattern to search for.
/// </param>
/// <returns>
/// A <see cref="SnapshotSpan"/> containing the match if a match was found, or null if no matches were found.
/// </returns>
/// <remarks>
/// This method can be executed from any thread.
/// </remarks>
/// <exception cref="ArgumentException">
/// The <see cref="FindOptions.UseRegularExpressions"/> flag is set and the search string is an invalid regular expression.
/// </exception>
SnapshotSpan? Find(SnapshotSpan searchRange, SnapshotPoint startingPosition, string searchPattern, FindOptions options);
/// <summary>
/// Searches for the next occurence of <paramref name="searchPattern"/> and sets <paramref name="expandedReplacePattern"/> to the result of
/// the text replacement.
/// </summary>
/// <param name="startingPosition">
/// The position from which search is started. The search will be performed on the <see cref="ITextSnapshot"/> to which this
/// parameter belongs.
/// </param>
/// <param name="searchPatterh">
/// The pattern to look for.
/// </param>
/// <param name="replacePattern">
/// The pattern to replace the found text with.
/// </param>
/// <param name="options">
/// Options used to perform the search.
/// </param>
/// <param name="expandedReplacePattern">
/// The result of the replacement. This output parameter will be useful when performing regular expression searches. Will be empty
/// if no matches are found.
/// </param>
/// <returns>
/// A <see cref="SnapshotSpan"/> pointing to the search result found. If no matches are found, null is returned.
/// </returns>
/// <remarks>
/// <para>
/// This function does not perform any edits. The consumers would need to create an <see cref="ITextEdit"/> to perform the actual text
/// replacement if desired. This method is safe to be executed from any thread.
/// </para>
/// <para>
/// Note that <paramref name="expandedReplacePattern"/> will always equal <paramref name="replacePattern"/> if the search is not using regular
/// expressions. In those scenarios you can utilize the more lightweight <see cref="Find(SnapshotSpan, SnapshotPoint, string, FindOptions)"/>.
/// </para>
/// </remarks>
SnapshotSpan? FindForReplace(SnapshotPoint startingPosition, string searchPattern, string replacePattern, FindOptions options, out string expandedReplacePattern);
/// <summary>
/// Searches for the next occurence of <paramref name="searchPattern"/> and sets <paramref name="expandedReplacePattern"/> to the result of
/// the text replacement.
/// </summary>
/// <param name="searchRange">
/// The range of text to search in.
/// </param>
/// <param name="searchPatterh">
/// The pattern to look for.
/// </param>
/// <param name="replacePattern">
/// The pattern to replace the found text with.
/// </param>
/// <param name="options">
/// Options used to perform the search.
/// </param>
/// <param name="expandedReplacePattern">
/// The result of the replacement. This output parameter will be useful when performing regular expression searches. Will be empty
/// if no matches are found.
/// </param>
/// <returns>
/// A <see cref="SnapshotSpan"/> pointing to the search result found. If no matches are found, null is returned.
/// </returns>
/// <remarks>
/// <para>
/// This function does not perform any edits. The consumers would need to create an <see cref="ITextEdit"/> to perform the actual text
/// replacement if desired. This method is safe to be executed from any thread.
/// </para>
/// <para>
/// Note that <paramref name="expandedReplacePattern"/> will always equal <paramref name="replacePattern"/> if search is not using regular
/// expressions. In those scenarios you can utilize the more lightweight <see cref="Find(SnapshotSpan, SnapshotPoint, string, FindOptions)"/>.
/// </para>
/// </remarks>
SnapshotSpan? FindForReplace(SnapshotSpan searchRange, string searchPattern, string replacePattern, FindOptions options, out string expandedReplacePattern);
/// <summary>
/// Finds all occurences of the <paramref name="searchPattern"/> in <paramref name="searchRange"/>.
/// </summary>
/// <param name="searchRange">
/// The range to search in.
/// </param>
/// <param name="searchPattern">
/// The pattern to search for.
/// </param>
/// <param name="options">
/// The options to use while performing the search operation.
/// </param>
/// <returns>
/// An <see cref="IEnumerable{SnapshotSpan}"/> containing all occurences of the <paramref name="searchPattern"/>.
/// </returns>
/// <remarks>
/// This method is safe to execute on any thread.
/// </remarks>
IEnumerable<SnapshotSpan> FindAll(SnapshotSpan searchRange, string searchPattern, FindOptions options);
/// <summary>
/// Finds all occurences of the <paramref name="searchPattern"/> in <paramref name="searchRange"/> starting from
/// <paramref name="startingPosition"/>.
/// </summary>
/// <param name="searchRange">
/// The range to search in.
/// </param>
/// <param name="startingPosition">
/// The location from which the search should be started.
/// </param>
/// <param name="searchPattern">
/// The pattern to search for.
/// </param>
/// <param name="options">
/// The options to use while performing the search operation.
/// </param>
/// <returns>
/// An <see cref="IEnumerable{SnapshotSpan}"/> containing all occurences of the <paramref name="searchPattern"/>.
/// </returns>
/// <remarks>
/// This method is safe to execute on any thread.
/// </remarks>
IEnumerable<SnapshotSpan> FindAll(SnapshotSpan searchRange, SnapshotPoint startingPosition, string searchPattern, FindOptions options);
/// <summary>
/// Searches for all occurences of the <paramref name="searchPattern"/> and calculates all
/// the corresponding replacement results for every match according to the <paramref name="replacePattern"/>.
/// </summary>
/// <param name="searchRange">
/// The range of text to search in.
/// </param>
/// <param name="searchPattern">
/// The pattern to search for.
/// </param>
/// <param name="replacePattern">
/// The replace pattern to use for the operation.
/// </param>
/// <param name="options">
/// The options to use while performing the search operation.
/// </param>
/// <returns>
/// An <see cref="IEnumerable{T}"/> containing all matches found and their corresponding replacement values.
/// </returns>
/// <remarks>
/// <para>
/// The returned <see cref="IEnumerable{T}"/> will contain a collection of tuples indicating all the matches. Each
/// <see cref="Tuple"/> will contain a <see cref="SnapshotSpan"/> referencing the location of the match and a <see cref="string"/>
/// containing the calculated replacement text for the match.
/// </para>
/// <para>
/// If you are not using regular expressions then the calculated replacement text will always
/// equal the <paramref name="replacePattern"/>. In that scenario, you can use the
/// <see cref="ITextSearchService2.FindAll(SnapshotSpan, string, FindOptions)"/> method to only obtain the search results.
/// </para>
/// </remarks>
IEnumerable<Tuple<SnapshotSpan, string>> FindAllForReplace(SnapshotSpan searchRange, string searchPattern, string replacePattern, FindOptions options);
}
}
|
