Struct SubmatrixRaw 

pub struct SubmatrixRaw<V, T>
where
    V: AsPointerToSlice<T>,
{ /* private fields */ }

Available on crate feature unstable-enable only.

A submatrix that works on raw pointers, thus does not care about mutability and borrowing. It already takes care about bounds checking and indexing. Nevertheless, it is quite difficult to use this correctly, best not use it at all. I mainly made it public to allow doctests.

More concretely, when having a 2d-structure, given by a sequence of Vs, we can consider a rectangular sub-block. This is encapsulated by SubmatrixRaw.

Safety

The individual safety contracts are described at the corresponding functions. However, in total be careful when actuall transforming the entry pointers (given by SubmatrixRaw::entry_at or SubmatrixRaw::row_at) into references. Since SubmatrixRaw does not borrow-check (and is Copy!), it is easy to create aliasing pointers, that must not be converted into references.

Example of illegal use

let mut data = [1, 2, 3];
// this is actuall safe and intended use
let mut matrix = unsafe { SubmatrixRaw::<AsFirstElement<i64>, i64>::new(std::mem::transmute(NonNull::new(data.as_mut_ptr()).unwrap()), 1, 3, 0, 3) };
// this is safe, but note that ptr1 and ptr2 alias...
let mut ptr1: NonNull<i64> = matrix.entry_at(0, 0);
let mut ptr2: NonNull<i64> = matrix.entry_at(0, 0);
// this is UB now!
let (ref1, ref2) = unsafe { (ptr1.as_mut(), ptr2.as_mut()) };

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Implementations

impl<V, T> SubmatrixRaw<V, T>

where V: AsPointerToSlice<T>,

pub unsafe fn new( rows: NonNull<V>, row_count: usize, row_step: isize, cols_start: usize, col_count: usize, ) -> Self

Create a new SubmatrixRaw object.

Safety

We require that each pointer rows.offset(row_step * i) for 0 <= i < row_count points to a valid object and can be dereferenced. Furthermore, if ptr is the pointer returned by [AsPointerToSlice::get_pointer()], then ptr.offset(i + cols_start) must point to a valid T for 0 <= i < col_count.

Furthermore, we require any two of these (for different i) to represent disjunct “slices”, i.e. if they give pointers ptr1 and ptr2 (via AsPointerToSlice::get_pointer()), then ptr1.offset(cols_start + k) and ptr2.offset(cols_start + l) for 0 <= k, l < col_count never alias.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn restrict_rows(self, rows: Range<usize>) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn restrict_cols(self, cols: Range<usize>) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn row_at(&self, row: usize) -> NonNull<[T]>

Returns a pointer to the row-th row of the matrix. Be carefull about aliasing when making this into a reference!

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn entry_at(&self, row: usize, col: usize) -> NonNull<T>

Returns a pointer to the (row, col)-th entry of the matrix. Be carefull about aliasing when making this into a reference!

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<V, T> Clone for SubmatrixRaw<V, T>

where V: AsPointerToSlice<T>,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V, T> Copy for SubmatrixRaw<V, T>

where V: AsPointerToSlice<T>,

impl<V, T> Send for SubmatrixRaw<V, T>

where V: AsPointerToSlice<T> + Sync, T: Sync,

Requiring T: Sync is the more conservative choice. If SubmatrixRaw acts as a mutable reference, we would only require T: Send, but we also want SubmatrixRaw to be usable as an immutable reference, thus it can be shared between threads, which requires T: Sync.

impl<V, T> Sync for SubmatrixRaw<V, T>

where V: AsPointerToSlice<T> + Sync, T: Sync,