box_raw_ptr 2.0.2

A Rust library providing safe wrappers for working with raw pointer. These raw pointers are `*const T` and `*mut T`. These wrappers ensure memory safety by encapsulating the raw pointers in safe abstractions and providing safe methods for working with them.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# box_raw_ptr


box_raw_ptr is a Rust library providing safe abstractions for working with raw pointers (`*const T` and `*mut T`). It ensures proper alignment, bounds checking, and safe memory operations, inspired by Rust's safety principles while allowing interoperability with C-style memory management.

## Features


- **Type Safety**: Wrappers (`ConstRawPtr` and `MutRawPtr`) ensure safe usage of raw pointers (`*const T` and `*mut T`).

- **Bounds Checking**: Methods to check and adjust offsets within allocated memory.

- **Alignment Guarantees**: Ensures pointers are aligned according to `T`.

- **Memory Management**: Includes methods for deallocating memory and safely handling null pointers.

- **Interoperability**: Facilitates safe interaction with memory allocated by C functions or Rust's allocator.

## Components


- **ConstRawPtr**: Provides safe operations on `*const T` pointers, including bounds checking and memory release.

- **MutRawPtr**: Offers safe operations on `*mut T` pointers, supporting mutable access and memory management.

## Usage


```rust
use box_raw_ptr::{const_raw_ptr::ConstRawPtr, mut_raw_ptr::MutRawPtr};

fn main() {
    // Example: Import C pointer and write to the allocated data
    #[link(name = "example", kind = "static")]
    extern "C" {
        fn c_ptr() -> *mut std::ffi::c_int;
    }

    let ptr: *mut i32 = unsafe { c_ptr() };

    let safeptr = MutRawPtr::new(ptr, 1, 1);

    safeptr.write_ptr(14).unwrap();

    assert_eq!(safeptr.unwrap().unwrap(), 14)

    // Example: Create a ConstRawPtr to safely handle a raw const pointer
    // Allocate properly aligned memory for an i32
    let alloc: *const i32 = unsafe { 
    std::alloc::alloc(std::alloc::Layout::from_size_align(20, 4).unwrap()) as *const i32 
    };
    let mut ptr: ConstRawPtr<i32> = ConstRawPtr::new(alloc, 5, 1);

    ptr.change_offset(4).unwrap();

    println!("{} : {}", ptr.unwrap().unwrap(), ptr.memory_address());

    // Example: Allocate data using c_malloc
    let alloc: *const i32 = ConstRawPtr::c_malloc(1).unwrap();
    let _: ConstRawPtr<i32> = ConstRawPtr::new(t, 1, 1);
}
```

## Safety Considerations


- **Unsafe Contexts**: Use of raw pointers inherently involves unsafe operations.

- **Memory Safety**: Ensure proper initialization and alignment of pointers.

- **Dropping Pointers**: Manually dropping pointers can lead to undefined behavior if used afterward.

## Installation


Add the following to your `Cargo.toml`:

```toml

[dependencies]

box_raw_ptr = "2.0.2"

```

## Documentation


For detailed API documentation, refer to [docs.rs](https://docs.rs/box_raw_ptr/latest/box_raw_ptr/).

## License


MIT License

Copyright (c) [2024] [Rocco Zinedine Samuel Jenson]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.