#![doc(html_root_url = "https://docs.rs/high_mem_utils/0.1.1/")]
#![feature(vec_leak, untagged_unions)]

/*!
This crate provides high-level memory abstractions used for ensure memory and exception safety in some
patterns.

High-level signifies that it only brings safe abstractions for some cases of transmute and others unsafe
functions in the mem or ptr module,does not provide a custom allocator or garbage collector neither depends
on the [core::alloc] unstable lib.

At the moment this crate is nightly only,this will change if the features [`vec_leak`] and
[`untagged_unions`] get stabilished.

# Examples

```
use high_mem_utils::{CatchStr, DontDrop, DropBy};

let mut string = String::from("Hello world!");
let catch = CatchStr::new(string.clone());

assert_eq!(catch.leaked().to_string(), string); // leaked returns &&mut str,not use to_string 
                                                // is a bit difficult cast rigth now

assert_eq!(catch.seal(), string); // catch consumed
let mut a = [1, 2, 3];

{
    let elem = DropBy::new([2, 3, 4], |e| { a = e.clone(); });

    assert_eq!(*elem, [2, 3, 4]);
}
    
assert_eq!(a, [2, 3, 4]);

unsafe { 
    let b = DontDrop([1, 2, 3]); // we're not dropping here because we will have two variables 
                                 // pointing to the same memory and "b" lives for shorter
    a = [0; 3];
    b.as_ptr().copy_to(a.as_mut_ptr(), 3);
}

assert_eq!(a, [1, 2, 3]);
```

[`vec_leak`]: https://github.com/rust-lang/rust/issues/62195
[`untagged_unions`]: https://github.com/rust-lang/rust/issues/32836
[core::alloc]: https://doc.rust-lang.org/core/alloc/index.html
*/

use std::mem::{self, ManuallyDrop};
use std::ops::{Deref, DerefMut};

/// An union type that can be leaked or sealed(owned),useful when you want to give temporal global access to a particular value.
pub union Catch<'a, T> {
    leaked: &'a mut T,
    sealed: ManuallyDrop<Box<T>>,
}

impl<'a, T> Catch<'a, T> {
    /// Creates a new Catch with a leak, you can lately get the underlying value and consume the Catch
    /// with the [`seal`](#method.seal) method.
    pub fn new(a: Box<T>) -> Self {
        Catch {
            leaked: Box::leak(a),
        }
    }

    /// Returns a a reference to the leaked field,'cause the only ways for construct this union returns
    /// a leaked one,for warranty never transmute stack to heap data,this method does not use transmute
    /// implicitly. 
    pub fn leaked(&self) -> &&'a mut T {
        unsafe { &self.leaked }
    }

    /// Consumes the Catch and gets the inner Box\<T\>,preventing the memory leak.
    /// 
    /// This does a call to transmute but,as the only ways to construct this union gives you a leaked one
    /// this never trigger undefined behavior by itself.
    pub fn seal(self) -> Box<T> {
        unsafe { ManuallyDrop::into_inner(self.sealed) }
    }

    /// Consumes the Catch and returns a mutable reference pointing to leaked data.
    pub fn leak(self) -> &'a mut T {
        unsafe { self.leaked }
    } 

    /// Creates a new Catch from a mutable reference to T,without checking if T is in the heap.
    /// 
    /// # Safety
    /// 
    /// This function should only be used with data returned by leak from a safely construct Catch or with
    /// data returned by Box::leak otherwise will trigger undefined behavior if seal is called.
    pub unsafe fn from_leaked(leaked: &'a mut T) -> Self {
        Catch { leaked }
    }
}

/// An union slice that can be leaked or sealed(owned),useful when you want to give temporal global access
/// to a particular sequence.
pub union CatchSeq<'a, T> {
    leaked: &'a mut [T],
    sealed: ManuallyDrop<Box<[T]>>,
}

impl<'a, T> CatchSeq<'a, T> {
    /// Creates a new CatchSeq with a leak, you can lately get the underlying sequence and consume the CatchSeq
    /// with the [`seal`](#method.seal) method.
    pub fn new(a: Vec<T>) -> Self {
        CatchSeq {
            leaked: Vec::leak(a),
        }
    }

    /// Returns a a reference to the leaked field,as the only safe ways for construct this union returns a leaked
    /// one,for warranty never transmute stack to heap data,this method does not use transmute implicitly. 
    pub fn leaked(&self) -> &&'a mut [T] {
        unsafe { &self.leaked }
    }

    /// Consumes the Catch and gets the inner Vec<T>, preventing the memory leak.
    /// 
    /// This does a call to transmute but,as the only safe ways for construct this union returns a leaked
    /// one,this never trigger undefined behavior by itself.
    pub fn seal(self) -> Vec<T> {
        unsafe { ManuallyDrop::into_inner(self.sealed).into_vec() }
    }

    /// Consumes the CatchSeq and returns a mutable reference pointing to leaked data.
    pub fn leak(self) -> &'a mut [T] {
        unsafe { self.leaked }
    } 

    /// Creates a new CatchSeq from a `&mut [T]`,without checking if the referent is in the heap.
    /// 
    /// # Safety
    /// 
    /// This function should only be used with data returned by leak from a safely constructed CatchSeq or
    /// with data returned by Vec::leak otherwise this will trigger undefined behavior if[`seal`](#method.seal)
    /// is called.
    pub unsafe fn from_leaked(leaked: &'a mut [T]) -> Self {
        CatchSeq { leaked }
    }
}

/// An union string that can be leaked or sealed(owned),useful when you want to give temporal global access
/// to a particular string.
pub union CatchStr<'a> {
    leaked: &'a mut str,
    sealed: ManuallyDrop<Box<str>>,
}

impl<'a> CatchStr<'a> {
    /// Creates a new CatchStr with a leak, you can lately get the underlying string and consume the CatchStr
    /// with the [`seal`](#method.seal) method.
    pub fn new(a: String) -> Self {
        CatchStr {
            leaked: Box::leak(a.into_boxed_str()),
        }
    }

    /// Returns a a reference to the leaked field,as the only safe ways for construct this union returns a leaked
    /// one,for warranty never transmute stack to heap data,this method does not use transmute implicitly. 
    pub fn leaked(&self) -> &&'a mut str {
        unsafe { &self.leaked }
    }

    /// Consumes the Catch and gets the inner String, preventing the memory leak.
    /// 
    /// This does a call to transmute but,as the only safe ways for construct this union return a leaked
    /// one,this never trigger undefined behavior by itself.
    pub fn seal(self) -> String {
        unsafe { ManuallyDrop::into_inner(self.sealed).into_string() }
    }

    /// Consumes the CatchStr and returns a mutable reference pointing to leaked data.
    pub fn leak(self) -> &'a mut str {
        unsafe { self.leaked }
    } 

    /// Creates a new CatchStr from a `&mut str`,without checking if the referent is in the heap.
    /// 
    /// # Safety
    /// 
    /// This function should only be used with data returned by leak from a safely constructed CatchStr or
    /// with data returned by `Box::leak(s.into_boxed_str())` otherwise this will trigger undefined behavior
    /// if [`seal`](#method.seal) is called.
    pub unsafe fn from_leaked(leaked: &'a mut str) -> Self {
        CatchStr { leaked }
    }
}

/// A wrapper for an implementation of drop that [`mem::take`] the value and [`mem::forget`]s it.
/// 
/// This might be useful if you want assuring that a particular destructor not run if it can lead to
/// a double-free or another memory issue.
/// 
/// This type is particularly not recomended for reference types because as such they can never be null
/// and the value is still dropped. Neither on types with a costly initialization because it replaces the
/// forgotten value with the `Default` one,these values should not implement it anyways.
/// 
/// This type has the same implications that forget except for the fact that this ensures that the value
/// is never dropped even on panic,unless you abort.In general [`DontDropOpt`](./struct.DontDropOpt.html) is preferred.
/// 
/// It derefs to T.
/// 
/// [`mem::take`]: https://doc.rust-lang.org/core/mem/fn.take.html
pub struct DontDrop<T: Default>(pub T);

impl<T: Default> Drop for DontDrop<T> {
    fn drop(&mut self) {
        mem::forget(mem::take(&mut self.0));
    }
}

impl<T: Default> Deref for DontDrop<T> {
    type Target = T;
    
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T: Default> DerefMut for DontDrop<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

/// A wrapper for an implementation of drop that [`mem::forget`] the previous value and replace it with None.
/// 
/// This might be useful if you want assuring that a particular destructor not run if it can lead to
/// a double-free or another memory issue.
/// 
/// This type is particularly not recomended for reference types because as such they can never be null
/// and the value is still dropped.
/// 
/// This type has the same implications that [`mem::forget`] except for the fact that this ensures that the
/// value is never dropped even on panic,unless you abort.
/// 
/// It derefs to Option<T>.
pub struct DontDropOpt<T>(Option<T>);

impl<T> DontDropOpt<T> {
    /// Construct a new `DontDropOpt` from a value,this has no effect if the value is a reference.
    pub fn new(a: T) -> Self {
        DontDropOpt(Some(a))
    }
} 

impl<T> Drop for DontDropOpt<T> {
    fn drop(&mut self) {
        mem::forget(&mut self.0.take());
    }
}

impl<T> Deref for DontDropOpt<T> {
    type Target = Option<T>;
    
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T> DerefMut for DontDropOpt<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

/// A wrapper that calls the given closure at Drop. Useful when you have a conditional assign of one
/// that,once assigned,you want to warranty a call to it with the given T,and then drop it.
/// 
/// It derefs to T.
pub struct DropBy<T, F: FnMut(&mut T)> {
    pub value: T,
    pub clos: F
}

impl<T, F: FnMut(&mut T)> DropBy<T, F> {
    pub fn new(value: T, clos: F) -> Self {
        DropBy {value, clos}
    }
}

impl<T, F: FnMut(&mut T)> Drop for DropBy<T, F> {
    fn drop(&mut self) {
        (self.clos)(&mut self.value)
    }
}

impl<T, F: FnMut(&mut T)> Deref for DropBy<T, F> {
    type Target = T;
    
    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

impl<T, F: FnMut(&mut T)> DerefMut for DropBy<T, F> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.value
    }
}