From b40ca9e40d2cc344c3cc5d09883027c79509052c Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Wed, 24 Aug 2022 18:27:58 +0800 Subject: [PATCH] Improve docs. --- src/api/build_type.rs | 10 +++++----- src/api/deprecated.rs | 10 +++++----- src/api/register.rs | 20 ++++++++------------ src/func/register.rs | 36 ++++++++++++++++++++++-------------- src/module/mod.rs | 34 +++++++++++++++++----------------- src/serde/de.rs | 36 +++++++++++++----------------------- 6 files changed, 70 insertions(+), 76 deletions(-) diff --git a/src/api/build_type.rs b/src/api/build_type.rs index 20556eb7..9ce59ba4 100644 --- a/src/api/build_type.rs +++ b/src/api/build_type.rs @@ -128,11 +128,11 @@ impl<'a, T: Variant + Clone> TypeBuilder<'a, T> { /// Register a custom function. #[inline(always)] - pub fn with_fn(&mut self, name: N, method: F) -> &mut Self - where - N: AsRef + Into, - F: RegisterNativeFunction, - { + pub fn with_fn( + &mut self, + name: impl AsRef + Into, + method: impl RegisterNativeFunction, + ) -> &mut Self { self.engine.register_fn(name, method); self } diff --git a/src/api/deprecated.rs b/src/api/deprecated.rs index b1a06279..c4fa140c 100644 --- a/src/api/deprecated.rs +++ b/src/api/deprecated.rs @@ -143,11 +143,11 @@ impl Engine { /// This method will be removed in the next major version. #[deprecated(since = "1.9.1", note = "use `register_fn` instead")] #[inline(always)] - pub fn register_result_fn(&mut self, name: N, func: F) -> &mut Self - where - N: AsRef + Into, - F: RegisterNativeFunction>, - { + pub fn register_result_fn( + &mut self, + name: impl AsRef + Into, + func: impl RegisterNativeFunction>, + ) -> &mut Self { self.register_fn(name, func) } /// Register a getter function for a member of a registered type with the [`Engine`]. diff --git a/src/api/register.rs b/src/api/register.rs index 01b4f048..f8102864 100644 --- a/src/api/register.rs +++ b/src/api/register.rs @@ -53,11 +53,11 @@ impl Engine { /// # } /// ``` #[inline] - pub fn register_fn(&mut self, name: N, func: F) -> &mut Self - where - N: AsRef + Into, - F: RegisterNativeFunction, - { + pub fn register_fn>( + &mut self, + name: impl AsRef + Into, + func: F, + ) -> &mut Self { let param_types = F::param_types(); #[cfg(feature = "metadata")] @@ -109,16 +109,12 @@ impl Engine { /// /// To access the first mutable parameter, use `args.get_mut(0).unwrap()` #[inline(always)] - pub fn register_raw_fn( + pub fn register_raw_fn( &mut self, - name: N, + name: impl AsRef + Into, arg_types: impl AsRef<[TypeId]>, func: impl Fn(NativeCallContext, &mut FnCallArgs) -> RhaiResultOf + SendSync + 'static, - ) -> &mut Self - where - N: AsRef + Into, - T: Variant + Clone, - { + ) -> &mut Self { self.global_namespace_mut().set_raw_fn( name, FnNamespace::Global, diff --git a/src/func/register.rs b/src/func/register.rs index d9e45e76..40035b64 100644 --- a/src/func/register.rs +++ b/src/func/register.rs @@ -11,20 +11,23 @@ use crate::{reify, Dynamic, NativeCallContext, RhaiResultOf}; use std::prelude::v1::*; use std::{any::TypeId, mem}; -// These types are used to build a unique _marker_ tuple type for each combination -// of function parameter types in order to make each trait implementation unique. -// That is because stable Rust currently does not allow distinguishing implementations -// based purely on parameter types of traits (`Fn`, `FnOnce` and `FnMut`). -// -// For example: -// -// `NativeFunction<(Mut, B, Ref), R>` -// -// will have the function prototype constraint to: -// -// `FN: (&mut A, B, &C) -> R` -// -// These types are not actually used anywhere. +/// These types are used to build a unique _marker_ tuple type for each combination +/// of function parameter types in order to make each trait implementation unique. +/// +/// That is because stable Rust currently does not allow distinguishing implementations +/// based purely on parameter types of traits (`Fn`, `FnOnce` and `FnMut`). +/// +/// # Examples +/// +/// `RegisterNativeFunction<(Mut, B, Ref), R, ()>` = `Fn(&mut A, B, &C) -> R` +/// +/// `RegisterNativeFunction<(Mut, B, Ref), R, NativeCallContext>` = `Fn(NativeCallContext, &mut A, B, &C) -> R` +/// +/// `RegisterNativeFunction<(Mut, B, Ref), R, RhaiResultOf<()>>` = `Fn(&mut A, B, &C) -> Result>` +/// +/// `RegisterNativeFunction<(Mut, B, Ref), R, RhaiResultOf>` = `Fn(NativeCallContext, &mut A, B, &C) -> Result>` +/// +/// These types are not actually used anywhere. pub struct Mut(T); //pub struct Ref(T); @@ -60,6 +63,11 @@ pub fn by_value(data: &mut Dynamic) -> T { } /// Trait to register custom Rust functions. +/// +/// # Type Parameters +/// +/// * `ARGS` - a tuple containing parameter types, with `&mut T` represented by [`Mut`]. +/// * `RET` - return type of the function; if the function returns `Result`, it is the unwrapped inner value type. pub trait RegisterNativeFunction { /// Convert this function into a [`CallableFunction`]. #[must_use] diff --git a/src/module/mod.rs b/src/module/mod.rs index 07d9c261..d82d529c 100644 --- a/src/module/mod.rs +++ b/src/module/mod.rs @@ -1245,18 +1245,14 @@ impl Module { /// assert!(module.contains_fn(hash)); /// ``` #[inline(always)] - pub fn set_raw_fn( + pub fn set_raw_fn( &mut self, name: impl AsRef, namespace: FnNamespace, access: FnAccess, arg_types: impl AsRef<[TypeId]>, - func: F, - ) -> u64 - where - T: Variant + Clone, - F: Fn(NativeCallContext, &mut FnCallArgs) -> RhaiResultOf + SendSync + 'static, - { + func: impl Fn(NativeCallContext, &mut FnCallArgs) -> RhaiResultOf + SendSync + 'static, + ) -> u64 { let f = move |ctx: NativeCallContext, args: &mut FnCallArgs| func(ctx, args).map(Dynamic::from); @@ -1293,11 +1289,14 @@ impl Module { /// assert!(module.contains_fn(hash)); /// ``` #[inline(always)] - pub fn set_native_fn(&mut self, name: N, func: F) -> u64 + pub fn set_native_fn( + &mut self, + name: impl AsRef + Into, + func: F, + ) -> u64 where - N: AsRef + Into, T: Variant + Clone, - F: RegisterNativeFunction>, + F: RegisterNativeFunction>, { self.set_fn( name, @@ -1587,16 +1586,17 @@ impl Module { /// ``` #[cfg(any(not(feature = "no_index"), not(feature = "no_object")))] #[inline(always)] - pub fn set_indexer_get_set_fn( - &mut self, - get_fn: impl RegisterNativeFunction<(Mut, B), T, RhaiResultOf> + SendSync + 'static, - set_fn: impl RegisterNativeFunction<(Mut, B, T), (), RhaiResultOf> + SendSync + 'static, - ) -> (u64, u64) - where + pub fn set_indexer_get_set_fn< A: Variant + Clone, B: Variant + Clone, T: Variant + Clone, - { + S1, + S2, + >( + &mut self, + get_fn: impl RegisterNativeFunction<(Mut, B), T, RhaiResultOf> + SendSync + 'static, + set_fn: impl RegisterNativeFunction<(Mut, B, T), (), RhaiResultOf> + SendSync + 'static, + ) -> (u64, u64) { ( self.set_indexer_get_fn(get_fn), self.set_indexer_set_fn(set_fn), diff --git a/src/serde/de.rs b/src/serde/de.rs index aa6bbd66..15c538cd 100644 --- a/src/serde/de.rs +++ b/src/serde/de.rs @@ -515,41 +515,31 @@ impl<'a: 'de, 'de, ITER: Iterator> serde::de::SeqAccess<'de> /// `MapAccess` implementation for maps. #[cfg(not(feature = "no_object"))] -struct IterateMap<'a, KEYS, VALUES> -where - KEYS: Iterator, - VALUES: Iterator, -{ +struct IterateMap<'a, K: Iterator, V: Iterator> { // Iterator for a stream of [`Dynamic`][crate::Dynamic] keys. - keys: KEYS, + keys: K, // Iterator for a stream of [`Dynamic`][crate::Dynamic] values. - values: VALUES, + values: V, } #[cfg(not(feature = "no_object"))] -impl<'a, KEYS, VALUES> IterateMap<'a, KEYS, VALUES> -where - KEYS: Iterator, - VALUES: Iterator, -{ +impl<'a, K: Iterator, V: Iterator> IterateMap<'a, K, V> { #[must_use] - pub fn new(keys: KEYS, values: VALUES) -> Self { + pub fn new(keys: K, values: V) -> Self { Self { keys, values } } } #[cfg(not(feature = "no_object"))] -impl<'a: 'de, 'de, KEYS, VALUES> serde::de::MapAccess<'de> for IterateMap<'a, KEYS, VALUES> -where - KEYS: Iterator, - VALUES: Iterator, +impl<'a: 'de, 'de, K: Iterator, V: Iterator> + serde::de::MapAccess<'de> for IterateMap<'a, K, V> { type Error = RhaiError; - fn next_key_seed>( + fn next_key_seed>( &mut self, - seed: K, - ) -> RhaiResultOf> { + seed: S, + ) -> RhaiResultOf> { // Deserialize each `Identifier` key coming out of the keys iterator. match self.keys.next() { None => Ok(None), @@ -559,10 +549,10 @@ where } } - fn next_value_seed>( + fn next_value_seed>( &mut self, - seed: V, - ) -> RhaiResultOf { + seed: S, + ) -> RhaiResultOf { // Deserialize each value item coming out of the iterator. seed.deserialize(&mut DynamicDeserializer::from_dynamic( self.values.next().unwrap(),