Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added detailed documentation for Stream.Read(Span<byte>) method. #10469

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added detailed documentation for Stream.Read(Span<byte>) method. #10469

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 27 additions & 23 deletions xml/System.IO/Stream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1992,6 +1992,32 @@
<MemberSignature Language="F#" Value="abstract member Read : Span&lt;byte&gt; -&gt; int&#xA;override this.Read : Span&lt;byte&gt; -&gt; int" Usage="stream.Read buffer" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; virtual int Read(Span&lt;System::Byte&gt; buffer);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="buffer" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0" />
</Parameters>
<Docs>
<param name="buffer">A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.</param>
<summary>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.</summary>
<returns>The total number of bytes read into the buffer. This can be less than the size of the buffer if that many bytes are not currently available, or zero (0) if the buffer's length is zero or the end of the stream has been reached.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Use the <xref:System.IO.Stream.CanRead%2A> property to determine whether the current instance supports reading. Use the <xref:System.IO.Stream.ReadAsync%2A> method to read asynchronously from the current stream.

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. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). <xref:System.IO.Stream.Read%2A> returns 0 only if zero bytes were requested or 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.

Use <xref:System.IO.BinaryReader> for reading primitive data types.

]]></format>
</remarks>
<exception cref="System.IO.IOException">An I/O error occurred during reading.</exception>
<exception cref="System.NotSupportedException">The stream does not support reading.</exception>
<exception cref="System.ObjectDisposedException">The stream has been disposed.</exception>
</Docs>
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
Expand All @@ -2018,30 +2044,8 @@
<AttributeName Language="F#">[&lt;System.Runtime.CompilerServices.NullableContext(0)&gt;]</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="buffer" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0" />
</Parameters>
<Docs>
<param name="buffer">A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.</param>
<summary>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.</summary>
<returns>The total number of bytes read into the buffer. This can be less than the size of the buffer if that many bytes are not currently available, or zero (0) if the buffer's length is zero or the end of the stream has been reached.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Use the <xref:System.IO.Stream.CanRead%2A> property to determine whether the current instance supports reading. Use the <xref:System.IO.Stream.ReadAsync%2A> method to read asynchronously from the current stream.

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. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). <xref:System.IO.Stream.Read%2A> returns 0 only if zero bytes were requested or 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.

Use <xref:System.IO.BinaryReader> for reading primitive data types.

]]></format>
</remarks>
</Docs>
</Member>

<Member MemberName="Read">
<MemberSignature Language="C#" Value="public abstract int Read (byte[] buffer, int offset, int count);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance int32 Read(unsigned int8[] buffer, int32 offset, int32 count) cil managed" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
Expand Down