Change how handles are constructed, so that we can ensure non-null handles

src/android.rs

@@ -1,43 +1,50 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw display handle for Android.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::AndroidDisplayHandle;
-/// let mut display_handle = AndroidDisplayHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct AndroidDisplayHandle;
+pub struct AndroidDisplayHandle {}
 
 impl AndroidDisplayHandle {
-    pub fn empty() -> Self {
+    /// Create a new empty display handle.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::AndroidDisplayHandle;
+    /// let handle = AndroidDisplayHandle::new();
+    /// ```
+    pub fn new() -> Self {
         Self {}
     }
 }
 
 /// Raw window handle for Android NDK.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::AndroidNdkWindowHandle;
-/// let mut window_handle = AndroidNdkWindowHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct AndroidNdkWindowHandle {
     /// A pointer to an `ANativeWindow`.
-    pub a_native_window: *mut c_void,
+    pub a_native_window: NonNull<c_void>,
 }
 
 impl AndroidNdkWindowHandle {
-    pub fn empty() -> Self {
-        Self {
-            a_native_window: ptr::null_mut(),
-        }
+    /// Create a new handle to an `ANativeWindow`.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use core::ptr::NonNull;
+    /// # use raw_window_handle::AndroidNdkWindowHandle;
+    /// # type ANativeWindow = ();
+    /// #
+    /// let ptr: NonNull<ANativeWindow>;
+    /// # ptr = NonNull::from(&());
+    /// let handle = AndroidNdkWindowHandle::new(ptr.cast());
+    /// ```
+    pub fn new(a_native_window: NonNull<c_void>) -> Self {
+        Self { a_native_window }
     }
 }

src/appkit.rs

@@ -1,43 +1,50 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw display handle for AppKit.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::AppKitDisplayHandle;
-/// let mut display_handle = AppKitDisplayHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct AppKitDisplayHandle;
+pub struct AppKitDisplayHandle {}
 
 impl AppKitDisplayHandle {
-    pub fn empty() -> Self {
+    /// Create a new empty display handle.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::AppKitDisplayHandle;
+    /// let handle = AppKitDisplayHandle::new();
+    /// ```
+    pub fn new() -> Self {
         Self {}
     }
 }
 
 /// Raw window handle for AppKit.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::AppKitWindowHandle;
-/// let mut window_handle = AppKitWindowHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct AppKitWindowHandle {
     /// A pointer to an `NSView` object.
-    pub ns_view: *mut c_void,
+    pub ns_view: NonNull<c_void>,
 }
 
 impl AppKitWindowHandle {
-    pub fn empty() -> Self {
-        Self {
-            ns_view: ptr::null_mut(),
-        }
+    /// Create a new handle to a view.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use core::ptr::NonNull;
+    /// # use raw_window_handle::AppKitWindowHandle;
+    /// # type NSView = ();
+    /// #
+    /// let view: &NSView;
+    /// # view = &();
+    /// let handle = AppKitWindowHandle::new(NonNull::from(view).cast());
+    /// ```
+    pub fn new(ns_view: NonNull<c_void>) -> Self {
+        Self { ns_view }
     }
 }

src/haiku.rs

@@ -1,46 +1,57 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw display handle for Haiku.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::HaikuDisplayHandle;
-/// let mut display_handle = HaikuDisplayHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct HaikuDisplayHandle;
+pub struct HaikuDisplayHandle {}
 
 impl HaikuDisplayHandle {
-    pub fn empty() -> Self {
+    /// Create a new empty display handle.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::HaikuDisplayHandle;
+    /// let handle = HaikuDisplayHandle::new();
+    /// ```
+    pub fn new() -> Self {
         Self {}
     }
 }
 
 /// Raw window handle for Haiku.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::HaikuWindowHandle;
-/// let mut window_handle = HaikuWindowHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct HaikuWindowHandle {
     /// A pointer to a BWindow object
-    pub b_window: *mut c_void,
+    pub b_window: NonNull<c_void>,
     /// A pointer to a BDirectWindow object that might be null
-    pub b_direct_window: *mut c_void,
+    pub b_direct_window: Option<NonNull<c_void>>,
 }
 
 impl HaikuWindowHandle {
-    pub fn empty() -> Self {
+    /// Create a new handle to a window.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use core::ptr::NonNull;
+    /// # use raw_window_handle::HaikuWindowHandle;
+    /// # type BWindow = ();
+    /// #
+    /// let b_window: NonNull<BWindow>;
+    /// # b_window = NonNull::from(&());
+    /// let mut handle = HaikuWindowHandle::new(b_window.cast());
+    /// // Optionally set `b_direct_window`.
+    /// handle.b_direct_window = None;
+    /// ```
+    pub fn new(b_window: NonNull<c_void>) -> Self {
         Self {
-            b_window: ptr::null_mut(),
-            b_direct_window: ptr::null_mut(),
+            b_window,
+            b_direct_window: None,
         }
     }
 }

src/lib.rs

@@ -60,7 +60,7 @@ use core::fmt;
 ///
 /// # Safety
 ///
-/// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the
+/// Users can safely assume that pointers and non-zero fields are valid, and it is up to the
 /// 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
@@ -205,7 +205,7 @@ pub enum RawWindowHandle {
 ///
 /// # Safety
 ///
-/// Users can safely assume that non-`null`/`0` fields are valid handles, and it is up to the
+/// Users can safely assume that pointers and non-zero fields are valid, and it is up to the
 /// 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

src/redox.rs

@@ -1,43 +1,52 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw display handle for the Redox operating system.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::OrbitalDisplayHandle;
-/// let mut display_handle = OrbitalDisplayHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct OrbitalDisplayHandle;
+pub struct OrbitalDisplayHandle {}
 
 impl OrbitalDisplayHandle {
-    pub fn empty() -> Self {
+    /// Create a new empty display handle.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::OrbitalDisplayHandle;
+    /// let handle = OrbitalDisplayHandle::new();
+    /// ```
+    pub fn new() -> Self {
         Self {}
     }
 }
 
 /// Raw window handle for the Redox operating system.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::OrbitalWindowHandle;
-/// let mut window_handle = OrbitalWindowHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct OrbitalWindowHandle {
     /// A pointer to an orbclient window.
-    pub window: *mut c_void,
+    // TODO(madsmtm): I think this is a file descriptor, so perhaps it should
+    // actually use `std::os::fd::RawFd`, or some sort of integer instead?
+    pub window: NonNull<c_void>,
 }
 
 impl OrbitalWindowHandle {
-    pub fn empty() -> Self {
-        Self {
-            window: ptr::null_mut(),
-        }
+    /// Create a new handle to a window.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use core::ptr::NonNull;
+    /// # use raw_window_handle::OrbitalWindowHandle;
+    /// # type Window = ();
+    /// #
+    /// let window: NonNull<Window>;
+    /// # window = NonNull::from(&());
+    /// let mut handle = OrbitalWindowHandle::new(window.cast());
+    /// ```
+    pub fn new(window: NonNull<c_void>) -> Self {
+        Self { window }
     }
 }

src/uikit.rs

@@ -1,46 +1,57 @@
 use core::ffi::c_void;
-use core::ptr;
+use core::ptr::NonNull;
 
 /// Raw display handle for UIKit.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::UiKitDisplayHandle;
-/// let mut display_handle = UiKitDisplayHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct UiKitDisplayHandle;
+pub struct UiKitDisplayHandle {}
 
 impl UiKitDisplayHandle {
-    pub fn empty() -> Self {
+    /// Create a new empty display handle.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::UiKitDisplayHandle;
+    /// let handle = UiKitDisplayHandle::new();
+    /// ```
+    pub fn new() -> Self {
         Self {}
     }
 }
 
 /// Raw window handle for UIKit.
-///
-/// ## Construction
-/// ```
-/// # use raw_window_handle::UiKitWindowHandle;
-/// let mut window_handle = UiKitWindowHandle::empty();
-/// /* set fields */
-/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct UiKitWindowHandle {
     /// A pointer to an `UIView` object.
-    pub ui_view: *mut c_void,
+    pub ui_view: NonNull<c_void>,
     /// A pointer to an `UIViewController` object, if the view has one.
-    pub ui_view_controller: *mut c_void,
+    pub ui_view_controller: Option<NonNull<c_void>>,
 }
 
 impl UiKitWindowHandle {
-    pub fn empty() -> Self {
+    /// Create a new handle to a view.
+    ///
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use core::ptr::NonNull;
+    /// # use raw_window_handle::UiKitWindowHandle;
+    /// # type UIView = ();
+    /// #
+    /// let view: &UIView;
+    /// # view = &();
+    /// let mut handle = UiKitWindowHandle::new(NonNull::from(view).cast());
+    /// // Optionally set the view controller.
+    /// handle.ui_view_controller = None;
+    /// ```
+    pub fn new(ui_view: NonNull<c_void>) -> Self {
         Self {
-            ui_view: ptr::null_mut(),
-            ui_view_controller: ptr::null_mut(),
+            ui_view,
+            ui_view_controller: None,
         }
     }
 }