Merge pull request #12227 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.IO/MemoryStream.xml

@@ -312,8 +312,6 @@
 
  This constructor exposes the underlying stream that <xref:System.IO.MemoryStream.GetBuffer%2A> returns.
 
-
-
 ## Examples
  This code example is part of a larger example provided for the <xref:System.IO.MemoryStream> class.
 
@@ -452,7 +450,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The <xref:System.IO.MemoryStream.CanRead%2A>, <xref:System.IO.MemoryStream.CanSeek%2A>, and <xref:System.IO.MemoryStream.CanWrite%2A> properties are all set to `true`, but the capacity cannot be changed. <xref:System.IO.MemoryStream.Capacity%2A> is set to `count`.
+ The <xref:System.IO.MemoryStream.CanRead>, <xref:System.IO.MemoryStream.CanSeek>, and <xref:System.IO.MemoryStream.CanWrite> properties are all set to `true`, but the capacity cannot be changed. <xref:System.IO.MemoryStream.Capacity%2A> is set to `count`.
 
  The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see <xref:System.IO.MemoryStream.SetLength%2A>).
 
@@ -527,7 +525,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The <xref:System.IO.MemoryStream.CanRead%2A> and <xref:System.IO.MemoryStream.CanSeek%2A> properties are both set to `true`. <xref:System.IO.MemoryStream.Capacity%2A> is set to `count`.
+ The <xref:System.IO.MemoryStream.CanRead> and <xref:System.IO.MemoryStream.CanSeek> properties are both set to `true`. <xref:System.IO.MemoryStream.Capacity> is set to `count`.
 
  The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see <xref:System.IO.MemoryStream.SetLength%2A>).
 
@@ -604,7 +602,7 @@
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The <xref:System.IO.MemoryStream.CanRead%2A> and <xref:System.IO.MemoryStream.CanSeek%2A> properties are both set to `true`. <xref:System.IO.MemoryStream.Capacity%2A> is set to `count`.
+ The <xref:System.IO.MemoryStream.CanRead> and <xref:System.IO.MemoryStream.CanSeek> properties are both set to `true`. <xref:System.IO.MemoryStream.Capacity> is set to `count`.
 
  The new stream instance can be written to, but the <xref:System.IO.MemoryStream.Capacity%2A> of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see <xref:System.IO.MemoryStream.SetLength%2A>).
 
@@ -1029,20 +1027,23 @@ Refer to the <xref:System.IO.Stream.BeginWrite%2A> remarks for additional usage
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
- `Capacity` is the buffer length for system-provided byte arrays. `Capacity` cannot be set to a value less than the current length of the stream.
-
-
+`Capacity` is the buffer length for system-provided byte arrays. `Capacity` cannot be set to a value less than the current length of the stream.
 
 ## Examples
- This code example is part of a larger example provided for the <xref:System.IO.MemoryStream> class.
 
- :::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet5":::
- :::code language="vb" source="~/snippets/visualbasic/System.IO/MemoryStream/Overview/memstream.vb" id="Snippet5":::
+This code example is part of a larger example provided for the <xref:System.IO.MemoryStream> class.
+
+:::code language="csharp" source="~/snippets/csharp/System.IO/MemoryStream/Overview/memstream.cs" id="Snippet5":::
+:::code language="vb" source="~/snippets/visualbasic/System.IO/MemoryStream/Overview/memstream.vb" id="Snippet5":::
 
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentOutOfRangeException">A capacity is set that is negative or less than the current length of the stream.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException">A capacity is set that is negative or less than the current length of the stream.
+
+-or-
+
+In .NET 11 and later versions, the value being set is greater than 0x7FFFFFC7 bytes.
+        </exception>
         <exception cref="T:System.ObjectDisposedException">The current stream is closed.</exception>
         <exception cref="T:System.NotSupportedException">
           <see langword="set" /> is invoked on a stream whose capacity cannot be modified.</exception>
@@ -1546,9 +1547,9 @@ The pending operation does not support writing.</exception>
 ## Remarks
  Because any data written to a <xref:System.IO.MemoryStream> object is written into RAM, this method is redundant.
 
- If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property.
+ If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status> property.
 
- You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token%2A> property as the `cancellationToken` parameter.
+ You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token> property as the `cancellationToken` parameter.
 
  This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.IO.MemoryStream.Flush>.
 
@@ -2077,9 +2078,9 @@ The pending operation does not support writing.</exception>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property.
+ If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status> property.
 
- You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token%2A> property as the `cancellationToken` parameter.
+ You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token> property as the `cancellationToken` parameter.
 
  This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.IO.MemoryStream.Read(System.Byte[],System.Int32,System.Int32)>.
 
@@ -2229,7 +2230,7 @@ The pending operation does not support writing.</exception>
 
  Seeking to any location beyond the length of the stream is supported.
 
- Do not use the <xref:System.IO.MemoryStream.Seek%2A> method to determine the new position in the stream if the <xref:System.IO.MemoryStream> was initialized with a non-zero offset. If you do, <xref:System.IO.MemoryStream.Seek%2A> will return an inaccurate value. Instead, use the <xref:System.IO.MemoryStream.Position%2A> property to get the new position of the stream.
+ Do not use the <xref:System.IO.MemoryStream.Seek%2A> method to determine the new position in the stream if the <xref:System.IO.MemoryStream> was initialized with a non-zero offset. If you do, <xref:System.IO.MemoryStream.Seek%2A> will return an inaccurate value. Instead, use the <xref:System.IO.MemoryStream.Position> property to get the new position of the stream.
 
 
 
@@ -2303,28 +2304,35 @@ The pending operation does not support writing.</exception>
         <Parameter Name="value" Type="System.Int64" />
       </Parameters>
       <Docs>
-        <param name="value">The value at which to set the length.</param>
+        <param name="value">The length to set.</param>
         <summary>Sets the length of the current stream to the specified value.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
- This method overrides <xref:System.IO.Stream.SetLength%2A>.
+This method overrides <xref:System.IO.Stream.SetLength%2A>.
 
- If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the <xref:System.IO.MemoryStream.ReadByte%2A> method returns -1, the <xref:System.IO.MemoryStream.Read%2A> method reads zero bytes into the provided byte array, and <xref:System.IO.MemoryStream.Write%2A> and <xref:System.IO.MemoryStream.WriteByte%2A> methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros.
+If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the <xref:System.IO.MemoryStream.ReadByte%2A> method returns -1, the <xref:System.IO.MemoryStream.Read%2A> method reads zero bytes into the provided byte array, and <xref:System.IO.MemoryStream.Write%2A> and <xref:System.IO.MemoryStream.WriteByte%2A> methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros.
 
 > [!NOTE]
->  A <xref:System.IO.MemoryStream> instance must support writing for this method to work. Use the <xref:System.IO.MemoryStream.CanWrite%2A> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite%2A>.
+> A <xref:System.IO.MemoryStream> instance must support writing for this method to work. Use the <xref:System.IO.MemoryStream.CanWrite> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite>.
 
  ]]></format>
         </remarks>
         <exception cref="T:System.NotSupportedException">The current stream is not resizable and <paramref name="value" /> is larger than the current capacity.
 
- -or-
+-or-
 
- The current stream does not support writing.</exception>
+The current stream does not support writing.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">
-          <paramref name="value" /> is negative or is greater than the maximum length of the <see cref="T:System.IO.MemoryStream" />, where the maximum length is (<see cref="F:System.Int32.MaxValue">Int32.MaxValue</see> - <code>origin</code>), and <code>origin</code> is the index into the underlying buffer at which the stream starts.</exception>
+          <paramref name="value" /> is negative
+
+-or-
+
+In .NET 11 and later versions, <paramref name="value" /> is greater than 0x7FFFFFC7 bytes.
+
+-or-
+
+In .NET 10 and earlier versions, <paramref name="value" /> is greater than the maximum length of the <see cref="T:System.IO.MemoryStream" />, where the maximum length is (<see cref="F:System.Int32.MaxValue">Int32.MaxValue</see> - <code>origin</code>), and <code>origin</code> is the index into the underlying buffer at which the stream starts.</exception>
         <related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
         <related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
         <related type="Article" href="/dotnet/standard/io/how-to-write-text-to-a-file">How to: Write Text to a File</related>
@@ -2390,10 +2398,10 @@ The pending operation does not support writing.</exception>
 ## Remarks
  This method omits unused bytes in <xref:System.IO.MemoryStream> from the array. To get the entire buffer, use the <xref:System.IO.MemoryStream.GetBuffer%2A> method.
 
- This method returns a copy of the contents of the <xref:System.IO.MemoryStream> as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the <xref:System.IO.MemoryStream.%23ctor%2A> constructor for details.
+ This method returns a copy of the contents of the <xref:System.IO.MemoryStream> as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the <xref:System.IO.MemoryStream.%23ctor*> constructor for details.
 
 > [!NOTE]
->  This method works when the <xref:System.IO.MemoryStream> is closed.
+> This method works when the <xref:System.IO.MemoryStream> is closed.
 
  ]]></format>
         </remarks>
@@ -2741,9 +2749,9 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property.
+ If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status> property.
 
- You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token%2A> property as the `cancellationToken` parameter.
+ You can create a cancellation token by creating an instance of the <xref:System.Threading.CancellationTokenSource> class and passing the <xref:System.Threading.CancellationTokenSource.Token> property as the `cancellationToken` parameter.
 
  This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.IO.MemoryStream.Write(System.Byte[],System.Int32,System.Int32)>.