Crate box_raw_ptr 

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. NOTE: It is still the user’s responcibilty to correctly handle input of length and offset.

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

use box_raw_ptr::mut_raw_ptr::MutRawPtr; // Import MutRawPtr from box_raw_ptr

#[link(name = "example", kind = "static")] // Link to a static library "example"
extern "C" { // Declare C functions
    fn c_ptr() -> *mut Data; // Declare C function returning a pointer to Data
    fn c_ptr2() -> *mut std::ffi::c_int; // Declare C function returning a pointer to std::ffi::c_int
}

#[repr(C)] // Make Data a C-compatible struct
#[derive(Clone, Copy)] // Derive Copy and Clone traits for Data
struct Data { // Define a struct to represent data
    a: i32, // Field of type i32
    b: f64, // Field of type f64
}

fn main() { // Main function starts here
    // Example: Import C pointer and write to the allocated data
    let mut safeptr: MutRawPtr<Data> = MutRawPtr::new(unsafe { c_ptr() }, /*# of Data Blocks*/ 1, /*offset*/ 0); // Create MutRawPtr with the C pointer

    assert_eq!(16, safeptr.size_of()); // Assert the size of Data is 16 bytes

    safeptr.write_ptr(Data {a: 100, b: 12.0}); // Write to the memory pointed by safeptr

    assert_eq!(100, (safeptr.access().unwrap()).a); // Assert the written value

    // Example: Iteratively Rewrite Values in a Block Of Data (Assuming 5 Blocks of i32)
    let mut safeptr: MutRawPtr<_> = MutRawPtr::new( unsafe { c_ptr2() }, 5, 0); // Create MutRawPtr with another C pointer

    for i in 0..=4 { // Iterate 5 times
                      /* change_offset() is byte indexed */
        safeptr.change_offset(i * std::mem::size_of::<i32>()).unwrap();
        safeptr.write_ptr(100 as i32).unwrap(); // Write a value (100) to the current memory location
        println!("{}", safeptr.access().unwrap()); // Print the value at the current offset
    }
}

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:

[dependencies]
box_raw_ptr = "2.2.0"

Documentation

For detailed API documentation, refer to docs.rs.

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.

Modules

const_raw_ptr

mut_raw_ptr