Add with_metadata function to references

Made ByteRange type public again

Signed-off-by: Tin Svagelj <[email protected]>

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "contiguous-mem"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2021"
 description = "A contiguous memory storage"
 authors = ["Tin Švagelj <[email protected]>"]

README.md

@@ -60,11 +60,11 @@ Add the crate to your dependencies:
 contiguous_mem = { version = "0.4.*" }
 ```
 
-Optionally disable the `std` feature and enable `no_std` feature to use in `no_std` environment:
+Optionally enable `no_std` feature to use in `no_std` environment:
 
 ```toml
 [dependencies]
-contiguous_mem = { version = "0.4.*", default-features = false, features = ["no_std"] }
+contiguous_mem = { version = "0.4.*", features = ["no_std"] }
 ```
 
 ### Features

src/lib.rs

@@ -21,9 +21,11 @@ mod types;
 
 use details::*;
 pub use details::{ImplConcurrent, ImplDefault, ImplUnsafe};
-use range::ByteRange;
+pub use range::ByteRange;
 use refs::sealed::EntryRef;
 pub use refs::{CERef, ContiguousEntryRef, SCERef, SyncContiguousEntryRef};
+#[cfg(feature = "ptr_metadata")]
+pub use types::static_metadata;
 use types::*;
 
 use core::{

src/refs.rs

@@ -179,6 +179,27 @@ impl<T: ?Sized> SyncContiguousEntryRef<T> {
         }
     }
 
+    /// Transmutes this reference to type `R` with provided `metadata`.
+    ///
+    /// [`static_metadata`](crate::static_metadata) function may be used to
+    /// statically construct metadata for a struct-trait pair.
+    ///
+    /// # Safety
+    ///
+    /// See: [`ContiguousEntryRef::with_metadata`]
+    #[cfg(feature = "ptr_metadata")]
+    pub unsafe fn with_metadata<R: ?Sized>(
+        self,
+        metadata: <R as Pointee>::Metadata,
+    ) -> ContiguousEntryRef<R> {
+        unsafe {
+            ContiguousEntryRef {
+                inner: core::mem::transmute(self.inner),
+                metadata,
+            }
+        }
+    }
+
     /// Creates an immutable pointer to underlying data, blocking the current
     /// thread until base address can be read.
     ///
@@ -416,6 +437,32 @@ impl<T: ?Sized> ContiguousEntryRef<T> {
         }
     }
 
+    /// Transmutes this reference to type `R` with provided `metadata`.
+    ///
+    /// [`static_metadata`](crate::static_metadata) function may be used to
+    /// statically construct metadata for a struct-trait pair.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it assumes any `T` to implement `R`,
+    /// as the original type of stored data can be erased through
+    /// [`into_dyn`](ContiguousEntryRef::into_dyn) it's impossible to check
+    /// whether the initial struct actually implements `R`.
+    ///
+    /// Calling methods from an incorrect vtable will cause undefined behavior.
+    #[cfg(feature = "ptr_metadata")]
+    pub unsafe fn with_metadata<R: ?Sized>(
+        self,
+        metadata: <R as Pointee>::Metadata,
+    ) -> ContiguousEntryRef<R> {
+        unsafe {
+            ContiguousEntryRef {
+                inner: core::mem::transmute(self.inner),
+                metadata,
+            }
+        }
+    }
+
     /// Creates an immutable pointer to underlying data.
     ///
     /// # Safety

src/types.rs

@@ -187,6 +187,12 @@ mod pointer {
     use super::*;
     use core::ptr::NonNull;
 
+    /// Returns [`Pointee`] metadata for provided pair of struct `S` and some
+    /// unsized type (e.g. a trait) `T`.
+    /// 
+    /// This metadata is usually a pointer to vtable of `T` implementation for
+    /// `S`, but can be something else and the value is considered internal to
+    /// the compiler.
     pub const fn static_metadata<S, T: ?Sized>() -> <T as Pointee>::Metadata
     where
         S: Unsize<T>,
@@ -212,4 +218,4 @@ mod pointer {
     }
 }
 #[cfg(feature = "ptr_metadata")]
-pub(crate) use pointer::*;
+pub use pointer::*;