Replace nullable pointers with Option<NonNull<_>> and update docs

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+* **Breaking:** Change type for pointers, which may be null, to `Option<NonNull<_>>`.
+
 # 0.3.3 (2019-12-1)
 
 * Add missing `Hash` implementation for `AndroidHandle`.

src/android.rs

@@ -1,5 +1,5 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw window handle for Android.
 ///
@@ -14,7 +14,7 @@ use core::ptr;
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct AndroidHandle {
     /// A pointer to an ANativeWindow.
-    pub a_native_window: Option<ptr::NonNull<c_void>>,
+    pub a_native_window: Option<NonNull<c_void>>,
     #[doc(hidden)]
     #[deprecated = "This field is used to ensure that this struct is non-exhaustive, so that it may be extended in the future. Do not refer to this field."]
     pub _non_exhaustive_do_not_use: crate::seal::Seal,

src/ios.rs

@@ -1,5 +1,5 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw window handle for iOS.
 ///
@@ -13,9 +13,9 @@ use core::ptr;
 /// ```
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct IOSHandle {
-    pub ui_window: *mut c_void,
-    pub ui_view: *mut c_void,
-    pub ui_view_controller: *mut c_void,
+    pub ui_window: Option<NonNull<c_void>>,
+    pub ui_view: Option<NonNull<c_void>>,
+    pub ui_view_controller: Option<NonNull<c_void>>,
     #[doc(hidden)]
     #[deprecated = "This field is used to ensure that this struct is non-exhaustive, so that it may be extended in the future. Do not refer to this field."]
     pub _non_exhaustive_do_not_use: crate::seal::Seal,
@@ -25,9 +25,9 @@ impl IOSHandle {
     pub fn empty() -> IOSHandle {
         #[allow(deprecated)]
         IOSHandle {
-            ui_window: ptr::null_mut(),
-            ui_view: ptr::null_mut(),
-            ui_view_controller: ptr::null_mut(),
+            ui_window: None,
+            ui_view: None,
+            ui_view_controller: None,
             _non_exhaustive_do_not_use: crate::seal::Seal,
         }
     }

src/lib.rs

@@ -79,18 +79,15 @@ mod platform {
 /// # Safety guarantees
 ///
 /// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the
-/// implementer of this trait to ensure that condition is upheld. However, It is entirely valid
-/// behavior for fields within each platform-specific `RawWindowHandle` variant to be `null` or
-/// `0`, and appropriate checking should be done before the handle is used.
+/// implementer of this trait to ensure that condition is upheld.
 ///
 /// Despite that qualification, implementers should still make a best-effort attempt to fill in all
 /// available fields. If an implementation doesn't, and a downstream user needs the field, it should
 /// try to derive the field from other fields the implementer *does* provide via whatever methods the
 /// platform provides.
 ///
 /// The exact handles returned by `raw_window_handle` must remain consistent between multiple calls
-/// to `raw_window_handle`, and must be valid for at least the lifetime of the `HasRawWindowHandle`
-/// implementer.
+/// to `raw_window_handle` as long as not indicated otherwise by platform specific events.
 pub unsafe trait HasRawWindowHandle {
     fn raw_window_handle(&self) -> RawWindowHandle;
 }

src/macos.rs

@@ -1,5 +1,5 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw window handle for macOS.
 ///
@@ -13,8 +13,8 @@ use core::ptr;
 /// ```
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct MacOSHandle {
-    pub ns_window: *mut c_void,
-    pub ns_view: *mut c_void,
+    pub ns_window: Option<NonNull<c_void>>,
+    pub ns_view: Option<NonNull<c_void>>,
     // TODO: WHAT ABOUT ns_window_controller and ns_view_controller?
     #[doc(hidden)]
     #[deprecated = "This field is used to ensure that this struct is non-exhaustive, so that it may be extended in the future. Do not refer to this field."]
@@ -25,8 +25,8 @@ impl MacOSHandle {
     pub fn empty() -> MacOSHandle {
         #[allow(deprecated)]
         MacOSHandle {
-            ns_window: ptr::null_mut(),
-            ns_view: ptr::null_mut(),
+            ns_window: None,
+            ns_view: None,
             _non_exhaustive_do_not_use: crate::seal::Seal,
         }
     }