StreamReader.Read Method (Char(), Int32, Int32)

Updated: December 2010

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

Namespace:  System.IO
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
Public Overrides Function Read ( _
	<OutAttribute> buffer As Char(), _
	index As Integer, _
	count As Integer _
) As Integer
'Usage
Dim instance As StreamReader 
Dim buffer As Char()
Dim index As Integer 
Dim count As Integer 
Dim returnValue As Integer 

returnValue = instance.Read(buffer, index, _
	count)

Parameters

buffer
Type: System.Char()

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
Type: System.Int32

The index of buffer at which to begin writing.

count
Type: System.Int32

The maximum number of characters to read.

Return Value

Type: System.Int32
The number of characters that have been read, or 0 if at the end of the stream and no data was read. The number will be less than or equal to the count parameter, depending on whether the data is available within the stream.

ExceptionCondition
ArgumentException

The buffer length minus index is less than count.

ArgumentNullException

buffer is Nothing.

ArgumentOutOfRangeException

index or count is negative.

IOException

An I/O error occurs, such as the stream is closed.

This method overrides Read.

This method returns an integer so that it can return 0 if the end of the stream has been reached.

When using the Read method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream, where the internal buffer is set to your desired block size, and to always read less than the block size. If the size of the internal buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the DiscardBufferedData method; however, this method slows performance and should be called only when absolutely necessary.

This method returns after either the number of characters specified by the count parameter are read, or the end of the file is reached. ReadBlock is a blocking version of Read.

For a list of common I/O tasks, see Common I/O Tasks.

The following code example reads five characters at a time until the end of the file is reached.

Imports System
Imports System.IO
Imports System.Text

Public Class Test

    Public Shared Sub Main()
        Dim path As String = "c:\temp\MyTest.txt" 

        Try 
            If File.Exists(path) Then
                File.Delete(path)
            End If 

            Dim sw As StreamWriter = New StreamWriter(path)
            sw.WriteLine("This")
            sw.WriteLine("is some text")
            sw.WriteLine("to test")
            sw.WriteLine("Reading")
            sw.Close()

            Dim sr As StreamReader = New StreamReader(path)

            Do While sr.Peek() >= 0
                'This is an arbitrary size for this example. 
                Dim c(5) As Char
                sr.Read(c, 0, c.Length)
                'The output will look odd, because 
                'only five characters are read at a time.
                Console.WriteLine(c)
            Loop
            sr.Close()
        Catch e As Exception
            Console.WriteLine("The process failed: {0}", e.ToString())
        End Try 
    End Sub 
End Class

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

December 2010

Added information about calling DiscardBufferedData.

Information enhancement.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft