Skip to content

Update S.T.Unicode.Utf8 APIs to correctly document the isFinalBlock bool. #3208

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

Merged
merged 1 commit into from
Oct 2, 2019
Merged

Update S.T.Unicode.Utf8 APIs to correctly document the isFinalBlock bool. #3208

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
22 changes: 11 additions & 11 deletions xml/System.Text.Unicode/Utf8.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,25 +44,25 @@
<param name="source">A UTF-16 encoded read-only character span.</param>
<param name="destination">A UTF-8 encoded byte span.</param>
<param name="charsRead">When the method returns, the number of characters read from <paramref name="source" />.</param>
<param name="bytesWritten">When the method returns, the number of characters written to <paramref name="destination" />.</param>
<param name="bytesWritten">When the method returns, the number of bytes written to <paramref name="destination" />.</param>
<param name="replaceInvalidSequences">
<see langword="true" /> to replace invalid UTF-16 sequences in <paramref name="source" /> with U+FFFD; <see langword="false" /> to return <see cref="F:System.Buffers.OperationStatus.InvalidData" /> if invalid characters are found in <paramref name="source" />.</param>
<param name="isFinalBlock">
<see langword="true" /> if the method should not return <see cref="F:System.Buffers.OperationStatus.InvalidData" />; otherwise, <see langword="false" />.</param>
<see langword="true" /> if the method should not return <see cref="F:System.Buffers.OperationStatus.NeedMoreData" />; otherwise, <see langword="false" />.</param>
<summary>Converts a UTF-16 character span to a UTF-8 encoded byte span.</summary>
<returns>A value that indicates that status of the conversion.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

### Remarks
## Remarks

This method corresponds to the [UTFEncoding.GetBytes](xref:System.Text.UTF8Encoding.GetBytes%2A) method, except that it has a different calling convention, different error handling mechanisms, and different performance characteristics.
This method corresponds to the [UTF8Encoding.GetBytes](xref:System.Text.UTF8Encoding.GetBytes%2A) method, except that it has a different calling convention, different error handling mechanisms, and different performance characteristics.

If 'replaceInvalidSequences' is `true`, the method replaces any ill-formed subsequences in `source` with U+FFFD in `destination` and continues processing the remainder of the buffer. Otherwise, the method returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType> if it encounters any ill-formed sequences.

If the method returns an error code, the out parameters indicate how much of the data was successfully transcoded, and the location of the ill-formed subsequence can be deduced from these values.

If 'replaceInvalidSequences' is `true`, the method never returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType>. If 'isFinalBlock' is `true`, the method is never returns <xref:System.Buffers.OperationStatus.NeedMoreData?displayProperty=nameWithType>.
If 'replaceInvalidSequences' is `true`, the method never returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType>. If 'isFinalBlock' is `true`, the method never returns <xref:System.Buffers.OperationStatus.NeedMoreData?displayProperty=nameWithType>.

]]></format>
</remarks>
Expand Down Expand Up @@ -91,28 +91,28 @@ If 'replaceInvalidSequences' is `true`, the method never returns <xref:System.Bu
<Parameter Name="isFinalBlock" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="source">A UTF-8 encoded read-only character span.</param>
<param name="destination">A UTF-8 encoded byte span..</param>
<param name="source">A UTF-8 encoded read-only byte span.</param>
<param name="destination">A UTF-16 encoded character span.</param>
<param name="bytesRead">When the method returns, the number of bytes read from <paramref name="source" />.</param>
<param name="charsWritten">When the method returns, the number of characters written to <paramref name="destination" />.</param>
<param name="replaceInvalidSequences">
<see langword="true" /> to replace invalid UTF-8 sequences in <paramref name="source" /> with U+FFFD; <see langword="false" /> to return <see cref="F:System.Buffers.OperationStatus.InvalidData" /> if invalid characters are found in <paramref name="source" />.</param>
<param name="isFinalBlock">
<see langword="true" /> if the method should not return <see cref="F:System.Buffers.OperationStatus.InvalidData" />; otherwise, <see langword="false" />.</param>
<see langword="true" /> if the method should not return <see cref="F:System.Buffers.OperationStatus.NeedMoreData" />; otherwise, <see langword="false" />.</param>
<summary>Converts a UTF-8 encoded read-only byte span to a UTF-16 encoded character span.</summary>
<returns>A value that indicates the status of the conversion.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

### Remarks
## Remarks

This method corresponds to the [UTFEncoding.GetChars](xref:System.Text.UTF8Encoding.GetChars%2A) method, except that it has a different calling convention, different error handling mechanisms, and different performance characteristics.
This method corresponds to the [UTF8Encoding.GetChars](xref:System.Text.UTF8Encoding.GetChars%2A) method, except that it has a different calling convention, different error handling mechanisms, and different performance characteristics.

If 'replaceInvalidSequences' is `true`, the method replaces any ill-formed subsequences in `source` with U+FFFD in `destination` and continues processing the remainder of the buffer. Otherwise, the method returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType> if it encounters any ill-formed sequences.

If the method returns an error code, the out parameters indicate how much of the data was successfully transcoded, and the location of the ill-formed subsequence can be deduced from these values.

If 'replaceInvalidSequences' is `true`, the method never returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType>. If 'isFinalBlock' is `true`, the method is never returns <xref:System.Buffers.OperationStatus.NeedMoreData?displayProperty=nameWithType>.
If 'replaceInvalidSequences' is `true`, the method never returns <xref:System.Buffers.OperationStatus.InvalidData?displayProperty=nameWithType>. If 'isFinalBlock' is `true`, the method never returns <xref:System.Buffers.OperationStatus.NeedMoreData?displayProperty=nameWithType>.

]]></format>
</remarks>
Expand Down