[Foundation] Improve nullability in NSArray.ArrayFromHandleFunc. (#24900)

* Improve nullability annotations for ArrayFromHandleFunc<T> (return T?[]?).
* Add an ArrayFromHandleDropNullElements overload with Converter and NSNullBehavior parameters.
* Update DictionaryContainer.GetArray and GetArrayOfDictionariesValue to use ArrayFromHandleDropNullElements.
* Update NSUrlSessionConfiguration.ProxyConfigurations to use NonNullArrayFromHandleDropNullElements.
* Update PdfAnnotation.QuadrilateralPoints to return CGPoint[]? and use ArrayFromHandle.
* Update XML docs for ArrayFromHandleFunc, ProxyConfigurations and QuadrilateralPoints.

Contributes towards #17285.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rolfbjarne

src/Foundation/DictionaryContainer.cs

@@ -215,7 +215,7 @@ bool TryGetNativeValue (NativeHandle key, out NativeHandle value)
 			if (!TryGetNativeValue (key, out var value))
 				return null;
 
-			return NSArray.ArrayFromHandleFunc<T> (value, creator);
+			return NSArray.ArrayFromHandleDropNullElements<T> (value, (v) => creator (v), NSNullBehavior.DropIfIncompatible);
 		}
 
 		/// <summary>Retrieves the <see cref="DictionaryContainer" /> array associeted with <paramref name="key" />.</summary>
@@ -226,7 +226,7 @@ bool TryGetNativeValue (NativeHandle key, out NativeHandle value)
 			if (!TryGetNativeValue (key, out var value))
 				return null;
 
-			return NSArray.ArrayFromHandleFunc<T> (value, (handle) => Create<T> (handle)!);
+			return NSArray.ArrayFromHandleDropNullElements<T> (value, (handle) => Create<T> (handle)!, NSNullBehavior.DropIfIncompatible);
 		}
 
 		/// <summary>Returns the nullable <see cref="byte" /> associated with the specified <paramref name="key" />.</summary>

src/Foundation/NSArray.cs

@@ -686,6 +686,18 @@ static bool TryGetItem<T> (NativeHandle elementHandle, Converter<NativeHandle, T
 			return ArrayFromHandle<T> (handle, (h) => Runtime.GetINativeObject<T> (h, false)!, nsNullElementBehavior, releaseHandle)!;
 		}
 
+		/// <summary>Returns a strongly-typed C# array from a handle to an NSArray, dropping null elements.</summary>
+		/// <typeparam name="T">Parameter type, determines the kind of array returned.</typeparam>
+		/// <param name="handle">Pointer (handle) to the unmanaged object.</param>
+		/// <param name="createObject">A delegate to convert a native handle to an object of type T.</param>
+		/// <param name="nsNullElementBehavior">How to handle null and NSNull elements in the native array.</param>
+		/// <param name="releaseHandle">Whether the native NSArray instance should be released before returning or not.</param>
+		/// <returns>A C# array with the values (excluding null elements). Returns <see langword="null" /> if the handle is <see cref="NativeHandle.Zero" />.</returns>
+		internal static T []? ArrayFromHandleDropNullElements<T> (NativeHandle handle, Converter<NativeHandle, T> createObject, NSNullBehavior nsNullElementBehavior, bool releaseHandle = false)
+		{
+			return ArrayFromHandle<T> (handle, createObject, nsNullElementBehavior, releaseHandle)!;
+		}
+
 		/// <summary>Returns a strongly-typed C# array from a handle to an NSArray, dropping null elements and guaranteeing a non-null return value.</summary>
 		/// <typeparam name="T">Parameter type, determines the kind of array returned.</typeparam>
 		/// <param name="handle">Pointer (handle) to the unmanaged object.</param>
@@ -832,36 +844,38 @@ internal static T [] ToNonNullArrayDropNullElements<T> (NSArray? weakArray) wher
 			}
 		}
 
-#nullable disable
-		// Used when we need to provide our constructor
-		/// <typeparam name="T">Parameter type, determines the kind of array returned.</typeparam>
-		/// <param name="handle">Pointer (handle) to the unmanaged object.</param>
-		/// <param name="createObject">To be added.</param>
-		/// <summary>Returns a strongly-typed C# array of the parametrized type from a handle to an NSArray.</summary>
-		/// <returns>An C# array with the values.</returns>
+		/// <summary>Creates a strongly-typed C# array from a handle to an <see cref="NSArray" />, using a custom factory function.</summary>
+		/// <typeparam name="T">The element type for the returned array.</typeparam>
+		/// <param name="handle">Pointer (handle) to the unmanaged <see cref="NSArray" /> object.</param>
+		/// <param name="createObject">A factory function that creates an instance of <typeparamref name="T" /> from a native handle.</param>
+		/// <returns>A C# array with the values, or <see langword="null" /> if <paramref name="handle" /> is <see cref="NativeHandle.Zero" />.</returns>
 		/// <remarks>
-		///           <para>Use this method to get a set of NSObject arrays from a handle to an NSArray.   Instead of wrapping the results in NSObjects, the code invokes your method to create the return value.</para>
-		///           <example>
-		///             <code lang="c#"><![CDATA[
-		/// int [] args = NSArray.ArrayFromHandle<int> (someHandle, (x) => (int) x);
+		///   <para>
+		///     Instead of wrapping the results in <see cref="NSObject" /> instances,
+		///     this method invokes <paramref name="createObject" /> for each element to create the return value.
+		///   </para>
+		///   <example>
+		///     <code lang="c#"><![CDATA[
+		/// var args = NSArray.ArrayFromHandleFunc<int> (someHandle, (x) => (int) x);
 		/// ]]></code>
-		///           </example>
-		///         </remarks>
-		static public T [] ArrayFromHandleFunc<T> (NativeHandle handle, Func<NativeHandle, T> createObject)
+		///   </example>
+		/// </remarks>
+		public static T? []? ArrayFromHandleFunc<T> (NativeHandle handle, Func<NativeHandle, T> createObject)
 		{
 			return ArrayFromHandle<T> (handle, (v) => createObject (v));
 		}
 
-		/// <summary>Create a managed array from a pointer to a native NSArray instance.</summary>
-		/// <param name="handle">The pointer to the native NSArray instance.</param>
-		/// <param name="createObject">A callback that returns an instance of the type T for a given pointer (for an element in the NSArray).</param>
-		/// <param name="releaseHandle">Whether the native NSArray instance should be released before returning or not.</param>
-		public static T [] ArrayFromHandleFunc<T> (NativeHandle handle, Func<NativeHandle, T> createObject, bool releaseHandle)
+		/// <summary>Creates a strongly-typed C# array from a handle to an <see cref="NSArray" />, using a custom factory function.</summary>
+		/// <typeparam name="T">The element type for the returned array.</typeparam>
+		/// <param name="handle">Pointer (handle) to the unmanaged <see cref="NSArray" /> object.</param>
+		/// <param name="createObject">A factory function that creates an instance of <typeparamref name="T" /> from a native handle.</param>
+		/// <param name="releaseHandle">Whether the native <see cref="NSArray" /> instance should be released before returning or not.</param>
+		/// <returns>A C# array with the values, or <see langword="null" /> if <paramref name="handle" /> is <see cref="NativeHandle.Zero" />.</returns>
+		public static T? []? ArrayFromHandleFunc<T> (NativeHandle handle, Func<NativeHandle, T> createObject, bool releaseHandle)
 		{
 			return ArrayFromHandle<T> (handle, (v) => createObject (v), releaseHandle);
 		}
 
-#nullable enable
 		/// <summary>Creates a managed array from a pointer to a native NSArray of NSDictionary objects, dropping null and NSNull elements.</summary>
 		/// <typeparam name="T">The type of objects to create from the dictionaries.</typeparam>
 		/// <param name="handle">The pointer to the native NSArray instance containing NSDictionary objects.</param>

src/Foundation/NSUrlSessionConfiguration.cs

@@ -70,16 +70,17 @@ public static NSUrlSessionConfiguration CreateBackgroundSessionConfiguration (st
 			return config;
 		}
 
+		/// <summary>Gets or sets the proxy configurations for this session.</summary>
+		/// <value>An array of <see cref="Network.NWProxyConfig" /> objects representing the proxy configurations.</value>
 		[SupportedOSPlatform ("ios17.0")]
 		[SupportedOSPlatform ("macos14.0")]
 		[SupportedOSPlatform ("maccatalyst17.0")]
 		[SupportedOSPlatform ("tvos17.0")]
 		public NWProxyConfig [] ProxyConfigurations {
-			get => NSArray.ArrayFromHandleFunc (_ProxyConfigurations, handle => new NWProxyConfig (handle, owns: false));
+			get => NSArray.NonNullArrayFromHandleDropNullElements (_ProxyConfigurations, handle => new NWProxyConfig (handle, owns: false));
 			set {
-				var arr = NSArray.FromNSObjects (value);
-				_ProxyConfigurations = arr.Handle;
-				GC.KeepAlive (arr);
+				using var arr = NSArray.FromNSObjects (value);
+				_ProxyConfigurations = arr.GetHandle ();
 			}
 		}
 

src/PdfKit/PdfAnnotation.cs

@@ -76,30 +76,22 @@ public PdfAnnotationKey AnnotationType {
 			set { Type = value.GetConstant ()!; }
 		}
 
-		/// <summary>To be added.</summary>
-		///         <value>To be added.</value>
-		///         <remarks>To be added.</remarks>
+		/// <summary>Gets or sets the points defining the quadrilateral bounds of the annotation.</summary>
+		/// <value>An array of <see cref="CGPoint" /> values representing the quadrilateral vertices, or <see langword="null" />.</value>
 		[SupportedOSPlatform ("macos")]
 		[SupportedOSPlatform ("ios")]
 		[SupportedOSPlatform ("maccatalyst")]
 		[SupportedOSPlatform ("tvos18.2")]
-		public CGPoint [] QuadrilateralPoints {
+		public CGPoint []? QuadrilateralPoints {
 			get {
-				return NSArray.ArrayFromHandleFunc<CGPoint> (_QuadrilateralPoints, (v) => {
+				return NSArray.ArrayFromHandle<CGPoint> (_QuadrilateralPoints, (v) => {
 					using (var value = new NSValue (v))
 						return value.CGPointValue;
 				});
 			}
 			set {
-				if (value is null) {
-					_QuadrilateralPoints = IntPtr.Zero;
-				} else {
-					using (var arr = new NSMutableArray ()) {
-						for (int i = 0; i < value.Length; i++)
-							arr.Add (NSValue.FromCGPoint (value [i]));
-						_QuadrilateralPoints = arr.Handle;
-					}
-				}
+				using var arr = NSArray.FromNSObjects<CGPoint> ((element) => NSValue.FromCGPoint (element), value);
+				_QuadrilateralPoints = arr.GetHandle ();
 			}
 		}
 	}

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -21062,7 +21062,6 @@ P:Foundation.NSUbiquitousKeyValueStoreChangeEventArgs.ChangedKeys
 P:Foundation.NSUbiquitousKeyValueStoreChangeEventArgs.ChangeReason
 P:Foundation.NSUndoManagerCloseUndoGroupEventArgs.Discardable
 P:Foundation.NSUrlAuthenticationChallenge.SenderObject
-P:Foundation.NSUrlSessionConfiguration.ProxyConfigurations
 P:Foundation.NSUrlSessionConfiguration.SessionType
 P:Foundation.NSUrlSessionConfiguration.StrongConnectionProxyDictionary
 P:Foundation.NSUrlSessionHandler.AllowsCellularAccess