Add glib::StrVRef

This type represents a borrowed reference to a `NULL`-terminated array
of `NULL`-terminated UTF-8 strings.

Signed-off-by: fbrouille <[email protected]>

Author: fbrouille

glib/src/collections/mod.rs

@@ -13,4 +13,4 @@ pub mod slist;
 pub use slist::SList;
 
 pub mod strv;
-pub use strv::StrV;
+pub use strv::{StrV, StrVRef};

glib/src/collections/strv.rs

@@ -114,12 +114,26 @@ impl std::borrow::Borrow<[GStringPtr]> for StrV {
     }
 }
 
+impl AsRef<StrVRef> for StrV {
+    #[inline]
+    fn as_ref(&self) -> &StrVRef {
+        self.into()
+    }
+}
+
+impl std::borrow::Borrow<StrVRef> for StrV {
+    #[inline]
+    fn borrow(&self) -> &StrVRef {
+        self.into()
+    }
+}
+
 impl std::ops::Deref for StrV {
-    type Target = [GStringPtr];
+    type Target = StrVRef;
 
     #[inline]
-    fn deref(&self) -> &[GStringPtr] {
-        self.as_slice()
+    fn deref(&self) -> &StrVRef {
+        self.into()
     }
 }
 
@@ -1364,6 +1378,208 @@ impl<const N: usize> IntoStrV for [&'_ String; N] {
     }
 }
 
+// rustdoc-stripper-ignore-next
+/// Representation of a borrowed `NULL`-terminated C array of `NULL`-terminated UTF-8 strings.
+///
+/// It can be constructed safely from a `&StrV` and unsafely from a pointer to a C array.
+/// This type is very similar to `[GStringPtr]`, but with one added constraint: the underlying C array must be `NULL`-terminated.
+#[repr(transparent)]
+pub struct StrVRef {
+    inner: [GStringPtr],
+}
+
+impl StrVRef {
+    // rustdoc-stripper-ignore-next
+    /// Borrows a C array.
+    /// # Safety
+    ///
+    /// The provided pointer **must** be `NULL`-terminated. It is undefined behavior to
+    /// pass a pointer that does not uphold this condition.
+    #[inline]
+    pub unsafe fn from_glib_borrow<'a>(ptr: *const *const c_char) -> &'a StrVRef {
+        let slice = StrV::from_glib_borrow(ptr);
+        &*(slice as *const [GStringPtr] as *const StrVRef)
+    }
+
+    // rustdoc-stripper-ignore-next
+    /// Borrows a C array.
+    /// # Safety
+    ///
+    /// The provided pointer **must** be `NULL`-terminated. It is undefined behavior to
+    /// pass a pointer that does not uphold this condition.
+    #[inline]
+    pub unsafe fn from_glib_borrow_num<'a>(ptr: *const *const c_char, len: usize) -> &'a StrVRef {
+        let slice = StrV::from_glib_borrow_num(ptr, len);
+        &*(slice as *const [GStringPtr] as *const StrVRef)
+    }
+
+    // rustdoc-stripper-ignore-next
+    /// Returns the underlying pointer.
+    ///
+    /// This is guaranteed to be nul-terminated.
+    #[inline]
+    pub const fn as_ptr(&self) -> *const *const c_char {
+        self.inner.as_ptr() as *const *const _
+    }
+}
+
+impl fmt::Debug for StrVRef {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.inner.fmt(f)
+    }
+}
+
+unsafe impl Send for StrVRef {}
+
+unsafe impl Sync for StrVRef {}
+
+impl PartialEq for StrVRef {
+    #[inline]
+    fn eq(&self, other: &Self) -> bool {
+        self.inner == other.inner
+    }
+}
+
+impl Eq for StrVRef {}
+
+impl PartialOrd for StrVRef {
+    #[inline]
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for StrVRef {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.inner.cmp(&other.inner)
+    }
+}
+
+impl std::hash::Hash for StrVRef {
+    #[inline]
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.inner.hash(state)
+    }
+}
+
+impl PartialEq<[&'_ str]> for StrVRef {
+    fn eq(&self, other: &[&'_ str]) -> bool {
+        for (a, b) in Iterator::zip(self.iter(), other.iter()) {
+            if a != b {
+                return false;
+            }
+        }
+
+        true
+    }
+}
+
+impl PartialEq<StrVRef> for [&'_ str] {
+    #[inline]
+    fn eq(&self, other: &StrVRef) -> bool {
+        other.eq(self)
+    }
+}
+
+impl Default for &StrVRef {
+    #[inline]
+    fn default() -> Self {
+        const SLICE: &[*const c_char] = &[ptr::null()];
+        // SAFETY: `SLICE` is indeed a valid nul-terminated array.
+        unsafe { StrVRef::from_glib_borrow(SLICE.as_ptr()) }
+    }
+}
+
+impl std::ops::Deref for StrVRef {
+    type Target = [GStringPtr];
+
+    #[inline]
+    fn deref(&self) -> &[GStringPtr] {
+        &self.inner
+    }
+}
+
+impl<'a> std::iter::IntoIterator for &'a StrVRef {
+    type Item = &'a GStringPtr;
+    type IntoIter = std::slice::Iter<'a, GStringPtr>;
+
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter {
+        self.inner.iter()
+    }
+}
+
+impl<'a> From<&'a StrV> for &'a StrVRef {
+    fn from(value: &'a StrV) -> Self {
+        let slice = value.as_slice();
+        // Safety: `&StrV` is a null-terminated C array of nul-terminated UTF-8 strings,
+        // therefore `&StrV::as_slice()` return a a null-terminated slice of nul-terminated UTF-8 strings,
+        // thus it is safe to convert it to `&CStr`.
+        unsafe { &*(slice as *const [GStringPtr] as *const StrVRef) }
+    }
+}
+
+impl FromGlibContainer<*mut c_char, *const *const c_char> for &StrVRef {
+    unsafe fn from_glib_none_num(ptr: *const *const c_char, num: usize) -> Self {
+        StrVRef::from_glib_borrow_num(ptr, num)
+    }
+
+    unsafe fn from_glib_container_num(_ptr: *const *const c_char, _num: usize) -> Self {
+        unimplemented!();
+    }
+
+    unsafe fn from_glib_full_num(_ptr: *const *const c_char, _num: usize) -> Self {
+        unimplemented!();
+    }
+}
+
+impl FromGlibPtrContainer<*mut c_char, *const *const c_char> for &StrVRef {
+    #[inline]
+    unsafe fn from_glib_none(ptr: *const *const c_char) -> Self {
+        StrVRef::from_glib_borrow(ptr)
+    }
+
+    unsafe fn from_glib_container(_ptr: *const *const c_char) -> Self {
+        unimplemented!();
+    }
+
+    unsafe fn from_glib_full(_ptr: *const *const c_char) -> Self {
+        unimplemented!();
+    }
+}
+
+impl<'a> ToGlibPtr<'a, *const *const c_char> for StrVRef {
+    type Storage = PhantomData<&'a Self>;
+
+    #[inline]
+    fn to_glib_none(&'a self) -> Stash<'a, *const *const c_char, Self> {
+        Stash(self.as_ptr(), PhantomData)
+    }
+}
+
+impl IntoGlibPtr<*const *const c_char> for &StrVRef {
+    #[inline]
+    fn into_glib_ptr(self) -> *const *const c_char {
+        self.as_ptr()
+    }
+}
+
+impl StaticType for StrVRef {
+    #[inline]
+    fn static_type() -> crate::Type {
+        <Vec<String>>::static_type()
+    }
+}
+
+unsafe impl<'a> crate::value::FromValue<'a> for &'a StrVRef {
+    type Checker = crate::value::GenericValueTypeChecker<Self>;
+
+    unsafe fn from_value(value: &'a crate::value::Value) -> Self {
+        let ptr = gobject_ffi::g_value_get_boxed(value.to_glib_none().0) as *const *const c_char;
+        StrVRef::from_glib_borrow(ptr)
+    }
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

glib/src/lib.rs

@@ -120,7 +120,7 @@ mod exit_code;
 pub use exit_code::{ExitCode, InvalidExitCode};
 
 pub mod collections;
-pub use collections::{List, PtrSlice, SList, Slice, StrV};
+pub use collections::{List, PtrSlice, SList, Slice, StrV, StrVRef};
 
 pub use self::auto::*;
 #[allow(clippy::too_many_arguments)]