System.IO.StreamReader Class

public class StreamReader : TextReader

Base Types

Object
  MarshalByRefObject
    TextReader
      StreamReader

This type implements IDisposable.

Assembly

mscorlib

Library

BCL

Summary

Implements a Stream that reads characters from a byte stream in a particular encoding.

Description

The StreamReader class is designed for character input in a particular Encoding, whereas subclasses of Stream are designed for byte input and output.

[Note: StreamReader defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system.

When reading from a Stream, it is more efficient to use a buffer that is the same size as the internal buffer of the stream.

By default, a StreamReader is not thread safe. For a thread-safe wrapper, see System.IO.TextReader.Synchronized(System.IO.TextReader) .

]

See Also

System.IO Namespace

Members

StreamReader Constructors

StreamReader(System.String, System.Text.Encoding, bool, int) Constructor
StreamReader(System.String, System.Text.Encoding, bool) Constructor
StreamReader(System.String, System.Text.Encoding) Constructor
StreamReader(System.String, bool) Constructor
StreamReader(System.String) Constructor
StreamReader(System.IO.Stream, System.Text.Encoding, bool, int) Constructor
StreamReader(System.IO.Stream, System.Text.Encoding, bool) Constructor
StreamReader(System.IO.Stream) Constructor
StreamReader(System.IO.Stream, bool) Constructor
StreamReader(System.IO.Stream, System.Text.Encoding) Constructor

StreamReader Methods

StreamReader.Close Method
StreamReader.DiscardBufferedData Method
StreamReader.Dispose Method
StreamReader.Peek Method
StreamReader.Read() Method
StreamReader.Read(char[], int, int) Method
StreamReader.ReadLine Method
StreamReader.ReadToEnd Method

StreamReader Properties

StreamReader.BaseStream Property
StreamReader.CurrentEncoding Property


StreamReader(System.String, System.Text.Encoding, bool, int) Constructor

public StreamReader(string path, Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified file name, with the specified character encoding, byte order mark detection option, and buffer size.

Parameters

path
A String that specifies the complete file path to read.
encoding
A Encoding that specifies the character encoding to use.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReaderis required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .
bufferSize
A Int32 that specifies the minimum buffer size, in number of 16-bit characters. If less than the minimum allowable size (128 characters), the minimum allowable size is used.

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
FileNotFoundExceptionThe file specified in path was not found.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath or encoding is null .
ArgumentOutOfRangeExceptionbuffersize is less than or equal to zero.

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding .

If requested, the current constructor detects the encoding by examining the first three bytes of the stream. The constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the System.Text.Encoding.GetPreamble method for more information.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

When reading from a Stream, it is more efficient to use a buffer that is the same size as the internal buffer of the stream.

For information on the valid format and characters for path strings, see Path.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.String, System.Text.Encoding, bool) Constructor

public StreamReader(string path, Encoding encoding, bool detectEncodingFromByteOrderMarks);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified file name, with the specified character encoding and byte order mark detection option.

Parameters

path
A String that specifies the complete file path to read.
encoding
A Encoding that specifies the character encoding to use.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReaderis required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
FileNotFoundExceptionThe file specified in path was not found.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath or encoding is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

If requested, the current constructor detects the encoding by examining the first three bytes of the stream. The constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the System.Text.Encoding.GetPreamble method for more information.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.String, System.Text.Encoding) Constructor

public StreamReader(string path, Encoding encoding);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified file name and with the specified character encoding.

Parameters

path
A String that specifies the complete file path to read.
encoding
A Encoding that specifies the character encoding to use.

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
FileNotFoundExceptionThe file specified in path was not found.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath or encoding is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.String, bool) Constructor

public StreamReader(string path, bool detectEncodingFromByteOrderMarks);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified file name, with the specified byte order mark detection option.

Parameters

path
A String that specifies the complete file path to read.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReader is required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
FileNotFoundExceptionThe file specified in path was not found.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property to UTF8Encoding , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

If requested, the current constructor detects the encoding by examining the first three bytes of the stream. The constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, UTF-8 encoding is used. See the System.Text.Encoding.GetPreamble method for more information.

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.String) Constructor

public StreamReader(string path);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified file name.

Parameters

path
A String that specifies the complete file path to read.

Exceptions

Exception TypeCondition
IOExceptionpath is in an invalid format or contains invalid characters.
DirectoryNotFoundExceptionThe directory information specified in path was not found.
FileNotFoundExceptionThe file specified in path was not found.
ArgumentExceptionpath is an empty string ("").
ArgumentNullExceptionpath is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property to UTF8Encoding, and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

[Note: path is not required to be a file stored on disk; it can be any part of a system that supports access via streams. For example, depending on the system, this class might be able to access a physical device.

For information on the valid format and characters for path strings, see Path .

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.IO.Stream, System.Text.Encoding, bool, int) Constructor

public StreamReader(Stream stream, Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified stream, with the specified character encoding, byte order mark detection option, and buffer size.

Parameters

stream
The Stream to read.
encoding
A Encoding that specifies the character encoding to use.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReader is required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .
bufferSize
A Int32 that specifies the minimum buffer size, in number of 16-bit characters. If bufferSize is less than the minimum allowable size (128 characters), the minimum allowable size is used.

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support reading.
ArgumentNullExceptionstream or encoding is null .
ArgumentOutOfRangeExceptionbufferSize is less than or equal to zero.

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding parameter the System.IO.StreamReader.BaseStream property using stream .

If requested, this constructor detects the encoding by examining the first three bytes of the stream. The constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. For more information, see the System.Text.Encoding.GetPreamble method.

[Note: When reading from a Stream, it is more efficient to use a buffer that is the same size as the internal buffer of the stream.]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.IO.Stream, System.Text.Encoding, bool) Constructor

public StreamReader(Stream stream, Encoding encoding, bool detectEncodingFromByteOrderMarks);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified stream, with the specified character encoding and byte order mark detection option.

Parameters

stream
The Stream to read.
encoding
A Encoding that specifies the character encoding to use.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReader is required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support reading.
ArgumentNullExceptionstream or encoding is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding , the System.IO.StreamReader.BaseStream property using stream , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

If requested, this constructor detects the encoding by examining the first three bytes of stream . This constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the stream starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the System.Text.Encoding.GetPreamble method for more information.

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.IO.Stream) Constructor

public StreamReader(Stream stream);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified stream.

Parameters

stream
The Stream to read.

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support reading.
ArgumentNullExceptionstream is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property to UTF8Encoding, the System.IO.StreamReader.BaseStream property using stream , and the internal buffer to the default size. [Note: The default buffer size is implementation dependent.]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.IO.Stream, bool) Constructor

public StreamReader(Stream stream, bool detectEncodingFromByteOrderMarks);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified stream, with the specified byte order mark detection option.

Parameters

stream
The stream to read.
detectEncodingFromByteOrderMarks
A Boolean value that indicates whether the new StreamReader is required to look for byte order marks at the beginning of the stream. Specify true to enable detection of byte order marks; otherwise, specify false .

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support reading.
ArgumentNullExceptionstream is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property to UTF8Encoding , the System.IO.StreamReader.BaseStream property using stream , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

If requested, the current constructor detects the encoding by examining the first three bytes of the stream. The constructor automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, UTF-8 encoding is used. For more information, see the System.Text.Encoding.GetPreamble method.

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader(System.IO.Stream, System.Text.Encoding) Constructor

public StreamReader(Stream stream, Encoding encoding);

Summary

Constructs and initializes a new instance of the StreamReader class for the specified stream with the specified character encoding.

Parameters

stream
The Stream to read.
encoding
A Encoding that specifies the character encoding to use.

Exceptions

Exception TypeCondition
ArgumentExceptionstream does not support reading.
ArgumentNullExceptionstream or encoding is null .

Description

This constructor initializes the System.IO.StreamReader.CurrentEncoding property using encoding , the System.IO.StreamReader.BaseStream property using stream , and the internal buffer to the default size. [Note: The default buffer size is implementation defined.]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.Close Method

public override void Close();

Summary

Closes the current instance of StreamReader , releasing any system resources associated with it.

Description

Following a call to this method, operations on the current instance might raise exceptions.

[Note: This version of System.IO.StreamReader.Close is equivalent to System.IO.StreamReader.Dispose(System.Boolean)(true ).

This method overrides System.IO.TextReader.Close.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.DiscardBufferedData Method

public void DiscardBufferedData();

Summary

Allows a StreamReader to discard its buffered data.

Description

[Note: This method is useful when reading from a stream after seeking to a new position. If this method is not called and the internal buffer is not empty, a read attempt at the new location will first return data that is in the buffer before returning the text at the current position in the stream.]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.Dispose Method

protected override void Dispose(bool disposing);

Summary

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

Parameters

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

Description

When the disposing parameter is true , this method releases all resources held by any managed objects that this StreamReader references. This method invokes the Dispose() method of each referenced object.

[Note: System.IO.StreamReader.Dispose(System.Boolean) can be called multiple times by other objects. When overriding System.IO.StreamReader.Dispose(System.Boolean)(Boolean), be careful not to reference objects that have been previously disposed in an earlier call to System.IO.StreamReader.Dispose(System.Boolean) .

This method calls the dispose method of the base class, System.IO.TextReader.Dispose(System.Boolean)(disposing).

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.Peek Method

public override int Peek();

Summary

Returns the next character in the underlying stream without advancing the position of the StreamReader in the stream.

Return Value

The next character from the character source as a Int32 , or -1 if at the end of the stream.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurred.

Description

[Note: This method returns -1 is when the end of the underlying stream is reached because a Unicode character can contain only values between hexadecimal 0x0000 to 0xFFFF (0 to 65535).

This method overrides System.IO.TextReader.Peek.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.Read() Method

public override int Read();

Summary

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

Return Value

The next character from the character source represented as a Int32 , or -1 if at the end of the stream.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurred.

Description

[Note: This method returns -1 when the end of the underlying stream is reached because a Unicode character can contain only values between hexadecimal 0x0000 to 0xFFFF (0 to 65535).

This method overrides System.IO.TextReader.Read.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.Read(char[], int, int) Method

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

Summary

Reads a maximum of count characters from the current stream into buffer, beginning at index.

Parameters

buffer
A Char array. 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 instance.
index
A Int32 that specifies the index of buffer at which to begin writing.
count
A Int32 that specifies the maximum number of characters to read.

Return Value

A Int32 containing the number of characters that have been read, or zero if there are no more characters left to read. Can be less than count if the end of the stream has been reached.

Exceptions

Exception TypeCondition
ArgumentExceptionbuffer .Length - index < count .
ArgumentNullExceptionbuffer is null .
ArgumentOutOfRangeExceptionindex or count is negative.
IOException An I/O error occurred.

-or-

The current stream is closed.

Description

[Note: This method returns after either count characters are read, or the end of the file is reached. System.IO.TextReader.ReadBlock(System.Char[],System.Int32,System.Int32) is a blocking version of System.IO.StreamReader.Read .

This method overrides System.IO.TextReader.Read.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.ReadLine Method

public override string ReadLine();

Summary

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

Return Value

A String containing the next line from the input stream, or null if the end of the input stream is reached.

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurred.
OutOfMemoryExceptionThere is insufficient memory to allocate a buffer for the returned string.

Description

[Note: This method defines a line as a sequence of characters followed by a carriage return (hexadecimal 0x000d), a line feed (hexadecimal 0x000a), or System.Environment.NewLine. The returned string does not contain the terminating character(s).

This method overrides System.IO.TextReader.ReadLine.

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.ReadToEnd Method

public override string ReadToEnd();

Summary

Reads the stream from the current position to the end of the stream.

Return Value

A Int32 containing the rest of the stream as a string, from the current position to the end. If the current position is at the end of the stream, returns the empty string ("").

Exceptions

Exception TypeCondition
IOExceptionAn I/O error occurred.
OutOfMemoryExceptionThere is insufficient memory to allocate a buffer for the returned string.

Description

[Note: This method overrides System.IO.TextReader.ReadToEnd .

]

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.BaseStream Property

public virtual Stream BaseStream { get; }

Summary

Gets the underlying stream.

Property Value

The underlying Stream which the current StreamReader instance is reading.

Description

This property is read-only.

See Also

System.IO.StreamReader Class, System.IO Namespace

StreamReader.CurrentEncoding Property

public virtual Encoding CurrentEncoding { get; }

Summary

Gets the current character encoding that the current StreamReader is using.

Property Value

The current Encoding used by the current reader.

Description

This property is read-only.

The value returned by this property might change after the first call to a System.IO.StreamReader.Read method if encoding auto detection was specified to the constructor for the current instance.

See Also

System.IO.StreamReader Class, System.IO Namespace