Add ImmutableArray<T>.Builder.DrainToImmutable()

[jeffhandley]

Closes #72625. Approved API details: #72625 (comment).

DrainToImmutable will "do the cheapest thing possible" to return the current contents as an immutable array and then reset the collection to a zero-length array.

[ghost]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, to please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-collections
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Closes #72625. Approved API details: #72625 (comment).

DrainToImmutable will "do the cheapest thing possible" to return the current contents as an immutable array and then reset the collection to a zero-length array.

Author:	jeffhandley
Assignees:	jeffhandley
Labels:	area-System.Collections
Milestone:	8.0.0

[eiriktsarpalis]

Thanks!

[jeffhandley]

• Failure in runtime (Build Linux arm64 Release NativeAOT) is System.Tests.ArrayTests.CreateInstance test failing in NativeAOT #79403
• Failure in runtime (Build Browser wasm Linux Release LibraryTests) is SyndicationFeed_Write_RSS_Atom test failing with "IOException : The file '/tmp/' already exists." #78454