diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 54 |
1 files changed, 54 insertions, 0 deletions
@@ -57,6 +57,7 @@ where 1 }; + /// Returns a new `MultiVec`. This function does not allocate any memory. pub const fn new() -> Self { Self { @@ -69,6 +70,12 @@ where } } + /// Pushes a item to the `MultiVec`. + /// + /// ## Note on performance + /// Pushing can be pretty slow. Since all of the field lists are stored in the same + /// allocation, when pushing and the `MultiVec` needs to grow, all lists except the + /// first has to be moved to new locations for them to not overlap. pub fn push(&mut self, item: ItemT) { if self.capacity != 0 { @@ -90,6 +97,7 @@ where self.length = 1; } + /// Returns a field of the item with the given index. pub fn get<FieldSel>( &self, index: usize, @@ -293,13 +301,58 @@ pub unsafe trait Item + DoubleEndedIterator + ExactSizeIterator; + /// The number of fields this item has. const FIELD_CNT: usize; + /// Returns a iterator of metadata of the fields of this item. fn iter_field_metadata() -> Self::FieldMetadataIter<'static>; + /// Drops a field of this item inplace. + /// + /// # Safety + /// Behavior is undefined if any of the following conditions are violated: + /// + /// * `field_index` must be a valid field index for this item. + /// * The value `field_ptr` points to must be valid for the type of the field with + /// index `field_index`. + /// * `field_ptr` must be [valid] for both reads and writes. + /// * `field_ptr` must be properly aligned, even if the field type has size 0. + /// * `field_ptr` must be nonnull, even if the field type has size 0. + /// * The value `field_ptr` points to must be valid for dropping, which may mean it + /// must uphold additional invariants. These invariants depend on the type of the + /// value being dropped. For instance, when dropping a Box, the box's pointer to the + /// heap must be valid. + /// * While `drop_field_inplace` is executing, the only way to access parts of + /// `field_ptr` is through the `&mut self` references supplied to the [`Drop::drop`] + /// methods that `drop_field_inplace` invokes. + /// + /// Additionally, if the field type is not [`Copy`], using the pointed-to value after + /// calling `drop_field_inplace` can cause undefined behavior. Note that `*field_ptr = + /// foo` counts as a use because it will cause the value to be dropped again. + /// + /// [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety unsafe fn drop_field_inplace(field_index: usize, field_ptr: *mut u8); } +/// Contains metadata of a field of a [`Item`]. +/// +/// # Examples +/// ``` +/// # use multi_vec::ItemFieldMetadata; +/// # +/// struct CatFood +/// { +/// label: String, +/// age_days: u16, +/// quality: u8, +/// } +/// +/// let cat_food_field_metadata = ItemFieldMetadata { +/// offset: std::mem::offset_of!(CatFood, age_days), +/// size: std::mem::size_of::<u16>(), +/// alignment: std::mem::align_of::<u16>(), +/// }; +/// ``` pub struct ItemFieldMetadata { pub offset: usize, @@ -320,6 +373,7 @@ where type Field; + /// Returns metadata of this item field. fn metadata() -> &'static ItemFieldMetadata; } |