System.IO.TextReader Class

Summary

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

C# Syntax:

[Serializable] public abstract class TextReader : MarshalByRefObject, IDisposable

TextReader is designed for character input, whereas the Stream class is designed for byte input and output and the BinaryReader class is designed for reading primitive types in binary rather than text.

By default, a TextReader is not thread safe. See TextReader.Synchronized for a thread-safe wrapper.

A derived class must minimally implement the TextReader.Peek and TextReader.Read methods in order to make a useful instance of TextReader.

System.IO Namespace

System.IO.TextReader Member List:

Public Fields

Null	Provides a TextReader with no data to read from.

Public Methods

Close	Closes the TextReader and releases any system resources associated with the TextReader.
CreateObjRef (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.CreateObjRef Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.GetLifetimeService Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
InitializeLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.InitializeLifetimeService Obtains a lifetime service object to control the lifetime policy for this instance.
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 input stream.
Read	Overloaded: Read() Reads the next character from the input stream and advances the character position by one character.
Read	Overloaded: Read(in char[] buffer, int index, int count) Reads a maximum of count characters from the current stream and writes the data to buffer, beginning at index.
ReadBlock	Reads a maximum of count characters from the current stream and writes the data to buffer, beginning at index.
ReadLine	Reads a line of characters from the current stream and returns the data as a string.
ReadToEnd	Reads all characters from the current position to the end of the TextReader and returns them as one string.
Synchronized	Creates a thread-safe wrapper around the specified TextReader.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Constructors

ctor #1

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

Protected Methods

Dispose	Releases the unmanaged resources used by the TextReader and optionally releases the managed resources.
Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.MarshalByRefObject
• System.IO.TextReader
  • System.IO.StreamReader
  • System.IO.StringReader

System.IO.TextReader Member Details

Summary

Initializes a new instance of the TextReader class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected TextReader();

Use this constructor for derived classes.

Return to top

Summary

Provides a TextReader with no data to read from.

C# Syntax:

public static readonly TextReader Null;

Reading from the TextReader.Null text reader is similar to reading from the end of a stream:

TextReader.Read and TextReader.Peek methods return -1

TextReader.ReadBlock method returns zero

TextReader.ReadLine and TextReader.ReadToEnd methods return null

Return to top

Summary

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

C# Syntax:

public virtual void Close();

This implementation of Close calls the StringReader.Dispose method passing a true value.

Flushing the stream will not flush its underlying encoder unless you explicitly call Close. Setting StreamWriter.AutoFlush to true means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters.

Following a call to Close, any operations on the TextReader might throw exceptions. This default method is empty, but derived classes can override the method to provide the appropriate functionality.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.CreateObjRef

Summary

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

C# Syntax:

public virtual ObjRef CreateObjRef(    Type requestedType );

requestedType

The Type of the object that the new ObjRef will reference.

Return Value:

Information required to generate a proxy.

Exceptions

Exception Type	Condition
RemotingException	This instance is not a valid remoting object.

Return to top

Summary

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

C# Syntax:

protected virtual void Dispose(    bool disposing );

disposing

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

This method is called by the public Dispose() method and the Object.Finalize method.Dispose() invokes the protected Dispose(Boolean) method with the disposing parameter set to true. Object.Finalize invokes Dispose with disposing set to 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.

Notes to inheritors: Dispose can be called multiple times by other objects. When overriding Dispose(Boolean), be careful not to reference objects that have been previously disposed of in an earlier call to Dispose. For more information about how to implement Dispose(Boolean), see the conceptual topic at MSDN: implementingdisposemethod.

For more information about Dispose and Object.Finalize, see the conceptual topic at MSDN: cleaningupunmanagedresources and the conceptual topic at MSDN: overridingfinalizemethod.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~TextReader();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.GetLifetimeService

Summary

Retrieves the current lifetime service object that controls the lifetime policy for this instance.

C# Syntax:

public object GetLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance.

For more information about lifetime services, see the LifetimeServices class.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.InitializeLifetimeService

Summary

Obtains a lifetime service object to control the lifetime policy for this instance.

C# Syntax:

public virtual object InitializeLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the LifetimeServices.LeaseManagerPollTime property.

For more information about lifetime services, see the LifetimeServices class.

The following code example demonstrates creating a lease.

 public class MyClass : MarshalByRefObject
 {
   public override Object InitializeLifetimeService()
   {
     ILease lease = (ILease)base.InitializeLifetimeService();
     if (lease.CurrentState == LeaseState.Initial)
     {
          lease.InitialLeaseTime = TimeSpan.FromMinutes(1);
          lease.SponsorshipTimeout = TimeSpan.FromMinutes(2);
           lease.RenewOnCallTime = TimeSpan.FromSeconds(2);
     }
       return lease;
   }
 }

    

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

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 input stream.

C# Syntax:

public virtual int Peek();

Return Value:

The next character to be read, or -1 if no more characters are available or the stream does not support seeking.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.

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.

Return to top

Summary

Reads the next character from the input stream and advances the character position by one character.

C# Syntax:

public virtual int Read();

Return Value:

The next character from the input stream, or -1 if no more characters are available. The default implementation returns -1.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.

Return to top

Summary

Reads a maximum of count characters from the current stream and writes the data to buffer, beginning at index.

C# Syntax:

public virtual int Read(    in char[] buffer,    int index,    int count );

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.

index

The place in buffer at which to begin writing.

count

The maximum number of characters to read. If the end of the stream is reached before count of characters is read into buffer, the current method returns.

Return Value:

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 stream. This method returns zero if called when no more characters are left to read.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentException	The buffer length minus index is less than count.
ArgumentOutOfRangeException	index or count is negative.
IOException	An I/O error occurs.

This method returns after either count characters are read or the end of the file is reached. TextReader.ReadBlock is a blocking version of this method.

Return to top

Summary

Reads a maximum of count characters from the current stream and writes the data to buffer, beginning at index.

C# Syntax:

public virtual int ReadBlock(    in char[] buffer,    int index,    int count );

buffer

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

index

The place in buffer at which to begin writing.

count

The maximum number of characters to read.

Return Value:

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.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentException	The buffer length minus index is less than count.
ArgumentOutOfRangeException	index or count is negative.
IOException	An I/O error occurs.

The method blocks until either count characters are read, or all characters have been read. This is a blocking version of TextReader.Read.

Return to top

Summary

Reads a line of characters from the current stream and returns the data as a string.

C# Syntax:

public virtual string ReadLine();

Return Value:

The next line from the input stream, or null if all characters have been read.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.
OutOfMemoryException	There is insufficient memory to allocate a buffer for the returned string.
ArgumentOutOfRangeException	The number of characters in the next line is larger than Int32.MaxValue

A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), Environment.NewLine, or the end of stream marker. The string that is returned does not contain the terminating carriage return and/or line feed. The returned value is null if the end of the input stream has been reached.

If the current method throws an OutOfMemoryException, the reader's position in the underlying Stream is advanced by the number of characters the method was able to read, but the characters already read into the internal TextReader.ReadLine buffer are discarded. Since the position of the reader in the stream cannot be changed, the characters 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 TextReader.Read method and store the read characters in a preallocated buffer.

Return to top

Summary

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

C# Syntax:

public virtual string ReadToEnd();

Return Value:

A string containing all characters from the current position to the end of the TextReader.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.
OutOfMemoryException	There is insufficient memory to allocate a buffer for the returned string.
ArgumentOutOfRangeException	The number of characters in the next line is larger than Int32.MaxValue

If the current method throws an OutOfMemoryException, the reader's position in the underlying Stream is advanced by the number of characters the method was able to read, but the characters already read into the internal TextReader.ReadToEnd buffer are discarded. Since the position of the reader in the stream cannot be changed, the characters 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 TextReader.Read method and store the read characters in a preallocated buffer.

Return to top

Summary

Creates a thread-safe wrapper around the specified TextReader.

C# Syntax:

public static TextReader Synchronized(    TextReader reader );

reader

The TextReader to synchronize.

Return Value:

A thread-safe TextReader.

Exceptions

Exception Type	Condition
ArgumentNullException	reader is null.

The current method returns a class that wraps around the specified TextReader instance and restricts access to it by multiple threads. All reads from the returned wrapper will be thread safe.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page