From d50fa7712b69b0be5ecae24d267afbbbb7a821e8 Mon Sep 17 00:00:00 2001 From: John-John Tedro Date: Sun, 3 Nov 2024 11:03:24 +0100 Subject: [PATCH] rune: Rename and document methods on Value --- crates/rune/src/macros/format_args.rs | 2 +- crates/rune/src/runtime/bytes.rs | 2 +- crates/rune/src/runtime/from_value.rs | 18 +-- crates/rune/src/runtime/function.rs | 2 +- crates/rune/src/runtime/range.rs | 2 +- crates/rune/src/runtime/range_from.rs | 2 +- crates/rune/src/runtime/range_full.rs | 2 +- crates/rune/src/runtime/range_inclusive.rs | 2 +- crates/rune/src/runtime/range_to.rs | 2 +- crates/rune/src/runtime/range_to_inclusive.rs | 2 +- crates/rune/src/runtime/tests.rs | 6 +- crates/rune/src/runtime/value.rs | 145 ++++++++++++++---- crates/rune/src/runtime/vec.rs | 6 +- crates/rune/src/runtime/vec_tuple.rs | 2 +- crates/rune/src/runtime/vm.rs | 2 +- crates/rune/src/tests/bug_344.rs | 2 +- 16 files changed, 145 insertions(+), 54 deletions(-) diff --git a/crates/rune/src/macros/format_args.rs b/crates/rune/src/macros/format_args.rs index d616ceb76..95985bd1c 100644 --- a/crates/rune/src/macros/format_args.rs +++ b/crates/rune/src/macros/format_args.rs @@ -48,7 +48,7 @@ impl FormatArgs { } } - let format = format.into_any::().with_span(&self.format)?; + let format = format.downcast::().with_span(&self.format)?; let mut unused_pos = (0..pos.len()).try_collect::>()?; let mut unused_named = named diff --git a/crates/rune/src/runtime/bytes.rs b/crates/rune/src/runtime/bytes.rs index fb1e67a11..fe21308bf 100644 --- a/crates/rune/src/runtime/bytes.rs +++ b/crates/rune/src/runtime/bytes.rs @@ -358,7 +358,7 @@ impl UnsafeToRef for [u8] { type Guard = RawAnyGuard; unsafe fn unsafe_to_ref<'a>(value: Value) -> VmResult<(&'a Self, Self::Guard)> { - let (value, guard) = Ref::into_raw(vm_try!(value.into_any_ref::())); + let (value, guard) = Ref::into_raw(vm_try!(value.into_ref::())); VmResult::Ok((value.as_ref().as_slice(), guard)) } } diff --git a/crates/rune/src/runtime/from_value.rs b/crates/rune/src/runtime/from_value.rs index c28ed3012..7f4a8a5eb 100644 --- a/crates/rune/src/runtime/from_value.rs +++ b/crates/rune/src/runtime/from_value.rs @@ -247,7 +247,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - value.into_any() + value.downcast() } } @@ -257,7 +257,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - value.into_any_mut() + value.into_mut() } } @@ -267,7 +267,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - value.into_any_ref() + value.into_ref() } } @@ -291,7 +291,7 @@ where T: FromValue, { fn from_value(value: Value) -> Result { - Ok(match value.into_any::>()? { + Ok(match value.downcast::>()? { Some(some) => Some(T::from_value(some.clone())?), None => None, }) @@ -333,7 +333,7 @@ impl UnsafeToRef for str { type Guard = RawAnyGuard; unsafe fn unsafe_to_ref<'a>(value: Value) -> VmResult<(&'a Self, Self::Guard)> { - let string = vm_try!(value.into_any_ref::()); + let string = vm_try!(value.into_ref::()); let (string, guard) = Ref::into_raw(string); VmResult::Ok((string.as_ref().as_str(), guard)) } @@ -343,7 +343,7 @@ impl UnsafeToMut for str { type Guard = RawAnyGuard; unsafe fn unsafe_to_mut<'a>(value: Value) -> VmResult<(&'a mut Self, Self::Guard)> { - let string = vm_try!(value.into_any_mut::()); + let string = vm_try!(value.into_mut::()); let (mut string, guard) = Mut::into_raw(string); VmResult::Ok((string.as_mut().as_mut_str(), guard)) } @@ -356,7 +356,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - Ok(match value.into_any::>()? { + Ok(match value.downcast::>()? { Ok(ok) => Result::Ok(T::from_value(ok.clone())?), Err(err) => Result::Err(E::from_value(err.clone())?), }) @@ -435,7 +435,7 @@ cfg_std! { T: FromValue, { fn from_value(value: Value) -> Result { - let object = value.into_any::<$crate::runtime::Object>()?; + let object = value.downcast::<$crate::runtime::Object>()?; let mut output = <$ty>::with_capacity(object.len()); @@ -462,7 +462,7 @@ macro_rules! impl_try_map { T: FromValue, { fn from_value(value: Value) -> Result { - let object = value.into_any::<$crate::runtime::Object>()?; + let object = value.downcast::<$crate::runtime::Object>()?; let mut output = <$ty>::try_with_capacity(object.len())?; diff --git a/crates/rune/src/runtime/function.rs b/crates/rune/src/runtime/function.rs index bf7bd3ea1..ded84a248 100644 --- a/crates/rune/src/runtime/function.rs +++ b/crates/rune/src/runtime/function.rs @@ -1046,7 +1046,7 @@ struct FnTupleVariant { impl FromValue for SyncFunction { #[inline] fn from_value(value: Value) -> Result { - value.into_any::()?.into_sync() + value.downcast::()?.into_sync() } } diff --git a/crates/rune/src/runtime/range.rs b/crates/rune/src/runtime/range.rs index 5f00573aa..c13acfe84 100644 --- a/crates/rune/src/runtime/range.rs +++ b/crates/rune/src/runtime/range.rs @@ -316,7 +316,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - let range = value.into_any::()?; + let range = value.downcast::()?; let start = Idx::from_value(range.start)?; let end = Idx::from_value(range.end)?; Ok(ops::Range { start, end }) diff --git a/crates/rune/src/runtime/range_from.rs b/crates/rune/src/runtime/range_from.rs index 8f8b7b516..26a2faa2f 100644 --- a/crates/rune/src/runtime/range_from.rs +++ b/crates/rune/src/runtime/range_from.rs @@ -291,7 +291,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - let range = value.into_any::()?; + let range = value.downcast::()?; let start = Idx::from_value(range.start)?; Ok(ops::RangeFrom { start }) } diff --git a/crates/rune/src/runtime/range_full.rs b/crates/rune/src/runtime/range_full.rs index e921299c9..0691fc4ab 100644 --- a/crates/rune/src/runtime/range_full.rs +++ b/crates/rune/src/runtime/range_full.rs @@ -135,7 +135,7 @@ impl ToValue for ops::RangeFull { impl FromValue for ops::RangeFull { #[inline] fn from_value(value: Value) -> Result { - let RangeFull = value.into_any::()?; + let RangeFull = value.downcast::()?; Ok(ops::RangeFull) } } diff --git a/crates/rune/src/runtime/range_inclusive.rs b/crates/rune/src/runtime/range_inclusive.rs index ea15e818a..a551f6146 100644 --- a/crates/rune/src/runtime/range_inclusive.rs +++ b/crates/rune/src/runtime/range_inclusive.rs @@ -317,7 +317,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - let range = value.into_any::()?; + let range = value.downcast::()?; let start = Idx::from_value(range.start)?; let end = Idx::from_value(range.end)?; Ok(start..=end) diff --git a/crates/rune/src/runtime/range_to.rs b/crates/rune/src/runtime/range_to.rs index f4e2d2700..7746b68f7 100644 --- a/crates/rune/src/runtime/range_to.rs +++ b/crates/rune/src/runtime/range_to.rs @@ -202,7 +202,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - let range = value.into_any::()?; + let range = value.downcast::()?; let end = Idx::from_value(range.end)?; Ok(ops::RangeTo { end }) } diff --git a/crates/rune/src/runtime/range_to_inclusive.rs b/crates/rune/src/runtime/range_to_inclusive.rs index c3a05540f..23feb5ede 100644 --- a/crates/rune/src/runtime/range_to_inclusive.rs +++ b/crates/rune/src/runtime/range_to_inclusive.rs @@ -200,7 +200,7 @@ where { #[inline] fn from_value(value: Value) -> Result { - let range = value.into_any::()?; + let range = value.downcast::()?; let end = Idx::from_value(range.end)?; Ok(ops::RangeToInclusive { end }) } diff --git a/crates/rune/src/runtime/tests.rs b/crates/rune/src/runtime/tests.rs index e1723d7a1..0c8a2a823 100644 --- a/crates/rune/src/runtime/tests.rs +++ b/crates/rune/src/runtime/tests.rs @@ -44,8 +44,8 @@ fn test_clone_take() -> Result<()> { let v = Value::from(AnyObj::new(Thing(0))?); let v2 = v.clone(); let v3 = v.clone(); - assert_eq!(Thing(0), v2.into_any::()?); - assert!(v3.into_any::().is_err()); + assert_eq!(Thing(0), v2.downcast::()?); + assert!(v3.downcast::().is_err()); let any = v.into_any_obj()?; assert_eq!(any.type_hash(), Thing::HASH); Ok(()) @@ -549,7 +549,7 @@ fn test_clone_issue() { let shared = Value::try_from(Bytes::new()).unwrap(); let _ = { - let shared = shared.into_any_ref::().unwrap(); + let shared = shared.into_ref::().unwrap(); let out = shared.try_clone().unwrap(); out }; diff --git a/crates/rune/src/runtime/value.rs b/crates/rune/src/runtime/value.rs index cb97d1d8f..b1a454f78 100644 --- a/crates/rune/src/runtime/value.rs +++ b/crates/rune/src/runtime/value.rs @@ -899,8 +899,13 @@ impl Value { } /// Try to coerce value into a typed reference. + /// + /// # Safety + /// + /// The returned pointer is only valid to dereference as long as the + /// returned guard is live. #[inline] - pub fn into_any_ref(self) -> Result, RuntimeError> + pub fn into_any_ref_ptr(self) -> Result<(NonNull, RawValueGuard), RuntimeError> where T: Any, { @@ -910,18 +915,23 @@ impl Value { Repr::Mutable(value) => Err(RuntimeError::expected_any::( value.borrow_ref()?.type_info(), )), - Repr::Any(value) => Ok(value.into_ref()?), + Repr::Any(value) => { + let (ptr, guard) = value.borrow_ref_ptr::()?; + let guard = RawValueGuard { guard }; + Ok((ptr, guard)) + } } } - /// Try to coerce value into a typed reference. + /// Try to coerce value into a typed mutable reference. /// /// # Safety /// /// The returned pointer is only valid to dereference as long as the /// returned guard is live. #[inline] - pub fn into_any_ref_ptr(self) -> Result<(NonNull, RawValueGuard), RuntimeError> + #[doc(hidden)] + pub fn into_any_mut_ptr(self) -> Result<(NonNull, RawValueGuard), RuntimeError> where T: Any, { @@ -932,16 +942,44 @@ impl Value { value.borrow_ref()?.type_info(), )), Repr::Any(value) => { - let (ptr, guard) = value.borrow_ref_ptr::()?; + let (ptr, guard) = value.borrow_mut_ptr::()?; let guard = RawValueGuard { guard }; Ok((ptr, guard)) } } } - /// Try to coerce value into a typed mutable reference. + /// Downcast the value into a stored value that implements `Any`. + /// + /// This takes the interior value, making it inaccessible to other owned + /// references. + /// + /// You should usually prefer to use [`rune::from_value`] instead of this + /// directly. + /// + /// [`rune::from_value`]: crate::from_value + /// + /// # Examples + /// + /// ```rust + /// use rune::Value; + /// use rune::alloc::String; + /// + /// let a = Value::try_from("Hello World")?; + /// let b = a.clone(); + /// + /// assert!(b.borrow_ref::().is_ok()); + /// + /// // NB: The interior representation of the stored string is from rune-alloc. + /// let a = a.downcast::()?; + /// + /// assert!(b.borrow_ref::().is_err()); + /// + /// assert_eq!(a, "Hello World"); + /// # Ok::<_, rune::support::Error>(()) + /// ``` #[inline] - pub fn into_any_mut(self) -> Result, RuntimeError> + pub fn downcast(self) -> Result where T: Any, { @@ -951,52 +989,82 @@ impl Value { Repr::Mutable(value) => Err(RuntimeError::expected_any::( value.borrow_ref()?.type_info(), )), - Repr::Any(value) => Ok(value.into_mut()?), + Repr::Any(value) => Ok(value.downcast::()?), } } - /// Try to coerce value into a typed mutable reference. + /// Borrow the value as a typed reference of type `T`. /// - /// # Safety + /// # Examples /// - /// The returned pointer is only valid to dereference as long as the - /// returned guard is live. + /// ```rust + /// use rune::Value; + /// use rune::alloc::String; + /// + /// let a = Value::try_from("Hello World")?; + /// let b = a.clone(); + /// + /// assert!(b.borrow_ref::().is_ok()); + /// + /// // NB: The interior representation of the stored string is from rune-alloc. + /// let a = a.downcast::()?; + /// + /// assert!(b.borrow_ref::().is_err()); + /// + /// assert_eq!(a, "Hello World"); + /// # Ok::<_, rune::support::Error>(()) + /// ``` #[inline] - pub fn into_any_mut_ptr(self) -> Result<(NonNull, RawValueGuard), RuntimeError> + pub fn borrow_ref(&self) -> Result, RuntimeError> where T: Any, { - match self.repr { + match &self.repr { Repr::Empty => Err(RuntimeError::from(AccessError::empty())), Repr::Inline(value) => Err(RuntimeError::expected_any::(value.type_info())), Repr::Mutable(value) => Err(RuntimeError::expected_any::( value.borrow_ref()?.type_info(), )), - Repr::Any(value) => { - let (ptr, guard) = value.borrow_mut_ptr::()?; - let guard = RawValueGuard { guard }; - Ok((ptr, guard)) - } + Repr::Any(value) => Ok(value.borrow_ref()?), } } - /// Borrow the value as a typed reference. + /// Try to coerce value into a typed reference of type `T`. + /// + /// You should usually prefer to use [`rune::from_value`] instead of this + /// directly. + /// + /// [`rune::from_value`]: crate::from_value + /// + /// # Examples + /// + /// ```rust + /// use rune::Value; + /// use rune::alloc::String; + /// + /// let mut a = Value::try_from("Hello World")?; + /// let b = a.clone(); + /// + /// assert_eq!(a.into_ref::()?.as_str(), "Hello World"); + /// assert_eq!(b.into_ref::()?.as_str(), "Hello World"); + /// # Ok::<_, rune::support::Error>(()) + /// ``` #[inline] - pub fn borrow_ref(&self) -> Result, RuntimeError> + pub fn into_ref(self) -> Result, RuntimeError> where T: Any, { - match &self.repr { + match self.repr { Repr::Empty => Err(RuntimeError::from(AccessError::empty())), Repr::Inline(value) => Err(RuntimeError::expected_any::(value.type_info())), Repr::Mutable(value) => Err(RuntimeError::expected_any::( value.borrow_ref()?.type_info(), )), - Repr::Any(value) => Ok(value.borrow_ref()?), + Repr::Any(value) => Ok(value.into_ref()?), } } - /// Borrow the value as a mutable typed reference. + /// Try to borrow value into a typed mutable reference of type `T`. #[inline] pub fn borrow_mut(&self) -> Result, RuntimeError> where @@ -1012,9 +1080,32 @@ impl Value { } } - /// Try to coerce value into a typed value. + /// Try to coerce value into a typed mutable reference of type `T`. + /// + /// You should usually prefer to use [`rune::from_value`] instead of this + /// directly. + /// + /// [`rune::from_value`]: crate::from_value + /// + /// # Examples + /// + /// ```rust + /// use rune::Value; + /// use rune::alloc::String; + /// + /// let mut a = Value::try_from("Hello World")?; + /// let b = a.clone(); + /// + /// let s = a.into_mut::()?; + /// assert_eq!(s.as_str(), "Hello World"); + /// s.make_ascii_lowercase(); + /// assert_eq!(s.as_str(), "hello world"); + /// + /// assert_eq!(b.borrow_mut::()?.as_str(), "hello world"); + /// # Ok::<_, rune::support::Error>(()) + /// ``` #[inline] - pub fn into_any(self) -> Result + pub fn into_mut(self) -> Result, RuntimeError> where T: Any, { @@ -1024,7 +1115,7 @@ impl Value { Repr::Mutable(value) => Err(RuntimeError::expected_any::( value.borrow_ref()?.type_info(), )), - Repr::Any(value) => Ok(value.downcast::()?), + Repr::Any(value) => Ok(value.into_mut()?), } } diff --git a/crates/rune/src/runtime/vec.rs b/crates/rune/src/runtime/vec.rs index dc90067c7..80540e76c 100644 --- a/crates/rune/src/runtime/vec.rs +++ b/crates/rune/src/runtime/vec.rs @@ -535,7 +535,7 @@ where T: FromValue, { fn from_value(value: Value) -> Result { - let vec = value.into_any::()?; + let vec = value.downcast::()?; let mut output = ::rust_alloc::vec::Vec::with_capacity(vec.len()); @@ -552,7 +552,7 @@ where T: FromValue, { fn from_value(value: Value) -> Result { - let vec = value.into_any::()?; + let vec = value.downcast::()?; let mut output = alloc::Vec::try_with_capacity(vec.len())?; @@ -568,7 +568,7 @@ impl UnsafeToRef for [Value] { type Guard = RawAnyGuard; unsafe fn unsafe_to_ref<'a>(value: Value) -> VmResult<(&'a Self, Self::Guard)> { - let vec = vm_try!(value.into_any_ref::()); + let vec = vm_try!(value.into_ref::()); let (vec, guard) = Ref::into_raw(vec); VmResult::Ok((vec.as_ref().as_slice(), guard)) } diff --git a/crates/rune/src/runtime/vec_tuple.rs b/crates/rune/src/runtime/vec_tuple.rs index 81595cd94..51bc13768 100644 --- a/crates/rune/src/runtime/vec_tuple.rs +++ b/crates/rune/src/runtime/vec_tuple.rs @@ -27,7 +27,7 @@ macro_rules! impl_from_value_tuple_vec { $($ty: FromValue,)* { fn from_value(value: Value) -> Result { - let vec = value.into_any_ref::<$crate::runtime::Vec>()?; + let vec = value.into_ref::<$crate::runtime::Vec>()?; let [$($var,)*] = vec.as_slice() else { return Err(RuntimeError::new(VmErrorKind::ExpectedTupleLength { diff --git a/crates/rune/src/runtime/vm.rs b/crates/rune/src/runtime/vm.rs index f430c3c9f..4d8290051 100644 --- a/crates/rune/src/runtime/vm.rs +++ b/crates/rune/src/runtime/vm.rs @@ -2101,7 +2101,7 @@ impl Vm { let futures = futures_util::stream::FuturesUnordered::new(); for (branch, value) in vm_try!(self.stack.slice_at(addr, len)).iter().enumerate() { - let future = vm_try!(value.clone().into_any_mut::()); + let future = vm_try!(value.clone().into_mut::()); if !future.is_completed() { futures.push(SelectFuture::new(self.ip + branch, future)); diff --git a/crates/rune/src/tests/bug_344.rs b/crates/rune/src/tests/bug_344.rs index ea5b02702..d4d3fb9a1 100644 --- a/crates/rune/src/tests/bug_344.rs +++ b/crates/rune/src/tests/bug_344.rs @@ -192,7 +192,7 @@ impl UnsafeToRef for GuardCheck { type Guard = Guard; unsafe fn unsafe_to_ref<'a>(value: Value) -> VmResult<(&'a Self, Self::Guard)> { - let (output, guard) = Ref::into_raw(vm_try!(value.into_any_ref::())); + let (output, guard) = Ref::into_raw(vm_try!(value.into_ref::())); let guard = Guard { guard,