Class TextReader

Represents a reader that can read a sequential series of characters.

Inheritance
object
MarshalByRefObject
TextReader
StreamReader
Implements
Inherited Members
Namespace: System.IO
Assembly: System.IO.Streams.dll
Syntax
public abstract class TextReader : MarshalByRefObject, IDisposable
Remarks

TextReader is the abstract base class of StreamReader and StringReader, which read characters from streams and strings, respectively. Use these derived classes to open a text file for reading a specified range of characters, or to create a reader based on an existing stream.

Constructors

TextReader()

Initializes a new instance of the TextReader class.

Declaration
protected TextReader()
Remarks

Use this constructor for derived classes.

Methods

Close()

Closes the TextReader and releases any system resources associated with the TextReader.

Declaration
public virtual void Close()
Remarks

This implementation of Close() calls the Dispose(bool) method and passes it a true value.

Dispose()

Releases all resources used by the TextReader object.

Declaration
public void Dispose()

Dispose(bool)

Releases the unmanaged resources used by the TextReader and optionally releases the managed resources.

Declaration
protected virtual void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.
Remarks

This method is called by the public Dispose() method and the Finalize method. By default, this method specifies the disposing parameter as true. Finalize specifies the disposing parameter as false. When the disposing parameter is true, this method releases all resources held by any managed objects that this TextReader references. This method invokes the Dispose() method of each referenced object.

Peek()

Reads the next character without changing the state of the reader or the character source. Returns the next available character without actually reading it from the reader.

Declaration
public virtual int Peek()
Returns
Type Description
int

An integer representing the next character to be read, or -1 if no more characters are available or the reader does not support seeking.
Remarks

The Peek() method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a Char type.

The current position of the TextReader is not changed by this operation.The returned value is -1 if no more characters are available.The default implementation returns -1.

The TextReader class is an abstract class. Therefore, you do not instantiate it in your code.For an example of using the Peek method, see the StreamReader.Peek method.

Read()

Reads the next character from the text reader and advances the character position by one character.

Declaration
public virtual int Read()
Returns
Type Description
int

The next character from the text reader, or -1 if no more characters are available. The default implementation returns -1.
Remarks

The TextReader class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the Read method, see the StreamReader.Read method.

Read(char[], int, int)

Reads a specified maximum number of characters from the current reader and writes the data to a buffer, beginning at the specified index.

Declaration
public virtual int Read(char[] buffer, int index, int count)
Parameters
Type Name Description
char[] buffer

When this method returns, contains the specified character array with the values between index and (index + count - 1) replaced by the characters read from the current source.
int index

The position in buffer at which to begin writing.
int count

The maximum number of characters to read. If the end of the reader is reached before the specified number of characters is read into the buffer, the method returns.
Returns
Type Description
int

The number of characters that have been read. The number will be less than or equal to count, depending on whether the data is available within the reader. This method returns 0 (zero) if it is called when no more characters are left to read.
Remarks

This method returns after either count characters are read or the end of the file is reached. ReadBlock(char[], int, int) is a blocking version of this method.

The TextReader class is an abstract class. Therefore, you do not instantiate it in your code.For an example of using the Read(char[], int, int) method, see the StreamReader.Read method.

ReadBlock(char[], int, int)

Reads a specified maximum number of characters from the current text reader and writes the data to a buffer, beginning at the specified index.

Declaration
public virtual int ReadBlock(char[] buffer, int index, int count)
Parameters
Type Name Description
char[] buffer

When this method returns, this parameter contains the specified character array with the values between index and (index + count -1) replaced by the characters read from the current source.
int index

The position in buffer at which to begin writing.
int count

The maximum number of characters to read.
Returns
Type Description
int

The number of characters that have been read. The number will be less than or equal to count, depending on whether all input characters have been read.
Remarks

The position of the underlying text reader is advanced by the number of characters that were read into buffer.

The method blocks until either count characters are read, or all characters have been read.This is a blocking version of Read(char[], int, int).

ReadLine()

Reads a line of characters from the text reader and returns the data as a string.

Declaration
public virtual string ReadLine()
Returns
Type Description
string

The next line from the reader, or null if all characters have been read.
Remarks

A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), a carriage return followed by a line feed, Environment.NewLine, or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is null if the end of the input stream has been reached. If the method throws an OutOfMemoryException exception, the reader's position in the underlying Stream is advanced by the number of characters the method was able to read, but the characters that were already read into the internal ReadLine buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the TextReader object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying Stream also needs to be reinitialized. To avoid such a situation and produce robust code you should use the Read method and store the read characters in a preallocated buffer. The TextReader class is an abstract class. Therefore, you do not instantiate it in your code.For an example of using the ReadLine method, see the StreamReader.ReadLine method.

ReadToEnd()

Reads all characters from the current position to the end of the text reader and returns them as one string.

Declaration
public virtual string ReadToEnd()
Returns
Type Description
string

A string that contains all characters from the current position to the end of the text reader.
Remarks

If the method throws an OutOfMemoryException exception, the reader's position in the underlying Stream is advanced by the number of characters the method was able to read, but the characters that were already read into the internal ReadToEnd buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the TextReader. If the initial position within the stream is unknown or the stream does not support seeking, the underlying Stream also needs to be reinitialized. To avoid such a situation and produce robust code you should use the Read method and store the read characters in a preallocated buffer. The TextReader class is an abstract class. Therefore, you do not instantiate it in your code.For an example of using the ReadToEnd method, see the StreamReader.ReadToEnd method.

Implements

Extension Methods