# WrapIt
`wrapit` is a small Rust library that wraps any variable using interior mutability to allow mutation through shared references.
This crate provides a generic Wrapper<T> type for single-threaded use, which allows:
- Mutable access to a value through a shared reference.
- Convenient cloning and sharing via Arc.
- Read, reset, and functional mapping of the inner value.
**Note**: This crate uses RefCell for interior mutability. It is not thread-safe. Concurrent access across threads will not compile.
---
## Installation
You can install `wrapit` either from Crates.io or directly from the Git repository.
### Installing from Crates.io
1. Open your `Cargo.toml` file.
2. Add `wrapit` to your dependencies:
```toml
[dependencies]
wrapit = "0.1.0"
```
OR do;
```toml
cargo add wrapit
```
from your project folder or directory.
### Installing directly from Git
1. Open your `Cargo.toml` file.
2. Add `wrapit` as a dependency using the Git repository URL:
```toml
[dependencies]
wrapit = { git = "https://github.com/2teez/wrapit.git" }
```
3. In your Rust code, import the wrapper:
```rust
use wrapit::Wrapper;
```
## Description
`wraptit` - Simple wraps any type and using interior mutability makes using the variable like in javascript or python without specifying `mut` to the wrapper variable, however using the function _*reset*_ and _*get*_, the values in the variable could be reset and gotten.
```javascript
const langs = ["java", "clojure", "lua"];
langs.push("swift");
console.log(langs);
```
However in rust, you will have to use the `mut` keyword with the variable like so:
```rust
let mut langs = vec!["java", "clojure", "lua"];
langs.push("swift");
println!("{:?}", langs);
```
using `wrapit`, do this:
```rust
use wrapit::Wrapper;
let langs = vec!["java", "clojure", "lua"]; // immutable
let wrapper = Wrapper::new(langs);
// changed the variable content without the `mut` keyword
wrapper.reset(vec!["java", "clojure", "lua", "swift"]);
println!("{:?}", wrapper);
```
## wrait Methods
1. new
> **_fn new(data: T) -> Self_**
>
> - Creates a new Wrapper<T> containing data.
> - Allocates the value inside RefCell and wraps it in Arc.
- No runtime panic.
### Example:
```rust
let wrapper = Wrapper::new(42);
```
2. reset
> **_fn reset(&self, ndata: T) -> &Self_**
>
> - Replaces the inner value with ndata.
> - Returns a reference to self for method chaining.
> - Panics at runtime if any active borrow exists (e.g., if .borrow() has been called and not dropped).
### Example:
```rust
wrapper.reset(100);
```
3. get
> **_fn get(&self) -> T_**
>
> - Returns a clone of the inner value.
> - Uses immutable borrow (borrow()) internally.
> - Panics if a mutable borrow is active.
### Example:
```rust
let value = wrapper.get();
```
4. borrow
> **fn borrow(&self) -> std::cell::Ref<'_, T>**
>
> - Returns a Ref<T>, a smart pointer for immutable access.
> - Automatically releases the borrow when dropped.
> - Panics if a mutable borrow is active.
## Example:
```rust
let value_ref = wrapper.borrow();
println!("{}", *value_ref);
```
5. map
> **fn map<F, U>(&self, f: F) -> U
where
F: FnOnce(&T) -> U,**
>
> - Applies a function f to the inner value.
> - Returns the function’s result.
> - Panics if a mutable borrow exists while calling this method.
## Example:
```rust
### Summary of Runtime Panics
reset() | Active immutable borrow exists
get() | Active mutable borrow exists
borrow() | Active mutable borrow exists
map() | Active mutable borrow exists
> - These panics are enforced at runtime by *RefCell*.
## Usage Example
```rust
use wrapped::wrapped::Wrapper;
let w = Wrapper::new(String::from("Rust"));
// Read value
assert_eq!(w.get(), "Rust");
// Mutate value
w.reset(String::from("C++"));
assert_eq!(w.get(), "C++");
// Borrow inner value
let val = w.borrow();
println!("Value = {}", *val);
// Map function
```
## Notes
> - This Wrapper is not thread-safe (*YET*). The thread-safe branch would be added in later version.
> - All borrows are checked at runtime using RefCell.
> - Use .borrow() and .borrow_mut() carefully to avoid panics.
> - Cloning the Wrapper shares the same underlying value.