| //! Less used details of `CxxVector` are exposed in this module. `CxxVector` |
| //! itself is exposed at the crate root. |
| |
| use crate::extern_type::ExternType; |
| use crate::kind::Trivial; |
| use crate::string::CxxString; |
| use crate::unique_ptr::UniquePtr; |
| use core::ffi::c_void; |
| use core::fmt::{self, Debug}; |
| use core::iter::FusedIterator; |
| use core::marker::{PhantomData, PhantomPinned}; |
| use core::mem::{self, ManuallyDrop, MaybeUninit}; |
| use core::pin::Pin; |
| use core::slice; |
| |
| /// Binding to C++ `std::vector<T, std::allocator<T>>`. |
| /// |
| /// # Invariants |
| /// |
| /// As an invariant of this API and the static analysis of the cxx::bridge |
| /// macro, in Rust code we can never obtain a `CxxVector` by value. Instead in |
| /// Rust code we will only ever look at a vector behind a reference or smart |
| /// pointer, as in `&CxxVector<T>` or `UniquePtr<CxxVector<T>>`. |
| #[repr(C, packed)] |
| pub struct CxxVector<T> { |
| // A thing, because repr(C) structs are not allowed to consist exclusively |
| // of PhantomData fields. |
| _void: [c_void; 0], |
| // The conceptual vector elements to ensure that autotraits are propagated |
| // correctly, e.g. CxxVector is UnwindSafe iff T is. |
| _elements: PhantomData<[T]>, |
| // Prevent unpin operation from Pin<&mut CxxVector<T>> to &mut CxxVector<T>. |
| _pinned: PhantomData<PhantomPinned>, |
| } |
| |
| impl<T> CxxVector<T> |
| where |
| T: VectorElement, |
| { |
| /// Constructs a new heap allocated vector, wrapped by UniquePtr. |
| /// |
| /// The C++ vector is default constructed. |
| pub fn new() -> UniquePtr<Self> { |
| unsafe { UniquePtr::from_raw(T::__vector_new()) } |
| } |
| |
| /// Returns the number of elements in the vector. |
| /// |
| /// Matches the behavior of C++ [std::vector\<T\>::size][size]. |
| /// |
| /// [size]: https://en.cppreference.com/w/cpp/container/vector/size |
| pub fn len(&self) -> usize { |
| T::__vector_size(self) |
| } |
| |
| /// Returns true if the vector contains no elements. |
| /// |
| /// Matches the behavior of C++ [std::vector\<T\>::empty][empty]. |
| /// |
| /// [empty]: https://en.cppreference.com/w/cpp/container/vector/empty |
| pub fn is_empty(&self) -> bool { |
| self.len() == 0 |
| } |
| |
| /// Returns a reference to an element at the given position, or `None` if |
| /// out of bounds. |
| pub fn get(&self, pos: usize) -> Option<&T> { |
| if pos < self.len() { |
| Some(unsafe { self.get_unchecked(pos) }) |
| } else { |
| None |
| } |
| } |
| |
| /// Returns a pinned mutable reference to an element at the given position, |
| /// or `None` if out of bounds. |
| pub fn index_mut(self: Pin<&mut Self>, pos: usize) -> Option<Pin<&mut T>> { |
| if pos < self.len() { |
| Some(unsafe { self.index_unchecked_mut(pos) }) |
| } else { |
| None |
| } |
| } |
| |
| /// Returns a reference to an element without doing bounds checking. |
| /// |
| /// This is generally not recommended, use with caution! Calling this method |
| /// with an out-of-bounds index is undefined behavior even if the resulting |
| /// reference is not used. |
| /// |
| /// Matches the behavior of C++ |
| /// [std::vector\<T\>::operator\[\] const][operator_at]. |
| /// |
| /// [operator_at]: https://en.cppreference.com/w/cpp/container/vector/operator_at |
| pub unsafe fn get_unchecked(&self, pos: usize) -> &T { |
| let this = self as *const CxxVector<T> as *mut CxxVector<T>; |
| unsafe { |
| let ptr = T::__get_unchecked(this, pos) as *const T; |
| &*ptr |
| } |
| } |
| |
| /// Returns a pinned mutable reference to an element without doing bounds |
| /// checking. |
| /// |
| /// This is generally not recommended, use with caution! Calling this method |
| /// with an out-of-bounds index is undefined behavior even if the resulting |
| /// reference is not used. |
| /// |
| /// Matches the behavior of C++ |
| /// [std::vector\<T\>::operator\[\]][operator_at]. |
| /// |
| /// [operator_at]: https://en.cppreference.com/w/cpp/container/vector/operator_at |
| pub unsafe fn index_unchecked_mut(self: Pin<&mut Self>, pos: usize) -> Pin<&mut T> { |
| unsafe { |
| let ptr = T::__get_unchecked(self.get_unchecked_mut(), pos); |
| Pin::new_unchecked(&mut *ptr) |
| } |
| } |
| |
| /// Returns a slice to the underlying contiguous array of elements. |
| pub fn as_slice(&self) -> &[T] |
| where |
| T: ExternType<Kind = Trivial>, |
| { |
| let len = self.len(); |
| if len == 0 { |
| // The slice::from_raw_parts in the other branch requires a nonnull |
| // and properly aligned data ptr. C++ standard does not guarantee |
| // that data() on a vector with size 0 would return a nonnull |
| // pointer or sufficiently aligned pointer, so using it would be |
| // undefined behavior. Create our own empty slice in Rust instead |
| // which upholds the invariants. |
| &[] |
| } else { |
| let this = self as *const CxxVector<T> as *mut CxxVector<T>; |
| let ptr = unsafe { T::__get_unchecked(this, 0) }; |
| unsafe { slice::from_raw_parts(ptr, len) } |
| } |
| } |
| |
| /// Returns a slice to the underlying contiguous array of elements by |
| /// mutable reference. |
| pub fn as_mut_slice(self: Pin<&mut Self>) -> &mut [T] |
| where |
| T: ExternType<Kind = Trivial>, |
| { |
| let len = self.len(); |
| if len == 0 { |
| &mut [] |
| } else { |
| let ptr = unsafe { T::__get_unchecked(self.get_unchecked_mut(), 0) }; |
| unsafe { slice::from_raw_parts_mut(ptr, len) } |
| } |
| } |
| |
| /// Returns an iterator over elements of type `&T`. |
| pub fn iter(&self) -> Iter<T> { |
| Iter { v: self, index: 0 } |
| } |
| |
| /// Returns an iterator over elements of type `Pin<&mut T>`. |
| pub fn iter_mut(self: Pin<&mut Self>) -> IterMut<T> { |
| IterMut { v: self, index: 0 } |
| } |
| |
| /// Appends an element to the back of the vector. |
| /// |
| /// Matches the behavior of C++ [std::vector\<T\>::push_back][push_back]. |
| /// |
| /// [push_back]: https://en.cppreference.com/w/cpp/container/vector/push_back |
| pub fn push(self: Pin<&mut Self>, value: T) |
| where |
| T: ExternType<Kind = Trivial>, |
| { |
| let mut value = ManuallyDrop::new(value); |
| unsafe { |
| // C++ calls move constructor followed by destructor on `value`. |
| T::__push_back(self, &mut value); |
| } |
| } |
| |
| /// Removes the last element from a vector and returns it, or `None` if the |
| /// vector is empty. |
| pub fn pop(self: Pin<&mut Self>) -> Option<T> |
| where |
| T: ExternType<Kind = Trivial>, |
| { |
| if self.is_empty() { |
| None |
| } else { |
| let mut value = MaybeUninit::uninit(); |
| Some(unsafe { |
| T::__pop_back(self, &mut value); |
| value.assume_init() |
| }) |
| } |
| } |
| } |
| |
| /// Iterator over elements of a `CxxVector` by shared reference. |
| /// |
| /// The iterator element type is `&'a T`. |
| pub struct Iter<'a, T> { |
| v: &'a CxxVector<T>, |
| index: usize, |
| } |
| |
| impl<'a, T> IntoIterator for &'a CxxVector<T> |
| where |
| T: VectorElement, |
| { |
| type Item = &'a T; |
| type IntoIter = Iter<'a, T>; |
| |
| fn into_iter(self) -> Self::IntoIter { |
| self.iter() |
| } |
| } |
| |
| impl<'a, T> Iterator for Iter<'a, T> |
| where |
| T: VectorElement, |
| { |
| type Item = &'a T; |
| |
| fn next(&mut self) -> Option<Self::Item> { |
| let next = self.v.get(self.index)?; |
| self.index += 1; |
| Some(next) |
| } |
| |
| fn size_hint(&self) -> (usize, Option<usize>) { |
| let len = self.len(); |
| (len, Some(len)) |
| } |
| } |
| |
| impl<'a, T> ExactSizeIterator for Iter<'a, T> |
| where |
| T: VectorElement, |
| { |
| fn len(&self) -> usize { |
| self.v.len() - self.index |
| } |
| } |
| |
| impl<'a, T> FusedIterator for Iter<'a, T> where T: VectorElement {} |
| |
| /// Iterator over elements of a `CxxVector` by pinned mutable reference. |
| /// |
| /// The iterator element type is `Pin<&'a mut T>`. |
| pub struct IterMut<'a, T> { |
| v: Pin<&'a mut CxxVector<T>>, |
| index: usize, |
| } |
| |
| impl<'a, T> IntoIterator for Pin<&'a mut CxxVector<T>> |
| where |
| T: VectorElement, |
| { |
| type Item = Pin<&'a mut T>; |
| type IntoIter = IterMut<'a, T>; |
| |
| fn into_iter(self) -> Self::IntoIter { |
| self.iter_mut() |
| } |
| } |
| |
| impl<'a, T> Iterator for IterMut<'a, T> |
| where |
| T: VectorElement, |
| { |
| type Item = Pin<&'a mut T>; |
| |
| fn next(&mut self) -> Option<Self::Item> { |
| let next = self.v.as_mut().index_mut(self.index)?; |
| self.index += 1; |
| // Extend lifetime to allow simultaneous holding of nonoverlapping |
| // elements, analogous to slice::split_first_mut. |
| unsafe { |
| let ptr = Pin::into_inner_unchecked(next) as *mut T; |
| Some(Pin::new_unchecked(&mut *ptr)) |
| } |
| } |
| |
| fn size_hint(&self) -> (usize, Option<usize>) { |
| let len = self.len(); |
| (len, Some(len)) |
| } |
| } |
| |
| impl<'a, T> ExactSizeIterator for IterMut<'a, T> |
| where |
| T: VectorElement, |
| { |
| fn len(&self) -> usize { |
| self.v.len() - self.index |
| } |
| } |
| |
| impl<'a, T> FusedIterator for IterMut<'a, T> where T: VectorElement {} |
| |
| impl<T> Debug for CxxVector<T> |
| where |
| T: VectorElement + Debug, |
| { |
| fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { |
| formatter.debug_list().entries(self).finish() |
| } |
| } |
| |
| /// Trait bound for types which may be used as the `T` inside of a |
| /// `CxxVector<T>` in generic code. |
| /// |
| /// This trait has no publicly callable or implementable methods. Implementing |
| /// it outside of the CXX codebase requires using [explicit shim trait impls], |
| /// adding the line `impl CxxVector<MyType> {}` in the same `cxx::bridge` that |
| /// defines `MyType`. |
| /// |
| /// # Example |
| /// |
| /// A bound `T: VectorElement` may be necessary when manipulating [`CxxVector`] |
| /// in generic code. |
| /// |
| /// ``` |
| /// use cxx::vector::{CxxVector, VectorElement}; |
| /// use std::fmt::Display; |
| /// |
| /// pub fn take_generic_vector<T>(vector: &CxxVector<T>) |
| /// where |
| /// T: VectorElement + Display, |
| /// { |
| /// println!("the vector elements are:"); |
| /// for element in vector { |
| /// println!(" • {}", element); |
| /// } |
| /// } |
| /// ``` |
| /// |
| /// Writing the same generic function without a `VectorElement` trait bound |
| /// would not compile. |
| /// |
| /// [explicit shim trait impls]: https://cxx.rs/extern-c++.html#explicit-shim-trait-impls |
| pub unsafe trait VectorElement: Sized { |
| #[doc(hidden)] |
| fn __typename(f: &mut fmt::Formatter) -> fmt::Result; |
| #[doc(hidden)] |
| fn __vector_new() -> *mut CxxVector<Self>; |
| #[doc(hidden)] |
| fn __vector_size(v: &CxxVector<Self>) -> usize; |
| #[doc(hidden)] |
| unsafe fn __get_unchecked(v: *mut CxxVector<Self>, pos: usize) -> *mut Self; |
| #[doc(hidden)] |
| unsafe fn __push_back(v: Pin<&mut CxxVector<Self>>, value: &mut ManuallyDrop<Self>) { |
| // Opaque C type vector elements do not get this method because they can |
| // never exist by value on the Rust side of the bridge. |
| let _ = v; |
| let _ = value; |
| unreachable!() |
| } |
| #[doc(hidden)] |
| unsafe fn __pop_back(v: Pin<&mut CxxVector<Self>>, out: &mut MaybeUninit<Self>) { |
| // Opaque C type vector elements do not get this method because they can |
| // never exist by value on the Rust side of the bridge. |
| let _ = v; |
| let _ = out; |
| unreachable!() |
| } |
| #[doc(hidden)] |
| fn __unique_ptr_null() -> MaybeUninit<*mut c_void>; |
| #[doc(hidden)] |
| unsafe fn __unique_ptr_raw(raw: *mut CxxVector<Self>) -> MaybeUninit<*mut c_void>; |
| #[doc(hidden)] |
| unsafe fn __unique_ptr_get(repr: MaybeUninit<*mut c_void>) -> *const CxxVector<Self>; |
| #[doc(hidden)] |
| unsafe fn __unique_ptr_release(repr: MaybeUninit<*mut c_void>) -> *mut CxxVector<Self>; |
| #[doc(hidden)] |
| unsafe fn __unique_ptr_drop(repr: MaybeUninit<*mut c_void>); |
| } |
| |
| macro_rules! vector_element_by_value_methods { |
| (opaque, $segment:expr, $ty:ty) => {}; |
| (trivial, $segment:expr, $ty:ty) => { |
| unsafe fn __push_back(v: Pin<&mut CxxVector<$ty>>, value: &mut ManuallyDrop<$ty>) { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$std$vector$", $segment, "$push_back")] |
| fn __push_back(_: Pin<&mut CxxVector<$ty>>, _: &mut ManuallyDrop<$ty>); |
| } |
| unsafe { __push_back(v, value) } |
| } |
| unsafe fn __pop_back(v: Pin<&mut CxxVector<$ty>>, out: &mut MaybeUninit<$ty>) { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$std$vector$", $segment, "$pop_back")] |
| fn __pop_back(_: Pin<&mut CxxVector<$ty>>, _: &mut MaybeUninit<$ty>); |
| } |
| unsafe { __pop_back(v, out) } |
| } |
| }; |
| } |
| |
| macro_rules! impl_vector_element { |
| ($kind:ident, $segment:expr, $name:expr, $ty:ty) => { |
| const_assert_eq!(0, mem::size_of::<CxxVector<$ty>>()); |
| const_assert_eq!(1, mem::align_of::<CxxVector<$ty>>()); |
| |
| unsafe impl VectorElement for $ty { |
| fn __typename(f: &mut fmt::Formatter) -> fmt::Result { |
| f.write_str($name) |
| } |
| fn __vector_new() -> *mut CxxVector<Self> { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$std$vector$", $segment, "$new")] |
| fn __vector_new() -> *mut CxxVector<$ty>; |
| } |
| unsafe { __vector_new() } |
| } |
| fn __vector_size(v: &CxxVector<$ty>) -> usize { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$std$vector$", $segment, "$size")] |
| fn __vector_size(_: &CxxVector<$ty>) -> usize; |
| } |
| unsafe { __vector_size(v) } |
| } |
| unsafe fn __get_unchecked(v: *mut CxxVector<$ty>, pos: usize) -> *mut $ty { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$std$vector$", $segment, "$get_unchecked")] |
| fn __get_unchecked(_: *mut CxxVector<$ty>, _: usize) -> *mut $ty; |
| } |
| unsafe { __get_unchecked(v, pos) } |
| } |
| vector_element_by_value_methods!($kind, $segment, $ty); |
| fn __unique_ptr_null() -> MaybeUninit<*mut c_void> { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$unique_ptr$std$vector$", $segment, "$null")] |
| fn __unique_ptr_null(this: *mut MaybeUninit<*mut c_void>); |
| } |
| let mut repr = MaybeUninit::uninit(); |
| unsafe { __unique_ptr_null(&mut repr) } |
| repr |
| } |
| unsafe fn __unique_ptr_raw(raw: *mut CxxVector<Self>) -> MaybeUninit<*mut c_void> { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$unique_ptr$std$vector$", $segment, "$raw")] |
| fn __unique_ptr_raw(this: *mut MaybeUninit<*mut c_void>, raw: *mut CxxVector<$ty>); |
| } |
| let mut repr = MaybeUninit::uninit(); |
| unsafe { __unique_ptr_raw(&mut repr, raw) } |
| repr |
| } |
| unsafe fn __unique_ptr_get(repr: MaybeUninit<*mut c_void>) -> *const CxxVector<Self> { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$unique_ptr$std$vector$", $segment, "$get")] |
| fn __unique_ptr_get(this: *const MaybeUninit<*mut c_void>) -> *const CxxVector<$ty>; |
| } |
| unsafe { __unique_ptr_get(&repr) } |
| } |
| unsafe fn __unique_ptr_release(mut repr: MaybeUninit<*mut c_void>) -> *mut CxxVector<Self> { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$unique_ptr$std$vector$", $segment, "$release")] |
| fn __unique_ptr_release(this: *mut MaybeUninit<*mut c_void>) -> *mut CxxVector<$ty>; |
| } |
| unsafe { __unique_ptr_release(&mut repr) } |
| } |
| unsafe fn __unique_ptr_drop(mut repr: MaybeUninit<*mut c_void>) { |
| extern "C" { |
| #[link_name = concat!("cxxbridge1$unique_ptr$std$vector$", $segment, "$drop")] |
| fn __unique_ptr_drop(this: *mut MaybeUninit<*mut c_void>); |
| } |
| unsafe { __unique_ptr_drop(&mut repr) } |
| } |
| } |
| }; |
| } |
| |
| macro_rules! impl_vector_element_for_primitive { |
| ($ty:ident) => { |
| impl_vector_element!(trivial, stringify!($ty), stringify!($ty), $ty); |
| }; |
| } |
| |
| impl_vector_element_for_primitive!(u8); |
| impl_vector_element_for_primitive!(u16); |
| impl_vector_element_for_primitive!(u32); |
| impl_vector_element_for_primitive!(u64); |
| impl_vector_element_for_primitive!(usize); |
| impl_vector_element_for_primitive!(i8); |
| impl_vector_element_for_primitive!(i16); |
| impl_vector_element_for_primitive!(i32); |
| impl_vector_element_for_primitive!(i64); |
| impl_vector_element_for_primitive!(isize); |
| impl_vector_element_for_primitive!(f32); |
| impl_vector_element_for_primitive!(f64); |
| |
| impl_vector_element!(opaque, "string", "CxxString", CxxString); |
