From 1ef28495224fc89c533c31c36bc32a759a118c1e Mon Sep 17 00:00:00 2001
From: Tin Svagelj <tin.svagelj@live.com>
Date: Tue, 19 Sep 2023 22:40:09 +0200
Subject: [PATCH] Add with_metadata function to references

Made ByteRange type public again

Signed-off-by: Tin Svagelj <tin.svagelj@live.com>
---
 Cargo.toml   |  2 +-
 README.md    |  4 ++--
 src/lib.rs   |  4 +++-
 src/refs.rs  | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 src/types.rs |  8 +++++++-
 5 files changed, 60 insertions(+), 5 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 6e6954c..b803fae 100644
--- a/Cargo.toml
+++ b/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 <tin.svagelj@live.com>"]
diff --git a/README.md b/README.md
index c2971e3..e83eefe 100644
--- a/README.md
+++ b/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
diff --git a/src/lib.rs b/src/lib.rs
index 9cf3009..f7e3435 100644
--- a/src/lib.rs
+++ b/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::{
diff --git a/src/refs.rs b/src/refs.rs
index c7dce5a..1d70db8 100644
--- a/src/refs.rs
+++ b/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
diff --git a/src/types.rs b/src/types.rs
index 73fbea9..07be568 100644
--- a/src/types.rs
+++ b/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::*;