Scanning Text Using a Reader
The text framework has very robust features built-in for scanning through snapshot text via the use of readers.
ITextBufferReader vs. ITextSnapshotReader
There are two types of readers included with the text framework: ITextBufferReader and ITextSnapshotReader.
ITextBufferReader
ITextBufferReader provides a very fast, low-level interface for scanning through text. It reads character-by-character but does allow for jumping to a specific offset.
The current character's value, offset, and TextPosition can be retrieved at any time. This interface also has some help methods like ReadThrough, that advance the reader until it encounters and passes a particular character.
Please see the ITextBufferReader members list in the class library to see what scanning features are available for use.
ITextSnapshotReader
ITextSnapshotReader is a higher-level interface for scanning through text and is made specifically for reading an ITextSnapshot instance. It internally uses a ITextBufferReader but wraps the core buffer reader with a ton of extended functionality.
A snapshot reader can return the current character, offset, TextPosition, current IToken, current token text, current ITextSnapshotLine, and more.
It has a large number of helper methods for navigating through text, such as ReadToken, GoToNextTokenWithId, etc.
Please see the ITextSnapshotReader members list in the class library to see what scanning features are available for use.
Getting an ITextSnapshotReader for a Snapshot
To get an ITextSnapshotReader for an ITextSnapshot, call the ITextSnapshot.GetReader method.
There are two overloads for this method. Each accepts a parameter indicating to where in the snapshot the reader should be initialized. The first overload accepts an offset and the second accepts a TextPosition.
This code retrieves an ITextSnapshotReader for the current text in a document, starting at offset 0:
ITextSnapshotReader reader = document.CurrentSnapshot.GetReader(0);
Getting an ITextBufferReader for a Snapshot
As mentioned above, the ITextSnapshotReader implementations use a core ITextBufferReader instance. So once you have an ITextSnapshotReader instance via the code in the previous section, simply use its BufferReader property to return the wrapped ITextBufferReader.
This code retrieves an ITextBufferReader from the reader defined above:
ITextBufferReader bufferReader = reader.BufferReader;
Notes on Performance
If you only need to do core character scanning for a snapshot, use an ITextBufferReader. It is the most low-level reader available and therefore has the fastest performance.
You also can do basic text/character scanning with an ITextSnapshotReader. This will incur a negligible performance loss since all of those members essentially just call members on the core ITextBufferReader.
Performance, while still fast, will be lessened a little when using the various members on ITextSnapshotReader that deal with tokens and token scanning. Any of these methods do additional work to ensure that tokens are in sync with the reader. Overall, they should still perform fast, as this is a common usage for readers.
The ITextSnapshotReader.Options property allows you to customize some optimizations used for token scanning to aid in performance. Since tokens are virtualized in the text/parsing framework, tweaking these options to best fit your scenario can make a difference in scanning performance. The following section describes the options.
ITextSnapshotReader Options
The ITextSnapshotReader interface has an Options property that allows you to modify the options for the reader instance. The options are of type ITextSnapshotReaderOptions and must be changed prior to using any members on the reader, if you are changing the options.
The options are mainly used to configure optimizations for token scanning, since tokens are virtualized in the text/parsing framework. If you will not be doing token scanning with your reader, you do not need to change the options. Even if you are doing token scanning, you can optionally leave the default options if you wish.
The options basically deal with how large of a block of tokens to load up, both initially and afterward, when scanning through text. They also let you indicate whether you primarily plan on scanning forward, backward, or both.
Please see the ITextSnapshotReaderOptions members list in the class library to see what options available for use.
Getting an ITextBufferReader for a String
The StringTextBufferReader class is an implementation of ITextBufferReader that operates on a string.
This code creates a StringTextBufferReader for a string:
StringTextBufferReader bufferReader = new StringTextBufferReader("Text to read");
Getting a System.IO.TextReader for an ITextBufferReader
The ITextBufferReader.AsTextReader method can be used to create a System.IO.TextReader instance.
System.IO.TextReader objects are defined in the core .NET framework and are useful for passing to various external components that are based on text readers.