Improve documentation for OpenCVType and rename opencv_to_extern to opencv_as_extern
MODIFY
binding-generator/src/type_ref.rs
binding-generator/src/type_ref.rs
@@ -1373,16 +1373,16 @@ impl<'tu> TypeRef<'tu> {
return if self.is_output() {
format!("&mut {name}_via", name=name)
} else if self.is_const() || is_const {
- format!("{name}.opencv_to_extern()", name=name)
+ format!("{name}.opencv_as_extern()", name=name)
} else {
- format!("{name}.opencv_to_extern_mut()", name=name)
+ format!("{name}.opencv_as_extern_mut()", name=name)
}
}
if self.as_reference().map_or(false, |inner| (inner.as_simple_class().is_some() || inner.is_enum()) && (inner.is_const() || is_const)) {
return format!("&{name}", name=name);
}
if self.as_simple_class().is_some() {
- return format!("{name}.opencv_to_extern()", name=name);
+ return format!("{name}.opencv_as_extern()", name=name);
}
if self.is_by_ptr() {
let typ = self.source();

MODIFY
src/manual/core.rs
src/manual/core.rs
@@ -46,8 +46,8 @@ macro_rules! opencv_type_simple_generic {
type ExternSend = *const Self;
type ExternSendMut = *mut Self;
- #[inline] fn opencv_to_extern(&self) -> Self::ExternSend { self }
- #[inline] fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut { self }
+ #[inline] fn opencv_as_extern(&self) -> Self::ExternSend { self }
+ #[inline] fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut { self }
}
};
}

MODIFY
src/manual/core/mat/mat_.rs
src/manual/core/mat/mat_.rs
@@ -141,12 +141,12 @@ impl<T> OpenCVTypeExternContainer for Mat_<T> {
type ExternSendMut = *mut c_void;
#[inline]
- fn opencv_to_extern(&self) -> Self::ExternSend {
+ fn opencv_as_extern(&self) -> Self::ExternSend {
self.as_raw()
}
#[inline]
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut {
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut {
self.as_raw_mut()
}
}

MODIFY
src/manual/core/matx.rs
src/manual/core/matx.rs
@@ -158,8 +158,8 @@ impl<T: ValidMatxType, A: SizedArray<T>> OpenCVTypeExternContainer for Matx<T, A
type ExternSend = *const Self;
type ExternSendMut = *mut Self;
- #[inline] fn opencv_to_extern(&self) -> Self::ExternSend { self }
- #[inline] fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut { self }
+ #[inline] fn opencv_as_extern(&self) -> Self::ExternSend { self }
+ #[inline] fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut { self }
}
impl<T: ValidMatxType, A: SizedArray<T>> std::cmp::PartialEq for Matx<T, A> {

MODIFY
src/manual/core/ptr.rs
src/manual/core/ptr.rs
@@ -85,12 +85,12 @@ impl<T: ?Sized> OpenCVTypeExternContainer for Ptr<T> where Self: PtrExtern {
type ExternSendMut = *mut c_void;
#[inline]
- fn opencv_to_extern(&self) -> Self::ExternSend {
+ fn opencv_as_extern(&self) -> Self::ExternSend {
self.as_raw()
}
#[inline]
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut {
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut {
self.as_raw_mut()
}
}

MODIFY
src/manual/core/vector.rs
src/manual/core/vector.rs
@@ -222,14 +222,14 @@ impl<T: VectorElement> Vector<T> where Self: VectorExtern<T> {
/// Add new element
pub fn push(&mut self, val: <T as OpenCVType<'_>>::Arg) {
let val = val.opencv_into_extern_container_nofail();
- unsafe { self.extern_push(val.opencv_to_extern()) }
+ unsafe { self.extern_push(val.opencv_as_extern()) }
}
/// Insert a new element at the specified `index`
pub fn insert(&mut self, index: size_t, val: <T as OpenCVType<'_>>::Arg) -> Result<()> {
vector_index_check(index, self.len() + 1)?;
let val = val.opencv_into_extern_container()?;
- unsafe { self.extern_insert(index, val.opencv_to_extern()) }
+ unsafe { self.extern_insert(index, val.opencv_as_extern()) }
Ok(())
}
@@ -237,14 +237,14 @@ impl<T: VectorElement> Vector<T> where Self: VectorExtern<T> {
pub fn set(&mut self, index: size_t, val: <T as OpenCVType<'_>>::Arg) -> Result<()> {
vector_index_check(index, self.len())?;
let val = val.opencv_into_extern_container()?;
- unsafe { self.extern_set(index, val.opencv_to_extern()) }
+ unsafe { self.extern_set(index, val.opencv_as_extern()) }
Ok(())
}
/// Same as `set()` but without bounds checking
pub unsafe fn set_unchecked(&mut self, index: size_t, val: <T as OpenCVType<'_>>::Arg) {
let val = val.opencv_into_extern_container_nofail();
- self.extern_set(index, val.opencv_to_extern())
+ self.extern_set(index, val.opencv_as_extern())
}
/// Get element at the specified `index`

MODIFY
src/manual/types/abstract_ref.rs
src/manual/types/abstract_ref.rs
@@ -62,12 +62,12 @@ impl<T: ?Sized> OpenCVTypeExternContainer for AbstractRefMut<'_, T> {
type ExternSendMut = *mut c_void;
#[inline]
- fn opencv_to_extern(&self) -> Self::ExternSend {
+ fn opencv_as_extern(&self) -> Self::ExternSend {
self.as_raw()
}
#[inline]
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut {
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut {
self.as_raw_mut()
}
}

MODIFY
src/traits/boxed.rs
src/traits/boxed.rs
@@ -77,12 +77,12 @@ macro_rules! opencv_type_boxed {
type ExternSendMut = *mut std::ffi::c_void;
#[inline]
- fn opencv_to_extern(&self) -> Self::ExternSend {
+ fn opencv_as_extern(&self) -> Self::ExternSend {
self.as_raw()
}
#[inline]
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut {
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut {
self.as_raw_mut()
}
}

MODIFY
src/traits/opencv_type.rs
src/traits/opencv_type.rs
@@ -5,23 +5,55 @@ use std::{
use crate::Result;
+#[doc(hidden)]
+/// Common trait of all OpenCV related types, helps with generic handling of FFI marshalling
+///
+/// This trait is somewhat unnecessary complex because of the need of handling String, we need to be able to
+/// pass &str as argument to functions that await String and do necessary conversion through CString.
pub trait OpenCVType<'a>: Sized {
+ #[doc(hidden)]
+ /// Owned version of the type, e.g. String for &str, for most other types it's Self
type Owned: OpenCVType<'a>;
+ #[doc(hidden)]
+ /// Type when passed as argument to function, e.g. &str for String, for most other types it's either Self
+ /// or &Self
type Arg: OpenCVType<'a>;
- type ExternReceive; // return type when this type is returned from the C++ function
+ #[doc(hidden)]
+ /// Return type when this type is returned over the FFI boundary from the C++ function, Self for simple
+ /// types, *mut c_void for complex ones
+ type ExternReceive;
+ #[doc(hidden)]
+ /// Container to help marshall type over FFI boundary, e.g. CString for String or &str, for most other
+ /// types it's Self
type ExternContainer: OpenCVTypeExternContainer;
+ #[doc(hidden)]
+ /// Convert Self into external container with possible error result, it shouldn't panic
fn opencv_into_extern_container(self) -> Result<Self::ExternContainer>;
+ #[doc(hidden)]
+ /// Convert Self into external container in the nofail context, this can panic
fn opencv_into_extern_container_nofail(self) -> Self::ExternContainer;
+ #[doc(hidden)]
+ /// Construct the new Self::Owned from the data received from C++ function
unsafe fn opencv_from_extern(s: Self::ExternReceive) -> Self::Owned;
}
+#[doc(hidden)]
+/// Common trait for the type that is used to help marshall OpenCV related type over the FFI boundary
pub trait OpenCVTypeExternContainer: Sized {
+ #[doc(hidden)]
+ /// Type when constant Self is sent to C++ function, usually it's Self for simple types or *const c_void
+ /// for complex ones
type ExternSend;
+ #[doc(hidden)]
+ /// Type when mutable Self is sent to C++ function, usually it's Self for simple types or *mut c_void for
+ /// complex ones
type ExternSendMut;
- fn opencv_to_extern(&self) -> Self::ExternSend;
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut;
+ #[doc(hidden)]
+ fn opencv_as_extern(&self) -> Self::ExternSend;
+ #[doc(hidden)]
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut;
}
#[macro_export]
@@ -43,8 +75,8 @@ macro_rules! opencv_type_copy {
type ExternSend = Self;
type ExternSendMut = Self;
- #[inline] fn opencv_to_extern(&self) -> Self { *self }
- #[inline] fn opencv_to_extern_mut(&mut self) -> Self { *self }
+ #[inline] fn opencv_as_extern(&self) -> Self { *self }
+ #[inline] fn opencv_as_extern_mut(&mut self) -> Self { *self }
}
)+
};
@@ -75,8 +107,8 @@ macro_rules! opencv_type_simple {
type ExternSend = *const Self;
type ExternSendMut = *mut Self;
- #[inline] fn opencv_to_extern(&self) -> Self::ExternSend { self }
- #[inline] fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut { self }
+ #[inline] fn opencv_as_extern(&self) -> Self::ExternSend { self }
+ #[inline] fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut { self }
}
};
}
@@ -89,14 +121,14 @@ pub fn cstring_new_nofail(bytes: impl Into<Vec<u8>>) -> CString {
Err(e) => {
let nul_pos = e.nul_position();
let mut bytes = e.into_vec();
- bytes.drain(nul_pos + 1..);
+ bytes.drain(nul_pos..);
unsafe { CString::from_vec_unchecked(bytes) }
}
}
}
impl<'a> OpenCVType<'a> for String {
- type Owned = String;
+ type Owned = Self;
type Arg = &'a str;
type ExternReceive = *mut c_void;
type ExternContainer = CString;
@@ -144,12 +176,12 @@ impl OpenCVTypeExternContainer for CString {
type ExternSendMut = *mut c_char;
#[inline]
- fn opencv_to_extern(&self) -> Self::ExternSend {
+ fn opencv_as_extern(&self) -> Self::ExternSend {
self.as_ptr()
}
#[inline]
- fn opencv_to_extern_mut(&mut self) -> Self::ExternSendMut {
+ fn opencv_as_extern_mut(&mut self) -> Self::ExternSendMut {
self.as_ptr() as _ // fixme: use as_mut_ptr() when it's stabilized
}
}

Improve documentation for OpenCVType and rename opencv_to_extern to opencv_as_extern