feat: Safe constructors for some display handles

For display handles which are empty, it is safe to create them without
any borrowing considerations. This may be useful to windowing
frameworks with entirely safe code.

Signed-off-by: John Nunley <[email protected]>

src/android.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for Android.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl AndroidDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create an Android-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::android();
+    /// do_something(handle);
+    /// ```
+    pub fn android() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(AndroidDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for Android NDK.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/appkit.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for AppKit.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl AppKitDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create an AppKit-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::appkit();
+    /// do_something(handle);
+    /// ```
+    pub fn appkit() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(AppKitDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for AppKit.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/haiku.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for Haiku.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl HaikuDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create an Haiku-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::haiku();
+    /// do_something(handle);
+    /// ```
+    pub fn haiku() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(HaikuDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for Haiku.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/redox.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for the Redox operating system.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl OrbitalDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create an Orbital-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::orbital();
+    /// do_something(handle);
+    /// ```
+    pub fn orbital() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(OrbitalDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for the Redox operating system.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/uikit.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for UIKit.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl UiKitDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create a UiKit-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::uikit();
+    /// do_something(handle);
+    /// ```
+    pub fn uikit() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(UiKitDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for UIKit.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/web.rs

@@ -1,6 +1,8 @@
 use core::ffi::c_void;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for the Web.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -21,6 +23,26 @@ impl WebDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create a Web-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::web();
+    /// do_something(handle);
+    /// ```
+    pub fn web() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(WebDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for the Web.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

src/windows.rs

@@ -2,6 +2,8 @@ use core::ffi::c_void;
 use core::num::NonZeroIsize;
 use core::ptr::NonNull;
 
+use super::DisplayHandle;
+
 /// Raw display handle for Windows.
 ///
 /// It can be used regardless of Windows window backend.
@@ -24,6 +26,26 @@ impl WindowsDisplayHandle {
     }
 }
 
+impl DisplayHandle<'static> {
+    /// Create a Windows-based display handle.
+    ///
+    /// As no data is borrowed by this handle, it is completely safe to create. This function
+    /// may be useful to windowing framework implementations that want to avoid unsafe code.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use raw_window_handle::{DisplayHandle, HasDisplayHandle};
+    /// # fn do_something(rwh: impl HasDisplayHandle) { let _ = rwh; }
+    /// let handle = DisplayHandle::windows();
+    /// do_something(handle);
+    /// ```
+    pub fn windows() -> Self {
+        // SAFETY: No data is borrowed.
+        unsafe { Self::borrow_raw(WindowsDisplayHandle::new().into()) }
+    }
+}
+
 /// Raw window handle for Win32.
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]