summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHampusM <hampus@hampusmat.com>2024-08-26 20:59:45 +0200
committerHampusM <hampus@hampusmat.com>2024-08-26 20:59:45 +0200
commit17e05f57f4b95b51196893cd341fdc089f20c6bb (patch)
tree7510709d02a12ecd991593b0d94960599722ad7c
parent0639ef032fd979762657eb48fea3f20cfc5ba1c2 (diff)
docs: add documentation comments
-rw-r--r--src/lib.rs54
1 files changed, 54 insertions, 0 deletions
diff --git a/src/lib.rs b/src/lib.rs
index fc92c3a..fefcb97 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -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;
}