From a81d7b3e8c4f346ae35fa3d93b9fac5f5e09f095 Mon Sep 17 00:00:00 2001 From: Andrew Bailey Date: Thu, 3 Feb 2022 11:00:21 -0500 Subject: [PATCH 1/2] Added some comments to the first example --- README.md | 92 +++++++++++++++++++++++++------------------- ouroboros/src/lib.rs | 14 +++++++ 2 files changed, 67 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index dcf0a98..09d9c88 100644 --- a/README.md +++ b/README.md @@ -20,42 +20,56 @@ Version notes: Tests are located in the examples/ folder because they need to be in a crate outside of `ouroboros` for the `self_referencing` macro to work properly. -```rust -use ouroboros::self_referencing; - -#[self_referencing] -struct MyStruct { - int_data: i32, - float_data: f32, - #[borrows(int_data)] - int_reference: &'this i32, - #[borrows(mut float_data)] - float_reference: &'this mut f32, -} - -fn main() { - let mut my_value = MyStructBuilder { - int_data: 42, - float_data: 3.14, - int_reference_builder: |int_data: &i32| int_data, - float_reference_builder: |float_data: &mut f32| float_data, - }.build(); - - // Prints 42 - println!("{:?}", my_value.borrow_int_data()); - // Prints 3.14 - println!("{:?}", my_value.borrow_float_reference()); - // Sets the value of float_data to 84.0 - my_value.with_mut(|fields| { - **fields.float_reference = (**fields.int_reference as f32) * 2.0; - }); - - // We can hold on to this reference... - let int_ref = *my_value.borrow_int_reference(); - println!("{:?}", *int_ref); - // As long as the struct is still alive. - drop(my_value); - // This will cause an error! - // println!("{:?}", *int_ref); -} -``` +/// ```rust +/// use ouroboros::self_referencing; +/// +/// #[self_referencing] +/// struct MyStruct { +/// int_data: i32, +/// float_data: f32, +/// #[borrows(int_data)] +/// // the 'this lifetime is created by the #[self_referencing] macro +/// // and should be used on all references marked by the #[borrows] macro +/// int_reference: &'this i32, +/// #[borrows(mut float_data)] +/// float_reference: &'this mut f32, +/// } +/// +/// fn main() { +/// // The builder is created by the #[self_referencing] macro +/// // and is used to create the struct +/// let mut my_value = MyStructBuilder { +/// int_data: 42, +/// float_data: 3.14, +/// +/// // Note that the name of the field in the builder +/// // is the name of the field in the struct + `_builder` +/// // ie: {field_name}_builder +/// // the closure that assigns the value for the field will be passed +/// // a reference to the field(s) defined in the #[borrows] macro +/// +/// int_reference_builder: |int_data: &i32| int_data, +/// float_reference_builder: |float_data: &mut f32| float_data, +/// }.build(); +/// +/// // The fields in the original struct can not be accesed directly +/// // The builder creates accessor methods which are called borrow_{field_name}() +/// +/// // Prints 42 +/// println!("{:?}", my_value.borrow_int_data()); +/// // Prints 3.14 +/// println!("{:?}", my_value.borrow_float_reference()); +/// // Sets the value of float_data to 84.0 +/// my_value.with_mut(|fields| { +/// **fields.float_reference = (**fields.int_reference as f32) * 2.0; +/// }); +/// +/// // We can hold on to this reference... +/// let int_ref = *my_value.borrow_int_reference(); +/// println!("{:?}", *int_ref); +/// // As long as the struct is still alive. +/// drop(my_value); +/// // This will cause an error! +/// // println!("{:?}", *int_ref); +/// } +/// ``` diff --git a/ouroboros/src/lib.rs b/ouroboros/src/lib.rs index 9e784a8..d32f905 100644 --- a/ouroboros/src/lib.rs +++ b/ouroboros/src/lib.rs @@ -14,19 +14,33 @@ /// int_data: i32, /// float_data: f32, /// #[borrows(int_data)] +/// // the 'this lifetime is created by the #[self_referencing] macro +/// // and should be used on all references marked by the #[borrows] macro /// int_reference: &'this i32, /// #[borrows(mut float_data)] /// float_reference: &'this mut f32, /// } /// /// fn main() { +/// // The builder is created by the #[self_referencing] macro +/// // and is used to create the struct /// let mut my_value = MyStructBuilder { /// int_data: 42, /// float_data: 3.14, +/// +/// // Note that the name of the field in the builder +/// // is the name of the field in the struct + `_builder` +/// // ie: {field_name}_builder +/// // the closure that assigns the value for the field will be passed +/// // a reference to the field(s) defined in the #[borrows] macro +/// /// int_reference_builder: |int_data: &i32| int_data, /// float_reference_builder: |float_data: &mut f32| float_data, /// }.build(); /// +/// // The fields in the original struct can not be accesed directly +/// // The builder creates accessor methods which are called borrow_{field_name}() +/// /// // Prints 42 /// println!("{:?}", my_value.borrow_int_data()); /// // Prints 3.14 From 9b98c732b44d77fff451f196c3351f078d2e93ca Mon Sep 17 00:00:00 2001 From: Andrew Bailey Date: Thu, 3 Feb 2022 11:04:26 -0500 Subject: [PATCH 2/2] Correcting mistake in previous commit to README --- README.md | 106 +++++++++++++++++++++++++++--------------------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 09d9c88..651ab51 100644 --- a/README.md +++ b/README.md @@ -20,56 +20,56 @@ Version notes: Tests are located in the examples/ folder because they need to be in a crate outside of `ouroboros` for the `self_referencing` macro to work properly. -/// ```rust -/// use ouroboros::self_referencing; -/// -/// #[self_referencing] -/// struct MyStruct { -/// int_data: i32, -/// float_data: f32, -/// #[borrows(int_data)] -/// // the 'this lifetime is created by the #[self_referencing] macro -/// // and should be used on all references marked by the #[borrows] macro -/// int_reference: &'this i32, -/// #[borrows(mut float_data)] -/// float_reference: &'this mut f32, -/// } -/// -/// fn main() { -/// // The builder is created by the #[self_referencing] macro -/// // and is used to create the struct -/// let mut my_value = MyStructBuilder { -/// int_data: 42, -/// float_data: 3.14, -/// -/// // Note that the name of the field in the builder -/// // is the name of the field in the struct + `_builder` -/// // ie: {field_name}_builder -/// // the closure that assigns the value for the field will be passed -/// // a reference to the field(s) defined in the #[borrows] macro -/// -/// int_reference_builder: |int_data: &i32| int_data, -/// float_reference_builder: |float_data: &mut f32| float_data, -/// }.build(); -/// -/// // The fields in the original struct can not be accesed directly -/// // The builder creates accessor methods which are called borrow_{field_name}() -/// -/// // Prints 42 -/// println!("{:?}", my_value.borrow_int_data()); -/// // Prints 3.14 -/// println!("{:?}", my_value.borrow_float_reference()); -/// // Sets the value of float_data to 84.0 -/// my_value.with_mut(|fields| { -/// **fields.float_reference = (**fields.int_reference as f32) * 2.0; -/// }); -/// -/// // We can hold on to this reference... -/// let int_ref = *my_value.borrow_int_reference(); -/// println!("{:?}", *int_ref); -/// // As long as the struct is still alive. -/// drop(my_value); -/// // This will cause an error! -/// // println!("{:?}", *int_ref); -/// } -/// ``` +```rust +use ouroboros::self_referencing; + +#[self_referencing] +struct MyStruct { + int_data: i32, + float_data: f32, + #[borrows(int_data)] + // the 'this lifetime is created by the #[self_referencing] macro + // and should be used on all references marked by the #[borrows] macro + int_reference: &'this i32, + #[borrows(mut float_data)] + float_reference: &'this mut f32, +} + +fn main() { + // The builder is created by the #[self_referencing] macro + // and is used to create the struct + let mut my_value = MyStructBuilder { + int_data: 42, + float_data: 3.14, + + // Note that the name of the field in the builder + // is the name of the field in the struct + `_builder` + // ie: {field_name}_builder + // the closure that assigns the value for the field will be passed + // a reference to the field(s) defined in the #[borrows] macro + + int_reference_builder: |int_data: &i32| int_data, + float_reference_builder: |float_data: &mut f32| float_data, + }.build(); + + // The fields in the original struct can not be accesed directly + // The builder creates accessor methods which are called borrow_{field_name}() + + // Prints 42 + println!("{:?}", my_value.borrow_int_data()); + // Prints 3.14 + println!("{:?}", my_value.borrow_float_reference()); + // Sets the value of float_data to 84.0 + my_value.with_mut(|fields| { + **fields.float_reference = (**fields.int_reference as f32) * 2.0; + }); + + // We can hold on to this reference... + let int_ref = *my_value.borrow_int_reference(); + println!("{:?}", *int_ref); + // As long as the struct is still alive. + drop(my_value); + // This will cause an error! + // println!("{:?}", *int_ref); +} +```