`Array.ConstrainedCopy` explanation is misleading and has incorrect exception specifications

[GeeLaw]

Type of issue

Other (describe below)

Description

Array.ConstrainedCopy says:

Copies a range of elements from an Array starting at the specified source index and pastes them to another Array starting at the specified destination index. Guarantees that all changes are undone if the copy does not succeed completely.

The meaning of "Guarantees that all changes are undone if the copy does not succeed completely.", if interpreted naturally, is as follows.

It tries to do the same as Array.Copy, and if an exception is thrown during this copying, it undoes all the changes.

This interpretation is reasonable due to the use of present indicative in both the condition and the consequence. Moreover, it suggests two things:

1. If both arrays are primitive integral types and the representable range of the source array's element type is not larger than that for the destination, then the copy succeeds. For example, constrained-copying int[] into long[] would appear to always succeed.
2. It will use an intermediate array to avoid corrupting the destination.

Of course, the method does neither of the above. It just checks the types before starting copying. So it's not "undo changes if not succeeding completely", but "not doing any changes unless provably safe". The message exception for ArrayTypeMismatchException is more accurate.

Suggested rewording:

 Copies a range of elements from an `Array` starting at the specified source
 index and pastes them to another `Array` starting at the specified destination
 index.
-Guarantees that all changes are undone if the copy does not succeed completely.
+The method does not start copying unless the arrays' element types are provably
+compatible, so it guarantees the array is not modified if it throws an exception.

Maybe add the compatibility rules (see comments)?

---

Array.ConstrainedCopy is documented that it may throw InvalidCastException. It will never throw this exception, instead it's always the ArrayTypeMismatchException if the element types are not provable compatible.

InvalidCastException should be removed from the list of possible exceptions in Array.ConstrainedCopy.

---

This applies retroactively to all .NET versions since .NET Framework 2.0.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.array.constrainedcopy?view=net-10.0

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/Array.xml

Document Version Independent Id

8f1a7f9e-41e5-6fcb-aab3-b102bac80a5f

Platform Id

4b343d8d-ec07-df04-21c1-3976ef5b6f43

Article author

@dotnet-bot

[GeeLaw]

On documenting the compatibility rule... It's rather complex and cannot be easily expressed in terms of C# because CLR is more permissive than C# (e.g., int[] is uint[]). Let the element types of source, destination be D, B. From what I observe:

• if B is the same as D (including void, only for the purpose of recursion in case of pointers), then they're compatible;
• if B is not the same kind as D (kind being "pointer type", "value type", "reference type"), then they're not compatible;
• if B is pointer b* and D is pointer d* and b is compatible with d (per those rules), then compatible;
• byte, sbyte, and any enum based on byte, sbyte are compatible (i.e., both B, D are one of those);
• similar rules for short, ushort, and int, uint, and long, ulong;
• similar rule between nint and nuint (? see below);
• if B is reference type and D is implicitly reference convertible (in the sense of C#) to B, then compatible;
• if B is array b[r][...] and D is array d[r][...] and b[...] is compatible with d[...] (per those rules; the rest array specifier [...] need not be the same when considering this rule), then compatible;
• no other cases are compatible (? see below).

Notably, there's no compatibility between each pair of the following, either way: char, ushort; nuint, void*; byte*, void*.

It's also not clear to me what happens for bool, char, nint, nuint and enums based on them, the latter of which are allowed in ECMA 335 Edition 6 (p. 168, "II.14.3 Enums"), but not allowed in C#.