Stream.Read 方法

定義

多載

Read(Span<Byte>)

當在衍生類別中覆寫時,自目前資料流讀取一連串的位元組,並依所讀取的位元組數目進階資料流中的位置。When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Read(Byte[], Int32, Int32)

當在衍生類別中覆寫時,自目前資料流讀取一連串的位元組,並依所讀取的位元組數目進階資料流中的位置。When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Read(Span<Byte>)

當在衍生類別中覆寫時,自目前資料流讀取一連串的位元組,並依所讀取的位元組數目進階資料流中的位置。When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

public:
 virtual int Read(Span<System::Byte> buffer);
public virtual int Read (Span<byte> buffer);
abstract member Read : Span<byte> -> int
override this.Read : Span<byte> -> int
Public Overridable Function Read (buffer As Span(Of Byte)) As Integer

參數

buffer
Span<Byte>

記憶體區域。A region of memory. 當這個方法傳回時,讀取自目前來源的位元組會取代此區域內容。When this method returns, the contents of this region are replaced by the bytes read from the current source.

傳回

讀入緩衝區的位元組總數。The total number of bytes read into the buffer. 如果目前無法取得足夠的位元組,則這個數目可能小於緩衝區所配置的位元組數,如果已經到達資料流末端,則為零 (0)。This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.

備註

使用 CanRead 屬性來判斷目前的實例是否支援讀取。Use the CanRead property to determine whether the current instance supports reading. 使用 ReadAsync 方法,以非同步方式從目前的資料流程讀取。Use the ReadAsync method to read asynchronously from the current stream.

這個方法的執行會從目前的資料流程讀取最多 buffer.Length 個位元組,並將它們儲存在 buffer中。Implementations of this method read a maximum of buffer.Length bytes from the current stream and store them in buffer. 資料流程中目前的位置會依讀取的位元組數來前移;不過,如果發生例外狀況,則資料流程中的目前位置會保持不變。The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. 「實現」會傳回讀取的位元組數目。Implementations return the number of bytes read. 在沒有可用資料的情況下,將會封鎖執行,直到至少有一個位元組的資料可以讀取為止。The implementation will block until at least one byte of data can be read, in the event that no data is available. 只有當資料流程中沒有其他資料,而且不需要更多(例如封閉的通訊端或檔案結尾)時,Read 才會傳回0。Read returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). 即使尚未到達資料流程的結尾,執行也可以自由地傳回比要求還要少的位元組。An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

使用 BinaryReader 來讀取基本資料類型。Use BinaryReader for reading primitive data types.

Read(Byte[], Int32, Int32)

當在衍生類別中覆寫時,自目前資料流讀取一連串的位元組,並依所讀取的位元組數目進階資料流中的位置。When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

public:
 abstract int Read(cli::array <System::Byte> ^ buffer, int offset, int count);
public abstract int Read (byte[] buffer, int offset, int count);
abstract member Read : byte[] * int * int -> int
Public MustOverride Function Read (buffer As Byte(), offset As Integer, count As Integer) As Integer

參數

buffer
Byte[]

位元組的陣列。An array of bytes. 當這個方法傳回時,緩衝區會包含指定的位元組陣列,這個陣列具有介於 offset 到 (offset + count - 1) 之間的值,已由讀取自目前來源的位元組所取代。When this method returns, the buffer contains the specified byte array with the values between offset and (offset + count - 1) replaced by the bytes read from the current source.

offset
Int32

buffer 中以零起始的位元組位移,即開始儲存讀取自目前資料流之資料的位置。The zero-based byte offset in buffer at which to begin storing the data read from the current stream.

count
Int32

要從目前資料流讀取的最大位元組數目。The maximum number of bytes to be read from the current stream.

傳回

讀入緩衝區的位元組總數。The total number of bytes read into the buffer. 如果目前沒有夠多的位元組,此值可以小於要求的位元組數目,如果已到達資料流結尾則為零 (0)。This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.

例外狀況

offsetcount 的總和大於緩衝區長度。The sum of offset and count is larger than the buffer length.

buffernullbuffer is null.

offsetcount 是負數。offset or count is negative.

發生 I/O 錯誤。An I/O error occurs.

資料流不支援讀取。The stream does not support reading.

關閉資料流後呼叫了方法。Methods were called after the stream was closed.

範例

下列範例顯示如何使用 Read 讀取資料區塊。The following example shows how to use Read to read a block of data.

using namespace System;
using namespace System::IO;

public ref class Block
{
public:
    static void Main()
    {
        Stream^ s = gcnew MemoryStream();
        for (int i = 0; i < 100; i++)
        {
            s->WriteByte((Byte)i);
        }
        s->Position = 0;

        // Now read s into a byte buffer.
        array<Byte>^ bytes = gcnew array<Byte>(s->Length);
        int numBytesToRead = (int) s->Length;
        int numBytesRead = 0;
        while (numBytesToRead > 0)
        {
            // Read may return anything from 0 to 10.
            int n = s->Read(bytes, numBytesRead, 10);
            // The end of the file is reached.
            if (n == 0)
            {
                break;
            }
            numBytesRead += n;
            numBytesToRead -= n;
        }
        s->Close();
        // numBytesToRead should be 0 now, and numBytesRead should
        // equal 100.
        Console::WriteLine("number of bytes read: {0:d}", numBytesRead);
    }
};

int main()
{
    Block::Main();
}
using System;
using System.IO;

public class Block
{
    public static void Main()
    {
        Stream s = new MemoryStream();
        for (int i = 0; i < 122; i++)
        {
            s.WriteByte((byte)i);
        }
        s.Position = 0;

        // Now read s into a byte buffer with a little padding.
        byte[] bytes = new byte[s.Length + 10];
        int numBytesToRead = (int)s.Length;
        int numBytesRead = 0;
        do
        {
            // Read may return anything from 0 to 10.
            int n = s.Read(bytes, numBytesRead, 10);
            numBytesRead += n;
            numBytesToRead -= n;
        } while (numBytesToRead > 0);
        s.Close();
       
        Console.WriteLine("number of bytes read: {0:d}", numBytesRead);
    }
}
Imports System.IO

Public Class Block
    Public Shared Sub Main()
        Dim s As Stream = New MemoryStream()
        For i As Integer = 0 To 121
            s.WriteByte(CType(i, Byte))
        Next i
        s.Position = 0

        ' Now read s into a byte buffer that is padded slightly.
        Dim bytes(s.Length + 10) As Byte
        Dim numBytesToRead As Integer = s.Length
        Dim numBytesRead As Integer = 0
        Dim n As Integer
        Do
            ' Read may return anything from 0 to 10.
            n = s.Read(bytes, numBytesRead, 10)
            ' The end of the file is reached.
            numBytesRead += n
            numBytesToRead -= n
        Loop While numBytesToRead > 0

        s.Close()
    
        Console.WriteLine("number of bytes read: {0:d}", numBytesRead)
    End Sub
End Class

備註

使用 CanRead 屬性來判斷目前的實例是否支援讀取。Use the CanRead property to determine whether the current instance supports reading. 使用 ReadAsync 方法,以非同步方式從目前的資料流程讀取。Use the ReadAsync method to read asynchronously from the current stream.

這個方法的執行會從目前的資料流程讀取最多 count 個位元組,並將它們儲存在 buffer 開始 offsetImplementations of this method read a maximum of count bytes from the current stream and store them in buffer beginning at offset. 資料流程中目前的位置會依讀取的位元組數來前移;不過,如果發生例外狀況,則資料流程中的目前位置會保持不變。The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. 「實現」會傳回讀取的位元組數目。Implementations return the number of bytes read. 在沒有可用資料的情況下,將會封鎖執行,直到至少有一個位元組的資料可以讀取為止。The implementation will block until at least one byte of data can be read, in the event that no data is available. 只有當資料流程中沒有其他資料,而且不需要更多(例如封閉的通訊端或檔案結尾)時,Read 才會傳回0。Read returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). 即使尚未到達資料流程的結尾,執行也可以自由地傳回比要求還要少的位元組。An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

使用 BinaryReader 來讀取基本資料類型。Use BinaryReader for reading primitive data types.

另請參閱

適用於