Skip to content

Conversation

@WalterSmuts
Copy link
Contributor

Again would require a major version bump. Just adding here as reminder until that happens.

Commit 1:

    Return a boxed slice instead of vector from make_*

    The number of elements of a vector can be changed after returned while a
    boxed slice cannot. This is safer and more clearly communicates the
    intention of the function to the user while taking up less space on the
    stack.

    This change renames make_*_vec to make_*_buffer and returns a boxed
    slice instead of a vector.

Commit 2:

    Update documentation wording of vector to buffer

    Since vector has a specific meaning in Rust I think it's less confusing
    to use buffer in the documentation instead.

The number of elements of a vector can be changed after returned while a
boxed slice cannot. This is safer and more clearly communicates the
intention of the function to the user while taking up less space on the
stack.

This change renames make_*_vec to make_*_buffer and returns a boxed
slice instead of a vector.
@HEnquist
Copy link
Owner

The first commit makes perfect sense. Didn't think of that, thanks!

The second one needs a little more work. The word "vector" is referring both to the mathematical concept of vectors, and the name of the data structure storing it. They just conveniently happen to be the same. At least for me "buffer" intuitively means a pile of some data, while "vector" is a coordinate in an N-dimensional space.
It's not easy to write something that is both short and clear..
One first attempt:

    /// Transform a real-valued vector of length N, producing an N/2+1 (with N/2 rounded down) element long complex output vector.
    /// Input and output vectors are stored in buffers of type `&mut [T]` and `&mut [Complex<T>]` respectively.
    /// The input buffer is used as scratch space, so the contents of input should be considered garbage after calling.
    /// It also allocates additional scratch space as needed.
    /// An error is returned if any of the given buffers has the wrong length.
    fn process(&self, input: &mut [T], output: &mut [Complex<T>]) -> Res<()>;

@WalterSmuts
Copy link
Contributor Author

Suggestion to use "buffer" when talking about rust data types and "signal" when talking about the mathematical concept?

Since vector has a specific meaning in Rust it's less confusing to use
signal in the documentation instead. Buffer is used when talking about
the extra space required to do the operation.
@WalterSmuts WalterSmuts force-pushed the vector-to-constant-buffers branch from 91563f0 to 95350e9 Compare October 15, 2022 12:33
@WalterSmuts
Copy link
Contributor Author

I've updated the wording to use "signal" and "buffer" where appropriate.

@HEnquist HEnquist added enhancement New feature or request next major version Breaking change that should wait for the next major version bump labels Nov 9, 2022
@HEnquist
Copy link
Owner

I did a quite large rewrite of the documentation in #38
I used the word "signal" for the real data, and "spectrum" for the complex. I also tried to use "buffer" or "slice" for the data structures, depending on what made the most sense in the context.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request next major version Breaking change that should wait for the next major version bump

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants