Skip to content

Commit

Permalink
improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@daniellga
daniellga committed Jun 21, 2024
1 parent ab1e756 commit 104a351
Show file tree
Hide file tree
Showing 15 changed files with 862 additions and 563 deletions.
6 changes: 6 additions & 0 deletions harmonium-core/src/array.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ where
self.0.is_empty()
}

/// Returns true if the array data is laid out in contiguous “C order” in memory (where the last index is the most rapidly varying).
/// Returns false otherwise, i.e. the array is possibly not contiguous in memory, it has custom strides, etc.
pub fn is_standard_layout(&self) -> bool {
self.0.is_standard_layout()
}

/// Gets the underlying slice. Returns `None` if not contiguous.
pub fn as_slice(&self) -> Option<&[T]> {
self.0.as_slice()
Expand Down
114 changes: 64 additions & 50 deletions r-harmonium/src/rust/src/harray.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ use savvy::{
use std::sync::Arc;

/// HArray
/// An array representation. \
/// An array representation.
///
/// # Methods
///
Expand All @@ -23,21 +23,25 @@ impl HArray {
/// HArray
/// ## new_from_values
///
/// `new_from_values(arr: array, dtype: HDataType) -> HArray` \
/// `new_from_values(arr: array, dtype: HDataType) -> HArray`
///
/// Creates a new `HArray` from an R array. \
/// Creates a new `HArray` from an R array.
///
/// #### Arguments
///
/// * `arr` \
/// - `arr`
///
/// A `double` or `complex` array.
/// * `dtype` \
/// An `HDataType` to indicate which type of `HArray` to be created. \
///
/// - `dtype`
///
/// An `HDataType` to indicate which type of `HArray` to be created.
///
/// For float dtypes, the atomic vector must be a `double`. For complex dtypes, a `complex` atomic vector.
///
/// #### Returns
///
/// An `HArray`. \
/// An `HArray`.
///
/// #### Examples
///
Expand Down Expand Up @@ -98,13 +102,13 @@ impl HArray {
/// HArray
/// ## len
///
/// `len() -> integer` \
/// `len() -> integer`
///
/// Returns the number of elements of this `Harray`. \
/// Returns the number of elements of this `Harray`.
///
/// #### Returns
///
/// An `integer`. \
/// An integer.
///
/// #### Examples
///
Expand All @@ -126,13 +130,13 @@ impl HArray {
/// HArray
/// ## shape
///
/// `shape() -> integers` \
/// `shape() -> integeratomicvector`
///
/// Returns the shape of this `HArray`. \
/// Returns the shape of this `HArray`.
///
/// #### Returns
///
/// A vector of integers. \
/// An integer atomic vector.
///
/// #### Examples
///
Expand Down Expand Up @@ -160,13 +164,13 @@ impl HArray {
/// HArray
/// ## ndim
///
/// `ndim() -> integer` \
/// `ndim() -> integer`
///
/// Returns the number of dimensions of this `HArray`. \
/// Returns the number of dimensions of this `HArray`.
///
/// #### Returns
///
/// An integer. \
/// An integer.
///
/// #### Examples
///
Expand All @@ -188,23 +192,26 @@ impl HArray {
/// HArray
/// ## slice
///
/// `slice(range: list[atomicvector]) -> HArray` \
/// `slice(range: list[atomicvector]) -> HArray`
///
/// Slices the HArray.
///
/// Slices the HArray. \
/// This operation has a COW ([clone-on-write](https://doc.rust-lang.org/std/borrow/enum.Cow.html)) behaviour. The created slice shares the inner data with
/// the original array until one of them is modified. \
/// the original array until one of them is modified.
///
/// #### Arguments
///
/// * `range` \
/// - `range`
///
/// A list of vectors of integers.
/// The number of vectors in the list must be equal to the number of dimensions in the original HArray as they represent the slice information for each axis. \
/// Each vector must be composed of 3 elements: [start, end, step]. All 3 values can be
/// positive or negative, although step can't be 0. \
///
/// The number of vectors in the list must be equal to the number of dimensions in the original HArray as they represent the slice information for each axis.
///
/// Each vector must be composed of 3 elements: [start, end, step]. All 3 values can be positive or negative, although step can't be 0.
///
/// #### Returns
///
/// An `HArray`. \
/// An `HArray`.
///
/// #### Examples
///
Expand Down Expand Up @@ -256,10 +263,11 @@ impl HArray {
/// HArray
/// ## print
///
/// `print()` \
/// `print()`
///
/// Prints the `HArray`.
///
/// Prints the `HArray`. \
/// Differently from R's normal behaviour, `print` doesn't return the value invisibly. \
/// Differently from R's normal behaviour, `print` doesn't return the value invisibly.
///
/// #### Examples
///
Expand All @@ -284,20 +292,22 @@ impl HArray {
/// HArray
/// ## eq
///
/// `eq(other: HArray) -> bool` \
/// `eq(other: HArray) -> bool`
///
/// Equality with another `HArray`.
///
/// Equality with another `HArray`. \
/// The comparison only checks if the dtype and the values are the same. To compare if the
/// underlying data is the same in memory, check `mem_adress`. \
/// underlying data is the same in memory, check `mem_adress`.
///
/// #### Arguments
///
/// * `other` \
/// An `HArray`. \
/// - `other`
///
/// An `HArray`.
///
/// #### Returns
///
/// A `bool`. \
/// A `bool`.
///
/// #### Examples
///
Expand Down Expand Up @@ -328,15 +338,17 @@ impl HArray {
/// HArray
/// ## ne
///
/// `ne(other: HArray) -> bool` \
/// `ne(other: HArray) -> bool`
///
/// Difference with another `HArray`.
///
/// Difference with another `HArray`. \
/// The comparison only checks if the dtype and the values are the same. To compare if the
/// underlying data is the same in memory, check `mem_adress`.
///
/// #### Arguments
///
/// * `other` \
/// - `other`
///
/// An `HArray`.
///
/// #### Returns
Expand Down Expand Up @@ -372,7 +384,7 @@ impl HArray {
/// HArray
/// ## clone
///
/// `clone() -> HArray` \
/// `clone() -> HArray`
///
/// Creates a new `HArray`, with the underlying data pointing to the same place in memory.
///
Expand Down Expand Up @@ -400,7 +412,7 @@ impl HArray {
/// HArray
/// ## collect
///
/// `collect() -> array` \
/// `collect() -> array`
///
/// Creates an R array from an `HArray`. The type of the array created (`double` or `complex`) will depend on the `HArray`'s dtype.
///
Expand All @@ -427,7 +439,7 @@ impl HArray {
/// HArray
/// ## dtype
///
/// `dtype() -> HDataType` \
/// `dtype() -> HDataType`
///
/// Gets the `HArray`'s dtype as an `HDataType`.
///
Expand All @@ -454,15 +466,16 @@ impl HArray {
/// HArray
/// ## is_shared
///
/// `is_shared() -> bool` \
/// `is_shared() -> bool`
///
/// Checks if the object is shared.
///
/// Checks if the object is shared. \
/// Since `HArray` has a COW ([clone-on-write](https://doc.rust-lang.org/std/borrow/enum.Cow.html)) behaviour, this function is useful to check if a new
/// object will be created or if the change will be done in-place. \
/// object will be created or if the change will be done in-place.
///
/// #### Returns
///
/// A `bool`. \
/// A `bool`.
///
/// #### Examples
///
Expand All @@ -488,14 +501,15 @@ impl HArray {
/// HArray
/// ## mem_adress
///
/// `mem_adress() -> string` \
/// `mem_adress() -> string`
///
/// The memory adress of the first element of the inner array.
///
/// The memory adress of the first element of the inner array. \
/// This is useful to check if different objects share the same underlying data. \
/// This is useful to check if different objects share the same underlying data.
///
/// #### Returns
///
/// A `string`. \
/// A `string`.
///
/// #### Examples
///
Expand All @@ -517,10 +531,10 @@ impl HArray {
/// HArray
/// ## invalidate
///
/// `invalidate()` \
/// `invalidate()`
///
/// Replaces the inner value of the external pointer, invalidating it. \
/// This function is useful to remove one of the shared references of the inner pointer in rust. \
/// Replaces the inner value of the external pointer, invalidating it.
/// This function is useful to remove one of the shared references of the inner pointer in rust.
///
/// #### Examples
///
Expand Down
60 changes: 36 additions & 24 deletions r-harmonium/src/rust/src/haudioop.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ use crate::{
use savvy::{savvy, Sexp};

/// HAudioOp
/// A collection of methods that can be applied to float 1D or 2D `HArray`s which represents audio data. \
/// A collection of methods that can be applied to float 1D or 2D `HArray`s which represents audio data.
///
/// # Methods
///
Expand All @@ -17,14 +17,15 @@ impl HAudioOp {
/// HAudioOp
/// ## nchannels
///
/// `nchannels() -> integer` \
/// `nchannels() -> integer`
///
/// Returns the number of channels. \
/// This is the same as the number of rows of a 1D or 2D HArray. \
/// Returns the number of channels.
///
/// This is the same as the number of rows of a 1D or 2D HArray.
///
/// #### Returns
///
/// An `integer`. \
/// An `integer`.
///
/// #### Examples
///
Expand All @@ -47,15 +48,17 @@ impl HAudioOp {
/// HAudioOp
/// ## nframes
///
/// `nframes() -> integer` \
/// `nframes() -> integer`
///
/// Returns the number of frames.
///
/// This is the same as the number of cols of a 1D or 2D HArray.
///
/// Returns the number of frames. \
/// This is the same as the number of cols of a 1D or 2D HArray. \
/// The number of frames is equivalent to the number of samples divided by the number of channels. \
/// The number of frames is equivalent to the number of samples divided by the number of channels.
///
/// #### Returns
///
/// An `integer`. \
/// An `integer`.
///
/// #### Examples
///
Expand All @@ -78,20 +81,27 @@ impl HAudioOp {
/// HAudioOp
/// ## db_to_amplitude
///
/// `db_to_amplitude(harray: HArray, reference: double)` \
/// `db_to_amplitude(harray: HArray, reference: double)`
///
/// Converts the `HArray` input from dB to amplitude. \
/// $db_to_amplitude(x) = reference * (10.0**(x * 0.1))**power$ \
/// The operation is done in-place. \
/// Converts the `HArray` input from dB to amplitude.
///
/// $db_to_amplitude(x) = reference * (10.0**(x * 0.1))**power$
///
/// The operation is done in-place.
///
/// #### Arguments
///
/// * `harray` \
/// A 1D or 2D float `HArray`. \
/// * `reference` \
/// A double that scales the output. \
/// * `power` \
/// A double. If 1.0, will compute DB to power. If 0.5, will compute DB to amplitude. \
/// - `harray`
///
/// A 1D or 2D float `HArray`.
///
/// - `reference`
///
/// A double that scales the output.
///
/// - `power`
///
/// A double. If 1.0, will compute DB to power. If 0.5, will compute DB to amplitude.
///
/// #### Examples
///
Expand All @@ -115,14 +125,16 @@ impl HAudioOp {
/// HAudioOp
/// ## to_mono
///
/// `to_mono(harray: HArray)` \
/// `to_mono(harray: HArray)`
///
/// Convert to 1 channel by taking the average across channels.
///
/// Convert to 1 channel by taking the average across channels. \
/// The operation is done in-place. A new inner array is created. \
/// The operation is done in-place. A new inner array is created.
///
/// #### Arguments
///
/// * `harray` \
/// - `harray`
///
/// A 2D float `HArray`.
///
/// #### Examples
Expand Down
Loading

0 comments on commit 104a351

Please sign in to comment.