Document saturating floating-point conversions to small integral types - #55948
Merged
tannergooding merged 2 commits intoSep 11, 2026
Merged
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Add the Half native fallback workaround to the article.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review tier: Lite
Findings: 1
New issues introduced by this change (1)
| Severity | Finding |
|---|---|
 |
docs/core/compatibility/jit/11/fp-to-small-integer.md — Document the Half native conversion workaround |
What changed in this PR
Documents the .NET 11 change where floating-point conversions to small integral types saturate at destination bounds.
Changes:
- Adds the new compatibility article with behavior details, examples, and workarounds.
- Links the .NET 9 predecessor article.
- Updates the compatibility TOC and .NET 11 index.
| File | Description |
|---|---|
docs/core/compatibility/toc.yml |
Adds the article to the compatibility TOC. |
docs/core/compatibility/jit/9.0/fp-to-integer.md |
Links to the .NET 11 article. |
docs/core/compatibility/jit/11/fp-to-small-integer.md |
Documents the .NET 11 conversion behavior. |
docs/core/compatibility/11.md |
Adds the article to the .NET 11 index. |
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
gewarren
approved these changes
Sep 11, 2026
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
gewarren
approved these changes
Sep 11, 2026
tannergooding
deleted the
tannergooding-small-integral-conversion-docs
branch
September 11, 2026 23:10
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Document the .NET 11 Preview 7 behavioral change introduced by dotnet/runtime#128604. Unchecked floating-point conversions to sbyte, byte, short, ushort, and char saturate at the destination bounds on CoreCLR and Native AOT.
Preserve the distinction between hardware-dependent historical results and new saturation, including 65578.0 to short: 42 previously, 32767 now. Cover unchecked Half conversions and Single/Double.ConvertToInteger, and explain native and explicit-intermediate workarounds without promising universal recovery of historical results. Mono, checked conversions, and wider/vector conversions are outside this change. The proposed switch in dotnet/runtime#133608 is not documented as shipped.
Add the article to the .NET 11 index and compatibility TOC, and link it from the .NET 9 predecessor.
Content source
Adapted the user-reviewed draft's description, version, previous behavior, new behavior, breaking-change classification, reason, recommended action, and affected APIs into Learn article structure. The numeric tables and six-line C# example are preserved verbatim. Front matter, API cross-references, navigation entries, and the predecessor link are newly authored; no new feature claims are introduced.
Example validation
On Windows x64, the article's C# example returns 42 on .NET 10.0.12 and 32767 on .NET 11.0.0-rc.1.26425.128. Executable checks also cover all approved previous-result rows, float/double saturation and NaN/infinity cases, unchecked Half conversions, and Single/Double.ConvertToInteger for all five destinations.
For x = -42 and x = 65578, the three documented ushort workarounds return 65494 and 42, respectively, on both tested runtimes. The float-native equivalents return the same values. These are observations on this platform, not guarantees for other platforms. Preview 7 introduction is established from the runtime merge's release-branch membership.
Markdownlint passes for all three changed Markdown files. Content checks confirm preserved tables, relative links, navigation entries, and whitespace.
Note
This pull request was drafted with AI assistance from Copilot.
Internal previews
Build report