M-Labs/nalgebra
3
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix missing docs.

Browse Source
This commit is contained in:
Sébastien Crozet 2021-08-03 17:26:56 +02:00
parent d609a2f174
commit eedb860565
9 changed files with 59 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -4,7 +4,7 @@ documented here.
This project adheres to [Semantic Versioning](https://semver.org/).
## [0.29.0]
## [0.29.0] - WIP
### Modified
- The closure given to `apply`, `zip_apply`, `zip_zip_apply` must now modify the
first argument inplace, instead of returning a new value. This makes these

9
src/base/array_storage.rs
View File

@ -22,7 +22,7 @@ use crate::base::dimension::{Const, ToTypenum};
use crate::base::storage::{IsContiguous, Owned, RawStorage, RawStorageMut, ReshapableStorage};
use crate::base::Scalar;
use crate::Storage;
use std::mem::{self, MaybeUninit};
use std::mem;
/*
*
@ -35,12 +35,14 @@ use std::mem::{self, MaybeUninit};
pub struct ArrayStorage<T, const R: usize, const C: usize>(pub [[T; R]; C]);
impl<T, const R: usize, const C: usize> ArrayStorage<T, R, C> {
/// Converts this array storage to a slice.
#[inline]
pub fn as_slice(&self) -> &[T] {
// SAFETY: this is OK because ArrayStorage is contiguous.
unsafe { self.as_slice_unchecked() }
}
/// Converts this array storage to a mutable slice.
#[inline]
pub fn as_mut_slice(&mut self) -> &mut [T] {
// SAFETY: this is OK because ArrayStorage is contiguous.
@ -237,14 +239,15 @@ where
where
V: SeqAccess<'a>,
{
let mut out: ArrayStorage<MaybeUninit<T>, R, C> =
let mut out: ArrayStorage<core::mem::MaybeUninit<T>, R, C> =
DefaultAllocator::allocate_uninit(Const::<R>, Const::<C>);
let mut curr = 0;
while let Some(value) = visitor.next_element()? {
*out.as_mut_slice()
.get_mut(curr)
.ok_or_else(|| V::Error::invalid_length(curr, &self))? = MaybeUninit::new(value);
.ok_or_else(|| V::Error::invalid_length(curr, &self))? =
core::mem::MaybeUninit::new(value);
curr += 1;
}

54
src/base/blas_uninit.rs
View File

@ -73,19 +73,12 @@ fn array_axc<Status, T>(
}
}
/// Computes `self = a * x * c + b * self`.
/// Computes `y = a * x * c + b * y`.
///
/// If `b` is zero, `self` is never read from.
/// If `b` is zero, `y` is never read from and may be uninitialized.
///
/// # Examples:
///
/// ```
/// # use nalgebra::Vector3;
/// let mut vec1 = Vector3::new(1.0, 2.0, 3.0);
/// let vec2 = Vector3::new(0.1, 0.2, 0.3);
/// vec1.axcpy(5.0, &vec2, 2.0, 5.0);
/// assert_eq!(vec1, Vector3::new(6.0, 12.0, 18.0));
/// ```
/// # Safety
/// This is UB if `Status == Uninit && b != 0`.
#[inline]
#[allow(clippy::many_single_char_names)]
pub unsafe fn axcpy_uninit<Status, T, D1: Dim, D2: Dim, SA, SB>(
@ -119,22 +112,13 @@ pub unsafe fn axcpy_uninit<Status, T, D1: Dim, D2: Dim, SA, SB>(
}
}
/// Computes `self = alpha * a * x + beta * self`, where `a` is a matrix, `x` a vector, and
/// Computes `y = alpha * a * x + beta * y`, where `a` is a matrix, `x` a vector, and
/// `alpha, beta` two scalars.
///
/// If `beta` is zero, `self` is never read.
/// If `beta` is zero, `y` is never read from and may be uninitialized.
///
/// # Examples:
///
/// ```
/// # use nalgebra::{Matrix2, Vector2};
/// let mut vec1 = Vector2::new(1.0, 2.0);
/// let vec2 = Vector2::new(0.1, 0.2);
/// let mat = Matrix2::new(1.0, 2.0,
/// 3.0, 4.0);
/// vec1.gemv(10.0, &mat, &vec2, 5.0);
/// assert_eq!(vec1, Vector2::new(10.0, 21.0));
/// ```
/// # Safety
/// This is UB if `Status == Uninit && beta != 0`.
#[inline]
pub unsafe fn gemv_uninit<Status, T, D1: Dim, R2: Dim, C2: Dim, D3: Dim, SA, SB, SC>(
status: Status,
@ -193,27 +177,13 @@ pub unsafe fn gemv_uninit<Status, T, D1: Dim, R2: Dim, C2: Dim, D3: Dim, SA, SB,
}
}
/// Computes `self = alpha * a * b + beta * self`, where `a, b, self` are matrices.
/// Computes `y = alpha * a * b + beta * y`, where `a, b, y` are matrices.
/// `alpha` and `beta` are scalar.
///
/// If `beta` is zero, `self` is never read.
/// If `beta` is zero, `y` is never read from and may be uninitialized.
///
/// # Examples:
///
/// ```
/// # #[macro_use] extern crate approx;
/// # use nalgebra::{Matrix2x3, Matrix3x4, Matrix2x4};
/// let mut mat1 = Matrix2x4::identity();
/// let mat2 = Matrix2x3::new(1.0, 2.0, 3.0,
/// 4.0, 5.0, 6.0);
/// let mat3 = Matrix3x4::new(0.1, 0.2, 0.3, 0.4,
/// 0.5, 0.6, 0.7, 0.8,
/// 0.9, 1.0, 1.1, 1.2);
/// let expected = mat2 * mat3 * 10.0 + mat1 * 5.0;
///
/// mat1.gemm(10.0, &mat2, &mat3, 5.0);
/// assert_relative_eq!(mat1, expected);
/// ```
/// # Safety
/// This is UB if `Status == Uninit && beta != 0`.
#[inline]
pub unsafe fn gemm_uninit<
Status,

1
src/base/construction.rs
View File

@ -31,6 +31,7 @@ impl<T: Scalar, R: Dim, C: Dim> UninitMatrix<T, R, C>
where
DefaultAllocator: Allocator<T, R, C>,
{
/// Builds a matrix with uninitialized elements of type `MaybeUninit<T>`.
pub fn uninit(nrows: R, ncols: C) -> Self {
// SAFETY: this is OK because the dimension automatically match the storage
// because we are building an owned storage.

1
src/base/matrix.rs
View File

@ -451,6 +451,7 @@ impl<T, R: Dim, C: Dim, S: RawStorage<T, R, C>> Matrix<T, R, C, S> {
(nrows.value(), ncols.value())
}
/// The shape of this matrix wrapped into their representative types (`Const` or `Dynamic`).
#[inline]
#[must_use]
pub fn shape_generic(&self) -> (R, C) {

1
src/base/mod.rs
View File

@ -38,6 +38,7 @@ mod blas_uninit;
pub mod helper;
mod interpolation;
mod min_max;
/// Mechanisms for working with values that may not be initialized.
pub mod uninit;
pub use self::matrix::*;

9
src/base/storage.rs
View File

@ -32,6 +32,9 @@ pub type CStride<T, R, C = U1> =
/// The trait shared by all matrix data storage.
///
/// TODO: doc
/// In generic code, it is recommended use the `Storage` trait bound instead. The `RawStorage`
/// trait bound is generally used by code that needs to work with storages that contains
/// `MaybeUninit<T>` elements.
///
/// Note that `Self` must always have a number of elements compatible with the matrix length (given
/// by `R` and `C` if they are known at compile-time). For example, implementors of this trait
@ -125,6 +128,7 @@ pub unsafe trait RawStorage<T, R: Dim, C: Dim = U1>: Sized {
unsafe fn as_slice_unchecked(&self) -> &[T];
}
/// Trait shared by all matrix data storage that don’t contain any uninitialized elements.
pub unsafe trait Storage<T, R: Dim, C: Dim = U1>: RawStorage<T, R, C> {
/// Builds a matrix data storage that does not contain any reference.
fn into_owned(self) -> Owned<T, R, C>
@ -139,6 +143,10 @@ pub unsafe trait Storage<T, R: Dim, C: Dim = U1>: RawStorage<T, R, C> {
/// Trait implemented by matrix data storage that can provide a mutable access to its elements.
///
/// In generic code, it is recommended use the `StorageMut` trait bound instead. The
/// `RawStorageMut` trait bound is generally used by code that needs to work with storages that
/// contains `MaybeUninit<T>` elements.
///
/// Note that a mutable access does not mean that the matrix owns its data. For example, a mutable
/// matrix slice can provide mutable access to its elements even if it does not own its data (it
/// contains only an internal reference to them).
@ -217,6 +225,7 @@ pub unsafe trait RawStorageMut<T, R: Dim, C: Dim = U1>: RawStorage<T, R, C> {
unsafe fn as_mut_slice_unchecked(&mut self) -> &mut [T];
}
/// Trait shared by all mutable matrix data storage that don’t contain any uninitialized elements.
pub unsafe trait StorageMut<T, R: Dim, C: Dim = U1>:
Storage<T, R, C> + RawStorageMut<T, R, C>
{

29
src/base/uninit.rs
View File

@ -1,19 +1,44 @@
use std::mem::MaybeUninit;
// # Safety
// This trait must not be implemented outside of this crate.
/// This trait is used to write code that may work on matrices that may or may not
/// be initialized.
///
/// This trait is used to describe how a value must be accessed to initialize it or
/// to retrieve a reference or mutable reference. Typically, a function accepting
/// both initialized and uninitialized inputs should have a `Status: InitStatus<T>`
/// type parameter. Then the methods of the `Status` can be used to access the element.
///
/// # Safety
/// This trait must not be implemented outside of this crate.
pub unsafe trait InitStatus<T>: Copy {
/// The type of the values with the initialization status described by `Self`.
type Value;
/// Initialize the given element.
fn init(out: &mut Self::Value, t: T);
/// Retrieve a reference to the element, assuming that it is initialized.
///
/// # Safety
/// This is unsound if the referenced value isn’t initialized.
unsafe fn assume_init_ref(t: &Self::Value) -> &T;
/// Retrieve a mutable reference to the element, assuming that it is initialized.
///
/// # Safety
/// This is unsound if the referenced value isn’t initialized.
unsafe fn assume_init_mut(t: &mut Self::Value) -> &mut T;
}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
/// A type implementing `InitStatus` indicating that the value is completely initialized.
pub struct Init;
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
/// A type implementing `InitStatus` indicating that the value is completely unitialized.
pub struct Uninit;
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
/// A type implementing `InitStatus` indicating that the value is initialized even if the value
/// has the type `MaybeUninit` (i.e. when `Status == Uninit`).
pub struct Initialized<Status>(pub Status);
unsafe impl<T> InitStatus<T> for Init {

2
src/lib.rs
View File

@ -73,6 +73,7 @@ an optimized set of tools for computer graphics and physics. Those features incl
#![allow(unused_variables, unused_mut)]
#![deny(
missing_docs,
nonstandard_style,
unused_parens,
unused_qualifications,
@ -82,7 +83,6 @@ an optimized set of tools for computer graphics and physics. Those features incl
future_incompatible,
missing_copy_implementations
)]
// #![deny(missing_docs)] // XXX: deny that
#![doc(
html_favicon_url = "https://nalgebra.org/img/favicon.ico",
html_root_url = "https://docs.rs/nalgebra/0.25.0"